@volter/editor-threejs 0.5.211 → 0.5.212

package/src/ecs/object-marks.ts

@@ -12,18 +12,14 @@ export type EditorHelperType =
   | 'cameras'
   | 'audio'
   | 'colliders'
-  // Joint anchor/axis/limit gizmos (W2a) — distinct from 'colliders' so the
-  // viewport's per-type visibility filter can toggle them independently.
+  // Joint anchor, axis and limit gizmos have their own visibility toggle, independent of colliders.
   | 'joints'
-  // LOD distance rings (W2b) — one ring per `mesh.lod` level, radius = the
-  // level's camera-distance threshold in world units.
+  // LOD distance rings use each level’s world-space camera-distance threshold as their radius.
   | 'lod'
   | 'splines'
-  // 'particles' tags the LIVE three.quarks emitter Object3D itself (so the
-  // editor's helper machinery skips disposing it); 'particle-shape' tags the
-  // editor's emitter-shape WIREFRAME (W1b) — they must stay distinct: sweeping
-  // "particles"-tagged children would detach the running emitter, and quarks
-  // self-disposes any system whose emitter leaves the scene.
+  // Keep live three.quarks emitters distinct from editor-owned particle-shape wireframes. The
+  // helper sweep must preserve emitters because quarks disposes a system whose emitter leaves the
+  // scene.
   | 'particles'
   | 'particle-shape'
   | 'pivot'
@@ -33,7 +29,7 @@ export type EditorHelperType =
   | 'trigger-volumes'
   | 'skeletons'
   // A package's own helper kind, shown through the editor's viewport door
-  // (the viewport door's `setViewportHelper`): the host lists the kinds it toggles by name,
+  // (through the viewport door): the host lists the kinds it toggles by name,
   // any other follows the master Helpers toggle.
   | (string & {});
 
