@cavegiant/cave-world-r3f 1.0.0

package/dist/core/index.js

@@ -0,0 +1,47 @@
+import { CaveEventBus as o } from "./events/event-bus.js";
+import { ObjectRegistry as s } from "./registry/object-registry.js";
+import { ComponentRegistry as l } from "./registry/component-registry.js";
+import { CaveWorldProvider as n, createCaveWorldStore as v, useCaveEventBus as g, useCaveWorld as i, useCaveWorldMessages as m, useCaveWorldStore as p, useCaveWorldStoreApi as d, useComponentRegistry as f, useObjectRegistry as u } from "./context/cave-world-context.js";
+import { useCaveEvent as L } from "./hooks/use-cave-event.js";
+import { createLogger as S, setCaveWorldLogLevel as W, setCaveWorldLogSink as x } from "./logging/logger.js";
+import { CaveWorldError as y, isCaveWorldError as b } from "./errors.js";
+import { DEFAULT_MESSAGES as A, formatMessage as P, en as h, zhCN as B, resolveMessages as M } from "./i18n/messages.js";
+import { FALLBACK_LABEL_TEXT as _, computeLabelVisibility as j, getPortalTargetsWithSpaces as F, resolveConnectorLabel as O, shouldShowConnectorLabel as k } from "./connector-label/types.js";
+import { getConnectorPortalTargets as z, getReadyPortalTargets as D, isConnectorPortalNavigable as G, isPortalTargetReady as K, isSpaceTransferReady as U, resolveConnectorTransferStatus as V } from "./connector-label/readiness.js";
+export {
+  o as CaveEventBus,
+  y as CaveWorldError,
+  n as CaveWorldProvider,
+  l as ComponentRegistry,
+  A as DEFAULT_MESSAGES,
+  _ as FALLBACK_LABEL_TEXT,
+  s as ObjectRegistry,
+  j as computeLabelVisibility,
+  v as createCaveWorldStore,
+  S as createLogger,
+  P as formatMessage,
+  z as getConnectorPortalTargets,
+  F as getPortalTargetsWithSpaces,
+  D as getReadyPortalTargets,
+  b as isCaveWorldError,
+  G as isConnectorPortalNavigable,
+  K as isPortalTargetReady,
+  U as isSpaceTransferReady,
+  h as messagesEn,
+  B as messagesZhCN,
+  O as resolveConnectorLabel,
+  V as resolveConnectorTransferStatus,
+  M as resolveMessages,
+  W as setCaveWorldLogLevel,
+  x as setCaveWorldLogSink,
+  k as shouldShowConnectorLabel,
+  L as useCaveEvent,
+  g as useCaveEventBus,
+  i as useCaveWorld,
+  m as useCaveWorldMessages,
+  p as useCaveWorldStore,
+  d as useCaveWorldStoreApi,
+  f as useComponentRegistry,
+  u as useObjectRegistry
+};
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;"}

package/dist/core/logging/logger.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Minimal leveled logger used by every SDK module instead of raw `console.*`.
+ *
+ * A library embedded in someone else's app must not decide how noisy their
+ * console is, so the default level only surfaces warnings and errors. Hosts can
+ * raise it for debugging or silence it entirely, and can replace the sink to
+ * forward SDK diagnostics into their own telemetry.
+ */
+export type CaveWorldLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+export interface CaveWorldLogSink {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+export interface CaveWorldLogger extends CaveWorldLogSink {
+    /** Derive a nested logger, e.g. `createLogger('space').child('splat')`. */
+    child(scope: string): CaveWorldLogger;
+}
+/**
+ * Set the global SDK log level. Defaults to `'warn'`; use `'debug'` while
+ * integrating and `'silent'` to mute the SDK entirely.
+ */
+export declare function setCaveWorldLogLevel(level: CaveWorldLogLevel): void;
+/** Route SDK diagnostics somewhere other than `console` (e.g. Sentry). */
+export declare function setCaveWorldLogSink(sink: CaveWorldLogSink | undefined): void;
+/** Create a scoped logger. Messages are prefixed with `[cave-world:<scope>]`. */
+export declare function createLogger(scope: string): CaveWorldLogger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/core/logging/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../core/logging/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE9E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC/B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC9B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC9B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CAChC;AAED,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,2EAA2E;IAC3E,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAAA;CACtC;AAsBD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAEnE;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,GAAG,IAAI,CAE5E;AAMD,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAkB3D"}

package/dist/core/logging/logger.js

@@ -0,0 +1,47 @@
+const t = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40
+}, u = Number.POSITIVE_INFINITY;
+let c = t.warn;
+const f = {
+  debug: (...r) => console.debug(...r),
+  info: (...r) => console.info(...r),
+  warn: (...r) => console.warn(...r),
+  error: (...r) => console.error(...r)
+};
+let e = f;
+function l(r) {
+  c = r === "silent" ? u : t[r];
+}
+function d(r) {
+  e = r ?? f;
+}
+function i(r) {
+  return t[r] >= c;
+}
+function a(r) {
+  const o = `[cave-world:${r}]`;
+  return {
+    debug: (...n) => {
+      i("debug") && e.debug(o, ...n);
+    },
+    info: (...n) => {
+      i("info") && e.info(o, ...n);
+    },
+    warn: (...n) => {
+      i("warn") && e.warn(o, ...n);
+    },
+    error: (...n) => {
+      i("error") && e.error(o, ...n);
+    },
+    child: (n) => a(`${r}:${n}`)
+  };
+}
+export {
+  a as createLogger,
+  l as setCaveWorldLogLevel,
+  d as setCaveWorldLogSink
+};
+//# sourceMappingURL=logger.js.map

