rig-c 2.36.0 → 2.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-c",
-  "version": "2.36.0",
+  "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

@@ -824,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);
@@ -855,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);
@@ -953,16 +986,14 @@ 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 active = activeBones(doc);
   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);
@@ -974,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.
  */
@@ -27,6 +28,8 @@ export type { RawPose, RawBone, RawDrawn, RawClip, RawClipped, RawEvent, RawRese
 export { poseWalkSetup, poseLoopingWalk } from './walk.ts';
 export { openTrack } 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 LocalAdjust, 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';
@@ -666,28 +666,105 @@ function stepWalk<P>(track: TrackState<P>, dt: number, first = false): P {
   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, adjust }).world : posedBoneWorldAlone(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before, adjust });
+  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`. */

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