@found-in-space/skykit 0.2.0-dev.20260527.1 → 0.2.0

package/src/utils.js

@@ -211,6 +211,7 @@ function resolveViewLook(input, observerPc, options = {}) {
  * @returns {import('./index.d.ts').SkykitLookAtInput | null}
  */
 function cloneLookAt(lookAt) {
+  if (typeof lookAt === 'string') return lookAt;
   if (!lookAt || typeof lookAt !== 'object') return null;
   const source = /** @type {Record<string, unknown>} */ (lookAt);
   return {

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 }}
@@ -798,3 +862,13 @@ function resolveRayVisualParent(parent, context) {
   }
   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.d.ts

@@ -14,6 +14,7 @@ import type {
   SkykitEvent,
   SkykitPlugin,
   SkykitStarCellSource,
+  SkykitThreeFrame,
   SkykitViewState,
 } from './index.js';
 
@@ -105,6 +106,22 @@ export interface SkykitXrBodyTracker {
   dispose(): void;
 }
 
+export interface SkykitXrBodyPluginOptions {
+  id?: string;
+  priority?: number;
+  rig?: SkykitXrRig;
+  tracker?: SkykitXrBodyTracker;
+  hideUntrackedHands?: boolean;
+  disposeTracker?: boolean;
+  onBody?: (body: SkykitXrBodyModel, frame: SkykitThreeFrame) => void;
+}
+
+export interface SkykitXrBodyPlugin extends SkykitPlugin {
+  readonly id: string;
+  getBody(): SkykitXrBodyModel;
+  getSnapshot(): unknown;
+}
+
 export interface SkykitXrAxisBinding {
   hand?: 'left' | 'right' | 'any';
   stick?: 'primary' | 'secondary';
@@ -445,6 +462,7 @@ export interface SkykitXrStarPickingPluginOptions {
 
 export declare function createSkykitXrRig(options?: CreateSkykitXrRigOptions): SkykitXrRig;
 export declare function createSkykitXrBodyTracker(options?: CreateSkykitXrBodyTrackerOptions): SkykitXrBodyTracker;
+export declare function createSkykitXrBodyPlugin(options?: SkykitXrBodyPluginOptions): SkykitXrBodyPlugin;
 export declare function createSkykitXrControlBindings(options?: SkykitXrControlBindingsOptions): SkykitXrControlBindingsHandle;
 export declare function readSkykitXrAxis(inputSources: Iterable<any>, binding?: SkykitXrAxisBinding & { deadzone?: number }): SkykitXrAxisState;
 export declare function readSkykitXrButton(inputSources: Iterable<any>, binding?: SkykitXrButtonBinding, previous?: SkykitXrButtonState | null): SkykitXrButtonState;

package/src/xr.js

@@ -14,6 +14,7 @@ export {
 export { createSkykitXrRaySource } from './xr/rays.js';
 export { createSkykitXrPickRouter } from './xr/pick-router.js';
 export {
+  createSkykitXrBodyPlugin,
   createSkykitXrNavigationPlugin,
   createSkykitXrObserverRig,
   createSkykitXrRayVisualPlugin,

package/src/browser-journey.d.ts

@@ -1,8 +0,0 @@
-import type {
-  SkykitBrowser,
-  SkykitBrowserJourneyFacade,
-} from './browser.js';
-
-export declare function installSkykitJourneyBrowserCapability(
-  context: { browser: SkykitBrowser }
-): Promise<SkykitBrowserJourneyFacade>;

package/src/browser-journey.js

@@ -1,240 +0,0 @@
-import { createJourney } from '@found-in-space/journey';
-import { parseSpatialLookAtText } from '@found-in-space/spatial';
-
-import { SKYKIT_ACTIONS } from './actions.js';
-import {
-  createSkykitJourneyPlugin,
-  createSkykitNavigationPlugin,
-} from './plugins.js';
-
-const NAVIGATION_CAPABILITY = 'skykit:navigation';
-const JOURNEY_CAPABILITY = 'skykit:browser.journey';
-const SOURCE = 'browser.journey';
-
-/**
- * @param {{ browser: import('./browser.d.ts').SkykitBrowser }} context
- * @returns {Promise<import('./browser.d.ts').SkykitBrowserJourneyFacade>}
- */
-export async function installSkykitJourneyBrowserCapability({ browser }) {
-  browser.capabilities.add(JOURNEY_CAPABILITY);
-
-  return {
-    transitionTo(viewOrScene, options) {
-      return transitionTo(browser, viewOrScene, options);
-    },
-    applyScene(sceneSpec) {
-      return applyScene(browser, sceneSpec);
-    },
-    load(input, options) {
-      return loadJourney(browser, input, options);
-    },
-    getSnapshot() {
-      return {
-        capability: JOURNEY_CAPABILITY,
-        navigationInstalled: browser.capabilities.has(NAVIGATION_CAPABILITY),
-      };
-    },
-  };
-}
-
-/**
- * @param {import('./browser.d.ts').SkykitBrowser} browser
- */
-async function ensureNavigation(browser) {
-  if (browser.capabilities.has(NAVIGATION_CAPABILITY)) return;
-  await browser.install(createSkykitNavigationPlugin());
-  browser.capabilities.add(NAVIGATION_CAPABILITY);
-}
-
-/**
- * @param {import('./browser.d.ts').SkykitBrowser} browser
- * @param {unknown} viewOrScene
- * @param {Record<string, unknown>} [options]
- */
-async function transitionTo(browser, viewOrScene, options = {}) {
-  await ensureNavigation(browser);
-  const payload = normalizeTransitionPayload(viewOrScene, options);
-  return browser.viewer.actions.invoke(SKYKIT_ACTIONS.navigation.transitionTo, payload, { source: SOURCE });
-}
-
-/**
- * @param {import('./browser.d.ts').SkykitBrowser} browser
- * @param {unknown} sceneSpec
- */
-async function applyScene(browser, sceneSpec) {
-  const scene = /** @type {Record<string, unknown> | null} */ (
-    sceneSpec && typeof sceneSpec === 'object' ? sceneSpec : null
-  );
-  if (!scene) return null;
-  if (scene.view && typeof scene.view === 'object') {
-    browser.viewer.requestViewState(normalizeView(/** @type {Record<string, unknown>} */ (scene.view)), SOURCE);
-  }
-  const navigation = /** @type {Record<string, unknown> | null} */ (
-    scene.navigation && typeof scene.navigation === 'object' ? scene.navigation : null
-  );
-  if (navigation?.transitionTo) {
-    return transitionTo(browser, navigation.transitionTo);
-  }
-  return scene;
-}
-
-/**
- * @param {import('./browser.d.ts').SkykitBrowser} browser
- * @param {unknown} input
- * @param {Record<string, unknown>} [options]
- * @returns {Promise<import('./browser.d.ts').SkykitBrowserJourneyInstance>}
- */
-async function loadJourney(browser, input, options = {}) {
-  await ensureNavigation(browser);
-  const definition = await loadJourneyDefinition(input);
-  const plugin = isTimedJourney(definition)
-    ? createSkykitJourneyPlugin({
-      ...options,
-      timedJourney: definition,
-    })
-    : createSkykitJourneyPlugin({
-      ...options,
-      journey: createJourney(/** @type {import('@found-in-space/journey').CreateJourneyOptions} */ (definition)),
-    });
-  const uninstall = await browser.install(plugin);
-  let disposed = false;
-
-  return {
-    goTo(sceneId) {
-      assertActive();
-      return plugin.goTo?.(sceneId) ?? Promise.resolve(null);
-    },
-    next() {
-      assertActive();
-      return plugin.next?.() ?? Promise.resolve(null);
-    },
-    previous() {
-      assertActive();
-      return plugin.previous?.() ?? Promise.resolve(null);
-    },
-    play(payload) {
-      assertActive();
-      return plugin.play?.(payload) ?? 0;
-    },
-    pause() {
-      assertActive();
-      return plugin.pause?.() ?? 0;
-    },
-    seek(timeSecs) {
-      assertActive();
-      return plugin.seek?.({ timeSecs }) ?? 0;
-    },
-    getSnapshot() {
-      return {
-        disposed,
-        plugin: plugin.getSnapshot?.() ?? null,
-      };
-    },
-    dispose() {
-      if (disposed) return;
-      disposed = true;
-      uninstall();
-    },
-  };
-
-  function assertActive() {
-    if (disposed) throw new Error('SkyKit journey instance has been disposed.');
-  }
-}
-
-/**
- * @param {unknown} input
- * @returns {Promise<Record<string, unknown>>}
- */
-async function loadJourneyDefinition(input) {
-  if (typeof input === 'string') {
-    const response = await fetch(input);
-    if (!response.ok) throw new Error(`Failed to load SkyKit journey: ${response.status} ${response.statusText}`);
-    return /** @type {Record<string, unknown>} */ (await response.json());
-  }
-  if (!input || typeof input !== 'object') {
-    throw new TypeError('browser.journey.load() requires a URL or journey definition.');
-  }
-  return /** @type {Record<string, unknown>} */ (input);
-}
-
-/** @param {Record<string, unknown>} definition */
-function isTimedJourney(definition) {
-  return Number.isFinite(Number(definition.durationSecs))
-    && (Array.isArray(definition.locationWaypoints)
-      || Array.isArray(definition.cameraLookWaypoints)
-      || Array.isArray(definition.cameraWaypoints));
-}
-
-/**
- * @param {unknown} input
- * @param {Record<string, unknown>} [options]
- */
-function normalizeTransitionPayload(input, options = {}) {
-  const source = /** @type {Record<string, unknown>} */ (
-    input && typeof input === 'object' ? input : { lookAt: input }
-  );
-  if (source.navigation && typeof source.navigation === 'object') {
-    const navigation = /** @type {Record<string, unknown>} */ (source.navigation);
-    if (navigation.transitionTo) return normalizeTransitionPayload(navigation.transitionTo, options);
-  }
-  const viewSource = source.view && typeof source.view === 'object'
-    ? /** @type {Record<string, unknown>} */ (source.view)
-    : source.to && typeof source.to === 'object'
-      ? /** @type {Record<string, unknown>} */ (source.to)
-      : stripTransitionOptions(source);
-  return {
-    ...stripUndefined({
-      ...source,
-      ...options,
-      view: normalizeView(viewSource),
-      durationSecs: options.durationSecs ?? source.durationSecs,
-    }),
-  };
-}
-
-/** @param {Record<string, unknown>} input */
-function normalizeView(input) {
-  const lookAt = input.lookAt ?? (
-    hasLookAtShape(input) ? input : undefined
-  );
-  return {
-    ...input,
-    ...(lookAt !== undefined ? { lookAt: normalizeLookAt(lookAt) } : {}),
-  };
-}
-
-/** @param {unknown} input */
-function normalizeLookAt(input) {
-  if (typeof input !== 'string') return input;
-  return parseSpatialLookAtText(input) ?? { star: input };
-}
-
-/** @param {Record<string, unknown>} input */
-function stripTransitionOptions(input) {
-  const {
-    durationSecs: _durationSecs,
-    movement: _movement,
-    orientation: _orientation,
-    orientationDurationSecs: _orientationDurationSecs,
-    movementDurationSecs: _movementDurationSecs,
-    onArrive: _onArrive,
-    ...view
-  } = input;
-  return view;
-}
-
-/** @param {Record<string, unknown>} input */
-function hasLookAtShape(input) {
-  return 'raDeg' in input
-    || 'raHours' in input
-    || 'decDeg' in input
-    || 'targetPc' in input
-    || 'orientationIcrs' in input
-    || 'star' in input;
-}
-
-/** @param {Record<string, unknown>} input */
-function stripUndefined(input) {
-  return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
-}

package/src/story.d.ts

@@ -1,57 +0,0 @@
-import type { SkykitBrowser, SkykitBrowserHost, SkykitBrowserOptions } from './browser.js';
-import type { SkykitViewState, SkykitViewer, Vector3Like } from './index.js';
-
-export type SkykitStoryHost = SkykitBrowserHost;
-
-export interface SkykitStoryChapterInput {
-  id?: string;
-  title?: string;
-  body?: string;
-  bodyHtml?: string | null;
-  targetPc?: Vector3Like | null;
-  observerPc?: Vector3Like | null;
-  view?: Partial<SkykitViewState> | null;
-  annotations?: unknown[];
-}
-
-export interface SkykitStoryChapter {
-  id: string;
-  title: string;
-  body: string;
-  bodyHtml: string | null;
-  targetPc: Vector3Like | null;
-  observerPc: Vector3Like | null;
-  view: Partial<SkykitViewState> | null;
-  annotations: unknown[];
-}
-
-export interface SkykitStoryOptions extends SkykitBrowserOptions {
-  host?: SkykitStoryHost;
-  src?: string;
-  chapters?: Iterable<SkykitStoryChapterInput>;
-  initialChapter?: string | number;
-  controls?: boolean;
-  previousLabel?: string;
-  nextLabel?: string;
-}
-
-export interface SkykitStory {
-  browser: SkykitBrowser;
-  viewer: SkykitViewer;
-  chapters: SkykitStoryChapter[];
-  readonly currentIndex: number;
-  readonly currentChapter: SkykitStoryChapter | null;
-  next(): SkykitStoryChapter | null;
-  previous(): SkykitStoryChapter | null;
-  goTo(indexOrId: number | string): SkykitStoryChapter | null;
-  dispose(): Promise<void>;
-}
-
-export declare function createSkykitStory(
-  host: SkykitStoryHost,
-  options?: SkykitStoryOptions
-): Promise<SkykitStory>;
-
-export declare function createSkykitStory(
-  options?: SkykitStoryOptions
-): Promise<SkykitStory>;