@volter/editor-threejs 0.5.211 → 0.5.212

package/src/kit/asset-preview.ts

@@ -13,12 +13,11 @@ import type {
 } from '@volter/sdk';
 import { EDITOR_LAYER, isEditorOwnedObject } from '@volter/editor-threejs/viewport/editor-layers';
 import { markHostRenderer } from '@volter/editor-threejs/viewport/renderer-ownership';
-import { isBuiltInternal } from '@volter/editor-threejs/adapter/hierarchy-marks';
 import { loadSplat } from '@volter/editor-threejs/asset-loaders';
 import { hasUserData } from '@volter/editor-threejs/ecs/user-data';
 import { gltfLoader } from '@volter/editor-threejs/loader';
 import * as THREE from 'three';
-import { forwardYawRadians, parseForwardVector } from '@volter/sdk/kit/asset-compare-core';
+import { forwardYawRadians, parseForwardVector } from './asset-compare-core';
 import {
   ASSET_PREVIEW_PADDING,
   boneZoomCenter,
@@ -39,37 +38,22 @@ import {
   turntableViewBasis,
   unionOrthographicFrames,
 } from './asset-preview-framing';
-import { drawBitmapLabel, measureBitmapLabel } from '@volter/sdk/kit/bitmap-label';
+import { drawBitmapLabel, measureBitmapLabel } from '@volter/sdk/bitmap-label';
 import {
   applyStudioEnvironment,
   disposeStudioEnvironment,
   STUDIO_AMBIENT_WITH_ENVIRONMENT,
 } from './three-viewport/studio-environment';
 
-export const ASSET_PREVIEW_VIEWS = ['front', 'right', 'top', 'perspective'] as const;
-export type AssetPreviewView = (typeof ASSET_PREVIEW_VIEWS)[number];
+const ASSET_PREVIEW_VIEWS = ['front', 'right', 'top', 'perspective'] as const;
+type AssetPreviewView = (typeof ASSET_PREVIEW_VIEWS)[number];
 export type AssetPreviewBackground = 'neutral' | 'transparent';
 
-/**
- * Where an ENTITY capture is staged.
- *
- * `'lab'` — the neutral Asset Lab stage {@link captureObjectAssetPreview}
- * renders: an isolated, yaw-normalized snapshot under fixed studio lighting,
- * identical whatever the entity's surroundings are. It is the default
- * everywhere.
- *
- * `'scene'` — {@link captureSceneStageAssetPreview}: the entity photographed
- * WHERE IT STANDS, in the live scene, under the scene's own lighting, with
- * the editor's own furniture excluded. Entity captures only — a model loaded
- * from an asset path does not stand anywhere.
- */
-export type AssetPreviewStage = 'lab' | 'scene';
-
-export interface AssetPreviewOptions {
+interface AssetPreviewOptions {
   width?: number;
   height?: number;
   background?: AssetPreviewBackground;
-  /** ONE view from a chosen angle instead of the fixed four — see the SDK's
+  /** ONE view from a chosen angle instead of the fixed view sheet — see the SDK's
    *  {@link AssetPreviewCameraChoice} for the angle conventions. */
   camera?: AssetPreviewCameraChoice;
   /** Sample a named clip at a time on the capture's disposable snapshot
@@ -77,7 +61,7 @@ export interface AssetPreviewOptions {
   pose?: AssetPreviewPose;
 }
 
-export interface AssetPreviewImage {
+interface AssetPreviewImage {
   /** One of the four fixed views, or `below` — the underside tile the lab
    *  stage adds to its sheet (a cap's gills, a barrel's floor). */
   view: AssetPreviewView | 'below';
@@ -85,26 +69,15 @@ export interface AssetPreviewImage {
   mimeType: 'image/png';
 }
 
-/**
- * How the captured subject was oriented relative to its AUTHORED coordinates.
- *
- * `faceFrontSubject` yaw-normalizes a subject so the fixed front camera
- * photographs its declared front. For a rig persisting `forward = [0,0,-1]`
- * that is a PI yaw — correct photography whose projection maps authored +X to
- * screen-LEFT in the front view. Applied silently, that read as "the front
- * view mirrors world X" and cost a cold-round agent its geometry reasoning
- * (round #4, 2026-08-30), so the yaw is now REPORTED here and stamped onto
- * the sheet's own pixels ({@link renderFourViewCapture}'s axis markers) —
- * never inferred, never silent.
- */
-export interface AssetPreviewOrientation {
+/** The yaw applied to align the captured subject’s authored forward with the front camera, also printed on the sheet’s axis markers. */
+interface AssetPreviewOrientation {
   /** The subject's declared forward, `[0,0,1]` when it declares none. */
   forward: [number, number, number];
   /** Yaw applied to face the front camera; 0 means authored axes = world axes. */
   yawDegrees: number;
 }
 
-export interface AssetPreviewCapture {
+interface AssetPreviewCapture {
   width: number;
   height: number;
   orientation: AssetPreviewOrientation;
@@ -117,33 +90,12 @@ export interface AssetPreviewCapture {
   };
 }
 
-export interface AssetPreviewFraming {
+interface AssetPreviewFraming {
   center: THREE.Vector3;
   size: THREE.Vector3;
   radius: number;
 }
 
-/**
- * The shot-set contract is declared ONCE, in `@volter/sdk`
- * (`packages/sdk/src/types.ts`), because it crosses the editor relay:
- * a capability tool authors a set, the CLI carries it over, and THIS module is
- * the generic capture engine that renders it. Importing rather than
- * re-declaring is what makes `parseShotSetDefinition`'s return annotation
- * below a real drift check against the wire type — see the SDK block's own
- * comment for the contract and for what a pose step's `radians` is measured
- * from.
- */
-export type {
-  AssetPreviewShotSetDefinition,
-  AssetPreviewShotWarning,
-  LabeledShotSetCapture,
-  ShotSetPoseMorph,
-  ShotSetPoseRotation,
-  ShotSetPoseStep,
-  ShotSetPoseTranslation,
-  ShotSetShot,
-} from '@volter/sdk';
-
 /** Definitions cross the editor relay as untyped JSON from project-registered
  *  tools; capped so one capture stays within the relay's request budget. */
 const MAX_SHOT_SET_SHOTS = 24;
@@ -259,8 +211,8 @@ export function parseShotSetDefinition(value: unknown): AssetPreviewShotSetDefin
   for (const [poseName, steps] of Object.entries(poses)) {
     if (!Array.isArray(steps) || !steps.every(isPoseStep)) {
       fail(
-        `pose ${JSON.stringify(poseName)} must be an array of {bone, axis, radians} ` +
-          'and/or {morph, influence}.',
+        `pose ${JSON.stringify(poseName)} must be an array of {bone, axis, radians}, ` +
+          '{bone, axis, meters}, and/or {morph, influence}.',
       );
     }
   }
@@ -289,17 +241,15 @@ export function parseShotSetDefinition(value: unknown): AssetPreviewShotSetDefin
   return definition as AssetPreviewShotSetDefinition;
 }
 
-export const SOURCE_REVIEW_SHOT_LABELS = [
-  'front',
-  'back',
-  'left',
-  'right',
-  'quarter-left',
-  'quarter-right',
-] as const;
-export type SourceReviewShotLabel = (typeof SOURCE_REVIEW_SHOT_LABELS)[number];
+type SourceReviewShotLabel =
+  | 'front'
+  | 'back'
+  | 'left'
+  | 'right'
+  | 'quarter-left'
+  | 'quarter-right';
 
-export interface SourceReviewShotSetCapture {
+interface SourceReviewShotSetCapture {
   width: number;
   height: number;
   shots: Array<{ label: SourceReviewShotLabel; base64: string; mimeType: 'image/png' }>;
@@ -318,8 +268,6 @@ type MorphableObject = THREE.Object3D & {
 
 const DEFAULT_SIZE = 512;
 const MIN_SIZE = 64;
-// Four views plus the 2x2 sheet cross the editor relay as base64 JSON. At
-// 1024px even incompressible RGBA data remains below its 50 MB request limit.
 const MAX_SIZE = 1024;
 const NEUTRAL_COLOR = 0x20242a;
 const MODEL_FETCH_TIMEOUT_MS = 25_000;
@@ -335,21 +283,12 @@ export function checkedDimension(value: number | undefined): number {
 
 export function pngBase64(canvas: HTMLCanvasElement): string {
   const dataUrl = canvas.toDataURL('image/png');
-  const comma = dataUrl.indexOf(',');
-  return comma >= 0 ? dataUrl.slice(comma + 1) : dataUrl;
+  return dataUrl.slice(dataUrl.indexOf(',') + 1);
 }
 
 /**
- * The node a preview must snapshot for `object`: itself, unless a SkinnedMesh
- * under it binds to bones OUTSIDE it — then the nearest ancestor that owns
- * both the mesh and every bone, the skeleton root the refusal in
- * `resolveExternalBones` names. A skinned mesh sits BESIDE its Armature in
- * three's own glTF layout (`Scene > [SkinnedMesh, Armature > bones]`), so a
- * click on a character lands on the mesh, and the mesh alone cannot be drawn
- * without the bones that pose it: every Humanoid exhibit's Inspector preview
- * was the red refusal listing all 68 bones (runhuman pass 143; traced live —
- * selecting the rig root renders a clean bind pose). A bone whose chain never
- * meets `object`'s stays external, so the honest refusal still fires there.
+ * Choose an ancestor containing the selected object and its referenced bones where their
+ * hierarchies meet. Unrelated bones remain external for resolveExternalBones to refuse.
  */
 export function assetPreviewSubject(object: THREE.Object3D): THREE.Object3D {
   const inside = new Set<THREE.Object3D>();
@@ -386,14 +325,10 @@ export function assetPreviewSubject(object: THREE.Object3D): THREE.Object3D {
  * snapshot shares immutable geometry/material resources.
  */
 export function createAssetPreviewSnapshot(source: THREE.Object3D): THREE.Object3D {
-  // A skinned mesh can point at bones that are not in the selected subtree —
-  // in practice because the model was duplicated with `Object3D.clone()`
-  // instead of `SkeletonUtils.clone()`, which copies the bone nodes but leaves
-  // every clone's `skeleton` referencing the ORIGINAL bones. Where the subtree
-  // owns a same-named bone for each of them (it does for exactly that mount),
-  // the snapshot binds to its own copies — the pose those copies carry is the
-  // one the mount intended. Anything left unresolved is refused BY NAME below,
-  // because binding to a bone that is not there would be an invented pose.
+  // A skinned mesh can reference bones outside the selected subtree. Resolve
+  // each reference to an unambiguous same-named bone owned by the subtree, then
+  // bind the snapshot to its own copy of that pose. Unresolved references are
+  // refused by name rather than inventing a pose from absent bones.
   const sourceNodes = new Set<THREE.Object3D>();
   source.traverse((object) => {
     sourceNodes.add(object);
@@ -415,13 +350,6 @@ export function createAssetPreviewSnapshot(source: THREE.Object3D): THREE.Object
   // scene; descendant visibility remains authored and the source is untouched.
   snapshot.visible = true;
 
-  // Editor-only helpers are presentation siblings/children, never asset data.
-  const helpers: THREE.Object3D[] = [];
-  snapshot.traverse((object) => {
-    if (object !== snapshot && object.userData['editorHelper']) helpers.push(object);
-  });
-  for (const helper of helpers) helper.parent?.remove(helper);
-
   return snapshot;
 }
 
@@ -446,18 +374,7 @@ function objectWorldMatrix(object: THREE.Object3D): THREE.Matrix4 {
   return world;
 }
 
-/**
- * For every bone a skinned mesh in `source` references from OUTSIDE `source`,
- * the same-named bone inside it — or a thrown refusal naming what could not be
- * resolved. An empty map means the subtree's skeletons are already complete.
- *
- * The unresolvable case is real (a bone with no name, or one whose owner truly
- * lives above the selection), and it stays an error: the alternative is a
- * picture of a mesh bound to bones the caller never selected. What changed is
- * that the error now says WHICH mesh and WHICH bones, because "Select the
- * complete skeleton root" with nothing named is a dead end — there is no way
- * to act on it from the terminal that produced it.
- */
+/** Resolve every external skeleton reference to a same-named bone inside source. Return an empty map for a complete subtree; refuse with mesh and bone names when a reference cannot resolve. */
 function resolveExternalBones(
   source: THREE.Object3D,
   sourceNodes: ReadonlySet<THREE.Object3D>,
@@ -485,14 +402,8 @@ function resolveExternalBones(
     const meshName = skinned.name || skinned.uuid;
     for (const bone of skinned.skeleton.bones) {
       if (bone && sourceNodes.has(bone)) continue;
-      // Substitution is a per-BONE fact, so an answer found for one mesh holds
-      // for every other mesh referencing the same bone object — and they do:
-      // GLTFLoader gives every primitive of one skin a SkinnedMesh bound to the
-      // SAME Skeleton, which is the ordinary body+outfit character. Reading
-      // this as "already handled, nothing to do here" and falling through to
-      // the unresolved ledger refused exactly those models, with a sentence
-      // ("owns no bone of the same name") that the first mesh had just
-      // disproved.
+      // Bone substitution is shared across meshes referencing the same bone object, including glTF
+      // primitives bound to one skeleton.
       if (bone && substitutes.has(bone)) continue;
       const candidates = bone ? (nameIndex().get(bone.name) ?? []) : [];
       if (candidates.length === 1) {
@@ -509,10 +420,7 @@ function resolveExternalBones(
   });
 
   if (unresolved.size > 0) {
-    // Two refusals, and they are NOT the same fact: nothing of that name to
-    // bind to, versus several and no way to tell which was meant. Reporting
-    // one as the other is how an un-actionable error survives a fix that was
-    // supposed to remove it.
+    // Distinguish a missing same-named bone from several ambiguous candidates in the refusal.
     const detail = [...unresolved.values()]
       .map(({ mesh, bone, sameNamed }) =>
         sameNamed > 1
@@ -543,7 +451,7 @@ function resolveExternalBones(
  */
 function cloneRenderableHierarchy(
   source: THREE.Object3D,
-  boneSubstitutes: ReadonlyMap<THREE.Bone, THREE.Bone> = new Map(),
+  boneSubstitutes: ReadonlyMap<THREE.Bone, THREE.Bone>,
 ): THREE.Object3D {
   const cloneBySource = new Map<THREE.Object3D, THREE.Object3D>();
   const skinnedPairs: Array<[THREE.SkinnedMesh, THREE.SkinnedMesh]> = [];
@@ -760,7 +668,7 @@ export function createOwnedObjectPreviewSnapshot(
 
 export function measureAssetPreview(
   object: THREE.Object3D,
-  view: AssetPreviewView = 'front',
+  view: AssetPreviewView,
 ): AssetPreviewFraming {
   resolveWorldMatricesLikeRenderer(object);
   const box = readOnlyRenderableBounds(object, view);
@@ -774,33 +682,7 @@ export function measureAssetPreview(
   };
 }
 
-/**
- * Bring a subtree's world matrices to exactly the state the RENDERER will
- * compute for it, then measure from that.
- *
- * This is not interchangeable with `updateWorldMatrix`, and the difference
- * is measurable rather than stylistic: `SkinnedMesh` OVERRIDES
- * `updateMatrixWorld` to refresh `bindMatrixInverse` from its current world
- * matrix (attached bind mode), and `getVertexPosition` — how this module
- * reads skinned geometry — runs the vertex through
- * `bindMatrixInverse * boneWorld * boneInverse * bindMatrix`. Measure after
- * `updateWorldMatrix` alone and `bindMatrixInverse` is still the value from
- * before the subject was re-parented (for example under
- * {@link faceFrontSubject}'s yaw pivot), so the mesh's own transform gets
- * applied TWICE to every skinned vertex while the render applies it once.
- *
- * A yaw pivot of PI (our generated rigs persist `forward = [0,0,-1]`)
- * therefore mirrored the measured bounds in Z: the size stayed right and the
- * CENTRE flipped sign, which is invisible when the camera looks down Z
- * (front/back) and pushes the subject bodily out of frame when it looks
- * down X (left/right). That is the whole of the "long body runs off the
- * frame edge at yaw +/-PI/2" defect.
- *
- * `updateMatrixWorld(force)` is used deliberately in preference to
- * `updateWorldMatrix`: it honours `matrixWorldAutoUpdate` exactly as the
- * renderer's own `scene.updateMatrixWorld()` does, so a snapshot that pins
- * an exact composed matrix is measured the way it is drawn.
- */
+/** Update matrices through the renderer’s updateMatrixWorld path before measuring, including SkinnedMesh.bindMatrixInverse and matrixWorldAutoUpdate. */
 function resolveWorldMatricesLikeRenderer(object: THREE.Object3D): void {
   object.parent?.updateWorldMatrix(true, false);
   object.updateMatrixWorld(true);
@@ -832,7 +714,6 @@ function measureProjectedSpans(
   bases: readonly OrthographicViewBasis[],
 ): ProjectedSpan[] {
   const spans = bases.map(() => createProjectedSpan());
-  if (bases.length === 0) return spans;
   resolveWorldMatricesLikeRenderer(root);
   forEachRenderableVertex(root, bases[0]!, false, (point) => {
     for (let index = 0; index < bases.length; index++) {
@@ -867,7 +748,6 @@ function measureShotFrameCoverage(
 ): { framed: number[]; total: number } {
   const framed = frames.map(() => 0);
   let total = 0;
-  if (frames.length === 0) return { framed, total };
   resolveWorldMatricesLikeRenderer(subject);
   const spans = frames.map(() => createProjectedSpan());
   let open = -1;
@@ -918,14 +798,6 @@ function forEachRenderableVertex(
   let primitive = 0;
   const visit = (object: THREE.Object3D): void => {
     if (!object.visible) return;
-    // A live scene subject (`captureSceneStageAssetPreview`) carries its game's
-    // implementation as real children — a world-space particle renderer at
-    // identity, a pooled batch — and framing on those puts the subject in a
-    // corner of its own portrait. Subtree-scoped, same rule as the selection
-    // cage (`content-bounds.ts`); a loaded model file carries no marks, so the
-    // asset lanes are unaffected. The ROOT is always measured: a caller who
-    // named it meant it.
-    if (object !== root && isBuiltInternal(object)) return;
     if (hasUserData(object, 'gaussianSplat')) {
       splatBounds.copy((object as SplatMesh).getBoundingBox()).applyMatrix4(object.matrixWorld);
       const splatPrimitive = primitive++;
@@ -1108,12 +980,7 @@ function orthographicCamera(
 
   if (view === 'right') {
     horizontal = size.z;
-  } else {
-    if (view === 'top') {
-      horizontal = size.x;
-      vertical = size.z;
-    }
-  }
+  } else if (view === 'top') vertical = size.z;
 
   const frame = fitOrthographicFrame(horizontal / 2, vertical / 2, aspect);
   return createOrthographicShotCamera(
@@ -1187,7 +1054,7 @@ function assetViewBasis(view: AssetPreviewView): {
   return { direction, right, up };
 }
 
-export function createAssetPreviewCamera(
+function createAssetPreviewCamera(
   view: AssetPreviewView,
   framing: AssetPreviewFraming,
   aspect: number,
@@ -1207,22 +1074,7 @@ export function createPerspectiveAssetPreviewCamera(
   return perspectiveCamera(framing, aspect, direction);
 }
 
-/**
- * The turntable cameras for one staged subject, framed from what each yaw
- * ACTUALLY sees.
- *
- * Every yaw of a subject is measured separately (an oriented projection of
- * the rendered vertices onto that yaw's screen axes), each shot is centred
- * on its own projection, and the SCALE is the union across the set's yaws —
- * see {@link unionOrthographicFrames} for why the union rather than a
- * per-shot exact fit. The depth budget still comes from the subject's own
- * bounding radius, which no yaw can exceed.
- *
- * The predecessor derived every yaw from one world-axis-aligned box, which
- * both over-framed a bent, elongated subject and — because it centred every
- * yaw on that box's centre — placed the subject wrong the moment the
- * measured box and the drawn subject disagreed.
- */
+/** Frame each turntable yaw from its projected rendered vertices, centring each view independently and sharing the union scale. Use the subject radius for depth. */
 function turntableCameras(
   subject: THREE.Object3D,
   framing: AssetPreviewFraming,
@@ -1250,13 +1102,13 @@ function turntableCameras(
   return cameras;
 }
 
-/** Six source-review views aligned to the asset's declared semantic forward
- * rather than mislabeled world axes. This is bounding-box framing only: it
- * does not require or modify a skeleton. */
+/** Six source-review views aligned to the asset's declared semantic forward.
+ * Cardinal views share a scale fitted to projected rendered vertices; quarter
+ * views fit the bounds. No skeleton is required or modified. */
 export function captureSourceReviewShotSetAssetPreview(
   source: THREE.Object3D,
   forward: readonly [number, number, number],
-  options: AssetPreviewOptions = {},
+  options: AssetPreviewOptions,
 ): SourceReviewShotSetCapture {
   const width = checkedDimension(options.width);
   const height = checkedDimension(options.height);
@@ -1361,23 +1213,9 @@ export function captureSourceReviewShotSetAssetPreview(
 }
 
 /**
- * A tight orthographic close-up that frames every given world-space anchor
- * point (plus a margin proportional to the WHOLE MODEL's own bounding
- * radius — never a fixed reference-human height, so a goblin's crop stays
- * goblin-scaled). A single anchor (head, one shoulder) yields a fixed-size
- * crop around that point; two anchors that are naturally far apart in a
- * T-pose rig (both hands, both feet) still get a camera wide/tall enough to
- * hold both — the historical fixed-height-zoom defect the line-up harness's
- * own `zoom=head` fix (B5.1) already had to correct once, generalized here
- * to "the crop must actually contain what it claims to frame" for every
- * region, not just proportional scaling.
- *
- * The crop is taken from the shot's own `yaw` (the turntable convention;
- * omitted means 0, the front camera this used to be hardcoded to). An angle
- * is not decoration on a long subject: a junction whose axis runs down the
- * body's length — a tail root, a hip chain, a sail seen edge-on — has the
- * body itself standing between the front camera and the anchor, so the crop
- * frames the right point and photographs the wrong thing.
+ * Frame every world-space bone anchor with an orthographic close-up. Scale the margin and minimum
+ * crop size by the whole model’s bounding radius, and expand the crop to contain separated anchors.
+ * Use the shot’s yaw with the turntable convention; omitted yaw selects the front view.
  */
 function boneZoomCamera(
   anchors: readonly THREE.Vector3[],
@@ -1398,11 +1236,8 @@ function boneZoomCamera(
   );
 }
 
-/** Locate every bone a shot-set definition requires on the loaded GLB's OWN
- *  skeleton (never a body-engine assumption). Throws loudly, naming exactly
- *  which joints are missing, when the model has no rig at all or is missing
- *  a required joint — no silent fallback to a generic bounding-box zoom for
- *  a set that promised skeleton-anchored framing. */
+/** Locate every required bone on the source's skeleton. Refuse absent rigs
+ *  and missing joints by name before framing a skeleton-anchored shot. */
 function findRequiredSkeletonBones(
   root: THREE.Object3D,
   definition: AssetPreviewShotSetDefinition,
@@ -1417,13 +1252,13 @@ function findRequiredSkeletonBones(
   const hint = definition.rigRequirementHint ? ` (${definition.rigRequirementHint})` : '';
   if (required.length > 0 && bonesByName.size === 0) {
     throw new Error(
-      `Asset preview '--shots ${definition.name}' requires a rigged GLB${hint}, but this ` +
+      `Asset preview shot set '${definition.name}' requires a rigged model${hint}, but this ` +
         `model has no skeleton at all. Required joints: ${required.join(', ')}.`,
     );
   }
   if (missing.length > 0) {
     throw new Error(
-      `Asset preview '--shots ${definition.name}' requires joints this GLB's skeleton does ` +
+      `Asset preview shot set '${definition.name}' requires joints this model's skeleton does ` +
         `not have${hint}. Missing joint(s): ${missing.join(', ')}.`,
     );
   }
@@ -1432,8 +1267,8 @@ function findRequiredSkeletonBones(
 
 /**
  * Apply one of the definition's named poses to a snapshot in place — bone
- * rotations on the skeleton, morph influences on whatever meshes declare
- * them.
+ * rotations/translations on the skeleton, morph influences on meshes that
+ * declare them.
  *
  * BOTH halves degrade rather than throw, for the same reason: a pose may
  * touch a joint or a morph beyond the definition's `requiredBones` (a rig can
@@ -1479,9 +1314,7 @@ function applyShotSetPose(
   });
 }
 
-/** First valid `userData.forward` in the tree (our baked rigs persist it on
- *  the rig root, which sits below the GLTF scene root), else glTF's +Z.
- *  Shared with the compare mode (`asset-compare.ts` re-exports it). */
+/** Read the first valid `userData.forward` in the subtree, defaulting to glTF's +Z. */
 export function readModelForward(root: THREE.Object3D): [number, number, number] {
   let found: [number, number, number] | null = null;
   root.traverse((object) => {
@@ -1491,19 +1324,9 @@ export function readModelForward(root: THREE.Object3D): [number, number, number]
   return found ?? [0, 0, 1];
 }
 
-/**
- * Face-the-camera normalization (the compare path's forward detection,
- * applied to the labeled shot sets): wrap a snapshot in a pivot yawed so the
- * model's own forward faces +Z — the direction every 'front' camera looks
- * from. Models without forward extras keep the glTF +Z convention (yaw 0, an
- * exact no-op), so arbitrary GLBs render exactly as before; our generated
- * humanoids persist `userData.forward = [0,0,-1]` and previously had their
- * BACK photographed by every front-labeled shot.
- *
- * `forward` must be read from the SOURCE object (the compare path does the
- * same): render snapshots deliberately copy presentation state only, so the
- * forward extras never survive onto the snapshot itself.
- */
+/** Yaw a snapshot so the model’s forward faces the front camera at +Z. Read forward from the
+ * source object because snapshots copy presentation state without project extras. Missing
+ * forward extras use glTF’s +Z convention and need no rotation. */
 function faceFrontSubject(
   snapshot: THREE.Object3D,
   forward: readonly [number, number, number],
@@ -1528,15 +1351,9 @@ interface StagedShotSubject {
 }
 
 /**
- * The Asset Lab's studio stage: the subject, a hemisphere ambient, a key and a
- * fill. The IBL that completes it is applied SEPARATELY
- * ({@link applyStudioEnvironment}), because a PMREM bake needs a live
- * renderer and every caller here builds its scene before its renderer.
- *
- * The hemisphere is scaled down by {@link STUDIO_AMBIENT_WITH_ENVIRONMENT}:
- * with an environment map in the scene it is the second, cruder ambient term,
- * and at its historical 1.8 the two together flattened the subject. Key and
- * fill are untouched — they still own the form.
+ * Build the Asset Lab studio scene with hemisphere, key, fill and underside lights.
+ * applyStudioEnvironment adds the renderer-dependent IBL separately. Scale the
+ * hemisphere by STUDIO_AMBIENT_WITH_ENVIRONMENT to balance its ambient term with the IBL.
  */
 function createPreviewScene(snapshot: THREE.Object3D, framing: AssetPreviewFraming): THREE.Scene {
   const scene = new THREE.Scene();
@@ -1552,11 +1369,7 @@ function createPreviewScene(snapshot: THREE.Object3D, framing: AssetPreviewFrami
     .copy(framing.center)
     .addScaledVector(new THREE.Vector3(-1, 0.5, -0.7), framing.radius * 2);
   scene.add(fill);
-  // An UNDER fill, weak and warm, so a shot from below (`--elevation -60`:
-  // gills under a cap, a barrel's closed bottom) reads as a surface instead
-  // of a black disc. Measured on the blind modeling bench (round 10): an
-  // agent spent three looks and a probe deciding whether an unlit underside
-  // was closed. Tops are unchanged — this light sees only downward faces.
+  // A weak warm fill from below makes downward-facing surfaces visible in underside shots.
   const under = new THREE.DirectionalLight(0xfff1dc, 0.45);
   under.position
     .copy(framing.center)
@@ -1596,7 +1409,7 @@ if (import.meta.hot) import.meta.hot.dispose(disposeObjectCaptureRenderer);
 
 export function captureObjectAssetPreview(
   source: THREE.Object3D,
-  options: AssetPreviewOptions = {},
+  options: AssetPreviewOptions,
 ): AssetPreviewCapture {
   let containsSplat = false;
   source.traverse((object) => {
@@ -1657,8 +1470,7 @@ export function captureObjectAssetPreview(
         createAssetPreviewCamera(view, measureAssetPreview(subject, view), width / height),
       );
     }
-    // The underside, from 30° round and 60° below — the frame the look used
-    // to take as a separate second capture and write as `below.png`.
+    // Add an underside view from 30° azimuth and −60° elevation.
     const below = perspectiveCamera(
       framing,
       width / height,
@@ -1725,7 +1537,7 @@ function applyClipPose(snapshot: THREE.Object3D, pose: AssetPreviewPose): void {
       `Asset preview pose time must be a finite number of seconds >= 0, got ${pose.timeSeconds}.`,
     );
   }
-  const clips = snapshot.animations ?? [];
+  const clips = snapshot.animations;
   const clip = clips.find((candidate) => candidate.name === pose.clip);
   if (!clip) {
     const available = clips.map((candidate) => `'${candidate.name}'`).join(', ');
@@ -1807,9 +1619,8 @@ function renderFreeCameraCapture(
 /**
  * The axis marker for one orthographic view: which AUTHORED axis points
  * screen-right after the subject's face-front yaw, spelled as `+X>` (that
- * axis points right) or `<+X` (it points left). `null` for the perspective
- * view, and for the rare non-cardinal yaw — where the marker instead names
- * the yaw itself so nothing is silently askew.
+ * axis points right) or `<+X` (it points left). Perspective views return null;
+ * non-cardinal orientations name their yaw.
  */
 function authoredAxisMarker(
   view: AssetPreviewView,
@@ -1832,14 +1643,7 @@ function authoredAxisMarker(
 }
 
 /**
- * Render the four fixed views and assemble the labeled 2x2 contact sheet.
- *
- * Extracted verbatim from {@link captureObjectAssetPreview}'s own loop (its
- * only caller until the scene stage below): the two stages differ in WHAT
- * they photograph — an isolated snapshot on a studio stage versus the entity
- * standing in the live scene — never in how the sheet is assembled, so a
- * caller comparing a lab and a scene capture is comparing subjects rather
- * than two independently-drifting sheet builders.
+ * Render four fixed views and a 2×2 contact sheet, or a 3×2 sheet when the lab includes its underside view.
  */
 function renderFourViewCapture(
   renderer: THREE.WebGLRenderer,
@@ -1848,10 +1652,7 @@ function renderFourViewCapture(
   width: number,
   height: number,
   orientation: AssetPreviewOrientation,
-  /** A fifth camera, the UNDERSIDE, drawn as the sheet's fifth tile (3 × 2).
-   *  Every blind modeling session read the sheet and then `below.png` as a
-   *  second image, ten seconds of generation per look; one sheet that carries
-   *  the underside is one read (2026-09-06). */
+  /** The underside camera occupies the fifth tile of the 3 × 2 contact sheet. */
   below?: THREE.Camera,
 ): AssetPreviewCapture {
   const views: AssetPreviewImage[] = [];
@@ -1874,8 +1675,7 @@ function renderFourViewCapture(
   }
   renderer.setSize(width, height, false);
   tiles.forEach((view, index) => {
-    const camera = view === 'below' ? below : cameras.get(view);
-    if (!camera) return;
+    const camera = view === 'below' ? below! : cameras.get(view)!;
     renderer.render(scene, camera);
     views.push({
       view,
@@ -1934,7 +1734,7 @@ function renderFourViewCapture(
  * thing here that is not obviously self-restoring: it is undone in `finally`,
  * so a capture that throws mid-render still hands the human back their grid
  * and gizmos. The renderer is this function's own (created and destroyed
- * here, exactly as every other capture in this module does) — the editor's
+ * here) — the editor's
  * viewport renderer and camera are never borrowed, so there is nothing of
  * theirs to put back.
  *
@@ -1944,7 +1744,7 @@ function renderFourViewCapture(
 export function captureSceneStageAssetPreview(
   source: THREE.Object3D,
   scene: THREE.Scene,
-  options: AssetPreviewOptions = {},
+  options: AssetPreviewOptions,
 ): AssetPreviewCapture {
   let containsSplat = false;
   source.traverse((object) => {
@@ -2016,7 +1816,7 @@ export function captureSceneStageAssetPreview(
 }
 
 /** One shot, staged and framed but not yet rendered. */
-export interface PlannedShot {
+interface PlannedShot {
   label: string;
   camera: THREE.Camera;
   scene: THREE.Scene;
@@ -2027,7 +1827,7 @@ export interface PlannedShot {
 
 /** Everything {@link captureShotSetAssetPreview} needs before it touches a
  *  GPU, plus the snapshots that staging allocated. */
-export interface ShotSetCapturePlan {
+interface ShotSetCapturePlan {
   shots: PlannedShot[];
   warnings: AssetPreviewShotWarning[];
   dispose(): void;
@@ -2059,28 +1859,19 @@ function emptyFrameWarning(
     ...(shot.view === 'bone-zoom' ? { bones: [...shot.bones] } : {}),
     ...(shot.pose === undefined ? {} : { pose: shot.pose }),
     message:
-      `Asset preview '--shots ${definitionName}' shot ${JSON.stringify(shot.label)} (${aimed}` +
+      `Asset preview shot set '${definitionName}' shot ${JSON.stringify(shot.label)} (${aimed}` +
       `${posed}) framed NONE of the subject's ${totalPrimitives} rendered faces: the image is ` +
       `background only and proves nothing about the asset. ${cause}`,
   };
 }
 
 /**
- * Stage and frame a labeled shot set against the MODEL'S OWN skeleton and
- * bounds (no assumed proportions), WITHOUT rendering: turntable angles and
- * tight bone-anchored zooms, per the project-supplied definition. Shots that
- * name a pose are staged on a disposable POSED snapshot (per named pose) so
- * the rest-pose shots and the loaded source model are never affected. Zoom
- * `spanFraction`s size each crop relative to the whole model's own bounding
- * radius — a short "goblin" rig gets a goblin-scaled crop, never a fixed
- * reference-human height.
- *
- * Split out of {@link captureShotSetAssetPreview} so that everything the
- * capture DECIDES — which snapshot, which camera, and whether a shot frames
- * any geometry at all — is reachable without a WebGL context, for the same
- * reason `asset-preview-framing.ts` exists. The caller owns `dispose()`.
+ * Stage and frame a labeled shot set using the model’s skeleton and bounds without rendering. Each
+ * named pose uses a disposable snapshot; rest shots and the loaded source remain unchanged.
+ * Turntable angles and bone crops use the supplied definition, with spanFraction scaled to the
+ * whole model’s radius. The caller owns dispose().
  */
-export function planShotSetCapture(
+function planShotSetCapture(
   source: THREE.Object3D,
   definition: AssetPreviewShotSetDefinition,
   aspect: number,
@@ -2094,11 +1885,8 @@ export function planShotSetCapture(
     const snapshot = createAssetPreviewSnapshot(source);
     snapshots.push(snapshot);
     const bonesByName = findRequiredSkeletonBones(snapshot, definition);
-    // Yaw-normalize the subject to face the front camera (the compare
-    // path's forward detection — see {@link faceFrontSubject}): turntable
-    // labels AND the +Z-fixed zoom crops are only true to the model's
-    // facing once its forward actually points at them. Bone anchors are
-    // read AFTER the wrap, so the zoom framing follows the rotation.
+    // Normalize forward before framing so turntable labels and yaw-based bone crops use the model’s
+    // facing. Read bone anchors after that rotation.
     const forward = readModelForward(source);
     const subject = faceFrontSubject(snapshot, forward);
     const framing = measureAssetPreview(subject, 'perspective');
@@ -2112,7 +1900,7 @@ export function planShotSetCapture(
     const poseStages = new Map<string, StagedShotSubject>();
     for (const shot of definition.shots) {
       if (shot.pose === undefined || poseStages.has(shot.pose)) continue;
-      const steps = definition.poses?.[shot.pose] ?? [];
+      const steps = definition.poses![shot.pose]!;
       const poseSnapshot = createAssetPreviewSnapshot(source);
       snapshots.push(poseSnapshot);
       const poseBones = findRequiredSkeletonBones(poseSnapshot, definition);
@@ -2140,13 +1928,13 @@ export function planShotSetCapture(
     for (const pose of new Set(
       definition.shots
         .filter((shot) => shot.view === 'turntable')
-        .map((shot) => shot.pose ?? undefined),
+        .map((shot) => shot.pose),
     )) {
       const staged = stageFor(pose);
       const yaws = [
         ...new Set(
           definition.shots
-            .filter((shot) => shot.view === 'turntable' && (shot.pose ?? undefined) === pose)
+            .filter((shot) => shot.view === 'turntable' && (shot.pose) === pose)
             .map((shot) => (shot as Extract<ShotSetShot, { view: 'turntable' }>).yaw),
         ),
       ];
@@ -2167,28 +1955,19 @@ export function planShotSetCapture(
         if (shot.view === 'turntable') {
           return {
             label: shot.label,
-            camera: turntableByStage.get(shot.pose ?? undefined)!.get(shot.yaw)!,
+            camera: turntableByStage.get(shot.pose)!.get(shot.yaw)!,
             scene: staged.scene,
             stage: staged,
             basis: turntableViewBasis(shot.yaw),
           };
         }
-        // Bone-zoom anchors are read from the REST snapshot's bones, for
-        // every shot including posed ones — and for an EXPRESSION STRIP
-        // (several poses framed on the same head) that is the point, not a
-        // limitation: one anchor set means one camera, so the frames differ
-        // only by the face. A pose that MOVED its own anchor would want the
-        // pose snapshot's bone map instead; no definition does that today,
-        // and a strip never should.
-        //
-        // A zoom on multiple bones (both hands, both feet) sizes the crop to
-        // actually contain every anchor, not just apply a fixed fraction of
-        // the model's radius — see {@link boneZoomCamera}'s doc comment.
+        // Read bone-zoom anchors from the rest snapshot so expression-strip poses share a camera.
+        // Multiple anchors expand the crop to contain them all; see boneZoomCamera.
         const missingAnchor = shot.bones.find((bone) => !bonesByName.has(bone));
         if (missingAnchor !== undefined) {
           throw new Error(
-            `Asset preview '--shots ${definition.name}' shot ` +
-              `${JSON.stringify(shot.label)} zooms on a joint this GLB's skeleton does not ` +
+            `Asset preview shot set '${definition.name}' shot ` +
+              `${JSON.stringify(shot.label)} zooms on a joint this model's skeleton does not ` +
               `have: ${missingAnchor}. List it in the definition's requiredBones or fix the rig.`,
           );
         }
@@ -2273,7 +2052,7 @@ export function planShotSetCapture(
 export function captureShotSetAssetPreview(
   source: THREE.Object3D,
   definition: AssetPreviewShotSetDefinition,
-  options: AssetPreviewOptions = {},
+  options: AssetPreviewOptions,
 ): LabeledShotSetCapture {
   const width = checkedDimension(options.width);
   const height = checkedDimension(options.height);
@@ -2298,7 +2077,9 @@ export function captureShotSetAssetPreview(
     activeRenderer.setSize(width, height, false);
     // A pose gets its own staged scene, so every scene in the plan is lit —
     // once, off the renderer's single cached bake.
-    for (const planned of plan.shots) applyStudioEnvironment(planned.scene, activeRenderer);
+    for (const shotScene of new Set(plan.shots.map((shot) => shot.scene))) {
+      applyStudioEnvironment(shotScene, activeRenderer);
+    }
 
     const shots: LabeledShotSetCapture['shots'] = [];
     const columns = 2;
@@ -2372,7 +2153,7 @@ function projectModelUrl(rawAssetPath: string): URL {
   if (decodedPath.split('/').some((segment) => segment === '.' || segment === '..')) {
     throw new Error('Asset Editor model paths cannot traverse outside the project root.');
   }
-  const projectOrigin = globalThis.location?.origin ?? 'http://localhost';
+  const projectOrigin = globalThis.location.origin;
   const url = new URL(assetPath, projectOrigin);
   if (url.origin !== projectOrigin || !url.pathname.toLowerCase().match(/\.(?:glb|gltf|spz)$/)) {
     throw new Error(
@@ -2487,7 +2268,7 @@ function projectDependencyUrl(uri: string, sourceUrl: URL): URL {
 
 function dependencyMimeType(resource: ExternalGltfResource, url: URL): string {
   if (typeof resource.mimeType === 'string') return resource.mimeType;
-  const extension = url.pathname.split('.').pop()?.toLowerCase();
+  const extension = url.pathname.split('.').pop()!.toLowerCase();
   if (extension === 'png') return 'image/png';
   if (extension === 'jpg' || extension === 'jpeg') return 'image/jpeg';
   if (extension === 'webp') return 'image/webp';
@@ -2525,17 +2306,8 @@ async function inlineExternalGltfResources(
   return JSON.stringify(document);
 }
 
-/**
- * Parse a base64 GLB that travelled IN the relay command, rather than one
- * fetched from the project origin.
- *
- * EXTRACTED VERBATIM from `asset-compare.ts`'s private `parseRefGlb` (the
- * compare mode has shipped reference GLBs over the wire this way since B8.4);
- * `label` is the one addition, so each caller keeps its own error wording
- * while there is a single decoder. The bound is the SAME 64 MiB the fetched
- * path enforces (`MAX_MODEL_BYTES`) — bytes that arrive over the relay are no
- * cheaper to rasterize than bytes fetched over HTTP.
- */
+/** Parse a base64 GLB carried by the relay command. The caller's label names
+ * decoding failures. MAX_MODEL_BYTES bounds both relay and fetched models. */
 export function parseGlbBytesModel(base64: string, label: string): Promise<THREE.Object3D> {
   let bytes: Uint8Array<ArrayBuffer>;
   try {
@@ -2564,18 +2336,17 @@ export function parseGlbBytesModel(base64: string, label: string): Promise<THREE
 }
 
 /**
- * The Asset Lab's four-view capture of a model that exists only as BYTES — no
- * project path, no live entity. This is the rasterization half of the
- * "module path" look (`project.bake.preview`): a Node host builds a project
- * module's `Object3D`, exports it to an in-memory GLB, and hands those bytes
- * here, because Node has no GPU and the editor session does.
+ * The Asset Lab's contact-sheet capture of a model that exists only as BYTES — no
+ * project path, no live entity. A Node host that built an `Object3D` exports
+ * it to an in-memory GLB and hands those bytes here, because Node has no GPU
+ * and the editor session does.
  *
  * Deliberately the `'lab'` stage and nothing else — bytes stand nowhere, so
  * there is no scene to stage them in.
  */
 export async function captureGlbBytesAssetPreview(
   glbBase64: string,
-  options: AssetPreviewOptions = {},
+  options: AssetPreviewOptions,
 ): Promise<AssetPreviewCapture> {
   const model = await parseGlbBytesModel(glbBase64, 'Asset preview GLB bytes');
   try {
@@ -2586,16 +2357,15 @@ export async function captureGlbBytesAssetPreview(
 }
 
 /**
- * The same bytes, photographed as a LABELED SHOT SET instead of the four
- * views — what the editor's `screenshot <module> --orbit <n>` command renders. A shot set
- * stages the subject itself, exactly the way the asset-path lane's
+ * The same bytes, photographed as a LABELED SHOT SET. A shot set stages the
+ * subject itself, exactly the way the asset-path lane's
  * {@link captureShotSetModelPreview} does, so bytes are no less valid a
  * subject here than a project GLB is.
  */
 export async function captureShotSetGlbBytesPreview(
   glbBase64: string,
   definition: AssetPreviewShotSetDefinition,
-  options: AssetPreviewOptions = {},
+  options: AssetPreviewOptions,
 ): Promise<LabeledShotSetCapture> {
   const model = await parseGlbBytesModel(glbBase64, 'Asset preview GLB bytes');
   try {
@@ -2648,11 +2418,8 @@ export async function loadProjectAssetModelSource(
   }
 }
 
-export async function loadProjectAssetModel(
-  assetPath: string,
-  externalSignal?: AbortSignal,
-): Promise<THREE.Object3D> {
-  return (await loadProjectAssetModelSource(assetPath, externalSignal)).root;
+export async function loadProjectAssetModel(assetPath: string): Promise<THREE.Object3D> {
+  return (await loadProjectAssetModelSource(assetPath)).root;
 }
 
 /** Release a model returned by {@link loadProjectAssetModel}. */
@@ -2677,7 +2444,7 @@ export function disposeProjectAssetModel(root: THREE.Object3D): void {
 
 export async function captureModelAssetPreview(
   assetPath: string,
-  options: AssetPreviewOptions = {},
+  options: AssetPreviewOptions,
 ): Promise<AssetPreviewCapture> {
   const model = await loadProjectAssetModel(assetPath);
   try {
@@ -2692,7 +2459,7 @@ export async function captureModelAssetPreview(
 export async function captureSourceReviewShotSetModelPreview(
   assetPath: string,
   forward: readonly [number, number, number],
-  options: AssetPreviewOptions = {},
+  options: AssetPreviewOptions,
 ): Promise<SourceReviewShotSetCapture> {
   const model = await loadProjectAssetModel(assetPath);
   try {
@@ -2784,14 +2551,14 @@ async function captureSplatAssetPreview(
   }
 }
 
-/** The `--shots <set>` asset-path entry point — loads the project GLB the
+/** The shot set's asset-path entry point — loads the project model the
  *  same bounded/validated way {@link captureModelAssetPreview} does, then
  *  renders the definition's labeled shot set against ITS OWN skeleton
  *  (see {@link captureShotSetAssetPreview}). */
 export async function captureShotSetModelPreview(
   assetPath: string,
   definition: AssetPreviewShotSetDefinition,
-  options: AssetPreviewOptions = {},
+  options: AssetPreviewOptions,
 ): Promise<LabeledShotSetCapture> {
   const model = await loadProjectAssetModel(assetPath);
   try {