@found-in-space/skykit 0.2.0-dev.20260527.1 → 0.2.0

package/README.md

@@ -28,11 +28,11 @@ The beginner website entries are use-case bounded:
 | --- | --- | --- |
 | Viewer | "Put stars on my page and let me customize the scene." | `embed.js`, `viewer.js` |
 | Data | "Give me star data so I can render, list, map, or game it myself." | `data.js` |
-| Story | "Let me tell a curated story through space." | `story.js` |
 
 `embed.js` is the no-code viewer entry. It is not a separate use-case.
 `viewer.js` is the JavaScript-customizable viewer entry. `data.js` is renderer
-independent. `story.js` is authored chapters plus a viewer.
+independent. Authored chapters stay in website or lesson code and call SkyKit
+navigation actions directly.
 
 ## Paste into a static page or CMS
 
@@ -69,17 +69,29 @@ 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.
+`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
 `event.detail` after startup, and `skykit-browser-error` if startup fails. The
@@ -115,12 +127,20 @@ For small scripted interactions, use the browser handle:
 
 ```html
 <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.journey.transitionTo({
-      lookAt: 'ra=5.919h, dec=7.407',
-      durationSecs: 3,
+    browser.viewer.actions.invoke(SKYKIT_ACTIONS.navigation.transitionTo, {
+      view: { lookAt: alnilam },
+      movement: { durationSecs: 3 },
     });
   });
 </script>
@@ -190,25 +210,11 @@ const stars = await loadStarRows({
 });
 ```
 
-## Create a Guided Story
-
-Use `story.js` when the page is an authored article or tour:
-
-```html
-<div data-skykit-story style="height:600px;background:#02040b">
-  <section data-skykit-chapter data-title="The Sun" data-target-pc="0,0,0">
-    We start at the Sun.
-  </section>
-  <section data-skykit-chapter data-title="The Hyades" data-target-pc="17.574,42.316,13.963">
-    Now jump to the Hyades cluster.
-  </section>
-</div>
+## Author Chapters
 
-<script
-  type="module"
-  src="https://esm.sh/@found-in-space/skykit@0.2.0-alpha.2/story?bundle&deps=three@0.170.0"
-></script>
-```
+Keep named chapters in the website or lesson script. Each chapter can call
+navigation actions such as `skykit:navigation.transitionTo` and
+`skykit:navigation.orbit` from its own `goTo(id)` dispatcher.
 
 Use the lower-level factories when a lesson is teaching composition or replacing
 a part of the stack:
@@ -323,7 +329,7 @@ names, not renderer or loader factory names:
 SKYKIT_ACTIONS.ship.moveForward; // "skykit:ship.move.forward"
 SKYKIT_CONTROLS.observer.parallaxOffset; // "skykit:observer.control.parallaxOffset"
 SKYKIT_ACTIONS.viewer.reset; // "skykit:viewer.reset"
-SKYKIT_ACTIONS.journey.goToChapter; // "skykit:journey.goToChapter"
+SKYKIT_ACTIONS.navigation.transitionTo; // "skykit:navigation.transitionTo"
 ```
 
 Plugins can add their own namespaces:
