@volter/editor-threejs 0.5.66 → 0.5.68

package/contributions/animation-timeline.utility.tsx

@@ -0,0 +1,44 @@
+/**
+ * THE ANIMATION PANEL (`workspace.utility`): the active document's stage transport, drawn by the
+ * kit's own strip. A world document's stage attaches every clip its scene can show — a GLTF's
+ * own `animations`, and the mixers the game's code made (`animation-mixers.service.ts`) — and
+ * this is where a person scrubs and plays them in Edit, as Unity's Animation window does beside
+ * its Scene view. While Play drives time the strip goes read-only and says why.
+ */
+import { editorHost } from '@volter/editor-sdk/host';
+import { TransportStrip } from '@volter/editor-sdk/kit/transport-strip';
+import { Text } from '@volter/editor-sdk/widgets';
+import { useCallback, useSyncExternalStore } from 'react';
+
+export const point = 'workspace.utility';
+export const title = 'Animation';
+
+export default function AnimationTimeline() {
+  const { documents, transport } = editorHost();
+  const activeId = useSyncExternalStore(documents.subscribe, documents.activeId, documents.activeId);
+  const handle = useSyncExternalStore(
+    transport.subscribe,
+    useCallback(() => (activeId ? transport.for(activeId) : null), [activeId, transport]),
+  );
+  const snapshot = useSyncExternalStore(
+    useCallback((listener: () => void) => (handle ? handle.subscribe(listener) : () => {}), [handle]),
+    useCallback(() => handle?.snapshot() ?? null, [handle]),
+  );
+  if (!handle || !snapshot || snapshot.activeSubject === null) {
+    return (
+      <Text
+        as="p"
+        variant="caption"
+        data-testid="animation-timeline-empty"
+        data-document={activeId ?? ''}
+        data-transport={handle ? 'yes' : 'no'}
+        style={{ padding: 'var(--vgai-space-2) var(--vgai-space-3)' }}
+      >
+        {handle
+          ? 'Nothing in the active document plays an animation.'
+          : 'The active document has no stage to animate.'}
+      </Text>
+    );
+  }
+  return <TransportStrip transport={handle} />;
+}

package/contributions/three-integration.service.ts

@@ -0,0 +1,13 @@
+/**
+ * The Three integration, installed at boot (`workspace.service`): the Object3D surfaces
+ * contributions mount, the viewport's relay verbs, Asset Lab viewers, inspection and hierarchy
+ * media, captures, the authoring policy and the session's view-state persistence
+ * (`src/kit/three-integration.ts`). Every viewport also ensures it before it mounts.
+ */
+import { ensureThreeIntegration } from '../src/kit/three-integration';
+
+export const point = 'workspace.service';
+
+export function start(): () => void {
+  return ensureThreeIntegration();
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@volter/editor-threejs",
   "author": "Volter AI, Inc.",
-  "version": "0.5.66",
+  "version": "0.5.68",
   "publishConfig": {
     "access": "public"
   },
@@ -30,11 +30,96 @@
       "default": "./src/*"
     },
     "./asset-parse-error": "./src/asset-parse-error.ts",
