mapv10 Viewer

Plain TypeScript + Three.js viewer for mapv10 artifacts.

The renderer core must stay independent from React or any other UI framework. UI shells communicate with the renderer through typed commands/events.

Initial responsibility:

• load artifact manifests
• load typed raster/vector/mesh products
• render the map in Three.js
• expose typed picking and camera events
• keep debug/artifact inspection separate from clean viewer UX

Implemented boot:

• Vite + plain TypeScript + Three.js.
• Framework-neutral renderer core under src/renderer.
• Typed event/API boundary under src/events.
• Manifest-first loader and binary byte-length checks under src/data.
• Vanilla DOM shell under src/ui.
• Canonical generated continent proof fixture under public/continent-lod6, served through the artifact namespace as /mapv10/runs/continent-lod6/manifest.json. Legacy /continent-lod6/... paths are still intercepted so missing artifacts return JSON/problem responses instead of the Vite app shell.

Commands:

npm install
npm run typecheck
npm run build
npm run test
npm run scenarios
npm run fixture:continent
npm run validate:valenar-export
npm run verify:browser:continent
npm run verify:browser:baseline:update
npm run verify:browser:baseline
npm run verify:browser:all

Script	Role
dev	Run the Vite dev server with artifact middleware.
build	Type-check and build the static viewer bundle.
typecheck	TypeScript compile check only.
test / test:watch	Vitest suite once or in watch mode.
scenarios	Playwright scenario runner (scripts/run-scenarios.mjs) that writes screenshots and scenario-results.json.
fixture:continent	Regenerate the ignored canonical public/continent-lod6 fixture and validate its run-local Valenar export.
fixture:continent:validate	Validate an existing fixture without regenerating it.
validate:valenar-export	Validate the stage 15 Valenar export in public/continent-lod6.
verify:browser	Run the general Playwright browser verifier.
verify:browser:continent	Run the canonical m10 LOD6 continuity proof, readiness check, console/GL scan, screenshots, and missing-required-product proof.
verify:browser:baseline:update	Capture the local visual baseline.
verify:browser:baseline	Compare the current browser proof against the local baseline.
verify:browser:all	Chain the general and continent browser verifiers.

npm run fixture:continent is the fresh-clone bootstrap for the ignored canonical fixture. It regenerates public/continent-lod6, validates that the run contains stage 15-valenar-worlddata, and reports the run-local Valenar WorldData counts, hashes, and byte sizes. Use npm run fixture:continent:validate when the fixture already exists and only the export contract needs to be checked. These commands do not copy any files into examples/valenar/Content/WorldData; Valenar keeps using the small world-42 dummy fixture until an explicit import/package step selects a generated export.

Dev server

The Vite dev server runs over plain HTTP on port 5443, bound to 0.0.0.0 so a LAN/Tailscale-attached device can reach it, for example http://100.x.y.z:5443/?manifest=/mapv10/runs/continent-lod6/manifest.json.

Vite serves the viewer app. The mapv10 artifact middleware serves generated run artifacts under /mapv10/runs/<run-id>/..., including byte ranges for large binary products and typed application/problem+json errors for missing runs or artifacts. The tile loader checks byte lengths unconditionally.

Generated run directories under public/ are excluded from Vite's file watcher. They are still served by the artifact middleware, but they are not source files: watching the full continent fixture means traversing hundreds of thousands of tile assets and can exhaust Node's heap during browser verification.

The browser verifier (npm run verify:browser and npm run verify:browser:continent) uses the same HTTP origin as vite.config.ts. The canonical proof path is public/continent-lod6; --run-root is reserved for explicit ad-hoc generated runs and is not part of the continent baseline workflow.

npm run verify:browser:baseline:update captures the canonical browser proof screenshots as a local visual baseline under baselines/browser/continent-lod6. npm run verify:browser:baseline re-runs the same proof and pixel-compares the overview, slow zoom, camera-move, all current map modes, close/detail, boundary, zoom-back, and failure-UX screenshots against that baseline. Diff PNGs for failed comparisons are written under verification/. Baseline PNGs are ignored locally until the project chooses a committed/LFS or CI artifact storage policy.

See:

• ../architecture.md
• ../docs/viewer.md
• ../roadmap.md