@cavegiant/cave-world-r3f 1.0.0

package/doc/API.md

@@ -0,0 +1,617 @@
+# API Reference
+
+Integration and extension guide for `@cavegiant/cave-world-r3f`.
+
+## API stability
+
+| Tier         | Surface                                                                                                                                                                                                                                               | Semver expectation                                             |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| **Stable**   | `CaveExplore`, `CaveOrbitViewer`, `CaveViewerBaseProps`, loaders (`createHttpCaveSpaceLoader`, `DefaultCaveSpaceLoader`), `CaveWorldProvider`, registries, `useCaveEvent` / `CaveEventBus`, `messages` / logger APIs, scene JSON types under `/types` | Breaking changes only in major releases                        |
+| **Advanced** | Composition hooks (`useConnectorTransitions`, `usePrimarySpaceLoader`, …), `ConnectedSpacesRenderer`, `ExploreSimpleCharacter`, `RemoteCharacterController`, `WebSocketService`, `useCharacterSync`, store factories                                  | May change in minor releases; prefer Stable APIs when possible |
+
+Root package re-exports `CaveSpace` as **`CaveSpaceRenderer`** to avoid clashing with the `CaveSpace` config type. Prefer importing the component from `@cavegiant/cave-world-r3f/space` as `CaveSpace`.
+
+- [Viewers](#viewers)
+  - [CaveExplore](#caveexplore)
+  - [CaveOrbitViewer](#caveorbitviewer)
+- [Tracking the player's scene](#tracking-the-players-scene)
+- [Events](#events)
+- [Extending the scene](#extending-the-scene)
+- [Replacing the UI](#replacing-the-ui)
+- [The local character](#the-local-character)
+- [Multiplayer](#multiplayer)
+- [Load failures](#load-failures)
+- [Styling and copy](#styling-and-copy)
+- [Core hooks](#core-hooks)
+- [Composing your own canvas](#composing-your-own-canvas)
+- [Performance guidance](#performance-guidance)
+
+---
+
+## Viewers
+
+Both viewers share a base set of props (`CaveViewerBaseProps`):
+
+| Prop                 | Type                                 | Default                                         | Description                                       |
+| -------------------- | ------------------------------------ | ----------------------------------------------- | ------------------------------------------------- |
+| `spaceId`            | `string`                             | —                                               | Scene id passed to the loader                     |
+| `caveSpaceLoader`    | `(id: string) => Promise<CaveSpace>` | `DefaultCaveSpaceLoader` (CaveGiant public API) | Scene JSON loader — pass your own in production   |
+| `onSpaceInitialized` | see per-viewer                       | —                                               | Fires when the base layer is ready                |
+| `eventBus`           | `CaveEventBus`                       | created internally                              | Reuse a bus to observe events from outside React  |
+| `objectRegistry`     | `ObjectRegistry`                     | created internally                              | Custom object renderers                           |
+| `componentRegistry`  | `ComponentRegistry`                  | created internally                              | Custom behavior components                        |
+| `messages`           | `PartialCaveWorldMessages`           | `zhCN`                                          | Copy overrides, deep-merged                       |
+| `injectStyles`       | `boolean`                            | `true`                                          | Inject the default stylesheet at runtime          |
+| `revealOnEnter`      | `boolean`                            | `true`                                          | Play the spread reveal on first splat load        |
+| `renderDetailWindow` | `() => ReactNode`                    | built-in                                        | Replace the detail panel                          |
+| `onLoadError`        | `(error: SpaceLoadError) => void`    | —                                               | Terminal load failure (fires once)                |
+| `onLoadErrorExit`    | `() => void`                         | —                                               | Back-button handler; omitting it hides the button |
+| `renderLoadError`    | `LoadErrorRenderer`                  | built-in                                        | Replace the load-error prompt                     |
+| `children`           | `ReactNode`                          | —                                               | Extra R3F content inside the scene graph          |
+
+Importable type: `CaveViewerBaseProps`, `ActiveSpaceChangeHandler` from `@cavegiant/cave-world-r3f/explore`.
+
+### CaveExplore
+
+Walkable first/third-person tour with physics, character controls, and cross-scene travel.
+
+```tsx
+import { CaveExplore } from '@cavegiant/cave-world-r3f/explore'
+
+;<div style={{ width: '100vw', height: '100vh' }}>
+  <CaveExplore spaceId={id} />
+</div>
+```
+
+Uses `DefaultCaveSpaceLoader` (CaveGiant public API) when `caveSpaceLoader` is omitted. For a private backend:
+
+```tsx
+import { CaveExplore, createHttpCaveSpaceLoader } from '@cavegiant/cave-world-r3f/explore'
+
+const loader = createHttpCaveSpaceLoader({
+  buildUrl: (id) => `/api/spaces/${id}`
+})
+
+<CaveExplore spaceId={id} caveSpaceLoader={loader} />
+```
+
+Additional props:
+
+| Prop                   | Type                                                          | Default                | Description                                                                                      |
+| ---------------------- | ------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------ |
+| `onActiveSpaceChange`  | `(spaceId, space?) => void`                                   | —                      | Fires for the initial scene and after every transition; see [below](#tracking-the-players-scene) |
+| `multiplayer`          | `false \| { url, avatarId?, avatars?, maxRemoteCharacters? }` | `false`                | Character sync — **`url` is required** when enabled                                              |
+| `localCharacterModel`  | `LocalCharacterModelProp`                                     | viverse mannequin      | Third-person avatar; see [below](#the-local-character)                                           |
+| `characterControls`    | `CharacterControlsConfig`                                     | viverse defaults       | Movement speeds and input bindings                                                               |
+| `connectorLabel`       | `'auto' \| 'off'`                                             | `'auto'`               | Global default for wayfinding labels                                                             |
+| `renderConnectorLabel` | `ConnectorLabelRenderer`                                      | `ConnectorLabelBeacon` | Replace label visuals                                                                            |
+| `exploreHelper`        | `ExploreHelperConfig \| false`                                | enabled                | First-run controls hint                                                                          |
+| `renderExploreHelper`  | `ExploreHelperRenderer`                                       | built-in               | Replace the hint UI                                                                              |
+| `onPortalNavigate`     | `(portal, object) => boolean \| void`                         | —                      | Handle `portal` object activation                                                                |
+
+#### Imperative handle
+
+```tsx
+import { useRef } from 'react'
+import { CaveExplore, type CaveExploreHandle } from '@cavegiant/cave-world-r3f/explore'
+
+const ref = useRef<CaveExploreHandle>(null)
+
+// Base-layer-local coordinates in the active scene; yaw 0 faces +Z.
+ref.current?.teleport({ position: [12, 0, 4], yaw: Math.PI })
+ref.current?.getActiveSpaceId()
+ref.current?.getCharacter()
+
+<CaveExplore ref={ref} spaceId={id} />
+```
+
+#### Portal navigation
+
+`portal` objects can point anywhere, so the SDK only acts on absolute `http(s)` URLs (opened in a new tab). Anything else — in-app routes, deep links — is yours to handle, because the SDK cannot know your router:
+
+```tsx
+<CaveExplore
+  spaceId={id}
+  onPortalNavigate={(portal) => {
+    if (portal.internalScene?.id) {
+      navigate(`/scene/${portal.internalScene.id}`)
+      return true // handled
+    }
+  }}
+/>
+```
+
+### CaveOrbitViewer
+
+Orbit-camera overview of one scene: no avatar, no locomotion, no cross-scene travel. Use it for overview pages and scene pickers.
+
+```tsx
+import { Html } from '@react-three/drei'
+import { CaveOrbitViewer } from '@cavegiant/cave-world-r3f/explore'
+
+;<CaveOrbitViewer
+  spaceId={id}
+  camera={{ position: [-0.28, 2.65, -2.12], target: [0, 0, 0] }}
+  orbit={{ maxPolarAngle: Math.PI / 2.3, minDistance: 2, maxDistance: 8 }}
+  onSpaceInitialized={({ camera, controls, space }) => {
+    // Per-scene framing the SDK can't know about
+  }}
+>
+  {tags.map((tag) => (
+    <Html key={tag.id} position={tag.position} center>
+      <MyTag label={tag.label} />
+    </Html>
+  ))}
+</CaveOrbitViewer>
+```
+
+Additional props:
+
+| Prop                 | Type                                 | Default                         | Description                                                                                      |
+| -------------------- | ------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `transformSpace`     | `(space) => CaveSpace`               | —                               | Adjust the loaded scene before render (e.g. level an off-axis capture). Must return a new object |
+| `camera`             | `{ position, target?, fov? }`        | `position: [0,10,10]`           | Initial framing, applied when the base layer is ready                                            |
+| `orbit`              | `OrbitControlsConfig`                | damping off, `rotateSpeed: 0.8` | Orbit limits                                                                                     |
+| `connectorLabels`    | `boolean`                            | `false`                         | Show wayfinding labels                                                                           |
+| `onSpaceInitialized` | `(api: OrbitViewerReadyApi) => void` | —                               | Receives `{ camera, controls, space }`                                                           |
+
+---
+
+## Tracking the player's scene
+
+Players walk between scenes, so the route id only reflects where they _entered_. Anything scene-scoped in your UI should follow `onActiveSpaceChange`, which fires once for the initial scene and again after every transition — and hands you that scene's loaded JSON, so names come from the data rather than a hardcoded map.
+
+```tsx
+function ScenePage() {
+  const { id } = useParams()
+  const [currentSceneId, setCurrentSceneId] = useState(id)
+  const [sceneName, setSceneName] = useState('')
+
+  useEffect(() => {
+    setCurrentSceneId(id)
+    setSceneName('')
+  }, [id])
+
+  return (
+    <CaveExplore
+      spaceId={id}
+      onActiveSpaceChange={(sid, space) => {
+        setCurrentSceneId(sid)
+        setSceneName(space?.metadata?.name ?? '')
+      }}
+    />
+  )
+}
+```
+
+The `connector:transition` event covers the same ground but not the initial scene, so it is better suited to analytics than UI sync.
+
+---
+
+## Events
+
+```tsx
+import { CaveEventBus } from '@cavegiant/cave-world-r3f/core'
+
+// Outside React
+const eventBus = new CaveEventBus()
+const unsubscribe = eventBus.on('object:click', ({ object }) => console.log(object.name))
+
+<CaveExplore spaceId={id} eventBus={eventBus} />
+```
+
+```tsx
+import { useCaveEvent } from '@cavegiant/cave-world-r3f/core'
+
+// Inside the provider tree — auto-unsubscribes, always sees latest state
+function Listener() {
+  useCaveEvent('object:enter', ({ object }) => console.log(object.name))
+  return null
+}
+```
+
+| Event                     | Payload                                 | Fires when                                        |
+| ------------------------- | --------------------------------------- | ------------------------------------------------- |
+| `object:click`            | `{ object, nativeEvent? }`              | An object is clicked                              |
+| `object:enter`            | `{ object }`                            | Player enters an object's proximity sensor        |
+| `object:leave`            | `{ object }`                            | Player leaves it                                  |
+| `object:interact`         | `{ object, action }`                    | Player acts on an object (e.g. presses F)         |
+| `object:active`           | `{ object }`                            | An object becomes the active interaction target   |
+| `detail:open`             | `{ object }`                            | Detail window opened                              |
+| `detail:close`            | `{}`                                    | Detail window closed                              |
+| `connector:enter`         | `{ connector }`                         | Player enters a connector volume                  |
+| `connector:leave`         | `{ connector }`                         | Player leaves it                                  |
+| `connector:transition`    | `{ from, to, type }`                    | A cross-scene transition completed                |
+| `connector:portal:select` | `{ connector, target }`                 | A portal destination was chosen                   |
+| `connector:label:click`   | `{ connector }`                         | A wayfinding label was clicked                    |
+| `space:loading`           | `{ progress }`                          | Scene load progress, 0–1                          |
+| `space:initialized`       | `{}`                                    | Active scene's base layer is ready                |
+| `space:transfer:ready`    | `{ spaceId }`                           | A connected scene finished preloading             |
+| `space:error`             | `{ error, willRetry?, spaceId?, url? }` | A scene JSON or splat load failed (every attempt) |
+| `boundary:contact`        | `{ boundaryId, proximity }`             | Player is blocked by a boundary fence             |
+| `boundary:release`        | `{ boundaryId }`                        | Player moved away from the fence                  |
+| `custom:*`                | `unknown`                               | Your own events; no type registration needed      |
+
+Guarantees: handlers are snapshotted before dispatch, so subscribing or unsubscribing inside a handler cannot skip or double-fire a peer; and a throwing handler is logged and isolated rather than aborting the rest.
+
+---
+
+## Extending the scene
+
+### Custom object types
+
+Each object in the scene JSON has a `type` that selects its renderer.
+
+```tsx
+import { ObjectRegistry, type ObjectRendererProps } from '@cavegiant/cave-world-r3f/core'
+
+function TreasureChest({ object, onClick }: ObjectRendererProps) {
+  return (
+    <mesh onClick={onClick} userData={{ customObject: object }}>
+      <boxGeometry args={[1, 0.6, 0.8]} />
+      <meshStandardMaterial color="gold" />
+    </mesh>
+  )
+}
+
+const objectRegistry = new ObjectRegistry()
+objectRegistry.register('treasureChest', TreasureChest)
+
+<CaveExplore spaceId={id} objectRegistry={objectRegistry} />
+```
+
+Registering a built-in type name replaces that built-in: the SDK installs its own with `registerDefault`, which never overwrites an existing registration.
+
+Built-in renderers: `model`, `splat`, `image`, `video`, `poi`, `portal`, `placeholder`.
+
+Official schema types with **no** built-in renderer — they need product-specific UI, so register your own: `infoPoint`, `panoramaVideo`, `digitalHuman2D`, `text`, `light`, `audio`, `npc`. Objects of an unregistered type (or an unregistered behavior component) render nothing / are skipped. There is no throw. Call `setCaveWorldLogLevel('debug')` to log each skip once per type/name.
+
+### Custom behavior components
+
+Components attach to any object through the JSON `components` field. They are self-contained: each owns its sensors, state, and events.
+
+```tsx
+import { ComponentRegistry, type ObjectComponentProps } from '@cavegiant/cave-world-r3f/core'
+
+function GlowEffect({ object }: ObjectComponentProps) {
+  return <pointLight color="cyan" intensity={2} distance={5} />
+}
+
+const componentRegistry = new ComponentRegistry()
+componentRegistry.register('Glow', GlowEffect, { requiresInteraction: false })
+```
+
+```json
+{ "id": "obj1", "type": "model", "components": { "Glow": { "name": "Glow" } } }
+```
+
+`requiresInteraction: true` makes the object's wrapper bind an `onClick` that emits `object:click`.
+
+Built-in component: `Window` (proximity sensor + detail-window trigger).
+
+---
+
+## Replacing the UI
+
+Every built-in overlay has an escape hatch, and they all communicate through events and the stores — so a replacement gets the same inputs the original had.
+
+| Prop                   | Replaces                |
+| ---------------------- | ----------------------- |
+| `renderDetailWindow`   | Object detail panel     |
+| `renderConnectorLabel` | 3D wayfinding labels    |
+| `renderExploreHelper`  | First-run controls hint |
+| `renderLoadError`      | Load-failure prompt     |
+
+```tsx
+import {
+  ConnectorLabelTagShell,
+  type ConnectorLabelRendererProps
+} from '@cavegiant/cave-world-r3f/explore'
+
+function MyLabel({
+  label,
+  opacity,
+  displayMode,
+  isPlayerInside,
+  transferStatus,
+  onClick
+}: ConnectorLabelRendererProps) {
+  if (isPlayerInside || displayMode === 'hidden') return null
+  // Reuse the shell for camera-facing behavior and pointer handling.
+  return (
+    <ConnectorLabelTagShell opacity={opacity}>
+      <MySignpost text={label.text} pending={transferStatus === 'loading'} onClick={onClick} />
+    </ConnectorLabelTagShell>
+  )
+}
+
+;<CaveExplore spaceId={id} connectorLabel="auto" renderConnectorLabel={MyLabel} />
+```
+
+The SDK keeps owning visibility gating (distance fade, hide-while-inside, portal-only) so your renderer only supplies visuals.
+
+A full host-style recipe — Mixamo avatar plus the Ordos portal's real connector
+tag, Lottie loading carousel, and first-run guide — is in
+[`examples/07-product-skin.tsx`](../examples/07-product-skin.tsx).
+
+A custom detail window reads the same state the built-in one does:
+
+```tsx
+import { useCaveEvent, useCaveEventBus, useCaveWorldStore } from '@cavegiant/cave-world-r3f/core'
+
+function MyDetailWindow() {
+  const activeObject = useCaveWorldStore((s) => s.activeObject)
+  const detailVisible = useCaveWorldStore((s) => s.detailVisible)
+  const setDetailVisible = useCaveWorldStore((s) => s.setDetailVisible)
+  const eventBus = useCaveEventBus()
+
+  useCaveEvent('detail:open', () => setDetailVisible(true))
+  if (!detailVisible || !activeObject) return null
+
+  return (
+    <div>
+      <h2>{activeObject.name}</h2>
+      <button
+        onClick={() => {
+          setDetailVisible(false)
+          eventBus.emit('detail:close', {})
+        }}
+      >
+        Close
+      </button>
+    </div>
+  )
+}
+```
+
+---
+
+## The local character
+
+In third person the local player is rendered by viverse's `SimpleCharacter`. First person always hides the body.
+
+| `localCharacterModel`       | Result                                |
+| --------------------------- | ------------------------------------- |
+| omitted / `true`            | viverse built-in mannequin            |
+| `false`                     | no visible mesh, even in third person |
+| `LocalCharacterModelConfig` | your GLB/VRM from `url`               |
+
+```tsx
+import {
+  createLocalCharacterModelConfig,
+  MIXAMO_STYLE_BONE_MAP
+} from '@cavegiant/cave-world-r3f/explore'
+
+// Module scope: the reference must be stable (see below).
+const AVATAR = createLocalCharacterModelConfig('./human.glb', {
+  boneMap: MIXAMO_STYLE_BONE_MAP,
+  scale: 0.8
+})
+
+<CaveExplore spaceId={id} localCharacterModel={AVATAR} />
+```
+
+Config fields: `type?` (`'gltf' | 'vrm'`), `url`, `boneMap?`, `boneRotationOffset?`, `castShadow?`, `receiveShadow?`, `useDraco?`, `useViverseAvatar?` (default `false`), `scale?` (default `0.8`, scales both the mesh and the physics capsule).
+
+`MIXAMO_STYLE_BONE_MAP` maps unprefixed Mixamo joint names (`Hips`, `LeftUpLeg`, `Spine01`, …) to VRM 1.0 names, so viverse's built-in idle/walk/run/jump animations work. Bones your model lacks are skipped during retargeting. A rig already using VRM 1.0 names needs only `url`.
+
+> **Reference stability matters.** `ExploreSimpleCharacter` is `memo`-wrapped. A config object created inline in JSX is new on every render, which defeats the memo and can make viverse re-download the GLB and reset held-key movement state. Use a module constant, or `useMemo` keyed on the URL.
+
+### Movement and input
+
+```tsx
+import { Vanilla } from '@react-three/viverse'
+import type { CharacterControlsConfig } from '@cavegiant/cave-world-r3f/explore'
+
+const MOVEMENT = { walk: { speed: 2.4 }, run: { speed: 6 }, jump: false }
+
+export const CONTROLS: CharacterControlsConfig = {
+  movement: MOVEMENT,
+  mobileActionBindings: [
+    Vanilla.ScreenJoystickLocomotionActionBindings,
+    MySpeedSelectorBindings,
+    Vanilla.PointerCaptureRotateZoomActionBindings
+  ],
+  actionBindingOptions: { screenJoystickRunDistancePx: 9999 }
+}
+```
+
+For speed tiers, mutate `MOVEMENT.walk.speed` in place rather than passing a new object — replacing it remounts `SimpleCharacter` and drops keyboard/joystick state.
+
+---
+
+## Multiplayer
+
+Multiplayer is **opt-in and explicit**. Bare `multiplayer` / `multiplayer={true}` without a `url` is ignored (warning). Omitting `avatars` does **not** load the CaveGiant CDN catalog — pass your own, or import `BUILTIN_AVATARS` for demos.
+
+```tsx
+import {
+  BUILTIN_AVATARS,
+  DEFAULT_WEBSOCKET_URL,
+  CaveExplore
+} from '@cavegiant/cave-world-r3f/explore'
+
+;<CaveExplore
+  spaceId={id}
+  multiplayer={{
+    url: 'wss://realtime.example.com/gameplay',
+    // or DEFAULT_WEBSOCKET_URL for the CaveGiant demo backend
+    avatarId: 'hero',
+    avatars: MY_AVATAR_CATALOG, // or BUILTIN_AVATARS for demos
+    maxRemoteCharacters: 20
+  }}
+/>
+```
+
+The connection is per-viewer and torn down on unmount. Advanced exports for custom compositions: `WebSocketService`, `useCharacterSync`, `RemoteCharacterController`, `MessageActionEnum`, `DEFAULT_WEBSOCKET_URL`. Protocol details: [multiplayer-protocol.md](./multiplayer-protocol.md).
+
+Wrap host UI around the viewer with a React error boundary if you need recovery from unexpected R3F/WebGL failures outside the splat load-error path.
+
+---
+
+## Load failures
+
+3DGS assets and scene JSON occasionally fail on weak networks. Because spark's `SplatMesh` has only `onLoad` — no `onError` — a failure would otherwise leave `initialized` rejected and the viewer stuck loading forever. The SDK defends against that:
+
+- **Automatic retry** with backoff (3 attempts by default), re-downloading by remounting the mesh.
+- **Stall watchdog** (~30s) for downloads that neither complete nor error.
+- **`space:error`** on every failure, with `willRetry`, for telemetry.
+- **Retry prompt** once retries are exhausted, portaled to `document.body` at a very high z-index so it escapes host stacking contexts. Host loaders are usually `fixed` siblings outside the viewer subtree and would otherwise cover it — leaving the user on a spinner that never resolves.
+
+```tsx
+<CaveExplore
+  spaceId={id}
+  onLoadError={(error) => {
+    teardownMyLoader()
+    track(error)
+  }}
+  onLoadErrorExit={() => navigate('/')}
+  // renderLoadError={({ error, retry, exit }) => <MyPrompt … />}
+/>
+```
+
+Failure state lives on the per-instance store as `spaceLoadError` (`{ stage: 'config' | 'splat', url?, spaceId?, error }`); `retrySpaceLoad()` clears it and bumps `retryToken` to re-trigger loading.
+
+Loader errors are `CaveWorldError` with a stable `code`: `SPACE_FETCH_FAILED`, `SPACE_FETCH_TIMEOUT`, `INVALID_SPACE`, `SPLAT_LOAD_FAILED`, `SPLAT_LOAD_TIMEOUT`, `MISSING_PROVIDER`.
+
+---
+
+## Styling and copy
+
+See the [README](../README.md#styling) for theming and localization. The short version: `.cw-*` classes themed through `--cw-*` variables, injected at runtime unless `injectStyles={false}`; all copy comes from `messages`, deep-merged over the default locale.
+
+---
+
+## Core hooks
+
+All require a `<CaveWorldProvider>` ancestor, which the viewers mount.
+
+| Hook                           | Returns             | Notes                                        |
+| ------------------------------ | ------------------- | -------------------------------------------- |
+| `useCaveWorld()`               | `CaveWorldServices` | Everything: bus, registries, store, messages |
+| `useCaveWorldStore(selector)`  | `T`                 | Subscribe to world state                     |
+| `useCaveWorldStoreApi()`       | store handle        | `getState` / `subscribe`, no re-render       |
+| `useCaveWorldMessages()`       | `CaveWorldMessages` | Resolved copy                                |
+| `useCaveEventBus()`            | `CaveEventBus`      |                                              |
+| `useCaveEvent(event, handler)` | `void`              | Auto-cleanup; handler kept in a ref          |
+| `useObjectRegistry()`          | `ObjectRegistry`    |                                              |
+| `useComponentRegistry()`       | `ComponentRegistry` |                                              |
+
+Exploration hooks (require `<CaveExploreProvider>`, mounted by `CaveExplore`):
+
+| Hook                        | Returns                    |
+| --------------------------- | -------------------------- |
+| `useCaveExplore(selector)`  | Exploration state slice    |
+| `useCaveExploreStore()`     | Exploration store handle   |
+| `useActionPrompt(selector)` | Action-prompt state slice  |
+| `useActionPromptStore()`    | Action-prompt store handle |
+
+### World state
+
+```ts
+interface CaveWorldState {
+  spaceConfig: CaveSpace | undefined
+  activeObject: CustomObject | undefined
+  detailVisible: boolean
+  spaceLoadError: SpaceLoadError | undefined
+  retryToken: number
+
+  setSpaceConfig(config): void
+  setActiveObject(object): void
+  setDetailVisible(visible): void
+  setSpaceLoadError(error): void
+  retrySpaceLoad(): void
+}
+```
+
+### Exploration state
+
+```ts
+interface CaveExploreState {
+  viewMode: 'first-person' | 'third-person'
+  activeSpaceId: string | undefined
+  connectedSpaces: Record<string, CaveSpace> // primary + preloaded neighbors
+  spaceTransforms: Record<string, Matrix16> // world-space group matrices
+  activeConnector: ConnectorDef | undefined
+  readySpaceIds: Record<string, true>
+  // …setters
+}
+```
+
+> Inside `useFrame` loops and event handlers, read through `useCaveExploreStore().getState()` rather than a selector. `connectedSpaces` changes on every neighbor preload, and a subscription there re-renders the scene graph during loading.
+
+### Action prompts
+
+```ts
+interface ActionDef {
+  id: string
+  label: string
+  shortcut?: string // e.g. 'F', '1'
+  disabled?: boolean // shown but not selectable
+  onAction: () => void
+}
+```
+
+`bubble` style anchors in 3D next to the object (single hint); `panel` is a screen-space list (multi-choice). Shortcuts are handled by one global listener, so components never register their own `keydown`.
+
+---
+
+## Composing your own canvas
+
+If you already own an R3F canvas and physics world, use the `space` layer directly:
+
+```tsx
+import { Canvas } from '@react-three/fiber'
+import { BvhPhysicsWorld } from '@react-three/viverse'
+import { CaveWorldProvider } from '@cavegiant/cave-world-r3f/core'
+import {
+  CaveSpace,
+  configureCaveCanvasDomElement,
+  configureSparkWebGLRenderer,
+  getSparkCanvasDpr,
+  useVisibilityFrameloop
+} from '@cavegiant/cave-world-r3f/space'
+import '@cavegiant/cave-world-r3f/styles.css'
+
+function MyApp({ spaceConfig }) {
+  const frameloop = useVisibilityFrameloop()
+
+  return (
+    <CaveWorldProvider>
+      <Canvas
+        dpr={getSparkCanvasDpr()}
+        frameloop={frameloop}
+        gl={{ antialias: false }}
+        onCreated={({ gl }) => {
+          configureSparkWebGLRenderer(gl)
+          configureCaveCanvasDomElement(gl.domElement)
+        }}
+      >
+        <BvhPhysicsWorld>
+          <CaveSpace space={spaceConfig} revealOnEnter onInitialized={() => {}} />
+        </BvhPhysicsWorld>
+      </Canvas>
+    </CaveWorldProvider>
+  )
+}
+```
+
+`<CaveWorldProvider>` is mandatory. `useVisibilityFrameloop` stops rendering while the page is hidden (GPU drops to zero). `getSparkCanvasDpr` caps backing-store resolution so splat blending cost stays bounded.
+
+---
+
+## Performance guidance
+
+**Scene authoring**
+
+- Give the container a definite width and height; layout thrash forces canvas resizes.
+- Pre-author `baseLayer.colliders`. Deriving a collider from splat geometry at runtime costs roughly a second.
+- Provide `splatLevels` for heavy captures so mobile gets a variant it can actually render.
+- Prefer `.glb` over `.gltf` for models.
+- Only declare a `Collider` component on objects that need physics.
+
+**Integration**
+
+- Keep `localCharacterModel`, `characterControls.movement`, and `boneMap` references stable.
+- Read cross-scene state through `getState()` in handlers and frame loops.
+- Multiplayer renders at most 50 remote characters by default.