spine-rigc 1.9.0 → 1.9.2

package/src/core/constraints_physics.ts

@@ -431,6 +431,16 @@ export interface PhysicsTimelinePlant {
   search?: (keys: readonly CoreKey[], t: number) => number;
 }
 
+/**
+ * The records a physics timeline that names no constraint (`*`) writes: every
+ * active one whose `…Global` flag for `kind` is on, and for `reset` every
+ * active one (the header's *The timelines*), in the order given. `posedPhysics`
+ * asks it, and so does the additive probe (`./additive.ts`, issue #1025).
+ */
+export function unnamedPhysicsTargets<R extends CorePhysicsRecord>(records: readonly R[], kind: PhysicsTimelineKind, active: (r: CorePhysicsRecord) => boolean): R[] {
+  return records.filter((r) => active(r) && (kind === 'reset' || r.global[kind]));
+}
+
 /**
  * Every physics record posed by the animation's physics timelines at `t`, in
  * the timelines' order (the header's *The timelines*), and the names of the
@@ -438,18 +448,16 @@ export interface PhysicsTimelinePlant {
  * `last` to `t` (`resetCrossed`). `active`
  * says whether a constraint is applied at all (its skin and its bone).
  */
-export function posedPhysics(records: readonly CorePhysicsRecord[], timelines: readonly CorePhysicsTimeline[], t: number, last: number, active: (r: CorePhysicsRecord) => boolean, plant: PhysicsTimelinePlant = {}): { records: Map<string, CorePhysicsRecord>; reset: Set<string> } {
+export function posedPhysics(records: readonly CorePhysicsRecord[], timelines: readonly CorePhysicsTimeline[], t: number, last: number, active: (r: CorePhysicsRecord) => boolean, plant: PhysicsTimelinePlant = {}, wrapped = false): { records: Map<string, CorePhysicsRecord>; reset: Set<string> } {
   const search = plant.search ?? keyIndexAt;
   const channel = plant.channel ?? channelAt;
   const setupOf = new Map(records.map((r) => [r.name, r]));
   const posed = new Map(records.map((r) => [r.name, { ...r }]));
   const reset = new Set<string>();
   for (const tl of timelines) {
-    const targets = tl.name === EVERY_GLOBAL_PHYSICS
-      ? [...posed.values()].filter((r) => active(r) && (tl.kind === 'reset' || r.global[tl.kind]))
-      : [posed.get(tl.name) as CorePhysicsRecord].filter((r) => active(r));
+    const targets = tl.name === EVERY_GLOBAL_PHYSICS ? unnamedPhysicsTargets([...posed.values()], tl.kind, active) : [posed.get(tl.name) as CorePhysicsRecord].filter((r) => active(r));
     if (tl.kind === 'reset') {
-      if (resetCrossed(tl.keys, last, t)) for (const r of targets) reset.add(r.name);
+      if (resetCrossed(tl.keys, last, t, wrapped)) for (const r of targets) reset.add(r.name);
       continue;
     }
     const i = search(tl.keys, t);
@@ -473,9 +481,18 @@ export function posedPhysics(records: readonly CorePhysicsRecord[], timelines: r
  * issue #960): exactly when a key lies in `(last, t]` — so a key is crossed
  * once, by the step that reaches it, and `last` is −1 before the walk's
  * first apply, where a key at 0 is crossed.
+ *
+ * `wrapped` is a looping track's step whose animation time went DOWN (issue
+ * #1025, `./walk.ts`): the key crossed is then one after `last` or one at or
+ * before `t` — `(last, ∞)` and `(−1, t]` — measured against spine-core's
+ * `PhysicsConstraint.reset` calls on A10's walk. A step that wraps the track
+ * one or more times while its animation time still rises is not `wrapped`:
+ * the runtime fired only `(last, t]` there (a key at 0.25 of a 0.3 s
+ * animation stepped by 0.7 s, crossed by the track twice between two applies
+ * at 0.1 and 0.2, fired on neither).
  */
-export function resetCrossed(keys: readonly CoreKey[], last: number, t: number): boolean {
-  return keys.some((k) => last < k.time && k.time <= t);
+export function resetCrossed(keys: readonly CoreKey[], last: number, t: number, wrapped = false): boolean {
+  return wrapped ? keys.some((k) => k.time > last || k.time <= t) : keys.some((k) => last < k.time && k.time <= t);
 }
 
 // ---------------------------------------------------------------------------
@@ -546,6 +563,12 @@ export interface PhysicsStepContext {
    * to the step's time (`resetCrossed`).
    */
   last: number;
+  /**
+   * The walk's track loops (`./walk.ts`, issue #1025): a step whose animation
+   * time went down from `last` wrapped, and crosses the keys `resetCrossed`
+   * names for that. Absent on every walk but the looping one.
+   */
+  loop?: boolean;
 }
 
 /** A constraint's state in `ctx`, created fresh on its first update. */
@@ -788,7 +811,7 @@ export function physicsRows(records: readonly CorePhysicsRecord[], round: (v: nu
  */
 export function stepPhysicsRecords(records: readonly CoreConstraintRecord[], keyed: readonly CorePhysicsTimeline[], t: number, active: ReadonlySet<string>, ctx: PhysicsStepContext, before: number): CoreConstraintRecord[] {
   const physics = records.filter((r): r is CorePhysicsRecord => r.kind === 'physics');
-  const posed = posedPhysics(physics, keyed, t, ctx.last, (r) => physicsActive(r, active));
+  const posed = posedPhysics(physics, keyed, t, ctx.last, (r) => physicsActive(r, active), {}, ctx.loop === true && t < ctx.last);
   ctx.last = t;
   for (const name of posed.reset) resetPhysicsState(physicsState(ctx, name), before);
   return records.map((r) => (r.kind === 'physics' ? (posed.records.get(r.name) as CorePhysicsRecord) : r));

package/src/core/raw.ts

@@ -100,6 +100,12 @@
  *   `./clipping.ts`, issue #964), held to spine-core by the render's pixels.
  * - `events` — the oracle's event rows as doubles.
  *
+ * 🔁 **A second walk shares this one** (issue #1025, cut 4c-5a): A10's
+ * LOOPING walk, which keeps a non-finite value rather than refusing it, is
+ * `./walk.ts`; both are `walkIn` below in a `WalkMode`, and every difference
+ * is a branch on the mode — so this entry's walk is the one it was, and the
+ * raw gate's lines did not move.
+ *
  * ⛔ **Nothing is posed that the core would leave out.** Where the oracle's
  * core dump names a block absent — a constraint the core cannot pose
  * exactly, skins disagreeing over a placeholder under the merged view, a
@@ -189,8 +195,6 @@ export interface RawPose {
   // --- #968 render: end ---
 }
 
-const RAW_PLANT: CorePlant = { round: rawNumber };
-
 // --- #968 render: begin ---
 /** The shown records in `order`, the pose's draw order (a pose's `shown`). */
 function drawOrderOf(shown: readonly ShownGeometry[], order: readonly string[]): ShownGeometry[] {
@@ -205,6 +209,37 @@ function finite(v: number | null, what: string): number {
   return v;
 }
 
+/**
+ * How a walk treats the two things the raw entry and the looping walk
+ * (`./walk.ts`, issue #1025) read differently: whether the track loops, and
+ * whether a value that is not finite is kept in the pose or refuses the call.
+ * The raw entry is `{ loop: false, keep: false }`, and that is its contract.
+ */
+export interface WalkMode {
+  loop: boolean;
+  keep: boolean;
+  /** A plant only (the core suite's `CO26`): the animation time a looping step applies at, from its track time, the duration and the track time before it — `loopedTime` unless given. */
+  time?: (trackTime: number, duration: number, before: number) => number;
+  /** A plant only (`CO26`): what the physics clock moves by, from the step and how far the animation time moved — the step itself unless given. */
+  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 raw entry's mode: a track that holds at its duration, and a non-finite value refused. */
+const RAW_MODE: WalkMode = { loop: false, keep: false };
+
+/** What a kept walk writes a number as: the double itself, finite or not — so a NaN and an Infinity stay what they are. */
+const keptNumber = (v: number): number => v;
+
+/** The plant a walk in `mode` poses with: the raw entry's unrounded double, or under `keep` the number whatever it is. */
+const roundPlant = (mode: WalkMode): CorePlant => ({ round: mode.keep ? keptNumber : rawNumber });
+
+/** A double a kept walk computed, as it is; a raw walk's, refused when it is not finite (`finite`). */
+function numberOf(v: number | null, what: string, mode: WalkMode): number {
+  return mode.keep ? (v === null ? Number.NaN : v) : finite(v, what);
+}
+
 /** The bones of a pose from the world transforms (the header's `bones`). */
 function rawBones(doc: CompiledDocument, world: ReadonlyMap<string, CoreWorld>): RawBone[] {
   const active = activeBones(doc);
@@ -230,8 +265,8 @@ function rawBones(doc: CompiledDocument, world: ReadonlyMap<string, CoreWorld>):
 }
 
 /** Every region and mesh the shown records draw, with what the renderer reads past the vertices (the header's `drawn`). */
-function rawDrawn(doc: CompiledDocument, shown: readonly ShownGeometry[], world: ReadonlyMap<string, CoreWorld>, order: readonly string[], plant: CorePlant): { drawn: RawDrawn[]; clips: RawClip[]; clipped: RawClipped[] } {
-  const geometry = poseGeometry(shown, world, sourceOfDoc(doc), rawNumber, { region: plant.region, vertices: plant.vertices }, drawWalkOf(doc, order, plant));
+function rawDrawn(doc: CompiledDocument, shown: readonly ShownGeometry[], world: ReadonlyMap<string, CoreWorld>, order: readonly string[], plant: CorePlant, mode: WalkMode = RAW_MODE): { drawn: RawDrawn[]; clips: RawClip[]; clipped: RawClipped[] } {
+  const geometry = poseGeometry(shown, world, sourceOfDoc(doc), mode.keep ? keptNumber : rawNumber, { region: plant.region, vertices: plant.vertices }, drawWalkOf(doc, order, plant));
   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}`);
@@ -262,10 +297,10 @@ function rawDrawn(doc: CompiledDocument, shown: readonly ShownGeometry[], world:
       hull = source.hull ?? null;
     }
     const sequenceIndex = s.frame ?? record?.sequenceSetup ?? 0;
-    drawn.push({ slot: s.slot, attachment: row[1], kind: row[2], vertices: row[3].map((v) => finite(v, `vertex of slot "${s.slot}"`)), uvs, triangles, hull, sequenceIndex, colour });
+    drawn.push({ slot: s.slot, attachment: row[1], kind: row[2], vertices: row[3].map((v) => numberOf(v, `vertex of slot "${s.slot}"`, mode)), uvs, triangles, hull, sequenceIndex, colour });
   }
-  const clips = geometry.clips.map((c): RawClip => [c[0], c[1], c[2], c[3].map((v) => finite(v, `clip vertex of slot "${c[0]}"`))]);
-  const clipped = geometry.drawnClipped.map((c): RawClipped => [c[0], c[1], c[2], c[3].map((v) => finite(v, `clipped vertex of slot "${c[0]}"`)), c[4].map((v) => finite(v, `clipped uv of slot "${c[0]}"`)), c[5]]);
+  const clips = geometry.clips.map((c): RawClip => [c[0], c[1], c[2], c[3].map((v) => numberOf(v, `clip vertex of slot "${c[0]}"`, mode))]);
+  const clipped = geometry.drawnClipped.map((c): RawClipped => [c[0], c[1], c[2], c[3].map((v) => numberOf(v, `clipped vertex of slot "${c[0]}"`, mode)), c[4].map((v) => numberOf(v, `clipped uv of slot "${c[0]}"`, mode)), c[5]]);
   return { drawn, clips, clipped };
 }
 
@@ -275,13 +310,18 @@ function rawDrawn(doc: CompiledDocument, shown: readonly ShownGeometry[], world:
  * where the core leaves a block of it out.
  */
 export function poseRawSetup(doc: CompiledDocument, plant: CorePlant = {}): RawPose {
-  const posed = poseSetup(doc, { ...plant, ...RAW_PLANT }, freshStepContext(plant.physicsStep));
+  return setupPoseIn(doc, plant, RAW_MODE);
+}
+
+/** `poseRawSetup` in `mode` — under `keep`, a value that is not finite stays in the pose (`./walk.ts`). */
+export function setupPoseIn(doc: CompiledDocument, plant: CorePlant, mode: WalkMode): RawPose {
+  const posed = poseSetup(doc, { ...plant, ...roundPlant(mode) }, freshStepContext(plant.physicsStep));
   // `setup.clipped` is the oracle's block, left out under a concave or inverse clip whose triangle list is the runtime's own; what the core draws there is `rawDrawn`'s to refuse or pose (issue #964).
   const absent = posed.absent.filter(([block]) => block !== 'setup.clipped');
   if (absent.length > 0) throw new CoreInputError(`the raw setup pose leaves ${absent.map(([b, why]) => `${b} out (${why})`).join('; ')}`);
   const { setup, world, shown } = posed;
   if (world === null || shown === null || setup.slots === null || setup.drawOrder === null) throw new CoreInputError('the raw setup pose was not posed');
-  const drawn = rawDrawn(doc, shown, world, setup.drawOrder, plant);
+  const drawn = rawDrawn(doc, shown, world, setup.drawOrder, plant, mode);
   return { trackTime: 0, animationTime: 0, bones: rawBones(doc, world), slots: setup.slots, drawOrder: setup.drawOrder, ...drawn, events: [], shown: drawOrderOf(shown, setup.drawOrder) };
 }
 
@@ -296,34 +336,54 @@ export function poseRawSetup(doc: CompiledDocument, plant: CorePlant = {}): RawP
  * deformmeasure's one jump.
  */
 export function poseRawAnimation(doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant = {}, reset: RawReset = 'animation'): RawPose[] {
+  return walkIn(doc, animation, steps, plant, reset, RAW_MODE);
+}
+
+/**
+ * The animation time a looping track applies its animation at (`./walk.ts`,
+ * *The time*): the track time wrapped by the duration, and 0 over a duration
+ * of 0.
+ */
+export function loopedTime(trackTime: number, duration: number): number {
+  return duration === 0 ? 0 : trackTime % duration;
+}
+
+/**
+ * `poseRawAnimation` in `mode`: the raw entry's walk, or the looping walk
+ * `./walk.ts` documents — the animation time the track time wrapped by the
+ * duration, every value kept whatever it is. Each difference is a branch on
+ * `mode` here, so the raw entry's walk is the one it was.
+ */
+export function walkIn(doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant, reset: RawReset, mode: WalkMode): RawPose[] {
   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`);
   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, ...RAW_PLANT };
+  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;
   const poses: RawPose[] = [];
   let trackTime = 0;
   let 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, ...RAW_PLANT }, ctx);
+    const setup = poseSetup(doc, { ...plant, ...roundPlant(mode) }, 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';
-    poses.push({ trackTime: 0, animationTime: 0, bones: rawBones(doc, setup.world), slots: setup.setup.slots, drawOrder: setup.setup.drawOrder, ...rawDrawn(doc, setup.shown, setup.world, setup.setup.drawOrder, plant), events: [], shown: drawOrderOf(setup.shown, setup.setup.drawOrder) });
+    poses.push({ trackTime: 0, animationTime: 0, bones: rawBones(doc, setup.world), slots: setup.setup.slots, drawOrder: setup.setup.drawOrder, ...rawDrawn(doc, setup.shown, setup.world, setup.setup.drawOrder, plant, mode), events: [], shown: drawOrderOf(setup.shown, setup.setup.drawOrder) });
   }
   for (let i = reset === 'setup' ? 1 : 0; i <= steps.length; i++) {
     const dt = i === 0 ? 0 : steps[i - 1];
     trackTime += dt;
-    const t = trackTime < duration ? trackTime : duration;
+    const t = mode.loop ? (mode.time ?? loopedTime)(trackTime, duration, trackTime - dt) : trackTime < duration ? trackTime : duration;
     const before = ctx.time;
-    ctx.time += dt;
+    ctx.time += mode.clock === undefined ? dt : mode.clock(dt, t - (i === 0 ? 0 : Math.max(last, 0)));
     const sliders: SliderApplication[] = [];
     const posed = posedBoneWorld(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before });
     if (i === 0) ctx.phase = 'update';
@@ -338,8 +398,9 @@ export function poseRawAnimation(doc: CompiledDocument, animation: string, steps
     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));
-    const drawn = rawDrawn(doc, shown, posed.world, drawOrder, plant);
-    const events = (plant.events ?? eventsFired)(anim.timelines.events, last, t, rawNumber).map((e): RawEvent => [e[0], finite(e[1], 'event time'), e[2], finite(e[3], 'event float'), e[4]]);
+    const drawn = rawDrawn(doc, shown, posed.world, drawOrder, plant, mode);
+    // A looping walk fires no event here: what fires across the wrap was not measured, and the walk's one reader (A10) reads none.
+    const events = mode.loop ? [] : (plant.events ?? eventsFired)(anim.timelines.events, last, t, rawNumber).map((e): RawEvent => [e[0], finite(e[1], 'event time'), e[2], finite(e[3], 'event float'), e[4]]);
     last = t;
     poses.push({ trackTime, animationTime: t, bones: rawBones(doc, posed.world), slots: slots.rows, drawOrder, ...drawn, events, shown });
   }

package/src/core/walk.ts

@@ -0,0 +1,202 @@
+/**
+ * The core's looping walk (issue #1025, cut 4c-5a of step 4c of #380): one
+ * animation on a LOOPING track, reset at the setup pose and then stepped at
+ * the caller's steps, every pose returned as the doubles the core computed —
+ * a value that is not finite included, in place, rather than refused.
+ *
+ * This is the walk `A10_NO_NAN_AFTER_STEPPING` takes, and the reason it is
+ * its own entry rather than the raw entry (`./raw.ts`) under another name is
+ * the two things the raw entry's contract excludes on purpose: its track
+ * holds at the duration, and it refuses a non-finite value by name
+ * (`CoreInputError`), because a renderer handed one would draw a different
+ * picture in silence. A10's subject is exactly that value, so here it is the
+ * answer, not a refusal. Everything else is the raw entry's walk, called
+ * rather than restated (`walkIn` in `./raw.ts`, which branches on the two).
+ *
+ * ## The walk, measured
+ *
+ * Written from spine-core 4.3.13 running A10's own recipe — `Skeleton`,
+ * `AnimationState` with `setAnimation(0, name, true)`; `setupPose()`,
+ * `update(0)`, `updateWorldTransform(Physics.reset)`; then per step
+ * `AnimationState.update(dt)`, `apply`, `Skeleton.update(dt)`,
+ * `updateWorldTransform(Physics.update)` — and read off `TrackEntry.trackTime`,
+ * `TrackEntry.getAnimationTime()`, every bone's `appliedPose`, every shown
+ * region's and mesh's world vertices, every slot's colours and the calls the
+ * runtime makes to `PhysicsConstraint.reset`. The PR of issue #1025's cut
+ * 4c-5a carries the tables; each rule names the count that held it.
+ *
+ * - **Pose 0 is the setup pose, reset** — the animation is set and not yet
+ *   applied, so the reset is taken at the setup pose (`RawReset` `setup`).
+ * - **The track time is the running sum of the steps**, as on the raw
+ *   entry's walk: `TrackEntry.trackTime` equalled it on every step of the
+ *   nineteen tree rows' walks (6,480 of 6,480).
+ * - **The time** — the animation is applied at the track time wrapped by the
+ *   duration (`loopedTime` in `./raw.ts`): `trackTime % duration` in double,
+ *   so a track time of exactly the duration is 0, the first pose again, and
+ *   over a duration of 0 the time is 0 whatever the track time (an animation
+ *   keying nothing, or keying only at 0) — `getAnimationTime()` read so on
+ *   6,480 of 6,480 steps, 1,087 of them at or past the duration and 4 exactly
+ *   on it; before the zero-duration reading it read 6,000.
+ * - **The physics clock moves by the step itself** (`Skeleton.update(dt)`),
+ *   whatever the wrap does to the animation time: moved by the animation
+ *   time's own change instead, 32 of 82 seeded and forged walks read off.
+ * - **A `reset` key across the wrap.** A key is crossed when it lies in
+ *   `(previous animation time, animation time]`, as on the raw entry; on a
+ *   step whose animation time went DOWN — the wrap — it is crossed when it
+ *   lies after the previous time or at or before the new one, `(last, ∞)`
+ *   and `(−1, t]` (`resetCrossed` in `./constraints_physics.ts`). A step
+ *   that passes the duration once or more while its animation time still
+ *   rises is not a wrap there: a key at 0.25 s of a 0.3 s animation stepped
+ *   by 0.7 s fired on neither of the two steps that carried the track past
+ *   it, and an equal time is not a wrap either (a 0.25 s animation stepped by
+ *   0.25 s fired its key at 0 once). With the wrap firing nothing, 957 of
+ *   14,460 poses of a seeded population read off.
+ * - **A value that is not finite** is the IEEE result of the same
+ *   arithmetic, kept: a world matrix term, a world position, a vertex, a slot
+ *   colour channel. Where the raw entry writes such a value `null` and
+ *   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.
+ *
+ * ⛔ **What is still refused** is the raw entry's other refusal: a construct
+ * the core would leave out (a block the oracle's core dump names absent) is a
+ * `CoreInputError` naming why, as there — a pose with a block missing is not
+ * a pose whose values can be judged finite.
+ *
+ * ⛔ **And one construct this walk refuses that the raw entry does not**
+ * (`sliderPhysicsWhy`): a slider whose animation keys a physics timeline.
+ * Issue #1049. Of the selftest's builds of that class (a dial, or two
+ * sliders, keying a physics constraint's `wind` or `gravity`), five walked off spine-core from the third
+ * step on — `tip` at worldX 14.87 against 12.09 on the first, at 0.025 s —
+ * while others of the same class walked exact. The raw entry's own non-looping walk reads the same
+ * gap (and with the slider made non-additive, 14.78 against 12.09), so it is
+ * the stepped walk's reading of a slider's physics keys, not the loop's.
+ * Which of the class it reaches is not measured, so the walk refuses the
+ * class by name rather than return a pose it cannot vouch for. On the same
+ * five inputs, `./additive.ts` and spine-core's probe agree that each slider's
+ * `wind` or `gravity` timeline accumulates when applied twice with `add` — so
+ * the gap is downstream of that rule, in the stepped bones, not in it.
+ */
+import { setupPoseIn, walkIn, type RawBone, type RawDrawn, type WalkMode } from './raw.ts';
+import { activeBones, CoreInputError, constraintRecords, type CompiledDocument, type CorePlant, type CoreSlotRow } from './index.ts';
+import { historyTaint } from './constraints.ts';
+import type { TimelinePlant } from './animation.ts';
+
+/** One pose of the looping walk: the raw entry's pose less what this walk does not carry (events, the clip rows, the shown records). */
+export interface WalkPose {
+  /** The running sum of the steps, 0 for pose 0. */
+  trackTime: number;
+  /** The time the animation was applied at: the track time wrapped by the duration (`loopedTime`). */
+  animationTime: number;
+  /** Every bone in document order, its world matrix and origin as computed, finite or not. */
+  bones: RawBone[];
+  /** Every slot row (`CoreSlotRow`) with its colour channels as computed, finite or not. */
+  slots: CoreSlotRow[];
+  /** The slot names in the posed draw order. */
+  drawOrder: string[];
+  /** Every region and mesh a slot shows, in draw order, its world vertices as computed, finite or not. */
+  drawn: RawDrawn[];
+}
+
+/**
+ * Why the looping walk refuses this document, or `null` (the header's last
+ * ⛔, issue #1049): every slider whose animation keys a physics timeline,
+ * named with it.
+ */
+export function sliderPhysicsWhy(doc: CompiledDocument): string | null {
+  const keyed = constraintRecords(doc).flatMap((r) => {
+    if (r.kind !== 'slider') return [];
+    const anim = doc.animations.find((a) => a.name === r.animation);
+    return anim !== undefined && anim.constraints.physics > 0 ? [`slider "${r.name}" applies animation "${r.animation}", which keys physics timelines`] : [];
+  });
+  return keyed.length === 0 ? null : `${keyed.join('; ')} — under the stepped walk spine-core's bones leave the core's from the third step, on the raw entry's walk as on this one, and that reading is not measured (issue #1049)`;
+}
+
+/**
+ * The bones and slots whose numbers the walk does not vouch for, because the
+ * runtime's own value there is HISTORY (issue #979): a bone the view leaves
+ * unposed — inactive, or below an inactive bone — that a constraint writing
+ * into an inactive bone reaches (`historyTaint` in `./constraints.ts`, the
+ * walk the core's leak refusal reads), each with that writer; and every slot
+ * on such a bone. spine-core never updates an inactive bone, so what a
+ * constraint wrote into it on the step before is what the constraint reads
+ * on the next one; the core poses every step from the setup pose. Measured on
+ * a public probe (a transform constraint writing four skin-required bones no
+ * skin activates): at mix 1 the two differ only in the sign of zero of the
+ * matrix cells (`atan2` of a zero matrix is 0° or 180° by those signs), and at
+ * a translate mix of 0.5 by value (worldX 30.000000348 in spine-core against
+ * 20.000000232 in the core at step 1), on the bones and on an active child of
+ * one. Where such a value reaches a posed bone the core already refuses the
+ * document (`unposedLeakWhy`); here nothing posed reads it, so a walk
+ * comparison counts these numbers apart by name and compares them with
+ * nothing, as `tools/pose_oracle.ts unposed` does under the step.
+ */
+export function walkHistory(view: CompiledDocument): { bones: Map<string, string>; slots: Map<string, string> } {
+  const active = activeBones(view);
+  const unposed = new Set<string>();
+  for (const b of view.bones) if (!active.has(b.name) || (b.parent !== undefined && unposed.has(b.parent))) unposed.add(b.name);
+  const bones = new Map<string, string>();
+  for (const [bone, w] of historyTaint(view).tainted) if (unposed.has(bone)) bones.set(bone, `${w.kind}/${w.name} on inactive ${w.inactive}`);
+  return { bones, slots: new Map(view.slots.filter((s) => bones.has(s.bone)).map((s) => [s.name, s.bone])) };
+}
+
+/** Refuse, by name, a document the looping walk cannot vouch for (`sliderPhysicsWhy`). */
+function refuseUnmeasured(doc: CompiledDocument): void {
+  const why = sliderPhysicsWhy(doc);
+  if (why !== null) throw new CoreInputError(`the looping walk leaves the bones out: ${why}`);
+}
+
+/** The looping walk's mode: the track loops, and a non-finite value stays in the pose. */
+const LOOPING: WalkMode = { loop: true, keep: true };
+
+/**
+ * The looping walk's plants (the core suite's `CO26`), each the reading the
+ * walk was measured against and rejected, in a copy: the time a step applies
+ * at, what the physics clock moves by, and what a number is written as.
+ * Nothing but a control passes one.
+ */
+export interface WalkPlant {
+  time?: WalkMode['time'];
+  clock?: WalkMode['clock'];
+  wrapResets?: WalkMode['wrapResets'];
+  /** Every number of a pose rewritten — a swallowed non-finite value is `(v) => (Number.isFinite(v) ? v : 0)`. */
+  number?: (v: number) => number;
+}
+
+/** A raw pose narrowed to what the looping walk carries, every number through `number`. */
+function narrow(p: { trackTime: number; animationTime: number; bones: RawBone[]; slots: CoreSlotRow[]; drawOrder: string[]; drawn: RawDrawn[] }, number?: (v: number) => number): WalkPose {
+  if (number === undefined) return { trackTime: p.trackTime, animationTime: p.animationTime, bones: p.bones, slots: p.slots, drawOrder: p.drawOrder, drawn: p.drawn };
+  const n = (v: number | null): number | null => (v === null ? null : number(v));
+  return {
+    trackTime: p.trackTime,
+    animationTime: p.animationTime,
+    bones: p.bones.map((b) => ({ ...b, a: number(b.a), b: number(b.b), c: number(b.c), d: number(b.d), worldX: number(b.worldX), worldY: number(b.worldY) })),
+    slots: p.slots.map((r): CoreSlotRow => [r[0], r[1], n(r[2]), n(r[3]), n(r[4]), n(r[5]), r[6] === null ? null : [n(r[6][0]), n(r[6][1]), n(r[6][2])], r[7], r[8]]),
+    drawOrder: p.drawOrder,
+    drawn: p.drawn.map((d) => ({ ...d, vertices: d.vertices.map(number) })),
+  };
+}
+
+/**
+ * The setup pose, every physics state reset, every value kept whatever it is —
+ * what A10 reads before any animation is set.
+ */
+export function poseWalkSetup(doc: CompiledDocument, plant: CorePlant = {}, walkPlant: WalkPlant = {}): WalkPose {
+  refuseUnmeasured(doc);
+  return narrow(setupPoseIn(doc, plant, LOOPING), walkPlant.number);
+}
+
+/**
+ * One animation on a looping track (the header's *The walk*): pose 0 the setup
+ * pose reset, then one pose per step of `steps` — `steps.length + 1` poses in
+ * all. A step must be a finite time at or above 0 and the animation the
+ * document's, as on the raw entry; a construct the core would leave out
+ * refuses the call by name; a value that is not finite does not.
+ */
+export function poseLoopingWalk(doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant = {}, walkPlant: WalkPlant = {}): WalkPose[] {
+  refuseUnmeasured(doc);
+  const mode: WalkMode = { ...LOOPING, ...(walkPlant.time === undefined ? {} : { time: walkPlant.time }), ...(walkPlant.clock === undefined ? {} : { clock: walkPlant.clock }), ...(walkPlant.wrapResets === undefined ? {} : { wrapResets: walkPlant.wrapResets }) };
+  return walkIn(doc, animation, steps, plant, 'setup', mode).map((p) => narrow(p, walkPlant.number));
+}