@cavegiant/cave-world-r3f 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to `@cavegiant/cave-world-r3f` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-09-17
+
+Initial public release.
+
+### Added
+
+- **`CaveExplore`** — first/third-person walkable tour with physics, character controls, connector travel, and interaction overlays.
+- **`CaveOrbitViewer`** — orbit-camera overview for scene pickers and bird's-eye framing (`camera` / `orbit` / `transformSpace`).
+- **Scene graph** — `CaveSpace` renders splat / model base layers, colliders, boundaries, connectors, and custom objects from JSON.
+- **Gaussian splat pipeline** — spark `SplatMesh` wrapper with retry, stall watchdog, optional entry reveal, and device-aware LOD (`splatLevels`).
+- **Extensibility** — `ObjectRegistry` / `ComponentRegistry` with `registerDefault`, typed `CaveEventBus`, and host `render*` / `on*` props for UI and navigation.
+- **Multiplayer (optional)** — WebSocket sync via `multiplayer` config with **required** `url`; avatar catalog must be supplied (or `BUILTIN_AVATARS` for demos).
+- **Localization** — built-in overlay copy via `messages` (zh-CN default, `messagesEn` export); partial overrides deep-merge.
+- **Styles** — `.cw-*` / `--cw-*` stylesheet, runtime inject by default, also published as `./styles.css`.
+- **Loading** — `createHttpCaveSpaceLoader` with timeout and payload validation; terminal failures surface a retry prompt (`CaveWorldError` codes). `DefaultCaveSpaceLoader` targets the public CaveGiant API for demos.
+- **Imperative control** — `CaveExploreHandle` (`getCharacter`, `getActiveSpaceId`, `teleport`).
+- **Sub-path exports** — `.` / `./core` / `./types` / `./space` / `./explore` / `./styles.css` (ESM-only).
+- **Docs & examples** — README, API / ARCHITECTURE / scene-JSON / multiplayer docs (published in the npm `doc/` folder), and a runnable playground (`npm run examples`) mounting `examples/0N-*.tsx` — including multiplayer and product-skin recipes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CaveGiant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# @cavegiant/cave-world-r3f
+
+Web-based 3D virtual tour SDK. Renders an interactive, walkable 3D scene from a single JSON description — including Gaussian-splat captures, collision, interactive objects, and seamless travel between connected scenes.
+
+**ESM-only.** Consumers must use `import` (not `require`).
+
+## Install
+
+```bash
+npm install @cavegiant/cave-world-r3f
+```
+
+Peer dependencies (all required):
+
+```bash
+npm install react@">=18 <19.3" react-dom@">=18 <19.3" three @react-three/fiber @react-three/drei @react-three/viverse @sparkjsdev/spark@^0.1.10 zustand
+```
+
+> `@react-three/fiber` currently requires React `>=19 <19.3` (or React 18). Do not install React 19.3+ until fiber widens its peer range.
+>
+> `@sparkjsdev/spark` is pinned to `0.1.x` on purpose. Spark 2.x rebuilds its splat accumulator whenever the view changes, which injects frame-time jitter that the character integrator turns into visible stutter while walking. See [`doc/ARCHITECTURE.md`](./doc/ARCHITECTURE.md#spark-version).
+>
+> If you hit `@react-three/timeline` issues with viverse, pin `@react-three/timeline@0.3.9` in the **host** app as well — this package's `overrides` only apply to its own install.
+
+## Quick start
+
+The container needs a definite width and height — the viewer fills it. Omitting
+`caveSpaceLoader` uses `DefaultCaveSpaceLoader` (the public CaveGiant content API).
+
+```tsx
+import { CaveExplore } from '@cavegiant/cave-world-r3f/explore'
+
+export default function App() {
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <CaveExplore spaceId="your-space-id" />
+    </div>
+  )
+}
+```
+
+### Loading scenes from your own backend
+
+```tsx
+import { CaveExplore, createHttpCaveSpaceLoader } from '@cavegiant/cave-world-r3f/explore'
+
+const loader = createHttpCaveSpaceLoader({
+  buildUrl: (spaceId) => `/api/spaces/${spaceId}`,
+  headers: { Authorization: `Bearer ${token}` }
+})
+
+<CaveExplore spaceId={id} caveSpaceLoader={loader} />
+```
+
+`createHttpCaveSpaceLoader` adds a request timeout, non-2xx detection, and payload validation on top of `fetch`, and reports failures as `CaveWorldError` with a stable `code`. Any `(spaceId) => Promise<CaveSpace>` function works too.
+
+## Features
+
+- **JSON-driven** — scene content is fully described by one config file
+- **Gaussian splats** — native 3DGS rendering with device-aware LOD selection
+- **Cross-scene travel** — seamless walk-through and portal teleport between scenes, with neighbor preloading
+- **Extensible objects** — register custom 3D object types through `ObjectRegistry` (unregistered types render nothing; enable `setCaveWorldLogLevel('debug')` to see skips)
+- **Extensible behaviors** — attach reusable components to any object through `ComponentRegistry`
+- **Typed event bus** — `object:click`, `connector:enter`, `detail:open`, `custom:*`, and more
+- **Custom avatars** — third-person GLB/VRM with VRM 1.0 bone mapping
+- **Multiplayer** — optional WebSocket character sync (requires explicit `url` + your avatar catalog)
+- **Replaceable UI** — every built-in overlay has a `render*` prop, and all copy is translatable
+- **Load-failure hardening** — automatic splat retry, stall watchdog, and a retry prompt instead of an infinite spinner
+
+Wrap the viewer (or your own R3F canvas) in a React error boundary if you need host-level recovery from unexpected WebGL/R3F throws — the SDK's load-error overlay covers the hardened splat/config path only.
+
+## Entry points
+
+| Import path                            | Contents                                                                              |
+| -------------------------------------- | ------------------------------------------------------------------------------------- |
+| `@cavegiant/cave-world-r3f`            | Common re-exports from all layers (`CaveSpace` is re-exported as `CaveSpaceRenderer`) |
+| `@cavegiant/cave-world-r3f/types`      | Scene JSON types only — zero runtime                                                  |
+| `@cavegiant/cave-world-r3f/core`       | Event bus, registries, provider, hooks, logger, i18n                                  |
+| `@cavegiant/cave-world-r3f/space`      | Scene rendering components (R3F), including `CaveSpace`                               |
+| `@cavegiant/cave-world-r3f/explore`    | Viewers, overlays, character, multiplayer                                             |
+| `@cavegiant/cave-world-r3f/styles.css` | Default overlay stylesheet                                                            |
+
+## Viewers
+
+| Component         | Use it for                                                           |
+| ----------------- | -------------------------------------------------------------------- |
+| `CaveExplore`     | First/third-person walkable tour with physics and cross-scene travel |
+| `CaveOrbitViewer` | Orbit-camera overview of a single scene (no avatar, no physics)      |
+
+## Styling
+
+The built-in overlays ship a small stylesheet, namespaced under `.cw-*` and themed entirely through `--cw-*` custom properties. It is injected at runtime by default, so nothing is required to get a working UI.
+
+The defaults are declared on `:root`, which means setting the same property on any ancestor of the viewer overrides them.
+
+```css
+/* Re-theme without replacing any component */
+:root {
+  --cw-color-accent: #7c9cff;
+  --cw-color-surface: rgb(20 20 28 / 88%);
+  --cw-radius-md: 4px;
+}
+```
+
+The properties you are most likely to want:
+
+| Property                                                                      | Themes                                                                       |
+| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `--cw-color-accent` / `--cw-color-accent-soft`                                | Primary gold: eyebrow text, key caps, hairlines, hover rules                 |
+| `--cw-color-accent-mint`                                                      | Secondary accent: hover states and the action-panel status dot               |
+| `--cw-color-accent-warm`                                                      | Load-error badge and its primary button                                      |
+| `--cw-color-text` / `--cw-color-text-muted`                                   | Overlay copy                                                                 |
+| `--cw-color-surface` / `--cw-color-surface-solid` / `--cw-color-scrim`        | Panel, dialog, and detail-window backgrounds                                 |
+| `--cw-color-label-surface` / `--cw-color-label-border`                        | In-scene connector tags                                                      |
+| `--cw-panel-fill` / `--cw-panel-rim` / `--cw-panel-clip` / `--cw-panel-grain` | Action-panel HUD decoration (set `--cw-panel-clip: none` for square corners) |
+| `--cw-radius-*`, `--cw-blur*`, `--cw-shadow-*`, `--cw-z-*`                    | Shape, depth, stacking                                                       |
+
+To bundle the CSS yourself instead, import it and turn the injector off:
+
+```tsx
+import '@cavegiant/cave-world-r3f/styles.css'
+
+;<CaveExplore spaceId={id} injectStyles={false} />
+```
+
+## Localization
+
+All built-in copy defaults to Chinese and is overridable per string. `messages` is deep-merged over the default locale, so partial overrides keep everything else intact.
+
+```tsx
+import { messagesEn } from '@cavegiant/cave-world-r3f/core'
+
+<CaveExplore spaceId={id} messages={messagesEn} />
+<CaveExplore spaceId={id} messages={{ loadError: { retry: 'Try again' } }} />
+```
+
+## Diagnostics
+
+The SDK only logs warnings and errors by default, and never writes to the console outside that.
+
+```ts
+import { setCaveWorldLogLevel, setCaveWorldLogSink } from '@cavegiant/cave-world-r3f/core'
+
+setCaveWorldLogLevel('debug') // while integrating (also logs unknown object types)
+setCaveWorldLogLevel('silent') // mute entirely
+setCaveWorldLogSink(myTelemetryAdapter) // forward to your own pipeline
+```
+
+## Documentation
+
+| Document                                                     | Audience                                                          |
+| ------------------------------------------------------------ | ----------------------------------------------------------------- |
+| [doc/API.md](./doc/API.md)                                   | Integration guide, props reference, event list, extension recipes |
+| [doc/ARCHITECTURE.md](./doc/ARCHITECTURE.md)                 | Module design, data flow, dependency rules                        |
+| [doc/scene-json-structure.md](./doc/scene-json-structure.md) | Scene JSON schema                                                 |
+| [doc/multiplayer-protocol.md](./doc/multiplayer-protocol.md) | WebSocket message protocol                                        |
+| [AGENTS.md](./AGENTS.md)                                     | Invariants and recipes for AI coding agents (repo only)           |
+| [examples/](./examples)                                      | Runnable demos — `npm run examples`                               |
+| [CONTRIBUTING.md](./CONTRIBUTING.md)                         | Setup, checks, PR expectations                                    |
+| [SECURITY.md](./SECURITY.md)                                 | Vulnerability reporting                                           |
+
+## Development
+
+This repository is the standalone package. From the package root:
+
+```bash
+npm install
+npm run typecheck
+npm run lint
+npm run format:check
+npm run test
+npm run build
+npm run check              # typecheck + lint + test
+npm run verify:package     # publint + attw
+npm run verify:pack-size   # tarball must stay lean (no examples/)
+npm run examples           # live playground at https://localhost:5173/
+```
+
+### Nested under a host monorepo
+
+If this tree lives inside a larger portal repo, do **not** run `npm install` here (nested `node_modules` duplicates React / Three.js). Use the host's `sdk:*` scripts instead (`npm run sdk:examples`, `sdk:check`, …). See [AGENTS.md](./AGENTS.md).
+
+The playground mounts every `examples/0N-*.tsx` against the public demo scene
+id in [`examples/demo-space.ts`](./examples/demo-space.ts). See
+[`examples/README.md`](./examples/README.md).
+
+## License
+
+MIT

package/dist/core/connector-label/readiness.d.ts

@@ -0,0 +1,11 @@
+import type { CaveSpace, ConnectorDef, ConnectorTarget } from '../../types/index.js';
+/** Whether a connected space has finished base-layer init (splat + colliders). */
+export declare function isSpaceTransferReady(spaceId: string, connectedSpaces: Record<string, CaveSpace>, readySpaceIds: Record<string, true>): boolean;
+export declare function getConnectorPortalTargets(connector: ConnectorDef): ConnectorTarget[];
+export declare function isPortalTargetReady(target: ConnectorTarget, connectedSpaces: Record<string, CaveSpace>, readySpaceIds: Record<string, true>): boolean;
+/** At least one portal destination is loaded and ready to receive the player. */
+export declare function isConnectorPortalNavigable(connector: ConnectorDef, connectedSpaces: Record<string, CaveSpace>, readySpaceIds: Record<string, true>): boolean;
+/** Label / interaction status derived from portal target preload state. */
+export declare function resolveConnectorTransferStatus(connector: ConnectorDef, connectedSpaces: Record<string, CaveSpace>, readySpaceIds: Record<string, true>): 'ready' | 'loading';
+export declare function getReadyPortalTargets(connector: ConnectorDef, connectedSpaces: Record<string, CaveSpace>, readySpaceIds: Record<string, true>): ConnectorTarget[];
+//# sourceMappingURL=readiness.d.ts.map

package/dist/core/connector-label/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../../../core/connector-label/readiness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE3E,kFAAkF;AAClF,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAC1C,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAClC,OAAO,CAET;AAED,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,YAAY,GAAG,eAAe,EAAE,CAEpF;AAED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,eAAe,EACvB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAC1C,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAClC,OAAO,CAET;AAED,iFAAiF;AACjF,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,YAAY,EACvB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAC1C,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAClC,OAAO,CAIT;AAED,2EAA2E;AAC3E,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,YAAY,EACvB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAC1C,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAClC,OAAO,GAAG,SAAS,CAErB;AAED,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,YAAY,EACvB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAC1C,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAClC,eAAe,EAAE,CAInB"}

package/dist/core/connector-label/readiness.js

@@ -0,0 +1,31 @@
+function i(r, t, n) {
+  return !!t[r] && !!n[r];
+}
+function o(r) {
+  return r.connectorInfo.to.filter((t) => t.transitionType === "portal");
+}
+function a(r, t, n) {
+  return i(r.caveWorldId, t, n);
+}
+function u(r, t, n) {
+  return o(r).some(
+    (e) => a(e, t, n)
+  );
+}
+function c(r, t, n) {
+  return u(r, t, n) ? "ready" : "loading";
+}
+function f(r, t, n) {
+  return o(r).filter(
+    (e) => a(e, t, n)
+  );
+}
+export {
+  o as getConnectorPortalTargets,
+  f as getReadyPortalTargets,
+  u as isConnectorPortalNavigable,
+  a as isPortalTargetReady,
+  i as isSpaceTransferReady,
+  c as resolveConnectorTransferStatus
+};
+//# sourceMappingURL=readiness.js.map

package/dist/core/connector-label/readiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.js","sources":["../../../core/connector-label/readiness.ts"],"sourcesContent":["import type { CaveSpace, ConnectorDef, ConnectorTarget } from '../../types'\n\n/** Whether a connected space has finished base-layer init (splat + colliders). */\nexport function isSpaceTransferReady(\n  spaceId: string,\n  connectedSpaces: Record<string, CaveSpace>,\n  readySpaceIds: Record<string, true>\n): boolean {\n  return !!connectedSpaces[spaceId] && !!readySpaceIds[spaceId]\n}\n\nexport function getConnectorPortalTargets(connector: ConnectorDef): ConnectorTarget[] {\n  return connector.connectorInfo.to.filter((t) => t.transitionType === 'portal')\n}\n\nexport function isPortalTargetReady(\n  target: ConnectorTarget,\n  connectedSpaces: Record<string, CaveSpace>,\n  readySpaceIds: Record<string, true>\n): boolean {\n  return isSpaceTransferReady(target.caveWorldId, connectedSpaces, readySpaceIds)\n}\n\n/** At least one portal destination is loaded and ready to receive the player. */\nexport function isConnectorPortalNavigable(\n  connector: ConnectorDef,\n  connectedSpaces: Record<string, CaveSpace>,\n  readySpaceIds: Record<string, true>\n): boolean {\n  return getConnectorPortalTargets(connector).some((target) =>\n    isPortalTargetReady(target, connectedSpaces, readySpaceIds)\n  )\n}\n\n/** Label / interaction status derived from portal target preload state. */\nexport function resolveConnectorTransferStatus(\n  connector: ConnectorDef,\n  connectedSpaces: Record<string, CaveSpace>,\n  readySpaceIds: Record<string, true>\n): 'ready' | 'loading' {\n  return isConnectorPortalNavigable(connector, connectedSpaces, readySpaceIds) ? 'ready' : 'loading'\n}\n\nexport function getReadyPortalTargets(\n  connector: ConnectorDef,\n  connectedSpaces: Record<string, CaveSpace>,\n  readySpaceIds: Record<string, true>\n): ConnectorTarget[] {\n  return getConnectorPortalTargets(connector).filter((target) =>\n    isPortalTargetReady(target, connectedSpaces, readySpaceIds)\n  )\n}\n"],"names":["isSpaceTransferReady","spaceId","connectedSpaces","readySpaceIds","getConnectorPortalTargets","connector","isPortalTargetReady","target","isConnectorPortalNavigable","resolveConnectorTransferStatus","getReadyPortalTargets"],"mappings":"AAGO,SAASA,EACdC,GACAC,GACAC,GACS;AACT,SAAO,CAAC,CAACD,EAAgBD,CAAO,KAAK,CAAC,CAACE,EAAcF,CAAO;AAC9D;AAEO,SAASG,EAA0BC,GAA4C;AACpF,SAAOA,EAAU,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,mBAAmB,QAAQ;AAC/E;AAEO,SAASC,EACdC,GACAL,GACAC,GACS;AACT,SAAOH,EAAqBO,EAAO,aAAaL,GAAiBC,CAAa;AAChF;AAGO,SAASK,EACdH,GACAH,GACAC,GACS;AACT,SAAOC,EAA0BC,CAAS,EAAE;AAAA,IAAK,CAACE,MAChDD,EAAoBC,GAAQL,GAAiBC,CAAa;AAAA,EAAA;AAE9D;AAGO,SAASM,EACdJ,GACAH,GACAC,GACqB;AACrB,SAAOK,EAA2BH,GAAWH,GAAiBC,CAAa,IAAI,UAAU;AAC3F;AAEO,SAASO,EACdL,GACAH,GACAC,GACmB;AACnB,SAAOC,EAA0BC,CAAS,EAAE;AAAA,IAAO,CAACE,MAClDD,EAAoBC,GAAQL,GAAiBC,CAAa;AAAA,EAAA;AAE9D;"}

package/dist/core/connector-label/types.d.ts

@@ -0,0 +1,64 @@
+import type { ComponentType } from 'react';
+import type { CaveSpace, ConnectorDef, ConnectorTarget, Vector3 } from '../../types/index.js';
+/**
+ * Fallback label text when no target metadata is available yet.
+ *
+ * @deprecated Prefer `messages.connector.fallbackLabel`, which is what the
+ * built-in label host passes to {@link resolveConnectorLabel}.
+ */
+export declare const FALLBACK_LABEL_TEXT = "\u524D\u65B9\u573A\u666F";
+export interface ResolvedConnectorLabel {
+    variant: string;
+    text: string;
+    icon?: string;
+    thumbnail?: string;
+    anchorOffset: Vector3;
+    visibility: {
+        maxDistance: number;
+        minDistance: number;
+        fadeRange: number;
+    };
+    custom?: Record<string, unknown>;
+    /** Whether clicking the label triggers portal navigation. Default true. */
+    clickable: boolean;
+}
+export interface ConnectorLabelRendererProps {
+    connector: ConnectorDef;
+    label: ResolvedConnectorLabel;
+    targets: Array<{
+        target: ConnectorTarget;
+        space: CaveSpace | undefined;
+    }>;
+    distance: number;
+    isPlayerInside: boolean;
+    /** 0–1 opacity from distance fade + inside-state gating. */
+    opacity: number;
+    /** 'full' badge with text, 'compact' icon-only, 'hidden' when fully faded. */
+    displayMode: 'full' | 'compact' | 'hidden';
+    /** Resolved from JSON; default true. When false, `onClick` is omitted. */
+    clickable: boolean;
+    /** Triggers the same portal navigation as the in-zone action panel. */
+    onClick?: () => void;
+    /** `loading` while target scene base layer is still preloading. */
+    transferStatus: 'ready' | 'loading';
+}
+export type ConnectorLabelRenderer = ComponentType<ConnectorLabelRendererProps>;
+export type ConnectorLabelMode = 'auto' | 'off';
+export declare function shouldShowConnectorLabel(connector: ConnectorDef, connectorLabelDefault: ConnectorLabelMode): boolean;
+/**
+ * Flatten a connector's label config into concrete render values.
+ *
+ * Text falls back through `label.text` → first portal target's
+ * `metadata.name` → `fallbackText`, so a `caveWorldId` is never shown to users.
+ */
+export declare function resolveConnectorLabel(connector: ConnectorDef, connectedSpaces: Record<string, CaveSpace>, fallbackText?: string): ResolvedConnectorLabel;
+export declare function getPortalTargetsWithSpaces(connector: ConnectorDef, connectedSpaces: Record<string, CaveSpace>): Array<{
+    target: ConnectorTarget;
+    space: CaveSpace | undefined;
+}>;
+/** Compute label opacity and display mode from camera distance. */
+export declare function computeLabelVisibility(distance: number, label: ResolvedConnectorLabel, isPlayerInside: boolean): {
+    opacity: number;
+    displayMode: 'full' | 'compact' | 'hidden';
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/core/connector-label/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../core/connector-label/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAC1C,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EAEZ,eAAe,EACf,OAAO,EACR,MAAM,aAAa,CAAA;AAEpB;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,6BAAS,CAAA;AAEzC,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,OAAO,CAAA;IACrB,UAAU,EAAE;QACV,WAAW,EAAE,MAAM,CAAA;QACnB,WAAW,EAAE,MAAM,CAAA;QACnB,SAAS,EAAE,MAAM,CAAA;KAClB,CAAA;IACD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,2EAA2E;IAC3E,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,YAAY,CAAA;IACvB,KAAK,EAAE,sBAAsB,CAAA;IAC7B,OAAO,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,eAAe,CAAC;QAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAA;KAAE,CAAC,CAAA;IACzE,QAAQ,EAAE,MAAM,CAAA;IAChB,cAAc,EAAE,OAAO,CAAA;IACvB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAA;IAC1C,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAA;IAClB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,mEAAmE;IACnE,cAAc,EAAE,OAAO,GAAG,SAAS,CAAA;CACpC;AAED,MAAM,MAAM,sBAAsB,GAAG,aAAa,CAAC,2BAA2B,CAAC,CAAA;AAE/E,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,KAAK,CAAA;AAE/C,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,YAAY,EACvB,qBAAqB,EAAE,kBAAkB,GACxC,OAAO,CAMT;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,YAAY,EACvB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAC1C,YAAY,GAAE,MAA4B,GACzC,sBAAsB,CAyBxB;AAED,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,YAAY,EACvB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GACzC,KAAK,CAAC;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAA;CAAE,CAAC,CAOlE;AAED,mEAAmE;AACnE,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,sBAAsB,EAC7B,cAAc,EAAE,OAAO,GACtB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAA;CAAE,CA0BjE"}

package/dist/core/connector-label/types.js

@@ -0,0 +1,47 @@
+const f = "前方场景";
+function u(t, o) {
+  return !t.connectorInfo.to.some((a) => a.transitionType === "portal") || t.label === !1 ? !1 : t.label !== void 0 ? !0 : o === "auto";
+}
+function p(t, o, e = f) {
+  const a = t.label === !1 ? void 0 : t.label, n = t.connectorInfo.to.filter((c) => c.transitionType === "portal")[0], i = n ? o[n.caveWorldId] : void 0, s = [0, t.transform.scale[1] / 4 + 0.2, 0];
+  return {
+    variant: a?.variant ?? "beacon",
+    text: a?.text ?? i?.metadata?.name ?? e,
+    icon: a?.icon,
+    thumbnail: a?.thumbnail ?? i?.metadata?.thumbnail,
+    anchorOffset: a?.anchorOffset ?? s,
+    visibility: {
+      maxDistance: a?.visibility?.maxDistance ?? 30,
+      minDistance: a?.visibility?.minDistance ?? 5,
+      fadeRange: a?.visibility?.fadeRange ?? 5
+    },
+    custom: a?.custom,
+    clickable: a?.clickable !== !1
+  };
+}
+function d(t, o) {
+  return t.connectorInfo.to.filter((e) => e.transitionType === "portal").map((e) => ({
+    target: e,
+    space: o[e.caveWorldId]
+  }));
+}
+function m(t, o, e) {
+  if (e)
+    return { opacity: 0, displayMode: "hidden" };
+  const { maxDistance: a, minDistance: l, fadeRange: n } = o.visibility;
+  if (t > a + n || t < l - n)
+    return { opacity: 0, displayMode: "hidden" };
+  let i = 1;
+  if (t > a ? i = 1 - (t - a) / n : t < l && (i = 1 - (l - t) / n), i = Math.max(0, Math.min(1, i)), i <= 0)
+    return { opacity: 0, displayMode: "hidden" };
+  const r = Math.max(a * 0.65, l + 2), s = t > r ? "compact" : "full";
+  return { opacity: i, displayMode: s };
+}
+export {
+  f as FALLBACK_LABEL_TEXT,
+  m as computeLabelVisibility,
+  d as getPortalTargetsWithSpaces,
+  p as resolveConnectorLabel,
+  u as shouldShowConnectorLabel
+};
+//# sourceMappingURL=types.js.map

package/dist/core/connector-label/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sources":["../../../core/connector-label/types.ts"],"sourcesContent":["import type { ComponentType } from 'react'\nimport type {\n  CaveSpace,\n  ConnectorDef,\n  ConnectorLabelDef,\n  ConnectorTarget,\n  Vector3\n} from '../../types'\n\n/**\n * Fallback label text when no target metadata is available yet.\n *\n * @deprecated Prefer `messages.connector.fallbackLabel`, which is what the\n * built-in label host passes to {@link resolveConnectorLabel}.\n */\nexport const FALLBACK_LABEL_TEXT = '前方场景'\n\nexport interface ResolvedConnectorLabel {\n  variant: string\n  text: string\n  icon?: string\n  thumbnail?: string\n  anchorOffset: Vector3\n  visibility: {\n    maxDistance: number\n    minDistance: number\n    fadeRange: number\n  }\n  custom?: Record<string, unknown>\n  /** Whether clicking the label triggers portal navigation. Default true. */\n  clickable: boolean\n}\n\nexport interface ConnectorLabelRendererProps {\n  connector: ConnectorDef\n  label: ResolvedConnectorLabel\n  targets: Array<{ target: ConnectorTarget; space: CaveSpace | undefined }>\n  distance: number\n  isPlayerInside: boolean\n  /** 0–1 opacity from distance fade + inside-state gating. */\n  opacity: number\n  /** 'full' badge with text, 'compact' icon-only, 'hidden' when fully faded. */\n  displayMode: 'full' | 'compact' | 'hidden'\n  /** Resolved from JSON; default true. When false, `onClick` is omitted. */\n  clickable: boolean\n  /** Triggers the same portal navigation as the in-zone action panel. */\n  onClick?: () => void\n  /** `loading` while target scene base layer is still preloading. */\n  transferStatus: 'ready' | 'loading'\n}\n\nexport type ConnectorLabelRenderer = ComponentType<ConnectorLabelRendererProps>\n\nexport type ConnectorLabelMode = 'auto' | 'off'\n\nexport function shouldShowConnectorLabel(\n  connector: ConnectorDef,\n  connectorLabelDefault: ConnectorLabelMode\n): boolean {\n  const hasPortal = connector.connectorInfo.to.some((t) => t.transitionType === 'portal')\n  if (!hasPortal) return false\n  if (connector.label === false) return false\n  if (connector.label !== undefined) return true\n  return connectorLabelDefault === 'auto'\n}\n\n/**\n * Flatten a connector's label config into concrete render values.\n *\n * Text falls back through `label.text` → first portal target's\n * `metadata.name` → `fallbackText`, so a `caveWorldId` is never shown to users.\n */\nexport function resolveConnectorLabel(\n  connector: ConnectorDef,\n  connectedSpaces: Record<string, CaveSpace>,\n  fallbackText: string = FALLBACK_LABEL_TEXT\n): ResolvedConnectorLabel {\n  const labelDef: ConnectorLabelDef | undefined =\n    connector.label === false ? undefined : connector.label\n\n  const portalTargets = connector.connectorInfo.to.filter((t) => t.transitionType === 'portal')\n  const firstTarget = portalTargets[0]\n  const space = firstTarget ? connectedSpaces[firstTarget.caveWorldId] : undefined\n\n  const scaleY = connector.transform.scale[1]\n  const defaultAnchor: Vector3 = [0, scaleY / 4 + 0.2, 0]\n\n  return {\n    variant: labelDef?.variant ?? 'beacon',\n    text: labelDef?.text ?? space?.metadata?.name ?? fallbackText,\n    icon: labelDef?.icon,\n    thumbnail: labelDef?.thumbnail ?? space?.metadata?.thumbnail,\n    anchorOffset: labelDef?.anchorOffset ?? defaultAnchor,\n    visibility: {\n      maxDistance: labelDef?.visibility?.maxDistance ?? 30,\n      minDistance: labelDef?.visibility?.minDistance ?? 5,\n      fadeRange: labelDef?.visibility?.fadeRange ?? 5\n    },\n    custom: labelDef?.custom,\n    clickable: labelDef?.clickable !== false\n  }\n}\n\nexport function getPortalTargetsWithSpaces(\n  connector: ConnectorDef,\n  connectedSpaces: Record<string, CaveSpace>\n): Array<{ target: ConnectorTarget; space: CaveSpace | undefined }> {\n  return connector.connectorInfo.to\n    .filter((t) => t.transitionType === 'portal')\n    .map((target) => ({\n      target,\n      space: connectedSpaces[target.caveWorldId]\n    }))\n}\n\n/** Compute label opacity and display mode from camera distance. */\nexport function computeLabelVisibility(\n  distance: number,\n  label: ResolvedConnectorLabel,\n  isPlayerInside: boolean\n): { opacity: number; displayMode: 'full' | 'compact' | 'hidden' } {\n  if (isPlayerInside) {\n    return { opacity: 0, displayMode: 'hidden' }\n  }\n\n  const { maxDistance, minDistance, fadeRange } = label.visibility\n\n  if (distance > maxDistance + fadeRange || distance < minDistance - fadeRange) {\n    return { opacity: 0, displayMode: 'hidden' }\n  }\n\n  let opacity = 1\n  if (distance > maxDistance) {\n    opacity = 1 - (distance - maxDistance) / fadeRange\n  } else if (distance < minDistance) {\n    opacity = 1 - (minDistance - distance) / fadeRange\n  }\n  opacity = Math.max(0, Math.min(1, opacity))\n\n  if (opacity <= 0) {\n    return { opacity: 0, displayMode: 'hidden' }\n  }\n\n  const compactThreshold = Math.max(maxDistance * 0.65, minDistance + 2)\n  const displayMode = distance > compactThreshold ? 'compact' : 'full'\n  return { opacity, displayMode }\n}\n"],"names":["FALLBACK_LABEL_TEXT","shouldShowConnectorLabel","connector","connectorLabelDefault","t","resolveConnectorLabel","connectedSpaces","fallbackText","labelDef","firstTarget","space","defaultAnchor","getPortalTargetsWithSpaces","target","computeLabelVisibility","distance","label","isPlayerInside","maxDistance","minDistance","fadeRange","opacity","compactThreshold","displayMode"],"mappings":"AAeO,MAAMA,IAAsB;AAwC5B,SAASC,EACdC,GACAC,GACS;AAGT,SADI,CADcD,EAAU,cAAc,GAAG,KAAK,CAACE,MAAMA,EAAE,mBAAmB,QAAQ,KAElFF,EAAU,UAAU,KAAc,KAClCA,EAAU,UAAU,SAAkB,KACnCC,MAA0B;AACnC;AAQO,SAASE,EACdH,GACAI,GACAC,IAAuBP,GACC;AACxB,QAAMQ,IACJN,EAAU,UAAU,KAAQ,SAAYA,EAAU,OAG9CO,IADgBP,EAAU,cAAc,GAAG,OAAO,CAACE,MAAMA,EAAE,mBAAmB,QAAQ,EAC1D,CAAC,GAC7BM,IAAQD,IAAcH,EAAgBG,EAAY,WAAW,IAAI,QAGjEE,IAAyB,CAAC,GADjBT,EAAU,UAAU,MAAM,CAAC,IACE,IAAI,KAAK,CAAC;AAEtD,SAAO;AAAA,IACL,SAASM,GAAU,WAAW;AAAA,IAC9B,MAAMA,GAAU,QAAQE,GAAO,UAAU,QAAQH;AAAA,IACjD,MAAMC,GAAU;AAAA,IAChB,WAAWA,GAAU,aAAaE,GAAO,UAAU;AAAA,IACnD,cAAcF,GAAU,gBAAgBG;AAAA,IACxC,YAAY;AAAA,MACV,aAAaH,GAAU,YAAY,eAAe;AAAA,MAClD,aAAaA,GAAU,YAAY,eAAe;AAAA,MAClD,WAAWA,GAAU,YAAY,aAAa;AAAA,IAAA;AAAA,IAEhD,QAAQA,GAAU;AAAA,IAClB,WAAWA,GAAU,cAAc;AAAA,EAAA;AAEvC;AAEO,SAASI,EACdV,GACAI,GACkE;AAClE,SAAOJ,EAAU,cAAc,GAC5B,OAAO,CAACE,MAAMA,EAAE,mBAAmB,QAAQ,EAC3C,IAAI,CAACS,OAAY;AAAA,IAChB,QAAAA;AAAA,IACA,OAAOP,EAAgBO,EAAO,WAAW;AAAA,EAAA,EACzC;AACN;AAGO,SAASC,EACdC,GACAC,GACAC,GACiE;AACjE,MAAIA;AACF,WAAO,EAAE,SAAS,GAAG,aAAa,SAAA;AAGpC,QAAM,EAAE,aAAAC,GAAa,aAAAC,GAAa,WAAAC,EAAA,IAAcJ,EAAM;AAEtD,MAAID,IAAWG,IAAcE,KAAaL,IAAWI,IAAcC;AACjE,WAAO,EAAE,SAAS,GAAG,aAAa,SAAA;AAGpC,MAAIC,IAAU;AAQd,MAPIN,IAAWG,IACbG,IAAU,KAAKN,IAAWG,KAAeE,IAChCL,IAAWI,MACpBE,IAAU,KAAKF,IAAcJ,KAAYK,IAE3CC,IAAU,KAAK,IAAI,GAAG,KAAK,IAAI,GAAGA,CAAO,CAAC,GAEtCA,KAAW;AACb,WAAO,EAAE,SAAS,GAAG,aAAa,SAAA;AAGpC,QAAMC,IAAmB,KAAK,IAAIJ,IAAc,MAAMC,IAAc,CAAC,GAC/DI,IAAcR,IAAWO,IAAmB,YAAY;AAC9D,SAAO,EAAE,SAAAD,GAAS,aAAAE,EAAA;AACpB;"}

package/dist/core/context/cave-world-context.d.ts

@@ -0,0 +1,96 @@
+import { type ReactNode } from 'react';
+import { type Mutate, type StoreApi } from 'zustand';
+import type { CaveSpace, CustomObject } from '../../types/index.js';
+import { CaveEventBus } from '../events/event-bus.js';
+import { type CaveWorldMessages, type PartialCaveWorldMessages } from '../i18n/messages.js';
+import { ObjectRegistry } from '../registry/object-registry.js';
+import { ComponentRegistry } from '../registry/component-registry.js';
+import type { ConnectorLabelMode, ConnectorLabelRenderer } from '../connector-label/types.js';
+export interface CaveWorldInteraction {
+    activeObject: CustomObject | undefined;
+    detailVisible: boolean;
+}
+/**
+ * A terminal (retries-exhausted) failure to load a space's assets. Surfaced so
+ * a built-in / custom overlay can prompt the user instead of the page hanging
+ * on an infinite loading screen.
+ *
+ * - `stage: 'config'` — the space JSON (`caveSpaceLoader`) failed.
+ * - `stage: 'splat'`  — the base-layer 3DGS/splat asset failed to download.
+ */
+export interface SpaceLoadError {
+    stage: 'config' | 'splat';
+    /** Asset URL that failed (present for the splat stage). */
+    url?: string;
+    /** Space id that failed, when known. */
+    spaceId?: string;
+    error: unknown;
+}
+export interface CaveWorldState extends CaveWorldInteraction {
+    spaceConfig: CaveSpace | undefined;
+    /** Terminal space/splat load failure, or `undefined` when healthy. */
+    spaceLoadError: SpaceLoadError | undefined;
+    /**
+     * Monotonic counter bumped by {@link CaveWorldState.retrySpaceLoad}. Load
+     * effects and the robust splat mesh include it in their dependencies so a
+     * user-triggered retry forces a fresh config fetch / splat re-download.
+     */
+    retryToken: number;
+    setSpaceConfig: (config: CaveSpace | undefined) => void;
+    setActiveObject: (obj: CustomObject | undefined) => void;
+    setDetailVisible: (visible: boolean) => void;
+    setSpaceLoadError: (error: SpaceLoadError | undefined) => void;
+    /** Clear the error and bump {@link CaveWorldState.retryToken} to retry. */
+    retrySpaceLoad: () => void;
+}
+/**
+ * Store handle including the `subscribeWithSelector` overload, so callers can
+ * watch one field instead of re-running on every write.
+ */
+export type CaveWorldStoreApi = Mutate<StoreApi<CaveWorldState>, [
+    ['zustand/subscribeWithSelector', never]
+]>;
+export interface CaveWorldServices {
+    eventBus: CaveEventBus;
+    objectRegistry: ObjectRegistry;
+    componentRegistry: ComponentRegistry;
+    store: CaveWorldStoreApi;
+    /** Resolved UI copy for the built-in overlays. */
+    messages: CaveWorldMessages;
+    connectorLabel: ConnectorLabelMode;
+    connectorLabelRenderer?: ConnectorLabelRenderer;
+}
+export declare function createCaveWorldStore(): CaveWorldStoreApi;
+export interface CaveWorldProviderProps {
+    children: ReactNode;
+    /** Reuse an external bus to observe SDK events from outside the tree. */
+    eventBus?: CaveEventBus;
+    /** Pre-populated registry of object renderers. */
+    objectRegistry?: ObjectRegistry;
+    /** Pre-populated registry of behavior components. */
+    componentRegistry?: ComponentRegistry;
+    /** Partial copy overrides, deep-merged over the default locale. */
+    messages?: PartialCaveWorldMessages;
+    /** Global default for connector wayfinding labels. @default 'auto' */
+    connectorLabel?: ConnectorLabelMode;
+    connectorLabelRenderer?: ConnectorLabelRenderer;
+}
+/**
+ * Provides the per-instance services every SDK hook and component reads:
+ * event bus, registries, world store, and resolved copy.
+ *
+ * `CaveExplore` / `CaveOrbitViewer` mount this for you. Mount it yourself only
+ * when composing `CaveSpace` into your own canvas.
+ */
+export declare function CaveWorldProvider({ children, eventBus: externalEventBus, objectRegistry: externalObjectRegistry, componentRegistry: externalComponentRegistry, messages, connectorLabel, connectorLabelRenderer }: CaveWorldProviderProps): import("react").JSX.Element;
+export declare function useCaveWorld(): CaveWorldServices;
+/** Subscribe to a slice of the per-instance world store. */
+export declare function useCaveWorldStore<T>(selector: (state: CaveWorldState) => T): T;
+/** Imperative handle to the world store (`getState` / `setState` / `subscribe`). */
+export declare function useCaveWorldStoreApi(): CaveWorldStoreApi;
+export declare function useCaveEventBus(): CaveEventBus;
+export declare function useObjectRegistry(): ObjectRegistry;
+export declare function useComponentRegistry(): ComponentRegistry;
+/** Resolved UI copy for the current provider. */
+export declare function useCaveWorldMessages(): CaveWorldMessages;
+//# sourceMappingURL=cave-world-context.d.ts.map

package/dist/core/context/cave-world-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cave-world-context.d.ts","sourceRoot":"","sources":["../../../core/context/cave-world-context.tsx"],"names":[],"mappings":"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"}

package/dist/core/context/cave-world-context.js

@@ -0,0 +1,100 @@
+import { jsx as g } from "react/jsx-runtime";
+import { useState as t, useMemo as l, useContext as b, createContext as y } from "react";
+import { create as R, useStore as S } from "zustand";
+import { subscribeWithSelector as W } from "zustand/middleware";
+import { CaveEventBus as j } from "../events/event-bus.js";
+import { CaveWorldError as E } from "../errors.js";
+import { resolveMessages as k } from "../i18n/messages.js";
+import { ObjectRegistry as w } from "../registry/object-registry.js";
+import { ComponentRegistry as O } from "../registry/component-registry.js";
+const p = y(null);
+function B() {
+  return R(
+    W((o) => ({
+      spaceConfig: void 0,
+      activeObject: void 0,
+      detailVisible: !1,
+      spaceLoadError: void 0,
+      retryToken: 0,
+      setSpaceConfig: (e) => o({ spaceConfig: e }),
+      setActiveObject: (e) => o({ activeObject: e }),
+      setDetailVisible: (e) => o({ detailVisible: e }),
+      setSpaceLoadError: (e) => o({ spaceLoadError: e }),
+      retrySpaceLoad: () => o((e) => ({ spaceLoadError: void 0, retryToken: e.retryToken + 1 }))
+    }))
+  );
+}
+function D({
+  children: o,
+  eventBus: e,
+  objectRegistry: s,
+  componentRegistry: n,
+  messages: i,
+  connectorLabel: c = "auto",
+  connectorLabelRenderer: a
+}) {
+  const [u] = t(B), [v] = t(() => new j()), [f] = t(() => new w()), [m] = t(() => new O()), d = l(() => k(i), [i]), C = l(
+    () => ({
+      eventBus: e ?? v,
+      objectRegistry: s ?? f,
+      componentRegistry: n ?? m,
+      store: u,
+      messages: d,
+      connectorLabel: c,
+      connectorLabelRenderer: a
+    }),
+    [
+      e,
+      s,
+      n,
+      v,
+      f,
+      m,
+      u,
+      d,
+      c,
+      a
+    ]
+  );
+  return /* @__PURE__ */ g(p.Provider, { value: C, children: o });
+}
+function r() {
+  const o = b(p);
+  if (!o)
+    throw new E(
+      "MISSING_PROVIDER",
+      "useCaveWorld must be used within a <CaveWorldProvider>."
+    );
+  return o;
+}
+function G(o) {
+  const { store: e } = r();
+  return S(e, o);
+}
+function N() {
+  return r().store;
+}
+function _() {
+  return r().eventBus;
+}
+function q() {
+  return r().objectRegistry;
+}
+function z() {
+  return r().componentRegistry;
+}
+function F() {
+  return r().messages;
+}
+export {
+  D as CaveWorldProvider,
+  B as createCaveWorldStore,
+  _ as useCaveEventBus,
+  r as useCaveWorld,
+  F as useCaveWorldMessages,
+  G as useCaveWorldStore,
+  N as useCaveWorldStoreApi,
+  z as useComponentRegistry,
+  q as useObjectRegistry
+};
+//# sourceMappingURL=cave-world-context.js.map