package/dist/core/logging/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sources":["../../../core/logging/logger.ts"],"sourcesContent":["/**\n * Minimal leveled logger used by every SDK module instead of raw `console.*`.\n *\n * A library embedded in someone else's app must not decide how noisy their\n * console is, so the default level only surfaces warnings and errors. Hosts can\n * raise it for debugging or silence it entirely, and can replace the sink to\n * forward SDK diagnostics into their own telemetry.\n */\n\nexport type CaveWorldLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent'\n\nexport interface CaveWorldLogSink {\n  debug(...args: unknown[]): void\n  info(...args: unknown[]): void\n  warn(...args: unknown[]): void\n  error(...args: unknown[]): void\n}\n\nexport interface CaveWorldLogger extends CaveWorldLogSink {\n  /** Derive a nested logger, e.g. `createLogger('space').child('splat')`. */\n  child(scope: string): CaveWorldLogger\n}\n\nconst LEVEL_RANK: Record<Exclude<CaveWorldLogLevel, 'silent'>, number> = {\n  debug: 10,\n  info: 20,\n  warn: 30,\n  error: 40\n}\n\nconst SILENT_RANK = Number.POSITIVE_INFINITY\n\nlet currentRank: number = LEVEL_RANK.warn\n\nconst consoleSink: CaveWorldLogSink = {\n  debug: (...args) => console.debug(...args),\n  info: (...args) => console.info(...args),\n  warn: (...args) => console.warn(...args),\n  error: (...args) => console.error(...args)\n}\n\nlet currentSink: CaveWorldLogSink = consoleSink\n\n/**\n * Set the global SDK log level. Defaults to `'warn'`; use `'debug'` while\n * integrating and `'silent'` to mute the SDK entirely.\n */\nexport function setCaveWorldLogLevel(level: CaveWorldLogLevel): void {\n  currentRank = level === 'silent' ? SILENT_RANK : LEVEL_RANK[level]\n}\n\n/** Route SDK diagnostics somewhere other than `console` (e.g. Sentry). */\nexport function setCaveWorldLogSink(sink: CaveWorldLogSink | undefined): void {\n  currentSink = sink ?? consoleSink\n}\n\nfunction enabled(level: Exclude<CaveWorldLogLevel, 'silent'>): boolean {\n  return LEVEL_RANK[level] >= currentRank\n}\n\n/** Create a scoped logger. Messages are prefixed with `[cave-world:<scope>]`. */\nexport function createLogger(scope: string): CaveWorldLogger {\n  const prefix = `[cave-world:${scope}]`\n\n  return {\n    debug: (...args) => {\n      if (enabled('debug')) currentSink.debug(prefix, ...args)\n    },\n    info: (...args) => {\n      if (enabled('info')) currentSink.info(prefix, ...args)\n    },\n    warn: (...args) => {\n      if (enabled('warn')) currentSink.warn(prefix, ...args)\n    },\n    error: (...args) => {\n      if (enabled('error')) currentSink.error(prefix, ...args)\n    },\n    child: (childScope) => createLogger(`${scope}:${childScope}`)\n  }\n}\n"],"names":["LEVEL_RANK","SILENT_RANK","currentRank","consoleSink","args","currentSink","setCaveWorldLogLevel","level","setCaveWorldLogSink","sink","enabled","createLogger","scope","prefix","childScope"],"mappings":"AAuBA,MAAMA,IAAmE;AAAA,EACvE,OAAO;AAAA,EACP,MAAM;AAAA,EACN,MAAM;AAAA,EACN,OAAO;AACT,GAEMC,IAAc,OAAO;AAE3B,IAAIC,IAAsBF,EAAW;AAErC,MAAMG,IAAgC;AAAA,EACpC,OAAO,IAAIC,MAAS,QAAQ,MAAM,GAAGA,CAAI;AAAA,EACzC,MAAM,IAAIA,MAAS,QAAQ,KAAK,GAAGA,CAAI;AAAA,EACvC,MAAM,IAAIA,MAAS,QAAQ,KAAK,GAAGA,CAAI;AAAA,EACvC,OAAO,IAAIA,MAAS,QAAQ,MAAM,GAAGA,CAAI;AAC3C;AAEA,IAAIC,IAAgCF;AAM7B,SAASG,EAAqBC,GAAgC;AACnE,EAAAL,IAAcK,MAAU,WAAWN,IAAcD,EAAWO,CAAK;AACnE;AAGO,SAASC,EAAoBC,GAA0C;AAC5E,EAAAJ,IAAcI,KAAQN;AACxB;AAEA,SAASO,EAAQH,GAAsD;AACrE,SAAOP,EAAWO,CAAK,KAAKL;AAC9B;AAGO,SAASS,EAAaC,GAAgC;AAC3D,QAAMC,IAAS,eAAeD,CAAK;AAEnC,SAAO;AAAA,IACL,OAAO,IAAIR,MAAS;AAClB,MAAIM,EAAQ,OAAO,OAAe,MAAMG,GAAQ,GAAGT,CAAI;AAAA,IACzD;AAAA,IACA,MAAM,IAAIA,MAAS;AACjB,MAAIM,EAAQ,MAAM,OAAe,KAAKG,GAAQ,GAAGT,CAAI;AAAA,IACvD;AAAA,IACA,MAAM,IAAIA,MAAS;AACjB,MAAIM,EAAQ,MAAM,OAAe,KAAKG,GAAQ,GAAGT,CAAI;AAAA,IACvD;AAAA,IACA,OAAO,IAAIA,MAAS;AAClB,MAAIM,EAAQ,OAAO,OAAe,MAAMG,GAAQ,GAAGT,CAAI;AAAA,IACzD;AAAA,IACA,OAAO,CAACU,MAAeH,EAAa,GAAGC,CAAK,IAAIE,CAAU,EAAE;AAAA,EAAA;AAEhE;"}

