@volter/editor-threejs 0.5.65 → 0.5.67

package/src/animation/live-mixers.ts

@@ -0,0 +1,55 @@
+/**
+ * The mixers a running world animates with, as the editor reads them: the registry the served
+ * animation stamp fills (`serving/animation-live-module.ts`) in the game's graph. An instrument
+ * that drives time on an object asks here for the mixer the game already made for it, so the
+ * skeleton keeps one writer.
+ */
+
+import type * as THREE from 'three';
+
+export interface LiveMixer {
+  /** The call site that made it (`src/prefabs/Player.tsx:358:37`). */
+  readonly key: string;
+  readonly mixer: THREE.AnimationMixer;
+  /** Every clip the game has played through it, and every clip `useAnimations` was handed. */
+  readonly clips: ReadonlyMap<string, THREE.AnimationClip>;
+  /** The objects its actions animate. */
+  readonly roots: ReadonlySet<unknown>;
+}
+
+interface Registry {
+  readonly mixers: Map<unknown, LiveMixer>;
+  readonly listeners: Set<() => void>;
+  version: number;
+}
+
+const REGISTRY = Symbol.for('volter.three.animation.live');
+
+function registry(): Registry {
+  const holder = globalThis as unknown as Record<symbol, Registry | undefined>;
+  return (holder[REGISTRY] ??= { mixers: new Map(), listeners: new Set(), version: 0 });
+}
+
+/** The live mixer that animates `object`, or null when the game animates it with none. */
+export function liveMixerFor(object: THREE.Object3D): LiveMixer | null {
+  for (const entry of registry().mixers.values()) {
+    if (entry.clips.size === 0) continue;
+    if (entry.mixer.getRoot() === object || entry.roots.has(object)) return entry;
+  }
+  return null;
+}
+
+/** Every mixer the running world's code has made, in the order it made them. */
+export function liveMixers(): LiveMixer[] {
+  return [...registry().mixers.values()];
+}
+
+export function subscribeLiveMixers(listener: () => void): () => void {
+  const listeners = registry().listeners;
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function liveMixersVersion(): number {
+  return registry().version;
+}

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,13 +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.
- * - `_animClips`          — Map<string, AnimationClip> discovered on the GLTF.
- * - `_availableClips`     — string[] of clip names discovered on the GLTF
- *                           (inspector dropdown; same names as `_animClips`' keys).
- * - `_animationRuntime`   — format-neutral live native mixer/action inspection.
- *
  * Disposal contract:
  * - `__sharedGeometry`    — `true` when a mesh's geometry is shared/cached and MUST
  *                           NOT be disposed by per-object cleanup (P0.2 contract).
@@ -119,7 +112,6 @@ import type { ConstraintMark } from '../adapter/constraint';
 import type { Object3DAuthoringSubjectMark } from '../adapter/object3d-authoring-subject';
 import type { ReflectionProbeMark } from '../adapter/reflection-probe';
 import type { TriggerVolumeMark } from '../adapter/trigger-volume';
-import type { AnimationRuntimeInspection } from '../animation/runtime-inspection';
 import { ObjectMarkKeys, type ObjectMarkSchema } from './object-marks';
 
 export type { EditorHelperType } from './object-marks';
@@ -140,10 +132,6 @@ export interface UserDataSchema extends ObjectMarkSchema {
   _camera: THREE.Camera;
   _particleSystem: ParticleSystem;
   gaussianSplat: { src: string; numSplats: number };
-  _animMixer: THREE.AnimationMixer;
-  _animClips: Map<string, THREE.AnimationClip>;
-  _availableClips: string[];
-  _animationRuntime: AnimationRuntimeInspection;
   __sharedGeometry: boolean;
   __shadeOrig: THREE.Material | THREE.Material[];
   __shadeUnlit: THREE.Material[];
@@ -194,10 +182,6 @@ export const UserDataKeys = {
   _camera: '_camera',
   _particleSystem: '_particleSystem',
   gaussianSplat: 'gaussianSplat',
-  _animMixer: '_animMixer',
-  _animClips: '_animClips',
-  _availableClips: '_availableClips',
-  _animationRuntime: '_animationRuntime',
   __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();
+    },
+  };
+}

package/src/kit/asset-compare.ts

@@ -0,0 +1,294 @@
+/**
+ * B8.4 — the Asset Lab COMPARE surface (`vgai screenshot <model.glb>
+ * --compare <ref.glb>`): renders the project asset AND a caller-supplied reference GLB
+ * with matched orthographic front + side framing, then scores their
+ * silhouettes (IoU) and composes review overlays, so an agent can
+ * numerically converge a procedural character toward a reference.
+ *
+ * Framing is DELIBERATELY bounding-box based (equal-height normalization,
+ * shared ground plane, centered footprint) rather than the humanoid shot
+ * set's Mixamo-skeleton anchors: the reference may carry any rig (UE joint
+ * names, no rig at all), and the bone-anchored path throws on missing joints
+ * by design. Both models are yaw-normalized to FACE the front camera —
+ * forward read from GLB `extras`/`userData.forward` when present (our
+ * generated rigs persist `[0,0,-1]`), else the glTF +Z convention, with an
+ * explicit reference override for models whose extras lie.
+ *
+ * Pure scoring math lives in `asset-compare-core.ts` (unit-tested in node);
+ * this module owns only loading, scene assembly, and WebGL capture. Fixed
+ * cameras + fixed resolution + flat unlit override ⇒ identical IoU numbers
+ * across runs (a stated acceptance gate).
+ */
+
+import { markHostRenderer } from '@volter/editor-threejs/viewport/renderer-ownership';
+import * as THREE from 'three';
+import {
+  ASSET_COMPARE_VIEWS,
+  type AssetCompareView,
+  COMPARE_FRAME_CENTER_Y,
+  COMPARE_FRAME_HALF_HEIGHT,
+  forwardYawRadians,
+  maskIoU,
+  normalizedPlacement,
+  overlayRgba,
+  silhouetteMaskFromRgba,
+} from '@volter/editor-sdk/kit/asset-compare-core';
+import {
+  checkedDimension,
+  createAssetPreviewSnapshot,
+  disposeAssetPreviewSnapshot,
+  disposeProjectAssetModel,
+  loadProjectAssetModel,
+  measureAssetPreview,
+  parseGlbBytesModel,
+  pngBase64,
+  readModelForward,
+} from './asset-preview';
+
+export type { AssetCompareView } from '@volter/editor-sdk/kit/asset-compare-core';
+// The forward detection moved to `asset-preview.ts` (the shot sets need it
+// too); re-exported here so compare-mode consumers keep their import path.
+export { readModelForward } from './asset-preview';
+
+export interface AssetCompareImage {
+  base64: string;
+  mimeType: 'image/png';
+}
+
+export interface AssetCompareViewResult {
+  view: AssetCompareView;
+  /** Silhouette intersection-over-union in [0, 1]. */
+  iou: number;
+  /** Both silhouettes in distinct colors (orange asset / cyan ref / white agreement). */
+  overlay: AssetCompareImage;
+  /** The asset's own silhouette (white on black), as captured for scoring. */
+  asset: AssetCompareImage;
+  /** The reference's silhouette (white on black), as captured for scoring. */
+  ref: AssetCompareImage;
+}
+
+export interface AssetCompareCapture {
+  width: number;
+  height: number;
+  views: AssetCompareViewResult[];
+}
+
+export interface AssetCompareOptions {
+  width?: number;
+  height?: number;
+  /** Override the reference GLB's forward vector (its facing in the ground
+   *  plane). Defaults to the GLB's own `userData.forward` extras, else +Z. */
+  refForward?: [number, number, number];
+}
+
+const SILHOUETTE_BACKGROUND = 0x000000;
+const SILHOUETTE_FOREGROUND = 0xffffff;
+const COMPARE_CAMERA_DISTANCE = 10;
+
+/** The base64-GLB decoder moved to `asset-preview.ts` (`parseGlbBytesModel`)
+ *  when the module-look lane needed the same wire-carried bytes; this keeps
+ *  compare's own error wording. */
+function parseRefGlb(base64: string): Promise<THREE.Object3D> {
+  return parseGlbBytesModel(base64, 'Compare reference GLB');
+}
+
+/** Snapshot + face-the-camera yaw + equal-height ground-aligned placement,
+ *  as one disposable wrapper ready to drop into a silhouette scene. */
+function buildNormalizedSubject(
+  source: THREE.Object3D,
+  forward: [number, number, number],
+): { wrapper: THREE.Object3D; dispose: () => void } {
+  const snapshot = createAssetPreviewSnapshot(source);
+  const pivot = new THREE.Group();
+  pivot.rotation.y = forwardYawRadians(forward);
+  pivot.add(snapshot);
+  const wrapper = new THREE.Group();
+  wrapper.add(pivot);
+  wrapper.updateWorldMatrix(true, true);
+  const bounds = measureAssetPreview(wrapper, 'front');
+  const min: [number, number, number] = [
+    bounds.center.x - bounds.size.x / 2,
+    bounds.center.y - bounds.size.y / 2,
+    bounds.center.z - bounds.size.z / 2,
+  ];
+  const max: [number, number, number] = [
+    bounds.center.x + bounds.size.x / 2,
+    bounds.center.y + bounds.size.y / 2,
+    bounds.center.z + bounds.size.z / 2,
+  ];
+  const placement = normalizedPlacement(min, max);
+  wrapper.scale.setScalar(placement.scale);
+  wrapper.position.set(...placement.position);
+  wrapper.updateWorldMatrix(true, true);
+  return { wrapper, dispose: () => disposeAssetPreviewSnapshot(snapshot) };
+}
+
+function compareCamera(view: AssetCompareView, aspect: number): THREE.OrthographicCamera {
+  const halfHeight = COMPARE_FRAME_HALF_HEIGHT;
+  const halfWidth = halfHeight * aspect;
+  const camera = new THREE.OrthographicCamera(
+    -halfWidth,
+    halfWidth,
+    halfHeight,
+    -halfHeight,
+    0.01,
+    COMPARE_CAMERA_DISTANCE * 4,
+  );
+  const direction = view === 'front' ? new THREE.Vector3(0, 0, 1) : new THREE.Vector3(1, 0, 0);
+  camera.position
+    .set(0, COMPARE_FRAME_CENTER_Y, 0)
+    .addScaledVector(direction, COMPARE_CAMERA_DISTANCE);
+  camera.up.set(0, 1, 0);
+  camera.lookAt(0, COMPARE_FRAME_CENTER_Y, 0);
+  camera.updateProjectionMatrix();
+  camera.updateMatrixWorld(true);
+  return camera;
+}
+
+interface SilhouetteShot {
+  image: AssetCompareImage;
+  mask: Uint8Array;
+}
+
+/**
+ * Compare an already-loaded asset model against an already-loaded reference:
+ * the shared capture core behind both the asset-path and entity entry
+ * points. Neither input is mutated (both are snapshotted).
+ */
+export function captureAssetComparePreview(
+  assetSource: THREE.Object3D,
+  refSource: THREE.Object3D,
+  options: AssetCompareOptions = {},
+): AssetCompareCapture {
+  const width = checkedDimension(options.width);
+  const height = checkedDimension(options.height);
+  const aspect = width / height;
+  const disposers: Array<() => void> = [];
+  let renderer: THREE.WebGLRenderer | null = null;
+  try {
+    const asset = buildNormalizedSubject(assetSource, readModelForward(assetSource));
+    disposers.push(asset.dispose);
+    const ref = buildNormalizedSubject(
+      refSource,
+      options.refForward ?? readModelForward(refSource),
+    );
+    disposers.push(ref.dispose);
+
+    const override = new THREE.MeshBasicMaterial({ color: SILHOUETTE_FOREGROUND });
+    disposers.push(() => override.dispose());
+    const sceneFor = (subject: THREE.Object3D): THREE.Scene => {
+      const scene = new THREE.Scene();
+      scene.background = new THREE.Color(SILHOUETTE_BACKGROUND);
+      scene.overrideMaterial = override;
+      scene.add(subject);
+      return scene;
+    };
+    const assetScene = sceneFor(asset.wrapper);
+    const refScene = sceneFor(ref.wrapper);
+
+    // Antialiasing off: silhouette masks want a crisp, deterministic
+    // coverage decision per pixel, not blended edge ramps.
+    const activeRenderer = markHostRenderer(
+      new THREE.WebGLRenderer({
+        antialias: false,
+        alpha: false,
+        preserveDrawingBuffer: true,
+      }),
+    );
+    renderer = activeRenderer;
+    activeRenderer.setPixelRatio(1);
+    activeRenderer.toneMapping = THREE.NoToneMapping;
+    activeRenderer.setClearColor(SILHOUETTE_BACKGROUND, 1);
+    activeRenderer.setSize(width, height, false);
+
+    const readCanvas = document.createElement('canvas');
+    readCanvas.width = width;
+    readCanvas.height = height;
+    const readContext = readCanvas.getContext('2d');
+    if (!readContext) throw new Error('Unable to create the compare readback canvas.');
+
+    const captureSilhouette = (
+      scene: THREE.Scene,
+      camera: THREE.Camera,
+      label: string,
+      view: AssetCompareView,
+    ): SilhouetteShot => {
+      activeRenderer.render(scene, camera);
+      readContext.clearRect(0, 0, width, height);
+      readContext.drawImage(activeRenderer.domElement, 0, 0);
+      const rgba = readContext.getImageData(0, 0, width, height).data;
+      const mask = silhouetteMaskFromRgba(rgba, width * height);
+      if (!mask.some((value) => value !== 0)) {
+        throw new Error(
+          `Compare ${view} view rendered an empty ${label} silhouette — nothing to score.`,
+        );
+      }
+      return {
+        image: { base64: pngBase64(readCanvas), mimeType: 'image/png' },
+        mask,
+      };
+    };
+
+    const overlayCanvas = document.createElement('canvas');
+    overlayCanvas.width = width;
+    overlayCanvas.height = height;
+    const overlayContext = overlayCanvas.getContext('2d');
+    if (!overlayContext) throw new Error('Unable to create the compare overlay canvas.');
+
+    const views: AssetCompareViewResult[] = [];
+    for (const view of ASSET_COMPARE_VIEWS) {
+      const camera = compareCamera(view, aspect);
+      const assetShot = captureSilhouette(assetScene, camera, 'asset', view);
+      const refShot = captureSilhouette(refScene, camera, 'reference', view);
+      const stats = maskIoU(assetShot.mask, refShot.mask);
+      overlayContext.putImageData(
+        new ImageData(overlayRgba(assetShot.mask, refShot.mask), width, height),
+        0,
+        0,
+      );
+      views.push({
+        view,
+        iou: stats.iou,
+        overlay: { base64: pngBase64(overlayCanvas), mimeType: 'image/png' },
+        asset: assetShot.image,
+        ref: refShot.image,
+      });
+    }
+    return { width, height, views };
+  } finally {
+    renderer?.dispose();
+    renderer?.forceContextLoss();
+    for (const dispose of disposers.reverse()) dispose();
+  }
+}
+
+/** The `--asset <path> --compare` entry point: loads the project GLB the
+ *  same bounded/validated way the other asset-path captures do, parses the
+ *  relayed reference GLB bytes, and scores them. */
+export async function captureModelComparePreview(
+  assetPath: string,
+  refGlbBase64: string,
+  options: AssetCompareOptions = {},
+): Promise<AssetCompareCapture> {
+  const model = await loadProjectAssetModel(assetPath);
+  try {
+    return await captureEntityComparePreview(model, refGlbBase64, options);
+  } finally {
+    disposeProjectAssetModel(model);
+  }
+}
+
+/** The `--entity <id> --compare` entry point (also the shared tail of the
+ *  asset-path leg): parses the reference and runs the capture core. */
+export async function captureEntityComparePreview(
+  entity: THREE.Object3D,
+  refGlbBase64: string,
+  options: AssetCompareOptions = {},
+): Promise<AssetCompareCapture> {
+  const refModel = await parseRefGlb(refGlbBase64);
+  try {
+    return captureAssetComparePreview(entity, refModel, options);
+  } finally {
+    disposeProjectAssetModel(refModel);
+  }
+}