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

3.1 KiB

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:

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:

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.