@@ -336,13 +342,13 @@ const firePlugin = (ctx) => {
 };
 ```
 
-DOM buttons, touch surfaces, keyboard bindings, XR controls, journeys, and debug
-tools can all call the same action:
+DOM buttons, touch surfaces, keyboard bindings, XR controls, app-owned chapters,
+and debug tools can all call the same action:
 
 ```js
 button.addEventListener('click', () => {
-  viewer.actions.invoke(SKYKIT_ACTIONS.journey.goToChapter, {
-    chapterId: 'hyades-arrival',
+  viewer.actions.invoke('website:chapter.goTo', {
+    id: 'hyades-arrival',
   });
 });
 ```
@@ -397,8 +403,7 @@ Skykit.registerBrowserAddon({
 ```
 
 See `docs/skykit-browser-plugins.md` for the browser add-on spec,
-`Skykit.whenReady()`, first-party constellation support, and the
-`browser.journey` API.
+`Skykit.whenReady()`, and first-party constellation support.
 
 Browser lessons:
 

package/examples/xr-free-roam/xr-free-roam.js

@@ -24,6 +24,7 @@ import {
 import {
   applySkykitXrDepthRange,
   computeSkykitXrDepthRange,
+  createSkykitXrBodyPlugin,
   createSkykitXrControlBindings,
   createSkykitXrNavigationPlugin,
   createSkykitXrObserverRig,
@@ -169,6 +170,7 @@ async function main() {
   let cachedPanelRevision = -1;
   let cachedPanelRoot = null;
   let latestPanelFrame = null;
+  let leftHandPanelTracked = false;
   let activeXrHandle = null;
   let artController = null;
   let preflightController = null;
@@ -207,7 +209,7 @@ async function main() {
   touchPanel = createTouchOsPanelPlugin({
     id: 'xr-free-roam-touch-panel',
     priority: 20,
-    driver: 'pose-anchored',
+    driver: 'scene',
     root: createPanelRoot,
     surfaceMetrics: XR_PANEL_SURFACE,
     runtimeOptions: {
@@ -215,18 +217,23 @@ async function main() {
       longPressDelay: 360,
     },
     pointerSources: [touchPointerSource],
-    anchorPose(frame) {
-      latestPanelFrame = frame;
-      return resolveLeftHandPanelPose(frame, xrRig.xrOrigin);
+    parent() {
+      return xrRig.leftHandRoot;
     },
     driverOptions: {
       panelWidth: 0.32,
       panelHeight: 0.44,
-      offset: { x: 0.04, y: 0.02, z: -0.08 },
-      tiltRadians: -0.22,
       transparent: true,
       depthTest: false,
       renderOrder: 50,
+      updatePlacement(mesh) {
+        if (!leftHandPanelTracked) return false;
+        applyLocalTabletPlacement(mesh, {
+          offset: { x: 0.04, y: 0.02, z: -0.08 },
+          tiltRadians: -0.22,
+        });
+        return true;
+      },
     },
   });
 
@@ -271,6 +278,12 @@ async function main() {
       createStreamingStarsPlugin({ id: 'xr-stars', source, renderer: starField }),
       hrDiagram,
       ...(artPlugin ? [artPlugin] : []),
+      createSkykitXrBodyPlugin({
+        rig: xrRig,
+        onBody(body) {
+          leftHandPanelTracked = Boolean(body.leftHand?.grip ?? body.leftHand?.targetRay);
+        },
+      }),
       createXrFreeRoamFrameSyncPlugin({
         update() {
           selectedTarget.update(camera);
@@ -389,7 +402,8 @@ async function main() {
     });
   }
 
-  function createPanelRoot() {
+  function createPanelRoot(rootContext) {
+    latestPanelFrame = rootContext?.frame ?? latestPanelFrame;
     if (cachedPanelRoot && cachedPanelRevision === panelRevision) return cachedPanelRoot;
     cachedPanelRevision = panelRevision;
     cachedPanelRoot = createSkykitTabletRoot({
@@ -1023,57 +1037,17 @@ function createWorldXrRaySource(source, transformRoot) {
   };
 }
 
-function resolveLeftHandPanelPose(frame, transformRoot) {
-  const gripPose = resolveInputPose(frame, 'left', 'gripSpace');
-  if (!gripPose) return undefined;
-  return transformPoseByObject(gripPose, transformRoot);
-}
-
-function resolveInputPose(frame, handedness, spaceKey) {
-  const xr = frame.xr;
-  const xrFrame = xr?.frame;
-  const referenceSpace = xr?.referenceSpace;
-  const inputSources = xr?.session && typeof xr.session === 'object'
-    ? xr.session.inputSources ?? []
-    : [];
-  if (!xrFrame || !referenceSpace || typeof xrFrame.getPose !== 'function') return null;
-  for (const inputSource of inputSources) {
-    if (inputSource?.handedness !== handedness || !inputSource[spaceKey]) continue;
-    const pose = xrFrame.getPose(inputSource[spaceKey], referenceSpace);
-    const transform = pose?.transform;
-    if (!transform) continue;
-    return {
-      position: {
-        x: Number(transform.position?.x ?? 0),
-        y: Number(transform.position?.y ?? 0),
-        z: Number(transform.position?.z ?? 0),
-      },
-      orientation: {
-        x: Number(transform.orientation?.x ?? 0),
-        y: Number(transform.orientation?.y ?? 0),
-        z: Number(transform.orientation?.z ?? 0),
-        w: Number(transform.orientation?.w ?? 1),
-      },
-    };
+function applyLocalTabletPlacement(mesh, options = {}) {
+  const offset = options.offset ?? {};
+  mesh.position.set(0, 0, 0);
+  mesh.quaternion.identity();
+  mesh.scale.set(1, 1, 1);
+  if (Number.isFinite(options.tiltRadians)) {
+    mesh.rotateX(options.tiltRadians);
   }
-  return null;
-}
-
-function transformPoseByObject(pose, object) {
-  object.updateMatrixWorld(true);
-  const position = new THREE.Vector3(pose.position.x, pose.position.y, pose.position.z)
-    .applyMatrix4(object.matrixWorld);
-  const objectQuaternion = object.getWorldQuaternion(new THREE.Quaternion());
-  const orientation = new THREE.Quaternion(
-    pose.orientation.x,
-    pose.orientation.y,
-    pose.orientation.z,
-    pose.orientation.w,
-  ).premultiply(objectQuaternion).normalize();
-  return {
-    position: { x: position.x, y: position.y, z: position.z },
-    orientation: { x: orientation.x, y: orientation.y, z: orientation.z, w: orientation.w },
-  };
+  mesh.translateX(offset.x ?? 0);
+  mesh.translateY(offset.y ?? 0);
+  mesh.translateZ(offset.z ?? 0);
 }
 
 function createSelectedStarTarget() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@found-in-space/skykit",
-  "version": "0.2.0-dev.20260527.1",
+  "version": "0.2.0",
   "description": "Slim composition and teaching layer for Found in Space packages",
   "license": "MIT",
   "type": "module",
@@ -31,10 +31,6 @@
       "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"
@@ -47,10 +43,6 @@
       "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"
@@ -70,28 +62,26 @@
     "README.md"
   ],
   "sideEffects": [
-    "./src/embed.js",
-    "./src/story.js"
+    "./src/embed.js"
   ],
   "scripts": {
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "node --test"
   },
   "dependencies": {
-    "@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-dev.20260527.1",
-    "@found-in-space/meta-sidecar-provider": "0.2.0-alpha.0",
-    "@found-in-space/spatial": "0.2.0-dev.20260527.1",
-    "@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"
+    "@found-in-space/anchored-image": "0.2.0",
+    "@found-in-space/hr-diagram": "0.2.0",
+    "@found-in-space/meta-sidecar-provider": "0.2.0",
+    "@found-in-space/spatial": "0.2.0",
+    "@found-in-space/star-octree-provider": "0.2.0",
+    "@found-in-space/star-trees": "0.2.0",
+    "@found-in-space/three-star-field": "0.2.0"
   },
   "devDependencies": {
-    "@found-in-space/touch-os": "0.2.0-dev.3"
+    "@found-in-space/touch-os": "0.2.0"
   },
   "peerDependencies": {
-    "@found-in-space/touch-os": ">=0.2.0-dev.3 <1",
+    "@found-in-space/touch-os": ">=0.2.0 <1",
     "three": "^0.170.0"
   },
   "peerDependenciesMeta": {

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({
@@ -160,6 +189,56 @@ test('createSkykitBrowser can disable mouse drag controls', async () => {
   });
 });
 
+test('createSkykitBrowser enables persistent provider cache by default and can opt out', async () => {
+  await withFakeWindow(async () => {
+    await withFakeCaches(async () => {
+      const cached = await createSkykitBrowser({
+        host: createHost(),
+        status: false,
+        renderer: createRenderer(),
+        starField: createStarField(),
+        autoResize: false,
+        autoDispose: false,
+        autoStart: false,
+      });
+      assert.equal(cached.provider.describe().capabilities.persistentCache, true);
+      await cached.dispose();
+
+      const uncached = await createSkykitBrowser({
+        host: createHost(),
+        status: false,
+        renderer: createRenderer(),
+        starField: createStarField(),
+        persistentCache: 'off',
+        autoResize: false,
+        autoDispose: false,
+        autoStart: false,
+      });
+      assert.equal(uncached.provider.describe().capabilities.persistentCache, false);
+      await uncached.dispose();
+    });
+  });
+});
+
+test('createSkykitBrowser treats forbidden Cache API access as disabled', async () => {
+  await withFakeWindow(async () => {
+    await withForbiddenCaches(async () => {
+      const browser = await createSkykitBrowser({
+        host: createHost(),
+        status: false,
+        renderer: createRenderer(),
+        starField: createStarField(),
+        autoResize: false,
+        autoDispose: false,
+        autoStart: false,
+      });
+
+      assert.equal(browser.provider.describe().capabilities.persistentCache, false);
+      await browser.dispose();
+    });
+  });
+});
+
 test('browser.install adds plugins after startup and cleans returned teardowns', async () => {
   await withFakeWindow(async () => {
     const calls = [];
@@ -193,46 +272,6 @@ test('browser.install adds plugins after startup and cleans returned teardowns',
   });
 });
 
-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({
@@ -338,6 +377,88 @@ async function withFakeWindow(callback) {
   }
 }
 
+async function withFakeCaches(callback) {
+  const previousCaches = Object.getOwnPropertyDescriptor(globalThis, 'caches');
+  const previousFetch = globalThis.fetch;
+  const cache = {
+    async match() {
+      return null;
+    },
+    async put() {},
+  };
+
+  Object.defineProperty(globalThis, 'caches', {
+    configurable: true,
+    value: {
+      async open() {
+        return cache;
+      },
+    },
+  });
+  Object.defineProperty(globalThis, 'fetch', {
+    configurable: true,
+    value(_url, options = {}) {
+      return new Promise((_resolve, reject) => {
+        if (options.signal?.aborted) {
+          const error = new Error('Range fetch aborted.');
+          error.name = 'AbortError';
+          reject(error);
+          return;
+        }
+        options.signal?.addEventListener?.('abort', () => {
+          const error = new Error('Range fetch aborted.');
+          error.name = 'AbortError';
+          reject(error);
+        }, { once: true });
+      });
+    },
+  });
+
+  try {
+    await callback();
+  } finally {
+    restoreGlobalProperty('caches', previousCaches);
+    if (previousFetch === undefined) {
+      delete globalThis.fetch;
+    } else {
+      Object.defineProperty(globalThis, 'fetch', {
+        configurable: true,
+        value: previousFetch,
+      });
+    }
+  }
+}
+
+async function withForbiddenCaches(callback) {
+  const previousCaches = Object.getOwnPropertyDescriptor(globalThis, 'caches');
+  const previousWarn = console.warn;
+
+  Object.defineProperty(globalThis, 'caches', {
+    configurable: true,
+    get() {
+      const error = new Error('Cache API storage is blocked.');
+      error.name = 'SecurityError';
+      throw error;
+    },
+  });
+  console.warn = () => {};
+
+  try {
+    await callback();
+  } finally {
+    console.warn = previousWarn;
+    restoreGlobalProperty('caches', previousCaches);
+  }
+}
+
+function restoreGlobalProperty(name, descriptor) {
+  if (descriptor) {
+    Object.defineProperty(globalThis, name, descriptor);
+  } else {
+    delete globalThis[name];
+  }
+}
+
 function createHost() {
   return {
     children: [],
@@ -440,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-xr.test.js

@@ -6,6 +6,7 @@ import * as THREE from 'three';
 import {
   applySkykitXrDepthRange,
   computeSkykitXrDepthRange,
+  createSkykitXrBodyPlugin,
   createSkykitXrBodyTracker,
   createSkykitXrControlBindings,
   createSkykitXrNavigationPlugin,
@@ -28,6 +29,7 @@ test('xr free-roam demo uses restored alpha XR regressions defaults', () => {
   assert.match(source, /createDefaultThreeStarFieldMaterialProfile/);
   assert.doesNotMatch(source, /createVrThreeStarFieldMaterialProfile/);
   assert.match(source, /createSkykitXrRayVisualPlugin/);
+  assert.match(source, /createSkykitXrBodyPlugin/);
   assert.match(source, /createSurfaceShell/);
   assert.match(source, /createMetaSidecarProviderService/);
   assert.match(source, /deriveMetaSidecarUrlFromRenderUrl/);
@@ -39,7 +41,12 @@ test('xr free-roam demo uses restored alpha XR regressions defaults', () => {
   assert.match(source, /primaryActionLabel:\s*'Fly to'/);
   assert.match(source, /homeControl:\s*'button'/);
   assert.match(source, /pointerType:\s*'ray'/);
+  assert.match(source, /return xrRig\.leftHandRoot/);
+  assert.match(source, /latestPanelFrame = rootContext\?\.frame \?\? latestPanelFrame/);
   assert.doesNotMatch(source, /dragThreshold/);
+  assert.doesNotMatch(source, /driver:\s*'pose-anchored'/);
+  assert.doesNotMatch(source, /anchorPose/);
+  assert.doesNotMatch(source, /latestPanelFrame = frame/);
   assert.doesNotMatch(source, /createChoiceGroup/);
   assert.doesNotMatch(source, /createSlider/);
   assert.doesNotMatch(source, /createToggle/);
@@ -112,6 +119,55 @@ test('skykit/xr body, rays, and pick router compose generic route results', () =
   assert.equal(route.hit.object, 'target');
 });
 
+test('skykit/xr body plugin drives tracked hand roots before dependent parts', () => {
+  const rig = createSkykitXrRig();
+  const leftGripSpace = {};
+  const referenceSpace = {};
+  const bodyUpdates = [];
+  let part = null;
+  const plugin = createSkykitXrBodyPlugin({
+    rig,
+    onBody(body) {
+      bodyUpdates.push(body);
+    },
+  });
+  plugin.setup(createPluginContext({
+    addPart(nextPart) {
+      part = nextPart;
+    },
+  }));
+
+  part.update(createXrFrame({
+    referenceSpace,
+    inputSources: [{
+      handedness: 'left',
+      gripSpace: leftGripSpace,
+      gamepad: {
+        buttons: [{ pressed: false, touched: false, value: 0 }],
+        axes: [0, 0],
+      },
+    }],
+    xrFrame: {
+      getPose(space, ref) {
+        assert.equal(ref, referenceSpace);
+        if (space !== leftGripSpace) return null;
+        return {
+          transform: {
+            position: { x: 0.1, y: 0.2, z: 0.3 },
+            orientation: { x: 0, y: 0, z: 0, w: 1 },
+          },
+        };
+      },
+    },
+  }));
+
+  assert.deepEqual(rig.leftHandRoot.position.toArray(), [0.1, 0.2, 0.3]);
+  assert.equal(rig.leftHandRoot.visible, true);
+  assert.equal(rig.rightHandRoot.visible, false);
+  assert.equal(plugin.getBody().leftHand?.buttons, 1);
+  assert.equal(bodyUpdates.length, 1);
+});
+
 test('skykit/xr depth helpers compute and apply render state', () => {
   const range = computeSkykitXrDepthRange({
     visibleBounds: { min: { x: -1, y: -1, z: -20 }, max: { x: 1, y: 1, z: -10 } },