@@ -43,8 +39,6 @@ export interface ObjectMarkSchema {
   skeletonEnabled: boolean;
   engineInternal: boolean;
   editorHelper: boolean;
-  volterComponentRoot: string;
-  volterBuiltInternal: boolean;
 }
 
 export const ObjectMarkKeys = {
@@ -53,8 +47,6 @@ export const ObjectMarkKeys = {
   skeletonEnabled: 'skeletonEnabled',
   engineInternal: 'engineInternal',
   editorHelper: 'editorHelper',
-  volterComponentRoot: 'volterComponentRoot',
-  volterBuiltInternal: 'volterBuiltInternal',
 } as const satisfies Record<keyof ObjectMarkSchema, string>;
 
 export function getObjectMark<K extends keyof ObjectMarkSchema>(

package/src/ecs/user-data.ts

@@ -1,113 +1,6 @@
-/**
- * Typed registry for `Object3D.userData` keys used by the engine and editor.
- *
- * Three.js lets any code stash arbitrary values on `object.userData`, and over
- * time the engine + editor accumulated ~20 stringly-typed keys that together
- * form a *parallel object model* — meaning carried entirely in undocumented
- * string literals. This module is the ONE documented place that lists every
- * such key, its value type, and what it means. All engine/editor-internal
- * `userData` access for these keys must go through {@link getUserData} /
- * {@link setUserData} / {@link hasUserData} / {@link deleteUserData} so the key
- * strings live in exactly one place and are type-checked at every call site.
- * Structural readers may use the narrow `object-marks` accessors instead;
- * this registry includes that module's canonical keys and value schema.
- *
- * NOTE: This covers engine/editor *internal* keys only. User game code in the
- * example template may stash its own ad-hoc keys; those are out of scope.
- *
- * ## Key reference
- *
- * Serialization / identity (load-bearing — editor identity):
- * - `entityId`            — the entity's stable string id. Presence also marks an
- *                           Object3D as a "real" entity (vs editor helper/env object).
- *
- * Runtime scene-query metadata (read by `scene-query.ts` and `scene-index.ts`):
- * - `tags`                — string[] tags for `queryByTag` and the live index.
- * - `attributes`          — per-object `Record<string, string|number|boolean>`
- *                           of game-defined attributes (P2 `observe`). Written
- *                           through `SceneIndex.setAttribute`, which emits an
- *                           `attributechanged` signal; JSON-simple values only,
- *                           so an attribute survives serialization unchanged.
- *
- * Runtime gameplay metadata:
- * - `forward`             — `[x,y,z]` model-space visual forward exported as
- *                           ordinary glTF extras for asset-facing validation.
- * - `navRole`             — `'walkable' | 'obstacle'` navmesh role; collected at runtime.
- * - `pivot`              — `[x,y,z]` local-space pivot for rotate/scale-around-pivot.
- * - `splineCurve`         — resolved THREE curve for a spline-following object.
- * - `_camera`             — THREE.Camera owned by a camera entity (collected on load).
- * - `_particleSystem`     — three.quarks ParticleSystem (scene-sync registration + census).
- * - `gaussianSplat`       — native Spark splat metadata used for renderer discovery,
- *                           inspector facts, bounds, and deterministic disposal.
- *
- * Disposal contract:
- * - `__sharedGeometry`    — `true` when a mesh's geometry is shared/cached and MUST
- *                           NOT be disposed by per-object cleanup (P0.2 contract).
- *
- * Editor shading overrides (editor-only, see `scene-sync.ts`):
- * - `__shadeOrig`         — original material(s) stashed before a shading override.
- * - `__shadeUnlit`        — generated unlit material(s) for the unlit view mode.
- *
- * Unmodified-game ingestion (editor-only, see `editor/src/ingest/`):
- * - `__ingest`            — `true` on every Object3D minted by ingestion; routes
- *                           edits to live mutation.
- * - `__ingestNextId`      — monotonic id counter stashed on the captured Scene
- *                           root so re-reflects keep minting unique ids.
- *
- * Editor scene-graph tagging (editor-only):
- * - `engineInternal`      — `true` on engine-owned infrastructure in the game scene
- *                           (particle BatchedRenderer, debug-draw + its subtree).
- *                           The editor's play-mode hierarchy skips these so they
- *                           don't show up as selectable "entities".
- * - `authoringRoot`       — explicit opt-in for a runtime descendant to become
- *                           its own authoring object instead of a part of the
- *                           nearest ancestor owner.
- * - `authoringInstance`   — source OID of the custom-component callsite that
- *                           rendered this existing Object3D. Used to group
- *                           implementation parts without adding wrappers.
- * - `authoringLabel`      — authored literal name (or component tag fallback)
- *                           for that source-backed component instance.
- * - `authoringComponent`  — exact source component identity for portable-CSF
- *                           association; unlike the label, never user-facing copy.
- * - `authoringDocument`   — generic reference to the project-tool document
- *                           that owns this scene instance's authored asset.
- * - `authoringHierarchyId`, `authoringHierarchyParentId`,
- *   `authoringHierarchyOrder` — source-owned semantic identity, parent identity,
- *                           and sibling ordinal shared across native surfaces.
- * - `editorHelper`        — `true` for editor-only helper objects (gizmos, wireframes).
- *
- * Hierarchy-presentation convention (written by GAME code, read by the editor —
- * see `../adapter/hierarchy-marks.ts`, which is the ONLY place these two are
- * read/written from; the `volter` prefix marks them as the HOST's namespace on a
- * node a game owns, unlike every other key above, which the engine/editor also
- * write):
- * - `volterComponentRoot`   — display name of the component instance this subtree
- *                           IS. The node renders as one collapsed, expandable
- *                           row named for it.
- * - `volterBuiltInternal`   — `true` on the ROOT of a subtree runtime code
- *                           CONSTRUCTED rather than authored (skeleton bones,
- *                           particle renderers). Subtree-scoped: everything
- *                           below a marked node is built-internal too.
- * - `editorHelperType`    — which kind of helper (lights/particles/pivot/navmesh/...).
- * - `editorIcon`          — `true` for editor billboard icon sprites.
- * - `skeletonVisible`     — per-entity editor preference for its bone overlay.
- * - `skeletonEnabled`     — resolved visibility preference on a skeleton helper.
- * - `envObject`           — `true` for environment objects (ambient light, etc.).
- * - `reflectionProbe`     — live project-owned reflection probe projected from
- *                           JSX props for renderer/editor integration.
- * - `triggerVolume`       — plain `{ radius }` a GAME writes on the node that IS
- *                           a trigger volume, so the editor can draw its ring
- *                           (see `../adapter/trigger-volume.ts`).
- * - `constraints`         — live project-owned spatial constraints projected
- *                           into the shared Inspector and viewport.
- * - `authoringSubject`    — transient identity/inspection for an ecosystem-native
- *                           subject represented by an Object3D proxy.
- * - `splineControlPoint`  — index of a spline control-point drag handle.
- * - `vcDirIdx`            — view-cube face direction index (0=+X,1=-X,2=+Y,...).
- */
+/** Typed Object3D.userData keys shared by the engine and editor. Internal accesses use getUserData, setUserData and hasUserData; structural consumers may use object-marks accessors. Project-defined extras remain outside this registry. */
 
 import type * as THREE from 'three';
-import type { ParticleSystem } from 'three.quarks';
 import type { ConstraintMark } from '../adapter/constraint';
 import type { Object3DAuthoringSubjectMark } from '../adapter/object3d-authoring-subject';
 import type { ReflectionProbeMark } from '../adapter/reflection-probe';
@@ -125,27 +18,14 @@ export interface UserDataSchema extends ObjectMarkSchema {
   forward: [number, number, number];
   tags: string[];
   attributes: Record<string, string | number | boolean>;
-  navRole: 'walkable' | 'obstacle';
   pivot: [number, number, number];
-  splineCurve: THREE.Curve<THREE.Vector3>;
-  splineControlPoint: number;
   _camera: THREE.Camera;
-  _particleSystem: ParticleSystem;
   gaussianSplat: { src: string; numSplats: number };
-  __sharedGeometry: boolean;
-  __shadeOrig: THREE.Material | THREE.Material[];
-  __shadeUnlit: THREE.Material[];
   __ingest: boolean;
-  __ingestNextId: number;
   authoringRoot: boolean;
   authoringInstance: string;
   authoringLabel: string;
   authoringComponent: string;
-  authoringDocument: {
-    readonly kind: 'project-tool';
-    readonly name: string;
-    readonly title: string;
-  };
   /** Project-owned identity used to join authored hierarchy rows across adapter roots. */
   authoringHierarchyId: string;
   /** Project-owned parent identity when the authored parent can live on another surface. */
@@ -165,9 +45,8 @@ export interface UserDataSchema extends ObjectMarkSchema {
 export type UserDataKey = keyof UserDataSchema;
 
 /**
- * Canonical name → literal `userData` string key. The accessor names match the
- * raw string keys 1:1 (this is the documented set referenced by the AC), so the
- * literal strings are owned here or by the included structural mark registry.
+ * Canonical accessor names map to literal userData keys owned here or by the structural mark
+ * registry.
  */
 export const UserDataKeys = {
   ...ObjectMarkKeys,
@@ -175,23 +54,14 @@ export const UserDataKeys = {
   forward: 'forward',
   tags: 'tags',
   attributes: 'attributes',
-  navRole: 'navRole',
   pivot: 'pivot',
-  splineCurve: 'splineCurve',
-  splineControlPoint: 'splineControlPoint',
   _camera: '_camera',
-  _particleSystem: '_particleSystem',
   gaussianSplat: 'gaussianSplat',
-  __sharedGeometry: '__sharedGeometry',
-  __shadeOrig: '__shadeOrig',
-  __shadeUnlit: '__shadeUnlit',
   __ingest: '__ingest',
-  __ingestNextId: '__ingestNextId',
   authoringRoot: 'authoringRoot',
   authoringInstance: 'authoringInstance',
   authoringLabel: 'authoringLabel',
   authoringComponent: 'authoringComponent',
-  authoringDocument: 'authoringDocument',
   authoringHierarchyId: 'authoringHierarchyId',
   authoringHierarchyParentId: 'authoringHierarchyParentId',
   authoringHierarchyOrder: 'authoringHierarchyOrder',
@@ -228,8 +98,3 @@ export function setUserData<K extends UserDataKey>(
 export function hasUserData(obj: THREE.Object3D | null | undefined, key: UserDataKey): boolean {
   return obj ? obj.userData[UserDataKeys[key]] !== undefined : false;
 }
-
-/** Remove a `userData` key. */
-export function deleteUserData(obj: THREE.Object3D, key: UserDataKey): void {
-  delete obj.userData[UserDataKeys[key]];
-}

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

@@ -1,33 +1,13 @@
 /**
- * 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.
+ * Stage-transport subjects for three.js animation. Discover object.animations and
+ * liveMixerFor(object): standalone clip arrays get a new AnimationMixer, while a mixer owned by
+ * the world is borrowed. GLTFLoader does not assign scene.animations, so live mixer discovery also
+ * reaches clips loaded through useGLTF and useAnimations. Subjects seek through
+ * AnimationMixer.setTime; the transport owns playback position.
  */
 import { liveMixerFor, subscribeLiveMixers } from '@volter/editor-threejs/animation/live-mixers';
 import * as THREE from 'three';
-import type { StageTransport } from '@volter/sdk/kit/animation/stage-transport';
+import type { StageTransport } from '@volter/sdk/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
@@ -51,8 +31,9 @@ function attachOwnClips(object: THREE.Object3D, transport: StageTransport): (()
   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 initial = clips[0];
+  if (!initial) return null;
+  let current: THREE.AnimationClip = initial;
 
   const show = (clip: THREE.AnimationClip): void => {
     mixer.stopAllAction();
@@ -66,9 +47,9 @@ function attachOwnClips(object: THREE.Object3D, transport: StageTransport): (()
   const detach = transport.attach({
     id: object.uuid,
     label: object.name || current.name || 'Clip',
-    range: () => ({ start: 0, end: current?.duration ?? 0, fps: THREE_DISPLAY_FPS }),
+    range: () => ({ start: 0, end: current.duration, fps: THREE_DISPLAY_FPS }),
     seek: (seconds) => {
-      mixer.setTime(clamp(seconds, 0, current?.duration ?? 0));
+      mixer.setTime(clamp(seconds, 0, current.duration));
     },
     clips: () => clips.map((clip) => ({ id: clip.name, label: clip.name })),
     setClip: (id) => {
@@ -91,8 +72,9 @@ function attachOwnClips(object: THREE.Object3D, transport: StageTransport): (()
 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 initial = inspection.clips.values().next().value;
+  if (!initial) return null;
+  let current: THREE.AnimationClip = initial;
 
   const show = (clip: THREE.AnimationClip): void => {
     inspection.mixer.stopAllAction();
@@ -105,9 +87,9 @@ function attachInspected(object: THREE.Object3D, transport: StageTransport): (()
   const detach = transport.attach({
     id: object.uuid,
     label: object.name || current.name || 'Animation',
-    range: () => ({ start: 0, end: current?.duration ?? 0, fps: THREE_DISPLAY_FPS }),
+    range: () => ({ start: 0, end: current.duration, fps: THREE_DISPLAY_FPS }),
     seek: (seconds) => {
-      inspection.mixer.setTime(clamp(seconds, 0, current?.duration ?? 0));
+      inspection.mixer.setTime(clamp(seconds, 0, current.duration));
     },
     clips: () => [...inspection.clips.entries()].map(([name, clip]) => ({ id: name, label: clip.name || name })),
     setClip: (id) => {
@@ -140,8 +122,8 @@ 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;
+    /** Rescan when the game registers or drops a mixer. */
+    readonly rescanOnLiveMixers?: boolean;
   } = {},
 ): ClipSubjectScan {
   const attached = new Map<string, () => void>();
@@ -172,12 +154,7 @@ export function scanClipSubjects(
   };
 
   refresh();
-  const rescanWhen = options.rescanOnLiveMixers;
-  const stopMixers = rescanWhen
-    ? subscribeLiveMixers(() => {
-        if (rescanWhen()) refresh();
-      })
-    : () => {};
+  const stopMixers = options.rescanOnLiveMixers ? subscribeLiveMixers(refresh) : () => {};
 
   return {
     refresh,

package/src/kit/asset-compare-core.ts

@@ -0,0 +1,161 @@
+
+
+export const ASSET_COMPARE_VIEWS = ['front', 'side'] as const;
+export type AssetCompareView = (typeof ASSET_COMPARE_VIEWS)[number];
+
+/** Both models are scaled to this height, feet at y=0, centered on x=z=0. */
+export const COMPARE_TARGET_HEIGHT = 1;
+/**
+ * Fixed orthographic half-height around the model’s mid-height, with a 10% margin for reproducible
+ * silhouette comparisons.
+ */
+export const COMPARE_FRAME_HALF_HEIGHT = 0.55;
+export const COMPARE_FRAME_CENTER_Y = COMPARE_TARGET_HEIGHT / 2;
+
+/** Silhouettes render as a flat unlit white override on solid black, so the
+ *  mask threshold sits mid-range — antialiased edge pixels land on the side
+ *  of the ramp they dominate. */
+export const SILHOUETTE_LUMA_THRESHOLD = 128;
+
+/** Overlay legend (RGB). The overlay is machine-generated review evidence:
+ *  every pixel is exactly one of these four colors. */
+export const OVERLAY_BACKGROUND_RGB = [24, 26, 31] as const;
+export const OVERLAY_ASSET_ONLY_RGB = [235, 137, 52] as const; // orange — the asset under test
+export const OVERLAY_REF_ONLY_RGB = [56, 189, 248] as const; // cyan — the reference
+export const OVERLAY_OVERLAP_RGB = [236, 240, 238] as const; // near-white — agreement
+
+/**
+ * Binary silhouette mask from RGBA pixels of a white-on-black render: a
+ * pixel belongs to the silhouette when any color channel crosses the
+ * threshold. Returns one byte (0|1) per pixel.
+ */
+export function silhouetteMaskFromRgba(rgba: ArrayLike<number>, pixelCount: number): Uint8Array {
+  if (rgba.length < pixelCount * 4) {
+    throw new Error(
+      `Silhouette mask expected ${pixelCount * 4} RGBA bytes but received ${rgba.length}.`,
+    );
+  }
+  const mask = new Uint8Array(pixelCount);
+  for (let pixel = 0; pixel < pixelCount; pixel++) {
+    const offset = pixel * 4;
+    const value =
+      rgba[offset]! >= SILHOUETTE_LUMA_THRESHOLD ||
+      rgba[offset + 1]! >= SILHOUETTE_LUMA_THRESHOLD ||
+      rgba[offset + 2]! >= SILHOUETTE_LUMA_THRESHOLD;
+    mask[pixel] = value ? 1 : 0;
+  }
+  return mask;
+}
+
+export interface MaskOverlapStats {
+  intersection: number;
+  union: number;
+  aCount: number;
+  bCount: number;
+  /** intersection / union; 0 when the union is empty (guard emptiness upstream). */
+  iou: number;
+}
+
+/** Silhouette intersection-over-union between two same-length binary masks. */
+export function maskIoU(a: Uint8Array, b: Uint8Array): MaskOverlapStats {
+  if (a.length !== b.length) {
+    throw new Error(`Mask IoU requires equal-size masks (${a.length} vs ${b.length}).`);
+  }
+  let intersection = 0;
+  let aCount = 0;
+  let bCount = 0;
+  for (let index = 0; index < a.length; index++) {
+    const inA = a[index] !== 0;
+    const inB = b[index] !== 0;
+    if (inA) aCount++;
+    if (inB) bCount++;
+    if (inA && inB) intersection++;
+  }
+  const union = aCount + bCount - intersection;
+  return { intersection, union, aCount, bCount, iou: union === 0 ? 0 : intersection / union };
+}
+
+/**
+ * The compare overlay: both silhouettes on one image in visibly distinct
+ * colors — asset-only orange, reference-only cyan, agreement near-white on a
+ * dark background. Returns opaque RGBA bytes ready for an ImageData.
+ */
+export function overlayRgba(
+  assetMask: Uint8Array,
+  refMask: Uint8Array,
+): Uint8ClampedArray<ArrayBuffer> {
+  if (assetMask.length !== refMask.length) {
+    throw new Error(
+      `Overlay requires equal-size masks (${assetMask.length} vs ${refMask.length}).`,
+    );
+  }
+  const out = new Uint8ClampedArray(assetMask.length * 4);
+  for (let pixel = 0; pixel < assetMask.length; pixel++) {
+    const inAsset = assetMask[pixel] !== 0;
+    const inRef = refMask[pixel] !== 0;
+    const color =
+      inAsset && inRef
+        ? OVERLAY_OVERLAP_RGB
+        : inAsset
+          ? OVERLAY_ASSET_ONLY_RGB
+          : inRef
+            ? OVERLAY_REF_ONLY_RGB
+            : OVERLAY_BACKGROUND_RGB;
+    const offset = pixel * 4;
+    out[offset] = color[0];
+    out[offset + 1] = color[1];
+    out[offset + 2] = color[2];
+    out[offset + 3] = 255;
+  }
+  return out;
+}
+
+/** A structurally valid forward vector ([x,y,z], finite, non-degenerate in
+ *  the ground plane) or null — used to read GLB `extras`/`userData.forward`
+ *  without trusting arbitrary content. */
+export function parseForwardVector(value: unknown): [number, number, number] | null {
+  if (!Array.isArray(value) || value.length !== 3) return null;
+  const [x, y, z] = value as unknown[];
+  if (typeof x !== 'number' || typeof y !== 'number' || typeof z !== 'number') return null;
+  if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) return null;
+  if (Math.hypot(x, z) < 1e-6) return null; // vertical/zero forward cannot define a facing
+  return [x, y, z];
+}
+
+/**
+ * The Y rotation (radians) that turns a model whose forward is `forward`
+ * to face +Z — the direction the fixed front camera looks from. Facing is a
+ * ground-plane property; the vector's y component is ignored.
+ */
+export function forwardYawRadians(forward: readonly [number, number, number]): number {
+  const [x, , z] = forward;
+  if (!Number.isFinite(x) || !Number.isFinite(z) || Math.hypot(x, z) < 1e-6) {
+    throw new Error(`Cannot derive a facing from forward vector [${forward.join(', ')}].`);
+  }
+  return Math.atan2(x, z);
+}
+
+export interface NormalizedPlacement {
+  scale: number;
+  /** Applied AFTER the scale: ground at y=0, footprint centered at x=z=0. */
+  position: [number, number, number];
+}
+
+/**
+ * Bounding-box height normalization (the decided compare framing): scale the
+ * model so its bounds stand `COMPARE_TARGET_HEIGHT` tall, then place it with its
+ * ground plane at y=0 and its bounds center on the x=0/z=0 axis.
+ */
+export function normalizedPlacement(
+  min: readonly [number, number, number],
+  max: readonly [number, number, number],
+): NormalizedPlacement {
+  const height = max[1] - min[1];
+  if (!Number.isFinite(height) || height <= 0) {
+    throw new Error(`Compare normalization needs positive model height, got ${height}.`);
+  }
+  const scale = COMPARE_TARGET_HEIGHT / height;
+  const centerX = (min[0] + max[0]) / 2;
+  const centerZ = (min[2] + max[2]) / 2;
+  return { scale, position: [-centerX * scale, -min[1] * scale, -centerZ * scale] };
+}

package/src/kit/asset-compare.ts

@@ -1,23 +1,9 @@
 /**
- * B8.4 — the Asset Lab COMPARE surface (the editor's `screenshot <model.glb>
- * --compare <ref.glb>` command): 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).
+ * Asset Lab comparison capture for screenshot --compare: load an asset and reference GLB, normalize
+ * their height and forward direction, capture matched orthographic front and side views, and
+ * compose silhouette IoU scores and overlays. Bounding-box framing supports arbitrary rigs.
+ * asset-compare-core.ts owns the scoring math; this module owns loading, scene assembly and WebGL
+ * capture.
  */
 
 import { markHostRenderer } from '@volter/editor-threejs/viewport/renderer-ownership';
@@ -32,7 +18,7 @@ import {
   normalizedPlacement,
   overlayRgba,
   silhouetteMaskFromRgba,
-} from '@volter/sdk/kit/asset-compare-core';
+} from './asset-compare-core';
 import {
   checkedDimension,
   createAssetPreviewSnapshot,
@@ -45,10 +31,7 @@ import {
   readModelForward,
 } from './asset-preview';
 
-export type { AssetCompareView } from '@volter/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 type { AssetCompareView } from './asset-compare-core';
 
 export interface AssetCompareImage {
   base64: string;
@@ -85,9 +68,7 @@ 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. */
+/** Parse the reference GLB using comparison-specific error wording. */
 function parseRefGlb(base64: string): Promise<THREE.Object3D> {
   return parseGlbBytesModel(base64, 'Compare reference GLB');
 }

package/src/kit/asset-preview-command.ts

@@ -5,7 +5,7 @@
  * viewport's relay verbs (`viewport-commands.ts`).
  */
 import type { EditorCommandMessage, EditorCommandResult } from '@volter/sdk/commands';
-import { parseForwardVector } from '@volter/sdk/kit/asset-compare-core';
+import { parseForwardVector } from './asset-compare-core';
 import { captureEntityComparePreview, captureModelComparePreview } from './asset-compare';
 import {
   type AssetPreviewBackground,
@@ -20,8 +20,8 @@ import {
   captureSourceReviewShotSetModelPreview,
   parseShotSetDefinition,
 } from './asset-preview';
-import { activeDocumentAuthoring } from '@volter/sdk/kit/authoring/shell-document-ops';
-import { parseCameraChoice, parsePoseChoice } from '@volter/sdk/kit/capture-camera-pose';
+import { activeDocumentAuthoring } from '@volter/sdk/authoring/shell-document-ops';
+import { parseCameraChoice, parsePoseChoice } from './capture-camera-pose';
 import type { EditorShellStore } from './editor-shell-store';
 import { entityObject3D } from './entity-object';
 
@@ -32,9 +32,8 @@ export async function handleAssetPreviewCommand(
   const assetPath = cmd['assetPath'];
   const entityId = cmd['entityId'];
   // The THIRD source: a GLB that travels IN the command rather than being
-  // fetched or looked up — the module-look lane (`project.bake.preview`)
-  // builds an Object3D in Node, where there is no GPU, and hands the editor
-  // the exported bytes. Counted rather than XOR-ed because there are now more
+  // fetched or looked up — a Node caller that built an Object3D, where there
+  // is no GPU, hands the editor the exported bytes. Counted rather than XOR-ed because there are now more
   // than two sources and "exactly one" has to stay exactly one.
   const glbBase64 = cmd['glbBase64'];
   const sourceCount =
@@ -97,9 +96,8 @@ export async function handleAssetPreviewCommand(
         'definition, compare, or stage "scene" — those legs stage their own cameras and poses.',
     };
   }
-  // A project-defined labeled shot set travels WITH the command (the CLI
-  // resolves `--shots <set>` through the registered
-  // `project.<set>.previewShots` tool); validate the untrusted
+  // A caller-defined labeled shot set travels WITH the command (`live`'s
+  // `assetPreviewShots`); validate the untrusted
   // definition at the relay boundary so a malformed contribution fails with
   // a named reason instead of a deep three.js error.
   let shotSetDefinition: ReturnType<typeof parseShotSetDefinition> | undefined;
@@ -114,11 +112,11 @@ export async function handleAssetPreviewCommand(
   if (shots === 'source' && parsedForward === null) {
     return {
       ok: false,
-      error: 'capture-asset-preview --shots source requires a non-degenerate forward [x,y,z].',
+      error: 'capture-asset-preview shots "source" requires a non-degenerate forward [x,y,z].',
     };
   }
   if (compare !== undefined) {
-    // B8.4 — the compare mode (the editor's `screenshot <model.glb> --compare <ref.glb>` command).
+    // Compare mode serves the editor's `screenshot <model.glb> --compare <ref.glb>` command.
     // Validated here at the relay boundary so a malformed payload fails with
     // a named reason instead of a deep three.js error.
     if (shots !== undefined || shotSetDefinition !== undefined) {
@@ -142,8 +140,8 @@ export async function handleAssetPreviewCommand(
   // Wire-carried GLB bytes stand NOWHERE, so they take no scene stage and no
   // compare (whose reference is named some other way). An explicit `shotSet`
   // definition is a different matter and is served: a shot set stages the
-  // subject itself, which is what lets the editor's `screenshot <module> --orbit <n>` command
-  // circle a model that only ever existed as bytes. `shots: 'source'` stays
+  // subject itself, which is what lets a caller circle a model that only
+  // ever existed as bytes. `shots: 'source'` stays
   // out — it is the asset-path review set, keyed to a stored forward vector.
   if (typeof glbBase64 === 'string') {
     if (shots !== undefined || compare !== undefined) {
@@ -191,12 +189,9 @@ export async function handleAssetPreviewCommand(
       };
     }
   }
-  // Resolve the screenshot subject through the SAME active-document adapter
-  // that produced `status.entities`, drives Hierarchy/Inspector selection and
-  // answers `frame-entity`. An adopted Play scene can own a stable OID in its
-  // projection without publishing that object through the shell's edit-mode
-  // `objectMap`; checking the map alone made the final door reject an id every
-  // preceding door had just accepted.
+  // Resolve screenshot subjects through the active-document adapter used by status, Hierarchy,
+  // Inspector and frame-entity. An adopted scene’s projected ids need not appear in the shell’s
+  // edit-mode object map.
   const entityObject =
     typeof entityId === 'string'
       ? entityObject3D(activeDocumentAuthoring(store.shell), store.objectMap, entityId)