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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@found-in-space/skykit",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-dev.20260527.0",
   "description": "Slim composition and teaching layer for Found in Space packages",
   "license": "MIT",
   "type": "module",
@@ -23,10 +23,34 @@
       "types": "./src/browser.d.ts",
       "default": "./src/browser.js"
     },
+    "./browser-addons": {
+      "types": "./src/browser-addons.d.ts",
+      "default": "./src/browser-addons.js"
+    },
+    "./browser-constellations": {
+      "types": "./src/browser-constellations.d.ts",
+      "default": "./src/browser-constellations.js"
+    },
+    "./browser-journey": {
+      "types": "./src/browser-journey.d.ts",
+      "default": "./src/browser-journey.js"
+    },
     "./embed": {
       "types": "./src/embed.d.ts",
       "default": "./src/embed.js"
     },
+    "./viewer": {
+      "types": "./src/viewer-entry.d.ts",
+      "default": "./src/viewer-entry.js"
+    },
+    "./data": {
+      "types": "./src/data.d.ts",
+      "default": "./src/data.js"
+    },
+    "./story": {
+      "types": "./src/story.d.ts",
+      "default": "./src/story.js"
+    },
     "./parallax": {
       "types": "./src/parallax.d.ts",
       "default": "./src/parallax.js"
@@ -46,7 +70,8 @@
     "README.md"
   ],
   "sideEffects": [
-    "./src/embed.js"
+    "./src/embed.js",
+    "./src/story.js"
   ],
   "scripts": {
     "typecheck": "tsc -p tsconfig.json --noEmit",
@@ -56,16 +81,17 @@
     "@found-in-space/anchored-image": "0.2.0-alpha.0",
     "@found-in-space/hr-diagram": "0.2.0-alpha.0",
     "@found-in-space/journey": "0.2.0-alpha.0",
-    "@found-in-space/spatial": "0.2.0-alpha.0",
+    "@found-in-space/meta-sidecar-provider": "0.2.0-alpha.0",
+    "@found-in-space/spatial": "0.2.0-dev.20260527.0",
     "@found-in-space/star-octree-provider": "0.2.0-alpha.0",
     "@found-in-space/star-trees": "0.2.0-alpha.0",
     "@found-in-space/three-star-field": "0.2.0-alpha.0"
   },
   "devDependencies": {
-    "@found-in-space/touch-os": "0.2.0-dev.1"
+    "@found-in-space/touch-os": "0.2.0-dev.3"
   },
   "peerDependencies": {
-    "@found-in-space/touch-os": ">=0.2.0-dev.1 <1",
+    "@found-in-space/touch-os": ">=0.2.0-dev.3 <1",
     "three": "^0.170.0"
   },
   "peerDependenciesMeta": {

package/src/__tests__/skykit-anchored-images.test.js

@@ -147,7 +147,7 @@ test('anchored image sky plugin preloads controller selection and mounts fixed-a
   });
   const viewer = await createSkykitViewer({
     renderer: createRenderer(),
-    view: { directionIcrs: { x: 1, y: 0, z: 0 } },
+    view: { lookAt: { raDeg: 0, decDeg: 0 } },
     plugins: [plugin],
   });
 
@@ -161,6 +161,34 @@ test('anchored image sky plugin preloads controller selection and mounts fixed-a
   await viewer.dispose();
 });
 
