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

package/src/index.d.ts

@@ -67,6 +67,18 @@ export interface QuaternionLike {
   w: number;
 }
 
+export interface SkykitLookAtInput {
+  targetPc?: Vector3Like | [number, number, number];
+  raDeg?: number;
+  raHours?: number;
+  decDeg?: number;
+  distancePc?: number;
+  star?: string | StarObjectRef | StarPickMeta | unknown;
+  orientationIcrs?: QuaternionLike;
+  positionAngleDeg?: number;
+  [key: string]: unknown;
+}
+
 export interface SkykitObserverMotion {
   velocityPcPerSec: Vector3Like;
   speedPcPerSec: number;
@@ -76,8 +88,8 @@ export interface SkykitViewState {
   revision: number;
   observerPc: Vector3Like;
   renderObserverPosition: Vector3Like;
+  lookAt?: SkykitLookAtInput | null;
   targetPc?: Vector3Like | null;
-  directionIcrs?: Vector3Like | null;
   orientationIcrs?: QuaternionLike | null;
   limitingMagnitude: number;
   verticalFovDeg?: number;
@@ -370,6 +382,8 @@ export interface SkykitViewerOptions {
   parts?: Iterable<SkykitThreePart>;
   plugins?: Iterable<SkykitPluginInput>;
   view?: Partial<SkykitViewState>;
+  resolveLookAtStar?: (star: unknown, lookAt: SkykitLookAtInput) => SkykitLookAtInput | Vector3Like | [number, number, number] | Promise<SkykitLookAtInput | Vector3Like | [number, number, number] | null> | null;
+  resolveLookAtBookmark?: (bookmarkId: string, lookAt: unknown) => SkykitLookAtInput | Vector3Like | [number, number, number] | Promise<SkykitLookAtInput | Vector3Like | [number, number, number] | null> | null;
   autoMountRenderer?: boolean;
 }
 
@@ -412,6 +426,7 @@ export interface SkykitViewer {
   readonly observerRig: SkykitObserverRig;
   readonly actions: SkykitActionRegistry;
   addPart(part: SkykitThreePart): SkykitPluginTeardown;
+  addPlugin(plugin: SkykitPluginInput): Promise<SkykitPluginTeardown>;
   getViewState(): SkykitViewState;
   requestViewState(patch: Partial<SkykitViewState>, reason?: string): void;
   update(deltaSeconds?: number, frameOptions?: SkykitFrameOptions): void;
@@ -501,11 +516,11 @@ export interface AnchoredImageCatalog {
   resolveTargetPc(key: string, options?: AnchoredImageTargetOptions): Vector3Like | null;
   resolveLookAt(key: string, options?: AnchoredImageLookAtOptions): AnchoredImageLookAtResult | null;
   resolveNearest(
-    directionIcrs: Vector3Like | [number, number, number],
+    lookDirection: Vector3Like | [number, number, number],
     options?: AnchoredImageResolveNearestOptions
   ): AnchoredImageMatch | null;
   resolveWithinAngle(
-    directionIcrs: Vector3Like | [number, number, number],
+    lookDirection: Vector3Like | [number, number, number],
     options: AnchoredImageResolveWithinAngleOptions
   ): AnchoredImageMatch[];
 }
@@ -553,6 +568,8 @@ export interface AnchoredImageSkyPluginOptions {
   catalog: AnchoredImageCatalog;
   controller: AnchoredImageController;
   loading?: AnchoredImageSkyLoading;
+  anchorMode?: SkykitLayerAnchorMode;
+  scaleBandId?: string;
   fixedAtInfinity?: boolean;
   radius?: number;
   opacity?: number;
@@ -674,7 +691,7 @@ export interface SkykitStarSourceRestartRetentionPolicy {
 }
 
 export interface SkykitHrDiagramTouchOsOptions {
-  surfaces?: EmbeddedSurfaceService;
+  surfaces?: EmbeddedSurfaceService | (() => EmbeddedSurfaceService | null | undefined);
   sourceId?: string;
   componentId?: string;
   width?: number;
@@ -938,6 +955,16 @@ export interface SkykitJourneyPluginOptions {
   ) => void;
 }
 
+export interface SkykitJourneyPlugin extends SkykitPlugin {
+  goTo(payload: unknown): Promise<JourneySceneSpec | null>;
+  next(): Promise<JourneySceneSpec | null>;
+  previous(): Promise<JourneySceneSpec | null>;
+  seek(payload: unknown): number;
+  play(payload?: unknown): number;
+  pause(): number;
+  getSnapshot(): unknown;
+}
+
 export interface SkykitSpatialPreloadStrategyOptions {
   combine?: boolean;
   baseStrategy?: StarCellStrategy;
@@ -1170,9 +1197,7 @@ export declare function createKeyboardNavigationPlugin(options?: SkykitKeyboardN
 export declare function createSkykitNavigationPlugin(options?: SkykitNavigationPluginOptions): SkykitPlugin & {
   getSnapshot(): unknown;
 };
-export declare function createSkykitJourneyPlugin(options?: SkykitJourneyPluginOptions): SkykitPlugin & {
-  getSnapshot(): unknown;
-};
+export declare function createSkykitJourneyPlugin(options?: SkykitJourneyPluginOptions): SkykitJourneyPlugin;
 export declare function createSkykitStarPreloadRequestsFromSpatialHints(
   hints: Iterable<SpatialPreloadHint>,
   options?: SkykitSpatialPreloadStrategyOptions

package/src/plugins.js

@@ -19,6 +19,7 @@ import {
   createOrbitTransferRoute,
   createSpatialPoseTransition,
   createSpatialNavigationAutomation,
+  resolveSpatialLookAt,
   resolveSpatialTarget,
 } from '@found-in-space/spatial';
 
@@ -219,8 +220,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 +371,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,
@@ -391,7 +410,7 @@ export function createSkykitNavigationPlugin(options = {}) {
 
 /**
  * @param {import('./index.d.ts').SkykitJourneyPluginOptions} [options]
- * @returns {SkykitPlugin & { getSnapshot(): unknown }}
+ * @returns {import('./index.d.ts').SkykitJourneyPlugin}
  */
 export function createSkykitJourneyPlugin(options = {}) {
   const id = options.id ?? 'journey';
@@ -458,56 +477,81 @@ export function createSkykitJourneyPlugin(options = {}) {
     id,
     setup(context) {
       const threeContext = /** @type {import('./index.d.ts').SkykitThreePluginContext} */ (context);
-      threeContext.addPart(part);
-      threeContext.addDisposable(registerJourneyActions(threeContext));
+      const removePart = threeContext.addPart(part);
+      const unregisterActions = registerJourneyActions(threeContext);
+      return () => {
+        unregisterActions();
+        removePart();
+      };
     },
+    goTo,
+    next,
+    previous,
+    seek,
+    play,
+    pause,
     getSnapshot,
   };
 
+  /** @param {unknown} payload */
+  async function goTo(payload) {
+    await pendingSceneApplication;
+    const sceneId = resolveSceneId(payload);
+    const spec = sceneId && controller ? controller.goTo(sceneId, { source: SKYKIT_ACTIONS.journey.goToChapter }) : null;
+    await pendingSceneApplication;
+    return spec;
+  }
+
+  async function next() {
+    await pendingSceneApplication;
+    const spec = controller?.next({ source: SKYKIT_ACTIONS.journey.next }) ?? null;
+    await pendingSceneApplication;
+    return spec;
+  }
+
+  async function previous() {
+    await pendingSceneApplication;
+    const spec = controller?.previous({ source: SKYKIT_ACTIONS.journey.previous }) ?? null;
+    await pendingSceneApplication;
+    return spec;
+  }
+
+  /** @param {unknown} payload */
+  function seek(payload) {
+    currentTimeSecs = clampTime(resolveTimeSecs(payload), evaluator?.durationSecs ?? Number.POSITIVE_INFINITY);
+    if (evaluator && pluginContext) applyTimedFrame(evaluator.evaluate(currentTimeSecs), { viewer: pluginContext.viewer, view: pluginContext.getViewState() });
+    if (pluginContext) emitTimedPreloadHints(pluginContext, 'seek');
+    return currentTimeSecs;
+  }
+
+  /** @param {unknown} [payload] */
+  function play(payload) {
+    if (payload && typeof payload === 'object' && 'timeSecs' in payload) {
+      currentTimeSecs = clampTime(resolveTimeSecs(payload), evaluator?.durationSecs ?? Number.POSITIVE_INFINITY);
+    }
+    playing = true;
+    if (pluginContext) emitTimedPreloadHints(pluginContext, 'play');
+    return currentTimeSecs;
+  }
+
+  function pause() {
+    playing = false;
+    return currentTimeSecs;
+  }
+
   /** @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;
-      }, {
+      context.actions.registerAction(SKYKIT_ACTIONS.journey.goToChapter, ({ payload }) => goTo(payload), { label: 'Go to journey chapter' }),
+      context.actions.registerAction(SKYKIT_ACTIONS.journey.next, () => next(), {
         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;
-      }, {
+      context.actions.registerAction(SKYKIT_ACTIONS.journey.previous, () => previous(), {
         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' }),
+      context.actions.registerAction(SKYKIT_ACTIONS.journey.seek, ({ payload }) => seek(payload), { label: 'Seek journey time' }),
+      context.actions.registerAction(SKYKIT_ACTIONS.journey.play, ({ payload }) => play(payload), { label: 'Play journey' }),
+      context.actions.registerAction(SKYKIT_ACTIONS.journey.pause, () => pause(), { label: 'Pause journey' }),
     ];
     return () => {
       for (const unregister of unregisters.reverse()) unregister();

package/src/story.d.ts

@@ -0,0 +1,57 @@
+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>;