@cavegiant/cave-world-r3f 1.0.0

package/dist/explore/hooks/use-character-sync.d.ts

@@ -0,0 +1,46 @@
+import type { Quaternion as QuaternionType, Vector3 as Vector3Type } from '../../types/index.js';
+import type { AnimationName } from '../characters/character-configs.js';
+import { type PlayerData, type WebSocketStatus } from '../services/websocket.service.js';
+export interface CharacterSyncConfig {
+    websocketUrl: string;
+    appId: string;
+    localAvatarId: string;
+    onPlayerUpdate?: (data: PlayerData) => void;
+    onPlayerJoin?: (data: PlayerData) => void;
+    onPlayerLeave?: (playerId: string) => void;
+    /** `localPlayerId` is `undefined` until the server confirms the join. */
+    onRoomSync?: (players: PlayerData[], localPlayerId?: string) => void;
+    onJoinSuccess?: (data: {
+        roomId: string;
+        playerId: string;
+        players: PlayerData[];
+        isRejoin: boolean;
+    }) => void;
+    onConnectionStatusChange?: (status: WebSocketStatus) => void;
+}
+export interface CharacterSyncResult {
+    status: WebSocketStatus;
+    isConnected: boolean;
+    /** Player id assigned by the server; `null` until `JOIN_SUCCESS`. */
+    localUserId: string | null;
+    connect: () => Promise<void>;
+    disconnect: () => void;
+    joinGame: (avatarId: string) => boolean;
+    updateState: (data: {
+        position?: Vector3Type;
+        rotation?: QuaternionType;
+        animation?: AnimationName;
+        avatarId?: string;
+    }) => boolean;
+    syncState: () => boolean;
+}
+/**
+ * Own a realtime connection for the lifetime of the mounting component.
+ *
+ * The connection is per-instance (it used to be a module-level singleton, which
+ * leaked across viewers and got torn down by whichever instance unmounted
+ * first). Callbacks are read through a ref so changing them never reconnects.
+ */
+export declare function useCharacterSync(config: CharacterSyncConfig): CharacterSyncResult;
+export type { PlayerData, WebSocketStatus };
+//# sourceMappingURL=use-character-sync.d.ts.map

package/dist/explore/hooks/use-character-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-character-sync.d.ts","sourceRoot":"","sources":["../../../explore/hooks/use-character-sync.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,IAAI,cAAc,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,aAAa,CAAA;AACvF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAA;AACpE,OAAO,EAIL,KAAK,UAAU,EAEf,KAAK,eAAe,EACrB,MAAM,+BAA+B,CAAA;AAItC,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,MAAM,CAAA;IACb,aAAa,EAAE,MAAM,CAAA;IACrB,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAA;IAC3C,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAA;IACzC,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,yEAAyE;IACzE,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,aAAa,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IACpE,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE;QACrB,MAAM,EAAE,MAAM,CAAA;QACd,QAAQ,EAAE,MAAM,CAAA;QAChB,OAAO,EAAE,UAAU,EAAE,CAAA;QACrB,QAAQ,EAAE,OAAO,CAAA;KAClB,KAAK,IAAI,CAAA;IACV,wBAAwB,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAA;CAC7D;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,eAAe,CAAA;IACvB,WAAW,EAAE,OAAO,CAAA;IACpB,qEAAqE;IACrE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,UAAU,EAAE,MAAM,IAAI,CAAA;IACtB,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAA;IACvC,WAAW,EAAE,CAAC,IAAI,EAAE;QAClB,QAAQ,CAAC,EAAE,WAAW,CAAA;QACtB,QAAQ,CAAC,EAAE,cAAc,CAAA;QACzB,SAAS,CAAC,EAAE,aAAa,CAAA;QACzB,QAAQ,CAAC,EAAE,MAAM,CAAA;KAClB,KAAK,OAAO,CAAA;IACb,SAAS,EAAE,MAAM,OAAO,CAAA;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,mBAAmB,GAAG,mBAAmB,CAiHjF;AAED,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,CAAA"}

package/dist/explore/hooks/use-character-sync.js

@@ -0,0 +1,72 @@
+import { useRef as C, useEffect as s, useMemo as L, useState as w, useCallback as c } from "react";
+import { createLogger as R } from "../../core/logging/logger.js";
+import { WebSocketService as h, MessageActionEnum as o, WebSocketStatusEnum as m } from "../services/websocket.service.js";
+const v = R("multiplayer");
+function M(d) {
+  const { websocketUrl: i, appId: S } = d, u = C(d);
+  s(() => {
+    u.current = d;
+  });
+  const e = L(() => new h({ url: i }), [i]), [l, T] = w(() => e.getStatus()), [b, U] = w(), p = b?.service === e ? b.playerId : null, r = C(null);
+  s(() => (e.connect().catch((n) => {
+    v.warn("Connection failed:", n);
+  }), () => {
+    e.destroy();
+  }), [e]), s(() => {
+    r.current = null;
+    const n = e.addStatusListener((t) => {
+      T(t), u.current.onConnectionStatusChange?.(t);
+    }), A = e.addMessageListener((t) => {
+      const a = u.current;
+      switch (t.action) {
+        case o.STATE_UPDATE:
+          t.data.playerId !== r.current && a.onPlayerUpdate?.(t.data);
+          break;
+        case o.PLAYER_JOINED:
+          t.data.playerId !== r.current && a.onPlayerJoin?.(t.data);
+          break;
+        case o.PLAYER_LEFT:
+          a.onPlayerLeave?.(t.data.playerId);
+          break;
+        case o.STATE_SYNC:
+          a.onRoomSync?.(t.data.players, r.current ?? void 0);
+          break;
+        case o.JOIN_SUCCESS:
+          r.current = t.data.playerId, U({ service: e, playerId: t.data.playerId }), a.onJoinSuccess?.(t.data);
+          break;
+      }
+    }), P = e.addErrorListener((t) => {
+      v.warn("Socket error:", t);
+    });
+    return () => {
+      n(), A(), P();
+    };
+  }, [e]), s(() => {
+    const n = () => e.disconnect();
+    return window.addEventListener("beforeunload", n), () => window.removeEventListener("beforeunload", n);
+  }, [e]);
+  const y = c(() => e.connect(), [e]), E = c(() => e.disconnect(), [e]), f = c(
+    (n) => e.joinGame(S, n),
+    [e, S]
+  ), k = c(
+    (n) => e.updateState(n),
+    [e]
+  ), I = c(() => e.syncState(), [e]);
+  return L(
+    () => ({
+      status: l,
+      isConnected: l === m.CONNECTED,
+      localUserId: p,
+      connect: y,
+      disconnect: E,
+      joinGame: f,
+      updateState: k,
+      syncState: I
+    }),
+    [l, p, y, E, f, k, I]
+  );
+}
+export {
+  M as useCharacterSync
+};
+//# sourceMappingURL=use-character-sync.js.map