-    "./loader": "./src/loader.ts"
+    "./loader": "./src/loader.ts",
+    "./kit/animation/three-clips-subject": "./src/kit/animation/three-clips-subject.ts",
+    "./kit/asset-compare": "./src/kit/asset-compare.ts",
+    "./kit/asset-preview-command": "./src/kit/asset-preview-command.ts",
+    "./kit/asset-preview-framing": "./src/kit/asset-preview-framing.ts",
+    "./kit/asset-preview": "./src/kit/asset-preview.ts",
+    "./kit/asset-workflow/model-inspection": "./src/kit/asset-workflow/model-inspection.ts",
+    "./kit/authoring/component-instance-root": "./src/kit/authoring/component-instance-root.ts",
+    "./kit/authoring/design-time-settle": "./src/kit/authoring/design-time-settle.ts",
+    "./kit/authoring/live-object-transform": "./src/kit/authoring/live-object-transform.ts",
+    "./kit/authoring/object3d-document-session-registry": "./src/kit/authoring/object3d-document-session-registry.ts",
+    "./kit/authoring/object3d-document-session": "./src/kit/authoring/object3d-document-session.ts",
+    "./kit/authoring/quarks-particle-systems": "./src/kit/authoring/quarks-particle-systems.ts",
+    "./kit/authoring/shell-viewport-policy": "./src/kit/authoring/shell-viewport-policy.ts",
+    "./kit/authoring/source-object3d-authoring-adapter": "./src/kit/authoring/source-object3d-authoring-adapter.ts",
+    "./kit/authoring/three-projection-core": "./src/kit/authoring/three-projection-core.ts",
+    "./kit/authoring/viewport-pick-context": "./src/kit/authoring/viewport-pick-context.ts",
+    "./kit/authoring/viewport-raycast": "./src/kit/authoring/viewport-raycast.ts",
+    "./kit/authoring/world-hidden-viewport": "./src/kit/authoring/world-hidden-viewport.ts",
+    "./kit/camera-authoring": "./src/kit/camera-authoring.ts",
+    "./kit/components/CameraInfo": "./src/kit/components/CameraInfo.tsx",
+    "./kit/components/InspectorObjectPreview": "./src/kit/components/InspectorObjectPreview.tsx",
+    "./kit/components/Object3DDocumentToolbar": "./src/kit/components/Object3DDocumentToolbar.tsx",
+    "./kit/components/Object3DDocumentViewport": "./src/kit/components/Object3DDocumentViewport.tsx",
+    "./kit/components/StageHost": "./src/kit/components/StageHost.tsx",
+    "./kit/components/StageOverlays": "./src/kit/components/StageOverlays.tsx",
+    "./kit/components/StatsOverlay": "./src/kit/components/StatsOverlay.tsx",
+    "./kit/components/ToolObject3DPreview": "./src/kit/components/ToolObject3DPreview.tsx",
+    "./kit/components/ViewportFurniture": "./src/kit/components/ViewportFurniture.tsx",
+    "./kit/components/ViewportOverlay": "./src/kit/components/ViewportOverlay.tsx",
+    "./kit/components/ViewportShadingMenu": "./src/kit/components/ViewportShadingMenu.tsx",
+    "./kit/components/ViewportViewMenu": "./src/kit/components/ViewportViewMenu.tsx",
+    "./kit/components/asset-viewers/EntityModelDocument": "./src/kit/components/asset-viewers/EntityModelDocument.tsx",
+    "./kit/components/asset-viewers/EnvironmentAssetDocument": "./src/kit/components/asset-viewers/EnvironmentAssetDocument.tsx",
+    "./kit/components/asset-viewers/LiveModuleDocument": "./src/kit/components/asset-viewers/LiveModuleDocument.tsx",
+    "./kit/components/asset-viewers/LutAssetDocument": "./src/kit/components/asset-viewers/LutAssetDocument.tsx",
+    "./kit/components/asset-viewers/ModelAssetDocument": "./src/kit/components/asset-viewers/ModelAssetDocument.tsx",
+    "./kit/components/asset-viewers/Object3DPreview": "./src/kit/components/asset-viewers/Object3DPreview.tsx",
+    "./kit/components/asset-viewers/QuarksAssetDocument": "./src/kit/components/asset-viewers/QuarksAssetDocument.tsx",
+    "./kit/components/asset-viewers/ShaderAssetDocument": "./src/kit/components/asset-viewers/ShaderAssetDocument.tsx",
+    "./kit/components/asset-viewers/three-asset-viewers": "./src/kit/components/asset-viewers/three-asset-viewers.tsx",
+    "./kit/components/stage-keyboard": "./src/kit/components/stage-keyboard.tsx",
+    "./kit/components/stage-overlay-set": "./src/kit/components/stage-overlay-set.tsx",
+    "./kit/components/stage-presence-markers": "./src/kit/components/stage-presence-markers.ts",
+    "./kit/components/stage-transform-chrome": "./src/kit/components/stage-transform-chrome.ts",
+    "./kit/components/stage-transform-tools": "./src/kit/components/stage-transform-tools.tsx",
+    "./kit/components/standard-viewport-dressing": "./src/kit/components/standard-viewport-dressing.ts",
+    "./kit/components/world-root-binding": "./src/kit/components/world-root-binding.ts",
+    "./kit/constraint-helper": "./src/kit/constraint-helper.ts",
+    "./kit/editor-shell-store": "./src/kit/editor-shell-store.ts",
+    "./kit/editor-viewport": "./src/kit/editor-viewport.ts",
+    "./kit/entity-lod": "./src/kit/entity-lod.ts",
+    "./kit/entity-object": "./src/kit/entity-object.ts",
+    "./kit/hierarchy-mark-reader": "./src/kit/hierarchy-mark-reader.ts",
+    "./kit/instanced-presentation": "./src/kit/instanced-presentation.ts",
+    "./kit/live-module-source": "./src/kit/live-module-source.ts",
+    "./kit/model-thumbnail": "./src/kit/model-thumbnail.ts",
+    "./kit/projection/three": "./src/kit/projection/three.ts",
+    "./kit/reflection-probe-helper": "./src/kit/reflection-probe-helper.ts",
+    "./kit/scene-document-viewport": "./src/kit/scene-document-viewport.ts",
+    "./kit/scene-framing": "./src/kit/scene-framing.ts",
+    "./kit/scene-view-fog": "./src/kit/scene-view-fog.ts",
+    "./kit/spatial-handle-visuals": "./src/kit/spatial-handle-visuals.ts",
+    "./kit/stories/three-story-model": "./src/kit/stories/three-story-model.ts",
+    "./kit/three-canvas-render": "./src/kit/three-canvas-render.ts",
+    "./kit/three-hierarchy-row-media": "./src/kit/three-hierarchy-row-media.ts",
+    "./kit/three-inspection-media": "./src/kit/three-inspection-media.ts",
+    "./kit/three-integration": "./src/kit/three-integration.ts",
+    "./kit/three-state": "./src/kit/three-state.ts",
+    "./kit/three-viewport/bone-selection-highlight": "./src/kit/three-viewport/bone-selection-highlight.ts",
+    "./kit/three-viewport/camera-fit": "./src/kit/three-viewport/camera-fit.ts",
+    "./kit/three-viewport/interactive-renderer": "./src/kit/three-viewport/interactive-renderer.ts",
+    "./kit/three-viewport/selection-brackets": "./src/kit/three-viewport/selection-brackets.ts",
+    "./kit/three-viewport/selection-outline": "./src/kit/three-viewport/selection-outline.ts",
+    "./kit/three-viewport/skeleton-helper": "./src/kit/three-viewport/skeleton-helper.ts",
+    "./kit/three-viewport/source-color": "./src/kit/three-viewport/source-color.ts",
+    "./kit/three-viewport/studio-environment": "./src/kit/three-viewport/studio-environment.ts",
+    "./kit/trigger-volume-helper": "./src/kit/trigger-volume-helper.ts",
+    "./kit/viewport-actions": "./src/kit/viewport-actions.ts",
+    "./kit/viewport-authoring-policy": "./src/kit/viewport-authoring-policy.ts",
+    "./kit/viewport-commands": "./src/kit/viewport-commands.ts",
+    "./kit/viewport-hotkeys": "./src/kit/viewport-hotkeys.ts",
+    "./kit/viewport-shading-boundary": "./src/kit/viewport-shading-boundary.ts",
+    "./kit/viewport-status-facet": "./src/kit/viewport-status-facet.ts"
   },
   "peerDependencies": {
     "three": "^0.180.0",
-    "vite": "^6.4.3"
+    "vite": "^6.4.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "scripts": {
     "build": "node scripts/build-serving.mjs",
@@ -43,17 +128,22 @@
   },
   "vgai": {
     "contributions": [
-      "./contributions/animation-mixers.service.ts"
+      "./contributions/three-integration.service.ts",
+      "./contributions/animation-mixers.service.ts",
+      "./contributions/animation-timeline.utility.tsx"
     ],
     "serving": "./dist-node/serving.mjs"
   },
   "dependencies": {
-    "@volter/editor-project": "0.5.66",
+    "@volter/editor-project": "0.5.68",
     "@sparkjsdev/spark": "^2.1.0",
     "three.quarks": "^0.16.0",
     "zod": "^4.3.6",
     "typescript": "5.9.3",
-    "@volter/editor-sdk": "0.5.66"
+    "@volter/editor-sdk": "0.5.68",
+    "postprocessing": "6.38.3",
+    "quarks.core": "0.16.0",
+    "@fortawesome/free-solid-svg-icons": "^7.2.0"
   },
   "devDependencies": {
     "esbuild": "0.25.12"

package/src/adapter/renderer-config.ts

@@ -4,9 +4,8 @@
  * The SHAPE is the project contract's (`@volter/editor-project/adapter/renderer-config`,
  * whose header states the rule and the three load-bearing properties); this
  * file is what writes it onto a live `WebGLRenderer` and hands back the