package/dist/core/registry/component-registry.d.ts

@@ -0,0 +1,41 @@
+import type { ComponentType } from 'react';
+import type { CustomObject } from '../../types/index.js';
+export interface ObjectComponentProps {
+    /** The object this behavior is attached to. */
+    object: CustomObject;
+}
+export type ObjectComponent = ComponentType<ObjectComponentProps>;
+export interface ComponentRegistryEntry {
+    component: ObjectComponent;
+    /**
+     * When true, objects carrying this component get an `onClick` handler wired
+     * by `CustomObject` (which emits `object:click`).
+     */
+    requiresInteraction: boolean;
+}
+export interface ComponentRegistryOptions {
+    requiresInteraction?: boolean;
+}
+/**
+ * Maps `CustomObject.components` keys from the scene JSON to React components.
+ *
+ * Behaviors are Unity-style: each one is self-contained and manages its own
+ * sensors, state, and event emission. Built-ins are installed with
+ * {@link registerDefault}, so host registrations made before mount always win.
+ */
+export declare class ComponentRegistry {
+    private components;
+    /** Register (or replace) a behavior component. */
+    register(name: string, component: ObjectComponent, options?: ComponentRegistryOptions): void;
+    /**
+     * Register only if the name is not taken. Used for SDK built-ins.
+     *
+     * @returns whether the component was installed.
+     */
+    registerDefault(name: string, component: ObjectComponent, options?: ComponentRegistryOptions): boolean;
+    unregister(name: string): void;
+    get(name: string): ComponentRegistryEntry | undefined;
+    has(name: string): boolean;
+    getRegisteredNames(): string[];
+}
+//# sourceMappingURL=component-registry.d.ts.map

package/dist/core/registry/component-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-registry.d.ts","sourceRoot":"","sources":["../../../core/registry/component-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,MAAM,EAAE,YAAY,CAAA;CACrB;AAED,MAAM,MAAM,eAAe,GAAG,aAAa,CAAC,oBAAoB,CAAC,CAAA;AAEjE,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,eAAe,CAAA;IAC1B;;;OAGG;IACH,mBAAmB,EAAE,OAAO,CAAA;CAC7B;AAED,MAAM,WAAW,wBAAwB;IACvC,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B;AAED;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,UAAU,CAA4C;IAE9D,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,IAAI;IAO5F;;;;OAIG;IACH,eAAe,CACb,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,eAAe,EAC1B,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO;IAMV,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS;IAIrD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,kBAAkB,IAAI,MAAM,EAAE;CAG/B"}

package/dist/core/registry/component-registry.js

@@ -0,0 +1,34 @@
+class n {
+  components = /* @__PURE__ */ new Map();
+  /** Register (or replace) a behavior component. */
+  register(e, t, s) {
+    this.components.set(e, {
+      component: t,
+      requiresInteraction: s?.requiresInteraction ?? !1
+    });
+  }
+  /**
+   * Register only if the name is not taken. Used for SDK built-ins.
+   *
+   * @returns whether the component was installed.
+   */
+  registerDefault(e, t, s) {
+    return this.components.has(e) ? !1 : (this.register(e, t, s), !0);
+  }
+  unregister(e) {
+    this.components.delete(e);
+  }
+  get(e) {
+    return this.components.get(e);
+  }
+  has(e) {
+    return this.components.has(e);
+  }
+  getRegisteredNames() {
+    return Array.from(this.components.keys());
+  }
+}
+export {
+  n as ComponentRegistry
+};
+//# sourceMappingURL=component-registry.js.map

