feat: harden CAD showcase skill and delivery pipeline
This commit is contained in:
67
references/web_delivery.md
Normal file
67
references/web_delivery.md
Normal file
@@ -0,0 +1,67 @@
|
||||
# GLB and Web Delivery
|
||||
|
||||
## Contents
|
||||
|
||||
1. Variant contract
|
||||
2. Served viewer
|
||||
3. Offline viewer
|
||||
4. Browser smoke test
|
||||
5. Strict evidence manifest
|
||||
|
||||
## Variant Contract
|
||||
|
||||
Deliver three variants for Web/digital-twin presentation:
|
||||
|
||||
- overview: walls, glazing, roof, columns, beams, slabs;
|
||||
- standard: overview plus railings and doors; use as default;
|
||||
- detail: all extracted categories for review.
|
||||
|
||||
Generate them with `build_showcase_variants.py` or `cad_showcase.py run`. Validate `variants_manifest.json` and every variant spec. Keep `source_file==site` floors intact across variants.
|
||||
|
||||
Both GLB backends consume versioned `building_spec.json`. They must preserve `<floor>__<category>` names and glTF Y-up. `floor.caps` is canonical; exporters must not independently infer different cap groups.
|
||||
|
||||
## Served Viewer
|
||||
|
||||
Use `write_web_showcase.py`, then install local dependencies from the copied exact-version `package.json`. Do not use mainland-unreliable CDNs.
|
||||
|
||||
The official template includes on-demand rendering, ACES/RoomEnvironment lighting, physical glass, shadows, grouped floor/category toggles, overview-to-standard progressive load, in-page variant switching, explode/section controls, presets, tour, bookmarks, URL-hash state, screenshot, inspection, and downloads.
|
||||
|
||||
Require idle `window.__renders` growth of zero after damping stops.
|
||||
|
||||
## Offline Viewer
|
||||
|
||||
Use `write_offline_viewer.py` only for double-click/no-server delivery. It embeds vendored Three r147, pako, and a gzip-compressed GLB. Run `verify_delivery.py --offline-viewer` to decode and verify the embedded payload.
|
||||
|
||||
The offline viewer intentionally follows an older Three API. Keep its vendored library versions/checksums documented when updating them; do not copy modern template code blindly into r147.
|
||||
|
||||
## Browser Smoke Test
|
||||
|
||||
Serve the Web directory locally, then run:
|
||||
|
||||
```bash
|
||||
node scripts/web_smoke_test.mjs \
|
||||
--url http://127.0.0.1:8188 \
|
||||
--out outputs/<project>/browser_smoke_report.json \
|
||||
--screenshots-dir outputs/<project>/browser_smoke
|
||||
```
|
||||
|
||||
Install Playwright/Chromium first when needed. The script checks desktop/mobile control visibility, console/page/request failures, and idle render behavior. Feed the report to final verification with `--browser-report`; use `--require-browser-report` for formal Web delivery.
|
||||
|
||||
## Strict Evidence Manifest
|
||||
|
||||
Run `verify_showcase.py --strict` for spec previews and GLB budgets, then:
|
||||
|
||||
```bash
|
||||
python3 scripts/verify_delivery.py \
|
||||
--source-report outputs/<project>/cad_read_report.json \
|
||||
--spec outputs/<project>/building_spec.json \
|
||||
--variants-manifest outputs/<project>/delivery/variants_manifest.json \
|
||||
--web-dir outputs/<project>/web \
|
||||
--offline-viewer outputs/<project>/viewer.html \
|
||||
--render outputs/<project>/verify_previews.png outputs/<project>/iso.png \
|
||||
--browser-report outputs/<project>/browser_smoke_report.json \
|
||||
--require-browser-report \
|
||||
--evidence-out outputs/<project>/evidence_manifest.json
|
||||
```
|
||||
|
||||
The verifier checks schema versions, GLB headers/mesh structure/naming/budgets, render dimensions/nonblank variance, Web assets/placeholders/features/variants, offline payload, and browser report. Treat overall FAIL as a delivery blocker.
|
||||
Reference in New Issue
Block a user