+test('anchored image sky plugin can mount art into a named scale band', async () => {
+  const catalog = await createAnchoredImageCatalog({ manifest: MANIFEST });
+  const requests = [];
+  const scaleRoot = new THREE.Group();
+  const plugin = createAnchoredImageSkyPlugin({
+    id: 'banded-art',
+    catalog,
+    controller: createManualAnchoredImageController({ selection: 'alpha' }),
+    loading: 'preload',
+    textureLoader: createTextureLoader(requests),
+    anchorMode: 'scale-banded',
+    scaleBandId: 'constellation-art',
+  });
+  const viewer = await createSkykitViewer({
+    renderer: createRenderer(),
+    roots: {
+      scaleBandedContentRoots: new Map([['constellation-art', scaleRoot]]),
+    },
+    view: { lookAt: { raDeg: 0, decDeg: 0 } },
+    plugins: [plugin],
+  });
+
+  assert.deepEqual(requests, ['alpha.png']);
+  assert.equal(scaleRoot.children.some((child) => child.name === 'banded-art'), true);
+
+  await viewer.dispose();
+});
+
 test('anchored image sky plugin lazy-loads active controller entries and caches them', async () => {
   const catalog = await createAnchoredImageCatalog({ manifest: MANIFEST });
   const requests = [];
@@ -174,13 +202,13 @@ test('anchored image sky plugin lazy-loads active controller entries and caches
   });
   const viewer = await createSkykitViewer({
     renderer: createRenderer(),
-    view: { directionIcrs: { x: 1, y: 0, z: 0 } },
+    view: { lookAt: { raDeg: 0, decDeg: 0 } },
     plugins: [plugin],
   });
   await flushPromises();
 
   assert.deepEqual(requests, ['alpha.png']);
-  viewer.requestViewState({ directionIcrs: { x: 0, y: 1, z: 0 } }, 'test-active-change');
+  viewer.requestViewState({ lookAt: { raDeg: 90, decDeg: 0 } }, 'test-active-change');
   viewer.update(0);
   await flushPromises();
   assert.deepEqual(requests, ['alpha.png', 'beta.png']);
@@ -208,7 +236,7 @@ test('anchored image sky plugin fades opacity by seconds and keeps fading object
   });
   const viewer = await createSkykitViewer({
     renderer: createRenderer(),
-    view: { directionIcrs: { x: 1, y: 0, z: 0 } },
+    view: { lookAt: { raDeg: 0, decDeg: 0 } },
     plugins: [plugin],
   });
   await flushPromises();

package/src/__tests__/skykit-browser.test.js

@@ -2,6 +2,10 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 import * as THREE from 'three';
 
+import {
+  installSkykitBrowserGlobal,
+  registerBrowserInstance,
+} from '../browser-addons.js';
 import { createSkykitBrowser } from '../browser.js';
 
 test('createSkykitBrowser wires the starter viewer and extra plugins', async () => {
@@ -44,6 +48,20 @@ test('createSkykitBrowser wires the starter viewer and extra plugins', async ()
     assert.deepEqual(extraPartCalls, ['attach', 'start']);
     assert.match(status.textContent, /"starsLoaded": 0/);
 
+    const marker = new THREE.Object3D();
+    const markerHandle = browser.addObject(marker, {
+      id: 'hyades-marker',
+      positionPc: { x: 17.574, y: 42.316, z: 13.963 },
+    });
+    await Promise.resolve();
+    assert.ok(Math.abs(marker.position.x - 0.017574) < 1e-12);
+    assert.ok(Math.abs(marker.position.y - 0.042316) < 1e-12);
+    assert.ok(Math.abs(marker.position.z - 0.013963) < 1e-12);
+    assert.equal(browser.viewer.roots.originContentRoot.children.includes(marker), true);
+    markerHandle.remove();
+    await Promise.resolve();
+    assert.equal(browser.viewer.roots.originContentRoot.children.includes(marker), false);
+
     browser.resize();
     assert.equal(fakeWindow.addedEvents.length, 0);
 
@@ -88,6 +106,205 @@ test('createSkykitBrowser registers resize and page-lifecycle cleanup by default
   });
 });
 