package/dist/core/registry/component-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-registry.js","sources":["../../../core/registry/component-registry.ts"],"sourcesContent":["import type { ComponentType } from 'react'\nimport type { CustomObject } from '../../types'\n\nexport interface ObjectComponentProps {\n  /** The object this behavior is attached to. */\n  object: CustomObject\n}\n\nexport type ObjectComponent = ComponentType<ObjectComponentProps>\n\nexport interface ComponentRegistryEntry {\n  component: ObjectComponent\n  /**\n   * When true, objects carrying this component get an `onClick` handler wired\n   * by `CustomObject` (which emits `object:click`).\n   */\n  requiresInteraction: boolean\n}\n\nexport interface ComponentRegistryOptions {\n  requiresInteraction?: boolean\n}\n\n/**\n * Maps `CustomObject.components` keys from the scene JSON to React components.\n *\n * Behaviors are Unity-style: each one is self-contained and manages its own\n * sensors, state, and event emission. Built-ins are installed with\n * {@link registerDefault}, so host registrations made before mount always win.\n */\nexport class ComponentRegistry {\n  private components = new Map<string, ComponentRegistryEntry>()\n\n  /** Register (or replace) a behavior component. */\n  register(name: string, component: ObjectComponent, options?: ComponentRegistryOptions): void {\n    this.components.set(name, {\n      component,\n      requiresInteraction: options?.requiresInteraction ?? false\n    })\n  }\n\n  /**\n   * Register only if the name is not taken. Used for SDK built-ins.\n   *\n   * @returns whether the component was installed.\n   */\n  registerDefault(\n    name: string,\n    component: ObjectComponent,\n    options?: ComponentRegistryOptions\n  ): boolean {\n    if (this.components.has(name)) return false\n    this.register(name, component, options)\n    return true\n  }\n\n  unregister(name: string): void {\n    this.components.delete(name)\n  }\n\n  get(name: string): ComponentRegistryEntry | undefined {\n    return this.components.get(name)\n  }\n\n  has(name: string): boolean {\n    return this.components.has(name)\n  }\n\n  getRegisteredNames(): string[] {\n    return Array.from(this.components.keys())\n  }\n}\n"],"names":["ComponentRegistry","name","component","options"],"mappings":"AA8BO,MAAMA,EAAkB;AAAA,EACrB,iCAAiB,IAAA;AAAA;AAAA,EAGzB,SAASC,GAAcC,GAA4BC,GAA0C;AAC3F,SAAK,WAAW,IAAIF,GAAM;AAAA,MACxB,WAAAC;AAAA,MACA,qBAAqBC,GAAS,uBAAuB;AAAA,IAAA,CACtD;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,gBACEF,GACAC,GACAC,GACS;AACT,WAAI,KAAK,WAAW,IAAIF,CAAI,IAAU,MACtC,KAAK,SAASA,GAAMC,GAAWC,CAAO,GAC/B;AAAA,EACT;AAAA,EAEA,WAAWF,GAAoB;AAC7B,SAAK,WAAW,OAAOA,CAAI;AAAA,EAC7B;AAAA,EAEA,IAAIA,GAAkD;AACpD,WAAO,KAAK,WAAW,IAAIA,CAAI;AAAA,EACjC;AAAA,EAEA,IAAIA,GAAuB;AACzB,WAAO,KAAK,WAAW,IAAIA,CAAI;AAAA,EACjC;AAAA,EAEA,qBAA+B;AAC7B,WAAO,MAAM,KAAK,KAAK,WAAW,MAAM;AAAA,EAC1C;AACF;"}

package/dist/core/registry/object-registry.d.ts

@@ -0,0 +1,38 @@
+import type { ComponentType } from 'react';
+import type { ThreeEvent } from '@react-three/fiber';
+import type { CustomObject } from '../../types/index.js';
+export interface ObjectRendererProps {
+    /** Full object entry from the scene JSON. */
+    object: CustomObject;
+    /** Click handler pre-wired to emit `object:click`; attach it to your mesh. */
+    onClick?: (event: ThreeEvent<MouseEvent>) => void;
+    /** Whether the owning space currently has physics enabled. */
+    physics?: boolean;
+    /** Whether the object should skip animation work (non-active space). */
+    static?: boolean;
+}
+export type ObjectRenderer = ComponentType<ObjectRendererProps>;
+/**
+ * Maps `CustomObject.type` values from the scene JSON to React components.
+ *
+ * Pass your own instance to a viewer to add object types, or to replace a
+ * built-in renderer. Built-ins are installed with {@link registerDefault}, so
+ * anything you `register()` before mount always wins.
+ */
+export declare class ObjectRegistry {
+    private renderers;
+    /** Register (or replace) the renderer for an object type. */
+    register(type: string, renderer: ObjectRenderer): void;
+    /**
+     * Register only if the type is not taken. Used for SDK built-ins so a host
+     * registration made before mount is never clobbered.
+     *
+     * @returns whether the renderer was installed.
+     */
+    registerDefault(type: string, renderer: ObjectRenderer): boolean;
+    unregister(type: string): void;
+    get(type: string): ObjectRenderer | undefined;
+    has(type: string): boolean;
+    getRegisteredTypes(): string[];
+}
+//# sourceMappingURL=object-registry.d.ts.map

