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

package/src/viewer.js

@@ -15,6 +15,7 @@ import {
   mountRenderer,
   normalizeViewState,
   positiveFinite,
+  resolveViewLookAtInput,
   setupPlugin,
   snapshotPart,
   syncRootsFromView,
@@ -71,7 +72,7 @@ export async function createSkykitViewer(options = {}) {
   let started = false;
   let elapsedSeconds = 0;
   const initialProjectionView = resolveCameraProjectionView(camera);
-  let view = normalizeViewState({
+  const initialViewInput = await resolveViewLookAtInput({
     ...options.view,
     ...(options.view?.verticalFovDeg === undefined && initialProjectionView.verticalFovDeg !== undefined
       ? { verticalFovDeg: initialProjectionView.verticalFovDeg }
@@ -83,8 +84,11 @@ export async function createSkykitViewer(options = {}) {
     renderObserverPosition: options.view?.renderObserverPosition ?? observerRig.getRenderObserverPosition(),
     orientationIcrs: options.view?.orientationIcrs ?? observerRig.getOrientationIcrs?.() ?? null,
     motion: options.view?.motion ?? observerRig.getMotion?.() ?? null,
-  }, 0);
+  }, viewLookResolverOptions(options.view?.observerPc ?? observerRig.getObserverPc()));
+  let view = normalizeViewState(initialViewInput, 0, viewLookResolverOptions(initialViewInput.observerPc));
   const initialView = cloneViewState(view);
+  observerRig.setObserverPc?.(view.observerPc);
+  if (view.orientationIcrs) observerRig.setOrientationIcrs?.(view.orientationIcrs);
 
   addRootToScene(scene, roots.originContentRoot);
   addRootToScene(scene, roots.observerContentRoot);
@@ -112,6 +116,7 @@ export async function createSkykitViewer(options = {}) {
     observerRig,
     actions,
     addPart,
+    addPlugin,
     getViewState,
     requestViewState,
     update,
@@ -139,10 +144,7 @@ export async function createSkykitViewer(options = {}) {
   }
 
   for (const plugin of pluginInputs) {
-    const teardown = await setupPlugin(plugin, context);
-    if (typeof teardown === 'function') {
-      disposables.push(teardown);
-    }
+    await installPlugin(plugin);
   }
 
   for (const part of orderedParts()) {
@@ -176,6 +178,32 @@ export async function createSkykitViewer(options = {}) {
     };
   }
 
+  /**
+   * @param {import('./index.d.ts').SkykitPluginInput} plugin
+   * @returns {Promise<SkykitPluginTeardown>}
+   */
+  async function addPlugin(plugin) {
+    assertActive();
+    return installPlugin(plugin, true);
+  }
+
+  /**
+   * @param {import('./index.d.ts').SkykitPluginInput} plugin
+   * @param {boolean} [record]
+   * @returns {Promise<SkykitPluginTeardown>}
+   */
+  async function installPlugin(plugin, record = false) {
+    const teardown = await setupPlugin(plugin, context);
+    if (record) pluginInputs.push(plugin);
+    if (typeof teardown !== 'function') return () => {};
+    disposables.push(teardown);
+    return () => {
+      const index = disposables.indexOf(teardown);
+      if (index >= 0) disposables.splice(index, 1);
+      void teardown();
+    };
+  }
+
   /**
    * @param {SkykitThreePart} part
    */
@@ -192,9 +220,8 @@ export async function createSkykitViewer(options = {}) {
    */
   async function removePart(part) {
     const index = parts.indexOf(part);
-    if (index >= 0) {
-      parts.splice(index, 1);
-    }
+    if (index < 0) return;
+    parts.splice(index, 1);
     emit({ type: 'part/remove', part });
     await detachAndDisposePart(part);
   }
@@ -209,11 +236,32 @@ export async function createSkykitViewer(options = {}) {
    */
   function requestViewState(patch, reason) {
     assertActive();
+    const normalizedPatch = normalizeRequestedViewPatch(patch);
+    if (lookAtNeedsAsyncResolution(normalizedPatch)) {
+      const observerPc = /** @type {Partial<SkykitViewState>} */ (normalizedPatch).observerPc ?? view.observerPc;
+      void resolveViewLookAtInput(normalizedPatch, viewLookResolverOptions(observerPc))
+        .then((resolvedPatch) => {
+          if (disposed) return;
+          pendingViewPatch = {
+            ...(pendingViewPatch ?? {}),
+            ...resolvedPatch,
+          };
+        })
+        .catch((error) => {
+          emit({
+            type: 'view/lookAt-error',
+            reason,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        });
+      emit({ type: 'view/request', reason, patch: normalizedPatch });
+      return;
+    }
     pendingViewPatch = {
       ...(pendingViewPatch ?? {}),
-      ...patch,
+      ...normalizedPatch,
     };
-    emit({ type: 'view/request', reason, patch });
+    emit({ type: 'view/request', reason, patch: normalizedPatch });
   }
 
   /**
@@ -356,7 +404,7 @@ export async function createSkykitViewer(options = {}) {
       }
     }
     for (const part of [...orderedParts()].reverse()) {
-      await detachAndDisposePart(part);
+      await removePart(part);
     }
     for (const disposable of [...disposables].reverse()) {
       await disposable();
@@ -454,6 +502,56 @@ export async function createSkykitViewer(options = {}) {
     return [...parts].sort(compareParts);
   }
 
+  /** @param {Partial<SkykitViewState>} patch */
+  function normalizeRequestedViewPatch(patch) {
+    if (!patch || typeof patch !== 'object') return patch;
+    if ('lookAt' in patch) return patch;
+    if (patch.orientationIcrs) {
+      return {
+        ...patch,
+        lookAt: { orientationIcrs: patch.orientationIcrs },
+      };
+    }
+    if (patch.targetPc) {
+      return {
+        ...patch,
+        lookAt: { targetPc: patch.targetPc },
+      };
+    }
+    return patch;
+  }
+
+  /** @param {Partial<SkykitViewState>} patch */
+  function lookAtNeedsAsyncResolution(patch) {
+    if (!patch || typeof patch !== 'object' || !('lookAt' in patch)) return false;
+    const lookAt = /** @type {Record<string, unknown> | null} */ (patch.lookAt);
+    return !!lookAt
+      && typeof lookAt === 'object'
+      && 'star' in lookAt
+      && !('targetPc' in lookAt)
+      && typeof options.resolveLookAtStar === 'function';
+  }
+
+  /** @param {unknown} observerPc */
+  function viewLookResolverOptions(observerPc) {
+    return {
+      observerPc,
+      resolveStar: typeof options.resolveLookAtStar === 'function'
+        ? /** @type {import('@found-in-space/spatial').ResolveSpatialLookAtOptions['resolveStar']} */ (
+          (star, lookAt) => options.resolveLookAtStar?.(
+            star,
+            /** @type {import('./index.d.ts').SkykitLookAtInput} */ (lookAt),
+          )
+        )
+        : undefined,
+      resolveBookmark: typeof options.resolveLookAtBookmark === 'function'
+        ? /** @type {import('@found-in-space/spatial').ResolveSpatialLookAtOptions['resolveBookmark']} */ (
+          (bookmarkId, lookAt) => options.resolveLookAtBookmark?.(bookmarkId, lookAt)
+        )
+        : undefined,
+    };
+  }
+
   /**
    * @param {SkykitViewer} currentViewer
    * @returns {SkykitThreePluginContext}

package/src/xr/plugins.js

@@ -11,6 +11,7 @@ import {
   positiveFinite,
 } from '../utils.js';
 import { createSkykitXrControlBindings } from './controls.js';
+import { createSkykitXrBodyTracker } from './body.js';
 import { createSkykitXrRaySource } from './rays.js';
 import { enterSkykitXrSession, exitSkykitXrSession, isSkykitXrModeSupported } from './session.js';
 
@@ -121,6 +122,69 @@ export function createSkykitXrObserverRig(options) {
   }
 }
 
+/**
+ * @param {import('../xr.d.ts').SkykitXrBodyPluginOptions} [options]
+ * @returns {import('../xr.d.ts').SkykitXrBodyPlugin}
+ */
+export function createSkykitXrBodyPlugin(options = {}) {
+  const id = options.id ?? 'skykit-xr-body';
+  const tracker = options.tracker ?? createSkykitXrBodyTracker();
+  const hideUntrackedHands = options.hideUntrackedHands !== false;
+  let disposed = false;
+  let body = tracker.getBody();
+
+  const part = {
+    id,
+    priority: options.priority ?? -900,
+    /** @param {import('../index.d.ts').SkykitThreeFrame} frame */
+    update(frame) {
+      if (disposed) return;
+      const session = frame.xr?.session && typeof frame.xr.session === 'object'
+        ? /** @type {{ inputSources?: Iterable<unknown> }} */ (frame.xr.session)
+        : null;
+      body = tracker.update({
+        frame: frame.xr?.frame,
+        referenceSpace: frame.xr?.referenceSpace,
+        session: /** @type {any} */ (frame.xr?.session),
+        inputSources: session?.inputSources ?? [],
+        rig: options.rig,
+        shipPose: options.rig?.getNavigationPose?.(),
+      });
+      if (hideUntrackedHands && options.rig) {
+        setObjectVisible(options.rig.leftHandRoot, Boolean(body.leftHand?.grip ?? body.leftHand?.targetRay));
+        setObjectVisible(options.rig.rightHandRoot, Boolean(body.rightHand?.grip ?? body.rightHand?.targetRay));
+      }
+      options.onBody?.(body, frame);
+    },
+    dispose() {
+      disposed = true;
+      if (options.disposeTracker !== false) {
+        tracker.dispose?.();
+      }
+    },
+    getSnapshot,
+  };
+
+  return {
+    id,
+    setup(context) {
+      context.addPart(part);
+    },
+    getBody() {
+      return body;
+    },
+    getSnapshot,
+  };
+
+  function getSnapshot() {
+    return {
+      id,
+      disposed,
+      body,
+    };
+  }
+}
+
 /**
  * @param {import('../xr.d.ts').SkykitXrSessionPluginOptions} options
  * @returns {import('../index.d.ts').SkykitPlugin & { enter(): Promise<import('../xr.d.ts').SkykitXrSessionHandle>; exit(): Promise<void>; getSnapshot(): unknown }}
@@ -137,6 +201,10 @@ export function createSkykitXrSessionPlugin(options = {}) {
   let disposed = false;
   /** @type {boolean | null} */
   let supported = null;
+  /** @type {string} */
+  let enterStage = 'idle';
+  /** @type {string | null} */
+  let lastError = null;
 
   const part = {
     id,
@@ -198,15 +266,40 @@ export function createSkykitXrSessionPlugin(options = {}) {
     const activeRenderer = renderer ?? context?.renderer;
     const rendererXr = resolveRendererXr(activeRenderer);
     if (rendererXr) rendererXr.enabled = true;
-    handle = await enterSkykitXrSession({
-      navigator: options.navigator,
-      mode,
-      referenceSpaceType,
-      sessionInit: options.sessionInit,
-      onSessionStarted: options.onSessionStarted,
-    });
-    if (rendererXr && typeof rendererXr.setSession === 'function') {
-      await rendererXr.setSession(handle.session);
+    rendererXr?.setReferenceSpaceType?.(referenceSpaceType);
+    enterStage = 'requesting-session';
+    lastError = null;
+    /** @type {import('../xr.d.ts').SkykitXrSessionHandle | null} */
+    let nextHandle = null;
+    try {
+      nextHandle = await enterSkykitXrSession({
+        navigator: options.navigator,
+        mode,
+        referenceSpaceType,
+        sessionInit: options.sessionInit,
+        requestReferenceSpace: false,
+      });
+      enterStage = 'binding-renderer';
+      if (rendererXr && typeof rendererXr.setSession === 'function') {
+        await rendererXr.setSession(nextHandle.session);
+      }
+      handle = nextHandle;
+      enterStage = 'presenting';
+      options.onSessionStarted?.(handle);
+    } catch (error) {
+      enterStage = 'failed';
+      lastError = error instanceof Error ? error.message : String(error);
+      if (nextHandle) {
+        await exitSkykitXrSession(nextHandle).catch(() => {});
+      }
+      const activeSession = rendererXr?.getSession?.();
+      if (activeSession && typeof /** @type {{ end?: unknown }} */ (activeSession).end === 'function') {
+        const endResult = /** @type {{ end: () => Promise<void> | void }} */ (activeSession).end();
+        if (endResult && typeof /** @type {Promise<void>} */ (endResult).catch === 'function') {
+          await /** @type {Promise<void>} */ (endResult).catch(() => {});
+        }
+      }
+      throw error;
     }
     context?.emit?.({
       type: 'xr/session-start',
@@ -220,14 +313,20 @@ export function createSkykitXrSessionPlugin(options = {}) {
   async function exit() {
     const previous = handle;
     handle = null;
+    enterStage = 'exiting';
     const activeRenderer = renderer ?? context?.renderer;
     const rendererXr = resolveRendererXr(activeRenderer);
-    if (rendererXr && typeof rendererXr.setSession === 'function' && rendererXr.getSession?.()) {
-      await rendererXr.setSession(null);
-    }
     if (previous) {
       await exitSkykitXrSession(previous);
+    } else {
+      const activeSession = rendererXr?.getSession?.();
+      if (activeSession && typeof /** @type {{ end?: unknown }} */ (activeSession).end === 'function') {
+        await /** @type {{ end: () => Promise<void> | void }} */ (activeSession).end();
+      } else if (rendererXr && typeof rendererXr.setSession === 'function' && rendererXr.getSession?.()) {
+        await rendererXr.setSession(null);
+      }
     }
+    enterStage = 'idle';
     context?.emit?.({
       type: 'xr/session-end',
       id,
@@ -246,7 +345,9 @@ export function createSkykitXrSessionPlugin(options = {}) {
       referenceSpaceType,
       supported,
       presenting: isPresenting(),
+      enterStage,
       session: handle?.getSnapshot?.() ?? null,
+      lastError,
       disposed,
     };
   }
@@ -365,6 +466,134 @@ export function createSkykitXrNavigationPlugin(options = {}) {
   };
 }
 
+/**
+ * @param {import('../xr.d.ts').SkykitXrRayVisualPluginOptions} options
+ * @returns {import('../index.d.ts').SkykitPlugin & { getSnapshot(): unknown }}
+ */
+export function createSkykitXrRayVisualPlugin(options) {
+  if (!options?.raySource || typeof options.raySource.getRay !== 'function') {
+    throw new TypeError('createSkykitXrRayVisualPlugin() requires a raySource.');
+  }
+  const id = options.id ?? 'skykit-xr-ray-visual';
+  const root = new THREE.Group();
+  root.name = id;
+  root.visible = false;
+  const positions = new Float32Array(6);
+  const geometry = new THREE.BufferGeometry();
+  geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+  const material = options.material ?? new THREE.LineBasicMaterial({
+    color: options.color ?? 0x66ffe8,
+    transparent: true,
+    opacity: options.opacity ?? 0.72,
+    depthTest: options.depthTest ?? false,
+    depthWrite: false,
+  });
+  const ownsMaterial = options.material == null;
+  const line = new THREE.Line(geometry, material);
+  line.name = `${id}:line`;
+  line.frustumCulled = false;
+  line.renderOrder = finiteNumber(options.renderOrder, 10_000);
+  root.add(line);
+
+  /** @type {THREE.Object3D | null} */
+  let parent = null;
+  let disposed = false;
+  let visible = false;
+  let blocked = false;
+  let lastLength = 0;
+
+  const part = {
+    id,
+    priority: options.priority ?? 45,
+    object3d: root,
+    /** @param {import('../index.d.ts').SkykitThreePluginContext} context */
+    attach(context) {
+      parent = resolveRayVisualParent(options.parent, context);
+      parent.add(root);
+    },
+    /** @param {import('../index.d.ts').SkykitThreeFrame} frame */
+    update(frame) {
+      if (disposed || frame.xr?.presenting !== true) {
+        setVisible(false);
+        return;
+      }
+      const session = frame.xr.session && typeof frame.xr.session === 'object'
+        ? /** @type {{ inputSources?: Iterable<unknown> }} */ (frame.xr.session)
+        : null;
+      const ray = options.raySource.getRay({
+        frame: frame.xr.frame,
+        referenceSpace: frame.xr.referenceSpace,
+        session: /** @type {any} */ (frame.xr.session),
+        inputSources: session?.inputSources ?? [],
+        rig: options.rig,
+        viewer: frame.viewer,
+      });
+      if (!ray) {
+        setVisible(false);
+        return;
+      }
+
+      const resolved = resolveRayVisualLength(ray, frame, options);
+      blocked = resolved.blocked;
+      if (!(resolved.length > 0)) {
+        setVisible(false);
+        return;
+      }
+
+      const direction = new THREE.Vector3(ray.direction.x, ray.direction.y, ray.direction.z).normalize();
+      positions[0] = ray.origin.x;
+      positions[1] = ray.origin.y;
+      positions[2] = ray.origin.z;
+      positions[3] = ray.origin.x + direction.x * resolved.length;
+      positions[4] = ray.origin.y + direction.y * resolved.length;
+      positions[5] = ray.origin.z + direction.z * resolved.length;
+      geometry.attributes.position.needsUpdate = true;
+      geometry.computeBoundingSphere();
+      lastLength = resolved.length;
+      setVisible(true);
+    },
+    detach() {
+      parent?.remove(root);
+      parent = null;
+    },
+    dispose() {
+      disposed = true;
+      parent?.remove(root);
+      parent = null;
+      geometry.dispose();
+      if (ownsMaterial) {
+        material.dispose();
+      }
+      options.raySource.dispose?.();
+    },
+    getSnapshot() {
+      return {
+        id,
+        disposed,
+        visible,
+        blocked,
+        lastLength,
+        parentName: parent?.name ?? null,
+        raySource: options.raySource.getSnapshot?.() ?? null,
+      };
+    },
+  };
+
+  return {
+    id,
+    setup(context) {
+      context.addPart(part);
+    },
+    getSnapshot: () => part.getSnapshot(),
+  };
+
+  /** @param {boolean} nextVisible */
+  function setVisible(nextVisible) {
+    visible = nextVisible;
+    root.visible = nextVisible;
+  }
+}
+
 /**
  * @param {import('../xr.d.ts').SkykitXrStarPickingPluginOptions} options
  * @returns {import('../index.d.ts').SkykitPlugin & { getSnapshot(): unknown }}
@@ -505,7 +734,7 @@ export function createSkykitXrStarPickingPlugin(options) {
  */
 function resolveRendererXr(renderer) {
   return renderer && typeof renderer === 'object'
-    ? /** @type {{ enabled?: boolean; isPresenting?: boolean; getSession?: () => unknown; getReferenceSpace?: () => unknown; setSession?: (session: unknown) => Promise<void> | void }} */ (
+    ? /** @type {{ enabled?: boolean; isPresenting?: boolean; getSession?: () => unknown; getReferenceSpace?: () => unknown; setReferenceSpaceType?: (type: string) => void; setSession?: (session: unknown) => Promise<void> | void }} */ (
         /** @type {{ xr?: unknown }} */ (renderer).xr
       )
     : null;
@@ -587,3 +816,59 @@ function callBlocker(blocker, ray, context) {
   }
   return blocker.blockRay?.(ray, context) ?? blocker.pick?.(ray, context) ?? null;
 }
+
+/**
+ * @param {import('../xr.d.ts').SkykitXrRay} ray
+ * @param {import('../index.d.ts').SkykitThreeFrame} frame
+ * @param {import('../xr.d.ts').SkykitXrRayVisualPluginOptions} options
+ */
+function resolveRayVisualLength(ray, frame, options) {
+  const fallbackLength = positiveFinite(options.length, 12);
+  let length = positiveFinite(ray.length, fallbackLength);
+  let blocked = false;
+  for (const blocker of options.blockers ?? []) {
+    const result = callBlocker(blocker, ray, {
+      frame: frame.xr?.frame,
+      referenceSpace: frame.xr?.referenceSpace,
+      session: /** @type {any} */ (frame.xr?.session),
+      ray,
+      viewer: frame.viewer,
+      maxDistance: length,
+    });
+    if (!result) continue;
+    const hitDistance = finiteNumber(
+      result.distance
+        ?? result.maxDistance
+        ?? /** @type {{ length?: unknown }} */ (result.hit ?? {}).length,
+      Number.NaN,
+    );
+    if (Number.isFinite(hitDistance) && hitDistance >= 0) {
+      length = Math.min(length, hitDistance);
+    } else if (result.consumed === true || result.blocked === true) {
+      length = 0;
+    }
+    blocked = blocked || result.consumed === true || result.blocked === true;
+  }
+  return { length, blocked };
+}
+
+/**
+ * @param {import('../xr.d.ts').SkykitXrRayVisualPluginOptions['parent']} parent
+ * @param {import('../index.d.ts').SkykitThreePluginContext} context
+ */
+function resolveRayVisualParent(parent, context) {
+  if (typeof parent === 'function') {
+    return parent(context) ?? context.scene;
+  }
+  return parent ?? context.scene;
+}
+
+/**
+ * @param {unknown} object
+ * @param {boolean} visible
+ */
+function setObjectVisible(object, visible) {
+  if (object && typeof object === 'object' && 'visible' in object) {
+    /** @type {{ visible: boolean }} */ (object).visible = visible;
+  }
+}

package/src/xr/session.js

@@ -26,20 +26,35 @@ export async function enterSkykitXrSession(options = {}) {
   if (!xr || typeof xr.requestSession !== 'function') {
     throw new Error('WebXR is not available.');
   }
-  const session = /** @type {{ requestReferenceSpace?: (type: string) => Promise<unknown> }} */ (
-    await xr.requestSession(mode, options.sessionInit)
-  );
-  const referenceSpace = typeof session.requestReferenceSpace === 'function'
-    ? await session.requestReferenceSpace(referenceSpaceType)
-    : null;
-  const handle = createSessionHandle({
-    mode,
-    referenceSpaceType,
-    session,
-    referenceSpace,
-  });
-  options.onSessionStarted?.(handle);
-  return handle;
+  /** @type {{ requestReferenceSpace?: (type: string) => Promise<unknown>; end?: () => Promise<void> | void } | null} */
+  let session = null;
+  try {
+    session = /** @type {{ requestReferenceSpace?: (type: string) => Promise<unknown>; end?: () => Promise<void> | void }} */ (
+      await xr.requestSession(mode, createSessionInit(options.sessionInit, referenceSpaceType))
+    );
+    const referenceSpace = options.requestReferenceSpace === false
+      ? null
+      : typeof session.requestReferenceSpace === 'function'
+        ? await session.requestReferenceSpace(referenceSpaceType)
+        : null;
+    const handle = createSessionHandle({
+      mode,
+      referenceSpaceType,
+      session,
+      referenceSpace,
+    });
+    options.onSessionStarted?.(handle);
+    return handle;
+  } catch (error) {
+    if (session && typeof session.end === 'function') {
+      try {
+        await session.end();
+      } catch {
+        // Preserve the original session-enter error.
+      }
+    }
+    throw error;
+  }
 }
 
 /**
@@ -106,3 +121,34 @@ function resolveSkykitXr(navigatorLike) {
   const nav = navigatorLike ?? globalThis.navigator;
   return /** @type {{ xr?: { isSessionSupported?: (mode: string) => Promise<boolean>; requestSession?: (mode: string, init?: unknown) => Promise<unknown> } }} */ (nav)?.xr ?? null;
 }
+
+/**
+ * @param {unknown} sessionInit
+ * @param {string} referenceSpaceType
+ */
+function createSessionInit(sessionInit, referenceSpaceType) {
+  const base = sessionInit && typeof sessionInit === 'object'
+    ? /** @type {Record<string, unknown>} */ (sessionInit)
+    : {};
+  const requiredFeatures = normalizeFeatureList(base.requiredFeatures);
+  const optionalFeatures = normalizeFeatureList(base.optionalFeatures);
+  if (
+    referenceSpaceType &&
+    !requiredFeatures.includes(referenceSpaceType) &&
+    !optionalFeatures.includes(referenceSpaceType)
+  ) {
+    optionalFeatures.push(referenceSpaceType);
+  }
+  return {
+    ...base,
+    ...(requiredFeatures.length > 0 ? { requiredFeatures } : {}),
+    ...(optionalFeatures.length > 0 ? { optionalFeatures } : {}),
+  };
+}
+
+/** @param {unknown} value */
+function normalizeFeatureList(value) {
+  return Array.isArray(value)
+    ? Array.from(new Set(value.filter((entry) => typeof entry === 'string' && entry.trim())))
+    : [];
+}