rig-c 2.35.1 → 2.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-c",
-  "version": "2.35.1",
+  "version": "2.37.0",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/core/animation.ts

@@ -706,6 +706,108 @@ export function posedBones(doc: CompiledDocument, timelines: CoreAnimationTimeli
   });
 }
 
+/**
+ * A player's bone-local adjustment (issue #1336): a function the live track
+ * (`openTrack`'s `adjust`, `./track.ts`) calls once per pose, after the
+ * animation's timelines have posed the bone locals at the step's time and
+ * before the world transforms, the constraints and the physics step — so a
+ * write is what the rest of the step reads: the bone's children, the
+ * attachments drawn through it, every constraint and the physics constraint
+ * stepped on top of it. It is spine-core's "application code" writing
+ * `Bone.pose` between `AnimationState.apply` and `updateWorldTransform`
+ * (`CO50` holds the two equal at tolerance 0).
+ *
+ * - **The view is the step's locals, posed from the setup pose.** Every pose
+ *   of a walk is posed from the setup pose at its time (`./raw.ts`,
+ *   `TrackState`), so a write lives for the pose it was written in and the
+ *   next step's hook reads the timelines' value again, not the write. A
+ *   channel no timeline keys reads its setup value on every step.
+ * - **A bone the hook does not write is untouched**: the timelines' bone
+ *   object as it was, the setup bone itself where nothing keys it. A written
+ *   bone is copied before the write, so the document is never written.
+ * - **A write that is not a finite number is refused by name**, the bone, the
+ *   channel and the value — where the core refuses a non-finite value, by
+ *   name, rather than posing a picture with it (`finite` in `./raw.ts`).
+ */
+export interface BoneLocals {
+  rotation: number;
+  x: number;
+  y: number;
+  scaleX: number;
+  scaleY: number;
+  shearX: number;
+  shearY: number;
+}
+
+/** The locals of a step's bones, by name (`BoneLocals`). */
+export interface AdjustableLocals {
+  /** The document's bones, in its order. */
+  readonly names: readonly string[];
+  /** One bone's locals, read and written in place; a name the document has no bone for is refused by name. */
+  bone(name: string): BoneLocals;
+}
+
+/** What `openTrack`'s `adjust` is: called once per pose with the step's locals (`BoneLocals`). */
+export type LocalAdjust = (locals: AdjustableLocals) => void;
+
+/** The seven channels a `BoneLocals` reads and writes, each with the value an unstated one reads as (`worldTransforms`' defaults). */
+const LOCAL_CHANNELS = { rotation: 0, x: 0, y: 0, scaleX: 1, scaleY: 1, shearX: 0, shearY: 0 } as const;
+type LocalChannel = keyof typeof LOCAL_CHANNELS;
+
+/** One bone of a step's `bones`, read through and written through, copied on its first write (`BoneLocals`' second rule). */
+class StepLocals implements BoneLocals {
+  constructor(
+    private readonly bones: ModelBone[],
+    private readonly index: number,
+    private readonly setup: ModelBone,
+  ) {}
+
+  private read(channel: LocalChannel): number {
+    return this.bones[this.index][channel] ?? LOCAL_CHANNELS[channel];
+  }
+
+  private write(channel: LocalChannel, value: number): void {
+    if (typeof value !== 'number' || !Number.isFinite(value)) throw new CoreInputError(`the adjustment wrote bone "${this.setup.name}" ${channel} = ${String(value)}, not a finite number`);
+    if (this.bones[this.index] === this.setup) this.bones[this.index] = { ...this.setup };
+    this.bones[this.index][channel] = value;
+  }
+
+  get rotation(): number { return this.read('rotation'); }
+  set rotation(v: number) { this.write('rotation', v); }
+  get x(): number { return this.read('x'); }
+  set x(v: number) { this.write('x', v); }
+  get y(): number { return this.read('y'); }
+  set y(v: number) { this.write('y', v); }
+  get scaleX(): number { return this.read('scaleX'); }
+  set scaleX(v: number) { this.write('scaleX', v); }
+  get scaleY(): number { return this.read('scaleY'); }
+  set scaleY(v: number) { this.write('scaleY', v); }
+  get shearX(): number { return this.read('shearX'); }
+  set shearX(v: number) { this.write('shearX', v); }
+  get shearY(): number { return this.read('shearY'); }
+  set shearY(v: number) { this.write('shearY', v); }
+}
+
+/** The adjustment run over a step's `bones` (`posedBones`' array, in the document's order), which it may replace bone by bone (`BoneLocals`). */
+function adjustLocals(doc: CompiledDocument, bones: ModelBone[], adjust: LocalAdjust): void {
+  const views = new Map<string, StepLocals>();
+  const names = doc.bones.map((b) => b.name);
+  adjust({
+    names,
+    bone(name: string): BoneLocals {
+      let view = views.get(name);
+      if (view === undefined) {
+        const index = names.indexOf(name);
+        if (index < 0) throw new CoreInputError(`the adjustment asked for bone ${JSON.stringify(name)}, which is not one of this document's bones`);
+        // A copy the timelines made is this step's own; the setup bone is the document's, copied on its first write.
+        view = new StepLocals(bones, index, doc.bones[index]);
+        views.set(name, view);
+      }
+      return view;
+    },
+  });
+}
+
 const clamp01 = (v: number): number => (v < 0 ? 0 : v > 1 ? 1 : v);
 
 /**
@@ -722,22 +824,13 @@ 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 resolve = plant.shown ?? shownAttachment;
   const colour = plant.colour ?? readColour;
-  const blend = plant.blend ?? readBlend;
-  const round = plant.round ?? gridRound;
   const byName = new Map(timelines.slots.map((s) => [s.name, s]));
-  const rows: CoreSlotRow[] = [];
-  const conflicts: string[] = [];
-  const active = activeBones(doc);
-  const gate = plant.slotTimelines ?? slotTimelinesApply;
-  for (const slot of doc.slots) {
+  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 dark = setupDark === null ? null : [setupDark[0], setupDark[1], setupDark[2]];
-    // A slot on a bone the skin leaves inactive is not animated — not by the sample's timelines, not by a slider (`./skins.ts`).
-    const live = gate(doc, slot, active);
     for (const tl of live ? (byName.get(slot.name)?.timelines ?? []) : []) {
       if (tl.kind === 'attachment') {
         const key = keyAt(tl.keys, t, plant);
@@ -753,6 +846,48 @@ export function posedSlots(
         else if (dark !== null && setupDark !== null) dark[at - 4] = v === null ? setupDark[at - 4] : clamp01(v[i]);
       });
     }
+    return { placeholder, light, dark };
+  });
+}
+
+/**
+ * What a slot holds once the timelines have posed it and before the sliders:
+ * the placeholder it shows, its light colour and its dark one (`null` where
+ * the slot states none). `posedSlots` reads it off one animation at `t`; the
+ * live tracks off their mixed entries (`./tracks.ts`, issue #1336).
+ */
+export interface SlotBase {
+  placeholder: string | null;
+  light: number[];
+  dark: number[] | null;
+}
+
+/**
+ * The slot rows from each slot's `SlotBase` — `baseOf`, called once per slot
+ * in the document's order with whether the slot is animated at all — then the
+ * sliders, the resolution and the oracle's row: `posedSlots`' body past the
+ * timelines, which the live tracks share (`./tracks.ts`).
+ */
+export function slotRowsFrom(
+  doc: CompiledDocument,
+  plant: TimelinePlant,
+  sliders: readonly SliderApplication[],
+  placeholders: Map<string, string | null> | undefined,
+  baseOf: (slot: ModelSlot, live: boolean) => SlotBase,
+): { rows: CoreSlotRow[]; conflicts: string[] } {
+  const resolve = plant.shown ?? shownAttachment;
+  const blend = plant.blend ?? readBlend;
+  const round = plant.round ?? gridRound;
+  const rows: CoreSlotRow[] = [];
+  const conflicts: string[] = [];
+  const active = activeBones(doc);
+  const gate = plant.slotTimelines ?? slotTimelinesApply;
+  for (const slot of doc.slots) {
+    // A slot on a bone the skin leaves inactive is not animated — not by the sample's timelines, not by a slider (`./skins.ts`).
+    const live = gate(doc, slot, active);
+    const base = baseOf(slot, live);
+    let placeholder = base.placeholder;
+    const { light, dark } = base;
     // The sliders, after the animation, in constraint order (`./constraints_slider.ts`).
     // What the slot shows after the sample's own timelines: the attachments' deform and sequence timelines are matched against it (`./deform.ts`, *A switch*).
     placeholders?.set(slot.name, placeholder);
@@ -778,6 +913,21 @@ export function posedSlots(
   return { rows, conflicts };
 }
 
+/**
+ * One step of the stepped phase, as a walk hands it to the bones: the physics
+ * context and the clock before the step (`./constraints_physics.ts`), and the
+ * caller's adjustment of the locals (`LocalAdjust`). The adjustment rides here
+ * rather than on the plant because it is not a rule the core measured and a
+ * control plants back — it is the caller's input to one walk — and because
+ * the step context exists exactly where a walk is stepped: the live track's
+ * every pose but a `reset: 'setup'` pose 0, which no animation is applied to.
+ */
+export interface PoseStep {
+  ctx: PhysicsStepContext;
+  before: number;
+  adjust?: LocalAdjust;
+}
+
 /**
  * The bone rows at `t`, in the oracle's shape and rounding. With `constraints`
  * — the animation's constraint timelines — the document's constraints are
@@ -792,7 +942,7 @@ 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?: { ctx: PhysicsStepContext; before: number }): { rows: CoreBoneRow[]; world: Map<string, CoreWorld> } {
+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 };
 }
@@ -804,7 +954,7 @@ export function posedBoneWorld(doc: CompiledDocument, timelines: CoreAnimationTi
  * 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.
  */
-export function posedBoneWorldAlone(doc: CompiledDocument, timelines: CoreAnimationTimelines, t: number, plant: TimelinePlant, constraints: CoreConstraintTimelines | undefined, sliders: SliderApplication[] | undefined, step: { ctx: PhysicsStepContext; before: number } | undefined): Map<string, CoreWorld> {
+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;
 }
 
@@ -835,15 +985,15 @@ 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: { ctx: PhysicsStepContext; before: number } | undefined): PosedStep {
-  const active = activeBones(doc);
+function posedBoneStep(doc: CompiledDocument, timelines: CoreAnimationTimelines, t: number, plant: TimelinePlant, constraints: CoreConstraintTimelines | undefined, sliders: SliderApplication[] | undefined, step: PoseStep | undefined): PosedStep {
   const bones = posedBones(doc, timelines, t, plant);
+  // 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);
+  const active = activeBones(doc);
+  // The caller's adjustment, after the timelines and before anything reads the locals (`LocalAdjust`).
+  if (step?.adjust !== undefined) adjustLocals(doc, bones, step.adjust);
   let world = (plant.evaluate ?? worldTransforms)(bones, active);
-  if (constraints !== undefined && step !== undefined) {
-    // 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. No previous pass: under the step it is the previous step's, and `poseAnimations` leaves such bones out.
-    const records = stepPhysicsRecords(pathDeformed(doc, posedRecords(constraintRecords(doc), constraints, t), timelines, t, plant), constraints.physicsKeyed ?? [], t, active, step.ctx, step.before);
-    world = applyConstraints(bones, world, active, plant.constraints ? plant.constraints(records) : records, null, sliders, step.ctx, undefined, solverRules(plant.solver));
-  } else if (constraints !== undefined) {
+  if (constraints !== undefined) {
     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);
@@ -855,6 +1005,40 @@ function posedBoneStep(doc: CompiledDocument, timelines: CoreAnimationTimelines,
   return { bones, world, active, round: plant.round ?? gridRound };
 }
 
+/**
+ * One step of the stepped phase from locals already posed (issue #1336): the
+ * caller's adjustment (`LocalAdjust`), the world transforms, the physics
+ * records posed by `records` and stepped under the walk's context, then every
+ * constraint. No previous pass: under the step it is the previous step's, and
+ * `poseAnimations` leaves such bones out. A single animation's walk reaches it
+ * through `posedBoneStep` with the locals `posedBones` posed; the live tracks
+ * (`./tracks.ts`) with the locals their mixed entries posed — one pose path
+ * 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 active = activeBones(doc);
+  // The caller's adjustment, after the timelines and before anything reads the locals (`LocalAdjust`).
+  if (step.adjust !== undefined) adjustLocals(doc, bones, step.adjust);
+  let world = (plant.evaluate ?? worldTransforms)(bones, active);
+  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));
+  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.
+ */
+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;
+}
+
 /** 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. */
 function pathDeformed(doc: CompiledDocument, records: CoreConstraintRecord[], timelines: CoreAnimationTimelines, t: number, plant: TimelinePlant): CoreConstraintRecord[] {
   if (timelines.attachments.every((a) => a.deform === null)) return records;

package/src/core/deform.ts

@@ -536,6 +536,14 @@ export function attachmentStates(
   sample: { timelines: CoreAnimationTimelines; t: number } | null,
   sliders: readonly AttachmentApplication[],
   plant: { deform?: DeformEvaluator; deformBlend?: DeformBlender; sequence?: SequenceEvaluator; slotTimelines?: SlotTimelineGate } = {},
+  /**
+   * The live tracks' deforms (`./tracks.ts`, issue #1336), in place of a
+   * sample's: each slot's deform array as the mixed entries left it (`null`
+   * none) and the records their deform timelines keyed on it — what the
+   * sample's own timelines would have set and seen. Absent on every other
+   * caller.
+   */
+  mixed?: ReadonlyMap<string, { deform: number[] | null; seen: readonly string[] }>,
 ): { shown: ShownGeometry[]; why: string[] } {
   const evalDeform = plant.deform ?? deformAt;
   const blendOf = plant.deformBlend ?? blendDeform;
@@ -548,9 +556,10 @@ export function attachmentStates(
     // A slot on a bone the skin leaves inactive is not animated: no deform, no frame, no slider switch (`./skins.ts`).
     const live = gate(doc, slot, active);
     let placeholder = placeholders.get(slot.name) ?? null;
-    let deform: number[] | null = null;
+    const base = live ? mixed?.get(slot.name) : undefined;
+    let deform: number[] | null = base?.deform ?? null;
     let frame: number | null = null;
-    const seen: string[] = [];
+    const seen: string[] = base === undefined ? [] : [...base.seen];
     // What the slot shows now, the record its timelines are keyed as, and what a deform or a frame is computed on.
     const state = (): { s: CoreShown; identity: string | null; vertices: ModelVertices | null; count: number | undefined } | null => {
       if (placeholder === null) return null;

package/src/core/entry.ts

@@ -16,7 +16,8 @@
  * browser and holds the bundle to zero `node:` strings.
  *
  * ⚠️ A symbol is listed here only because a dependant was seen using it,
- * or asked for it in writing before it could be (`openTrack`, issue #1276).
+ * or asked for it in writing before it could be (`openTrack`, issue #1276;
+ * `openTracks`, issue #1336).
  * The list is `scripts/install_smoke.ts`'s `OBSERVED_SYMBOLS` rows for
  * `./core`, and a symbol added here and not there is not promised.
  */
@@ -26,7 +27,9 @@ export { poseRawSetup, poseRawAnimation, poseRawAnimationEach, loopedTime, setup
 export type { RawPose, RawBone, RawDrawn, RawClip, RawClipped, RawEvent, RawReset } from './raw.ts';
 export { poseWalkSetup, poseLoopingWalk } from './walk.ts';
 export { openTrack } from './track.ts';
-export type { LiveTrack, TrackOptions } from './track.ts';
+export type { LiveTrack, TrackOptions, AdjustableLocals, BoneLocals, LocalAdjust } from './track.ts';
+export { openTracks } from './tracks.ts';
+export type { LiveTracks, TracksOptions, MixOptions, QueueOptions, TrackEntryView } from './tracks.ts';
 export type { WalkPose } from './walk.ts';
 export { documentPageLookup, drawnRegions, regionPageUvs, meshPageUvs, readUvSequences } from './uvs.ts';
 export type { DrawnRegion, UvPage, UvRegion, UvSource } from './uvs.ts';

package/src/core/raw.ts

@@ -114,12 +114,12 @@
  * missing would draw a different picture in silence.
  */
 import { activeBones, CoreInputError, drawWalkOf, poseSetup, rawNumber, readColour, shownAttachment, sourceOfDoc, underNoSkin, type CompiledDocument, type CorePlant, type CoreSlotRow } from './index.ts';
-import { posedBoneWorld, posedBoneWorldAlone, posedSlots, type TimelinePlant } from './animation.ts';
+import { posedBoneWorld, posedBoneWorldAlone, posedSlots, type CoreAnimationTimelines, type LocalAdjust, type TimelinePlant } from './animation.ts';
 import { constraintsAbsentWhy, pathAnimationsWhy } from './constraints.ts';
 import { freshStepContext, steppedPreviousPassWhy } from './constraints_physics.ts';
 import { attachmentStates } from './deform.ts';
-import { drawOrderAt } from './draw_order.ts';
-import { eventsFired } from './events.ts';
+import { drawOrderAt, type CoreDrawOrderKey } from './draw_order.ts';
+import { eventsFired, type CoreEventRow } from './events.ts';
 import { REGION_TRIANGLES, REGION_UVS, type CoreClippedRow, type ShapeClipper } from './clipping.ts';
 import { poseGeometry, type CoreAttachmentRow, type CoreClipRow, type ShownGeometry } from './vertices.ts';
 import { RUNTIME_DEG, type CoreWorld } from './world.ts';
@@ -612,6 +612,8 @@ export interface TrackState<P> {
   readonly resolve: NonNullable<TimelinePlant['shown']>;
   readonly shape: PoseShape<P>;
   readonly ctx: ReturnType<typeof freshStepContext>;
+  /** The caller's adjustment of each step's locals (`LocalAdjust` in `./animation.ts`): the live track's `adjust`, absent on every batch walk. */
+  readonly adjust?: LocalAdjust;
   /** The running sum of the steps taken. */
   trackTime: number;
   /** The animation time of the step before, −1 before the first. */
@@ -631,12 +633,12 @@ function animationOf(doc: CompiledDocument, animation: string): CompiledDocument
  * `reset: 'setup'` pose 0 is the setup pose, reset; under `animation` it is the
  * animation applied at 0 and reset there, a step of 0 (`stepWalk`'s `first`).
  */
-function openWalk<P>(doc: CompiledDocument, anim: CompiledDocument['animations'][number], plant: TimelinePlant, reset: RawReset, mode: WalkMode, shape: PoseShape<P>): { track: TrackState<P>; first: P } {
+function openWalk<P>(doc: CompiledDocument, anim: CompiledDocument['animations'][number], plant: TimelinePlant, reset: RawReset, mode: WalkMode, shape: PoseShape<P>, adjust?: LocalAdjust): { track: TrackState<P>; first: P } {
   const why = constraintsAbsentWhy(doc) ?? pathAnimationsWhy(doc) ?? steppedPreviousPassWhy(doc);
   if (why !== null) throw new CoreInputError(`the raw walk leaves the bones out: ${why}`);
   const ctx = freshStepContext(plant.physicsStep);
   if (mode.loop && mode.wrapResets !== false) ctx.loop = true;
-  const track: TrackState<P> = { doc, anim, duration: anim.timelines.duration, mode, plant, raw: { ...plant, ...roundPlant(mode) }, resolve: plant.shown ?? shownAttachment, shape, ctx, trackTime: 0, last: -1 };
+  const track: TrackState<P> = { doc, anim, duration: anim.timelines.duration, mode, plant, raw: { ...plant, ...roundPlant(mode) }, resolve: plant.shown ?? shownAttachment, shape, ctx, adjust, trackTime: 0, last: -1 };
   if (reset === 'setup') {
     // The reset taken at the setup pose, before the animation is applied (`src/deformmeasure.ts`'s `poseAt`): pose 0 is the setup pose.
     const setup = poseSetup(doc, { ...plant, ...roundPlant(mode) }, ctx);
@@ -657,35 +659,112 @@ function openWalk<P>(doc: CompiledDocument, anim: CompiledDocument['animations']
  * resets the physics there — and nothing else passes it.
  */
 function stepWalk<P>(track: TrackState<P>, dt: number, first = false): P {
-  const { doc, anim, duration, mode, plant, raw, resolve, shape, ctx } = track;
+  const { doc, anim, duration, mode, plant, raw, resolve, shape, ctx, adjust } = track;
   track.trackTime += dt;
   const trackTime = track.trackTime;
   const last = track.last;
   const t = mode.loop ? (mode.time ?? loopedTime)(trackTime, duration, trackTime - dt) : trackTime < duration ? trackTime : duration;
   const before = ctx.time;
   ctx.time += mode.clock === undefined ? dt : mode.clock(dt, t - (first ? 0 : Math.max(last, 0)));
+  // A10's looping walk fires no event here — its one reader reads none — nor cuts its drawn attachments through a clip (`NO_CLIPPED_ROWS`), so its
+  // `clipped` rows are empty. The live track's looping mode (`live`) fires its events across the wrap by the rule `./track.ts` states as measured.
+  const fire = plant.events ?? eventsFired;
+  const keys = anim.timelines.events;
+  const pose = poseStepFrom(doc, plant, resolve, shape, mode, ctx, first, trackTime, t, {
+    world: (sliders) => (shape.rows ? posedBoneWorld(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before, adjust }).world : posedBoneWorldAlone(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before, adjust })),
+    slots: (sliders, placeholders) => posedSlots(doc, anim.timelines, t, raw, sliders, placeholders),
+    drawOrder: anim.timelines.drawOrder,
+    at: t,
+    sample: { timelines: anim.timelines, t },
+    events: () => (mode.loop && mode.live !== true ? [] : mode.loop ? fire(keys, last, t, rawNumber, t < last) : fire(keys, last, t, rawNumber)),
+  });
+  track.last = t;
+  return pose;
+}
+
+/**
+ * What decides one step's pose before it is assembled (issue #1336): the bone
+ * world through the stepped phase, filling the sliders it applied; the slot
+ * rows, filling the placeholders the timelines left; the draw-order keys and
+ * the time they are read at; the deform and sequence timelines' sample, or the
+ * mixed deforms in its place; the events, computed when called. A walk's step
+ * reads every one off one animation at its time (`stepWalk`); the live tracks
+ * off their mixed entries (`./tracks.ts`). Everything past these is one body,
+ * `poseStepFrom`.
+ */
+export interface StepPosers {
+  world: (sliders: SliderApplication[]) => Map<string, CoreWorld>;
+  slots: (sliders: readonly SliderApplication[], placeholders: Map<string, string | null>) => { rows: CoreSlotRow[]; conflicts: string[] };
+  drawOrder: readonly CoreDrawOrderKey[];
+  at: number;
+  sample: { timelines: CoreAnimationTimelines; t: number } | null;
+  mixed?: ReadonlyMap<string, { deform: number[] | null; seen: readonly string[] }>;
+  events: () => CoreEventRow[];
+}
+
+/**
+ * One step's pose from what decided it (`StepPosers`): the bone world, the
+ * physics phase moved past the reset on `first`, the slot rows, the draw
+ * order (the keys' order, else the setup's, then each slider's key), the
+ * attachments drawn in it, and the pose assembled in `shape` — refused by name
+ * where the core leaves a block out, in that order. The one body a walk's step
+ * and a live tracks' step share.
+ */
+function poseStepFrom<P>(doc: CompiledDocument, plant: TimelinePlant, resolve: NonNullable<TimelinePlant['shown']>, shape: PoseShape<P>, mode: WalkMode, ctx: ReturnType<typeof freshStepContext>, first: boolean, trackTime: number, animationTime: number, posers: StepPosers): P {
   const sliders: SliderApplication[] = [];
-  const world = shape.rows ? posedBoneWorld(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before }).world : posedBoneWorldAlone(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before });
+  const world = posers.world(sliders);
   if (first) ctx.phase = 'update';
   const placeholders = new Map<string, string | null>();
-  const slots = posedSlots(doc, anim.timelines, t, raw, sliders, placeholders);
+  const slots = posers.slots(sliders, placeholders);
   if (slots.conflicts.length > 0) throw new CoreInputError(`the raw walk leaves the slots out: ${slots.conflicts.join('; ')}`);
   const evalOrder = plant.drawOrder ?? drawOrderAt;
-  let order = evalOrder(doc.slots.length, anim.timelines.drawOrder, t) ?? doc.slots.map((_s, k) => k);
+  let order = evalOrder(doc.slots.length, posers.drawOrder, posers.at) ?? doc.slots.map((_s, k) => k);
   for (const app of sliders) order = evalOrder(doc.slots.length, app.timelines.drawOrder, app.at) ?? order;
   const drawOrder = order.map((k) => doc.slots[k].name);
-  const states = attachmentStates(doc, resolve, placeholders, { timelines: anim.timelines, t }, sliders, plant);
+  const states = attachmentStates(doc, resolve, placeholders, posers.sample, sliders, plant, posers.mixed);
   if (states.why.length > 0) throw new CoreInputError(`the raw walk leaves the attachments out: ${states.why.join('; ')}`);
   const rank = new Map(drawOrder.map((n, r) => [n, r]));
   const shown = [...states.shown].sort((a, b) => (rank.get(a.slot) ?? 0) - (rank.get(b.slot) ?? 0));
-  // A10's looping walk fires no event here — its one reader reads none — nor cuts its drawn attachments through a clip (`NO_CLIPPED_ROWS`), so its
-  // `clipped` rows are empty. The live track's looping mode (`live`) fires its events across the wrap by the rule `./track.ts` states as measured.
-  const fire = plant.events ?? eventsFired;
-  const keys = anim.timelines.events;
-  const events = (): RawEvent[] => (mode.loop && mode.live !== true ? [] : (mode.loop ? fire(keys, last, t, rawNumber, t < last) : fire(keys, last, t, rawNumber)).map((e): RawEvent => [e[0], finite(e[1], 'event time'), e[2], finite(e[3], 'event float'), e[4]]));
-  const pose = shape.step(doc, { trackTime, animationTime: t, world, slots: slots.rows, drawOrder, shown, events }, plant, mode);
-  track.last = t;
-  return pose;
+  const events = (): RawEvent[] => posers.events().map((e): RawEvent => [e[0], finite(e[1], 'event time'), e[2], finite(e[3], 'event float'), e[4]]);
+  return shape.step(doc, { trackTime, animationTime, world, slots: slots.rows, drawOrder, shown, events }, plant, mode);
+}
+
+/**
+ * The live tracks' side of the raw pose path (issue #1336, `./tracks.ts`):
+ * the refusals a walk makes before its first pose, a fresh physics context,
+ * the plant with the raw entry's rounding, and the two ways a pose is made —
+ * the setup pose reset (`reset: 'setup'`'s pose 0) and one step from what the
+ * mixed entries decided, assembled as the raw entry's pose (`RAW_SHAPE`,
+ * `RAW_MODE`: a non-finite value refused, every clipped row cut).
+ */
+export interface RawTracksPath {
+  readonly ctx: ReturnType<typeof freshStepContext>;
+  /** `plant` with the raw entry's rounding. */
+  readonly raw: TimelinePlant;
+  setupPose(): RawPose;
+  step(first: boolean, trackTime: number, animationTime: number, posers: StepPosers): RawPose;
+}
+
+/** `RawTracksPath` opened on `doc`, refused by name where a walk on it would be (`openWalk`). */
+export function openRawTracksPath(doc: CompiledDocument, plant: TimelinePlant): RawTracksPath {
+  const why = constraintsAbsentWhy(doc) ?? pathAnimationsWhy(doc) ?? steppedPreviousPassWhy(doc);
+  if (why !== null) throw new CoreInputError(`the raw walk leaves the bones out: ${why}`);
+  const ctx = freshStepContext(plant.physicsStep);
+  const raw: TimelinePlant = { ...plant, ...roundPlant(RAW_MODE) };
+  const resolve = plant.shown ?? shownAttachment;
+  return {
+    ctx,
+    raw,
+    setupPose: () => {
+      const setup = poseSetup(doc, raw, ctx);
+      const absent = setup.absent.filter(([block]) => block !== 'setup.clipped');
+      if (absent.length > 0) throw new CoreInputError(`the raw walk's reset pose leaves ${absent.map(([b, w]) => `${b} out (${w})`).join('; ')}`);
+      if (setup.world === null || setup.shown === null || setup.setup.slots === null || setup.setup.drawOrder === null) throw new CoreInputError('the raw walk\'s reset pose was not posed');
+      ctx.phase = 'update';
+      return RAW_SHAPE.setup(doc, setup.world, setup.setup.slots, setup.setup.drawOrder, setup.shown, plant, RAW_MODE);
+    },
+    step: (first, trackTime, animationTime, posers) => poseStepFrom(doc, plant, resolve, RAW_SHAPE, RAW_MODE, ctx, first, trackTime, animationTime, posers),
+  };
 }
 
 /** `walkIn`'s walk, each pose assembled in `shape` and handed to `visit` in order as it is posed (`poseRawAnimationEach`): the walk opened, then stepped over `steps`. */
@@ -706,8 +785,8 @@ function walkEach<P>(doc: CompiledDocument, animation: string, steps: readonly n
  * `stepRawTrack` steps. Every pose is assembled as the raw entry's
  * (`RAW_SHAPE`).
  */
-export function openRawTrack(doc: CompiledDocument, animation: string, plant: TimelinePlant, reset: RawReset, mode: WalkMode): { track: TrackState<RawPose>; first: RawPose } {
-  return openWalk(doc, animationOf(doc, animation), plant, reset, mode, RAW_SHAPE);
+export function openRawTrack(doc: CompiledDocument, animation: string, plant: TimelinePlant, reset: RawReset, mode: WalkMode, adjust?: LocalAdjust): { track: TrackState<RawPose>; first: RawPose } {
+  return openWalk(doc, animationOf(doc, animation), plant, reset, mode, RAW_SHAPE, adjust);
 }
 
 /** One step of an opened raw track (`openRawTrack`): `walkIn`'s step, the step itself checked by the caller. */

package/src/core/track.ts

@@ -17,6 +17,11 @@
  * scan on A10's schedule and at 60 fps over three cycles — 157,771 poses, every
  * one the same bits (the PR of issue #1276 carries the table).
  *
+ * Several animations on several tracks, set, queued and mixed as spine-core's
+ * `AnimationState` mixes them, are `openTracks` (`./tracks.ts`, issue #1336):
+ * a second state machine over the same pose path past the timelines, which
+ * this track reaches with the locals its one animation posed.
+ *
  * ## The walk
  *
  * - **Held** (`loop: false`): the raw entry's walk — the track time the
@@ -95,6 +100,41 @@
  * and the events (4,009 of 4,009 on the tree row, 690 of them cutting 12,420
  * rows).
  *
+ * ## The adjustment (issue #1336)
+ *
+ * `adjust` is a player's own bone-local value — a breath's scale, a look's
+ * rotation — written onto the bones every pose, after the animation's
+ * timelines posed the locals at the step's time and before the world
+ * transforms, the constraints and the physics step (`LocalAdjust` in
+ * `./animation.ts`, which states the view's rules). It runs on every pose the
+ * animation is applied to — every `step`, and pose 0 under `reset:
+ * 'animation'` — and not on pose 0 under `reset: 'setup'`, the setup pose
+ * with nothing applied: a player applies its adjustment wherever it applies
+ * the animation state, the first frame included, and spine-core's reset at
+ * the setup pose applies none. Absent, every pose is the one the track posed
+ * before it existed, bit for bit (`CO46`, unchanged; `CO50` holds a hook that
+ * writes nothing to the same bits).
+ *
+ * `CO50` holds it to spine-core 4.3.13 on gallery/look, whose `head` carries
+ * the deformed head mesh and every face bone, and the physics-driven
+ * `ahoge_whip` two bones below it: the same `scaleY` written on `head` by the
+ * core's hook and on `Bone.pose` between `AnimationState.apply` and
+ * `updateWorldTransform(Physics.update)`, every bone's world transform and
+ * every drawn vertex equal at tolerance 0 over looping and held walks under
+ * both resets — spine-core's skeleton brought back to the setup pose
+ * (`setupPoseBones`) before each `apply`, which is the core's own reading:
+ * every pose is posed from the setup pose. Measured, and held red there:
+ *
+ * - **The write carried from frame to frame** — spine-core without that
+ *   reset, where no timeline writes an unkeyed channel back, so a `scaleY`
+ *   multiplied every frame compounds (every walk off from pose 2). The core
+ *   carries no local from one step to the next; a value a player wants
+ *   carried it keeps and writes again.
+ * - **The write at draw time** — made after `updateWorldTransform`, the
+ *   bone's own matrix alone brought up to date: the bone moves, its
+ *   children, the meshes they carry and the physics do not.
+ * - **Pose 0 not adjusted** under `reset: 'animation'`.
+ *
  * ## The oracle chain
  *
  * Nothing here is held to spine-core directly but the events: the live track
@@ -106,19 +146,22 @@
  *
  * ⛔ **A track refused part-way stays refused.** A step is checked before
  * anything moves; a refusal past that — a construct the core leaves out, a
- * non-finite vertex — comes after the track time and the physics have moved,
- * so every later `step` refuses naming the step it was refused at, and the
- * caller opens the track again. Seeking is the caller's too: a physics rig has
+ * non-finite vertex or write — comes after the track time and the physics
+ * have moved, so every later `step` refuses naming the step it was refused
+ * at, and the caller opens the track again. So does an error the caller's own
+ * `adjust` throws: it is thrown mid-step, after the same moves. Seeking is the caller's too: a physics rig has
  * history, so a seek is "open, then step to the time".
  */
 import { CoreInputError, type CompiledDocument } from './index.ts';
 import { openRawTrack, stepRawTrack, type RawPose, type RawReset, type TrackState, type WalkMode } from './raw.ts';
-import type { TimelinePlant } from './animation.ts';
+import type { LocalAdjust, TimelinePlant } from './animation.ts';
+export type { AdjustableLocals, BoneLocals, LocalAdjust } from './animation.ts';
 
-/** How a live track is opened: whether it loops, and where its physics is reset (`RawReset`). Both are the caller's and neither has a default. */
+/** How a live track is opened: whether it loops, and where its physics is reset (`RawReset`) — both the caller's, neither with a default — and the caller's adjustment of every pose's bone locals (the header's *The adjustment*). */
 export interface TrackOptions {
   loop: boolean;
   reset: RawReset;
+  adjust?: LocalAdjust;
 }
 
 /** A live track (`openTrack`): pose 0, then one pose per `step`. */
@@ -147,7 +190,8 @@ const LOOPED: WalkMode = { loop: true, keep: false, live: true };
 export function openTrack(doc: CompiledDocument, animation: string, options: TrackOptions, plant: TimelinePlant = {}): LiveTrack {
   if (typeof options !== 'object' || options === null || typeof options.loop !== 'boolean') throw new CoreInputError(`the live track's options.loop is ${JSON.stringify((options as Partial<TrackOptions> | null)?.loop)}, not true or false`);
   if (options.reset !== 'animation' && options.reset !== 'setup') throw new CoreInputError(`the live track's options.reset is ${JSON.stringify(options.reset)}, not "animation" or "setup"`);
-  const { track, first } = openRawTrack(doc, animation, plant, options.reset, options.loop ? LOOPED : HELD);
+  if (options.adjust !== undefined && typeof options.adjust !== 'function') throw new CoreInputError(`the live track's options.adjust is ${typeof options.adjust}, not a function`);
+  const { track, first } = openRawTrack(doc, animation, plant, options.reset, options.loop ? LOOPED : HELD, options.adjust);
   return new Track(track, first);
 }
 
@@ -186,7 +230,7 @@ class Track implements LiveTrack {
       this.latest = pose.animationTime;
       return pose;
     } catch (err) {
-      if (err instanceof CoreInputError) this.refused = `${n} (${err.message})`;
+      this.refused = `${n} (${err instanceof Error ? err.message : String(err)})`;
       throw err;
     }
   }