package/dist/core/registry/object-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-registry.d.ts","sourceRoot":"","sources":["../../../core/registry/object-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,MAAM,EAAE,YAAY,CAAA;IACpB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,IAAI,CAAA;IACjD,8DAA8D;IAC9D,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,wEAAwE;IACxE,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,MAAM,cAAc,GAAG,aAAa,CAAC,mBAAmB,CAAC,CAAA;AAE/D;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,SAAS,CAAoC;IAErD,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,IAAI;IAItD;;;;;OAKG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO;IAMhE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI7C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,kBAAkB,IAAI,MAAM,EAAE;CAG/B"}

package/dist/core/registry/object-registry.js

@@ -0,0 +1,32 @@
+class t {
+  renderers = /* @__PURE__ */ new Map();
+  /** Register (or replace) the renderer for an object type. */
+  register(e, r) {
+    this.renderers.set(e, r);
+  }
+  /**
+   * Register only if the type is not taken. Used for SDK built-ins so a host
+   * registration made before mount is never clobbered.
+   *
+   * @returns whether the renderer was installed.
+   */
+  registerDefault(e, r) {
+    return this.renderers.has(e) ? !1 : (this.renderers.set(e, r), !0);
+  }
+  unregister(e) {
+    this.renderers.delete(e);
+  }
+  get(e) {
+    return this.renderers.get(e);
+  }
+  has(e) {
+    return this.renderers.has(e);
+  }
+  getRegisteredTypes() {
+    return Array.from(this.renderers.keys());
+  }
+}
+export {
+  t as ObjectRegistry
+};
+//# sourceMappingURL=object-registry.js.map

package/dist/core/registry/object-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-registry.js","sources":["../../../core/registry/object-registry.ts"],"sourcesContent":["import type { ComponentType } from 'react'\nimport type { ThreeEvent } from '@react-three/fiber'\nimport type { CustomObject } from '../../types'\n\nexport interface ObjectRendererProps {\n  /** Full object entry from the scene JSON. */\n  object: CustomObject\n  /** Click handler pre-wired to emit `object:click`; attach it to your mesh. */\n  onClick?: (event: ThreeEvent<MouseEvent>) => void\n  /** Whether the owning space currently has physics enabled. */\n  physics?: boolean\n  /** Whether the object should skip animation work (non-active space). */\n  static?: boolean\n}\n\nexport type ObjectRenderer = ComponentType<ObjectRendererProps>\n\n/**\n * Maps `CustomObject.type` values from the scene JSON to React components.\n *\n * Pass your own instance to a viewer to add object types, or to replace a\n * built-in renderer. Built-ins are installed with {@link registerDefault}, so\n * anything you `register()` before mount always wins.\n */\nexport class ObjectRegistry {\n  private renderers = new Map<string, ObjectRenderer>()\n\n  /** Register (or replace) the renderer for an object type. */\n  register(type: string, renderer: ObjectRenderer): void {\n    this.renderers.set(type, renderer)\n  }\n\n  /**\n   * Register only if the type is not taken. Used for SDK built-ins so a host\n   * registration made before mount is never clobbered.\n   *\n   * @returns whether the renderer was installed.\n   */\n  registerDefault(type: string, renderer: ObjectRenderer): boolean {\n    if (this.renderers.has(type)) return false\n    this.renderers.set(type, renderer)\n    return true\n  }\n\n  unregister(type: string): void {\n    this.renderers.delete(type)\n  }\n\n  get(type: string): ObjectRenderer | undefined {\n    return this.renderers.get(type)\n  }\n\n  has(type: string): boolean {\n    return this.renderers.has(type)\n  }\n\n  getRegisteredTypes(): string[] {\n    return Array.from(this.renderers.keys())\n  }\n}\n"],"names":["ObjectRegistry","type","renderer"],"mappings":"AAwBO,MAAMA,EAAe;AAAA,EAClB,gCAAgB,IAAA;AAAA;AAAA,EAGxB,SAASC,GAAcC,GAAgC;AACrD,SAAK,UAAU,IAAID,GAAMC,CAAQ;AAAA,EACnC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,gBAAgBD,GAAcC,GAAmC;AAC/D,WAAI,KAAK,UAAU,IAAID,CAAI,IAAU,MACrC,KAAK,UAAU,IAAIA,GAAMC,CAAQ,GAC1B;AAAA,EACT;AAAA,EAEA,WAAWD,GAAoB;AAC7B,SAAK,UAAU,OAAOA,CAAI;AAAA,EAC5B;AAAA,EAEA,IAAIA,GAA0C;AAC5C,WAAO,KAAK,UAAU,IAAIA,CAAI;AAAA,EAChC;AAAA,EAEA,IAAIA,GAAuB;AACzB,WAAO,KAAK,UAAU,IAAIA,CAAI;AAAA,EAChC;AAAA,EAEA,qBAA+B;AAC7B,WAAO,MAAM,KAAK,KAAK,UAAU,MAAM;AAAA,EACzC;AACF;"}

package/dist/explore/cave-explore.d.ts