package/dist/explore/hooks/use-character-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-character-sync.js","sources":["../../../explore/hooks/use-character-sync.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useState } from 'react'\nimport { createLogger } from '../../core'\nimport type { Quaternion as QuaternionType, Vector3 as Vector3Type } from '../../types'\nimport type { AnimationName } from '../characters/character-configs'\nimport {\n  MessageActionEnum,\n  WebSocketService,\n  WebSocketStatusEnum,\n  type PlayerData,\n  type WebSocketMessage,\n  type WebSocketStatus\n} from '../services/websocket.service'\n\nconst logger = createLogger('multiplayer')\n\nexport interface CharacterSyncConfig {\n  websocketUrl: string\n  appId: string\n  localAvatarId: string\n  onPlayerUpdate?: (data: PlayerData) => void\n  onPlayerJoin?: (data: PlayerData) => void\n  onPlayerLeave?: (playerId: string) => void\n  /** `localPlayerId` is `undefined` until the server confirms the join. */\n  onRoomSync?: (players: PlayerData[], localPlayerId?: string) => void\n  onJoinSuccess?: (data: {\n    roomId: string\n    playerId: string\n    players: PlayerData[]\n    isRejoin: boolean\n  }) => void\n  onConnectionStatusChange?: (status: WebSocketStatus) => void\n}\n\nexport interface CharacterSyncResult {\n  status: WebSocketStatus\n  isConnected: boolean\n  /** Player id assigned by the server; `null` until `JOIN_SUCCESS`. */\n  localUserId: string | null\n  connect: () => Promise<void>\n  disconnect: () => void\n  joinGame: (avatarId: string) => boolean\n  updateState: (data: {\n    position?: Vector3Type\n    rotation?: QuaternionType\n    animation?: AnimationName\n    avatarId?: string\n  }) => boolean\n  syncState: () => boolean\n}\n\n/**\n * Own a realtime connection for the lifetime of the mounting component.\n *\n * The connection is per-instance (it used to be a module-level singleton, which\n * leaked across viewers and got torn down by whichever instance unmounted\n * first). Callbacks are read through a ref so changing them never reconnects.\n */\nexport function useCharacterSync(config: CharacterSyncConfig): CharacterSyncResult {\n  const { websocketUrl, appId } = config\n\n  const callbacksRef = useRef(config)\n  useEffect(() => {\n    callbacksRef.current = config\n  })\n\n  const service = useMemo(() => new WebSocketService({ url: websocketUrl }), [websocketUrl])\n\n  const [status, setStatus] = useState<WebSocketStatus>(() => service.getStatus())\n\n  // Tag the assigned player id with the service it came from, so a reconnect to\n  // a different URL reports \"not joined\" immediately — without a reset effect.\n  const [joined, setJoined] = useState<{ service: WebSocketService; playerId: string }>()\n  const localUserId = joined?.service === service ? joined.playerId : null\n\n  // Mirror of the id for use inside socket callbacks, which must not close over\n  // a render-time value. Written only from the JOIN_SUCCESS handler below.\n  const localUserIdRef = useRef<string | null>(null)\n\n  // Connect on mount / URL change, and always tear the socket down with it.\n  useEffect(() => {\n    service.connect().catch((error: unknown) => {\n      logger.warn('Connection failed:', error)\n    })\n\n    return () => {\n      service.destroy()\n    }\n  }, [service])\n\n  useEffect(() => {\n    localUserIdRef.current = null\n\n    const unsubscribeStatus = service.addStatusListener((next) => {\n      setStatus(next)\n      callbacksRef.current.onConnectionStatusChange?.(next)\n    })\n\n    const unsubscribeMessage = service.addMessageListener((message: WebSocketMessage) => {\n      const callbacks = callbacksRef.current\n      switch (message.action) {\n        case MessageActionEnum.STATE_UPDATE:\n          if (message.data.playerId !== localUserIdRef.current) {\n            callbacks.onPlayerUpdate?.(message.data)\n          }\n          break\n        case MessageActionEnum.PLAYER_JOINED:\n          if (message.data.playerId !== localUserIdRef.current) {\n            callbacks.onPlayerJoin?.(message.data)\n          }\n          break\n        case MessageActionEnum.PLAYER_LEFT:\n          callbacks.onPlayerLeave?.(message.data.playerId)\n          break\n        case MessageActionEnum.STATE_SYNC:\n          callbacks.onRoomSync?.(message.data.players, localUserIdRef.current ?? undefined)\n          break\n        case MessageActionEnum.JOIN_SUCCESS:\n          localUserIdRef.current = message.data.playerId\n          setJoined({ service, playerId: message.data.playerId })\n          callbacks.onJoinSuccess?.(message.data)\n          break\n        default:\n          break\n      }\n    })\n\n    const unsubscribeError = service.addErrorListener((error) => {\n      logger.warn('Socket error:', error)\n    })\n\n    return () => {\n      unsubscribeStatus()\n      unsubscribeMessage()\n      unsubscribeError()\n    }\n  }, [service])\n\n  // Leave cleanly when the tab closes so the server drops us immediately\n  // instead of waiting for a heartbeat timeout.\n  useEffect(() => {\n    const handleBeforeUnload = () => service.disconnect()\n    window.addEventListener('beforeunload', handleBeforeUnload)\n    return () => window.removeEventListener('beforeunload', handleBeforeUnload)\n  }, [service])\n\n  const connect = useCallback(() => service.connect(), [service])\n  const disconnect = useCallback(() => service.disconnect(), [service])\n  const joinGame = useCallback(\n    (avatarId: string) => service.joinGame(appId, avatarId),\n    [service, appId]\n  )\n  const updateState = useCallback<CharacterSyncResult['updateState']>(\n    (data) => service.updateState(data),\n    [service]\n  )\n  const syncState = useCallback(() => service.syncState(), [service])\n\n  return useMemo(\n    () => ({\n      status,\n      isConnected: status === WebSocketStatusEnum.CONNECTED,\n      localUserId,\n      connect,\n      disconnect,\n      joinGame,\n      updateState,\n      syncState\n    }),\n    [status, localUserId, connect, disconnect, joinGame, updateState, syncState]\n  )\n}\n\nexport type { PlayerData, WebSocketStatus }\n"],"names":["logger","createLogger","useCharacterSync","config","websocketUrl","appId","callbacksRef","useRef","useEffect","service","useMemo","WebSocketService","status","setStatus","useState","joined","setJoined","localUserId","localUserIdRef","error","unsubscribeStatus","next","unsubscribeMessage","message","callbacks","MessageActionEnum","unsubscribeError","handleBeforeUnload","connect","useCallback","disconnect","joinGame","avatarId","updateState","data","syncState","WebSocketStatusEnum"],"mappings":"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"}

package/dist/explore/hooks/use-connector-preloader.d.ts

@@ -0,0 +1,20 @@
+import type { CaveSpace } from '../../types/index.js';
+import type { CaveSpaceLoader } from '../loaders/cave-loader.js';
+/** Warm the loader cache for a space's heavy collider assets. */
+export declare function preloadSpaceAssets(space: CaveSpace): void;
+/**
+ * Preload every space referenced by the active space's connectors, and keep
+ * seamless neighbors' world-space group matrices up to date.
+ *
+ * Neighbor downloads are deferred until `primaryInitialized` (main splat +
+ * colliders ready) so they do not compete with the primary scene's assets on
+ * the same origin, and each neighbor's mount is scheduled in idle time so the
+ * burst doesn't stutter player input.
+ *
+ * The primary space is treated uniformly — it is registered in
+ * `connectedSpaces` with its own (initially identity) transform entry, which is
+ * what makes seamless back-traversal (A → B → A) work through the same path as
+ * forward traversal.
+ */
+export declare function useConnectorPreloader(loader: CaveSpaceLoader, primarySpaceId: string | undefined, primaryInitialized: boolean): void;
+//# sourceMappingURL=use-connector-preloader.d.ts.map

package/dist/explore/hooks/use-connector-preloader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-connector-preloader.d.ts","sourceRoot":"","sources":["../../../explore/hooks/use-connector-preloader.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAY,MAAM,aAAa,CAAA;AAQtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAa7D,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAMzD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,eAAe,EACvB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,kBAAkB,EAAE,OAAO,GAC1B,IAAI,CAoGN"}

package/dist/explore/hooks/use-connector-preloader.js

@@ -0,0 +1,78 @@
+import { useEffect as I, startTransition as C } from "react";
+import { useLoader as L } from "@react-three/fiber";
+import { Matrix4 as M } from "three";
+import { OBJLoader as E } from "three/examples/jsm/loaders/OBJLoader.js";
+import { createLogger as A } from "../../core/logging/logger.js";
+import { getConnectorTargetIds as v, matrixFromM16 as b, computeSeamlessGroupMatrix as h } from "../math/space-transforms.js";
+import { useCaveExploreStore as w, useCaveExplore as g } from "../stores/explore-context.js";
+import { scheduleIdle as y } from "../utils/schedule-idle.js";
+const N = A("explore:preload"), R = 1, O = /* @__PURE__ */ new M();
+function _(i) {
+  for (const c of i.baseLayer?.colliders ?? [])
+    c.type === "model" && c.url && L.preload(E, c.url);
+}
+function J(i, c, T) {
+  const r = w(), m = g((t) => t.connectedSpaces), x = g((t) => t.spaceTransforms), n = g((t) => t.activeSpaceId), d = n ? m[n] : void 0;
+  I(() => {
+    if (!n || !T) return;
+    const t = r.getState().connectedSpaces[n];
+    if (!t) return;
+    const p = v(t);
+    let s = !1;
+    const o = new Set(p);
+    if (o.add(n), c) {
+      o.add(c);
+      const e = r.getState().connectedSpaces[c];
+      if (e)
+        for (const f of v(e)) o.add(f);
+    }
+    r.getState().pruneConnectedSpaces(o);
+    const l = p.filter((e) => !r.getState().connectedSpaces[e]), a = /* @__PURE__ */ new Set(), u = () => {
+      if (s) return;
+      const e = l.shift();
+      if (e) {
+        if (r.getState().connectedSpaces[e]) {
+          u();
+          return;
+        }
+        i(e).then((f) => {
+          if (s) return;
+          let S = () => {
+          };
+          S = y(() => {
+            a.delete(S), !s && (_(f), C(() => r.getState().setConnectedSpace(e, f)), u());
+          }), a.add(S);
+        }).catch((f) => {
+          N.warn(`Failed to preload connected space ${e}:`, f), s || u();
+        });
+      }
+    };
+    for (let e = 0; e < R; e++) u();
+    return () => {
+      s = !0;
+      for (const e of a) e();
+      a.clear();
+    };
+  }, [n, c, T, i, r]), I(() => {
+    if (!d || !n) return;
+    const t = b(x[n]) ?? O, p = d.baseLayer.transform;
+    for (const s of d.baseLayer?.connectors ?? [])
+      for (const o of s.connectorInfo.to) {
+        if (o.transitionType !== "seamless" || !o.transform) continue;
+        const l = m[o.caveWorldId];
+        if (!l) continue;
+        const a = h(
+          t,
+          p,
+          o.transform,
+          l.baseLayer.transform
+        );
+        r.getState().setSpaceTransform(o.caveWorldId, a.toArray());
+      }
+  }, [n, d, m, x, r]);
+}
+export {
+  _ as preloadSpaceAssets,
+  J as useConnectorPreloader
+};
+//# sourceMappingURL=use-connector-preloader.js.map

package/dist/explore/hooks/use-connector-preloader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-connector-preloader.js","sources":["../../../explore/hooks/use-connector-preloader.ts"],"sourcesContent":["import { startTransition, useEffect } from 'react'\nimport { useLoader } from '@react-three/fiber'\nimport { Matrix4 } from 'three'\nimport { OBJLoader } from 'three/examples/jsm/loaders/OBJLoader.js'\nimport { createLogger } from '../../core'\nimport type { CaveSpace, Matrix16 } from '../../types'\nimport {\n  computeSeamlessGroupMatrix,\n  getConnectorTargetIds,\n  matrixFromM16\n} from '../math/space-transforms'\nimport { useCaveExplore, useCaveExploreStore } from '../stores/explore-context'\nimport { scheduleIdle } from '../utils/schedule-idle'\nimport type { CaveSpaceLoader } from '../loaders/cave-loader'\n\nconst logger = createLogger('explore:preload')\n\n/**\n * Max neighbor scenes whose heavy mount runs concurrently. Loading 2-4 at once\n * bursts JSON + splat decode/upload + OBJ parse onto the main thread; a small\n * limit serializes them so each lands in its own idle slot.\n */\nconst MAX_CONCURRENT_PRELOADS = 1\n\nconst IDENTITY_MATRIX4 = /* @__PURE__ */ new Matrix4()\n\n/** Warm the loader cache for a space's heavy collider assets. */\nexport function preloadSpaceAssets(space: CaveSpace): void {\n  for (const collider of space.baseLayer?.colliders ?? []) {\n    if (collider.type === 'model' && collider.url) {\n      useLoader.preload(OBJLoader, collider.url)\n    }\n  }\n}\n\n/**\n * Preload every space referenced by the active space's connectors, and keep\n * seamless neighbors' world-space group matrices up to date.\n *\n * Neighbor downloads are deferred until `primaryInitialized` (main splat +\n * colliders ready) so they do not compete with the primary scene's assets on\n * the same origin, and each neighbor's mount is scheduled in idle time so the\n * burst doesn't stutter player input.\n *\n * The primary space is treated uniformly — it is registered in\n * `connectedSpaces` with its own (initially identity) transform entry, which is\n * what makes seamless back-traversal (A → B → A) work through the same path as\n * forward traversal.\n */\nexport function useConnectorPreloader(\n  loader: CaveSpaceLoader,\n  primarySpaceId: string | undefined,\n  primaryInitialized: boolean\n): void {\n  const store = useCaveExploreStore()\n  const connectedSpaces = useCaveExplore((s) => s.connectedSpaces)\n  const spaceTransforms = useCaveExplore((s) => s.spaceTransforms)\n  const activeSpaceId = useCaveExplore((s) => s.activeSpaceId)\n\n  const activeSpace = activeSpaceId ? connectedSpaces[activeSpaceId] : undefined\n\n  // Effect 1: prune unreachable spaces, then queue throttled idle-scheduled\n  // preloads for the active space's neighbors.\n  useEffect(() => {\n    if (!activeSpaceId || !primaryInitialized) return\n    const active = store.getState().connectedSpaces[activeSpaceId]\n    if (!active) return\n\n    const targetIds = getConnectorTargetIds(active)\n    let cancelled = false\n\n    // Keep: active + active's direct neighbors + primary + primary's direct\n    // neighbors. The primary stays loaded so seamless back-traversal always\n    // works, and its other targets stay warm for the common A → B → A → C path.\n    const keepIds = new Set<string>(targetIds)\n    keepIds.add(activeSpaceId)\n    if (primarySpaceId) {\n      keepIds.add(primarySpaceId)\n      const primary = store.getState().connectedSpaces[primarySpaceId]\n      if (primary) {\n        for (const id of getConnectorTargetIds(primary)) keepIds.add(id)\n      }\n    }\n    store.getState().pruneConnectedSpaces(keepIds)\n\n    const queue = targetIds.filter((id) => !store.getState().connectedSpaces[id])\n    const pendingIdles = new Set<() => void>()\n\n    const processNext = () => {\n      if (cancelled) return\n      const id = queue.shift()\n      if (!id) return\n      if (store.getState().connectedSpaces[id]) {\n        processNext()\n        return\n      }\n      loader(id)\n        .then((space) => {\n          if (cancelled) return\n          let cancelIdle: () => void = () => {}\n          const run = () => {\n            pendingIdles.delete(cancelIdle)\n            if (cancelled) return\n            preloadSpaceAssets(space)\n            startTransition(() => store.getState().setConnectedSpace(id, space))\n            processNext()\n          }\n          cancelIdle = scheduleIdle(run)\n          pendingIdles.add(cancelIdle)\n        })\n        .catch((error: unknown) => {\n          logger.warn(`Failed to preload connected space ${id}:`, error)\n          if (!cancelled) processNext()\n        })\n    }\n\n    for (let i = 0; i < MAX_CONCURRENT_PRELOADS; i++) processNext()\n\n    return () => {\n      cancelled = true\n      for (const cancel of pendingIdles) cancel()\n      pendingIdles.clear()\n    }\n    // Intentionally keyed on identity only: `connectedSpaces` is read through\n    // `store.getState()` so a neighbor landing doesn't restart the queue.\n  }, [activeSpaceId, primarySpaceId, primaryInitialized, loader, store])\n\n  // Effect 2: recompute seamless group matrices as neighbors become available.\n  useEffect(() => {\n    if (!activeSpace || !activeSpaceId) return\n\n    // G_source: whatever was previously computed for the active space (identity\n    // for the primary on first entry; for back-traversal we honour the current\n    // value so round-trips stay self-consistent).\n    const sourceGroupMatrix = matrixFromM16(spaceTransforms[activeSpaceId]) ?? IDENTITY_MATRIX4\n    const sourceTransform = activeSpace.baseLayer.transform\n\n    for (const connector of activeSpace.baseLayer?.connectors ?? []) {\n      for (const target of connector.connectorInfo.to) {\n        if (target.transitionType !== 'seamless' || !target.transform) continue\n        const targetSpace = connectedSpaces[target.caveWorldId]\n        if (!targetSpace) continue\n\n        const groupMatrix = computeSeamlessGroupMatrix(\n          sourceGroupMatrix,\n          sourceTransform,\n          target.transform,\n          targetSpace.baseLayer.transform\n        )\n        store.getState().setSpaceTransform(target.caveWorldId, groupMatrix.toArray() as Matrix16)\n      }\n    }\n  }, [activeSpaceId, activeSpace, connectedSpaces, spaceTransforms, store])\n}\n"],"names":["logger","createLogger","MAX_CONCURRENT_PRELOADS","IDENTITY_MATRIX4","Matrix4","preloadSpaceAssets","space","collider","useLoader","OBJLoader","useConnectorPreloader","loader","primarySpaceId","primaryInitialized","store","useCaveExploreStore","connectedSpaces","useCaveExplore","s","spaceTransforms","activeSpaceId","activeSpace","useEffect","active","targetIds","getConnectorTargetIds","cancelled","keepIds","primary","id","queue","pendingIdles","processNext","cancelIdle","scheduleIdle","startTransition","error","i","cancel","sourceGroupMatrix","matrixFromM16","sourceTransform","connector","target","targetSpace","groupMatrix","computeSeamlessGroupMatrix"],"mappings":"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"}

package/dist/explore/hooks/use-connector-transitions.d.ts

@@ -0,0 +1,31 @@
+import { type RefObject } from 'react';
+import type { ExploreSimpleCharacterRoot } from '../simple-character.js';
+/**
+ * Window (ms) during which `connector:enter` events are dropped after a
+ * seamless transition, to swallow the "ghost" enter fired by the target scene's
+ * matching connector.
+ *
+ * Rationale: after a seamless A → B transition the character stays at the same
+ * world position, which (by construction of the alignment matrix) is also
+ * inside B's matching back-link connector. Because connector sensors only mount
+ * for the active scene, B's sensor is added while the character is already
+ * inside it; the very next physics tick flips its state false → true and fires
+ * `onIntersectedChanged(true)`, which would otherwise ping-pong the user
+ * straight back to A or pop a spurious portal panel.
+ *
+ * The window is deliberately short: the ghost fires within ~16–32 ms (one
+ * physics tick), and a human walk-out-walk-in cycle is far slower than 200 ms,
+ * so no legitimate event is dropped. Portal transitions don't need this — the
+ * character lands 0.5 m outside the target box.
+ */
+export declare const SEAMLESS_GHOST_ENTER_WINDOW_MS = 200;
+/**
+ * Wire connector events to scene transitions: seamless auto-switch, and portal
+ * destination selection with character teleport.
+ *
+ * All handlers subscribe once and read mutable inputs (active space, connected
+ * spaces, primary id) through store `getState()` / refs, so subscriptions don't
+ * churn on every preload-driven `connectedSpaces` update.
+ */
+export declare function useConnectorTransitions(primarySpaceId: string | undefined, characterRef: RefObject<ExploreSimpleCharacterRoot | null>): void;
+//# sourceMappingURL=use-connector-transitions.d.ts.map

package/dist/explore/hooks/use-connector-transitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-connector-transitions.d.ts","sourceRoot":"","sources":["../../../explore/hooks/use-connector-transitions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAKvF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAA;AAQrE;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,8BAA8B,MAAM,CAAA;AAEjD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,YAAY,EAAE,SAAS,CAAC,0BAA0B,GAAG,IAAI,CAAC,GACzD,IAAI,CAqGN"}

package/dist/explore/hooks/use-connector-transitions.js

@@ -0,0 +1,63 @@
+import { useRef as A, useEffect as l, useCallback as g, startTransition as E } from "react";
+import { useCaveEventBus as T, useCaveWorldStoreApi as W } from "../../core/context/cave-world-context.js";
+import { useCaveEvent as i } from "../../core/hooks/use-cave-event.js";
+import { applyCharacterPose as x } from "../characters/character-pose.js";
+import { findConnectorById as w, computePortalSpawnPose as y, matrixFromM16 as P } from "../math/space-transforms.js";
+import { isConnectorInActiveSpace as u } from "../stores/cave-explore.store.js";
+import { useCaveExploreStore as _, useActionPromptStore as B, useCaveExplore as M } from "../stores/explore-context.js";
+const b = 200;
+function q(a, p) {
+  const S = T(), f = W(), c = _(), s = B(), m = A(a);
+  l(() => {
+    m.current = a;
+  }, [a]);
+  const v = M((t) => t.activeSpaceId);
+  l(() => {
+    c.getState().setActiveConnector(void 0), s.getState().clearActions();
+  }, [v, c, s]);
+  const d = g(
+    (t, e, r) => {
+      const o = c.getState(), n = o.activeSpaceId ?? m.current ?? "";
+      r === "seamless" && o.setConnectorEnterSuppressUntil(performance.now() + b), E(() => {
+        o.setActiveSpaceId(t), f.getState().setSpaceConfig(e);
+      }), s.getState().clearActions(), S.emit("connector:transition", { from: n, to: t, type: r });
+    },
+    [c, f, s, S]
+  );
+  i("connector:enter", ({ connector: t }) => {
+    const e = c.getState();
+    if (performance.now() < e.connectorEnterSuppressUntil || !u(e, t)) return;
+    const r = t.connectorInfo.to, o = r.find((n) => n.transitionType === "seamless");
+    if (o) {
+      const n = e.connectedSpaces[o.caveWorldId];
+      if (!n || !e.readySpaceIds[o.caveWorldId]) return;
+      d(o.caveWorldId, n, "seamless");
+      return;
+    }
+    r.some((n) => n.transitionType === "portal") && e.setActiveConnector(t);
+  }), i("connector:leave", ({ connector: t }) => {
+    const e = c.getState();
+    u(e, t) && e.setActiveConnector(void 0);
+  }), i("connector:portal:select", ({ target: t }) => {
+    const e = t.caveWorldId, r = c.getState(), o = r.connectedSpaces[e];
+    if (!(!o || !r.readySpaceIds[e])) {
+      if (t.connectorId) {
+        const n = w(o, t.connectorId);
+        if (n && p.current) {
+          const { position: C, quaternion: I } = y(
+            n,
+            o.baseLayer.transform,
+            P(r.spaceTransforms[e])
+          );
+          x(p.current, C, I);
+        }
+      }
+      r.setActiveConnector(void 0), d(e, o, "portal");
+    }
+  });
+}
+export {
+  b as SEAMLESS_GHOST_ENTER_WINDOW_MS,
+  q as useConnectorTransitions
+};
+//# sourceMappingURL=use-connector-transitions.js.map

package/dist/explore/hooks/use-connector-transitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-connector-transitions.js","sources":["../../../explore/hooks/use-connector-transitions.ts"],"sourcesContent":["import { startTransition, useCallback, useEffect, useRef, type RefObject } from 'react'\nimport { useCaveEvent, useCaveEventBus, useCaveWorldStoreApi } from '../../core'\nimport type { CaveSpace } from '../../types'\nimport { applyCharacterPose } from '../characters/character-pose'\nimport { computePortalSpawnPose, findConnectorById, matrixFromM16 } from '../math/space-transforms'\nimport type { ExploreSimpleCharacterRoot } from '../simple-character'\nimport { isConnectorInActiveSpace } from '../stores/cave-explore.store'\nimport {\n  useActionPromptStore,\n  useCaveExplore,\n  useCaveExploreStore\n} from '../stores/explore-context'\n\n/**\n * Window (ms) during which `connector:enter` events are dropped after a\n * seamless transition, to swallow the \"ghost\" enter fired by the target scene's\n * matching connector.\n *\n * Rationale: after a seamless A → B transition the character stays at the same\n * world position, which (by construction of the alignment matrix) is also\n * inside B's matching back-link connector. Because connector sensors only mount\n * for the active scene, B's sensor is added while the character is already\n * inside it; the very next physics tick flips its state false → true and fires\n * `onIntersectedChanged(true)`, which would otherwise ping-pong the user\n * straight back to A or pop a spurious portal panel.\n *\n * The window is deliberately short: the ghost fires within ~16–32 ms (one\n * physics tick), and a human walk-out-walk-in cycle is far slower than 200 ms,\n * so no legitimate event is dropped. Portal transitions don't need this — the\n * character lands 0.5 m outside the target box.\n */\nexport const SEAMLESS_GHOST_ENTER_WINDOW_MS = 200\n\n/**\n * Wire connector events to scene transitions: seamless auto-switch, and portal\n * destination selection with character teleport.\n *\n * All handlers subscribe once and read mutable inputs (active space, connected\n * spaces, primary id) through store `getState()` / refs, so subscriptions don't\n * churn on every preload-driven `connectedSpaces` update.\n */\nexport function useConnectorTransitions(\n  primarySpaceId: string | undefined,\n  characterRef: RefObject<ExploreSimpleCharacterRoot | null>\n): void {\n  const eventBus = useCaveEventBus()\n  const worldStore = useCaveWorldStoreApi()\n  const exploreStore = useCaveExploreStore()\n  const actionPromptStore = useActionPromptStore()\n\n  // Hold the latest primary id in a ref so the event handlers stay stable.\n  const primaryIdRef = useRef(primarySpaceId)\n  useEffect(() => {\n    primaryIdRef.current = primarySpaceId\n  }, [primarySpaceId])\n\n  // When the active scene changes (seamless / portal), drop any connector prompt\n  // and `activeConnector` left over from the previous scene. A portal teleport\n  // moves the character while the previous scene is still active for a frame, so\n  // the old scene's sensors can leave a stale prompt (showing a previous-scene\n  // neighbor's name) that never clears. The new scene's sensors re-fire\n  // `connector:enter` for connectors the character actually stands in, so a\n  // legitimate prompt re-appears with the correct target-scene name.\n  const activeSpaceId = useCaveExplore((s) => s.activeSpaceId)\n  useEffect(() => {\n    exploreStore.getState().setActiveConnector(undefined)\n    actionPromptStore.getState().clearActions()\n  }, [activeSpaceId, exploreStore, actionPromptStore])\n\n  const switchActiveSpace = useCallback(\n    (targetId: string, targetSpace: CaveSpace, type: 'seamless' | 'portal') => {\n      const explore = exploreStore.getState()\n      const fromId = explore.activeSpaceId ?? primaryIdRef.current ?? ''\n\n      if (type === 'seamless') {\n        explore.setConnectorEnterSuppressUntil(performance.now() + SEAMLESS_GHOST_ENTER_WINDOW_MS)\n      }\n\n      // Mark the heavy downstream work (active scene's custom objects mounting,\n      // physics body re-wiring) as non-urgent so input handling stays responsive.\n      startTransition(() => {\n        explore.setActiveSpaceId(targetId)\n        worldStore.getState().setSpaceConfig(targetSpace)\n      })\n\n      actionPromptStore.getState().clearActions()\n      eventBus.emit('connector:transition', { from: fromId, to: targetId, type })\n    },\n    [exploreStore, worldStore, actionPromptStore, eventBus]\n  )\n\n  useCaveEvent('connector:enter', ({ connector }) => {\n    const state = exploreStore.getState()\n\n    // Ghost-enter guard. Note: we deliberately don't consume the timestamp here\n    // — `useExploreActions` registers its own `connector:enter` handler on the\n    // same bus, and consume-on-first-read would let one handler see the ghost\n    // while the other sees a clean state, causing a spurious portal panel for\n    // connectors with mixed seamless + portal targets.\n    if (performance.now() < state.connectorEnterSuppressUntil) return\n    // Ignore enters from a previous scene's still-mounted sensors mid-transition.\n    if (!isConnectorInActiveSpace(state, connector)) return\n\n    const targets = connector.connectorInfo.to\n    const seamless = targets.find((t) => t.transitionType === 'seamless')\n\n    if (seamless) {\n      const targetSpace = state.connectedSpaces[seamless.caveWorldId]\n      if (!targetSpace || !state.readySpaceIds[seamless.caveWorldId]) return\n      switchActiveSpace(seamless.caveWorldId, targetSpace, 'seamless')\n      return\n    }\n\n    if (targets.some((t) => t.transitionType === 'portal')) {\n      state.setActiveConnector(connector)\n    }\n  })\n\n  useCaveEvent('connector:leave', ({ connector }) => {\n    const state = exploreStore.getState()\n    if (!isConnectorInActiveSpace(state, connector)) return\n    state.setActiveConnector(undefined)\n  })\n\n  useCaveEvent('connector:portal:select', ({ target }) => {\n    const targetId = target.caveWorldId\n    const state = exploreStore.getState()\n    const targetSpace = state.connectedSpaces[targetId]\n    if (!targetSpace || !state.readySpaceIds[targetId]) return\n\n    if (target.connectorId) {\n      const targetConnector = findConnectorById(targetSpace, target.connectorId)\n      if (targetConnector && characterRef.current) {\n        const { position, quaternion } = computePortalSpawnPose(\n          targetConnector,\n          targetSpace.baseLayer.transform,\n          matrixFromM16(state.spaceTransforms[targetId])\n        )\n        applyCharacterPose(characterRef.current, position, quaternion)\n      }\n    }\n\n    state.setActiveConnector(undefined)\n    switchActiveSpace(targetId, targetSpace, 'portal')\n  })\n}\n"],"names":["SEAMLESS_GHOST_ENTER_WINDOW_MS","useConnectorTransitions","primarySpaceId","characterRef","eventBus","useCaveEventBus","worldStore","useCaveWorldStoreApi","exploreStore","useCaveExploreStore","actionPromptStore","useActionPromptStore","primaryIdRef","useRef","useEffect","activeSpaceId","useCaveExplore","s","switchActiveSpace","useCallback","targetId","targetSpace","type","explore","fromId","startTransition","useCaveEvent","connector","state","isConnectorInActiveSpace","targets","seamless","t","target","targetConnector","findConnectorById","position","quaternion","computePortalSpawnPose","matrixFromM16","applyCharacterPose"],"mappings":";;;;;;;AA+BO,MAAMA,IAAiC;AAUvC,SAASC,EACdC,GACAC,GACM;AACN,QAAMC,IAAWC,EAAA,GACXC,IAAaC,EAAA,GACbC,IAAeC,EAAA,GACfC,IAAoBC,EAAA,GAGpBC,IAAeC,EAAOX,CAAc;AAC1C,EAAAY,EAAU,MAAM;AACd,IAAAF,EAAa,UAAUV;AAAA,EACzB,GAAG,CAACA,CAAc,CAAC;AASnB,QAAMa,IAAgBC,EAAe,CAACC,MAAMA,EAAE,aAAa;AAC3D,EAAAH,EAAU,MAAM;AACd,IAAAN,EAAa,SAAA,EAAW,mBAAmB,MAAS,GACpDE,EAAkB,SAAA,EAAW,aAAA;AAAA,EAC/B,GAAG,CAACK,GAAeP,GAAcE,CAAiB,CAAC;AAEnD,QAAMQ,IAAoBC;AAAA,IACxB,CAACC,GAAkBC,GAAwBC,MAAgC;AACzE,YAAMC,IAAUf,EAAa,SAAA,GACvBgB,IAASD,EAAQ,iBAAiBX,EAAa,WAAW;AAEhE,MAAIU,MAAS,cACXC,EAAQ,+BAA+B,YAAY,IAAA,IAAQvB,CAA8B,GAK3FyB,EAAgB,MAAM;AACpB,QAAAF,EAAQ,iBAAiBH,CAAQ,GACjCd,EAAW,SAAA,EAAW,eAAee,CAAW;AAAA,MAClD,CAAC,GAEDX,EAAkB,SAAA,EAAW,aAAA,GAC7BN,EAAS,KAAK,wBAAwB,EAAE,MAAMoB,GAAQ,IAAIJ,GAAU,MAAAE,GAAM;AAAA,IAC5E;AAAA,IACA,CAACd,GAAcF,GAAYI,GAAmBN,CAAQ;AAAA,EAAA;AAGxD,EAAAsB,EAAa,mBAAmB,CAAC,EAAE,WAAAC,QAAgB;AACjD,UAAMC,IAAQpB,EAAa,SAAA;AAS3B,QAFI,YAAY,QAAQoB,EAAM,+BAE1B,CAACC,EAAyBD,GAAOD,CAAS,EAAG;AAEjD,UAAMG,IAAUH,EAAU,cAAc,IAClCI,IAAWD,EAAQ,KAAK,CAACE,MAAMA,EAAE,mBAAmB,UAAU;AAEpE,QAAID,GAAU;AACZ,YAAMV,IAAcO,EAAM,gBAAgBG,EAAS,WAAW;AAC9D,UAAI,CAACV,KAAe,CAACO,EAAM,cAAcG,EAAS,WAAW,EAAG;AAChE,MAAAb,EAAkBa,EAAS,aAAaV,GAAa,UAAU;AAC/D;AAAA,IACF;AAEA,IAAIS,EAAQ,KAAK,CAACE,MAAMA,EAAE,mBAAmB,QAAQ,KACnDJ,EAAM,mBAAmBD,CAAS;AAAA,EAEtC,CAAC,GAEDD,EAAa,mBAAmB,CAAC,EAAE,WAAAC,QAAgB;AACjD,UAAMC,IAAQpB,EAAa,SAAA;AAC3B,IAAKqB,EAAyBD,GAAOD,CAAS,KAC9CC,EAAM,mBAAmB,MAAS;AAAA,EACpC,CAAC,GAEDF,EAAa,2BAA2B,CAAC,EAAE,QAAAO,QAAa;AACtD,UAAMb,IAAWa,EAAO,aAClBL,IAAQpB,EAAa,SAAA,GACrBa,IAAcO,EAAM,gBAAgBR,CAAQ;AAClD,QAAI,GAACC,KAAe,CAACO,EAAM,cAAcR,CAAQ,IAEjD;AAAA,UAAIa,EAAO,aAAa;AACtB,cAAMC,IAAkBC,EAAkBd,GAAaY,EAAO,WAAW;AACzE,YAAIC,KAAmB/B,EAAa,SAAS;AAC3C,gBAAM,EAAE,UAAAiC,GAAU,YAAAC,EAAA,IAAeC;AAAA,YAC/BJ;AAAA,YACAb,EAAY,UAAU;AAAA,YACtBkB,EAAcX,EAAM,gBAAgBR,CAAQ,CAAC;AAAA,UAAA;AAE/C,UAAAoB,EAAmBrC,EAAa,SAASiC,GAAUC,CAAU;AAAA,QAC/D;AAAA,MACF;AAEA,MAAAT,EAAM,mBAAmB,MAAS,GAClCV,EAAkBE,GAAUC,GAAa,QAAQ;AAAA;AAAA,EACnD,CAAC;AACH;"}

package/dist/explore/hooks/use-explore-actions.d.ts

@@ -0,0 +1,17 @@
+import type { CustomObject, PortalProps } from '../../types/index.js';
+/**
+ * Decides what happens when the player activates a `portal` object.
+ *
+ * Return `true` if you handled the navigation. The default behavior only opens
+ * absolute `http(s)` URLs in a new tab; anything else (in-app routes, deep
+ * links) is left to the host, since the SDK cannot know your router.
+ */
+export type PortalNavigateHandler = (portal: PortalProps, object: CustomObject) => boolean | void;
+/**
+ * Turn object / connector proximity events into action prompts.
+ *
+ * Everything flows through the event bus and the action-prompt store, so no
+ * overlay needs a direct reference to the scene or the character.
+ */
+export declare function useExploreActions(onPortalNavigate?: PortalNavigateHandler): void;
+//# sourceMappingURL=use-explore-actions.d.ts.map

package/dist/explore/hooks/use-explore-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-explore-actions.d.ts","sourceRoot":"","sources":["../../../explore/hooks/use-explore-actions.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAIV,YAAY,EACZ,WAAW,EACZ,MAAM,aAAa,CAAA;AAWpB;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,KAAK,OAAO,GAAG,IAAI,CAAA;AAmDjG;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,gBAAgB,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAsJhF"}

package/dist/explore/hooks/use-explore-actions.js

@@ -0,0 +1,134 @@
+import { useCallback as b } from "react";
+import { useCaveEventBus as h, useCaveWorldMessages as y, useCaveWorldStoreApi as P } from "../../core/context/cave-world-context.js";
+import { useCaveEvent as c } from "../../core/hooks/use-cave-event.js";
+import { formatMessage as w } from "../../core/i18n/messages.js";
+import { getConnectorPortalTargets as g, isConnectorPortalNavigable as v, isPortalTargetReady as A } from "../../core/connector-label/readiness.js";
+import { isConnectorInActiveSpace as m } from "../stores/cave-explore.store.js";
+import { useCaveExploreStore as I, useActionPromptStore as E } from "../stores/explore-context.js";
+const T = 1.8, x = 9;
+function B(u) {
+  try {
+    const n = new URL(u);
+    return n.protocol === "http:" || n.protocol === "https:";
+  } catch {
+    return !1;
+  }
+}
+function U(u, n, l, f, s) {
+  const r = g(u), p = r.map(
+    (o) => A(o, n, l)
+  ), t = p.filter(Boolean).length;
+  let e = 0;
+  return r.map((o, i) => {
+    const a = p[i], d = n[o.caveWorldId]?.metadata?.name ?? f.actionPanel.unknownDestination, S = a ? e++ : -1, C = a ? t === 1 ? "F" : S < x ? String(S + 1) : void 0 : void 0;
+    return {
+      id: `connector-portal-${o.caveWorldId}-${o.connectorId ?? ""}`,
+      label: a ? d : w(f.connector.targetLoading, { name: d }),
+      shortcut: C,
+      disabled: !a,
+      onAction: () => {
+        a && s(o);
+      }
+    };
+  });
+}
+function H(u) {
+  const n = h(), l = y(), f = P(), s = I(), r = E(), p = b(
+    (t) => {
+      const { connectedSpaces: e, readySpaceIds: o } = s.getState(), { showActions: i } = r.getState();
+      if (g(t).length === 0) return;
+      if (!v(t, e, o)) {
+        i(
+          [
+            {
+              id: "connector-loading",
+              label: l.connector.loadingPanelLabel,
+              disabled: !0,
+              onAction: () => {
+              }
+            }
+          ],
+          null,
+          "panel"
+        );
+        return;
+      }
+      const a = U(
+        t,
+        e,
+        o,
+        l,
+        (d) => n.emit("connector:portal:select", { connector: t, target: d })
+      );
+      i(a, null, "panel");
+    },
+    [s, r, l, n]
+  );
+  c("object:enter", ({ object: t }) => {
+    if (f.getState().detailVisible) return;
+    const { showActions: e } = r.getState();
+    if (t.type === "portal" && t.portal) {
+      const o = t.portal, [i, a, d] = t.transform.position;
+      e(
+        [
+          {
+            id: "portal",
+            label: l.actions.enterPortal,
+            shortcut: "F",
+            onAction: () => {
+              n.emit("object:interact", { object: t, action: "portal" }), u?.(o, t) !== !0 && B(o.url) && window.open(o.url, "_blank", "noopener,noreferrer");
+            }
+          }
+        ],
+        [i, a + T, d],
+        "bubble"
+      );
+      return;
+    }
+    t.components?.Window && e(
+      [
+        {
+          id: "detail",
+          label: l.actions.viewDetail,
+          shortcut: "F",
+          onAction: () => {
+            n.emit("object:interact", { object: t, action: "detail" }), n.emit("detail:open", { object: t });
+          }
+        }
+      ],
+      [...t.transform.position],
+      "bubble"
+    );
+  }), c("object:leave", () => {
+    r.getState().clearActions();
+  }), c("detail:open", () => {
+    r.getState().clearActions();
+  }), c("connector:transition", () => {
+    r.getState().clearActions();
+  }), c("connector:enter", ({ connector: t }) => {
+    const e = s.getState();
+    performance.now() < e.connectorEnterSuppressUntil || m(e, t) && p(t);
+  }), c("connector:label:click", ({ connector: t }) => {
+    const { connectedSpaces: e, readySpaceIds: o } = s.getState();
+    if (!v(t, e, o)) return;
+    const i = g(t).filter(
+      (a) => A(a, e, o)
+    );
+    if (i.length === 1) {
+      n.emit("connector:portal:select", { connector: t, target: i[0] });
+      return;
+    }
+    p(t);
+  }), c("space:transfer:ready", () => {
+    const t = s.getState(), { activeConnector: e } = t;
+    e && m(t, e) && p(e);
+  }), c("connector:leave", ({ connector: t }) => {
+    m(s.getState(), t) && r.getState().clearActions();
+  }), c("connector:portal:select", () => {
+    r.getState().clearActions();
+  });
+}
+export {
+  H as useExploreActions
+};
+//# sourceMappingURL=use-explore-actions.js.map

package/dist/explore/hooks/use-explore-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-explore-actions.js","sources":["../../../explore/hooks/use-explore-actions.ts"],"sourcesContent":["import { useCallback } from 'react'\nimport {\n  formatMessage,\n  getConnectorPortalTargets,\n  isConnectorPortalNavigable,\n  isPortalTargetReady,\n  useCaveEvent,\n  useCaveEventBus,\n  useCaveWorldMessages,\n  useCaveWorldStoreApi,\n  type CaveWorldMessages\n} from '../../core'\nimport type {\n  CaveSpace,\n  ConnectorDef,\n  ConnectorTarget,\n  CustomObject,\n  PortalProps\n} from '../../types'\nimport type { ActionDef } from '../stores/action-prompt.store'\nimport { isConnectorInActiveSpace } from '../stores/cave-explore.store'\nimport { useActionPromptStore, useCaveExploreStore } from '../stores/explore-context'\n\n/** Height above an object's origin where the \"press F\" bubble is anchored. */\nconst PORTAL_BUBBLE_HEIGHT_M = 1.8\n\n/** Max destinations that get a number-key shortcut (1–9). */\nconst MAX_NUMERIC_SHORTCUTS = 9\n\n/**\n * Decides what happens when the player activates a `portal` object.\n *\n * Return `true` if you handled the navigation. The default behavior only opens\n * absolute `http(s)` URLs in a new tab; anything else (in-app routes, deep\n * links) is left to the host, since the SDK cannot know your router.\n */\nexport type PortalNavigateHandler = (portal: PortalProps, object: CustomObject) => boolean | void\n\nfunction isHttpUrl(url: string): boolean {\n  try {\n    const parsed = new URL(url)\n    return parsed.protocol === 'http:' || parsed.protocol === 'https:'\n  } catch {\n    return false\n  }\n}\n\nfunction buildConnectorPortalActions(\n  connector: ConnectorDef,\n  connectedSpaces: Record<string, CaveSpace>,\n  readySpaceIds: Record<string, true>,\n  messages: CaveWorldMessages,\n  onSelect: (target: ConnectorTarget) => void\n): ActionDef[] {\n  const portalTargets = getConnectorPortalTargets(connector)\n  const readyFlags = portalTargets.map((target) =>\n    isPortalTargetReady(target, connectedSpaces, readySpaceIds)\n  )\n  const readyCount = readyFlags.filter(Boolean).length\n\n  let readyIndex = 0\n  return portalTargets.map((target, index) => {\n    const ready = readyFlags[index]\n    const name =\n      connectedSpaces[target.caveWorldId]?.metadata?.name ?? messages.actionPanel.unknownDestination\n    const ordinal = ready ? readyIndex++ : -1\n\n    const shortcut = !ready\n      ? undefined\n      : readyCount === 1\n        ? 'F'\n        : ordinal < MAX_NUMERIC_SHORTCUTS\n          ? String(ordinal + 1)\n          : undefined\n\n    return {\n      id: `connector-portal-${target.caveWorldId}-${target.connectorId ?? ''}`,\n      label: ready ? name : formatMessage(messages.connector.targetLoading, { name }),\n      shortcut,\n      disabled: !ready,\n      onAction: () => {\n        if (ready) onSelect(target)\n      }\n    }\n  })\n}\n\n/**\n * Turn object / connector proximity events into action prompts.\n *\n * Everything flows through the event bus and the action-prompt store, so no\n * overlay needs a direct reference to the scene or the character.\n */\nexport function useExploreActions(onPortalNavigate?: PortalNavigateHandler): void {\n  const eventBus = useCaveEventBus()\n  const messages = useCaveWorldMessages()\n  const worldStore = useCaveWorldStoreApi()\n  const exploreStore = useCaveExploreStore()\n  const actionPromptStore = useActionPromptStore()\n\n  const showConnectorPortalPanel = useCallback(\n    (connector: ConnectorDef) => {\n      const { connectedSpaces, readySpaceIds } = exploreStore.getState()\n      const { showActions } = actionPromptStore.getState()\n      if (getConnectorPortalTargets(connector).length === 0) return\n\n      if (!isConnectorPortalNavigable(connector, connectedSpaces, readySpaceIds)) {\n        showActions(\n          [\n            {\n              id: 'connector-loading',\n              label: messages.connector.loadingPanelLabel,\n              disabled: true,\n              onAction: () => {}\n            }\n          ],\n          null,\n          'panel'\n        )\n        return\n      }\n\n      const actions = buildConnectorPortalActions(\n        connector,\n        connectedSpaces,\n        readySpaceIds,\n        messages,\n        (target) => eventBus.emit('connector:portal:select', { connector, target })\n      )\n      showActions(actions, null, 'panel')\n    },\n    [exploreStore, actionPromptStore, messages, eventBus]\n  )\n\n  // ── Object interactions (detail window + portal objects) ──\n\n  useCaveEvent('object:enter', ({ object }) => {\n    if (worldStore.getState().detailVisible) return\n    const { showActions } = actionPromptStore.getState()\n\n    if (object.type === 'portal' && object.portal) {\n      const portal = object.portal\n      const [x, y, z] = object.transform.position\n      showActions(\n        [\n          {\n            id: 'portal',\n            label: messages.actions.enterPortal,\n            shortcut: 'F',\n            onAction: () => {\n              eventBus.emit('object:interact', { object, action: 'portal' })\n              if (onPortalNavigate?.(portal, object) === true) return\n              // Default: only absolute web URLs are safe to act on without\n              // knowing the host's routing. Everything else stays an event.\n              if (isHttpUrl(portal.url)) {\n                window.open(portal.url, '_blank', 'noopener,noreferrer')\n              }\n            }\n          }\n        ],\n        [x, y + PORTAL_BUBBLE_HEIGHT_M, z],\n        'bubble'\n      )\n      return\n    }\n\n    if (object.components?.Window) {\n      showActions(\n        [\n          {\n            id: 'detail',\n            label: messages.actions.viewDetail,\n            shortcut: 'F',\n            onAction: () => {\n              eventBus.emit('object:interact', { object, action: 'detail' })\n              eventBus.emit('detail:open', { object })\n            }\n          }\n        ],\n        [...object.transform.position],\n        'bubble'\n      )\n    }\n  })\n\n  useCaveEvent('object:leave', () => {\n    actionPromptStore.getState().clearActions()\n  })\n\n  useCaveEvent('detail:open', () => {\n    actionPromptStore.getState().clearActions()\n  })\n\n  useCaveEvent('connector:transition', () => {\n    actionPromptStore.getState().clearActions()\n  })\n\n  // ── Connector portal interactions ──\n\n  useCaveEvent('connector:enter', ({ connector }) => {\n    const state = exploreStore.getState()\n    // Same ghost-enter guard as `useConnectorTransitions`: drop events fired\n    // immediately after a seamless transition while the character is still\n    // inside the new active scene's matching connector box.\n    if (performance.now() < state.connectorEnterSuppressUntil) return\n    if (!isConnectorInActiveSpace(state, connector)) return\n    showConnectorPortalPanel(connector)\n  })\n\n  useCaveEvent('connector:label:click', ({ connector }) => {\n    const { connectedSpaces, readySpaceIds } = exploreStore.getState()\n    if (!isConnectorPortalNavigable(connector, connectedSpaces, readySpaceIds)) return\n\n    const readyTargets = getConnectorPortalTargets(connector).filter((target) =>\n      isPortalTargetReady(target, connectedSpaces, readySpaceIds)\n    )\n\n    // A single ready destination needs no picker — behave like pressing F.\n    if (readyTargets.length === 1) {\n      eventBus.emit('connector:portal:select', { connector, target: readyTargets[0] })\n      return\n    }\n    showConnectorPortalPanel(connector)\n  })\n\n  // A destination finishing its preload should refresh an open picker so the\n  // greyed-out row becomes selectable without the player walking out and back in.\n  useCaveEvent('space:transfer:ready', () => {\n    const state = exploreStore.getState()\n    const { activeConnector } = state\n    if (!activeConnector) return\n    if (!isConnectorInActiveSpace(state, activeConnector)) return\n    showConnectorPortalPanel(activeConnector)\n  })\n\n  useCaveEvent('connector:leave', ({ connector }) => {\n    if (!isConnectorInActiveSpace(exploreStore.getState(), connector)) return\n    actionPromptStore.getState().clearActions()\n  })\n\n  useCaveEvent('connector:portal:select', () => {\n    actionPromptStore.getState().clearActions()\n  })\n}\n"],"names":["PORTAL_BUBBLE_HEIGHT_M","MAX_NUMERIC_SHORTCUTS","isHttpUrl","url","parsed","buildConnectorPortalActions","connector","connectedSpaces","readySpaceIds","messages","onSelect","portalTargets","getConnectorPortalTargets","readyFlags","target","isPortalTargetReady","readyCount","readyIndex","index","ready","name","ordinal","shortcut","formatMessage","useExploreActions","onPortalNavigate","eventBus","useCaveEventBus","useCaveWorldMessages","worldStore","useCaveWorldStoreApi","exploreStore","useCaveExploreStore","actionPromptStore","useActionPromptStore","showConnectorPortalPanel","useCallback","showActions","isConnectorPortalNavigable","actions","useCaveEvent","object","portal","x","y","z","state","isConnectorInActiveSpace","readyTargets","activeConnector"],"mappings":"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"}

package/dist/explore/hooks/use-load-error-notify.d.ts

@@ -0,0 +1,11 @@
+import { type SpaceLoadError } from '../../core/index.js';
+/**
+ * Invoke `onLoadError` once each time a terminal space/splat load failure is
+ * recorded on the per-instance store (`spaceLoadError` transitions to a value).
+ *
+ * Uses an imperative store subscription (with a manual diff) so it never
+ * re-renders the host component, and reads the latest callback from a ref.
+ * Shared by `CaveExplore` and `CaveOrbitViewer`.
+ */
+export declare function useLoadErrorNotify(onLoadError?: (error: SpaceLoadError) => void): void;
+//# sourceMappingURL=use-load-error-notify.d.ts.map

package/dist/explore/hooks/use-load-error-notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-load-error-notify.d.ts","sourceRoot":"","sources":["../../../explore/hooks/use-load-error-notify.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,YAAY,CAAA;AAE9D;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,QAe/E"}

package/dist/explore/hooks/use-load-error-notify.js

@@ -0,0 +1,18 @@
+import { useRef as u, useEffect as c } from "react";
+import { useCaveWorld as n } from "../../core/context/cave-world-context.js";
+function p(e) {
+  const { store: t } = n(), o = u(e);
+  c(() => {
+    o.current = e;
+  }, [e]), c(() => {
+    let s = t.getState().spaceLoadError;
+    return t.subscribe((f) => {
+      const r = f.spaceLoadError;
+      r !== s && (s = r, r && o.current?.(r));
+    });
+  }, [t]);
+}
+export {
+  p as useLoadErrorNotify
+};
+//# sourceMappingURL=use-load-error-notify.js.map

package/dist/explore/hooks/use-load-error-notify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-load-error-notify.js","sources":["../../../explore/hooks/use-load-error-notify.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport { useCaveWorld, type SpaceLoadError } from '../../core'\n\n/**\n * Invoke `onLoadError` once each time a terminal space/splat load failure is\n * recorded on the per-instance store (`spaceLoadError` transitions to a value).\n *\n * Uses an imperative store subscription (with a manual diff) so it never\n * re-renders the host component, and reads the latest callback from a ref.\n * Shared by `CaveExplore` and `CaveOrbitViewer`.\n */\nexport function useLoadErrorNotify(onLoadError?: (error: SpaceLoadError) => void) {\n  const { store } = useCaveWorld()\n  const onLoadErrorRef = useRef(onLoadError)\n  useEffect(() => {\n    onLoadErrorRef.current = onLoadError\n  }, [onLoadError])\n  useEffect(() => {\n    let prev = store.getState().spaceLoadError\n    return store.subscribe((state) => {\n      const error = state.spaceLoadError\n      if (error === prev) return\n      prev = error\n      if (error) onLoadErrorRef.current?.(error)\n    })\n  }, [store])\n}\n"],"names":["useLoadErrorNotify","onLoadError","store","useCaveWorld","onLoadErrorRef","useRef","useEffect","prev","state","error"],"mappings":";;AAWO,SAASA,EAAmBC,GAA+C;AAChF,QAAM,EAAE,OAAAC,EAAA,IAAUC,EAAA,GACZC,IAAiBC,EAAOJ,CAAW;AACzC,EAAAK,EAAU,MAAM;AACd,IAAAF,EAAe,UAAUH;AAAA,EAC3B,GAAG,CAACA,CAAW,CAAC,GAChBK,EAAU,MAAM;AACd,QAAIC,IAAOL,EAAM,SAAA,EAAW;AAC5B,WAAOA,EAAM,UAAU,CAACM,MAAU;AAChC,YAAMC,IAAQD,EAAM;AACpB,MAAIC,MAAUF,MACdA,IAAOE,GACHA,KAAOL,EAAe,UAAUK,CAAK;AAAA,IAC3C,CAAC;AAAA,EACH,GAAG,CAACP,CAAK,CAAC;AACZ;"}