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

package/src/touch-os.js

@@ -1,12 +1,19 @@
 import {
+  createAppShell,
   createButton,
   createColumn,
   createDPad,
   createDockLayout,
   createHoldButton,
+  createNode,
+  createRect,
   createRuntime,
+  createTabletHomePresentation,
   createTextLabel,
+  createTouchAppRegistry,
   createValueReadout,
+  defineTouchApp,
+  rectContainsPoint,
 } from '@found-in-space/touch-os';
 import {
   createHudPanelDriver,
@@ -31,6 +38,185 @@ const DEFAULT_PANEL_DRIVER_OPTIONS = Object.freeze({
   pointerClaimPolicy: 'block-on-hit',
   transparent: true,
 });
+const DEFAULT_TABLET_LAUNCHER_LAYOUT = Object.freeze({
+  tileWidth: 84,
+  tileHeight: 88,
+  gap: 10,
+  bodyPadding: 10,
+  iconMinSize: 38,
+  iconMaxSize: 46,
+  iconScale: 0.55,
+  iconTop: 2,
+  labelGap: 5,
+});
+
+const SkykitSurfaceAppFrameComponent = {
+  kind: 'skykit-surface-app-frame',
+  getChildren(ctx) {
+    return ctx.props.child ? [ctx.props.child] : [];
+  },
+  measure(ctx) {
+    const padding = positiveFinite(ctx.props.padding, 0);
+    const width = Math.max(0, ctx.constraints.maxWidth - padding * 2);
+    const height = Math.max(0, ctx.constraints.maxHeight - padding * 2);
+    if (ctx.props.child) {
+      ctx.measureChild(ctx.props.child.id, {
+        minWidth: 0,
+        minHeight: 0,
+        maxWidth: width,
+        maxHeight: height,
+      });
+    }
+    return {
+      width: ctx.constraints.maxWidth,
+      height: ctx.constraints.maxHeight,
+    };
+  },
+  layout(ctx) {
+    const padding = positiveFinite(ctx.props.padding, 0);
+    const content = createRect(
+      ctx.bounds.x + padding,
+      ctx.bounds.y + padding,
+      Math.max(0, ctx.bounds.width - padding * 2),
+      Math.max(0, ctx.bounds.height - padding * 2),
+    );
+    if (ctx.props.child) {
+      ctx.setChildBounds(ctx.props.child.id, content);
+    }
+    ctx.setContentBounds(content);
+  },
+  render(ctx) {
+    const theme = ctx.services.theme.getTokens();
+    return [{
+      type: 'rect',
+      componentId: ctx.id,
+      role: 'skykit-surface-app-frame',
+      rect: ctx.bounds,
+      fill: ctx.props.backgroundColor ?? theme.backgroundColor,
+      strokeWidth: 0,
+      radius: 0,
+    }];
+  },
+  hitTest(ctx) {
+    if (ctx.props.pointerOpaque === false || !rectContainsPoint(ctx.bounds, ctx.point)) {
+      return null;
+    }
+    return {
+      targetId: `${ctx.id}:background`,
+      role: 'surface-app-background',
+    };
+  },
+};
+
+/**
+ * Build a SkyKit-flavored touch-os tablet shell from ordinary touch apps.
+ *
+ * @param {import('./touch-os.d.ts').SkykitTabletRootOptions} [options]
+ * @returns {import('@found-in-space/touch-os').DisplayNode}
+ */
+export function createSkykitTabletRoot(options = {}) {
+  if (!options || typeof options !== 'object') {
+    throw new TypeError('createSkykitTabletRoot requires an options object.');
+  }
+
+  const id = options.id ?? 'skykit-tablet';
+  const registry = options.registry ?? createTouchAppRegistry(options.apps ?? []);
+  const presentation = options.presentation ?? createTabletHomePresentation({
+    homeControl: options.homeControl ?? 'button',
+    taskSwitcher: options.taskSwitcher ?? 'cards',
+    taskCloseControl: options.taskCloseControl ?? 'button',
+    launcherLayout: {
+      ...DEFAULT_TABLET_LAUNCHER_LAYOUT,
+      ...(options.launcherLayout ?? {}),
+    },
+  });
+
+  return createAppShell(id, {
+    registry,
+    presentation,
+    appHostMode: options.appHostMode ?? 'same-runtime',
+    homeKey: options.homeKey ?? true,
+    keepAlive: options.keepAlive ?? true,
+    ...(options.initialSessions === undefined ? {} : { initialSessions: options.initialSessions }),
+    ...(options.appStates === undefined ? {} : { appStates: options.appStates }),
+    ...(options.getAppState === undefined ? {} : { getAppState: options.getAppState }),
+    ...(options.forwardAppOutputs === undefined ? {} : { forwardAppOutputs: options.forwardAppOutputs }),
+    ...(options.storage === undefined ? {} : { storage: options.storage }),
+    ...(options.surfaces === undefined ? {} : { surfaces: options.surfaces }),
+    ...(options.onAppEvent === undefined ? {} : { onAppEvent: options.onAppEvent }),
+    ...(options.onShellChange === undefined ? {} : { onShellChange: options.onShellChange }),
+  });
+}
+
+/**
+ * Wrap a display node as a full-screen tablet app. This is useful for surface
+ * consumers such as HR diagrams, camera mirrors, or other panel-hosted views.
+ *
+ * @template TState
+ * @param {import('./touch-os.d.ts').SkykitSurfaceAppOptions<TState>} options
+ * @returns {import('@found-in-space/touch-os').TouchAppModule<TState>}
+ */
+export function createSkykitSurfaceApp(options) {
+  if (!options || typeof options !== 'object') {
+    throw new TypeError('createSkykitSurfaceApp requires options.');
+  }
+  const id = requiredString(options.id, 'createSkykitSurfaceApp id');
+  const name = requiredString(options.name, 'createSkykitSurfaceApp name');
+  const rootId = options.rootId ?? `${id}:root`;
+
+  return defineTouchApp({
+    manifest: {
+      id,
+      name,
+      version: options.version ?? '1.0.0',
+      icon: options.icon ?? createSymbolIcon(name),
+      capabilities: options.capabilities ?? ['surfaces'],
+      preferredWindow: {
+        width: options.preferredWindow?.width ?? 360,
+        height: options.preferredWindow?.height ?? 300,
+        minWidth: options.preferredWindow?.minWidth ?? 260,
+        minHeight: options.preferredWindow?.minHeight ?? 180,
+        resizable: options.preferredWindow?.resizable ?? false,
+      },
+    },
+    createApp(ctx) {
+      return {
+        render(state) {
+          const child = resolveSurfaceAppNode(options.node, {
+            context: ctx,
+            state,
+          });
+          if (!child) {
+            return createTextLabel(`${rootId}:empty`, {
+              text: options.emptyLabel ?? `${name} unavailable`,
+              tone: 'muted',
+              align: 'center',
+            });
+          }
+          return createSkykitSurfaceAppFrame(rootId, {
+            child,
+            padding: options.padding ?? 0,
+            pointerOpaque: options.pointerOpaque !== false,
+            backgroundColor: options.backgroundColor,
+          });
+        },
+        handleOutput(output) {
+          options.onOutput?.(output, { context: ctx });
+          emitSkykitSurfaceAppOutput(ctx, output);
+        },
+      };
+    },
+  });
+}
+
+/**
+ * @param {string} id
+ * @param {{ child: import('@found-in-space/touch-os').DisplayNode; padding?: number; pointerOpaque?: boolean; backgroundColor?: string }} props
+ * @returns {import('@found-in-space/touch-os').DisplayNode}
+ */
+function createSkykitSurfaceAppFrame(id, props) {
+  return createNode(id, SkykitSurfaceAppFrameComponent, props);
+}
 
 /**
  * Create a SkyKit plugin that mounts a touch-os HUD and routes action outputs
@@ -901,6 +1087,95 @@ function finiteNumber(value, fallback) {
   return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
 }
 
+/**
+ * @param {unknown} value
+ * @param {string} context
+ * @returns {string}
+ */
+function requiredString(value, context) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new TypeError(`${context} must be a non-empty string.`);
+  }
+  return value;
+}
+
+/**
+ * @param {import('./touch-os.d.ts').SkykitSurfaceAppOptions['node']} node
+ * @param {import('./touch-os.d.ts').SkykitSurfaceAppRenderContext} context
+ * @returns {import('@found-in-space/touch-os').DisplayNode | null}
+ */
+function resolveSurfaceAppNode(node, context) {
+  const resolved = typeof node === 'function' ? node(context) : node;
+  if (resolved == null) return null;
+  if (!resolved || typeof resolved !== 'object' || typeof resolved.id !== 'string') {
+    throw new TypeError('SkyKit surface app nodes must be display nodes.');
+  }
+  return resolved;
+}
+
+/**
+ * @param {import('@found-in-space/touch-os').TouchAppContext} context
+ * @param {unknown} output
+ */
+function emitSkykitSurfaceAppOutput(context, output) {
+  if (isTouchOsActionOutput(output)) {
+    context.actions.emit({
+      type: 'app-action',
+      appId: context.appId,
+      instanceId: context.instanceId,
+      windowId: context.windowId,
+      name: output.actionId,
+      ...(output.payload === undefined ? {} : { payload: output.payload }),
+      componentId: output.componentId,
+    });
+    return;
+  }
+  if (isTouchOsChangeOutput(output)) {
+    context.actions.emit({
+      type: 'app-change',
+      appId: context.appId,
+      instanceId: context.instanceId,
+      windowId: context.windowId,
+      name: `${output.field}.change`,
+      payload: {
+        field: output.field,
+        value: output.value,
+      },
+      componentId: output.componentId,
+    });
+  }
+}
+
+/**
+ * @param {unknown} output
+ * @returns {output is { type: 'change-request'; componentId: string; field: string; value: unknown }}
+ */
+function isTouchOsChangeOutput(output) {
+  return Boolean(output)
+    && typeof output === 'object'
+    && output.type === 'change-request'
+    && typeof output.componentId === 'string'
+    && typeof output.field === 'string';
+}
+
+/**
+ * @param {string} name
+ * @returns {{ kind: 'symbol'; value: string }}
+ */
+function createSymbolIcon(name) {
+  const letters = name
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((part) => part[0])
+    .join('')
+    .slice(0, 2)
+    .toUpperCase();
+  return {
+    kind: 'symbol',
+    value: letters || 'SK',
+  };
+}
+
 function now() {
   return typeof performance !== 'undefined' && typeof performance.now === 'function'
     ? performance.now()

package/src/utils.js

@@ -1,4 +1,7 @@
 import * as THREE from 'three';
+import {
+  resolveSpatialLookAt,
+} from '@found-in-space/spatial';
 
 export const DEFAULT_MAG_LIMIT = 6.5;
 export const IDENTITY_QUATERNION = Object.freeze({ x: 0, y: 0, z: 0, w: 1 });
@@ -86,16 +89,17 @@ export function resolveAnchorRoot(roots, anchorMode, scaleBandId) {
  * @param {number} revision
  * @returns {SkykitViewState}
  */
-export function normalizeViewState(input = {}, revision = 0) {
+export function normalizeViewState(input = {}, revision = 0, options = {}) {
   const observerPc = normalizeVector3(input.observerPc, { x: 0, y: 0, z: 0 });
   const coordinateUnitsPerParsec = positiveFinite(input.coordinateUnitsPerParsec, 1);
+  const look = resolveViewLook(input, observerPc, options);
   return {
     revision,
     observerPc,
     renderObserverPosition: normalizeVector3(input.renderObserverPosition, observerPc),
-    targetPc: input.targetPc == null ? null : normalizeVector3(input.targetPc, { x: 0, y: 0, z: 0 }),
-    directionIcrs: input.directionIcrs == null ? null : normalizeVector3(input.directionIcrs, { x: 0, y: 0, z: -1 }),
-    orientationIcrs: input.orientationIcrs == null ? null : normalizeQuaternion(input.orientationIcrs, IDENTITY_QUATERNION),
+    lookAt: look.lookAt,
+    targetPc: look.targetPc,
+    orientationIcrs: look.orientationIcrs,
     limitingMagnitude: finiteNumber(input.limitingMagnitude, DEFAULT_MAG_LIMIT),
     ...(input.verticalFovDeg !== undefined ? { verticalFovDeg: positiveFinite(input.verticalFovDeg, 40) } : {}),
     ...(input.aspectRatio !== undefined ? { aspectRatio: positiveFinite(input.aspectRatio, 1) } : {}),
@@ -110,8 +114,8 @@ export function cloneViewState(view) {
     ...view,
     observerPc: cloneVector3(view.observerPc),
     renderObserverPosition: cloneVector3(view.renderObserverPosition),
+    lookAt: cloneLookAt(view.lookAt),
     targetPc: view.targetPc ? cloneVector3(view.targetPc) : null,
-    directionIcrs: view.directionIcrs ? cloneVector3(view.directionIcrs) : null,
     orientationIcrs: view.orientationIcrs ? cloneQuaternion(view.orientationIcrs) : null,
     motion: view.motion ? cloneMotion(view.motion) : null,
   };
@@ -125,7 +129,6 @@ export function toStarOctreeViewPatch(view) {
     limitingMagnitude: view.limitingMagnitude,
     mDesired: view.limitingMagnitude,
     ...(view.targetPc ? { targetPc: view.targetPc } : {}),
-    ...(view.directionIcrs ? { directionIcrs: view.directionIcrs } : {}),
     ...(view.orientationIcrs ? { orientationIcrs: view.orientationIcrs } : {}),
     ...(view.verticalFovDeg !== undefined ? { verticalFovDeg: view.verticalFovDeg } : {}),
     ...(view.aspectRatio !== undefined ? { aspectRatio: view.aspectRatio } : {}),
@@ -134,6 +137,93 @@ export function toStarOctreeViewPatch(view) {
   return patch;
 }
 
+/**
+ * @param {Partial<SkykitViewState>} input
+ * @param {Record<string, unknown>} [options]
+ * @returns {Promise<Partial<SkykitViewState>>}
+ */
+export async function resolveViewLookAtInput(input = {}, options = {}) {
+  const observerPc = normalizeVector3(
+    input.observerPc ?? /** @type {{ observerPc?: unknown }} */ (options).observerPc,
+    { x: 0, y: 0, z: 0 },
+  );
+  const lookInput = input.lookAt
+    ?? (input.orientationIcrs ? { orientationIcrs: input.orientationIcrs } : null);
+  if (!lookInput) return input;
+  const resolved = await resolveSpatialLookAt(lookInput, {
+    observerPc,
+    resolveStar: typeof options.resolveStar === 'function'
+      ? /** @type {import('@found-in-space/spatial').ResolveSpatialLookAtOptions['resolveStar']} */ (options.resolveStar)
+      : undefined,
+    resolveBookmark: typeof options.resolveBookmark === 'function'
+      ? /** @type {import('@found-in-space/spatial').ResolveSpatialLookAtOptions['resolveBookmark']} */ (options.resolveBookmark)
+      : undefined,
+  });
+  const resolvedLook = /** @type {import('@found-in-space/spatial').SpatialResolvedLookAt} */ (resolved);
+  return {
+    ...input,
+    lookAt: /** @type {import('./index.d.ts').SkykitLookAtInput | null} */ (resolvedLook.lookAt),
+    targetPc: resolvedLook.targetPc,
+    orientationIcrs: resolvedLook.orientationIcrs,
+  };
+}
+
+/**
+ * @param {Partial<SkykitViewState>} input
+ * @param {Vector3Like} observerPc
+ * @param {Record<string, unknown>} [options]
+ * @returns {{ lookAt: import('./index.d.ts').SkykitLookAtInput | null; targetPc: Vector3Like | null; orientationIcrs: QuaternionLike | null }}
+ */
+function resolveViewLook(input, observerPc, options = {}) {
+  const lookInput = input.lookAt
+    ?? (input.orientationIcrs ? { orientationIcrs: input.orientationIcrs } : null);
+  if (!lookInput) {
+    return {
+      lookAt: null,
+      targetPc: null,
+      orientationIcrs: null,
+    };
+  }
+  const resolved = resolveSpatialLookAt(lookInput, {
+    observerPc,
+    resolveStar: typeof options.resolveStar === 'function'
+      ? /** @type {import('@found-in-space/spatial').ResolveSpatialLookAtOptions['resolveStar']} */ (options.resolveStar)
+      : undefined,
+    resolveBookmark: typeof options.resolveBookmark === 'function'
+      ? /** @type {import('@found-in-space/spatial').ResolveSpatialLookAtOptions['resolveBookmark']} */ (options.resolveBookmark)
+      : undefined,
+  });
+  if (resolved && typeof /** @type {Promise<unknown>} */ (resolved).then === 'function') {
+    throw new TypeError('normalizeViewState() received an async lookAt resolver result.');
+  }
+  const resolvedLook = /** @type {import('@found-in-space/spatial').SpatialResolvedLookAt} */ (resolved);
+  return {
+    lookAt: /** @type {import('./index.d.ts').SkykitLookAtInput | null} */ (cloneLookAt(resolvedLook.lookAt)),
+    targetPc: resolvedLook.targetPc
+      ? cloneVector3(resolvedLook.targetPc)
+      : (input.targetPc == null ? null : normalizeVector3(input.targetPc, { x: 0, y: 0, z: 0 })),
+    orientationIcrs: resolvedLook.orientationIcrs ? cloneQuaternion(resolvedLook.orientationIcrs) : null,
+  };
+}
+
+/**
+ * @param {unknown} lookAt
+ * @returns {import('./index.d.ts').SkykitLookAtInput | null}
+ */
+function cloneLookAt(lookAt) {
+  if (!lookAt || typeof lookAt !== 'object') return null;
+  const source = /** @type {Record<string, unknown>} */ (lookAt);
+  return {
+    ...source,
+    ...(source.targetPc && typeof source.targetPc === 'object'
+      ? { targetPc: cloneVector3(/** @type {Vector3Like} */ (source.targetPc)) }
+      : {}),
+    ...(source.orientationIcrs && typeof source.orientationIcrs === 'object'
+      ? { orientationIcrs: cloneQuaternion(/** @type {QuaternionLike} */ (source.orientationIcrs)) }
+      : {}),
+  };
+}
+
 /**
  * @param {SkykitPluginInput} plugin
  * @param {SkykitThreePluginContext} context

package/src/viewer-entry.d.ts

@@ -0,0 +1,10 @@
+import type * as ThreeNamespace from 'three';
+
+export declare const THREE: typeof ThreeNamespace;
+export {
+  createSkykitBrowser,
+  type SkykitBrowser,
+  type SkykitBrowserObjectHandle,
+  type SkykitBrowserObjectOptions,
+  type SkykitBrowserOptions,
+} from './browser.js';

package/src/viewer-entry.js

@@ -0,0 +1,4 @@
+import * as THREE from 'three';
+
+export { THREE };
+export { createSkykitBrowser } from './browser.js';

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}