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.