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

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 });

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

@@ -1,4 +1,5 @@
 import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
 import test from 'node:test';
 import * as THREE from 'three';
 
@@ -11,6 +12,7 @@ import {
   createSkykitXrObserverRig,
   createSkykitXrPickRouter,
   createSkykitXrRaySource,
+  createSkykitXrRayVisualPlugin,
   createSkykitXrRig,
   createSkykitXrSessionPlugin,
   createSkykitXrStarPickingPlugin,
@@ -20,6 +22,32 @@ import {
 } from '../xr.js';
 import { createSkykitActionRegistry } from '../index.js';
 
+test('xr free-roam demo uses restored alpha XR regressions defaults', () => {
+  const source = readFileSync(new URL('../../examples/xr-free-roam/xr-free-roam.js', import.meta.url), 'utf8');
+
+  assert.match(source, /createDefaultThreeStarFieldMaterialProfile/);
+  assert.doesNotMatch(source, /createVrThreeStarFieldMaterialProfile/);
+  assert.match(source, /createSkykitXrRayVisualPlugin/);
+  assert.match(source, /createSurfaceShell/);
+  assert.match(source, /createMetaSidecarProviderService/);
+  assert.match(source, /deriveMetaSidecarUrlFromRenderUrl/);
+  assert.match(source, /metaSidecarEntryDisplayFields/);
+  assert.match(source, /datasetId:\s*DATASET_ID_c56103/);
+  assert.match(source, /attributes:\s*\[\s*'objectRef'\s*,\s*'pickMeta'\s*\]/);
+  assert.match(source, /selectSun:\s*'xr-demo:selected\.sun'/);
+  assert.match(source, /primaryActionId:\s*XR_DEMO_ACTIONS\.goSelected/);
+  assert.match(source, /primaryActionLabel:\s*'Fly to'/);
+  assert.match(source, /homeControl:\s*'button'/);
+  assert.match(source, /pointerType:\s*'ray'/);
+  assert.doesNotMatch(source, /dragThreshold/);
+  assert.doesNotMatch(source, /createChoiceGroup/);
+  assert.doesNotMatch(source, /createSlider/);
+  assert.doesNotMatch(source, /createToggle/);
+  assert.doesNotMatch(source, /createStack/);
+  assert.doesNotMatch(source, /waypointPrefix/);
+  assert.doesNotMatch(source, /panelState\.page/);
+});
+
 test('skykit/xr rig builds multi-root hierarchy', () => {
   const camera = new THREE.PerspectiveCamera();
   const rig = createSkykitXrRig({
@@ -102,6 +130,32 @@ test('skykit/xr depth helpers compute and apply render state', () => {
   assert.deepEqual(state, { depthNear: range.depthNear, depthFar: range.depthFar });
 });
 
+test('skykit/xr depth helpers include distant visible star bounds', () => {
+  const range = computeSkykitXrDepthRange({
+    observer: { x: 0, y: 0, z: 0 },
+    visibleBounds: {
+      min: { x: 62, y: 602, z: -13 },
+      max: { x: 64, y: 604, z: -11 },
+    },
+    observerCentricSpheres: [{ radiusNavigationUnits: 16 }],
+    scale: {
+      navigationUnits: 'pc',
+      metersPerNavigationUnit: 1,
+      worldUnitsPerNavigationUnit: 1,
+    },
+    policy: {
+      near: 0.03,
+      minFar: 100,
+      maxFar: 2000000,
+      marginFactor: 1.2,
+    },
+  });
+
+  assert.ok(range.far > 720);
+  assert.ok(range.telemetry.farthestVisibleBoundsDistance > 600);
+  assert.equal(range.telemetry.farthestObserverCentricSphereDistance, 16);
+});
+
 test('skykit/xr session helpers use injected navigator', async () => {
   let ended = false;
   const session = {
@@ -118,7 +172,8 @@ test('skykit/xr session helpers use injected navigator', async () => {
       async isSessionSupported(mode) {
         return mode === 'immersive-vr';
       },
-      async requestSession() {
+      async requestSession(_mode, init) {
+        this.lastInit = init;
         return session;
       },
     },
@@ -126,6 +181,7 @@ test('skykit/xr session helpers use injected navigator', async () => {
   assert.equal(await isSkykitXrModeSupported('immersive-vr', { navigator }), true);
   const handle = await enterSkykitXrSession({ navigator, mode: 'immersive-vr' });
   assert.equal(handle.presenting, true);
+  assert.deepEqual(navigator.xr.lastInit.optionalFeatures, ['local-floor']);
   await exitSkykitXrSession(handle);
   assert.equal(ended, true);
 });
@@ -147,15 +203,20 @@ test('skykit/xr observer rig bridges viewer state to an XR rig without camera re
 
 test('skykit/xr session plugin registers enter/exit actions and syncs snapshot state', async () => {
   let activeSession = null;
+  let requestedReferenceSpaceCount = 0;
   const session = {
     async requestReferenceSpace(type) {
+      requestedReferenceSpaceCount += 1;
       return { type };
     },
     async end() {
       this.ended = true;
+      activeSession = null;
+      renderer.xr.isPresenting = false;
     },
     addEventListener() {},
   };
+  let rendererReferenceSpaceType = null;
   const renderer = {
     xr: {
       enabled: false,
@@ -163,6 +224,9 @@ test('skykit/xr session plugin registers enter/exit actions and syncs snapshot s
       getSession() {
         return activeSession;
       },
+      setReferenceSpaceType(type) {
+        rendererReferenceSpaceType = type;
+      },
       async setSession(nextSession) {
         activeSession = nextSession;
         this.isPresenting = Boolean(nextSession);
@@ -174,7 +238,8 @@ test('skykit/xr session plugin registers enter/exit actions and syncs snapshot s
       async isSessionSupported() {
         return true;
       },
-      async requestSession() {
+      async requestSession(_mode, init) {
+        this.lastInit = init;
         return session;
       },
     },
@@ -195,8 +260,12 @@ test('skykit/xr session plugin registers enter/exit actions and syncs snapshot s
 
   await actions.invoke('skykit:xr.enter');
   assert.equal(renderer.xr.enabled, true);
+  assert.equal(rendererReferenceSpaceType, 'local-floor');
+  assert.deepEqual(navigator.xr.lastInit.optionalFeatures, ['local-floor']);
+  assert.equal(requestedReferenceSpaceCount, 0);
   assert.equal(activeSession, session);
   assert.equal(plugin.getSnapshot().presenting, true);
+  assert.equal(plugin.getSnapshot().enterStage, 'presenting');
 
   const frame = createXrFrame({ renderer });
   part.update(frame);
@@ -240,6 +309,58 @@ test('skykit/xr navigation plugin updates viewer state from controller axes', ()
   assert.deepEqual(actions.getControlValue('skykit:ship.control.move'), { x: 0, y: 0, z: -10 });
 });
 
+test('skykit/xr ray visual shows the controller ray and shortens at blockers', () => {
+  let part = null;
+  let disposedRaySource = false;
+  const plugin = createSkykitXrRayVisualPlugin({
+    raySource: {
+      getRay() {
+        return {
+          id: 'ray',
+          kind: 'target-ray',
+          handedness: 'right',
+          origin: { x: 1, y: 2, z: 3 },
+          direction: { x: 0, y: 0, z: -1 },
+          length: 10,
+        };
+      },
+      getSnapshot() {
+        return { id: 'ray-source' };
+      },
+      dispose() {
+        disposedRaySource = true;
+      },
+    },
+    blockers: [{
+      blockRay() {
+        return { blocked: true, distance: 3, hit: { componentId: 'panel' } };
+      },
+    }],
+  });
+  const context = createPluginContext({
+    addPart(nextPart) {
+      part = nextPart;
+    },
+  });
+  plugin.setup(context);
+  part.attach(context);
+
+  part.update(createXrFrame());
+
+  assert.equal(part.object3d.visible, true);
+  assert.equal(plugin.getSnapshot().blocked, true);
+  assert.equal(plugin.getSnapshot().lastLength, 3);
+  assert.deepEqual(
+    Array.from(part.object3d.children[0].geometry.getAttribute('position').array),
+    [1, 2, 3, 1, 2, 0],
+  );
+
+  part.update({ ...createXrFrame(), xr: { presenting: false } });
+  assert.equal(part.object3d.visible, false);
+  part.dispose();
+  assert.equal(disposedRaySource, true);
+});
+
 test('skykit/xr star picking fires only on trigger edge and registers attribute-only demand', () => {
   const actions = createSkykitActionRegistry();
   let part = null;

package/src/__tests__/skykit.test.js

@@ -77,6 +77,57 @@ function createRenderer() {
   };
 }
 
+function createTextureRenderer() {
+  const renderer = createRenderer();
+  return {
+    ...renderer,
+    xr: { enabled: true },
+    currentTarget: null,
+    viewport: new THREE.Vector4(0, 0, 1, 1),
+    scissor: new THREE.Vector4(0, 0, 1, 1),
+    scissorTest: false,
+    getRenderTarget() {
+      return this.currentTarget;
+    },
+    setRenderTarget(target) {
+      this.currentTarget = target;
+    },
+    getViewport(target) {
+      return target.copy(this.viewport);
+    },
+    setViewport(value) {
+      if (value?.isVector4) this.viewport.copy(value);
+    },
+    getScissor(target) {
+      return target.copy(this.scissor);
+    },
+    setScissor(value) {
+      if (value?.isVector4) this.scissor.copy(value);
+    },
+    getScissorTest() {
+      return this.scissorTest;
+    },
+    setScissorTest(value) {
+      this.scissorTest = Boolean(value);
+    },
+  };
+}
+
+function createEmbeddedSurfaceSpy() {
+  const publishCalls = [];
+  const unpublishCalls = [];
+  return {
+    publishCalls,
+    unpublishCalls,
+    publish(sourceId, update) {
+      publishCalls.push({ sourceId, update });
+    },
+    unpublish(sourceId) {
+      unpublishCalls.push(sourceId);
+    },
+  };
+}
+
 async function flushMicrotasks(count = 10) {
   for (let index = 0; index < count; index += 1) {
     await Promise.resolve();
@@ -242,6 +293,51 @@ test('viewer exposes action registry, emits action events, and resets to initial
   await viewer.dispose();
 });
 
+test('viewer derives camera orientation from lookAt targets, sky coordinates, and stars', async () => {
+  const targetViewer = await createSkykitViewer({
+    renderer: createRenderer(),
+    view: {
+      observerPc: { x: 0, y: 0, z: 0 },
+      lookAt: { targetPc: { x: 10, y: 0, z: 0 }, positionAngleDeg: 0 },
+    },
+  });
+  let view = targetViewer.getViewState();
+  assert.deepEqual(view.targetPc, { x: 10, y: 0, z: 0 });
+  assertVectorApprox(localVectorFromView(view, { x: 0, y: 0, z: -1 }), { x: 1, y: 0, z: 0 });
+  assertVectorApprox(localVectorFromView(view, { x: 0, y: 1, z: 0 }), { x: 0, y: 0, z: 1 });
+  await targetViewer.dispose();
+
+  const skyViewer = await createSkykitViewer({
+    renderer: createRenderer(),
+    view: {
+      lookAt: { raDeg: 0, decDeg: 0, positionAngleDeg: 90 },
+    },
+  });
+  view = skyViewer.getViewState();
+  assert.equal(view.targetPc, null);
+  assertVectorApprox(localVectorFromView(view, { x: 0, y: 0, z: -1 }), { x: 1, y: 0, z: 0 });
+  assertVectorApprox(localVectorFromView(view, { x: 0, y: 1, z: 0 }), { x: 0, y: 1, z: 0 });
+  await skyViewer.dispose();
+
+  const starViewer = await createSkykitViewer({
+    renderer: createRenderer(),
+    view: { lookAt: { star: 'hyades' } },
+    resolveLookAtStar: async (star) => star === 'hyades'
+      ? { targetPc: { x: 4, y: 5, z: 6 } }
+      : null,
+  });
+  view = starViewer.getViewState();
+  assert.equal(view.lookAt?.star, 'hyades');
+  assert.deepEqual(view.targetPc, { x: 4, y: 5, z: 6 });
+  assert.ok(view.orientationIcrs);
+
+  starViewer.requestViewState({ lookAt: { star: 'orion' } }, 'test-star-look');
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  starViewer.update(0);
+  assert.deepEqual(starViewer.getViewState().targetPc, null);
+  await starViewer.dispose();
+});
+
 test('requestViewState batches patches and observer-centric root follows translation without rotation', async () => {
   const viewer = await createSkykitViewer({
     renderer: createRenderer(),
@@ -682,6 +778,41 @@ test('HR diagram mode changes refresh shared demand and update the renderer view
   await viewer.dispose();
 });
 
+test('HR diagram touch-os surfaces can be resolved lazily from panel runtimes', async () => {
+  const session = createFakeSession();
+  const provider = {
+    id: 'provider',
+    createSession() {
+      return session;
+    },
+  };
+  const source = createSkykitStarSourcePlugin({ provider });
+  const surfaces = createEmbeddedSurfaceSpy();
+  let activeSurfaces = null;
+  const hr = createSkykitHrDiagramPlugin({
+    id: 'hr',
+    source,
+    touchOs: {
+      sourceId: 'hr:surface',
+      surfaces: () => activeSurfaces,
+    },
+  });
+  const viewer = await createSkykitViewer({
+    renderer: createTextureRenderer(),
+    plugins: [source, hr],
+  });
+
+  activeSurfaces = surfaces;
+  viewer.frame(0.016);
+
+  assert.equal(surfaces.publishCalls.length, 1);
+  assert.equal(surfaces.publishCalls[0].sourceId, 'hr:surface');
+  assert.equal(surfaces.publishCalls[0].update.available, true);
+
+  await viewer.dispose();
+  assert.deepEqual(surfaces.unpublishCalls, ['hr:surface']);
+});
+
 test('HR diagram demand strategy override can be supplied and restored at runtime', async () => {
   const sessions = [];
   const provider = {
@@ -1698,7 +1829,7 @@ test('journey plugin can route to non-orbit scenes before applying the arrival t
         },
       },
       local: {
-        view: { targetPc: { x: 1, y: 0, z: 0 } },
+        view: { lookAt: { targetPc: { x: 1, y: 0, z: 0 } } },
         navigation: {
           transitionTo: {
             observerPc: { x: 0, y: 0, z: 0 },
@@ -2323,6 +2454,12 @@ function localVectorFromView(view, vector) {
   return { x: result.x, y: result.y, z: result.z };
 }
 
+function assertVectorApprox(actual, expected, epsilon = 1e-9) {
+  assert.ok(Math.abs(actual.x - expected.x) < epsilon, `x ${actual.x} !== ${expected.x}`);
+  assert.ok(Math.abs(actual.y - expected.y) < epsilon, `y ${actual.y} !== ${expected.y}`);
+  assert.ok(Math.abs(actual.z - expected.z) < epsilon, `z ${actual.z} !== ${expected.z}`);
+}
+
 function createPointerTarget() {
   const target = createEventTarget();
   target.clientWidth = 800;