@@ -0,0 +1,85 @@
+import { type ConnectorLabelMode, type ConnectorLabelRenderer } from '../core/index.js';
+import type { CharacterControlsConfig } from './characters/character-controls.js';
+import type { LocalCharacterModelProp } from './characters/local-character-model.js';
+import { type PortalNavigateHandler } from './hooks/use-explore-actions.js';
+import { type ExploreHelperConfig, type ExploreHelperRenderer } from './overlays/explore-helper.js';
+import { type ExploreSimpleCharacterRoot, type MultiplayerRuntimeConfig } from './simple-character.js';
+import type { CaveViewerBaseProps, ActiveSpaceChangeHandler } from './viewer-shared.js';
+/**
+ * Enable multiplayer with an explicit config object, or pass `true` only when
+ * you also supply `url` via a follow-up object — bare `true` is rejected.
+ */
+export type MultiplayerProp = boolean | MultiplayerRuntimeConfig;
+/** Imperative handle exposed through `ref` on `CaveExplore`. */
+export interface CaveExploreHandle {
+    /** Local player's root object, or `null` before the scene mounts. */
+    getCharacter(): ExploreSimpleCharacterRoot | null;
+    /** Space the player is currently in. */
+    getActiveSpaceId(): string | undefined;
+    /**
+     * Move the local player. Coordinates are base-layer-local in the active
+     * space, matching `spawnPoint` / connector conventions; `yaw = 0` faces +Z.
+     */
+    teleport(pose: {
+        position: [number, number, number];
+        yaw?: number;
+    }): void;
+}
+export interface CaveExploreProps extends CaveViewerBaseProps {
+    /**
+     * Fired with the id (and loaded config) of the scene the player is currently
+     * in — once for the initial scene and again after every seamless / portal
+     * transition. Use it to keep scene-scoped UI in sync during cross-scene
+     * travel; read the scene name from `space.metadata.name`.
+     */
+    onActiveSpaceChange?: ActiveSpaceChangeHandler;
+    /**
+     * Multiplayer character sync. Requires an explicit `url`. Pass `avatars`
+     * (or `BUILTIN_AVATARS`) for remote meshes — omitting it does not fall back
+     * to the CaveGiant CDN.
+     * @default false
+     */
+    multiplayer?: MultiplayerProp;
+    /**
+     * Third-person local player mesh. Omit for the viverse mannequin; pass a
+     * config with `url` (+ `boneMap` for non-VRM rigs) for a custom GLB/VRM.
+     * First-person always hides the body.
+     *
+     * Must be a stable reference (module constant or `useMemo`) — a new object
+     * each render re-loads the GLB and resets locomotion state.
+     */
+    localCharacterModel?: LocalCharacterModelProp;
+    /** Locomotion speeds and input bindings for the local player. */
+    characterControls?: CharacterControlsConfig;
+    /** Global default for connector wayfinding labels. @default 'auto' */
+    connectorLabel?: ConnectorLabelMode;
+    /** Replace the built-in connector label visuals. */
+    renderConnectorLabel?: ConnectorLabelRenderer;
+    /** Configure the first-run controls hint, or `false` to disable it. */
+    exploreHelper?: ExploreHelperConfig | false;
+    /** Replace the first-run controls hint UI. */
+    renderExploreHelper?: ExploreHelperRenderer;
+    /**
+     * Handle activation of `portal` objects (in-app routes, deep links). Return
+     * `true` if handled; otherwise the SDK opens absolute `http(s)` URLs only.
+     */
+    onPortalNavigate?: PortalNavigateHandler;
+}
+/**
+ * Full first/third-person virtual tour: canvas, physics, character controls,
+ * cross-scene travel, and the built-in interaction overlays.
+ *
+ * The container must have a definite width and height — the viewer fills it.
+ *
+ * @example
+ * ```tsx
+ * <div style={{ width: '100vw', height: '100vh' }}>
+ *   <CaveExplore spaceId="my-space" />
+ * </div>
+ * ```
+ */
+declare const CaveExplore: import("react").ForwardRefExoticComponent<CaveExploreProps & import("react").RefAttributes<CaveExploreHandle>>;
+export default CaveExplore;
+/** Re-exported so `ref` consumers don't need a deep import. */
+export type { ExploreSimpleCharacterRoot };
+//# sourceMappingURL=cave-explore.d.ts.map