+test('createSkykitBrowser accepts startup lookAt and mouse look mode', async () => {
+  await withFakeWindow(async () => {
+    const browser = await createSkykitBrowser({
+      host: createHost(),
+      status: false,
+      renderer: createRenderer(),
+      provider: createProvider(),
+      starField: createStarField(),
+      autoResize: false,
+      autoDispose: false,
+      autoStart: false,
+      mouseMode: 'strafe',
+      lookAt: { targetPc: { x: 10, y: 0, z: 0 } },
+    });
+
+    const view = browser.viewer.getViewState();
+    assert.deepEqual(view.targetPc, { x: 10, y: 0, z: 0 });
+    assert.ok(view.orientationIcrs);
+    assert.equal(
+      browser.viewer.getSnapshot().parts.some((part) => part.id === 'mouse-look'),
+      true,
+    );
+    assert.equal(
+      browser.viewer.getSnapshot().parts.some((part) => part.id === 'sky-grab'),
+      false,
+    );
+
+    await browser.dispose();
+  });
+});
+
+test('createSkykitBrowser can disable mouse drag controls', async () => {
+  await withFakeWindow(async () => {
+    const browser = await createSkykitBrowser({
+      host: createHost(),
+      status: false,
+      renderer: createRenderer(),
+      provider: createProvider(),
+      starField: createStarField(),
+      autoResize: false,
+      autoDispose: false,
+      autoStart: false,
+      mouseMode: 'none',
+    });
+
+    assert.equal(
+      browser.viewer.getSnapshot().parts.some((part) => part.id === 'mouse-look' || part.id === 'sky-grab'),
+      false,
+    );
+
+    await browser.dispose();
+  });
+});
+
+test('browser.install adds plugins after startup and cleans returned teardowns', async () => {
+  await withFakeWindow(async () => {
+    const calls = [];
+    const browser = await createSkykitBrowser({
+      host: createHost(),
+      status: false,
+      renderer: createRenderer(),
+      provider: createProvider(),
+      starField: createStarField(),
+      autoResize: false,
+      autoDispose: false,
+      autoStart: false,
+    });
+
+    const uninstall = await browser.install((context) => {
+      context.addPart({
+        id: 'late-part',
+        attach() { calls.push('attach'); },
+        start() { calls.push('start'); },
+      });
+      return () => calls.push('teardown');
+    });
+
+    await Promise.resolve();
+    assert.deepEqual(calls, ['attach', 'start']);
+    assert.equal(browser.viewer.getSnapshot().parts.some((part) => part.id === 'late-part'), true);
+    uninstall();
+    assert.deepEqual(calls, ['attach', 'start', 'teardown']);
+
+    await browser.dispose();
+  });
+});
+
+test('browser journey capability transitions through navigation actions and loads instances', async () => {
+  await withFakeWindow(async () => {
+    const browser = await createSkykitBrowser({
+      host: createHost(),
+      status: false,
+      renderer: createRenderer(),
+      provider: createProvider(),
+      starField: createStarField(),
+      autoResize: false,
+      autoDispose: false,
+      autoStart: false,
+    });
+
+    await browser.journey.transitionTo({
+      lookAt: { targetPc: { x: 10, y: 0, z: 0 } },
+      durationSecs: 1,
+    });
+    browser.viewer.update(1);
+    browser.viewer.update(0);
+    assert.ok(browser.viewer.getViewState().orientationIcrs);
+    assert.equal(browser.capabilities.has('skykit:navigation'), true);
+
+    const journey = await browser.journey.load({
+      initial: 'home',
+      scenes: {
+        home: { view: { observerPc: { x: 0, y: 0, z: 0 } } },
+        away: { view: { observerPc: { x: 1, y: 2, z: 3 } } },
+      },
+    });
+    await journey.goTo('away');
+    browser.viewer.update(0);
+    assert.deepEqual(browser.viewer.getViewState().observerPc, { x: 1, y: 2, z: 3 });
+    assert.equal(journey.getSnapshot().disposed, false);
+    journey.dispose();
+    assert.equal(journey.getSnapshot().disposed, true);
+
+    await browser.dispose();
+  });
+});
+
+test('browser constellations capability loads manifest boundaries without art', async () => {
+  await withFakeWindow(async () => {
+    const browser = await createSkykitBrowser({
+      host: createHost(),
+      status: false,
+      renderer: createRenderer(),
+      provider: createProvider(),
+      starField: createStarField(),
+      autoResize: false,
+      autoDispose: false,
+      autoStart: false,
+    });
+
+    const constellations = await browser.constellations.load({
+      art: 'off',
+      manifest: {
+        id: 'test-skyculture',
+        boundaries: {
+          edges: ['001:002 M+ 00:00:00 +00:00:00 01:00:00 +00:00:00 AAA BBB'],
+        },
+        constellations: [],
+      },
+    });
+
+    assert.equal(constellations.getSnapshot().lineCount, 1);
+    assert.equal(browser.capabilities.has('skykit:browser.constellations'), true);
+    assert.equal(browser.viewer.roots.observerContentRoot.children.some((child) => child.name === 'constellation-boundaries'), true);
+    assert.equal(constellations.hide(), false);
+    assert.equal(constellations.show(), true);
+
+    await browser.dispose();
+  });
+});
+
+test('Skykit browser global resolves existing and future browsers and installs add-ons once', async () => {
+  await withFakeWindow(async () => {
+    const service = installSkykitBrowserGlobal(/** @type {typeof globalThis} */ ({}));
+    const host = createHost();
+    const browser = await createSkykitBrowser({
+      host,
+      status: false,
+      renderer: createRenderer(),
+      provider: createProvider(),
+      starField: createStarField(),
+      autoResize: false,
+      autoDispose: false,
+      autoStart: false,
+    });
+    let installs = 0;
+    service.registerBrowserAddon({
+      id: 'test-addon',
+      install({ browser: installedBrowser }) {
+        installs += 1;
+        assert.equal(installedBrowser, browser);
+      },
+    });
+
+    const unregister = registerBrowserInstance(service, host, browser);
+    assert.equal(await service.whenReady(), browser);
+    assert.equal(installs, 1);
+    service.registerBrowserAddon({
+      id: 'test-addon',
+      install() {
+        installs += 1;
+      },
+    });
+    assert.equal(installs, 1);
+    unregister();
+    await browser.dispose();
+  });
+});
+
 async function withFakeWindow(callback) {
   const previousWindow = globalThis.window;
   const fakeWindow = {

package/src/__tests__/skykit-data.test.js

@@ -0,0 +1,131 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  formatStarLabel,
+  loadStarLabels,
+  loadStarRows,
+  rowsFromStarCells,
+  streamStarRows,
+} from '../data.js';
+
+test('rowsFromStarCells converts cells to plain app rows', () => {
+  const rows = rowsFromStarCells([createCell()], {
+    observerPc: { x: 0, y: 0, z: 0 },
+  });
+
+  assert.equal(rows.length, 2);
+  assert.deepEqual(rows[0].positionPc, { x: 1, y: 2, z: 2 });
+  assert.equal(rows[0].distancePc, 3);
+  assert.equal(rows[0].apparentMagnitude, 1 + 5 * (Math.log10(3) - 1));
+  assert.equal(rows[0].temperatureK, 5800);
+  assert.deepEqual(rows[0].ref, {
+    datasetId: 'dataset-a',
+    level: 1,
+    mortonCode: '2',
+    ordinal: 0,
+  });
+});
+
+test('loadStarRows streams provider cells, filters visible rows, and respects maxStars', async () => {
+  const provider = createProvider();
+  const rows = await loadStarRows({
+    provider,
+    limitingMagnitude: 4,
+    maxStars: 1,
+    sortBy: 'distancePc',
+  });
+
+  assert.equal(provider.disposed, false);
+  assert.equal(provider.streamOptions.length, 1);
+  assert.deepEqual(provider.streamOptions[0].view.observerPc, { x: 0, y: 0, z: 0 });
+  assert.deepEqual(provider.streamOptions[0].attributes, ['position', 'magAbs', 'teffLog8', 'objectRef']);
+  assert.equal(rows.length, 1);
+  assert.equal(rows[0].ordinal, 0);
+});
+
+test('streamStarRows yields row batches without exposing cell deltas', async () => {
+  const batches = [];
+  for await (const rows of streamStarRows({
+    provider: createProvider(),
+    limitingMagnitude: 99,
+  })) {
+    batches.push(rows);
+  }
+
+  assert.equal(batches.length, 1);
+  assert.equal(batches[0].length, 2);
+});
+
+test('loadStarLabels formats metadata labels for rows', async () => {
+  const [row] = rowsFromStarCells([createCell()]);
+  const labels = await loadStarLabels([row], {
+    metaProvider: {
+      async getMeta(ref) {
+        assert.equal(ref.ordinal, 0);
+        return { proper_name: 'Sol', hip_id: 0 };
+      },
+      dispose() {
+        throw new Error('caller-owned meta providers are not disposed');
+      },
+    },
+  });
+
+  assert.equal(labels.length, 1);
+  assert.equal(labels[0].label, 'Sol');
+  assert.equal(formatStarLabel(null, 'Fallback'), 'Fallback');
+});
+
+function createCell() {
+  return {
+    cellKey: '1:2',
+    cell: { level: 1, mortonCode: '2' },
+    bounds: {
+      centerPc: { x: 0, y: 0, z: 0 },
+      halfSizePc: 1,
+      gridX: 0,
+      gridY: 0,
+      gridZ: 0,
+    },
+    count: 2,
+    coordinates: {
+      name: 'position',
+      frame: 'icrs',
+      units: ['pc', 'pc', 'pc'],
+      components: new Float32Array([
+        1, 2, 2,
+        20, 0, 0,
+      ]),
+    },
+    attributes: {
+      magAbs: new Float32Array([1, 9]),
+      teffLog8: new Uint8Array([255, 0]),
+    },
+    refs: [
+      { datasetId: 'dataset-a', level: 1, mortonCode: '2', ordinal: 0 },
+      { datasetId: 'dataset-a', level: 1, mortonCode: '2', ordinal: 1 },
+    ],
+  };
+}
+
+function createProvider() {
+  return {
+    disposed: false,
+    streamOptions: [],
+    async *streamCells(options) {
+      this.streamOptions.push(options);
+      yield {
+        type: 'stars/cells-upsert',
+        cells: [createCell()],
+      };
+      yield {
+        type: 'stars/current',
+        cellKeys: ['1:2'],
+        starCount: 2,
+      };
+    },
+    dispose() {
+      this.disposed = true;
+    },
+  };
+}

package/src/__tests__/skykit-parallax.test.js

@@ -185,7 +185,7 @@ test('parallax observer moves in the target-relative plane without accumulating
   const viewer = await createSkykitViewer({
     view: {
       observerPc: { x: 0, y: 0, z: 0 },
-      targetPc: { x: 0, y: 0, z: -10 },
+      lookAt: { targetPc: { x: 0, y: 0, z: -10 } },
     },
     plugins: [
       createParallaxObserverPlugin({
@@ -223,7 +223,7 @@ test('parallax observer smoothing approaches the requested offset', async () =>
   const viewer = await createSkykitViewer({
     view: {
       observerPc: { x: 0, y: 0, z: 0 },
-      targetPc: { x: 0, y: 0, z: -10 },
+      lookAt: { targetPc: { x: 0, y: 0, z: -10 } },
     },
     plugins: [
       createParallaxObserverPlugin({
@@ -253,7 +253,7 @@ test('parallax observer static upIcrs controls the target-relative up plane', as
   const viewer = await createSkykitViewer({
     view: {
       observerPc: { x: 0, y: 0, z: 0 },
-      targetPc: { x: 0, y: -10, z: 0 },
+      lookAt: { targetPc: { x: 0, y: -10, z: 0 } },
     },
     plugins: [
       createParallaxObserverPlugin({
@@ -285,7 +285,7 @@ test('parallax observer resolveUpIcrs overrides static up and can change at runt
   const viewer = await createSkykitViewer({
     view: {
       observerPc: { x: 0, y: 0, z: 0 },
-      targetPc: { x: 0, y: -10, z: 0 },
+      lookAt: { targetPc: { x: 0, y: -10, z: 0 } },
     },
     plugins: [
       createParallaxObserverPlugin({

package/src/__tests__/skykit-touch-os.test.js

@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import * as THREE from 'three';
+import { createRuntime } from '@found-in-space/touch-os';
 
 import {
   SKYKIT_ACTIONS,
@@ -8,6 +9,8 @@ import {
 } from '../index.js';
 import {
   createSkykitShipControlsRoot,
+  createSkykitSurfaceApp,
+  createSkykitTabletRoot,
   createTouchOsHudPlugin,
   createTouchOsPanelPlugin,
   dispatchTouchOsActionOutputs,
@@ -72,6 +75,74 @@ test('createSkykitShipControlsRoot builds reusable pseudo-key controls and statu
   );
 });
 
+test('createSkykitTabletRoot builds a tablet app shell from touch apps', () => {
+  const app = createSkykitSurfaceApp({
+    id: 'app.surface',
+    name: 'Surface',
+    node: createSkykitShipControlsRoot({ id: 'surface-child', movePad: false, verticalControls: false }),
+  });
+  const root = createSkykitTabletRoot({
+    id: 'test-tablet',
+    apps: [app],
+    appStates: { 'app.surface': { ready: true } },
+  });
+
+  assert.equal(root.id, 'test-tablet');
+  assert.equal(root.component.kind, 'app-shell');
+  assert.equal(root.props.presentation.kind, 'tablet-home');
+  assert.equal(root.props.appHostMode, 'same-runtime');
+  assert.equal(root.props.homeKey, true);
+  assert.deepEqual(root.props.registry.list().map((manifest) => manifest.id), ['app.surface']);
+
+  const runtime = createRuntime({
+    root,
+    surface: { width: 320, height: 240 },
+  });
+  const snapshot = runtime.render();
+  assert.equal(snapshot.commands.some((command) => command.role === 'tablet-home-button'), true);
+  assert.equal(snapshot.commands.some((command) => command.role === 'tablet-home-bar'), false);
+});
+
+test('createSkykitSurfaceApp wraps display nodes and emits app events', () => {
+  const emitted = [];
+  const app = createSkykitSurfaceApp({
+    id: 'app.hr',
+    name: 'HR',
+    node: () => createSkykitShipControlsRoot({ id: 'hr-child', movePad: false, verticalControls: false }),
+  });
+  const instance = app.createApp({
+    appId: 'app.hr',
+    instanceId: 'app-1',
+    windowId: 'app-1-window',
+    surface: { width: 420, height: 300, pixelDensity: 1, safeArea: { top: 0, right: 0, bottom: 0, left: 0 } },
+    theme: { getTokens() { return {}; } },
+    actions: { emit(event) { emitted.push(event); } },
+    windows: {
+      setTitle() {},
+      requestClose() {},
+      requestResize() {},
+      openApp() {},
+    },
+  });
+
+  const root = instance.render({});
+  assert.equal(app.manifest.id, 'app.hr');
+  assert.deepEqual(app.manifest.capabilities, ['surfaces']);
+  assert.equal(root.component.kind, 'skykit-surface-app-frame');
+  assert.equal(root.props.child.id, 'hr-child');
+
+  instance.handleOutput({ type: 'action', actionId: 'app.fly', componentId: 'fly', payload: { target: 'sun' } });
+  assert.deepEqual(emitted, [{
+    type: 'app-action',
+    appId: 'app.hr',
+    instanceId: 'app-1',
+    windowId: 'app-1-window',
+    name: 'app.fly',
+    payload: { target: 'sun' },
+    componentId: 'fly',
+  }]);
+});
+
 test('touch-os pointer helpers resolve screen input and surface metrics', () => {
   const target = createTarget({ width: 640, height: 360, pixelRatio: 3 });
   const metrics = resolveTouchOsSurfaceMetrics(target, { pixelDensity: 1.5 });