@found-in-space/skykit 0.2.0-alpha.20260530 → 0.2.0-alpha.20260531

package/README.md

@@ -69,17 +69,25 @@ Optional attributes keep small tweaks HTML-only:
   data-skykit-magnitude="7"
   data-skykit-speed="4"
   data-skykit-exposure="2600"
-  data-skykit-look-at="05h 36m 12.81s, −01° 12′ 06.9″"
+  data-skykit-observer="06h 45m 08.9s, -16d 42m 58s, 2.64pc"
+  data-skykit-look-at="05h 35m 17.3s, -05d 23m 28s, 414pc"
+  data-skykit-coordinate-origin="solar"
   data-skykit-mouse-mode="strafe"
   data-skykit-persistent-cache="off"
   style="width: 100%; height: 520px; background: #02040b"
 ></div>
 ```
 
+`data-skykit-observer` accepts fixed parsec-space `x,y,z` coordinates or
+RA/Dec/distance text such as `06h 45m 08.9s, -16d 42m 58s, 2.64pc`.
 `data-skykit-look-at` accepts RA/Dec text such as
 `05h 36m 12.81s, −01° 12′ 06.9″`, decimal degrees such as
-`84.053393,-1.201926`, or a parsec-space `x,y,z` target for exact generated
-coordinates. `data-skykit-mouse-mode` defaults to `grab`; use `look` or
+`84.053393,-1.201926`, RA/Dec/distance text for a fixed heliocentric target,
+or a parsec-space `x,y,z` target for exact generated coordinates.
+RA/Dec/distance resolves from the solar origin; pure RA/Dec remains a
+directional look. `data-skykit-coordinate-origin="solar"` is accepted as
+clarifying markup, while observer-relative shorthand is not part of this alpha
+embed yet. `data-skykit-mouse-mode` defaults to `grab`; use `look` or
 `strafe` for the first-person mouse-look direction, or `none` to disable mouse
 drag controls. Persistent browser Cache API storage is enabled by default for
 octree ranges; set

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@found-in-space/skykit",
-  "version": "0.2.0-alpha.20260530",
+  "version": "0.2.0-alpha.20260531",
   "description": "Slim composition and teaching layer for Found in Space packages",
   "license": "MIT",
   "type": "module",
@@ -72,7 +72,7 @@
     "@found-in-space/anchored-image": "0.2.0-alpha.0",
     "@found-in-space/hr-diagram": "0.2.0-alpha.1",
     "@found-in-space/meta-sidecar-provider": "0.2.0-alpha.1",
-    "@found-in-space/spatial": "0.2.0-alpha.20260529",
+    "@found-in-space/spatial": "0.2.0-alpha.20260530",
     "@found-in-space/star-octree-provider": "0.2.0-alpha.1",
     "@found-in-space/star-trees": "0.2.0-alpha.0",
     "@found-in-space/three-star-field": "0.2.0-alpha.0"

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

@@ -137,6 +137,35 @@ test('createSkykitBrowser accepts startup lookAt and mouse look mode', async ()
   });
 });
 
+test('createSkykitBrowser starts from observer and solar RA/Dec distance lookAt', async () => {
+  await withFakeWindow(async () => {
+    const browser = await createSkykitBrowser({
+      host: createHost(),
+      status: false,
+      renderer: createRenderer(),
+      provider: createProvider(),
+      starField: createStarField(),
+      autoResize: false,
+      autoDispose: false,
+      autoStart: false,
+      lookAt: { raDeg: 90, decDeg: 0, distancePc: 10 },
+      view: {
+        observerPc: { x: 1, y: 0, z: 0 },
+      },
+    });
+
+    const view = browser.viewer.getViewState();
+    assert.deepEqual(view.observerPc, { x: 1, y: 0, z: 0 });
+    assertVectorApprox(view.targetPc, { x: 0, y: 10, z: 0 });
+    assertVectorApprox(
+      localVectorFromView(view, { x: 0, y: 0, z: -1 }),
+      normalizeVector({ x: -1, y: 10, z: 0 }),
+    );
+
+    await browser.dispose();
+  });
+});
+
 test('createSkykitBrowser can disable mouse drag controls', async () => {
   await withFakeWindow(async () => {
     const browser = await createSkykitBrowser({
@@ -532,3 +561,26 @@ function createStarField() {
     },
   };
 }
+
+function localVectorFromView(view, vector) {
+  const q = view.orientationIcrs ?? { x: 0, y: 0, z: 0, w: 1 };
+  const result = new THREE.Vector3(vector.x, vector.y, vector.z).applyQuaternion(
+    new THREE.Quaternion(q.x, q.y, q.z, q.w),
+  );
+  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 normalizeVector(vector) {
+  const length = Math.hypot(vector.x, vector.y, vector.z);
+  return {
+    x: vector.x / length,
+    y: vector.y / length,
+    z: vector.z / length,
+  };
+}

package/src/__tests__/skykit.test.js

@@ -7,6 +7,9 @@ import {
   encodeMorton3D,
 } from '@found-in-space/star-trees';
 
+import {
+  resolveSpatialTarget,
+} from '@found-in-space/spatial';
 import {
   SKYKIT_ACTION_NAMESPACE,
   SKYKIT_ACTIONS,
@@ -35,6 +38,7 @@ import {
   createStreamingStarLayer,
   createStreamingStarsPlugin,
   installSkykitDebugGlobal,
+  parseSpatialLookAtText,
 } from '../index.js';
 
 function createHost() {
@@ -327,6 +331,37 @@ test('viewer derives camera orientation from lookAt targets, sky coordinates, an
   );
   await alnilamViewer.dispose();
 
+  const siriusSpec = parseSpatialLookAtText('06h 45m 08.9s, -16d 42m 58s, 2.64pc');
+  const orionSpec = parseSpatialLookAtText('05h 35m 17.3s, -05d 23m 28s, 414pc');
+  const siriusPc = resolveSpatialTarget(siriusSpec);
+  const orionPc = resolveSpatialTarget(orionSpec);
+  assert.ok(siriusPc && orionPc && orionSpec);
+  const solarTargetViewer = await createSkykitViewer({
+    renderer: createRenderer(),
+    view: {
+      observerPc: siriusPc,
+      lookAt: orionSpec,
+    },
+  });
+  view = solarTargetViewer.getViewState();
+  assertVectorApprox(view.observerPc, siriusPc);
+  assertVectorApprox(view.targetPc, orionPc);
+  assertVectorApprox(
+    localVectorFromView(view, { x: 0, y: 0, z: -1 }),
+    normalizeVector(subtractVectors(orionPc, siriusPc)),
+  );
+
+  const movedObserver = { x: -8, y: 3, z: 11 };
+  solarTargetViewer.requestViewState({ observerPc: movedObserver, lookAt: orionSpec }, 'test-solar-radec');
+  solarTargetViewer.update(0);
+  view = solarTargetViewer.getViewState();
+  assertVectorApprox(view.targetPc, orionPc);
+  assertVectorApprox(
+    localVectorFromView(view, { x: 0, y: 0, z: -1 }),
+    normalizeVector(subtractVectors(orionPc, movedObserver)),
+  );
+  await solarTargetViewer.dispose();
+
   const starViewer = await createSkykitViewer({
     renderer: createRenderer(),
     view: { lookAt: { star: 'hyades' } },
@@ -1541,7 +1576,7 @@ test('navigation transition action restores pose with independent lane durations
   });
   viewer.update(1);
   viewer.update(0);
-  assert.deepEqual(viewer.getViewState().observerPc, { x: 20, y: 0, z: 0 });
+  assert.deepEqual(viewer.getViewState().observerPc, { x: 10, y: 0, z: 0 });
   assert.deepEqual(viewer.getViewState().orientationIcrs, orientationAfterExplicitTransition);
 
   await viewer.actions.invoke(SKYKIT_ACTIONS.navigation.transitionTo, {
@@ -1984,6 +2019,23 @@ function assertVectorApprox(actual, expected, epsilon = 1e-9) {
   assert.ok(Math.abs(actual.z - expected.z) < epsilon, `z ${actual.z} !== ${expected.z}`);
 }
 
+function subtractVectors(a, b) {
+  return {
+    x: a.x - b.x,
+    y: a.y - b.y,
+    z: a.z - b.z,
+  };
+}
+
+function normalizeVector(vector) {
+  const length = Math.hypot(vector.x, vector.y, vector.z);
+  return {
+    x: vector.x / length,
+    y: vector.y / length,
+    z: vector.z / length,
+  };
+}
+
 function directionFromRaDec(raDeg, decDeg) {
   const ra = raDeg * Math.PI / 180;
   const dec = decDeg * Math.PI / 180;

package/src/embed.js

@@ -1,4 +1,7 @@
-import { parseSpatialLookAtText } from '@found-in-space/spatial';
+import {
+  parseSpatialLookAtText,
+  resolveSpatialTarget,
+} from '@found-in-space/spatial';
 
 import {
   installSkykitBrowserGlobal,
@@ -59,7 +62,14 @@ async function installRequestedCapabilities(host, browser) {
 /** @param {Element} host */
 function readOptions(host) {
   const data = isHtmlElement(host) ? host.dataset : {};
+  const observerPc = data.skykitObserver ? parseSpatialTargetText(data.skykitObserver) : null;
   const lookAt = data.skykitLookAt ? parseSpatialLookAtText(data.skykitLookAt) : null;
+  const view = observerPc || lookAt
+    ? {
+      ...(observerPc ? { observerPc } : {}),
+      ...(lookAt ? { lookAt } : {}),
+    }
+    : null;
   return {
     host,
     ...(data.skykitStatus ? { status: data.skykitStatus } : {}),
@@ -68,10 +78,19 @@ function readOptions(host) {
     ...(data.skykitExposure ? { exposure: Number(data.skykitExposure) } : {}),
     ...(data.skykitMouseMode ? { mouseMode: data.skykitMouseMode } : {}),
     ...(data.skykitPersistentCache ? { persistentCache: data.skykitPersistentCache } : {}),
-    ...(lookAt ? { view: { lookAt } } : {}),
+    ...(view ? { view } : {}),
   };
 }
 
+/** @param {string} text */
+function parseSpatialTargetText(text) {
+  const targetSpec = parseSpatialLookAtText(text);
+  const target = resolveSpatialTarget(targetSpec);
+  return target && typeof /** @type {Promise<unknown>} */ (target).then !== 'function'
+    ? target
+    : null;
+}
+
 /**
  * @param {Element} host
  * @param {import('./browser.d.ts').SkykitBrowser} browser