Files
cad-building-showcase/references/web_delivery.md

79 lines
5.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 backends retain a decoder-free `.raw.glb` for offline embedding. The Trimesh branch then runs `tools/compress.mjs` (weld, dedup, prune, Draco), while the Blender branch performs a second Blender Draco export for each delivered `.glb`. `verify_showcase.py --strict` must see `draco=True` and every delivered variant within the size budget.
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 **uncompressed** GLB. The Trimesh pipeline therefore uses retained `standard.raw.glb`; passing a Draco GLB is a hard error because this offline bundle intentionally has no Draco decoder.
`cad_showcase.py run --offline` automatically opens the result via `file://` in Chromium and writes `offline_browser_smoke_report.json` plus a screenshot. For a manual/custom delivery, run `offline_viewer_smoke.mjs` and pass its report to `verify_delivery.py --offline-browser-report`. Decoding the base64 payload is not proof that GLTFLoader can render it.
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
`cad_showcase.py run --web` performs this gate automatically. For a manual/custom delivery, 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 real 1440×900/390×844 viewport dimensions, desktop/mobile control visibility, console/page/request failures, and idle render behavior. Feed the report to final verification with `--browser-report`. Supplying `--web-dir` makes the report mandatory: no report is `BLOCKED`, never PASS.
The verifier validates the report contract, not just its top-level `status`: all required named checks must exist and be PASS, viewport details must match exactly, and console/page/request arrays must be present and empty. A hand-written `{status: PASS}` report is invalid.
When an execution tool already has a `run_in_background` option, launch `python3 -m http.server ...` as the foreground command of that background process. Do not append shell `&`; the child server can die with the wrapper. Before presenting the viewer, probe the URL and keep that server process alive. Present the formal `web/index.html` URL when Web was requested; `viewer.html` is a separate offline fallback, not a substitute.
## 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 \
--audit outputs/<project>/extraction_audit.json --require-audit \
--scope-manifest work/<project>/scope_manifest.json --require-scope-manifest \
--variants-manifest outputs/<project>/delivery/variants_manifest.json \
--web-dir outputs/<project>/web \
--offline-viewer outputs/<project>/viewer.html \
--offline-browser-report outputs/<project>/offline_browser_smoke_report.json \
--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, audit gates, scope artifacts, GLB headers/mesh structure/naming/budgets, render dimensions/foreground occupancy/noise, Web assets/placeholders/features/variants, offline payload, offline `file://` browser load, and served-Web browser report. Only overall `PASS` is complete. Applicable `WARN`/`SKIP` produce overall `BLOCKED` unless the exact check has an explicit `--waiver 'CHECK=REASON'`; `NOT_APPLICABLE` is recorded but non-blocking, and `FAIL` cannot be waived.