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

package/src/three-shim.d.ts

@@ -17,6 +17,8 @@ declare module 'three' {
     updateMatrixWorld(force?: boolean): void;
   }
 
+  export type ColorRepresentation = number | string;
+
   export class Group extends Object3D {}
   export class Scene extends Object3D {}
   export class Camera extends Object3D {
@@ -105,10 +107,40 @@ declare module 'three' {
 
   export class ShaderMaterial extends Material {}
 
+  export class LineBasicMaterial extends Material {
+    constructor(parameters?: {
+      color?: ColorRepresentation;
+      transparent?: boolean;
+      opacity?: number;
+      depthTest?: boolean;
+      depthWrite?: boolean;
+    });
+  }
+
+  export class BufferAttribute {
+    array: ArrayLike<number>;
+    itemSize: number;
+    needsUpdate: boolean;
+    count: number;
+    constructor(array: ArrayLike<number>, itemSize: number, normalized?: boolean);
+  }
+
   export class BufferGeometry {
+    attributes: Record<string, BufferAttribute>;
+    setAttribute(name: string, attribute: BufferAttribute): this;
+    getAttribute(name: string): BufferAttribute | undefined;
+    computeBoundingSphere(): void;
     dispose(): void;
   }
 
+  export class Line extends Object3D {
+    geometry: BufferGeometry;
+    material: Material | Material[];
+    frustumCulled: boolean;
+    renderOrder: number;
+    constructor(geometry?: BufferGeometry, material?: Material | Material[]);
+  }
+
   export class Mesh extends Object3D {
     readonly isMesh: boolean;
     geometry: BufferGeometry;

package/src/touch-os.d.ts

@@ -1,9 +1,24 @@
 import type {
+  AppShellChange,
+  AppShellPresentation,
+  AppShellSession,
+  AppShellSessionSeed,
   DisplayNode,
   DisplayRuntime,
+  EmbeddedSurfaceService,
   RuntimeOutput,
   RuntimeOptions,
   SurfaceMetrics,
+  TabletHomeLauncherLayoutOptions,
+  TouchAppCapability,
+  TouchAppContext,
+  TouchAppEvent,
+  TouchAppModule,
+  TouchAppPreferredWindow,
+  TouchAppRegistry,
+  TouchAppStorage,
+  TouchIconDescriptor,
+  WindowManagerAppHostMode,
 } from '@found-in-space/touch-os';
 import type {
   HudPanelDriverOptions,
@@ -97,6 +112,55 @@ export interface TouchOsHudPlugin extends SkykitPlugin {
 
 export type TouchOsPanelDriverKind = 'hud' | 'pose-anchored' | 'scene';
 
+export interface SkykitTabletRootOptions {
+  id?: string;
+  apps?: readonly TouchAppModule<unknown>[];
+  registry?: TouchAppRegistry;
+  presentation?: AppShellPresentation;
+  appHostMode?: WindowManagerAppHostMode;
+  homeKey?: boolean;
+  keepAlive?: boolean;
+  initialSessions?: readonly AppShellSessionSeed[];
+  appStates?: Readonly<Record<string, unknown>>;
+  getAppState?: (session: AppShellSession) => unknown;
+  forwardAppOutputs?: boolean;
+  storage?: TouchAppStorage;
+  surfaces?: EmbeddedSurfaceService;
+  onAppEvent?: (event: TouchAppEvent) => void;
+  onShellChange?: (change: AppShellChange) => void;
+  homeControl?: 'button' | 'bar' | 'none';
+  taskSwitcher?: 'cards' | 'list' | 'none';
+  taskCloseControl?: 'button' | 'none';
+  launcherLayout?: TabletHomeLauncherLayoutOptions;
+}
+
+export interface SkykitSurfaceAppRenderContext<TState = unknown> {
+  context: TouchAppContext;
+  state: TState;
+}
+
+export interface SkykitSurfaceAppOutputContext {
+  context: TouchAppContext;
+}
+
+export interface SkykitSurfaceAppOptions<TState = unknown> {
+  id: string;
+  name: string;
+  version?: string;
+  icon?: TouchIconDescriptor;
+  capabilities?: readonly TouchAppCapability[];
+  preferredWindow?: TouchAppPreferredWindow;
+  rootId?: string;
+  node:
+    | DisplayNode
+    | ((context: SkykitSurfaceAppRenderContext<TState>) => DisplayNode | null | undefined);
+  padding?: number;
+  pointerOpaque?: boolean;
+  backgroundColor?: string;
+  emptyLabel?: string;
+  onOutput?: (output: RuntimeOutput, context: SkykitSurfaceAppOutputContext) => void;
+}
+
 export interface TouchOsPanelRootContext {
   id: string;
   context: SkykitPluginContext;
@@ -212,6 +276,12 @@ export interface CreateTouchOsHostFrameOptions {
   events?: readonly ThreePanelHostInputEvent[];
 }
 
+export declare function createSkykitTabletRoot(options?: SkykitTabletRootOptions): DisplayNode;
+
+export declare function createSkykitSurfaceApp<TState = unknown>(
+  options: SkykitSurfaceAppOptions<TState>
+): TouchAppModule<TState>;
+
 export declare function createTouchOsHudPlugin(options: TouchOsHudPluginOptions): TouchOsHudPlugin;
 export declare function createTouchOsPanelPlugin(options: TouchOsPanelPluginOptions): TouchOsPanelPlugin;
 

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';