@cavegiant/cave-world-r3f 1.0.0

package/doc/ARCHITECTURE.md

@@ -0,0 +1,264 @@
+# Architecture
+
+Internal design of `@cavegiant/cave-world-r3f`, for maintainers. For the rules you must not break while changing it, see [AGENTS.md](../AGENTS.md).
+
+## 1. Layers
+
+```
+types ──→ core ──→ space ──→ explore
+(types)  (runtime)  (scene)   (viewers)
+```
+
+Dependencies run strictly left to right, enforced by `no-restricted-imports` in `eslint.config.js`. Anything shared by `space` and `explore` lives in `space`.
+
+```
+@cave-world/
+├── types/                        # Pure TypeScript, zero runtime
+│   └── space-types.ts            # Complete CaveSpace JSON schema
+│
+├── core/                         # Runtime foundation
+│   ├── events/event-bus.ts       # CaveEventBus — typed pub/sub
+│   ├── registry/                 # ObjectRegistry, ComponentRegistry
+│   ├── context/                  # CaveWorldProvider + per-instance world store
+│   ├── hooks/use-cave-event.ts   # useCaveEvent()
+│   ├── connector-label/          # Label resolution + transfer readiness (pure)
+│   ├── i18n/messages.ts          # All user-visible copy
+│   ├── logging/logger.ts         # Leveled logger (no bare console anywhere)
+│   └── errors.ts                 # CaveWorldError + stable codes
+│
+├── space/                        # Scene rendering (R3F)
+│   ├── cave-space.tsx            # Composition root: env + base + custom layers
+│   ├── cave-env.tsx              # Lighting
+│   ├── cave-base-layer.tsx       # Splat + colliders + boundaries + connectors
+│   ├── cave-custom-layer.tsx     # Iterates custom objects
+│   ├── connector-label-host.tsx  # Label visibility driver
+│   ├── polygon-boundary.tsx      # Fence colliders + touch-only visuals
+│   ├── objects/                  # Renderers + builtin-registrar + behaviors
+│   ├── splats/spark/             # SplatMesh, RobustSplatMesh, reveal
+│   └── utils/                    # Colliders, LOD selection, device + canvas helpers
+│
+└── explore/                      # Viewers and interaction
+    ├── cave-explore.tsx          # Walkable tour — composition only
+    ├── cave-orbit-viewer.tsx     # Orbit overview viewer
+    ├── viewer-shared.ts          # CaveViewerBaseProps
+    ├── connected-spaces-renderer.tsx  # Multi-space scene graph
+    ├── simple-character.tsx      # Local player + viverse camera bridge
+    ├── math/space-transforms.ts  # Seamless / portal / spawn math (pure, tested)
+    ├── hooks/                    # Loading, preload, transitions, actions, shortcuts
+    ├── overlays/                 # Built-in UI, each replaceable
+    ├── characters/               # Avatar config, pose, multiplayer characters
+    ├── services/                 # WebSocket protocol
+    ├── loaders/                  # Scene JSON loaders
+    ├── stores/                   # Per-instance exploration + action-prompt stores
+    └── styles/                   # Stylesheet source + runtime injector
+```
+
+## 2. Design patterns
+
+| Pattern                   | Implementation                                  | Why                                                  |
+| ------------------------- | ----------------------------------------------- | ---------------------------------------------------- |
+| Registry                  | `ObjectRegistry`, `ComponentRegistry`           | Add object/behavior types without touching core code |
+| Event bus                 | `CaveEventBus`                                  | Decouples overlays from the scene graph entirely     |
+| Context DI                | `CaveWorldProvider`, `CaveExploreProvider`      | Per-instance services, no module singletons          |
+| Self-contained components | Each behavior owns its sensors and events       | Unity-style component model                          |
+| JSON-driven scene graph   | `CaveSpace` → layers → objects                  | Content is data, not code                            |
+| Per-object Suspense       | One boundary per object                         | One slow asset can't blank the scene                 |
+| Render props              | `renderDetailWindow`, `renderConnectorLabel`, … | UI replaceable without forking                       |
+
+### Everything is per-instance
+
+`createCaveWorldStore`, `createCaveExploreStore`, and `createActionPromptStore` are factories; the providers own one each. Module-level stores would make two viewers on one page share active-space and prompt state. The same rule applies to caches — the boundary fence keeps its local-player lookup in a ref rather than a module variable.
+
+## 3. Data flow
+
+### 3.1 Scene loading
+
+```
+CaveExplore(spaceId)
+    │
+    ▼
+usePrimarySpaceLoader → caveSpaceLoader(spaceId) ──fetch──→ CaveSpace JSON
+    │
+    ├──→ CaveWorldStore.setSpaceConfig(config)
+    └──→ CaveExploreStore.setConnectedSpace(id, config) + setActiveSpaceId(id)
+    │
+    ▼
+ConnectedSpacesRenderer renders every loaded space
+    └── CaveSpace (per space, memoised, own Suspense boundary)
+         ├── CaveEnv         ← baseLayer.lighting
+         ├── CaveBaseLayer   ← splat + colliders + boundaries + connectors
+         └── CaveCustomLayer ← customLayers[] → CustomObject × N
+                                 ├── ObjectRegistry.get(type)
+                                 └── ComponentRegistry.get(name) × N
+```
+
+The primary scene is registered in `connectedSpaces` like any neighbor. Treating it uniformly is what makes seamless back-traversal (A → B → A) work through the same code path as forward travel.
+
+Once the primary reports ready (`space:initialized`):
+
+1. If `baseLayer.spawnPoint` exists, the character is placed there once (guarded so transitions don't re-run it).
+2. `useConnectorPreloader` fetches every connected scene. Deliberately deferred until the primary's splat and colliders are done, so neighbors don't compete for bandwidth on the same origin, and each neighbor's mount is scheduled in idle time so the burst doesn't stutter input.
+
+### 3.2 Active vs. preloaded spaces
+
+Each `CaveSpace` receives `active`; only the current scene gets `true`.
+
+- `CaveBaseLayer` mounts connector sensors and labels only when active — otherwise a hidden neighbor's connector boxes would fire as the player walks through the same world coordinates in the scene they're actually in, and labels would spoil destinations early.
+- `CaveCustomLayer` renders nothing when inactive, so hidden scenes never pay network/decode/build cost for their objects.
+- The splat **stays rendered** (hidden by the parent `<group visible={false}>`) to keep the mesh resident in GPU memory. That residency is what makes a transition instant.
+- Splat fallback colliders are generated as soon as the splat loads, not when physics turns on, so first entry into a preloaded scene doesn't pay ~1s of generation as visible stutter.
+
+### 3.3 Character orientation
+
+Writing the character's facing **must** go through `behavior.rotationYaw`, never the Group's quaternion.
+
+viverse derives both input direction (`updateSimpleCharacterVelocity`) and model yaw (`updateSimpleCharacterRotation`) from `state.camera`, and the camera behavior overwrites `camera.rotation` from its internal `rotationYaw` every frame. The Group's own quaternion is never read in that pipeline. Since `<SimpleCharacter>` discards the ref returned by its internal `useCharacterCameraBehavior`, `ExploreSimpleCharacter` runs its own behavior, exposes it as `characterRef.current.viverseCameraBehavior`, and passes `cameraBehavior={false}` so viverse's copy short-circuits.
+
+There is also a 180° convention gap: scene data treats `yaw = 0` as facing **+Z** (object convention), while `rotationYaw` is a camera Y-rotation and Three.js cameras look down **−Z**. `applyCharacterPose` adds `Math.PI` to reconcile them.
+
+### 3.4 Action prompts
+
+All in-scene interaction hints flow through one store:
+
+```
+events (object:enter/leave, connector:enter/leave)
+          │
+          ▼
+useExploreActions — decides the action list from context
+          │
+          ▼
+ActionPromptStore { actions, anchor, style }
+          │
+          ├─ anchor set  → ActionBubble (3D Html, single hint)
+          └─ anchor null → ActionPanel  (screen-space list)
+          │
+          ▼
+useActionShortcuts — one global keydown listener, reads store.getState()
+```
+
+`useActionShortcuts` does **not** subscribe to `actions`. Subscribing would re-render the component hosting the character on every prompt show/hide, which trips a bug in viverse's `useSimpleCharacterActionBindings` (dep-less effect plus an `instanceof` guard that never passes): it recreates the keyboard bindings with an empty `pressedKeys` set, so the player stops mid-walk whenever a connector prompt appears. The `memo` on `ExploreSimpleCharacter` and the memoised `physics` object close the remaining paths.
+
+### 3.5 Cross-scene travel
+
+```
+JSON: baseLayer.connectors[] = [{ id, transform, connectorInfo: { to: [...] } }]
+          │
+          ▼
+CaveBaseLayer mounts a BvhPhysicsSensor per connector (active scene only)
+          │
+          ├─ plus ConnectorLabelHost for portal connectors with labels enabled
+          │     └─ distance fade, hides on entry, greys out while target preloads
+          │
+          ▼
+player touches the box → emit('connector:enter')
+          │
+          ▼
+useConnectorTransitions
+  ├─ seamless target → switch activeSpaceId immediately
+  └─ portal target   → setActiveConnector → useExploreActions shows the picker
+                          └─ selection → emit('connector:portal:select')
+                                └─ teleport + switch activeSpaceId
+```
+
+**Seamless alignment.** `ConnectorTarget.transform` is a column-major 4×4 mapping **source-local → target-local** (before `baseLayer.transform`):
+
+```
+p_target_local = M_raw × p_source_local
+G_target = G_source × T_source × inverse(M_raw) × inverse(T_target)
+```
+
+Implemented in `explore/math/space-transforms.ts` and covered by tests, including an A → B → A round-trip that must restore A's original placement.
+
+**Ghost-enter suppression.** After a seamless A → B transition the character occupies the same world position, which by construction is inside B's matching back-link connector. Since sensors mount only for the active scene, B's sensor is added while the player is already inside it and fires `onIntersectedChanged(true)` on the next tick — which would ping-pong them straight back to A. `useConnectorTransitions` writes a 200 ms timestamp to `connectorEnterSuppressUntil`; both it and `useExploreActions` check the window but neither consumes it, so one handler can't leave the other seeing clean state (which would pop a spurious panel for connectors with mixed seamless + portal targets). Portal transitions don't need this: the arrival point is 0.5 m outside the target box.
+
+### 3.6 Load-failure hardening
+
+spark's `SplatMesh` has `onLoad` but no `onError`, and a failed download leaves `mesh.initialized` rejected with nothing catching it. Since readiness gates on `onLoad`, that alone would hang the viewer forever.
+
+```
+RobustSplatMesh
+  ├─ attaches to mesh.initialized  → catches spark's unhandled rejection
+  ├─ watchdog timeout (~30s)       → catches silently stalled downloads
+  ├─ retries with backoff (×3)     → remounts the mesh via a fresh args ref
+  ├─ emits space:error each time   → telemetry, with willRetry
+  └─ exhausted → onError → CaveWorldState.spaceLoadError
+                              │
+                              ▼
+                    SpaceLoadErrorOverlay (portaled to document.body)
+```
+
+The overlay is portaled at a very high z-index specifically to escape host stacking contexts: host loading UI is typically a `fixed` sibling outside the viewer subtree and would otherwise cover the prompt, leaving the user on a spinner that never resolves.
+
+Only the **active** scene surfaces a terminal error. A hidden neighbor failing in the background must not pop a full-screen prompt over a working scene; it still retries, and a manual retry re-downloads it too.
+
+### 3.7 Entry reveal
+
+The primary scene's splat plays a one-shot reveal, driven inside `RobustSplatMesh` so it adds no state to `CaveBaseLayer`:
+
+```
+onLoad → applySpreadReveal()  — attach a spark dyno objectModifier
+onFrame → advance shader time → mesh.updateVersion()
+~6s     → clearSpreadReveal() + detach onFrame
+```
+
+Visually: the whole scene appears immediately as a point cloud (original colors, uniform tiny scale), then a radial wave from the center snaps each splat to full scale. It runs in parallel with `space:initialized` and never delays readiness. Only `isPrimary` scenes honour `revealOnEnter`, so preloaded neighbors and transitions never replay it.
+
+## 4. State ownership
+
+| Store               | Location          | Holds                                                                        |
+| ------------------- | ----------------- | ---------------------------------------------------------------------------- |
+| `CaveWorldState`    | `core/context/`   | Scene config, active object, detail visibility, load error, retry token      |
+| `CaveWorldServices` | `core/context/`   | Event bus, registries, store, messages, label renderer                       |
+| `CaveExploreState`  | `explore/stores/` | View mode, active space, connected spaces, transforms, connectors, room info |
+| `ActionPromptState` | `explore/stores/` | Current actions, anchor, style                                               |
+
+`CaveWorldState` is shared by `space` and `explore` through context. The exploration stores are `explore`-only. On a scene change, `CaveWorldState.spaceConfig` is updated to the new active scene so existing overlays keep working.
+
+## 5. Tech stack
+
+| Concern     | Choice                                                        |
+| ----------- | ------------------------------------------------------------- |
+| Rendering   | React Three Fiber + Three.js                                  |
+| Physics     | `@react-three/viverse` (BVH collision)                        |
+| Splats      | `@sparkjsdev/spark` 0.1.x                                     |
+| State       | Zustand + `subscribeWithSelector`                             |
+| 3D helpers  | `@react-three/drei`                                           |
+| Multiplayer | In-house WebSocket protocol                                   |
+| UI          | Hand-written CSS, `.cw-*` namespace, `--cw-*` theme variables |
+
+### Spark version
+
+**Pinned to 0.1.x deliberately.** Spark 2.x regenerates its splat accumulator every frame the view changes — i.e. only while walking. viverse integrates the character as `position += velocity * delta` with no smoothing, so that frame-time variance surfaces as the character stepping fore/aft. Idle and static environments are unaffected, which makes it read like a character bug. Disabling 2.x LOD and foveation did not help. 0.1.x also auto-injects its renderer, so no `SparkRenderer` component is needed, and `SplatMesh` takes plain `{ url, onLoad }` options.
+
+## 6. Performance measures
+
+- `antialias: false` on the canvas ([Spark guidance](https://sparkjs.dev/docs/performance/)).
+- `getSparkCanvasDpr()` caps `devicePixelRatio`; splat blending cost scales with pixel count.
+- `useVisibilityFrameloop()` switches R3F `frameloop` to `never` while the page is hidden — GPU work drops to zero, which is the main heat driver on mobile. R3F's `setFrameloop` restarts the clock, so the first visible frame has no delta spike.
+- Device-aware splat LOD via `selectSplatLevel`, evaluated once per scene mount so a resize can't trigger a re-download.
+- One Suspense boundary per suspending subtree — see [6.1](#61-suspense-topology).
+- Both viewers call `preloadSpaceAssets()` as soon as the scene JSON lands, so collider OBJs download alongside the splat instead of after the base layer mounts.
+- `ConnectorLabelHost` computes visibility every frame but only publishes to React across a threshold.
+- Neighbor preloads are serialized and idle-scheduled.
+- `startTransition` wraps collider generation and scene switches.
+- Remote characters are capped (50 by default).
+
+### 6.1 Suspense topology
+
+When a component suspends, React throws away everything already rendered inside the boundary it unwinds to and rebuilds that subtree once the promise resolves. For a splat scene that is not merely wasted work: spark's `SplatMesh` starts its download in the constructor and keeps no URL cache, so a rebuilt mesh downloads the asset again — while the discarded fetch keeps running, because spark offers no way to abort it. Entering a scene could issue the same multi-megabyte request several times.
+
+Every leaf that suspends therefore owns a boundary:
+
+| Suspending leaf                                     | Suspends via                                                      | Boundary lives in                                             |
+| --------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------- |
+| A space's whole subtree                             | anything below it                                                 | `SpaceSubtree` (`ConnectedSpacesRenderer`), `CaveOrbitViewer` |
+| Model collider                                      | `useLoader(OBJLoader, …)`                                         | `CaveBaseLayer`, one per collider                             |
+| Scene object (GLB / FBX / texture / video / `Text`) | drei loader hooks                                                 | `CustomObject`                                                |
+| Local character                                     | viverse `suspend()` — once for the model, once per animation clip | `CaveExplore`                                                 |
+| Remote player                                       | `useGLTF` × 7                                                     | `RemoteCharacterController`, one per player                   |
+| Host `children`                                     | anything                                                          | `CaveExplore`, `CaveOrbitViewer`                              |
+
+Two properties of that layout are load-bearing:
+
+- **Collider boundaries sit outside `BvhPhysicsBody`.** viverse snapshots the body's children into the BVH world in a mount effect and documents that its content must not suspend; a mesh that appears later never becomes a collider.
+- **Sibling assets load in parallel.** A shared boundary serializes them: the first suspension aborts the render before its siblings start their own request, so each retry only gets one step further.