package/dist/explore/cave-explore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cave-explore.d.ts","sourceRoot":"","sources":["../../explore/cave-explore.tsx"],"names":[],"mappings":"AAYA,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC5B,MAAM,SAAS,CAAA;AAUhB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAA;AAC9E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAA;AAMjF,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,6BAA6B,CAAA;AAQ3F,OAAsB,EACpB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC3B,MAAM,2BAA2B,CAAA;AAElC,OAA+B,EAC7B,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAC9B,MAAM,oBAAoB,CAAA;AAQ3B,OAAO,KAAK,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAA;AAMpF;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,wBAAwB,CAAA;AA6BhE,gEAAgE;AAChE,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,YAAY,IAAI,0BAA0B,GAAG,IAAI,CAAA;IACjD,wCAAwC;IACxC,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAAA;IACtC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;CAC3E;AAED,MAAM,WAAW,gBAAiB,SAAQ,mBAAmB;IAC3D;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,wBAAwB,CAAA;IAE9C;;;;;OAKG;IACH,WAAW,CAAC,EAAE,eAAe,CAAA;IAE7B;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,uBAAuB,CAAA;IAC7C,iEAAiE;IACjE,iBAAiB,CAAC,EAAE,uBAAuB,CAAA;IAE3C,sEAAsE;IACtE,cAAc,CAAC,EAAE,kBAAkB,CAAA;IACnC,oDAAoD;IACpD,oBAAoB,CAAC,EAAE,sBAAsB,CAAA;IAE7C,uEAAuE;IACvE,aAAa,CAAC,EAAE,mBAAmB,GAAG,KAAK,CAAA;IAC3C,8CAA8C;IAC9C,mBAAmB,CAAC,EAAE,qBAAqB,CAAA;IAE3C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,qBAAqB,CAAA;CACzC;AAiND;;;;;;;;;;;;GAYG;AACH,QAAA,MAAM,WAAW,gHAiBhB,CAAA;AAED,eAAe,WAAW,CAAA;AAE1B,+DAA+D;AAC/D,YAAY,EAAE,0BAA0B,EAAE,CAAA"}

package/dist/explore/cave-explore.js

