tera/BUILD_PLAN.md

Tera / Spaces build plan

This is the execution order for the California world. It is intentionally a dependency plan rather than a feature wish list: each milestone leaves behind a tested substrate the next one can safely use.

North star

One continuous California world at three nested scales:

1. State / corridor — Los Angeles to San Francisco, route traffic, flyover.
2. City / exterior — detailed Bay Area and Southern California boards, office buildings as real destinations.
3. Office / metre scale — walkable interiors, people, rooms, and screens.

Every scale supports Observe. Selected actors and vehicles additionally support Play. Public geometry and ambient simulation work from a static clone; identity, private presence, realtime state, webcam faces, and shared screens are hosted capabilities layered on top.

Work lanes

Lane	Owns	Can run in parallel with
World + simulation	transport packs, cells, origin rebasing, controllers	assets, UI, service contracts
Asset craft	vehicles, humanoids, dog, crow, buildings, animation	every milestone once interfaces are frozen
Product + camera	chapters, follow/chase/walk cameras, input, accessibility	simulation and assets
Realtime + media	session authority, interest zones, ACLs, WebRTC surfaces	solo play after state contracts exist
Quality	deterministic replays, browser captures, performance budgets, provenance	continuous; never a final cleanup phase

The critical path is world coordinates → deterministic control → walkable actor contract → authoritative sessions → private media. Art can stay one milestone ahead; realtime/media must not jump ahead of the actor and access contracts.

M0 — contracts and provenance

Status: implemented.

• Tera/Spaces is the renderer; lumbridgecorp is the control plane.
• Apache-2.0 remains the outbound code license.
• Every copied asset/data item gets a pinned source, license, hash, and intake note. Original procedural assets record their design lineage.
• PROVENANCE.json plus npm run provenance hash-gates every tracked distribution artifact, rejects undeclared copied items and remote/bundled fonts, and records original procedural/data lineage.
• npm run licenses enforces the reviewed dependency-license allowlist and registry integrity pins; npm run sbom emits SPDX 2.3 from the lockfile.

Exit gate: a clean clone builds and tests without private services or binary runtime art; every shipped dependency, route, font, and asset has recorded provenance. The only tracked raster art is the two generated social cards in public/, both source-reproducible and SHA-256 pinned in the manifest.

M1 — California roads and passive Model X traffic

Status: implemented and rendered on desktop and mobile; repeatable California and office browser performance-budget instrumentation is implemented.

• Coarse California board plus detailed Bay Area and SoCal boards.
• Serializable US-101 and I-5/I-580/I-80 route graphs.
• Procedural black Model X with follow and corridor detail tiers.
• Fixed-step deterministic traffic, both carriageways, instanced background vehicles, and a chase/follow camera selected from route chapters.

Exit gate: one hero completes either route on the road; the same seed and frame sequence reproduce the same poses; route switching leaks no GPU resources; the declared desktop/mobile frame budgets pass in browser capture.

M2 — solo playable driving

Status: deterministic control core plus keyboard, standard gamepad, touch, chase, and driver-height camera integration implemented and rendered on desktop and mobile. The vehicle owns a controller state separate from its render rig.

• Keyboard, gamepad, and touch input through one normalized action map.
• Chase and driver-height cameras.
• Assisted route following as a state machine; manual input takes over and can hand back cleanly.
• Route guardrails, recovery/reset, pause and background-tab recovery.
• Fixed input traces for deterministic replay tests.

Exit gate: finish both routes manually or assisted; no NaNs, ordinary-speed tunneling, or tab-resume jumps; a recorded input trace replays identically.

M3 — walkable offices and actors

Status: implemented and integrated. City actors and office walkers share the same profile-derived appearance and journey identity; anonymous visitors change from crow outdoors to dog indoors, while signed-in members remain humanoid.

• Third-person walker against the existing Plan.blocked wall segments. A first-person office camera is not implemented or required for this release.
• Door traversal and city ↔ office identity handoff.
• Customizable procedural humanoid for signed-in members.
• Anonymous office visitor is a dog; anonymous Tera visitor is a crow.
• Profiles begin as generated materials and parameters, not uploaded binaries.

Exit gate: every room reachable through doors but never through walls; identity survives scene changes; anonymous clients receive no private presence; 30-minute soak produces no stuck or out-of-bounds actor.

M4 — authoritative multiplayer

Status: core hosted actor, vehicle, and aircraft presence is implemented and covered by deterministic client/service tests; live two-browser acceptance is still an operator QA gate. The service uses short-lived rotating grants, exact interest cells, bounded 10 Hz publishing, strict motion validation, reconnect snapshots, and aggregate- only presence UI. Deterministic two-client and bounded-service acceptance tests cover convergence, late join, cell isolation, ownership, revocation, cleanup, and speed-hack rejection.

• Dedicated in-memory realtime module inside the optional Tera Fastify API; game-state and media signaling remain separate services and protocols.
• Server-authoritative actor/vehicle poses, input validation, interpolation, reconnect, and interest zones keyed by Tera cell / Office / Floor / Room.
• The Tera API issues short-lived rotating session grants after the configured deployment auth adapter resolves a signed-in subject.
• Delta snapshots around 10–15 Hz for nearby dynamic actors; media never rides on this socket.

