How the demo loop runs

How the WebAssembly harness behind the site’s future demo is built, served, and tested. This page stays deliberately short: it is the map of the loop, not its internals.

The three steps

1. Build. The map-web-bindings crate compiles to wasm32-unknown-unknown and the wasm-bindgen CLI emits the ES module the pages import. The CLI’s version and the crate’s wasm-bindgen dependency are a locked pair: one bump regenerates the emit.
2. Serve. A small dependency-free static server serves the generated pkg/ plus a set of allow-listed same-origin routes: recorded raster-tile imagery, the six committed golden images, the shared reference-scenes demo artifact, and the compiled offline-routing archive. The browser never touches an external network; the loop is fully offline against recorded fixtures, and the camera’s default anchor sits inside the recorded tile neighborhood, so the page shows real imagery immediately.
3. Test. The Playwright suite runs headless over Chromium: version and projection probes, round-trip projection, antimeridian tile listing, a WebGPU canvas smoke, and camera readouts. A separate contract-sync test (no browser, no npm) parses the frozen UDL, the hand-reviewed TypeScript mirror, and the wasm exports, and asserts the three agree.

What keeps the parity honest

The browser canvas mirrors the native renderer with one rule: same WGSL text, same vertex layout, same index pattern. Tests render the same camera against committed golden reference images in both places, so a browser-vs-native pixel compare stays meaningful.

Known limitations

• The static server binds a fixed localhost port, so two harness sessions cannot share it; a test-only environment-variable port override is the workaround.
• The GPU canvas draws only through WebGPU. Its documented degradation path is a 2D overlay grid, never WebGL.
• WebKit runs resolve WebGPU nowadays, so a WebKit run exercises the GPU path, not the 2D fallback.