- * restore. `world3d-react/r3f-root-factory.tsx` is the declarer,
- * `runtime/create-runtime.ts` the host, the editor's world-root stage the
- * applier.
+ * restore. A mounted three root declares it (`MountedThreeRoot.rendererConfig`)
+ * and the editor's world-root stage applies it.
  */
 
 import type {
@@ -28,7 +27,7 @@ export type {
  * Apply `config` to `renderer`, returning the restore function that puts back what was there.
  *
  * `three` is passed in rather than imported for values so the enum constants come from the HOST's
- * three instance — the same identity rule `r3f-root-factory.tsx` follows for the scene and camera.
+ * three instance — the same identity rule `r3f-root.tsx` follows for the scene and camera.
  */
 export function applyWorldRendererConfig(
   three: typeof THREE,

package/src/adapter/three-contract.ts

@@ -0,0 +1,72 @@
+/**
+ * The Three-typed half of the adapter contract. `@volter/editor-project`
+ * states the `three` surface with its medium objects opaque (a scene, a
+ * camera, a renderer, a hierarchy's scene objects, navigation's debug mesh);
+ * this module names them as three.js objects for the editor side that renders
+ * and authors them. A `three`-surface adapter hands exactly these objects, so
+ * each view below is a narrowing of what the contract already carries, not a
+ * conversion.
+ */
+
+import type {
+  AuthoringAdapter,
+  HierarchyProvider,
+  MountedThreeRoot,
+  NavigationAdapter,
+  PhysicsAdapter,
+  ThreeHostContext,
+} from '@volter/editor-project/adapter';
+import type { NavBakeParams } from '@volter/editor-project/adapter/system-adapter';
+import type * as THREE from 'three';
+
+/** Shared GLTF/texture cache a `three` host hands its roots. */
+export interface ThreeAssetCache {
+  /** Load an asset by URL. Returns a cached promise if already loading/loaded. */
+  load<T = unknown>(url: string): Promise<T>;
+  /** Get a previously-loaded asset synchronously. Throws if not yet loaded. */
+  get<T = unknown>(url: string): T;
+}
+
+/** What a `three`-surface root is handed, Three-typed. */
+export type ThreeRootHostContext = ThreeHostContext<typeof THREE, THREE.WebGLRenderer, ThreeAssetCache>;
+
+/** A live, mounted Three world, Three-typed. */
+export type ThreeMountedRoot = MountedThreeRoot<THREE.Scene, THREE.Camera>;
+
+/** A mounted `three` root, as the Three objects it hands. */
+export function threeRoot(mounted: MountedThreeRoot): ThreeMountedRoot {
+  return mounted as ThreeMountedRoot;
+}
+
+/** The hierarchy's scene-object doors, Three-typed. */
+export interface ThreeHierarchy {
+  object3D?(id: string): THREE.Object3D | null;
+  idForObject3D?(o: THREE.Object3D): string | null;
+}
+
+/** A `three`-surface authoring adapter's hierarchy, as the Three objects it hands. */
+export function threeHierarchy(adapter: Pick<AuthoringAdapter, 'hierarchy'>): HierarchyProvider & ThreeHierarchy {
+  return adapter.hierarchy as HierarchyProvider & ThreeHierarchy;
+}
+
+/** The live Three object a `three`-surface hierarchy hands for `id` (null
+ * when it has none, or omits the door). */
+export function threeObject(hierarchy: Pick<HierarchyProvider, 'object3D'>, id: string): THREE.Object3D | null {
+  return (hierarchy.object3D?.(id) ?? null) as THREE.Object3D | null;
+}
+
+/** A `three`-surface navigation adapter, as the Three objects it trades in. */
+export interface ThreeNavigationAdapter extends NavigationAdapter {
+  debugMesh(scene: THREE.Scene): THREE.Object3D | null;
+  bake?(meshes: THREE.Mesh[], params?: NavBakeParams): boolean;
+  clear?(scene: THREE.Scene): void;
+}
+
+export function threeNavigation(adapter: NavigationAdapter): ThreeNavigationAdapter {
+  return adapter as ThreeNavigationAdapter;
+}
+
+/** A `three`-surface physics adapter's debug-draw object. */
+export function threePhysicsDebugDraw(adapter: PhysicsAdapter): THREE.Object3D | null {
+  return (adapter.debugDraw?.() ?? null) as THREE.Object3D | null;
+}

package/src/ecs/object-marks.ts

@@ -33,7 +33,7 @@ export type EditorHelperType =
   | 'trigger-volumes'
   | 'skeletons'
   // A package's own helper kind, shown through the editor's viewport door
-  // (`host.viewport.setHelper`): the host lists the kinds it toggles by name,
+  // (the viewport door's `setViewportHelper`): the host lists the kinds it toggles by name,
   // any other follows the master Helpers toggle.
   | (string & {});
 

package/src/ecs/user-data.ts

@@ -40,11 +40,6 @@
  * - `gaussianSplat`       — native Spark splat metadata used for renderer discovery,
  *                           inspector facts, bounds, and deterministic disposal.
  *
- * Animation (load-bearing — ED5 disposal contract):
- * - `_animMixer`          — THREE.AnimationMixer driving this subtree's clips.
- * - `_availableClips`     — string[] of clip names discovered on the GLTF
- *                           (inspector dropdown).
- *
  * Disposal contract:
  * - `__sharedGeometry`    — `true` when a mesh's geometry is shared/cached and MUST
  *                           NOT be disposed by per-object cleanup (P0.2 contract).
@@ -137,8 +132,6 @@ export interface UserDataSchema extends ObjectMarkSchema {
   _camera: THREE.Camera;
   _particleSystem: ParticleSystem;
   gaussianSplat: { src: string; numSplats: number };
-  _animMixer: THREE.AnimationMixer;
-  _availableClips: string[];
   __sharedGeometry: boolean;
   __shadeOrig: THREE.Material | THREE.Material[];
   __shadeUnlit: THREE.Material[];
@@ -189,8 +182,6 @@ export const UserDataKeys = {
   _camera: '_camera',
   _particleSystem: '_particleSystem',
   gaussianSplat: 'gaussianSplat',
-  _animMixer: '_animMixer',
-  _availableClips: '_availableClips',
   __sharedGeometry: '__sharedGeometry',
   __shadeOrig: '__shadeOrig',
   __shadeUnlit: '__shadeUnlit',

package/src/host-hierarchy-objects.ts

@@ -0,0 +1,31 @@
+/**
+ * The live objects behind the hierarchy's node ids, as a media
+ * integration provides them: the Three integration answers from the session store's Three half,
+ * and a lane that reads a scene's objects (the navmesh bake, Play's camera flight) asks here.
+ * With none registered there are no objects.
+ */
+import type * as THREE from 'three';
+
+/**
+ * The world node IS the entity, so a contribution inspecting a live behavior resolves the
+ * hierarchy's node id to the object itself. The map is the authored viewport's in Edit and the
+ * adopted live scene's in Play; a reader must not hold an object across the hierarchy's
+ * `subscribe` firings.
+ */
+export interface HostHierarchyObjects {
+  object(id: string): THREE.Object3D | null;
+  objects(): ReadonlyMap<string, THREE.Object3D>;
+}
+
+let registered: HostHierarchyObjects | null = null;
+
+export function registerHostHierarchyObjects(provider: HostHierarchyObjects): () => void {
+  registered = provider;
+  return () => {
+    if (registered === provider) registered = null;
+  };
+}
+
+export function hostHierarchyObjects(): HostHierarchyObjects | null {
+  return registered;
+}

package/src/kit/animation/three-clips-subject.ts

@@ -0,0 +1,190 @@
+/**
+ * WHAT A THREE WORLD CAN SHOW AT A TIME — the stage transport's subjects for
+ * an ordinary three/R3F stage (WORK.md §The stage transport and the animation
+ * door, Step 3).
+ *
+ * TWO DISCOVERIES, because a three world carries clips in two different
+ * places and only one of them is the obvious one:
+ *
+ *  1. `object.animations` — what a GLTF's own `AnimationClip[]` lands in when
+ *     something assigns it. A subject here owns a NEW `AnimationMixer` on that
+ *     object, because nothing else is playing it.
+ *  2. `liveMixerFor(object)` — the mixer the world's OWN code made for it
+ *     (`new THREE.AnimationMixer(…)`, drei's `useAnimations`), found through
+ *     the served animation stamp (`@volter/editor-threejs/animation/live-mixers`).
+ *     A subject here drives THAT mixer; minting a second mixer over the same
+ *     object would give one skeleton two writers.
+ *
+ * DISCOVERY 2 IS NOT OPTIONAL, and this is the measurement that says so:
+ * three's `GLTFLoader` never assigns `scene.animations`, so an R3F character
+ * loaded with `useGLTF` has an EMPTY `animations` array on its Object3D. A
+ * scan that looked only at `animations` would find nothing on exactly the
+ * worlds a person most wants to scrub.
+ *
+ * THE MIXER IS THREE'S OWN and every call here is three's own API — this is a
+ * subject over `AnimationMixer`, never a wrapper around it. `setTime` is the
+ * one write; the transport owns the position.
+ */
+import { liveMixerFor, subscribeLiveMixers } from '@volter/editor-threejs/animation/live-mixers';
+import * as THREE from 'three';
+import type { StageTransport } from '@volter/editor-sdk/kit/animation/stage-transport';
+
+/** The display rate a three clip is shown at. Three clips carry a duration in
+ *  SECONDS and no rate of their own, so the transport needs one to convert a
+ *  frame for a look that asks in frames. 30 is three's own editor convention
+ *  (`AnimationClip.CreateFromMorphTargetSequence` defaults to it). */
+const THREE_DISPLAY_FPS = 30;
+
+function clamp(value: number, min: number, max: number): number {
+  return value < min ? min : value > max ? max : value;
+}
+
+/**
+ * A subject over an object's OWN clips, on a mixer this subject mints and
+ * owns. `setClip` swaps which clip is showing: the chosen action plays and
+ * every other action is stopped. Nothing but the transport ticks this mixer,
+ * so the action moves only when the transport samples it — and it must NOT
+ * be paused: three advances a paused action by zero, so every scrub would
+ * show the clip's first frame.
+ */
+function attachOwnClips(object: THREE.Object3D, transport: StageTransport): (() => void) | null {
+  const clips = object.animations;
+  if (clips.length === 0) return null;
+  const mixer = new THREE.AnimationMixer(object);
+  let current = clips[0];
+  if (!current) return null;
+
+  const show = (clip: THREE.AnimationClip): void => {
+    mixer.stopAllAction();
+    const action = mixer.clipAction(clip);
+    action.paused = false;
+    action.play();
+    current = clip;
+  };
+  show(current);
+
+  const detach = transport.attach({
+    id: object.uuid,
+    label: object.name || current.name || 'Clip',
+    range: () => ({ start: 0, end: current?.duration ?? 0, fps: THREE_DISPLAY_FPS }),
+    seek: (seconds) => {
+      mixer.setTime(clamp(seconds, 0, current?.duration ?? 0));
+    },
+    clips: () => clips.map((clip) => ({ id: clip.name, label: clip.name })),
+    setClip: (id) => {
+      const next = clips.find((clip) => clip.name === id);
+      if (next) show(next);
+    },
+  });
+
+  return () => {
+    detach();
+    mixer.stopAllAction();
+    mixer.uncacheRoot(object);
+  };
+}
+
+/**
+ * A subject over a mixer the world's own code made. It drives that mixer and
+ * never mints one; `clips` are the ones the world has played through it.
+ */
+function attachInspected(object: THREE.Object3D, transport: StageTransport): (() => void) | null {
+  const inspection = liveMixerFor(object);
+  if (!inspection) return null;
+  let current = inspection.clips.values().next().value;
+  if (!current) return null;
+
+  const show = (clip: THREE.AnimationClip): void => {
+    inspection.mixer.stopAllAction();
+    const action = inspection.mixer.clipAction(clip);
+    action.paused = false;
+    action.play();
+    current = clip;
+  };
+
+  const detach = transport.attach({
+    id: object.uuid,
+    label: object.name || current.name || 'Animation',
+    range: () => ({ start: 0, end: current?.duration ?? 0, fps: THREE_DISPLAY_FPS }),
+    seek: (seconds) => {
+      inspection.mixer.setTime(clamp(seconds, 0, current?.duration ?? 0));
+    },
+    clips: () => [...inspection.clips.entries()].map(([name, clip]) => ({ id: name, label: clip.name || name })),
+    setClip: (id) => {
+      const next = inspection.clips.get(id);
+      if (next) show(next);
+    },
+  });
+
+  // Deliberately NOT stopping the mixer's actions on detach: this subject
+  // borrowed a mixer the world owns, and a borrower does not decide what the
+  // owner is playing when it leaves.
+  return detach;
+}
+
+/**
+ * One scan of a mounted root, and the handle that keeps it current.
+ *
+ * `refresh()` DIFFS by object uuid rather than re-attaching: a rescan of an
+ * unchanged tree must not detach and re-attach every subject, because that
+ * would reset which clip each one is showing under a person's hands. The
+ * caller decides when to rescan (the stage host throttles it and skips it
+ * while the world is driving time).
+ */
+export interface ClipSubjectScan {
+  refresh(): void;
+  dispose(): void;
+}
+
+export function scanClipSubjects(
+  root: THREE.Object3D | (() => THREE.Object3D | null),
+  transport: StageTransport,
+  options: {
+    /** Rescan when the game registers or drops a mixer, while this answers true. */
+    readonly rescanOnLiveMixers?: () => boolean;
+  } = {},
+): ClipSubjectScan {
+  const attached = new Map<string, () => void>();
+
+  const refresh = (): void => {
+    const seen = new Set<string>();
+    // A getter for a stage whose rendered scene is not fixed at construction:
+    // a world stage draws the session store's scene once the world mounts.
+    const current = typeof root === 'function' ? root() : root;
+    current?.traverse((object) => {
+      if (attached.has(object.uuid)) {
+        seen.add(object.uuid);
+        return;
+      }
+      // The inspection wins when an object has both: it means a world binding
+      // is already driving that skeleton, and a second mixer over it would
+      // give one object two writers.
+      const detach = attachInspected(object, transport) ?? attachOwnClips(object, transport);
+      if (!detach) return;
+      attached.set(object.uuid, detach);
+      seen.add(object.uuid);
+    });
+    for (const [uuid, detach] of [...attached]) {
+      if (seen.has(uuid)) continue;
+      detach();
+      attached.delete(uuid);
+    }
+  };
+
+  refresh();
+  const rescanWhen = options.rescanOnLiveMixers;
+  const stopMixers = rescanWhen
+    ? subscribeLiveMixers(() => {
+        if (rescanWhen()) refresh();
+      })
+    : () => {};
+
+  return {
+    refresh,
+    dispose: () => {
+      stopMixers();
+      for (const detach of attached.values()) detach();
+      attached.clear();
+    },
+  };
+}