Automated gate: two logical clients converge; reconnect restores the right cell; revocation ejects promptly; malformed and speed-hack state is rejected; bounded service soak/capacity tests pass. A real two-browser, two-network convergence and revocation smoke remains required before calling a particular hosted deployment production-ready.

M5 — profile and webcam faces

Status: implemented and integrated. Signed-in members can start an optional camera face only from the Character dialog; a persistent live indicator and one-click Stop remain visible while active. Capture is tab-ephemeral, audio-free, never recorded or uploaded, follows the humanoid across scene transitions, and is torn down on Stop, track end, revocation, or page exit.

• Generated profile face is the default.
• Webcam face is opt-in and ephemeral: explicit contextual permission, active indicator, one-click stop, no recording/storage by default.
• Webcam pixels are local to the current browser and are never placed on the realtime or office-screen signaling paths. Remote webcam-face publication has no implementation in this release.

Exit gate: Stop, permission cancellation, track end, membership revocation and pagehide stop every app-owned track; anonymous users receive no camera control; the full product works without a camera. There is no webcam subscription API for an unauthorized peer to reach.

M6 — office media surfaces

Status: implemented and integrated for bounded peer-to-peer hosted sharing at the application layer; internet-grade relay deployment is not enabled. Authored Three.js monitors remain dark until an authorized viewer explicitly opts in; presenters choose a tab/window through the browser prompt and have an immediate kill switch. Signaling grants, conditional TURN credential issuance, video textures, late join, reconnect, and revoke lifecycle are bounded and tested. Presenter encoding defaults to 1280×720 at 15 fps and 1.5 Mbps with capability-safe browser fallback.

• MediaSurface records identify office/room/screen, ACL, source, and state.
• WebRTC peer track after authorization and explicit viewer opt-in; Three.js gets a video texture only while subscribed. An SFU is a later scale-out option, not a core requirement for the bounded eight-participant room.
• Share tab/window by default, muted viewer autoplay, visible broadcast state, presenter kill switch, late join and reconnect.

Exit gate: no unauthorized subscription; revoke ends tracks and disposes GPU textures; bandwidth adaptation and safe public placeholders work. The current server authorization boundary is a signed-in deployment member, not tenant or office membership. Tenant-isolated use requires an authoritative office- membership provider. Public TURN remains disabled until the operator completes the relay-only, cross-network, firewall, certificate, quota and revocation acceptance plan in deploy/coturn/README.md.

M7 — playable aircraft

Status: solo and hosted multiplayer play are implemented. The original procedural electric V-tail has deterministic assisted/manual control, chase camera, California bounds, and an authoritative geographic wire adapter; remote clients render its bank, control surfaces, and fan phase from validated state.

Ambient ADS-B rendering remains a separate source and authority path from the playable aircraft controller.

Exit gate: route/altitude bounds, camera and control handoff, multiplayer validation, and no regression to ambient live ADS-B rendering.

Performance gates

Run npm run build && npm run performance. The harness serves the production bundle locally, uses system Chrome (real GPU when available, SwiftShader as the headless fallback), warms each scene, and writes /tmp/tera-performance-budget.json. Budgets live in scripts/performance-budgets.json; a threshold, console error, insufficient sample, or anonymous private endpoint request makes the command non-zero. Use --output, --budgets, --warmup-ms, --sample-ms, or --software for explicit CI/diagnostic runs. The named matrix is California and Office at 1440×900 desktop and 390×844 mobile viewports. Frame comparisons allow only 0.1 ms for Chrome's rAF timestamp quantization; the declared and reported budgets are not raised.

• Named benchmark scenes: p95 frame at or below 16.7 ms desktop and 33.3 ms on the selected supported mobile tier.
• Enforced browser budgets currently cover p95 frame interval, draw calls and triangles. Resident-cell, dynamic-actor, GPU-memory and live-media-texture budgets remain future instrumentation and are not release claims.
• Fixed simulation tick separated from rendering; instancing, LOD, pooling, frustum/distance culling, and explicit resource disposal.
• Degrade shadows, traffic density, and far detail before input, access control, identity, or privacy enforcement.

Release boundary and operator gates

M0–M7 describe the repository implementation, not an assertion that every optional hosted facility is enabled on every deployment. The static/public California and Office experience, solo actors/vehicles/aircraft, procedural art, and local media placeholders remain the release baseline.

Before enabling hosted tenant use or advertising internet-grade screen sharing:

1. Provide authoritative tenant/office membership; current realtime/media auth proves only deployment membership.
2. Complete a real two-browser/two-network realtime and media acceptance run, including revocation and reconnect.
3. Keep TURN ports and TERA_ICE_URLS/TERA_TURN_SHARED_SECRET disabled until every mandatory gate in deploy/coturn/README.md passes.
4. Apply and verify the documented CSP and Permissions-Policy on both entry hosts. Browser capture permission is contextual and does not replace the application's explicit opt-in and visible Stop controls.
5. Treat narrower CSP allowlists, GPU/media memory budgets and Firefox/WebKit browser automation as hardening/follow-up work, not already-passed gates.