@found-in-space/skykit 0.2.0-alpha.1 → 0.2.0-alpha.20260528

package/src/plugins.js

@@ -1,10 +1,5 @@
 import * as THREE from 'three';
 
-import {
-  createJourneyController,
-  createTimedJourneyEvaluator,
-} from '@found-in-space/journey';
-
 import {
   combineStrategies,
   createLookaheadStrategy,
@@ -16,9 +11,9 @@ import {
 
 import {
   IDENTITY_QUATERNION as SPATIAL_IDENTITY_QUATERNION,
-  createOrbitTransferRoute,
   createSpatialPoseTransition,
   createSpatialNavigationAutomation,
+  resolveSpatialLookAt,
   resolveSpatialTarget,
 } from '@found-in-space/spatial';
 
@@ -219,8 +214,12 @@ export function createSkykitNavigationPlugin(options = {}) {
     id,
     setup(context) {
       const threeContext = /** @type {import('./index.d.ts').SkykitThreePluginContext} */ (context);
-      threeContext.addPart(part);
-      threeContext.addDisposable(registerNavigationActions(threeContext));
+      const removePart = threeContext.addPart(part);
+      const unregisterActions = registerNavigationActions(threeContext);
+      return () => {
+        unregisterActions();
+        removePart();
+      };
     },
     getSnapshot: () => part.getSnapshot?.() ?? null,
   };
@@ -366,10 +365,24 @@ export function createSkykitNavigationPlugin(options = {}) {
     const position = positionInput === undefined
       ? current.observerPc
       : await resolveTarget(positionInput, context) ?? current.observerPc;
+    const lookAtInput = targetSource.lookAt;
+    const resolvedLook = lookAtInput !== undefined
+      ? await resolveSpatialLookAt(lookAtInput, {
+        observerPc: position,
+        resolveBookmark: typeof options.resolveBookmark === 'function'
+          ? (bookmarkId, original) => options.resolveBookmark?.(
+            bookmarkId,
+            /** @type {import('@found-in-space/spatial').SpatialTargetInput} */ (original),
+            context,
+          ) ?? null
+          : undefined,
+      })
+      : null;
     const orientationInput = targetSource.orientationIcrs
       ?? (targetSource.orientation && isQuaternionLike(targetSource.orientation) ? targetSource.orientation : undefined)
       ?? source.orientationIcrs;
-    const orientation = normalizeQuaternion(orientationInput, current.orientationIcrs ?? IDENTITY_QUATERNION);
+    const orientation = resolvedLook?.orientationIcrs
+      ?? normalizeQuaternion(orientationInput, current.orientationIcrs ?? IDENTITY_QUATERNION);
     return createSpatialPoseTransition({
       from: {
         position: current.observerPc,
@@ -389,575 +402,6 @@ export function createSkykitNavigationPlugin(options = {}) {
   }
 }
 
-/**
- * @param {import('./index.d.ts').SkykitJourneyPluginOptions} [options]
- * @returns {SkykitPlugin & { getSnapshot(): unknown }}
- */
-export function createSkykitJourneyPlugin(options = {}) {
-  const id = options.id ?? 'journey';
-  const controller = options.controller
-    ?? (options.journey
-      ? createJourneyController({ graph: options.journey })
-      : (options.graph || options.scenes ? createJourneyController(options) : null));
-  const evaluator = options.evaluator
-    ?? (options.timedJourney ? createTimedJourneyEvaluator(options.timedJourney, options.evaluatorOptions) : null);
-  let disposed = false;
-  let playing = options.autoPlay === true;
-  let currentTimeSecs = Math.max(0, finiteNumber(options.startTimeSecs, 0));
-  let lastCueId = /** @type {string | null} */ (null);
-  let initialSceneApplied = false;
-  let timedPreloadHintsEmitted = false;
-  /** @type {import('./index.d.ts').SkykitThreePluginContext | null} */
-  let pluginContext = null;
-  const resolvedJourneyOrbits = new Map();
-  /** @type {(() => void) | null} */
-  let unsubscribeController = null;
-  /** @type {Promise<unknown>} */
-  let pendingSceneApplication = Promise.resolve(null);
-
-  /** @type {SkykitThreePart} */
-  const part = {
-    id,
-    priority: options.priority,
-    attach(context) {
-      pluginContext = context;
-      if (controller) {
-        unsubscribeController = controller.subscribe((event) => {
-          queueSceneApplication(event.spec, context, event);
-        });
-        applyInitialScene(context);
-      }
-      emitTimedPreloadHints(context, 'attach');
-    },
-    update(frame) {
-      if (disposed || !evaluator || !playing) return;
-      currentTimeSecs = Math.min(
-        evaluator.durationSecs,
-        currentTimeSecs + Math.max(0, finiteNumber(frame.deltaSeconds, 0)),
-      );
-      applyTimedFrame(evaluator.evaluate(currentTimeSecs), frame);
-      if (currentTimeSecs >= evaluator.durationSecs) {
-        playing = options.loop === true;
-        currentTimeSecs = playing ? 0 : evaluator.durationSecs;
-      }
-    },
-    detach() {
-      unsubscribeController?.();
-      unsubscribeController = null;
-      pluginContext = null;
-    },
-    dispose() {
-      disposed = true;
-      this.detach?.();
-      if (options.disposeController !== false) controller?.dispose?.();
-    },
-    getSnapshot,
-  };
-
-  return {
-    id,
-    setup(context) {
-      const threeContext = /** @type {import('./index.d.ts').SkykitThreePluginContext} */ (context);
-      threeContext.addPart(part);
-      threeContext.addDisposable(registerJourneyActions(threeContext));
-    },
-    getSnapshot,
-  };
-
-  /** @param {import('./index.d.ts').SkykitThreePluginContext} context */
-  function registerJourneyActions(context) {
-    const unregisters = [
-      context.actions.registerAction(SKYKIT_ACTIONS.journey.goToChapter, async ({ payload }) => {
-        await pendingSceneApplication;
-        const sceneId = resolveSceneId(payload);
-        const spec = sceneId && controller ? controller.goTo(sceneId, { source: SKYKIT_ACTIONS.journey.goToChapter }) : null;
-        await pendingSceneApplication;
-        return spec;
-      }, { label: 'Go to journey chapter' }),
-      context.actions.registerAction(SKYKIT_ACTIONS.journey.next, async () => {
-        await pendingSceneApplication;
-        const spec = controller?.next({ source: SKYKIT_ACTIONS.journey.next }) ?? null;
-        await pendingSceneApplication;
-        return spec;
-      }, {
-        label: 'Next journey chapter',
-      }),
-      context.actions.registerAction(SKYKIT_ACTIONS.journey.previous, async () => {
-        await pendingSceneApplication;
-        const spec = controller?.previous({ source: SKYKIT_ACTIONS.journey.previous }) ?? null;
-        await pendingSceneApplication;
-        return spec;
-      }, {
-        label: 'Previous journey chapter',
-      }),
-      context.actions.registerAction(SKYKIT_ACTIONS.journey.seek, ({ payload }) => {
-        currentTimeSecs = clampTime(resolveTimeSecs(payload), evaluator?.durationSecs ?? Number.POSITIVE_INFINITY);
-        if (evaluator) applyTimedFrame(evaluator.evaluate(currentTimeSecs), { viewer: context.viewer, view: context.getViewState() });
-        emitTimedPreloadHints(context, 'seek');
-        return currentTimeSecs;
-      }, { label: 'Seek journey time' }),
-      context.actions.registerAction(SKYKIT_ACTIONS.journey.play, ({ payload }) => {
-        if (payload && typeof payload === 'object' && 'timeSecs' in payload) {
-          currentTimeSecs = clampTime(resolveTimeSecs(payload), evaluator?.durationSecs ?? Number.POSITIVE_INFINITY);
-        }
-        playing = true;
-        emitTimedPreloadHints(context, 'play');
-        return currentTimeSecs;
-      }, { label: 'Play journey' }),
-      context.actions.registerAction(SKYKIT_ACTIONS.journey.pause, () => {
-        playing = false;
-        return currentTimeSecs;
-      }, { label: 'Pause journey' }),
-    ];
-    return () => {
-      for (const unregister of unregisters.reverse()) unregister();
-    };
-  }
-
-  /** @param {import('./index.d.ts').SkykitThreePluginContext} context */
-  function applyInitialScene(context) {
-    if (!controller || initialSceneApplied) return;
-    const snapshot = controller.getSnapshot();
-    const sceneId = snapshot.activeSceneId;
-    if (!sceneId) {
-      initialSceneApplied = true;
-      return;
-    }
-    initialSceneApplied = true;
-    const spec = controller.graph.resolveSceneSpec(sceneId, { fromSceneId: snapshot.previousSceneId });
-    queueSceneApplication(spec, context, {
-      type: 'journey/initial',
-      sceneId,
-      previousSceneId: snapshot.previousSceneId,
-      source: 'attach',
-      spec,
-    });
-  }
-
-  /**
-   * @param {unknown} spec
-   * @param {import('./index.d.ts').SkykitThreePluginContext} context
-   * @param {unknown} event
-   */
-  function queueSceneApplication(spec, context, event) {
-    pendingSceneApplication = Promise.resolve(applySceneSpec(spec, context, event)).catch((error) => {
-      context.emit?.({
-        type: 'journey/scene/error',
-        pluginId: id,
-        message: 'Failed to apply journey scene.',
-        error,
-        event,
-      });
-      return null;
-    });
-    return pendingSceneApplication;
-  }
-
-  /**
-   * @param {import('./index.d.ts').SkykitThreePluginContext} context
-   * @param {string} source
-   */
-  function emitTimedPreloadHints(context, source) {
-    if (!evaluator || timedPreloadHintsEmitted) return;
-    const preloadHints = typeof evaluator.getPreloadHints === 'function'
-      ? evaluator.getPreloadHints()
-      : evaluator.evaluate(currentTimeSecs).preloadHints;
-    timedPreloadHintsEmitted = true;
-    if (preloadHints.length > 0) {
-      options.onPreloadHints?.(preloadHints, {
-        type: 'journey/timed-preload',
-        journeyId: evaluator.journey.id,
-        source,
-      }, context);
-    }
-  }
-
-  /**
-   * @param {unknown} spec
-   * @param {import('./index.d.ts').SkykitThreePluginContext} context
-   * @param {unknown} event
-   */
-  async function applySceneSpec(spec, context, event) {
-    const scene = /** @type {Record<string, unknown> | null} */ (spec && typeof spec === 'object' ? spec : null);
-    options.onScene?.(scene, context, event);
-    if (!scene) return;
-    const onArrive = () => {
-      void notifySceneArrive(scene, context, event);
-    };
-    let arrivalDeferred = false;
-    if (scene.view && typeof scene.view === 'object') {
-      context.requestViewState(/** @type {Partial<import('./index.d.ts').SkykitViewState>} */ (scene.view), id);
-    }
-    const navigation = /** @type {Record<string, unknown> | null} */ (scene.navigation && typeof scene.navigation === 'object' ? scene.navigation : null);
-    if (isOrbitCameraScene(scene)) {
-      arrivalDeferred = await applyOrbitCameraScene(scene, context, event, onArrive);
-    } else if (navigation?.transitionTo) {
-      const travel = normalizeJourneySceneTravel(scene.travel);
-      const explicitRoutePoints = await resolveJourneyRoutePoints(scene, travel, context);
-      const results = explicitRoutePoints.length >= 2
-        ? await context.actions.invoke(SKYKIT_ACTIONS.navigation.flyPolyline, {
-          points: explicitRoutePoints,
-          durationSecs: travel.durationSecs,
-          arrivalThreshold: travel.arrivalThreshold,
-          onArrive: () => {
-            void context.actions.invoke(SKYKIT_ACTIONS.navigation.transitionTo, {
-              ...createRouteArrivalTransitionPayload(navigation.transitionTo),
-              onArrive,
-            }, {
-              source: id,
-            });
-          },
-        }, {
-          source: id,
-        })
-        : await context.actions.invoke(SKYKIT_ACTIONS.navigation.transitionTo, {
-          .../** @type {Record<string, unknown>} */ (navigation.transitionTo),
-          onArrive,
-        }, {
-          source: id,
-        });
-      arrivalDeferred = hasActionResult(results);
-    }
-    if (Array.isArray(scene.preloadHints)) {
-      options.onPreloadHints?.(scene.preloadHints, scene, context);
-    }
-    options.onLayerState?.(scene, context);
-    if (!arrivalDeferred) {
-      onArrive();
-    }
-  }
-
-  /**
-   * @param {Record<string, unknown>} scene
-   * @param {import('./index.d.ts').SkykitThreePluginContext} context
-   * @param {unknown} event
-   * @param {() => void} onArrive
-   * @returns {Promise<boolean>} true when arrival will be reported asynchronously
-   */
-  async function applyOrbitCameraScene(scene, context, event, onArrive) {
-    const camera = /** @type {Record<string, unknown>} */ (scene.camera);
-    const destinationOrbit = await resolveJourneyOrbit(camera, context);
-    if (!destinationOrbit) return false;
-    const lookTarget = await resolveJourneyTarget(camera.lookAt ?? camera.center, context)
-      ?? destinationOrbit.center;
-    const source = { source: id };
-    await context.actions.invoke(SKYKIT_ACTIONS.navigation.cancel, null, source);
-    context.requestViewState({ targetPc: lookTarget }, id);
-    await context.actions.invoke(SKYKIT_ACTIONS.navigation.lockAt, {
-      ...lookTarget,
-      ...(destinationOrbit.normal ? { up: destinationOrbit.normal } : {}),
-      dwellSecs: resolveJourneyDwellSecs(camera, scene.travel),
-      recenterSpeed: 0.06,
-    }, source);
-
-    if (isInitialJourneyEvent(event)) {
-      const initialNormal = destinationOrbit.normal ?? { x: 0, y: 1, z: 0 };
-      const initialObserverPc = resolveInitialSceneObserverPc(scene)
-        ?? defaultOrbitPosition(destinationOrbit.center, destinationOrbit.radius, initialNormal);
-      rememberResolvedJourneyOrbit(scene, {
-        ...destinationOrbit,
-        normal: initialNormal,
-      });
-      context.requestViewState({
-        observerPc: initialObserverPc,
-        targetPc: lookTarget,
-      }, id);
-      await context.actions.invoke(SKYKIT_ACTIONS.navigation.orbit, {
-        center: destinationOrbit.center,
-        radius: destinationOrbit.radius,
-        angularSpeedRadPerSec: destinationOrbit.angularSpeedRadPerSec,
-        normal: initialNormal,
-      }, source);
-      return false;
-    }
-
-    const travel = normalizeJourneySceneTravel(scene.travel);
-    const explicitRoutePoints = await resolveJourneyRoutePoints(scene, travel, context);
-    if (explicitRoutePoints.length >= 2) {
-      const arrivalAction = normalizeJourneyOrbitAction(
-        travel.arrivalAction ?? scene.travelPathArrivalAction,
-        destinationOrbit,
-      );
-      rememberResolvedJourneyOrbit(scene, arrivalAction);
-      const results = await context.actions.invoke(SKYKIT_ACTIONS.navigation.flyPolyline, {
-        points: explicitRoutePoints,
-        durationSecs: travel.durationSecs,
-        arrivalThreshold: travel.arrivalThreshold,
-        arrivalAction,
-        onArrive,
-      }, source);
-      return hasActionResult(results);
-    }
-    const route = createOrbitTransferRoute({
-      start: context.getViewState().observerPc,
-      sourceOrbit: await resolveSourceJourneyOrbit(event, context),
-      destinationOrbit,
-      durationSecs: travel.durationSecs,
-      sampleStepSecs: travel.sampleStepSecs,
-    });
-    if (route && Array.isArray(route.points) && route.points.length >= 2) {
-      rememberResolvedJourneyOrbit(scene, route.arrivalAction);
-      const results = await context.actions.invoke(SKYKIT_ACTIONS.navigation.flyPolyline, {
-        points: route.points,
-        durationSecs: travel.durationSecs,
-        currentSpeed: route.departureSpeed,
-        arrivalSpeed: route.arrivalSpeed,
-        arrivalThreshold: travel.arrivalThreshold,
-        arrivalAction: route.arrivalAction,
-        onArrive,
-      }, source);
-      return hasActionResult(results);
-    }
-    const fallbackNormal = destinationOrbit.normal ?? { x: 0, y: 1, z: 0 };
-    rememberResolvedJourneyOrbit(scene, {
-      ...destinationOrbit,
-      normal: fallbackNormal,
-    });
-    await context.actions.invoke(SKYKIT_ACTIONS.navigation.orbit, {
-      center: destinationOrbit.center,
-      radius: destinationOrbit.radius,
-      angularSpeedRadPerSec: destinationOrbit.angularSpeedRadPerSec,
-      normal: fallbackNormal,
-    }, source);
-    return false;
-  }
-
-  /**
-   * @param {unknown} transitionTo
-   * @returns {Record<string, unknown>}
-   */
-  function createRouteArrivalTransitionPayload(transitionTo) {
-    const payload = /** @type {Record<string, unknown>} */ (
-      transitionTo && typeof transitionTo === 'object' ? transitionTo : {}
-    );
-    return {
-      ...payload,
-      movement: {
-        ...(payload.movement && typeof payload.movement === 'object'
-          ? /** @type {Record<string, unknown>} */ (payload.movement)
-          : {}),
-        durationSecs: 0.001,
-      },
-    };
-  }
-
-  /**
-   * @param {Record<string, unknown>} scene
-   * @param {Record<string, unknown>} travel
-   * @param {import('./index.d.ts').SkykitThreePluginContext} context
-   * @returns {Promise<Vector3Like[]>}
-   */
-  async function resolveJourneyRoutePoints(scene, travel, context) {
-    const rawPoints = resolveJourneyRoutePointSource(scene, travel);
-    if (!rawPoints) return [];
-    const points = [];
-    for (const point of Array.from(rawPoints)) {
-      const resolved = await resolveJourneyTarget(point, context);
-      if (resolved) points.push(resolved);
-    }
-    return points;
-  }
-
-  /**
-   * @param {Record<string, unknown>} scene
-   * @param {Record<string, unknown>} travel
-   * @returns {Iterable<unknown> | null}
-   */
-  function resolveJourneyRoutePointSource(scene, travel) {
-    return firstIterable(
-      scene.travelPathPc,
-      scene.travelPath,
-      travel.pathPointsPc,
-      travel.pointsPc,
-      travel.points,
-    );
-  }
-
-  /**
-   * @param {...unknown} candidates
-   * @returns {Iterable<unknown> | null}
-   */
-  function firstIterable(...candidates) {
-    for (const candidate of candidates) {
-      if (
-        candidate
-        && typeof /** @type {{ [Symbol.iterator]?: unknown }} */ (candidate)[Symbol.iterator] === 'function'
-      ) {
-        return /** @type {Iterable<unknown>} */ (candidate);
-      }
-    }
-    return null;
-  }
-
-  /**
-   * @param {unknown} value
-   * @param {{ center: Vector3Like; radius: number; angularSpeedRadPerSec: number; normal?: Vector3Like }} fallback
-   * @returns {{ type: 'orbit'; center: Vector3Like; radius: number; angularSpeedRadPerSec: number; normal: Vector3Like }}
-   */
-  function normalizeJourneyOrbitAction(value, fallback) {
-    const source = value && typeof value === 'object'
-      ? /** @type {Record<string, unknown>} */ (value)
-      : {};
-    const fallbackNormal = fallback.normal ?? { x: 0, y: 1, z: 0 };
-    return {
-      type: 'orbit',
-      center: normalizeOptionalVector3(source.center) ?? cloneVector3(fallback.center),
-      radius: positiveFinite(source.radius ?? source.radiusPc, fallback.radius),
-      angularSpeedRadPerSec: finiteNumber(
-        source.angularSpeedRadPerSec ?? source.angularSpeed,
-        fallback.angularSpeedRadPerSec,
-      ),
-      normal: normalizeDirectionVector(source.normal, fallbackNormal),
-    };
-  }
-
-  /**
-   * @param {Record<string, unknown>} camera
-   * @param {import('./index.d.ts').SkykitThreePluginContext} context
-   */
-  async function resolveJourneyOrbit(camera, context) {
-    const center = await resolveJourneyTarget(camera.center, context);
-    if (!center) return null;
-    return {
-      center,
-      radius: positiveFinite(camera.radiusPc, 1),
-      angularSpeedRadPerSec: finiteNumber(camera.angularSpeedRadPerSec, 0.1),
-      ...(camera.normal != null ? { normal: normalizeDirectionVector(camera.normal, { x: 0, y: 1, z: 0 }) } : {}),
-    };
-  }
-
-  /**
-   * @param {Record<string, unknown>} scene
-   * @param {import('./index.d.ts').SkykitThreePluginContext} context
-   * @param {unknown} event
-   */
-  async function notifySceneArrive(scene, context, event) {
-    try {
-      await options.onSceneArrive?.(scene, context, event);
-    } catch (error) {
-      context.emit?.({
-        type: 'journey/scene-arrive/error',
-        pluginId: id,
-        message: 'Failed to handle journey scene arrival.',
-        error,
-        event,
-      });
-    }
-  }
-
-  /**
-   * @param {unknown} input
-   * @param {import('./index.d.ts').SkykitThreePluginContext} context
-   */
-  async function resolveJourneyTarget(input, context) {
-    if (typeof input === 'string') {
-      const targets = resolveJourneyTargets();
-      const target = targets[input];
-      if (target && typeof target === 'object' && target.positionPc) {
-        return normalizeVector3(target.positionPc, { x: 0, y: 0, z: 0 });
-      }
-      return null;
-    }
-    return await resolveSpatialTarget(
-      /** @type {import('@found-in-space/spatial').SpatialTargetInput} */ (input),
-      { observerPc: context.getViewState().observerPc },
-    );
-  }
-
-  function resolveJourneyTargets() {
-    const graph = controller?.graph;
-    if (graph && typeof graph === 'object' && 'targets' in graph) {
-      return /** @type {Record<string, { positionPc?: unknown }>} */ (
-        /** @type {Record<string, unknown>} */ (graph).targets ?? {}
-      );
-    }
-    return /** @type {Record<string, { positionPc?: unknown }>} */ (options.journey?.targets ?? {});
-  }
-
-  /**
-   * @param {unknown} event
-   * @param {import('./index.d.ts').SkykitThreePluginContext} context
-   */
-  async function resolveSourceJourneyOrbit(event, context) {
-    const previousSceneId = event && typeof event === 'object'
-      ? /** @type {{ previousSceneId?: unknown }} */ (event).previousSceneId
-      : null;
-    if (typeof previousSceneId !== 'string') return null;
-    const resolved = resolvedJourneyOrbits.get(previousSceneId);
-    if (resolved) return resolved;
-    const previousScene = controller?.graph.getScene(previousSceneId);
-    const camera = previousScene?.camera && typeof previousScene.camera === 'object'
-      ? /** @type {Record<string, unknown>} */ (previousScene.camera)
-      : null;
-    return camera && camera.type === 'orbit' ? resolveJourneyOrbit(camera, context) : null;
-  }
-
-  /** @param {Record<string, unknown>} scene */
-  function resolveInitialSceneObserverPc(scene) {
-    const view = scene.view && typeof scene.view === 'object'
-      ? /** @type {{ observerPc?: unknown }} */ (scene.view)
-      : null;
-    return normalizeOptionalVector3(view?.observerPc);
-  }
-
-  /**
-   * @param {Record<string, unknown>} scene
-   * @param {{ center: Vector3Like; radius: number; angularSpeedRadPerSec: number; normal: Vector3Like }} orbit
-   */
-  function rememberResolvedJourneyOrbit(scene, orbit) {
-    const sceneId = typeof scene.sceneId === 'string' ? scene.sceneId : null;
-    if (!sceneId) return;
-    resolvedJourneyOrbits.set(sceneId, {
-      center: cloneVector3(orbit.center),
-      radius: orbit.radius,
-      angularSpeedRadPerSec: orbit.angularSpeedRadPerSec,
-      normal: cloneVector3(orbit.normal),
-    });
-  }
-
-  /**
-   * @param {import('@found-in-space/journey').TimedJourneyFrame} frameState
-   * @param {{ viewer: import('./index.d.ts').SkykitViewer; view: import('./index.d.ts').SkykitViewState }} frame
-   */
-  function applyTimedFrame(frameState, frame) {
-    const context = pluginContext;
-    const hookResult = options.applyFrame?.(frameState, context, frame);
-    if (hookResult === false) return;
-    frame.viewer.requestViewState({
-      observerPc: frameState.observerPc,
-      orientationIcrs: frameState.orientationIcrs,
-      targetPc: frameState.targetPc,
-      motion: {
-        velocityPcPerSec: frameState.velocityPcPerSec,
-        speedPcPerSec: frameState.speedPcPerSec,
-      },
-    }, id);
-    if (frameState.cue && frameState.cue.id !== lastCueId) {
-      lastCueId = frameState.cue.id;
-      options.onCue?.(frameState.cue, frameState, context);
-    } else if (!frameState.cue) {
-      lastCueId = null;
-    }
-  }
-
-  function getSnapshot() {
-    return {
-      id,
-      disposed,
-      playing,
-      currentTimeSecs,
-      initialSceneApplied,
-      timedPreloadHintsEmitted,
-      controller: controller?.getSnapshot?.() ?? null,
-      timedJourney: evaluator
-        ? {
-            durationSecs: evaluator.durationSecs,
-            journeyId: evaluator.journey.id,
-          }
-        : null,
-    };
-  }
-}
 
 /**
  * Strategy-only convenience helper. View-bound lookahead hints stay in preload
@@ -1550,108 +994,6 @@ function getDefaultEventTarget() {
   return typeof globalThis.addEventListener === 'function' ? globalThis : null;
 }
 
-/** @param {Record<string, unknown>} scene */
-function isOrbitCameraScene(scene) {
-  return Boolean(
-    scene.camera
-    && typeof scene.camera === 'object'
-    && /** @type {{ type?: unknown }} */ (scene.camera).type === 'orbit',
-  );
-}
-
-/** @param {unknown} event */
-function isInitialJourneyEvent(event) {
-  return Boolean(
-    event
-    && typeof event === 'object'
-    && /** @type {{ type?: unknown; previousSceneId?: unknown }} */ (event).type === 'journey/initial',
-  );
-}
-
-/**
- * @param {unknown} value
- * @returns {Record<string, unknown> & { durationSecs: number; sampleStepSecs: number; arrivalThreshold: number }}
- */
-function normalizeJourneySceneTravel(value) {
-  const source = /** @type {Record<string, unknown>} */ (
-    value && typeof value === 'object' ? value : {}
-  );
-  return {
-    ...source,
-    durationSecs: positiveFinite(source.durationSecs, 5),
-    sampleStepSecs: positiveFinite(source.sampleStepSecs, 1 / 60),
-    arrivalThreshold: positiveFinite(source.arrivalThreshold, 0.05),
-  };
-}
-
-/**
- * @param {Record<string, unknown>} camera
- * @param {unknown} travel
- */
-function resolveJourneyDwellSecs(camera, travel) {
-  if (camera.dwellSecs != null) return Math.max(0, finiteNumber(camera.dwellSecs, 0));
-  if (travel && typeof travel === 'object' && 'dwellSecs' in travel) {
-    return Math.max(0, finiteNumber(/** @type {{ dwellSecs?: unknown }} */ (travel).dwellSecs, 0));
-  }
-  return 0;
-}
-
-/**
- * @param {Vector3Like} center
- * @param {number} radius
- * @param {Vector3Like} normal
- * @returns {Vector3Like}
- */
-function defaultOrbitPosition(center, radius, normal) {
-  const axis = Math.abs(normal.x) < 0.9 ? { x: 1, y: 0, z: 0 } : { x: 0, y: 1, z: 0 };
-  const projected = projectOnPlane(axis, normal);
-  const length = Math.hypot(projected.x, projected.y, projected.z);
-  const direction = length > 1e-9
-    ? { x: projected.x / length, y: projected.y / length, z: projected.z / length }
-    : { x: 1, y: 0, z: 0 };
-  return {
-    x: center.x + direction.x * radius,
-    y: center.y + direction.y * radius,
-    z: center.z + direction.z * radius,
-  };
-}
-
-/**
- * @param {unknown} value
- * @param {Vector3Like} fallback
- * @returns {Vector3Like}
- */
-function normalizeDirectionVector(value, fallback) {
-  const vector = normalizeVector3(value, fallback);
-  const length = Math.hypot(vector.x, vector.y, vector.z);
-  return length > 1e-9
-    ? { x: vector.x / length, y: vector.y / length, z: vector.z / length }
-    : cloneVector3(fallback);
-}
-
-/** @param {unknown} value */
-function normalizeOptionalVector3(value) {
-  if (!value || typeof value !== 'object') return null;
-  const vector = /** @type {{ x?: unknown; y?: unknown; z?: unknown }} */ (value);
-  const x = Number(vector.x);
-  const y = Number(vector.y);
-  const z = Number(vector.z);
-  return [x, y, z].every(Number.isFinite) ? { x, y, z } : null;
-}
-
-/**
- * @param {Vector3Like} vector
- * @param {Vector3Like} normal
- * @returns {Vector3Like}
- */
-function projectOnPlane(vector, normal) {
-  const amount = vector.x * normal.x + vector.y * normal.y + vector.z * normal.z;
-  return {
-    x: vector.x - normal.x * amount,
-    y: vector.y - normal.y * amount,
-    z: vector.z - normal.z * amount,
-  };
-}
 
 /**
  * @param {unknown} payload
@@ -1690,11 +1032,6 @@ function resolveOnArrive(payload) {
     : null;
 }
 
-/** @param {PromiseSettledResult<unknown>[]} results */
-function hasActionResult(results) {
-  return results.some((result) => result.status === 'fulfilled' && result.value != null);
-}
-
 /** @param {Record<string, unknown>} targetSource */
 function resolveTransitionPositionInput(targetSource) {
   if (targetSource.observerPc !== undefined) return targetSource.observerPc;
@@ -1717,29 +1054,6 @@ function isSpatialTargetLike(value) {
   return Array.isArray(value) && value.length >= 3;
 }
 
-/** @param {unknown} payload */
-function resolveSceneId(payload) {
-  if (typeof payload === 'string') return payload;
-  if (!payload || typeof payload !== 'object') return null;
-  const source = /** @type {Record<string, unknown>} */ (payload);
-  const value = source.chapterId ?? source.sceneId ?? source.id;
-  return typeof value === 'string' ? value : null;
-}
-
-/** @param {unknown} payload */
-function resolveTimeSecs(payload) {
-  if (Number.isFinite(Number(payload))) return Number(payload);
-  if (!payload || typeof payload !== 'object') return 0;
-  const value = /** @type {Record<string, unknown>} */ (payload).timeSecs
-    ?? /** @type {Record<string, unknown>} */ (payload).sceneTimeSecs
-    ?? /** @type {Record<string, unknown>} */ (payload).time;
-  return finiteNumber(value, 0);
-}
-
-/** @param {number} timeSecs @param {number} durationSecs */
-function clampTime(timeSecs, durationSecs) {
-  return Math.min(Math.max(0, finiteNumber(timeSecs, 0)), Math.max(0, finiteNumber(durationSecs, 0)));
-}
 
 /**
  * @param {unknown} value