@@ -0,0 +1,204 @@
+import { jsx as t, jsxs as A } from "react/jsx-runtime";
+import { forwardRef as X, useState as Y, useRef as b, useCallback as m, useEffect as x, useImperativeHandle as Z, useMemo as $, Suspense as v } from "react";
+import { Canvas as ee } from "@react-three/fiber";
+import { BvhPhysicsWorld as re } from "@react-three/viverse";
+import { CaveWorldProvider as te } from "../core/context/cave-world-context.js";
+import { createLogger as oe } from "../core/logging/logger.js";
+import { REVEAL_ON_ENTER_DEFAULT_ENABLED as ae } from "../space/splats/spark/splat-spread-reveal.js";
+import { useVisibilityFrameloop as ne } from "../space/utils/use-visibility-frameloop.js";
+import { getSparkCanvasDpr as ie } from "../space/utils/spark-performance.js";
+import { configureSparkWebGLRenderer as ce, configureCaveCanvasDomElement as se } from "../space/utils/configure-canvas.js";
+import { applyCharacterPose as R } from "./characters/character-pose.js";
+import le from "./connected-spaces-renderer.js";
+import { useActionShortcuts as me } from "./hooks/use-action-shortcuts.js";
+import { useActiveSpaceNotify as pe } from "./hooks/use-active-space-notify.js";
+import { preloadSpaceAssets as ue, useConnectorPreloader as de } from "./hooks/use-connector-preloader.js";
+import { useConnectorTransitions as fe } from "./hooks/use-connector-transitions.js";
+import { useExploreActions as ve } from "./hooks/use-explore-actions.js";
+import { useLoadErrorNotify as Se } from "./hooks/use-load-error-notify.js";
+import { usePrimarySpaceLoader as Ce } from "./hooks/use-primary-space-loader.js";
+import { DefaultCaveSpaceLoader as ye } from "./loaders/cave-loader.js";
+import Ee from "./overlays/action-bubble.js";
+import ge from "./overlays/action-panel.js";
+import Le from "./overlays/connector-label-beacon.js";
+import he from "./overlays/detail-window.js";
+import Ae from "./overlays/explore-helper.js";
+import be from "./overlays/space-load-error-overlay.js";
+import xe from "./simple-character.js";
+import { CaveExploreProvider as Re, useCaveExploreStore as we, useActionPromptStore as Pe } from "./stores/explore-context.js";
+import { computeSpawnPose as w, matrixFromM16 as P } from "./math/space-transforms.js";
+import { useCaveWorldStyles as Ie } from "./styles/inject.js";
+const De = { fov: 65, near: 0.1, far: 3e3 }, Te = { antialias: !1 }, I = oe("explore:multiplayer");
+function ke(c) {
+  if (!c) return;
+  const r = c === !0 ? {} : c;
+  if (!r.url) {
+    I.warn(
+      'multiplayer requires an explicit `url` (e.g. multiplayer={{ url: "wss://…" }}). Bare `true` or a config without `url` is ignored. Import DEFAULT_WEBSOCKET_URL only if you intentionally use the CaveGiant demo backend.'
+    );
+    return;
+  }
+  return r.avatars || I.warn(
+    "multiplayer.avatars was omitted — remote players will not resolve against the CaveGiant CDN. Pass your own catalog, or import BUILTIN_AVATARS for the demo assets."
+  ), {
+    url: r.url,
+    avatarId: r.avatarId,
+    avatars: r.avatars,
+    maxRemoteCharacters: r.maxRemoteCharacters
+  };
+}
+function Be({
+  props: c,
+  handleRef: r
+}) {
+  const {
+    spaceId: o,
+    caveSpaceLoader: S = ye,
+    onSpaceInitialized: C,
+    onActiveSpaceChange: D,
+    multiplayer: y,
+    localCharacterModel: T,
+    characterControls: k,
+    revealOnEnter: B,
+    injectStyles: N,
+    exploreHelper: E,
+    renderExploreHelper: _,
+    renderDetailWindow: g,
+    onPortalNavigate: M,
+    onLoadError: W,
+    onLoadErrorExit: F,
+    renderLoadError: U,
+    children: j
+  } = c, a = we(), p = Pe(), [u, L] = Y(!1), s = b(null), f = b(void 0);
+  Ie(N ?? !0);
+  const H = m(() => {
+    L(!1), f.current = void 0, p.getState().clearActions(), a.getState().setActiveConnector(void 0);
+  }, [p, a]), O = m(
+    (e, n) => {
+      ue(n);
+      const i = a.getState();
+      i.setConnectedSpace(e, n), i.setActiveSpaceId(e);
+    },
+    [a]
+  );
+  Ce({
+    spaceId: o,
+    loader: S,
+    onLoaded: O,
+    onReset: H
+  }), pe(D), Se(W), de(S, o, u), fe(o, s), ve(M), me();
+  const q = m(() => {
+    L(!0), C?.();
+  }, [C]);
+  x(() => {
+    const e = a, n = p;
+    return () => {
+      n.getState().clearActions(), e.getState().clearConnectedSpaces();
+    };
+  }, [a, p]);
+  const h = m(
+    (e) => {
+      const n = s.current;
+      if (!n) return;
+      const i = a.getState(), l = i.activeSpaceId, d = l ? i.connectedSpaces[l] : void 0;
+      if (!d) return;
+      const { position: J, quaternion: Q } = w(
+        { position: e.position, yaw: e.yaw ?? 0 },
+        d.baseLayer.transform,
+        l ? P(i.spaceTransforms[l]) : void 0
+      );
+      R(n, J, Q);
+    },
+    [a]
+  );
+  Z(
+    r,
+    () => ({
+      getCharacter: () => s.current,
+      getActiveSpaceId: () => a.getState().activeSpaceId,
+      teleport: h
+    }),
+    [a, h]
+  ), x(() => {
+    if (!u || !o || !s.current || f.current === o) return;
+    f.current = o;
+    const e = a.getState(), n = e.connectedSpaces[o], i = n?.baseLayer?.spawnPoint;
+    if (!i) return;
+    const { position: l, quaternion: d } = w(
+      i,
+      n.baseLayer.transform,
+      P(e.spaceTransforms[o])
+    );
+    R(s.current, l, d);
+  }, [u, o, a]);
+  const G = ne(), V = ie(), z = $(() => ke(y), [y]), K = m((e) => {
+    if (e.button === 2) {
+      document.exitPointerLock();
+      return;
+    }
+    e.pointerType === "mouse" && e.button === 0 && e.target instanceof HTMLCanvasElement && e.target.requestPointerLock();
+  }, []);
+  return /* @__PURE__ */ A("div", { className: "cw-root", children: [
+    /* @__PURE__ */ t(
+      ee,
+      {
+        dpr: V,
+        frameloop: G,
+        gl: Te,
+        camera: De,
+        onCreated: ({ gl: e }) => {
+          ce(e), se(e.domElement);
+        },
+        onPointerDown: K,
+        children: /* @__PURE__ */ t(v, { fallback: null, children: /* @__PURE__ */ A(re, { children: [
+          /* @__PURE__ */ t(
+            le,
+            {
+              primarySpaceId: o,
+              revealOnEnter: B ?? ae,
+              connectorLabels: !0,
+              onPrimaryInitialized: q
+            }
+          ),
+          /* @__PURE__ */ t(v, { fallback: null, children: /* @__PURE__ */ t(
+            xe,
+            {
+              ref: s,
+              spaceInited: u,
+              spaceId: o,
+              multiplayer: z,
+              localCharacterModel: T,
+              characterControls: k
+            }
+          ) }),
+          /* @__PURE__ */ t(Ee, {}),
+          /* @__PURE__ */ t(v, { fallback: null, children: j })
+        ] }) })
+      }
+    ),
+    g ? g() : /* @__PURE__ */ t(he, {}),
+    /* @__PURE__ */ t(ge, {}),
+    E === !1 ? null : /* @__PURE__ */ t(Ae, { config: E, render: _ }),
+    /* @__PURE__ */ t(be, { onExit: F, render: U })
+  ] });
+}
+const mr = X(
+  function(r, o) {
+    return /* @__PURE__ */ t(
+      te,
+      {
+        eventBus: r.eventBus,
+        objectRegistry: r.objectRegistry,
+        componentRegistry: r.componentRegistry,
+        messages: r.messages,
+        connectorLabel: r.connectorLabel ?? "auto",
+        connectorLabelRenderer: r.renderConnectorLabel ?? Le,
+        children: /* @__PURE__ */ t(Re, { children: /* @__PURE__ */ t(Be, { props: r, handleRef: o }) })
+      }
+    );
+  }
+);
+export {
+  mr as default
+};
+//# sourceMappingURL=cave-explore.js.map