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

package/README.md

@@ -69,19 +69,28 @@ Optional attributes keep small tweaks HTML-only:
   data-skykit-magnitude="7"
   data-skykit-speed="4"
   data-skykit-exposure="2600"
-  data-skykit-look-at="ra=4.496h, dec=16.948"
+  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
-`ra=4.496h, dec=16.948`, decimal degrees such as `67.447,16.948`, or a
-parsec-space `x,y,z` target for exact generated coordinates. `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
+`05h 36m 12.81s, −01° 12′ 06.9″`, decimal degrees such as
+`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
 `data-skykit-persistent-cache="off"` to keep caching session-only.
 
 The host dispatches `skykit-browser-ready` with `{ browser, viewer }` in
@@ -120,15 +129,17 @@ For small scripted interactions, use the browser handle:
 <script type="module">
   import {
     SKYKIT_ACTIONS,
+    createRaDecLookAt,
     createSkykitNavigationPlugin,
   } from 'https://esm.sh/@found-in-space/skykit';
 
   const browser = await Skykit.whenReady();
   await browser.install(createSkykitNavigationPlugin());
+  const alnilam = createRaDecLookAt('05h 36m 12.81s', '−01° 12′ 06.9″');
 
   document.querySelector('#orion').addEventListener('click', () => {
     browser.viewer.actions.invoke(SKYKIT_ACTIONS.navigation.transitionTo, {
-      view: { lookAt: 'ra=5.919h, dec=7.407' },
+      view: { lookAt: alnilam },
       movement: { durationSecs: 3 },
     });
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@found-in-space/skykit",
-  "version": "0.2.0-alpha.20260529",
+  "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.20260528",
+    "@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,
@@ -17,6 +20,7 @@ import {
   createDesktopSkykitObserverRig,
   createObject3dLayer,
   createObject3dPlugin,
+  createRaDecLookAt,
   createMouseLookPlugin,
   createSkyGrabPlugin,
   createSkykitDefaultKeyboardNavigationBindings,
@@ -34,6 +38,7 @@ import {
   createStreamingStarLayer,
   createStreamingStarsPlugin,
   installSkykitDebugGlobal,
+  parseSpatialLookAtText,
 } from '../index.js';
 
 function createHost() {
@@ -313,6 +318,50 @@ test('viewer derives camera orientation from lookAt targets, sky coordinates, an
   assertVectorApprox(localVectorFromView(view, { x: 0, y: 1, z: 0 }), { x: 0, y: 1, z: 0 });
   await skyViewer.dispose();
 
+  const alnilamViewer = await createSkykitViewer({
+    renderer: createRenderer(),
+    view: {
+      lookAt: createRaDecLookAt('05h 36m 12.81s', '−01° 12′ 06.9″'),
+    },
+  });
+  view = alnilamViewer.getViewState();
+  assertVectorApprox(
+    localVectorFromView(view, { x: 0, y: 0, z: -1 }),
+    directionFromRaDec(84.053375, -1.2019166666666667),
+  );
+  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' } },
@@ -1527,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, {
@@ -1539,6 +1588,17 @@ test('navigation transition action restores pose with independent lane durations
   assert.deepEqual(viewer.getViewState().observerPc, { x: 0, y: 0, z: 0 });
   assert.deepEqual(viewer.getViewState().orientationIcrs, orientationAfterExplicitTransition);
 
+  await viewer.actions.invoke(SKYKIT_ACTIONS.navigation.transitionTo, {
+    lookAt: '05:36:12.81, −01:12:06.9',
+    orientation: { durationSecs: 1 },
+  });
+  viewer.update(1);
+  viewer.update(0);
+  assertVectorApprox(
+    localVectorFromView(viewer.getViewState(), { x: 0, y: 0, z: -1 }),
+    directionFromRaDec(84.053375, -1.2019166666666667),
+  );
+
   await viewer.dispose();
 });
 
@@ -1959,6 +2019,34 @@ 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;
+  const cosDec = Math.cos(dec);
+  return {
+    x: Math.cos(ra) * cosDec,
+    y: Math.sin(ra) * cosDec,
+    z: Math.sin(dec),
+  };
+}
+
 function createPointerTarget() {
   const target = createEventTarget();
   target.clientWidth = 800;

package/src/browser.js

@@ -6,6 +6,12 @@ import {
 } from '@found-in-space/star-octree-provider';
 import { createObserverShellStrategy } from '@found-in-space/star-trees';
 import { createThreeStarField } from '@found-in-space/three-star-field';
+import {
+  createRaDecLookAt,
+  parseDeclination,
+  parseRightAscension,
+  parseSpatialLookAtText,
+} from '@found-in-space/spatial';
 
 import { createSkykitAnimationLoop } from './animation-loop.js';
 import { SKYKIT_ACTIONS, SKYKIT_CONTROLS } from './actions.js';
@@ -181,8 +187,12 @@ export async function createSkykitBrowser(input = {}) {
       skykit: {
         SKYKIT_ACTIONS,
         SKYKIT_CONTROLS,
+        createRaDecLookAt,
         createObject3dPlugin,
         createSkykitNavigationPlugin,
+        parseDeclination,
+        parseRightAscension,
+        parseSpatialLookAtText,
       },
     };
   }

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

package/src/hr-diagram.js

@@ -393,7 +393,9 @@ function cloneViewState(view) {
     ...view,
     observerPc: clonePoint(view.observerPc),
     renderObserverPosition: clonePoint(view.renderObserverPosition),
-    ...(view.lookAt ? { lookAt: { ...view.lookAt } } : {}),
+    ...(view.lookAt
+      ? { lookAt: typeof view.lookAt === 'object' ? { ...view.lookAt } : view.lookAt }
+      : {}),
     ...(view.targetPc ? { targetPc: clonePoint(view.targetPc) } : {}),
     ...(view.motion
       ? {

package/src/index.d.ts

@@ -56,7 +56,9 @@ export interface QuaternionLike {
   w: number;
 }
 
-export interface SkykitLookAtInput {
+export type SkykitLookAtInput = string | SkykitLookAtSpecInput;
+
+export interface SkykitLookAtSpecInput {
   targetPc?: Vector3Like | [number, number, number];
   raDeg?: number;
   raHours?: number;
@@ -68,6 +70,13 @@ export interface SkykitLookAtInput {
   [key: string]: unknown;
 }
 
+export {
+  createRaDecLookAt,
+  parseDeclination,
+  parseRightAscension,
+  parseSpatialLookAtText,
+} from '@found-in-space/spatial';
+
 export interface SkykitObserverMotion {
   velocityPcPerSec: Vector3Like;
   speedPcPerSec: number;

package/src/index.js

@@ -12,6 +12,12 @@ export {
 } from './actions.js';
 export { createSkykitAnimationLoop } from './animation-loop.js';
 export { createSkykitDebugBridge, installSkykitDebugGlobal } from './debug.js';
+export {
+  createRaDecLookAt,
+  parseDeclination,
+  parseRightAscension,
+  parseSpatialLookAtText,
+} from '@found-in-space/spatial';
 export { createSkykitHrDiagramPlugin } from './hr-diagram.js';
 export { createObject3dLayer } from './layers.js';
 export { createDesktopSkykitObserverRig } from './observer-rig.js';

package/src/utils.js

@@ -211,6 +211,7 @@ function resolveViewLook(input, observerPc, options = {}) {
  * @returns {import('./index.d.ts').SkykitLookAtInput | null}
  */
 function cloneLookAt(lookAt) {
+  if (typeof lookAt === 'string') return lookAt;
   if (!lookAt || typeof lookAt !== 'object') return null;
   const source = /** @type {Record<string, unknown>} */ (lookAt);
   return {