@rig-c/core 2.70.0 → 2.72.0

package/src/compile.ts

@@ -3011,10 +3011,50 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   const meshes: CompileResult['meshes'] = [];
   // `skin/slot/attachment` -> per-vertex z, for the attachments that named a
   // depth map. Read at deform-key time; never emitted. See `AttachmentContext`.
-  const attachmentDepths = new Map<string, number[]>();
+  const attachmentDepths = new Map<string, number[] | { z: number[]; geometry: DeformGeometry }>();
   // The same for a `soft` mask's per-vertex level, which a deform envelope's
   // `mask` reads (issue #1413). Never emitted either.
   const attachmentSoftMasks = new Map<string, DeformSoftMask>();
+  // `skin/slot/attachment` -> per-axis narrowing mode when a deform turn key on
+  // that attachment declares `narrowing: false` (issue #1584), so `sampleMeshDepth`
+  // evaluates `turnCeiling` with the `asin(|A₀ / A_axis|)` closed form that
+  // matches `A39` on the keyed turn.
+  const attachmentTurnNarrowing = new Map<string, { yaw?: boolean; pitch?: boolean }>();
+  const attachmentTurnNarrowingBy = new Map<string, { yaw?: { mode: boolean; anim: string }; pitch?: { mode: boolean; anim: string } }>();
+  withMotionSource(() => {
+    for (const [turnAnimName, turnAnim] of Object.entries(motion.animations ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+      for (const turnTrack of turnAnim.deform ?? []) {
+        const turnDeformSkin = turnTrack.skin ?? DEFAULT_SKIN;
+        const turnTriple = `${turnDeformSkin}/${turnTrack.slot}/${turnTrack.attachment}`;
+        for (const turnKey of turnTrack.keys ?? []) {
+          const turnSpec = turnKey.transform as { kind?: unknown; narrowing?: unknown } | undefined;
+          if (turnSpec && (turnSpec.kind === 'yaw' || turnSpec.kind === 'pitch')) {
+            const turnAxis = turnSpec.kind;
+            const turnNarrowMode = turnSpec.narrowing !== false;
+            const turnPrev = attachmentTurnNarrowingBy.get(turnTriple)?.[turnAxis];
+            if (turnPrev !== undefined && turnPrev.mode !== turnNarrowMode) {
+              const turnFalseAnim = turnNarrowMode ? turnPrev.anim : turnAnimName;
+              const turnTrueAnim = turnNarrowMode ? turnAnimName : turnPrev.anim;
+              throw new CompileError(
+                `deform ${turnTriple} keys "${turnAxis}" with narrowing=false in animation "${turnFalseAnim}" and with narrowing=true in animation "${turnTrueAnim}". ` +
+                  'An attachment\'s turn ceiling on one axis is either asin(|A₀ / A_axis|) (without narrowing) or atan(|A₀ / A_axis|) (with narrowing) — ' +
+                  `mixing both on one attachment and axis would report one ceiling where two apply. Use one "narrowing" setting across every "${turnAxis}" key on ${turnTriple}.`,
+                'CE_COMPILE_DEFORM_TURN_NARROWING_MIXED',
+              );
+            }
+            const curBy = attachmentTurnNarrowingBy.get(turnTriple) ?? {};
+            if (curBy[turnAxis] === undefined) curBy[turnAxis] = { mode: turnNarrowMode, anim: turnAnimName };
+            attachmentTurnNarrowingBy.set(turnTriple, curBy);
+            if (!turnNarrowMode) {
+              const cur = attachmentTurnNarrowing.get(turnTriple) ?? {};
+              cur[turnAxis] = false;
+              attachmentTurnNarrowing.set(turnTriple, cur);
+            }
+          }
+        }
+      }
+    }
+  });
 
   for (const rigSlot of rig.slots) {
     const part = partBySlot.get(rigSlot.name);
@@ -3183,6 +3223,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
           imagesDir,
           depths: attachmentDepths,
           softMasks: attachmentSoftMasks,
+          turnNarrowing: attachmentTurnNarrowing.get(`${skinName}/${rigSlot.name}/${placeholder}`),
           slotNames: new Set(rig.slots.map((s) => s.name)),
           atlasRegions: atlasIn === null ? null : atlasIn.byName,
           links: pendingLinks,
@@ -3688,6 +3729,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
         if (deformTimelines.get(skinName)?.get(track.slot)?.has(track.attachment)) {
           throw new CompileError(`${at}: two deform timelines on one attachment; merge them into one`, 'CE_COMPILE_DEFORM_TIMELINE_DUPLICATE');
         }
+        const sampledDepth = attachmentDepths.get(`${skinName}/${track.slot}/${track.attachment}`);
         const keys = compileDeformTrack(
           track,
           motion,
@@ -3695,10 +3737,11 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
           anim.duration,
           {
             ...deformGeometryOf(attachment, at, transforms),
-            depth: attachmentDepths.get(`${skinName}/${track.slot}/${track.attachment}`) ?? null,
+            depth: (Array.isArray(sampledDepth) ? sampledDepth : sampledDepth?.z) ?? null,
             soft: attachmentSoftMasks.get(`${skinName}/${track.slot}/${track.attachment}`) ?? null,
           },
           deformTransforms,
+          sampledDepth !== undefined && !Array.isArray(sampledDepth) ? sampledDepth.geometry : null,
         );
         for (const key of keys) compiledDuration = Math.max(compiledDuration, key.time);
         attachmentTimelinesOf(skinName, track.slot).set(track.attachment, { deform: keys });
@@ -4326,13 +4369,19 @@ interface AttachmentContext {
    * round trip and then vanish — and the whole point of this table is to be
    * read by `evaluateDeformTransform` at key time and never emitted at all.
    */
-  depths: Map<string, number[]>;
+  depths: Map<string, number[] | { z: number[]; geometry: DeformGeometry }>;
   /**
    * A `soft` mask's file and its sampled level per vertex, keyed like `depths`
    * — what a deform envelope's `mask` reads at key time (issue #1413). Never
    * emitted, for `depths`' reason.
    */
   softMasks: Map<string, DeformSoftMask>;
+  /**
+   * Per-axis `narrowing` mode when a deform turn key on this attachment states
+   * `"narrowing": false` (issue #1584), so `sampleMeshDepth` computes the turn
+   * ceiling with `asin(|A₀ / A_axis|)` on that axis.
+   */
+  turnNarrowing?: { yaw?: boolean; pitch?: boolean };
   /** Every slot the rig declares — a clipping attachment's `end` resolves here. */
   slotNames: Set<string>;
   /**
@@ -5708,7 +5757,12 @@ function buildRigMesh(
   if (authored && att.generator) {
     throw new CompileError(`${where}: a mesh is either authored geometry or a generator, never both`, 'CE_COMPILE_MESH_AUTHORED_AND_GENERATED');
   }
-  if (att.generator) return buildGeneratedMesh(att, att.generator, placeholder, where, ctx);
+  if (att.generator) {
+    if (att.depth !== undefined) {
+      throw new CompileError(`${where}: attachment "depth" describes authored geometry; a generated mesh states its depth on the contour or grid generator instead`, 'CE_COMPILE_DEPTH_AUTHORED_REQUIRED');
+    }
+    return buildGeneratedMesh(att, att.generator, placeholder, where, ctx);
+  }
   if (att.vertices && att.weights) {
     throw new CompileError(
       `${where}: a mesh gives geometry as "vertices" or as "weights", never both — "weights" is the by-name form of the same data`, 'CE_COMPILE_MESH_GEOMETRY_SOURCES_CONFLICT',
@@ -5786,6 +5840,35 @@ function buildRigMesh(
     height: f32(height),
   };
   if (att.sequence !== undefined) out.sequence = buildSequence(att.sequence);
+  let depth: ReturnType<typeof sampleMeshDepth> | undefined;
+  if (att.depth !== undefined) {
+    if (img === undefined) {
+      throw new CompileError(`${where}: an authored mesh with "depth" needs an "image" to locate the part's pixel grid`, 'CE_COMPILE_DEPTH_IMAGE_REQUIRED');
+    }
+    const anchor = ctx.transforms.get(ctx.anchorBone);
+    if (!anchor) throw new CompileError(`${where}: slot bone "${ctx.anchorBone}" has no setup transform`, 'CE_COMPILE_SLOT_SETUP_TRANSFORM_MISSING');
+    const geometry = deformGeometryOf(out, where, ctx.transforms, anchor);
+    if (geometry.setup === null) {
+      throw new CompileError(`${where}: depth needs resolved setup positions — ${geometry.setupWhy}`, 'CE_COMPILE_DEFORM_TRANSFORM_SETUP_UNRESOLVED');
+    }
+    const world = geometry.setup;
+    const plate = partPlate(img);
+    const toArt = img.width / plate.width;
+    // The generator's window is centred on the slot bone's setup WORLD origin.
+    // UVs describe texture placement, not a vertex's position in that window.
+    const points: Array<[number, number]> = [];
+    for (let v = 0; v < world.length; v += 2) {
+      points.push([(world[v] - anchor.worldX + img.width / 2) / toArt,
+        (img.height / 2 - (world[v + 1] - anchor.worldY)) / toArt]);
+    }
+    depth = sampleMeshDepth(att.depth, 'authored', points, att.triangles,
+      (px, py) => [anchor.worldX + px * toArt - img.width / 2, anchor.worldY + img.height / 2 - py * toArt],
+      img.pageGrid === undefined ? plateAlpha(plate) : { unlocated: img.pageGrid.said },
+      sheetGridOf(img, plate), where, ctx,
+      Array.from({ length: world.length / 2 }, (_, v) => [world[2 * v], world[2 * v + 1]]));
+    geometry.depth = depth.z;
+    ctx.depths.set(`${ctx.skinName}/${ctx.slotName}/${placeholder}`, { z: depth.z, geometry });
+  }
   // Register it as `authored`: geometry rigc did not build and whose topology it
   // therefore gets to assume nothing about. The generator-topology assertions
   // read this and skip rather than measuring a ring that was never a ring.
@@ -5796,6 +5879,7 @@ function buildRigMesh(
   ctx.meshes.push({
     slot: ctx.slotName,
     kind: 'authored',
+    ...(depth === undefined ? {} : { depth: depth.summary }),
     attachments: [ctx.slotName],
     vertices: uvCount / 2,
     triangles: att.triangles.length / 3,
@@ -6157,8 +6241,8 @@ function buildGeneratedMesh(
  * not invent tolerances.
  */
 function sampleMeshDepth(
-  spec: NonNullable<Extract<NonNullable<RigMeshAttachment['generator']>, { kind: 'contour' }>['depth']>,
-  kind: 'contour' | 'grid',
+  spec: RigDepthMap,
+  kind: 'contour' | 'grid' | 'authored',
   points: ReadonlyArray<readonly [number, number]>,
   /** The mesh's own triangle list, for the turn ceiling. */
   triangles: ReadonlyArray<number>,
@@ -6197,6 +6281,8 @@ function sampleMeshDepth(
   grid: SheetGrid,
   where: string,
   ctx: AttachmentContext,
+  /** Authored setup-world vertices, already in the depth turn's evaluation space. */
+  turnPoints?: ReadonlyArray<readonly [number, number]>,
 ): {
   z: number[];
   /** The tone-curved 0..1 nearness per vertex, which `bind` thresholds. */
@@ -6280,7 +6366,9 @@ function sampleMeshDepth(
       kind === 'contour'
         ? 'A contour mesh puts every vertex ON the silhouette and pushes it out by the margin, so a sheet cut to ' +
           'the art stops short of every one of them. Dilate the sheet past the mesh margin, or lower the margin.'
-        : 'A grid spans the whole part window, corners included, while a sheet is usually cut to the art — so the ' +
+        : kind === 'authored'
+          ? 'The authored setup vertices reach outside the sheet coverage. Extend the sheet to cover their bilinear taps, or correct the setup geometry.'
+          : 'A grid spans the whole part window, corners included, while a sheet is usually cut to the art — so the ' +
           'lattice reaches past it wherever the art does not fill the window. Dilate the sheet to the window, or ' +
           'state "us"/"vs" that keep the lattice inside the art.';
     throw new CompileError(
@@ -6321,9 +6409,10 @@ function sampleMeshDepth(
       range: [f32(lo), f32(hi)],
       ...(partAlpha instanceof Uint8Array ? { undrawn } : { undrawn: null, unlocated: partAlpha.unlocated }),
       ceiling: turnCeiling(
-        points.map(([px, py]) => toBind(px, py)),
+        turnPoints ?? points.map(([px, py]) => toBind(px, py)),
         z,
         triangles,
+        ctx.turnNarrowing === undefined ? undefined : { narrowing: ctx.turnNarrowing },
       ),
     },
   };
@@ -8689,7 +8778,7 @@ export interface DeformGeometry {
   /** Why `setup` is null, phrased for the refusal. Null when it is not. */
   setupWhy: string | null;
   /**
-   * Per-vertex `z`, when this attachment's generator named a depth map.
+   * Per-vertex `z`, when this attachment or its generator named a depth map.
    *
    * Not measured from the attachment like everything else here — there
    * is nowhere in the format to measure it FROM, which is the whole reason the
@@ -8723,6 +8812,8 @@ export function deformGeometryOf(
   where: string,
   /** Every bone's setup world transform, by name. */
   transforms: Map<string, BoneTransform>,
+  /** Force the world-offset path for an authored depth turn, including rigid meshes. */
+  depthAnchor?: BoneTransform,
 ): DeformGeometry {
   const type = att.kind;
   let worldVerticesLength: number;
@@ -8768,6 +8859,15 @@ export function deformGeometryOf(
   const vertices = att.vertices;
   const weighted = vertices.weighted;
   if (!vertices.weighted) {
+    if (depthAnchor !== undefined) {
+      return {
+        weighted, deformLength: worldVerticesLength, vertexCount: worldVerticesLength / 2,
+        boneCounts: Array(worldVerticesLength / 2).fill(1),
+        setup: setupWorldVertices(vertices, depthAnchor, transforms, where).flat(),
+        influenceBones: Array(worldVerticesLength / 2).fill(depthAnchor),
+        setupWhy: null, depth: null, soft: null,
+      };
+    }
     return {
       weighted,
       deformLength: worldVerticesLength,
@@ -8831,7 +8931,7 @@ export function deformGeometryOf(
   // the runtime's last bits (`b = −2.3e-8` on an unrotated bone) into its
   // offset, about 1e-6 on gallery/look's hair locks. Evaluating on the authored
   // positions instead would need them carried here from the binder.
-  if (boneCounts.every((n) => n === 1) && bones.size === 1) {
+  if (depthAnchor === undefined && boneCounts.every((n) => n === 1) && bones.size === 1) {
     return { ...common, setup: bindSpace, influenceBones: null, setupWhy: null };
   }
   // -- several influences, evaluated in world (issue #389) -------------------
@@ -9007,6 +9107,7 @@ function compileDeformTrack(
   duration: number,
   geometry: DeformGeometry,
   generated: CompileResult['deformTransforms'],
+  depthWorld: DeformGeometry | null = null,
 ): ModelKey[] {
   const skin = track.skin ?? 'default';
   const where = `animation "${animName}" deform ${skin}/${track.slot}/${track.attachment}`;
@@ -9032,6 +9133,7 @@ function compileDeformTrack(
     // definite, which the arithmetic does for any weighting that closes at 1 and
     // for no weighting that does not (issue #389).
     if (key.transform !== undefined) {
+      const evaluated = ('depth' in key.transform && key.transform.depth === true ? depthWorld : null) ?? geometry;
       if (key.vertices !== undefined && key.vertices !== null) {
         throw new CompileError(
           `${where} (t=${key.t}): the key carries both a "transform" and a "vertices" run, and they are two answers to ` +
@@ -9042,33 +9144,33 @@ function compileDeformTrack(
       if (key.offset !== undefined || key.fromVertex !== undefined) {
         throw new CompileError(
           `${where} (t=${key.t}): the key states a "transform" and a start index. A transform is a model of the whole ` +
-            `attachment and is evaluated over all ${geometry.vertexCount} of its vertices, so it always starts at deform ` +
+            `attachment and is evaluated over all ${evaluated.vertexCount} of its vertices, so it always starts at deform ` +
             'index 0. A model applied to part of a run leaves a step at the run\'s edge — write the partial run by hand ' +
             'if that is what you mean.', 'CE_COMPILE_DEFORM_TRANSFORM_START_INDEX',
         );
       }
-      if (geometry.setup === null) {
+      if (evaluated.setup === null) {
         throw new CompileError(
           `${where} (t=${key.t}): a "transform" states where every vertex of this attachment goes, and this one has a ` +
-            `vertex the arithmetic cannot place — ${geometry.setupWhy}. Fix the weights, or write the bind-space pairs ` +
+            `vertex the arithmetic cannot place — ${evaluated.setupWhy}. Fix the weights, or write the bind-space pairs ` +
             'yourself and start the run with "offset".', 'CE_COMPILE_DEFORM_TRANSFORM_SETUP_UNRESOLVED',
         );
       }
       const report = evaluateDeformTransform(
         key.transform,
-        geometry.setup,
+        evaluated.setup,
         onModelGrid,
         `${where} (t=${key.t})`,
-        geometry.depth,
-        geometry.soft,
+        evaluated.depth,
+        evaluated.soft,
       );
-      if (report.offsets.length !== geometry.vertexCount * 2) {
+      if (report.offsets.length !== evaluated.vertexCount * 2) {
         // Unreachable while `setup` is one pair per vertex, which is the whole
         // reason both are derived from the same walk. Stated rather than
         // assumed: a silent mismatch here is the overrun A35 exists for.
         throw new CompileError(
           `${where} (t=${key.t}): the transform produced ${report.offsets.length} numbers for ` +
-            `${geometry.vertexCount} vertices`, 'CE_COMPILE_DEFORM_TRANSFORM_OFFSET_COUNT',
+            `${evaluated.vertexCount} vertices`, 'CE_COMPILE_DEFORM_TRANSFORM_OFFSET_COUNT',
         );
       }
       // -- one displacement per vertex -> one pair per influence (issue #389) -
@@ -9080,11 +9182,11 @@ function compileDeformTrack(
       // displacement it expands is the ROUNDED one the report prints, so a
       // reader can reproduce every emitted pair from the audit rather than from
       // a second evaluation.
-      const run = expandDeformToInfluences(report.offsets, geometry);
-      if (run.length !== geometry.deformLength) {
+      const run = expandDeformToInfluences(report.offsets, evaluated);
+      if (run.length !== evaluated.deformLength) {
         throw new CompileError(
           `${where} (t=${key.t}): the transform expanded to ${run.length} numbers and this attachment's deform ` +
-            `array is ${geometry.deformLength} long`, 'CE_COMPILE_DEFORM_TRANSFORM_RUN_LENGTH',
+            `array is ${evaluated.deformLength} long`, 'CE_COMPILE_DEFORM_TRANSFORM_RUN_LENGTH',
         );
       }
       generated.push({
@@ -9100,14 +9202,14 @@ function compileDeformTrack(
         // other way to know they were not evaluated alike. Said only on the path
         // where it is not the attachment's own space, so every existing report
         // prints exactly the lines it printed before.
-        ...(geometry.influenceBones === null
+        ...(evaluated.influenceBones === null
           ? {}
           : {
               expanded: run,
               derived: [
                 ...report.derived,
-                `evaluated at setup WORLD positions, because ${geometry.vertexCount} vertices carry ` +
-                  `${geometry.deformLength / 2} influences; each displacement D is written into every influence as ` +
+                `evaluated at setup WORLD positions, because ${evaluated.vertexCount} vertices carry ` +
+                  `${evaluated.deformLength / 2} influences; each displacement D is written into every influence as ` +
                   'Mᵢ⁻¹·D, so the runtime composes Σwᵢ·Mᵢ·Mᵢ⁻¹·D = D',
               ],
             }),

package/src/core/animation.ts

@@ -189,11 +189,12 @@ import {
   foldInheritMode,
   gridRound,
   readBlend,
-  readColour,
   shownAttachment,
   shownRow,
   slidersKeyingWhy,
   sourceOfDoc,
+  viewColours,
+  WHITE,
   type CompiledDocument,
   type CoreAnimation,
   type CoreBoneRow,
@@ -834,12 +835,15 @@ export function posedSlots(
   /** Filled with each slot's placeholder once the sample's own timelines have moved it, before the sliders — what the attachments are posed from (`attachmentStates`). */
   placeholders?: Map<string, string | null>,
 ): { rows: CoreSlotRow[]; conflicts: string[] } {
-  const colour = plant.colour ?? readColour;
+  // The view's stated colours, read once (`viewColours`); a planted reader of the light colour is called as it always was.
+  const stated = viewColours(doc);
+  const colour = plant.colour ?? stated;
   const byName = new Map(timelines.slots.map((s) => [s.name, s]));
   return slotRowsFrom(doc, plant, sliders, placeholders, (slot, live) => {
     let placeholder = slot.setup;
-    const light = slot.color === undefined ? [1, 1, 1, 1] : colour(slot.color);
-    const setupDark = slot.dark === undefined ? null : readColour(slot.dark);
+    const setupLight = slot.color === undefined ? WHITE : colour(slot.color);
+    const light = [setupLight[0], setupLight[1], setupLight[2], setupLight[3]];
+    const setupDark = slot.dark === undefined ? null : stated(slot.dark);
     const dark = setupDark === null ? null : [setupDark[0], setupDark[1], setupDark[2]];
     for (const tl of live ? (byName.get(slot.name)?.timelines ?? []) : []) {
       if (tl.kind === 'attachment') {
@@ -848,7 +852,6 @@ export function posedSlots(
         continue;
       }
       const v = valuesAt(tl.keys, t, plant);
-      const setupLight = slot.color === undefined ? [1, 1, 1, 1] : colour(slot.color);
       const channels = SLOT_COLOUR_TIMELINES[tl.kind].channels;
       channels.forEach((name, i) => {
         const at = { r: 0, g: 1, b: 2, a: 3, r2: 4, g2: 5, b2: 6 }[name];
@@ -955,15 +958,22 @@ export function posedBoneRows(doc: CompiledDocument, timelines: CoreAnimationTim
 /** `posedBoneRows`, with the world transforms the rows were read off — what the sample's attachments are posed through. */
 export function posedBoneWorld(doc: CompiledDocument, timelines: CoreAnimationTimelines, t: number, plant: TimelinePlant = {}, constraints?: CoreConstraintTimelines, sliders?: SliderApplication[], step?: PoseStep): { rows: CoreBoneRow[]; world: Map<string, CoreWorld> } {
   const posed = posedBoneStep(doc, timelines, t, plant, constraints, sliders, step);
-  return { rows: stepRows(posed), world: posed.world };
+  const stage = plant.stage;
+  if (stage !== undefined) stage.begin('readout');
+  const rows = stepRows(posed);
+  if (stage !== undefined) stage.end('readout');
+  return { rows, world: posed.world };
 }
 
 /**
  * `posedBoneWorld`'s world transforms without its rows (issue #1179, the
  * second part): the same pose by the same operations in the same order, since
  * `stepRows` only reads the world once it is posed. A walk reads `world` and
- * no row, so the scan's walk (`scanWalkIn` in `./raw.ts`, A10's) asks for
- * this; the raw entry's walk still forms the rows it does not read, unchanged.
+ * no row, so every walk asks for this — the scan's (`scanWalkIn` in
+ * `./raw.ts`, A10's), the raw entry's batch walks and the live track's step.
+ * The rows were the only thing the other variant adds, and their rounding
+ * (`rawNumber`, `keptNumber`) refuses nothing, so leaving them out moves no
+ * number and no refusal of a walk.
  */
 export function posedBoneWorldAlone(doc: CompiledDocument, timelines: CoreAnimationTimelines, t: number, plant: TimelinePlant, constraints: CoreConstraintTimelines | undefined, sliders: SliderApplication[] | undefined, step: PoseStep | undefined): Map<string, CoreWorld> {
   return posedBoneStep(doc, timelines, t, plant, constraints, sliders, step).world;
@@ -997,20 +1007,34 @@ function stepRows(posed: PosedStep): CoreBoneRow[] {
 
 /** `posedBoneWorld` up to its rows, refusing a bone the evaluator gave no transform (`PosedStep`). */
 function posedBoneStep(doc: CompiledDocument, timelines: CoreAnimationTimelines, t: number, plant: TimelinePlant, constraints: CoreConstraintTimelines | undefined, sliders: SliderApplication[] | undefined, step: PoseStep | undefined): PosedStep {
+  const stage = plant.stage;
+  if (stage !== undefined) stage.begin('timeline');
   const bones = posedBones(doc, timelines, t, plant);
+  if (stage !== undefined) stage.end('timeline');
   // One step of the stepped phase (issue #956, `./constraints_physics.ts`): the physics records posed by their timelines and stepped under the walk's context; the deformed curve a path walks as above.
-  if (constraints !== undefined && step !== undefined) return steppedLocals(doc, bones, plant, () => pathDeformed(doc, posedRecords(constraintRecords(doc), constraints, t), timelines, t, plant), constraints.physicsKeyed ?? [], t, sliders, step);
+  if (constraints !== undefined && step !== undefined) {
+    return steppedLocals(doc, bones, plant, () => pathDeformed(doc, posedRecords(constraintRecords(doc), constraints, t), timelines, t, plant), constraints.physicsKeyed ?? [], t, sliders, step);
+  }
   const active = activeBones(doc);
   // The caller's adjustment, after the timelines and before anything reads the locals (`LocalAdjust`).
-  if (step?.adjustment !== undefined) adjustLocals(doc, bones, step.adjustment.callback, step.adjustment.context);
-  let world = (plant.evaluate ?? worldTransforms)(bones, active);
+  if (step?.adjustment !== undefined) {
+    if (stage !== undefined) stage.begin('timeline');
+    adjustLocals(doc, bones, step.adjustment.callback, step.adjustment.context);
+    if (stage !== undefined) stage.end('timeline');
+  }
+  if (stage !== undefined) stage.begin('world');
+  const initialWorld = (plant.evaluate ?? worldTransforms)(bones, active);
+  if (stage !== undefined) stage.end('world');
+  let world = initialWorld;
   if (constraints !== undefined) {
+    if (stage !== undefined) stage.begin('constraints');
     const setupRecords = constraintRecords(doc);
     // A path walks the curve the sample's deform timelines left on its slot (`./deform.ts`); a slider's deform of a walked path leaves the bones out (`pathAnimationsWhy`).
     const records = pathDeformed(doc, posedRecords(setupRecords, constraints, t), timelines, t, plant);
     // A path constraint may read a slot bone the runtime has not yet brought up to date in this pass, as the previous pass left it (`./constraints_path.ts`, *Which slot bone*); `poseAnimations` holds that pass to the setup pose's reading.
     const previous = setupRecords.some((r) => r.kind === 'path') ? applyConstraints(doc.bones, (plant.evaluate ?? worldTransforms)(doc.bones, active), active, plant.constraints ? plant.constraints(setupRecords) : setupRecords, null, undefined, undefined, undefined, solverRules(plant.solver)) : null;
-    world = applyConstraints(bones, world, active, plant.constraints ? plant.constraints(records) : records, previous, sliders, undefined, undefined, solverRules(plant.solver));
+    world = applyConstraints(bones, initialWorld, active, plant.constraints ? plant.constraints(records) : records, previous, sliders, undefined, undefined, solverRules(plant.solver));
+    if (stage !== undefined) stage.end('constraints');
   }
   for (const b of bones) if (world.get(b.name) === undefined) throw new CoreInputError(`the evaluator returned no transform for bone "${b.name}"`);
   return { bones, world, active, round: plant.round ?? gridRound };
@@ -1027,27 +1051,35 @@ function posedBoneStep(doc: CompiledDocument, timelines: CoreAnimationTimelines,
  * past the timelines for both.
  */
 function steppedLocals(doc: CompiledDocument, bones: ModelBone[], plant: TimelinePlant, records: () => CoreConstraintRecord[], physicsKeyed: NonNullable<CoreConstraintTimelines['physicsKeyed']>, t: number, sliders: SliderApplication[] | undefined, step: PoseStep): PosedStep {
+  const stage = plant.stage;
   const active = activeBones(doc);
   // The caller's adjustment, after the timelines and before anything reads the locals (`LocalAdjust`).
-  if (step.adjustment !== undefined) adjustLocals(doc, bones, step.adjustment.callback, step.adjustment.context);
-  let world = (plant.evaluate ?? worldTransforms)(bones, active);
+  if (step.adjustment !== undefined) {
+    if (stage !== undefined) stage.begin('timeline');
+    adjustLocals(doc, bones, step.adjustment.callback, step.adjustment.context);
+    if (stage !== undefined) stage.end('timeline');
+  }
+  if (stage !== undefined) stage.begin('world');
+  const initialWorld = (plant.evaluate ?? worldTransforms)(bones, active);
+  if (stage !== undefined) {
+    stage.end('world');
+    stage.begin('constraints');
+  }
   const stepped = stepPhysicsRecords(records(), physicsKeyed, t, active, step.ctx, step.before);
-  world = applyConstraints(bones, world, active, plant.constraints ? plant.constraints(stepped) : stepped, null, sliders, step.ctx, undefined, solverRules(plant.solver));
+  const world = applyConstraints(bones, initialWorld, active, plant.constraints ? plant.constraints(stepped) : stepped, null, sliders, step.ctx, undefined, solverRules(plant.solver));
+  if (stage !== undefined) stage.end('constraints');
   for (const b of bones) if (world.get(b.name) === undefined) throw new CoreInputError(`the evaluator returned no transform for bone "${b.name}"`);
   return { bones, world, active, round: plant.round ?? gridRound };
 }
 
 /**
- * `steppedLocals`' world transforms, the oracle's rows formed beside them when
- * `rows` is set (as `posedBoneWorld` forms them and `posedBoneWorldAlone` does
- * not): the live tracks' entry to the stepped phase (`./tracks.ts`). The
- * document's constraint records as they stand — the live tracks mix no
- * constraint timeline — and no physics timeline keyed.
+ * `steppedLocals`' world transforms, without the oracle's rows (as
+ * `posedBoneWorldAlone` poses them): the live tracks' entry to the stepped
+ * phase (`./tracks.ts`). The document's constraint records as they stand —
+ * the live tracks mix no constraint timeline — and no physics timeline keyed.
  */
-export function steppedLocalsWorld(doc: CompiledDocument, bones: ModelBone[], plant: TimelinePlant, sliders: SliderApplication[], step: PoseStep, rows: boolean): Map<string, CoreWorld> {
-  const posed = steppedLocals(doc, bones, plant, () => constraintRecords(doc), [], 0, sliders, step);
-  if (rows) stepRows(posed);
-  return posed.world;
+export function steppedLocalsWorld(doc: CompiledDocument, bones: ModelBone[], plant: TimelinePlant, sliders: SliderApplication[], step: PoseStep): Map<string, CoreWorld> {
+  return steppedLocals(doc, bones, plant, () => constraintRecords(doc), [], 0, sliders, step).world;
 }
 
 /** Each path record with the curve its slot shows deformed by the sample's own deform timelines at `t` (`./deform.ts`), or as it was. */

package/src/core/events.ts

@@ -33,6 +33,10 @@ import { gridRound } from './index.ts';
 
 /** An event definition, as the model states it (`ModelEvent`): the payload a key falls back to. */
 export interface CoreEventDef {
+  /** Audio metadata retained additively; the five-column oracle row is unchanged. */
+  audio?: string;
+  volume?: number;
+  balance?: number;
   name: string;
   int: number;
   float: number;
@@ -41,6 +45,9 @@ export interface CoreEventDef {
 
 /** One event key, as read: its time (float32) and the payload it fires with, each field resolved. */
 export interface CoreEventKey {
+  /** Audio delivery values, as observed from the public EventTimeline API. */
+  volume?: number;
+  balance?: number;
   time: number;
   name: string;
   int: number;
@@ -55,8 +62,8 @@ const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'obj
 const EVENT_DEF_FIELDS = ['name', 'int', 'float', 'string', 'audio', 'volume', 'balance'] as const;
 const EVENT_KEY_FIELDS = ['time', 'name', 'int', 'float', 'string', 'volume', 'balance'] as const;
 
-function payload(raw: Record<string, unknown>, at: string, problems: string[]): { int?: number; float?: number; string?: string } {
-  const out: { int?: number; float?: number; string?: string } = {};
+function payload(raw: Record<string, unknown>, at: string, problems: string[]): { int?: number; float?: number; string?: string; volume?: number; balance?: number } {
+  const out: { int?: number; float?: number; string?: string; volume?: number; balance?: number } = {};
   if (raw.int !== undefined) {
     if (typeof raw.int !== 'number' || !Number.isInteger(raw.int)) problems.push(`${at}: int is ${JSON.stringify(raw.int)}, not a whole number`);
     else out.int = raw.int;
@@ -69,7 +76,10 @@ function payload(raw: Record<string, unknown>, at: string, problems: string[]):
     if (typeof raw.string !== 'string') problems.push(`${at}: string is ${JSON.stringify(raw.string)}, not a string`);
     else out.string = raw.string;
   }
-  for (const key of ['volume', 'balance'] as const) if (raw[key] !== undefined && (typeof raw[key] !== 'number' || !Number.isFinite(raw[key]))) problems.push(`${at}: ${key} is ${JSON.stringify(raw[key])}, not a finite number`);
+  for (const key of ['volume', 'balance'] as const) if (raw[key] !== undefined) {
+    if (typeof raw[key] !== 'number' || !Number.isFinite(raw[key])) problems.push(`${at}: ${key} is ${JSON.stringify(raw[key])}, not a finite number`);
+    else out[key] = raw[key];
+  }
   return out;
 }
 
@@ -90,7 +100,7 @@ export function readEventDefs(value: unknown, problems: string[]): Map<string, C
     if (raw.audio !== undefined && typeof raw.audio !== 'string') problems.push(`${at} "${raw.name}": audio is ${JSON.stringify(raw.audio)}, not a string`);
     if (out.has(raw.name)) problems.push(`${at}: event "${raw.name}" is declared twice`);
     const p = payload(raw, `${at} "${raw.name}"`, problems);
-    out.set(raw.name, { name: raw.name, int: p.int ?? 0, float: p.float ?? 0, string: p.string ?? '' });
+    out.set(raw.name, { audio: typeof raw.audio === 'string' ? raw.audio : '', volume: p.volume ?? 0, balance: p.balance ?? 0, name: raw.name, int: p.int ?? 0, float: p.float ?? 0, string: p.string ?? '' });
   });
   return out;
 }
@@ -121,7 +131,9 @@ export function readEventKeys(value: unknown, label: string, defs: ReadonlyMap<s
       return;
     }
     const p = payload(raw, at, problems);
-    out.push({ time: Math.fround(typeof t === 'number' && Number.isFinite(t) ? t : 0), name: def.name, int: p.int ?? def.int, float: p.float ?? def.float, string: p.string ?? def.string });
+    // Observed oracle behavior: a voiced key's omitted balance falls back to
+    // the definition's volume, not its balance. A silent event keeps both at 0.
+    out.push({ volume: def.audio ? p.volume ?? def.volume ?? 0 : 0, balance: def.audio ? p.balance ?? def.volume ?? 0 : 0, time: Math.fround(typeof t === 'number' && Number.isFinite(t) ? t : 0), name: def.name, int: p.int ?? def.int, float: p.float ?? def.float, string: p.string ?? def.string });
   });
   return out;
 }

package/src/core/index.ts

@@ -176,7 +176,7 @@ import type { ModelAtlasRect, ModelBone, ModelEditorOrder, ModelPage, ModelPageR
 import { worldTransforms, type CoreWorld } from './world.ts';
 import { readAnimationTimelines, type CoreAnimationTimelines } from './animation.ts';
 import { readEventDefs, type CoreEventDef } from './events.ts';
-import { poseGeometry, readGeometry, type CoreAttachmentRow, type CoreClipRow, type CoreGeometry, type DrawWalk, type MeshArraysOf, type RegionPoser, type ShownGeometry, type VertexPoser } from './vertices.ts';
+import { poseGeometry, readGeometry, type CoreAttachmentRow, type CoreClipRow, type CoreGeometry, type DeformedVertexPoser, type DrawWalk, type MeshArraysOf, type RegionPoser, type ShownGeometry, type VertexPoser } from './vertices.ts';
 import type { CoreClippedRow, ShapeClipper, TriangleClipper } from './clipping.ts';
 import { applyConstraints, constraintsAbsentWhy, readConstraintRecord, readConstraintTimelines, solverRules, type ConstraintPlant, type CoreConstraintRecord, type CoreConstraintTimelines, type SolverRules } from './constraints.ts';
 import { readPathRecord } from './constraints_path.ts';
@@ -1062,6 +1062,23 @@ export type BlendReader = (slot: ModelSlot) => CoreBlendMode;
 /** What reads a stated light colour into its four channels: `readColour` unless a caller passes another. */
 export type ColourReader = (hex: string) => [number, number, number, number];
 
+/**
+ * The five pose stages a step passes through when instrumented (`StageHooks`,
+ * issue #1589):
+ * - `timeline`: timeline evaluation, animated bone local copy, attachment/deform/sequence timeline states
+ * - `world`: bone hierarchy world-transform composition (`worldTransforms`)
+ * - `constraints`: constraint record posing, physics step, and constraint solver orchestration (`applyConstraints`)
+ * - `geometry`: region corners, mesh/deformed world vertices, and triangle clipping (`drawnGeometry`)
+ * - `readout`: slot rows, draw-order resolution/sorting, bone rows, drawn row packaging, and events
+ */
+export type CoreStage = 'timeline' | 'world' | 'constraints' | 'geometry' | 'readout';
+
+/** Zero-cost-when-absent per-stage instrumentation callbacks on `CorePlant` (issue #1589). */
+export interface StageHooks {
+  begin(stage: CoreStage): void;
+  end(stage: CoreStage): void;
+}
+
 /**
  * What the core poses with, each part replaceable. The core suite's plants
  * pass a copy of one of them — a mode's sign flipped, the wrong skin, a
@@ -1077,6 +1094,8 @@ export interface CorePlant {
   region?: RegionPoser;
   /** A vertex array's world positions (`worldVertices` in `./vertices.ts`). */
   vertices?: VertexPoser;
+  /** A deformed vertex array's world positions (`deformedWorldVertices` in `./vertices.ts`). */
+  deformedVertices?: DeformedVertexPoser;
   /** A drawn mesh's read-only UVs and triangles (`meshArraysOf` in `./vertices.ts`) — the raw entry's `drawn`; nothing but a control passes one. */
   meshArrays?: MeshArraysOf;
   /** The ik, transform and path constraints as posed, rewritten before they are applied (`./constraints.ts`). */
@@ -1107,6 +1126,8 @@ export interface CorePlant {
    * `rawNumber`, the unrounded double.
    */
   round?: (v: number) => number | null;
+  /** Per-stage instrumentation callbacks for `tools/pose_bench.ts` (issue #1589); absent on every uninstrumented walk. */
+  stage?: StageHooks;
 }
 
 /** The document's ik, transform and path constraint records, in its order — what `applyConstraints` runs. */
@@ -1166,6 +1187,46 @@ export function readColour(hex: string): [number, number, number, number] {
   return [channel(0), channel(1), channel(2), hex.length === 8 ? channel(3) : 1];
 }
 
+/** A stated colour's channels, read once and shared (`viewColours`): read, or copied before a write — never handed out. */
+export type StatedColour = Readonly<[number, number, number, number]>;
+
+/** Each view's stated colours, by spelling, read once (`viewColours`). */
+const coloursOfView = new WeakMap<CompiledDocument, Map<string, StatedColour>>();
+
+/**
+ * The view's reader of a stated colour: `readColour(hex)` read the first time
+ * the view meets that spelling and kept, frozen, for every pose after it. The
+ * slot rows read every slot's colours on every pose, and a drawn row its
+ * record's (the parse was a measured share of a step). The reading is the
+ * spelling's alone, so the cache is keyed on the spelling rather than on a
+ * slot or a record — a colour respelled in place reads its new spelling, and
+ * a view built anew starts its own. The tuple is shared by every pose, so no
+ * caller hands it out or writes it (`StatedColour` is read-only): a pose's
+ * channels are copied out of it. It is not frozen because a frozen array is
+ * read several times slower under JavaScriptCore, measured on Bun 1.4.4, and
+ * the read is the whole of what the cache is for. The core suite's `CO63`
+ * holds a pose's colours to their spelling and to the pose.
+ */
+export function viewColours(doc: CompiledDocument): (hex: string) => StatedColour {
+  let kept = coloursOfView.get(doc);
+  if (kept === undefined) {
+    kept = new Map();
+    coloursOfView.set(doc, kept);
+  }
+  const colours = kept;
+  return (hex) => {
+    let c = colours.get(hex);
+    if (c === undefined) {
+      c = readColour(hex);
+      colours.set(hex, c);
+    }
+    return c;
+  };
+}
+
+/** A slot or record that states no light colour: white, opaque. */
+export const WHITE: StatedColour = [1, 1, 1, 1];
+
 /**
  * A slot's blend mode: `Normal` when it states none, else the stated
  * spelling folded (the header's measurement). `readModel` has already refused