rig-c 2.34.0 → 2.35.0

package/package.json

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

package/src/core/entry.ts

@@ -15,8 +15,9 @@
  * `CUR123` holds the closure, by name; the install smoke bundles it for a
  * browser and holds the bundle to zero `node:` strings.
  *
- * ⚠️ A symbol is listed here only because a dependant was seen using it.
- * The list is `scripts/install_smoke.ts`'s `OBSERVED_SYMBOLS` row for
+ * ⚠️ 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).
+ * The list is `scripts/install_smoke.ts`'s `OBSERVED_SYMBOLS` rows for
  * `./core`, and a symbol added here and not there is not promised.
  */
 export { readModel, underSkin, underNoSkin, CoreInputError, CORE_DOCUMENT_SPEC, CORE_DOCUMENT_SPECS, CORE_BLEND_MODES, activeBones } from './index.ts';
@@ -24,6 +25,8 @@ export type { CompiledDocument, CoreSlotRow, CoreBlendMode } from './index.ts';
 export { poseRawSetup, poseRawAnimation, poseRawAnimationEach, loopedTime, setupBounds } from './raw.ts';
 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 { 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/events.ts

@@ -126,10 +126,18 @@ export function readEventKeys(value: unknown, label: string, defs: ReadonlyMap<s
   return out;
 }
 
-/** What lists the events fired over `(last, t]`: `eventsFired` unless a plant passes another. */
-export type EventsFired = (keys: readonly CoreEventKey[], last: number, t: number, round?: (v: number) => number | null) => CoreEventRow[];
+/** What lists the events fired over `(last, t]` — or across the wrap when `wrapped` — : `eventsFired` unless a plant passes another. */
+export type EventsFired = (keys: readonly CoreEventKey[], last: number, t: number, round?: (v: number) => number | null, wrapped?: boolean) => CoreEventRow[];
 
-/** The rows of the keys fired over `(last, t]`, in key order — the header's rules, rounded as the oracle rounds. */
-export function eventsFired(keys: readonly CoreEventKey[], last: number, t: number, round: (v: number) => number | null = gridRound): CoreEventRow[] {
-  return keys.filter((k) => k.time > last && k.time <= t).map((k): CoreEventRow => [k.name, round(k.time), k.int, round(k.float), k.string]);
+/**
+ * The rows of the keys fired over `(last, t]`, in key order — the header's
+ * rules, rounded as the oracle rounds. `wrapped` is a looping track's step
+ * whose animation time went down (`t < last`, the wrap): the keys after
+ * `last`, in key order, then the keys at or before `t`, in key order — the
+ * header's *Across the wrap*. Nothing but a looping track passes it.
+ */
+export function eventsFired(keys: readonly CoreEventKey[], last: number, t: number, round: (v: number) => number | null = gridRound, wrapped = false): CoreEventRow[] {
+  const row = (k: CoreEventKey): CoreEventRow => [k.name, round(k.time), k.int, round(k.float), k.string];
+  if (wrapped) return [...keys.filter((k) => k.time > last), ...keys.filter((k) => k.time <= t)].map(row);
+  return keys.filter((k) => k.time > last && k.time <= t).map(row);
 }

package/src/core/raw.ts

@@ -261,6 +261,13 @@ export interface WalkMode {
   clock?: (dt: number, moved: number) => number;
   /** A plant only (`CO26`): `false` fires no `reset` key across the wrap — the reading the walk was measured against and rejected. */
   wrapResets?: boolean;
+  /**
+   * The live track's looping mode (`./track.ts`, issue #1276): a looping walk
+   * that fires its events across the wrap and cuts its clipped rows, as the
+   * raw entry does. Absent on A10's looping walk (`./walk.ts`), which does
+   * neither — its one reader reads no event and no clipped row.
+   */
+  live?: boolean;
 }
 
 /** The raw entry's mode: a track that holds at its duration, and a non-finite value refused. */
@@ -332,7 +339,7 @@ function scanBones(doc: CompiledDocument, world: ReadonlyMap<string, CoreWorld>)
  */
 function drawnGeometry(doc: CompiledDocument, shown: readonly ShownGeometry[], world: ReadonlyMap<string, CoreWorld>, order: readonly string[], plant: CorePlant, mode: WalkMode): { rows: CoreAttachmentRow[]; clips: CoreClipRow[]; drawnClipped: CoreClippedRow[] } {
   const draw = drawWalkOf(doc, order, plant);
-  const geometry = poseGeometry(shown, world, sourceOfDoc(doc), mode.keep ? keptNumber : rawNumber, { region: plant.region, vertices: plant.vertices }, mode.loop && plant.through === undefined ? { ...draw, through: NO_CLIPPED_ROWS } : draw);
+  const geometry = poseGeometry(shown, world, sourceOfDoc(doc), mode.keep ? keptNumber : rawNumber, { region: plant.region, vertices: plant.vertices }, mode.loop && mode.live !== true && plant.through === undefined ? { ...draw, through: NO_CLIPPED_ROWS } : draw);
   if (geometry.attachments === null) throw new CoreInputError(`the raw pose leaves the attachments out: ${geometry.attachmentsWhy}`);
   // The drawn rows (issue #964): the oracle's `clipped` rows where it is posed, and a concave or inverse clip cut through the core's own decomposition.
   if (geometry.drawnClipped === null) throw new CoreInputError(`the raw pose leaves the clipped triangles out: ${geometry.drawnClippedWhy}`);
@@ -583,22 +590,53 @@ function scanShape(scanPlant: ScanPlant): PoseShape<ScanPose> {
 }
 const SCAN_SHAPE: PoseShape<ScanPose> = scanShape({});
 
-/** `walkIn`'s walk, each pose assembled in `shape` and handed to `visit` in order as it is posed (`poseRawAnimationEach`). */
-function walkEach<P>(doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant, reset: RawReset, mode: WalkMode, shape: PoseShape<P>, visit: (pose: P, index: number) => void): void {
+/**
+ * A walk between two of its steps (issue #1276): everything `walkEach` carries
+ * from one step to the next, held in one object, so the walk can be stepped one
+ * `dt` at a time (`openTrack` in `./track.ts`) as well as over a list. That is
+ * the physics context (`ctx`: the skeleton's clock, the phase, each physics
+ * constraint's state, the animation time a `reset` key is crossed from, whether
+ * the track loops), the running track time, the animation time of the step
+ * before (−1 before the first) and what the walk was opened with. Nothing else
+ * survives a step: every pose is posed from the setup pose at its time.
+ */
+export interface TrackState<P> {
+  readonly doc: CompiledDocument;
+  readonly anim: CompiledDocument['animations'][number];
+  /** The runtime's duration (`CoreAnimationTimelines.duration`). */
+  readonly duration: number;
+  readonly mode: WalkMode;
+  readonly plant: TimelinePlant;
+  /** `plant` with the mode's rounding (`roundPlant`). */
+  readonly raw: TimelinePlant;
+  readonly resolve: NonNullable<TimelinePlant['shown']>;
+  readonly shape: PoseShape<P>;
+  readonly ctx: ReturnType<typeof freshStepContext>;
+  /** The running sum of the steps taken. */
+  trackTime: number;
+  /** The animation time of the step before, −1 before the first. */
+  last: number;
+}
+
+/** The document's animation named `animation`, or the walk refused naming the document's animations. */
+function animationOf(doc: CompiledDocument, animation: string): CompiledDocument['animations'][number] {
   const anim = doc.animations.find((a) => a.name === animation);
   if (anim === undefined) throw new CoreInputError(`animation "${animation}" is not one of this document's [${doc.animations.map((a) => a.name).join(', ')}]`);
-  const bad = steps.findIndex((s) => !Number.isFinite(s) || s < 0);
-  if (bad >= 0) throw new CoreInputError(`step ${bad} is ${steps[bad]}, not a finite time at or above 0`);
+  return anim;
+}
+
+/**
+ * A walk opened (issue #1276): the refusals a walk makes before its first pose,
+ * then pose 0 — the reset — and the state the walk steps on from. Under
+ * `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 } {
   const why = constraintsAbsentWhy(doc) ?? pathAnimationsWhy(doc) ?? steppedPreviousPassWhy(doc);
   if (why !== null) throw new CoreInputError(`the raw walk leaves the bones out: ${why}`);
-  const raw: TimelinePlant = { ...plant, ...roundPlant(mode) };
-  const resolve = plant.shown ?? shownAttachment;
-  const duration = anim.timelines.duration;
   const ctx = freshStepContext(plant.physicsStep);
   if (mode.loop && mode.wrapResets !== false) ctx.loop = true;
-  let visited = 0;
-  let trackTime = 0;
-  let last = -1;
+  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 };
   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);
@@ -606,36 +644,75 @@ function walkEach<P>(doc: CompiledDocument, animation: string, steps: readonly n
     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';
-    visit(shape.setup(doc, setup.world, setup.setup.slots, setup.setup.drawOrder, setup.shown, plant, mode), visited++);
-  }
-  for (let i = reset === 'setup' ? 1 : 0; i <= steps.length; i++) {
-    const dt = i === 0 ? 0 : steps[i - 1];
-    trackTime += dt;
-    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 - (i === 0 ? 0 : Math.max(last, 0)));
-    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 });
-    if (i === 0) ctx.phase = 'update';
-    const placeholders = new Map<string, string | null>();
-    const slots = posedSlots(doc, anim.timelines, t, raw, 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);
-    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);
-    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));
-    // A looping walk fires no event here: what fires across the wrap was not measured, and the walk's one reader (A10) reads none. Nor does it cut its
-    // drawn attachments through a clip (`NO_CLIPPED_ROWS`), so its `clipped` rows are empty.
-    const from = last;
-    const events = (): RawEvent[] => (mode.loop ? [] : (plant.events ?? eventsFired)(anim.timelines.events, from, 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);
-    last = t;
-    visit(pose, visited++);
+    return { track, first: shape.setup(doc, setup.world, setup.setup.slots, setup.setup.drawOrder, setup.shown, plant, mode) };
   }
+  return { track, first: stepWalk(track, 0, true) };
+}
+
+/**
+ * One step of a walk (the header's *One step*): the track time moved by `dt`,
+ * the animation applied at the mode's time from the setup pose, the physics
+ * clock moved by the step, and the pose assembled in the track's shape.
+ * `first` is the reset pose under `reset: 'animation'` — a step of 0 that
+ * 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;
+  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)));
+  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 });
+  if (first) ctx.phase = 'update';
+  const placeholders = new Map<string, string | null>();
+  const slots = posedSlots(doc, anim.timelines, t, raw, 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);
+  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);
+  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;
+}
+
+/** `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`. */
+function walkEach<P>(doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant, reset: RawReset, mode: WalkMode, shape: PoseShape<P>, visit: (pose: P, index: number) => void): void {
+  const anim = animationOf(doc, animation);
+  const bad = steps.findIndex((s) => !Number.isFinite(s) || s < 0);
+  if (bad >= 0) throw new CoreInputError(`step ${bad} is ${steps[bad]}, not a finite time at or above 0`);
+  const { track, first } = openWalk(doc, anim, plant, reset, mode, shape);
+  let visited = 0;
+  visit(first, visited++);
+  for (const dt of steps) visit(stepWalk(track, dt), visited++);
+}
+
+/**
+ * The raw entry's walk opened for stepping one `dt` at a time (issue #1276,
+ * `openTrack` in `./track.ts`): the same refusals in the same order as
+ * `walkIn`'s past the step list, pose 0 as `walkIn` poses it, and the state
+ * `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);
+}
+
+/** One step of an opened raw track (`openRawTrack`): `walkIn`'s step, the step itself checked by the caller. */
+export function stepRawTrack(track: TrackState<RawPose>, dt: number): RawPose {
+  return stepWalk(track, dt);
 }
 
 // --- #907 the setup-pose bounding box: begin ---

package/src/core/track.ts

@@ -0,0 +1,193 @@
+/**
+ * The core's live track (issue #1276): one animation opened on a track and
+ * stepped one `dt` at a time — a player's frame loop, whose steps are not known
+ * in advance — every pose the raw entry's (`RawPose` in `./raw.ts`), the doubles
+ * the core computed.
+ *
+ * It is not new math. Both batch walks — the raw entry's `poseRawAnimation`
+ * and A10's looping walk (`./walk.ts`) — take their steps up front and pose
+ * every step from the setup pose, carrying from one step to the next only the
+ * physics context, the running track time and the animation time of the step
+ * before. That carry is one object (`TrackState` in `./raw.ts`), and the batch
+ * walk is "open, then step over the list"; this track opens the same walk and
+ * takes its steps as they come. Measured before and after that split, over the
+ * nineteen tree rows' 54 animations: 956 batch walks — the raw entry at 12, 24
+ * and 60 fps from each reset, held three times past the duration, its two
+ * one-step jumps under each reset, `poseRawAnimationEach`, A10's walk and its
+ * 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).
+ *
+ * ## The walk
+ *
+ * - **Held** (`loop: false`): the raw entry's walk — the track time the
+ *   running sum of the steps, the animation time held at the duration, the
+ *   physics clock moved by the step, events over `(previous animation time,
+ *   animation time]` (`./raw.ts`, *One step*). `CO46` holds it to
+ *   `poseRawAnimation` pose for pose, every field, bit for bit.
+ * - **Looped** (`loop: true`): A10's looping walk's time, clock and `reset`
+ *   keys across the wrap (`./walk.ts`, *The walk*) — and, which that walk does
+ *   not carry because its one reader reads neither, the events it fires across
+ *   the wrap and the clipped rows it cuts. `CO46` holds it to
+ *   `poseLoopingWalk` narrowed to what that walk carries, bit for bit.
+ * - **The reset is the caller's**, as on the raw entry (`RawReset`): pose 0
+ *   (`first`) is posed when the track is opened, the batch walk's pose 0
+ *   under the same reset, and every `step` is one pose after it.
+ * - **Neither keeps a value that is not finite** (`keep: false`, the raw
+ *   entry's argument: a renderer handed one draws a different picture in
+ *   silence). What the raw entry refuses is a drawn vertex, a clip or clipped
+ *   vertex, a clipped UV and an event's numbers; a bone's matrix and a slot's
+ *   colour channel it passes on (NaN, `null`), and so does this track. Of
+ *   108 forged animations of the tree rows (a leaf and its parent scaled past
+ *   the largest double), 98 were refused at the first non-finite vertex and 4
+ *   walked holding a non-finite bone no drawn vertex reads; `CO49` holds both
+ *   halves, the second on a slotless bone chain.
+ *
+ * ## Across the wrap — what a looping track fires, measured
+ *
+ * Read off spine-core 4.3.13 — `AnimationState` with `setAnimation(0, name,
+ * true)`, pose 0 applied at 0 and reset there or reset at the setup pose
+ * with nothing applied, then per step `update(dt)`, `apply`,
+ * `Skeleton.update(dt)`, `updateWorldTransform(Physics.update)` — by a
+ * listener collecting `event` and `complete` in the order queued, on the
+ * tree rows' six animations keying events and on 300 seeded probes whose keys
+ * sit at 0, 1e-3 after it, in the middle, one float32 ulp and 1e-3 before the
+ * duration, on it, and one ulp and 1e-3 past the bone's last key (where the
+ * key sets the duration); over step lists that cross the wrap once and
+ * several times, land exactly on the duration, and carry the track past it by
+ * more than a cycle: 4,284 walks, 229,656 steps, 13,436 across the wrap, 8,846
+ * longer than a cycle, 52,880 events and 24,587 completes, each in the
+ * listener's order on every step. `CO47` holds the rule on its own population.
+ *
+ * - **A step whose animation time rose fires `(previous time, time]`**, as the
+ *   raw entry's — so a step that carries the track past the duration once or
+ *   more while its animation time still rises fires only that interval: the
+ *   keys it passed on the way are not fired.
+ * - **A step whose animation time went down — the wrap — fires the keys after
+ *   the previous time, in key order, then the keys at or before the new time,
+ *   in key order** (`eventsFired`'s `wrapped`): the second interval opens at
+ *   −1, so a key at 0 fires on every wrap. Read in key order instead, 7,680 of
+ *   the steps read off; with the second interval opening at 0, 6,066; with
+ *   nothing fired across the wrap, 12,956.
+ * - **A key at exactly the duration fires on the wrap step and on no other**,
+ *   before the keys from 0: 11,978 such firings, every one on a wrap step. A
+ *   key one float32 ulp before the duration is an ordinary key — it fired on a
+ *   rising step 545 times, where the animation time reached it before the wrap.
+ * - **An equal time is not a wrap** (`loopedTime`: a track time of exactly the
+ *   duration applies at 0). A track stepped by exactly the duration applies at
+ *   0 on every step, so it fires its keys at 0 on its first step and nothing
+ *   after; stepped by half the duration it wraps on every second step.
+ * - **`complete` is not carried** — a listener is the player's. Measured, it is
+ *   queued once on a step whose track time's whole cycles rose past 0 —
+ *   `⌊T / d⌋ > 0` and `⌊T / d⌋ > ⌊T_before / d⌋`, on every step at a duration
+ *   of 0 — however many cycles the step crossed, after the keys after the
+ *   previous time and before the keys from 0. A player derives it from
+ *   `trackTime` and `duration`.
+ *
+ * ## The clipped rows
+ *
+ * The looping mode cuts every drawn attachment under a clip as the raw entry
+ * does — the oracle's rows, and the core's own decomposition under a concave
+ * or inverse clip (`clipThrough`) — where A10's walk cuts none. That is a
+ * mode and not a measurement: the cut is per pose and does not read whether
+ * the track loops. `CO48` holds it: on the clipping probe and the tree row
+ * that clips, every looping pose, past the wrap included, equals the raw
+ * entry's one step to its animation time in every field but the track time
+ * and the events (4,009 of 4,009 on the tree row, 690 of them cutting 12,420
+ * rows).
+ *
+ * ## The oracle chain
+ *
+ * Nothing here is held to spine-core directly but the events: the live track
+ * is held to the batch walk (`CO46`), the held batch walk to spine-core's
+ * render and deform-measure recipes (`CR03`), the looped one to A10's recipe
+ * (`CO25`), and both to `tools/pose_oracle.ts`'s stepped dump, whose schedule
+ * is `stepSchedule` in `./constraints_physics.ts`. A second dump would be the
+ * same numbers twice.
+ *
+ * ⛔ **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
+ * 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';
+
+/** 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. */
+export interface TrackOptions {
+  loop: boolean;
+  reset: RawReset;
+}
+
+/** A live track (`openTrack`): pose 0, then one pose per `step`. */
+export interface LiveTrack {
+  /** Pose 0, posed when the track was opened: the batch walk's first pose under the same `reset`. */
+  readonly first: RawPose;
+  /** The next pose: the track time moved by `dt`, a finite time at or above 0. */
+  step(dt: number): RawPose;
+  /** The running sum of the steps taken, 0 before the first. */
+  readonly trackTime: number;
+  /** The time the latest pose applied the animation at (0 for pose 0). */
+  readonly animationTime: number;
+  /** The runtime's duration of the animation (`CoreAnimationTimelines.duration`). */
+  readonly duration: number;
+}
+
+/** The two modes: a track that holds at its duration is the raw entry's walk; a looping one fires its events across the wrap and cuts its clipped rows (`live`). Neither keeps a non-finite value. */
+const HELD: WalkMode = { loop: false, keep: false };
+const LOOPED: WalkMode = { loop: true, keep: false, live: true };
+
+/**
+ * One animation opened on a live track (the header): refused by name where the
+ * batch walk refuses the same document and animation, pose 0 posed, then
+ * stepped one `dt` at a time.
+ */
+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);
+  return new Track(track, first);
+}
+
+class Track implements LiveTrack {
+  readonly first: RawPose;
+  private readonly track: TrackState<RawPose>;
+  private steps = 0;
+  private latest: number;
+  private refused: string | null = null;
+
+  constructor(track: TrackState<RawPose>, first: RawPose) {
+    this.track = track;
+    this.first = first;
+    this.latest = first.animationTime;
+  }
+
+  get trackTime(): number {
+    return this.track.trackTime;
+  }
+
+  get animationTime(): number {
+    return this.latest;
+  }
+
+  get duration(): number {
+    return this.track.duration;
+  }
+
+  step(dt: number): RawPose {
+    const n = this.steps + 1;
+    if (this.refused !== null) throw new CoreInputError(`the live track was refused at step ${this.refused}, after its time and physics had moved; open the track again`);
+    if (typeof dt !== 'number' || !Number.isFinite(dt) || dt < 0) throw new CoreInputError(`the live track's step ${n} is ${String(dt)}, not a finite time at or above 0`);
+    try {
+      const pose = stepRawTrack(this.track, dt);
+      this.steps = n;
+      this.latest = pose.animationTime;
+      return pose;
+    } catch (err) {
+      if (err instanceof CoreInputError) this.refused = `${n} (${err.message})`;
+      throw err;
+    }
+  }
+}

package/src/core/walk.ts

@@ -57,8 +57,10 @@
  *   refuses, this entry writes the double; on 4,333 poses holding one, every
  *   NaN and Infinity stood where spine-core's did.
  *
- * Events are not carried: A10 reads none, and what a looping track fires
- * across the wrap was not measured. Nor are the clipped rows, and the walk
+ * Events are not carried: A10 reads none. What a looping track fires across
+ * the wrap is measured where a reader wants it — the live track
+ * (`./track.ts`, issue #1276), whose looping mode is this walk's with the
+ * events and the clipped rows put back. Nor are the clipped rows, and the walk
  * does not cut them (issue #1179): every clip it starts is still planned, so
  * a clip the core does not draw refuses the walk by name, as below.
  *