rig-c 3.2.0 → 3.3.0

package/docs/AUTHORING.md

@@ -130,6 +130,7 @@ commands take it and what its default is.
 | `split --rig … --motion … --slot <name> --out <dir>` | the answer to a mesh refused because its triangles are **several pieces that share no vertex** — two legs after the triangles bridging them were deleted. It reads the two specs and writes them back into an absent or empty `--out` with one mesh per piece: piece 1 stays in the slot, piece k gets a new slot `<slot>_<k>` after it, each with the original's uvs and weights unchanged, its triangles renumbered outline first where the hull rule needs it, and every deform key re-sliced to the new indices — plus `split.json`, where every original vertex and triangle went. One piece is said so and nothing is written; what it cannot carry is refused by name ([AUTHORING §3.4.11](../docs/AUTHORING.md)) <a id="cmd-split"></a> |
 | `explain --rig … --motion …` | the compiled rig as a table — every bone with its resolved parent, the slots in draw order, every timeline key by key. Writes nothing. What to reach for when a rig compiles and still looks wrong <a id="cmd-explain"></a> |
 | `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`, one directory per set: `<anim>@<fps>fps/` rather than `<anim>/` at any rate but the default — `--fps 24` writes `<anim>@24fps/`, and the default 12 writes `<anim>/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid. `--folds` adds a `folds.json` per set and prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count and which triangles, their world box and their setup-pose area. `--pass-through <cloth>:<leg>` adds a `pass-through.json` per set and prints the frames where a cloth drawn over a leg has its side inside the leg's drawn outline, with the depth and the world box — a reading, not a gate. `--seam <slot>:<slot>` adds a `seam.json` per set and prints, per pair, the frames where two slots that meet open background inside the joint (a gap) or show the overlap band of one past the other (a ghost), with the worst frame's cell count and world box; `ghostA` and `ghostB` partition the same ghost by which named pair member drew it, each with its own frames, spans and worst; `gapOpen` and `gapCovered` partition `gap` by zero versus positive rendered alpha from the whole skeleton, including faint and clipped drawings; ghost counts only visible contributions after draw order; `exposureA`/`exposureB` report each named slot’s whole-drawing background exposure even without a band ([AUTHORING §8.8](../docs/AUTHORING.md#88-where-two-slots-stop-meeting--render---seam)) — a reading, not a gate; the exit status never moves. `--overlaps` adds an `overlaps.json` per set and prints one `OVERLAP "<under>" under "<over>"` line per pair of slots where the one drawn later covers the earlier one and the motion moves it — the frames, and the most pixels covered and the frame of them — with an outline plate per covered frame; the render reports what was drawn, and the draw-order key is the author's remedy — a reading, not a gate. `--extremes` adds `extremes.json` and a native six-panel `extremes.png` (setup, geometry-pair min/max and three premultiplied RGBA diffs with a legend), plus one `EXTREMES` line per set. Per-channel minima/maxima and the farthest original-vertex geometry pair are distinct readings; valid channel extrema survive a geometry/image SKIP, with channel refusals reported separately; still or uncomparable geometry reports a named SKIP without changing render exit status. `--extremes-only` writes the same `extremes.json` and readable `extremes.png` bytes while skipping ordinary frame rasterization/encoding, `contact.png` and `frames.json`; it implies `--extremes` and takes no other diagnostic or sheet output flags. Look at min, max and diff before a person does ([AUTHORING §8.11](../docs/AUTHORING.md#811-min-max-and-diff-before-a-person-looks--render---extremes)). `--angle-range <bone>:<relative-to>` prints how far one bone turns against another over each set: the lowest and highest angle and the frames they fall on — a reading, not a gate. `--viewport <x,y,w,h>` or `--viewport-from <frames.json>` draws over a given box instead of a fitted one, so two builds land on one pixel grid; a slot that reaches past it is named by set and frame, and `frames.json` records it. `--environment <schedule.json>` draws the rig under the wind and gravity its physics answers, in time — the same frames on the core and on spine-core; an inspection of the response the rig states, not a scene. `--preroll <n>` walks each set `n` whole loops on a looping track before the loop it records, so a looping idle is drawn with its physics already warm, as a player's looping track carries it ([AUTHORING §8.13](../docs/AUTHORING.md#813-a-loop-with-its-physics-warm--render---preroll)). `--sheet [--sheet-format json-hash] [--page-edges pot\|free]` also packs each set's straight-alpha transparent frames into `sheet.png` + `sheet.json` (TexturePacker JSON Hash with a shared world-origin `anchor` and `2`-px clamped edge extrusion, verified through `pixi.js@8.22.0` and `phaser@3.90.0` by `tools/sheet_readers.ts`) and `sheet-manifest.json` (`rigc-sheet/1`), leaving diagnostic `f####.png` and `contact.png` unchanged ([AUTHORING §8.10](../docs/AUTHORING.md#810-sprite-sheets-from-a-render--render---sheet)) — a self-contained sprite object per animation set; when animations play and how a scene is composed remains the consumer's <a id="cmd-render"></a> |
+| `render … --physics off --boundary-from <dir>` | Suppress every physics constraint on both posers and read visible boundary displacement from a second render on the same viewport and frame grid. `frames.json` records off, `check` refuses it as a reference, and `boundary.json` carries per-frame distances or named SKIPs. See §8.14. |
 | `preview --candidate <dir>` | one self-contained `.html` that plays it, headed by the line `validate <dir>` prints for it and the rigc version — a refused candidate is still previewed, and its header says so in the gate's words. Repeat `--candidate` for one page with a pane per candidate, in the order given; a green `build` ends by naming this command for its own `--out` <a id="cmd-preview"></a> |
 | `vote --candidate a --candidate b` | one `.html` that asks a human which; `vote --record <file>` checks the answer into `votes.jsonl` <a id="cmd-vote"></a> |
 | `pose --images <dir> --frame <png>` | reads part placements **out of** a picture <a id="cmd-pose"></a> |
@@ -389,7 +390,7 @@ What the flags mean:
 | `--sheet-format` | `render --sheet` only: `json-hash` (default, TexturePacker JSON Hash with `frames`, `animations` and `meta`, verified against `pixi.js@8.22.0` and `phaser@3.90.0` by `tools/sheet_readers.ts`). Refused without `--sheet` or on an unknown value, exit 2, nothing written — **§8.10** |
 | `--viewport`, `--viewport-from` | `render`: give the box every frame is drawn over instead of fitting one — `--viewport <x,y,w,h>`, a world box, y up, `x,y` its bottom-left corner, at the pixel size `--max` gives; or `--viewport-from <frames.json \| dir>`, an earlier render's grid exactly (its box, scale and pixel size), so two candidates land on one pixel grid. A slot that reaches past the box is named by set and frame, and `frames.json` records the box was given under `pinned`. The two together are refused, and so is `--max` beside `--viewport-from` — **§8.6**. On `check` and `inspect`, `--viewport` pins the box those commands draw over instead |
 | `--environment` | `render` only: the wind and gravity the rig's physics constraints answer, in time — a schedule file `{ "spec": "rigc-environment/1", "steps": [{ "t": <seconds>, "wind"?: [x, y], "gravity"?: [x, y] }, …] }`, x right and **y down**, each step holding from its `t` until the next. Both posers set each change before the step that poses the first frame at or after its `t`, and draw the same frames, `geometry.json` and `frames.json` (`RE01`). `frames.json` and `geometry.json` record it, and the framing reads it. A malformed file, a half no physics constraint answers, two steps on one frame and a step after every set's last frame are refused by name, exit 2, nothing written; `check` refuses a frame set drawn under one as a reference. Without it every file is the bytes it always was. An inspection of the response the rig states, not a scene — **§8.4** |
-| `--preroll` | `render` only: `<n>`, a whole number of 1 or more — walk each set `n` whole loops on a **looping** track before the loop recorded, drawn by no frame, the physics carried across every wrap as a player's looping track carries it, so a spring that converges is warm on the first frame. The walk lands on track time `n · duration` exactly, where the track has wrapped `n` times, so frame `i` is the pose at animation time `i / fps` — the time it is filed under — whether or not the duration is a whole number of frames (`PRE06`). Both posers walk it alike and write the same frames, `geometry.json`, sheet and `frames.json` (`PRE01`). `frames.json`, `geometry.json` and `sheet-manifest.json` record it as `preroll`, a sheet's namespace ends `/preroll=<n>`, and the framing reads it. A value that is not a whole number of 1 or more, a walk past what a step list holds, a skeleton with no animation or no physics constraint, a set of 0 frames at the rate, and `--environment` or `--parallax` beside it are refused by name, exit 2, nothing written; `check` refuses a frame set drawn after one as a reference. Without it every file is the bytes it always was — **§8.13** |
+| `--preroll` | `render` only: `<n>`, a whole number of 1 or more — walk each set `n` whole loops on a **looping** track before the loop recorded, drawn by no frame, the physics carried across every wrap as a player's looping track carries it, so a spring that converges is warm on the first frame. The walk lands on track time `n · duration` exactly, where the track has wrapped `n` times, while its physics clock lands on the frame grid point nearest it, so the loop recorded is loop `n + 1` of a plain looping walk to rounding even where the duration is a float32 a hair off a whole number of frames (`PRE07`); so frame `i` is the pose at animation time `i / fps` — the time it is filed under — whether or not the duration is a whole number of frames (`PRE06`). Both posers walk it alike and write the same frames, `geometry.json`, sheet and `frames.json` (`PRE01`). `frames.json`, `geometry.json` and `sheet-manifest.json` record it as `preroll`, a sheet's namespace ends `/preroll=<n>`, and the framing reads it. A value that is not a whole number of 1 or more, a walk past what a step list holds, a skeleton with no animation or no physics constraint, a set of 0 frames at the rate, and `--environment` or `--parallax` beside it are refused by name, exit 2, nothing written; `check` refuses a frame set drawn after one as a reference. Without it every file is the bytes it always was — **§8.13** |
 | `--poser` | `render`, `inspect`, `check` and `explain`: `core` or `spine` — on `render`, `inspect` and `check`, which implementation poses the frames (on `check`, the candidate's; the reference side is pixels either way). By default a **rigc build** (the `skeleton.model.json` `build` writes; its atlas, when one is named or present, the one beside it) is posed by rigc's own core and a **Spine export** by spine-core; the render prints a `poser` line saying which and why, and so does the check report (`check.json`'s `poser`, and the pictures' `frames.json` under `--out`; `bench --frames` prints the same line). A concave or an inverse clip is posed by the core, and so is a build rendered with no `--skin` whose default skin names a skin-required bone or constraint, or whose skins name no `default` one — posed as a fresh skeleton is, no skin's bones or constraints applied (the default skin's included) and every slot resolved through the default skin alone, so the second draws nothing and stops at `there is nothing to draw` (exit 2) under either poser (issue #1051). Where the input cannot carry the core, or the core refuses it, the render poses it through spine-core and the `poser` line says why, in one of these words: `no skeleton.model.json beside` (a Spine export) · `is not beside` (`--atlas` names an atlas outside the build's directory) · `does not describe` (a model document whose bones, slots or animations are not the skeleton's) · `is not the skeleton.json` (a `skeleton.json` whose SHA-256 is not the `spine.sha256` its model document records — edited or replaced after the build — both digests named) · `the polygon is not simple` (a clip polygon two of whose edges cross or touch, the slot named) · `depends on the runtime's previous pass` (a constraint moves a posed bone from a bone that a constraint writes into while that bone is inactive, all four named) · `--poser spine` (asked for). Any other refusal of the core's — an unreadable model document among them — reads `the core refused` and then the core's own words. `--poser core` on an input that cannot carry it is refused in the same words (exit 2, nothing written); `--poser spine` forces the runtime. A fallback whose pair the runtime cannot load — another build's `skeleton.json` or atlas beside this build's document, or an export beside an atlas it was not exported with — is not drawn: it is refused `… does not load against <the atlas>: spine-core draws this pair (<why>) and could not resolve it — "<the runtime's own words>"` — or, where the atlas names a page that is not there, `nothing at <the page>: …` — exit 2, nothing written, on `render`, `render --geometry`, `check` and `bench --frames` alike; under `--poser core` the same pair is that flag's refusal, in the words above (`RC18`; the `--candidate` row says what to change). The repository's selftest renders one probe per reason above and holds this list to the lines they print (`RC09`). Both posers draw the same frames, geometry and framing box to the bit on every corpus (issue #968), and `check` through either writes the same report, `check.json` and pictures but for the poser it names on every tree row. A rigc build the core poses reads nothing through spine-core on `render`, `render --geometry` and `check`, `--texture-from` included (and the check `bench --frames` folds in; `bench`'s own `validate`, like `build`'s, is the runtime's round trip by design): its bone tree, slot list and slot roster come off its model document; so do the order its animations and skins are listed in, its stage and its pages' `scale:` lines, on a `rigc-compiled/3` document (`editorOrder`, `stage`, `pages`) — a `/2` or `/1` document states none of those, so they come off its own `skeleton.json` and atlas, and the `poser` line then says `a rigc-compiled/2 document, which does not state the order its skins and animations are listed in or its stage, read from` and names both files; where each region sits and the page images it draws off the document's `pages` (a `rigc-compiled/1` document's off the atlas beside it, and the `poser` line then says `a rigc-compiled/1 document, which does not state where each region sits on its page: that is read from` and names the atlas); and a `--texture-from` atlas off rigc's own atlas reader. The runtime is loaded for a Spine export, `--poser spine` and a fallback the `poser` line names; a run that cannot load it there is refused naming the input and why it needs the runtime (exit 1; `RC11`, `RC13`, `RC34`). On the entry that links none of spine-core — the installed `rigc` without the runtime beside it, `bun cli_core.ts` in a clone — that refusal ends on the route to the entry that does (``the entry that links it runs them — installed, the same `rigc` once @esotericsoftware/spine-core is installed beside the package; from a source checkout, `bun cli.ts` ``); a runtime that is installed and fails to load is refused without it, since installing it is not what that reader has to do. On `explain` the flag chooses the `DEFORM` block's survey (§4.11.2): `core`, the default, reads the skeleton's structure — its deform timelines and their keys, curves and slots, the skin each is keyed under, the sliders — off the model document the compile writes and poses it through the core, and spine-core is not touched (`RC15`); `spine` parses and poses the Spine skeleton through spine-core. The two are the same survey to the byte on every corpus row (`DM12`). Where the core refuses the document, the survey falls back to spine-core and the block says so on a line of its own (`read and posed through spine-core: …`); `--poser core` there is refused instead (exit 2), and a run that cannot load the runtime where it needs it is refused naming the survey and why (exit 1), ending on the same route where the entry links none of it |
 | `--lever-fold` | `explain` only: a fraction above 0 and at most 1. Also read, on the turn lines' walk, the steps where a physics constraint that drives `scaleX` has its inertia lever divide by less than this fraction of the divisor it takes at the setup pose, and the steps where the scale factor it applies moves by more than the bone's setup scale. **No default**: without it the reading is not taken and one line says so; a value that is not such a fraction is refused by name (exit 2). A reading, not a gate — **§4.6.2** |
 | `--record` | `vote` only: a saved vote to check against its ballot and append to the ledger, instead of writing a ballot. This is the command's second mode; it takes no `--candidate` |
@@ -9844,9 +9845,9 @@ first, drawn by no frame, then records the next loop:
 - **The walk.** `count` is the set's frame count at the rate,
   `round(duration · fps)`. From the same reset at frame 0 a render from rest
   takes, the track steps the render's grid `j / fps` up to the last point before
-  track time `n · duration`, takes one shorter step onto it, then the `count`
+  track time `n · duration`, takes one step onto it, then the `count`
   steps of the loop recorded, `n · duration + i / fps` — on the render's own
-  physics clock (§4.6) — and its animation time is the track time wrapped by the
+  physics clock (§4.6), save the step onto the wrap (below) — and its animation time is the track time wrapped by the
   duration, what spine-core's `setAnimation(0, name, true)` does and what the
   core's live track does looping (`openTrack({ loop: true })`). Both posers add
   the steps up the same way, and every one before the wrap subtracts without
@@ -9865,6 +9866,35 @@ first, drawn by no frame, then records the next loop:
   float and the wrap is hit exactly; for a duration that is not, where the
   product rounds below the wrap — the loop's end rather than its start — the
   walk lands one float past it (`prerollStart`).
+- **The physics clock lands on the grid, not on the wrap** (issue #1687). The
+  track's step onto the wrap is a frame only where the duration is exactly
+  `count / fps`. A duration read as a float32 a hair below it — 8/3 s is read as
+  2.6666665 s, `count / fps` less `δ` = 1.6e-7 s — makes that step a frame short
+  by `n · δ`, far more than the render's clock lead has gathered by then (3.2e-7
+  s against 5.0e-9 s at 2 loops at 12 fps); a physics constraint takes only the
+  whole steps that fit, so the clock moved by it dropped one physics step at the
+  landing, and the loop recorded started a fresh transient instead of continuing
+  the settled cycle. So every step of the walk moves the physics clock by its own
+  length except the step onto the wrap, which moves it to the grid point nearest
+  the wrap: a whole frame where the wrap sits just short of one, nothing where it
+  sits just past one and the step onto it is the sliver beyond. The loop recorded
+  is then loop `n + 1` of a plain looping walk on the uniform grid, its physics
+  clock off that walk's by rounding alone, and frame 0 is still the wrap — the
+  keyed bones re-phased onto it by `n · δ`. Where the duration is exactly `count
+  / fps` the step onto the wrap is a frame and nothing moves; on a loop of no
+  whole frame count the physics stays on the frame grid the same way and the
+  keyed bones are re-phased by under half a frame. On the selftest's
+  `preroll_probe` — four springs in a chain under loops read just short of 32
+  and 80 frames and just past 48 — the short step moved the springs 26.4 units
+  off the plain walk's loop on a stepped idle and 37.6 on an eased one at 2 loops
+  and 12 fps; now, on the stepped loops at pre-rolls of 2 and 10 on both posers,
+  every keyed bone is the plain walk's to the bit and every spring is within
+  what one more clock lead moves it (`PRE07`, at most 2.2e-5 of it); restoring
+  the short step on the core is red there on every case, by name (`PRE09`). On
+  the eased loop the springs sit 5.3e-5 units off at 2 loops and 2.6e-4 at 10,
+  linear in `n · δ`: that is the re-phase, which frame 0 being the wrap is. After
+  10 loops every spring's seam closes within its largest step on both posers,
+  where the short step opened four of five sets (`PRE08`).
 - **What moves.** Only what carries from one step to the next: the physics. A
   keyed bone is posed at the loop time the render from rest draws it at, to the
   rounding of the steps' sums — on the skirt fixture's hip, measured on this walk
@@ -9921,6 +9951,53 @@ still refused above 0, would reach the same looping walk; counted in steps rathe
 than loops, it would move every compared frame off its `FrameRef` time unless the
 steps were whole loops.
 
+### 8.14 Physics-off renders and boundary comparisons
+
+`rigc render --candidate <dir> --physics off --out <off>` suppresses every physics
+constraint on both posers, after the animation timelines apply. Every other
+constraint and the animation clock keep their ordinary walk. `--physics on` is the
+default. Any other value is refused by name. An omitted mode retains the existing
+render bytes. Off records `physicsMode: "off"` in `frames.json`, geometry and sheet
+metadata, and adds a `physics=off` variant to sheet frame keys. A reference
+without the field means on. `check` refuses an off reference because its candidate
+is posed with physics on.
+
+To compare two whole-figure renders, first render the reference, then render the
+second with `--viewport-from <reference-dir> --boundary-from <reference-dir>`.
+For example, render the public gallery physics recipe normally, then render it
+with those two flags and `--physics off`. Use the same animation selection, skin,
+fps and pre-roll on both runs. The shared viewport fixes the world box, scale and
+pixel dimensions. Check the viewport's recorded `pinned.outside` when interpreting
+an outline that reaches the canvas edge.
+
+`boundary.json` (`rigc-boundary-difference/1`) records each matching frame's maximum
+symmetric nearest-boundary distance in **L-infinity pixels**, and the maximum over
+the frames read. A boundary pixel is visible foreground with at least one
+four-neighbour background pixel, or a foreground pixel on the canvas edge. Holes
+contribute boundaries too. Foreground means the rendered RGBA differs from the
+recorded background exactly. Background-coloured art has no observable coverage
+in this reading, and anything outside the viewport is absent. This is a pixel
+reading with no registration, threshold or pass verdict.
+
+An identical on/on pair reads zero. An on/off pair measures the visible outline
+change on the chosen grid. Empty boundaries report `SKIP`, never zero. A frame
+schedule, viewport, background, skin, set roster or file mismatch also reports
+`SKIP` with a reason. Missing or unreadable frames remain unavailable. Mixed
+readable and empty frames report `PARTIAL` with the per-frame reasons. Both sides
+must record the same slot selection. `scope` records that selection explicitly. A backdrop is part of the visible outline when it is drawn, so a
+full-canvas opaque backdrop can make the distance zero even while the character
+moves. For `gallery/look`, use `--hide plate` on both renders to read the character
+without its backdrop. Every other drawn slot still contributes to that outline.
+`--extremes-only` takes no `--boundary-from`, and the reference directory must differ
+from `--out`. Reusing an output directory clears its previous `boundary.json`
+before writing the new render, including an `--extremes-only` render.
+
+`--extremes` chooses a pair within one animation and reads corresponding authored
+vertices and local channels. Subtracting two extreme readings does not compare
+the same frames' visible outlines. `diff` compares skeleton data, and `check`
+reposes and registers a candidate against reference pictures. Neither reads two
+already-rendered whole-figure boundaries on an unchanged grid.
+
 ## 9. Checking against the frames — `rigc check`
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-c",
-  "version": "3.2.0",
+  "version": "3.3.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/boundary.ts

@@ -0,0 +1,129 @@
+/** Visible boundary displacement on the recorded pixel grid, without registration or thresholds. */
+import { readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { readPlate, type Plate, type RGBA } from '../tools/plate.ts';
+import { FRAMES_SPEC, type FramesSidecar } from './render_shared.ts';
+
+type DistanceReading = { status: 'READ'; maxPixels: number } | { status: 'SKIP'; reason: string };
+
+/** Background-coloured pixels carry no observable foreground coverage. */
+export function visibleBoundary(plate: Plate, background: RGBA): number[] {
+  const { width, height, data } = plate;
+  const foreground = new Uint8Array(width * height);
+  for (let pixel = 0; pixel < foreground.length; pixel++) {
+    foreground[pixel] = background.some((value, channel) => data[pixel * 4 + channel] !== value) ? 1 : 0;
+  }
+  const boundary: number[] = [];
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const pixel = y * width + x;
+      if (foreground[pixel] && (
+        x === 0 || y === 0 || x === width - 1 || y === height - 1 ||
+        !foreground[pixel - 1] || !foreground[pixel + 1] ||
+        !foreground[pixel - width] || !foreground[pixel + width]
+      )) boundary.push(pixel);
+    }
+  }
+  return boundary;
+}
+
+/** Exact eight-neighbour nearest-boundary distance in L-infinity pixels. Linear in canvas area. */
+function distances(width: number, height: number, boundary: readonly number[]): Int32Array {
+  const distance = new Int32Array(width * height).fill(-1);
+  const queue = new Int32Array(distance.length);
+  let end = 0;
+  for (const pixel of boundary) {
+    distance[pixel] = 0;
+    queue[end++] = pixel;
+  }
+  for (let head = 0; head < end; head++) {
+    const pixel = queue[head];
+    const x = pixel % width;
+    const y = Math.floor(pixel / width);
+    for (let dy = -1; dy <= 1; dy++) {
+      for (let dx = -1; dx <= 1; dx++) {
+        const nextX = x + dx, nextY = y + dy;
+        if (nextX < 0 || nextY < 0 || nextX >= width || nextY >= height) continue;
+        const next = nextY * width + nextX;
+        if (distance[next] !== -1) continue;
+        distance[next] = distance[pixel] + 1;
+        queue[end++] = next;
+      }
+    }
+  }
+  return distance;
+}
+
+export function boundaryDistance(a: Plate, b: Plate, background: RGBA): DistanceReading {
+  if (a.width !== b.width || a.height !== b.height) return { status: 'SKIP', reason: 'pixel dimensions differ' };
+  const left = visibleBoundary(a, background), right = visibleBoundary(b, background);
+  if (left.length === 0 || right.length === 0) {
+    return { status: 'SKIP', reason: 'one or both frames have no visible foreground boundary' };
+  }
+  const toLeft = distances(a.width, a.height, left), toRight = distances(a.width, a.height, right);
+  let maxPixels = 0;
+  for (const pixel of left) maxPixels = Math.max(maxPixels, toRight[pixel]);
+  for (const pixel of right) maxPixels = Math.max(maxPixels, toLeft[pixel]);
+  return { status: 'READ', maxPixels };
+}
+
+const SCHEDULE_FIELDS = ['animation', 'fps', 'sampled', 'written', 'stride', 'duration'] as const;
+
+/** A failed observation remains a named SKIP and never becomes a zero distance. */
+export function boundaryComparison(reference: string, current: string, sidecar: FramesSidecar) {
+  const spec = 'rigc-boundary-difference/1';
+  const skip = (reason: string) => ({ spec, status: 'SKIP' as const, reason });
+  try {
+    if (realpathSync(reference) === realpathSync(current)) return skip('reference and output directories are the same');
+    const before = JSON.parse(readFileSync(join(reference, 'frames.json'), 'utf8')) as FramesSidecar;
+    if (before.spec !== FRAMES_SPEC || !Array.isArray(before.sets)) return skip('reference requires a render frames.json');
+    const coordinates = Object.keys(sidecar.viewport) as Array<keyof typeof sidecar.viewport>;
+    if (!before.viewport || coordinates.some((key) => !Number.isFinite(before.viewport[key]) || before.viewport[key] !== sidecar.viewport[key])) {
+      return skip('world viewport or pixel grid differs, use --viewport-from');
+    }
+    if (JSON.stringify(before.background) !== JSON.stringify(sidecar.background)) return skip('recorded backgrounds differ');
+    if (before.skin !== sidecar.skin || JSON.stringify(before.slots) !== JSON.stringify(sidecar.slots) || JSON.stringify(before.hidden) !== JSON.stringify(sidecar.hidden)) {
+      return skip(`skin or drawn slot selection differs: reference ${JSON.stringify({ skin: before.skin ?? null, slots: before.slots ?? null, hidden: before.hidden ?? null })}, current ${JSON.stringify({ skin: sidecar.skin ?? null, slots: sidecar.slots ?? null, hidden: sidecar.hidden ?? null })}. Required equal recorded selections`);
+    }
+    const frames: Array<{ set: string; file: string } & DistanceReading> = [];
+    for (const set of sidecar.sets) {
+      const match = before.sets.find((other) => other.dir === set.dir);
+      if (!match || SCHEDULE_FIELDS.some((key) => match[key] !== set[key])) {
+        return skip(`set ${JSON.stringify(set.dir)} has a different frame schedule`);
+      }
+      if (!set.dir || set.dir === '..' || set.dir === '.' || set.dir.includes('/') || set.dir.includes('\\')) {
+        return skip('set directory must be one relative directory name');
+      }
+      const names = (root: string): string[] => readdirSync(join(root, set.dir)).filter((name) => /^f\d+\.png$/.test(name)).sort();
+      const left = names(reference), right = names(current);
+      if (left.length === 0 || left.length !== set.written || JSON.stringify(left) !== JSON.stringify(right)) {
+        return skip(`set ${JSON.stringify(set.dir)} has missing or different frame files`);
+      }
+      for (const file of left) {
+        const a = readPlate(join(reference, set.dir, file)), b = readPlate(join(current, set.dir, file));
+        if ([a, b].some((plate) => plate.width !== sidecar.viewport.pixelWidth || plate.height !== sidecar.viewport.pixelHeight)) {
+          return skip(`set ${JSON.stringify(set.dir)} frame ${file} pixel dimensions disagree with frames.json`);
+        }
+        frames.push({ set: set.dir, file, ...boundaryDistance(a, b, sidecar.background) });
+      }
+    }
+    if (before.sets.length !== sidecar.sets.length || frames.length === 0) return skip('set roster differs or no frames were compared');
+    const readings = frames.filter((frame) => frame.status === 'READ');
+    let maxPixels = 0;
+    for (const frame of readings) if (frame.status === 'READ') maxPixels = Math.max(maxPixels, frame.maxPixels);
+    return {
+      spec,
+      status: readings.length === frames.length ? 'READ' : readings.length ? 'PARTIAL' : 'SKIP',
+      metric: 'symmetric Hausdorff L-infinity pixels',
+      coverage: 'visible pixels differing from the recorded background. Four-neighbour boundary including holes, clipped to viewport',
+      referencePhysics: before.physicsMode ?? 'on',
+      physics: sidecar.physicsMode ?? 'on',
+      scope: { slots: sidecar.slots ?? null, hidden: sidecar.hidden ?? null },
+      viewport: sidecar.viewport,
+      maxPixels: readings.length ? maxPixels : null,
+      frames,
+    };
+  } catch (error) {
+    return skip(`boundary unavailable: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}

package/src/check.ts

@@ -1298,6 +1298,9 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
         'difference between two worlds. Render the reference frames without --environment.',
     );
   }
+  if (located.sidecar?.physicsMode === 'off') {
+    throw new CheckError('frames.json records physicsMode off, while check poses the candidate with physics on. Render the reference with --physics on.');
+  }
   // A frame set drawn after a pre-roll (`render --preroll`, issue #1684) shows the physics warm; check poses the
   // candidate from rest, so the score would be a number about the difference between a warm loop and a cold one.
   const referencePreroll = located.sidecar?.preroll;

package/src/cli/core_commands.ts

@@ -1,3 +1,4 @@
+import { boundaryComparison } from '../boundary.ts';
 import { sampleParallax, parallaxPlate } from '../parallax_render.ts';
 import { textureScaleReading, textureScaleLines, TEXTURE_SCALE_FPS } from '../texture_scale.ts';
 import { extremesOf, extremesText, extremesPlate, extremesLine, extremesRefusal } from '../extremes.ts';
@@ -723,6 +724,8 @@ export function cmdRender(flags: Record<string, string>): void {
   // The pre-roll (issue #1684), read and refused as early, and refused beside a schedule: under a pre-roll a schedule's
   // `t` could be read on the recording's clock or on the walk's, the two give different physics, and nothing settles it.
   const preroll = readPrerollFlag(flags);
+  if (flags.physics !== undefined && flags.physics !== 'on' && flags.physics !== 'off') throw new UsageError(`--physics ${JSON.stringify(flags.physics)}: required on or off`);
+  const physicsMode = flags.physics === 'off' ? 'off' as const : undefined;
   if (preroll !== undefined && environment !== undefined) {
     throw new UsageError(
       `--preroll takes no --environment: a schedule's t could be read from the first frame recorded or from the first loop walked, ` +
@@ -734,7 +737,7 @@ export function cmdRender(flags: Record<string, string>): void {
   const given = readGivenViewport(flags);
   const extremesOnly = flags['extremes-only'] !== undefined;
   if (extremesOnly) {
-    for (const flag of ['sheet', 'sheet-format', 'page-edges', 'geometry', 'folds', 'pass-through', 'seam', 'overlaps', 'angle-range']) {
+    for (const flag of ['sheet', 'sheet-format', 'page-edges', 'geometry', 'folds', 'pass-through', 'seam', 'overlaps', 'angle-range', 'boundary-from']) {
       if (flags[flag] !== undefined) {
         throw new UsageError(`--extremes-only takes no --${flag}: it writes only extremes.json and, when readable, extremes.png. Drop --${flag}, or use --extremes for ordinary frames and additional outputs`);
       }
@@ -753,6 +756,7 @@ export function cmdRender(flags: Record<string, string>): void {
   const sheetFormat = wantsSheet ? readSheetFormat(flags) : undefined;
   const sheetPageEdges = wantsSheet ? readPageEdges(flags) : undefined;
   const outRoot = resolve(flags.out ?? 'render');
+  if (flags['boundary-from'] !== undefined && realpathAhead(flags['boundary-from']) === realpathAhead(outRoot)) throw new UsageError('--boundary-from must name an earlier render directory different from --out');
   const geometry = flags.geometry !== undefined;
   const extremes = extremesOnly || flags.extremes !== undefined;
   // The fold reading (issue #1383) is its own flag rather than a part of --geometry, so a caller that asked for
@@ -850,7 +854,7 @@ export function cmdRender(flags: Record<string, string>): void {
     posersAsked(flags),
   );
   if (flags.parallax !== undefined) {
-    for (const flag of ['animation', 'fps', 'slot', 'hide', 'geometry', 'folds', 'extremes', 'extremes-only', 'pass-through', 'seam', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'preroll', 'viewport', 'viewport-from']) {
+    for (const flag of ['animation', 'fps', 'slot', 'hide', 'geometry', 'folds', 'extremes', 'extremes-only', 'pass-through', 'seam', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'preroll', 'physics', 'boundary-from', 'viewport', 'viewport-from']) {
       if (flags[flag] !== undefined) throw new UsageError(`--parallax takes no --${flag}: it samples one named dial on its own 9-value grid; drop --${flag} or run ordinary render separately`);
     }
     if (flags.poser !== undefined && flags.poser !== 'core') throw new UsageError('--parallax requires --poser core: it reads only a rigc compiled model');
@@ -898,13 +902,14 @@ export function cmdRender(flags: Record<string, string>): void {
   // what the frames under it draw.
   // The pre-roll rides on it for the environment's reason (issue #1684): it changes the pose, so the framing reads it.
   const pose =
-    skin === undefined && subset === undefined && environment === undefined && preroll === undefined
+    skin === undefined && subset === undefined && environment === undefined && preroll === undefined && physicsMode === undefined
       ? undefined
       : {
           ...(skin === undefined ? {} : { skin }),
           ...subsetFields(subset),
           ...(environment === undefined ? {} : { environment: environment.steps }),
           ...(preroll === undefined ? {} : { preroll }),
+          ...(physicsMode === undefined ? {} : { physicsMode }),
         };
   if (skin !== undefined) console.log(`  ..    skin     ${skin}`);
   if (subset !== undefined) console.log(`  ..    ${subset.mode.padEnd(8)} ${subset.names.join(', ')}`);
@@ -1019,7 +1024,7 @@ export function cmdRender(flags: Record<string, string>): void {
     if (geometry) {
       for (const [name, frames] of sampled) {
         const animation = name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name;
-        geometryTexts.set(name, geometryText(geometryFileOf(poser, animation, fps, frames, viewport, skin, environment?.steps, preroll)));
+        geometryTexts.set(name, geometryText(geometryFileOf(poser, animation, fps, frames, viewport, skin, environment?.steps, preroll, physicsMode)));
       }
     }
     // The fold reading, off the very attachments the frames were drawn from, against the rest table the geometry
@@ -1151,6 +1156,7 @@ export function cmdRender(flags: Record<string, string>): void {
               subset,
               environment: environment?.steps,
               preroll,
+              physicsMode,
               pinned,
             }),
           );
@@ -1194,6 +1200,8 @@ export function cmdRender(flags: Record<string, string>): void {
   }
 
   mkdirSync(outRoot, { recursive: true });
+  // A prior observation cannot describe the new frames, including an observation-only render.
+  rmSync(join(outRoot, 'boundary.json'), { force: true });
   if (extremesOnly) {
     // Reuse the same posed grid and plates; selecting extremes needs no ordinary pixels.
     // Clear only the selected sets, just as the ordinary render does. No frames.json
@@ -1289,7 +1297,7 @@ export function cmdRender(flags: Record<string, string>): void {
         : ` + ${sheetPack.pages.map((p) => `${p.image} + ${p.table}`).join(' + ')} + ${SHEET_MANIFEST_FILE} (${sheetPack.pages.length} page(s), ${sheetPack.pageEdges})`;
     const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${sheetNote}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}${passNote}${seamNote}${overlapNote}`;
     console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${extras} -> ${dir}`);
-    if (physics !== undefined) console.log(`  ..    ${physicsLine(physics.stepped, physicsDeclared, fps, frames.length)}`);
+    if (physics !== undefined) console.log(`  ..    ${physicsLine(physics.stepped, physicsDeclared, fps, frames.length, physicsMode)}`);
     for (const mesh of foldReading?.meshes ?? []) {
       const key = `${mesh.slot}\u0000${mesh.attachment}`;
       const fault = faultsSaid.has(key) ? null : setupFaultLine(mesh);
@@ -1330,6 +1338,7 @@ export function cmdRender(flags: Record<string, string>): void {
     ...(environment === undefined ? {} : { environment: environment.steps }),
     // Written only when a pre-roll was asked for (issue #1684), for the same reason.
     ...(preroll === undefined ? {} : { preroll }),
+    ...(physicsMode === undefined ? {} : { physicsMode }),
     // Written only when the box was given (issue #1414): a fitted render says nothing and stays the bytes it was.
     ...(given === undefined ? {} : { pinned: pinnedRecord(given.by, outside) }),
     background: BACKGROUND,
@@ -1340,6 +1349,13 @@ export function cmdRender(flags: Record<string, string>): void {
   };
   writeFileSync(join(outRoot, FRAMES_SIDECAR), `${JSON.stringify(sidecar, null, 2)}\n`);
   console.log(`rigc: wrote ${join(outRoot, FRAMES_SIDECAR)}`);
+  if (flags['boundary-from'] !== undefined) {
+    const reading = boundaryComparison(resolve(flags['boundary-from']), outRoot, sidecar);
+    writeFileSync(join(outRoot, 'boundary.json'), `${JSON.stringify(reading, null, 2)}\n`);
+    const detail = 'reason' in reading ? reading.reason : `max ${String(reading.maxPixels)} L-infinity px over ${reading.frames.length} frame(s)`;
+    console.log(`  ..    boundary ${reading.status}: ${detail}`);
+    console.log(`rigc: wrote ${join(outRoot, 'boundary.json')}`);
+  }
 }
 
 /**
@@ -1371,11 +1387,11 @@ export function physicsSteppedOf(frames: readonly Frame[], fps: number): { stepp
  * `render`'s `physics:` line for one set (issue #1467): how many constraints were stepped at the set's rate, and — when
  * fewer than the rig declares — the ones that took no step, by name, with why a constraint takes none.
  */
-export function physicsLine(stepped: readonly string[], declared: readonly string[], fps: number, frames: number): string {
+export function physicsLine(stepped: readonly string[], declared: readonly string[], fps: number, frames: number, physicsMode?: 'off'): string {
   const head = `physics: ${stepped.length} constraint(s) stepped at ${fps} fps`;
   const idle = declared.filter((name) => !stepped.includes(name));
   if (idle.length === 0) return head;
-  const why = frames === 1 ? 'a single pose takes no step' : 'inactive, or a mix of 0, on every frame';
+  const why = physicsMode === 'off' ? '--physics off suppresses every physics constraint' : frames === 1 ? 'a single pose takes no step' : 'inactive, or a mix of 0, on every frame';
   return `${head} — ${idle.length} of the ${declared.length} declared took none: ${idle.map((n) => JSON.stringify(n)).join(', ')} (${why})`;
 }
 

package/src/cli/shared.ts

@@ -1108,6 +1108,8 @@ const FLAG_MEANINGS: Record<string, string> = {
     'runtime\'s, wind [1, 0] and gravity [0, 1]. frames.json and geometry.json record it, and the framing reads it. A ' +
     'malformed file, a half no physics constraint answers, two steps on one frame and a step after every set\'s last frame ' +
     'are refused by name. An inspection of what the rig offers, not a scene',
+  physics: 'pose with physics on (default) or off. Off suppresses every physics constraint after timeline application on both posers. frames.json records physicsMode off and check refuses that reference',
+  'boundary-from': 'read visible whole-figure pixel-boundary displacement against an earlier render on the identical viewport and frame grid. Writes boundary.json, no threshold or pass verdict',
   preroll:
     'walk each set this many whole loops on a looping track before the loop recorded, drawn by no frame, the physics carried ' +
     'across every wrap as a player\'s looping track carries it — so a spring that converges is warm on the first frame. Frame i is the ' +
@@ -1307,6 +1309,8 @@ const FLAG_VALUES: Record<string, string> = {
   'texture-from': '<path>',
   poser: 'core|spine',
   environment: '<schedule.json>',
+  physics: '<on|off>',
+  'boundary-from': '<dir>',
   preroll: '<n>',
   'pass-through': '<cloth>:<leg>[,<cloth>:<leg>…]',
   seam: '<slot>:<slot>[,<slot>:<slot>…]',
@@ -1785,7 +1789,7 @@ export const COMMANDS: CommandDoc[] = [
       'rigc render … --viewport <x,y,w,h> | --viewport-from <frames.json>   (a box given, not fitted: two renders on one pixel grid)',
       'rigc render … --sheet [--sheet-format json-hash] [--page-edges pot|free]   (deterministic sprite sheets + JSON hash table + sheet-manifest.json per set)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'extremes', 'extremes-only', 'parallax', 'pass-through', 'seam', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'preroll', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'extremes', 'extremes-only', 'parallax', 'pass-through', 'seam', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'preroll', 'physics', 'boundary-from', 'poser', 'out'],
     overrides: {
       'page-edges': {
         meaning:

package/src/render.ts

@@ -502,8 +502,8 @@ export function spinePoser(data: SkeletonData): Poser {
     bones: data.bones.map((bone) => ({ name: bone.name, parent: bone.parent?.name ?? null })),
     slots: data.slots.map((slot) => ({ name: slot.name, bone: slot.boneData.name })),
     subset: (opts, skin) => slotSubsetOf(data, opts, skin),
-    setup: (skin) => spinePosed(setupPosed(data, skin)),
-    animation: (name, skin, fps, count, visit, environment, _channels, times, loop) => {
+    setup: (skin, _channels, physicsMode) => spinePosed(setupPosed(data, skin, physicsMode)),
+    animation: (name, skin, fps, count, visit, environment, _channels, times, loop, clockSteps, physicsMode) => {
       const skeleton = skeletonUnderSkin(data, skin);
       const state = new AnimationState(new AnimationStateData(data));
       // Not looping: the last frame sits at the animation's duration, and a looping
@@ -522,13 +522,14 @@ export function spinePoser(data: SkeletonData): Poser {
           state.update(delta);
           state.apply(skeleton);
           setSkeletonEnvironment(skeleton, environment?.(i));
-          skeleton.update(times === undefined ? clock : physicsClockStep(delta));
-          skeleton.updateWorldTransform(Physics.update);
+          // `clockSteps` (issue #1687, `render --preroll`): what the step moves the physics clock by, where that is not its own length.
+          skeleton.update(times === undefined ? clock : physicsClockStep(clockSteps?.[i - 1] ?? delta));
+          skeleton.updateWorldTransform(physicsMode === 'off' ? Physics.none : Physics.update);
         } else {
           state.apply(skeleton);
           setSkeletonEnvironment(skeleton, environment?.(i));
           skeleton.update(0);
-          skeleton.updateWorldTransform(Physics.reset);
+          skeleton.updateWorldTransform(physicsMode === 'off' ? Physics.none : Physics.reset);
         }
         visit(i, posed);
       }
@@ -591,11 +592,11 @@ function steppedPhysicsOf(skeleton: Skeleton): string[] {
  * `sampleSetupPose` and the geometry export's `rest` table both pose from, so
  * the two cannot come to describe different rest poses.
  */
-function setupPosed(data: SkeletonData, skin: string | undefined): Skeleton {
+function setupPosed(data: SkeletonData, skin: string | undefined, physicsMode?: 'off'): Skeleton {
   const skeleton = skeletonUnderSkin(data, skin);
   skeleton.setupPose();
   skeleton.update(0);
-  skeleton.updateWorldTransform(Physics.reset);
+  skeleton.updateWorldTransform(physicsMode === 'off' ? Physics.none : Physics.reset);
   return skeleton;
 }
 

package/src/render_core.ts

@@ -367,18 +367,35 @@ export function keptPieceArrays(): PieceArrays {
  * one pose is held at a time rather than the animation's whole series. A plant
  * passes another (`RC44`).
  */
-export type CoreRawWalk = (doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant, visit: (pose: RawPose, index: number) => void, environment?: StepEnvironment, loop?: boolean) => void;
+export type CoreRawWalk = (doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant, visit: (pose: RawPose, index: number) => void, environment?: StepEnvironment, loop?: boolean, clock?: (dt: number) => number) => void;
 
 /**
  * The walk `corePoser` steps with unless a plant passes another: one pose posed, drawn and released before the next, the
  * physics clock moved by `physicsClockStep` (issue #1380), and `render --environment`'s change for each pose set before it
  * is posed (issue #1416, `StepEnvironment`). `loop` (issue #1684, `render --preroll`) walks the track looping
  * (`poseRawLoopEach`) — spine-core's poser sets the same track looping — and absent, the walk is the one it always was.
+ * `clock` (issue #1687) is what each step moves the physics clock by in place of `physicsClockStep` of the step — the
+ * pre-roll's walk passes one that reads its own step list (`Poser.animation`'s `clockSteps`) — and absent, the clock is
+ * the render's, `physicsClockStep`.
  */
-export const CORE_RAW_WALK: CoreRawWalk = (doc, animation, steps, plant, visit, environment, loop) =>
+export const CORE_RAW_WALK: CoreRawWalk = (doc, animation, steps, plant, visit, environment, loop, clock = physicsClockStep) =>
   loop === true
-    ? poseRawLoopEach(doc, animation, steps, plant, 'animation', visit, physicsClockStep, environment)
-    : poseRawAnimationEach(doc, animation, steps, plant, 'animation', visit, physicsClockStep, environment);
+    ? poseRawLoopEach(doc, animation, steps, plant, 'animation', visit, clock, environment)
+    : poseRawAnimationEach(doc, animation, steps, plant, 'animation', visit, clock, environment);
+
+/**
+ * The physics clock a walk moves by `clockSteps` (issue #1687, `Poser.animation`): the walk asks its clock once for
+ * the reset pose — a step of 0, which moves it by `physicsClockStep(0)`, nothing, as spine-core's `update(0)` at frame
+ * 0 does — and then once per step in order, and step `i` moves it by `physicsClockStep(clockSteps[i])` in place of
+ * `physicsClockStep` of the step's own length. One clock serves one walk: it counts the steps it was asked for.
+ */
+function steppedClock(clockSteps: readonly number[]): (dt: number) => number {
+  let next = -1;
+  return (dt) => {
+    const i = next++;
+    return physicsClockStep(i < 0 ? dt : clockSteps[i]);
+  };
+}
 
 /**
  * The render's physics clock (issue #1380): defined beside the walk that takes it (`./core/raw.ts`), where the mesh
@@ -787,14 +804,14 @@ export function corePoser(
       const result = poseRawDial(input.doc, override, name, { through });
       return { posed: corePosed(input, result.pose, through, []), read: result.read, applied: result.applied };
     },
-    setup: (skin, channels) => {
+    setup: (skin, channels, physicsMode) => {
       const input = inputOf(skin);
       let values: ChannelValue[] | undefined;
       const observe = channels ? { readLocals: (bones: readonly import('./model.ts').ModelBone[], sliders: readonly import('./core/constraints_slider.ts').SliderApplication[]) => { values = localChannels(bones, sliders); } } : {};
-      const pose = poseRawSetup(input.doc, { through, ...observe });
+      const pose = poseRawSetup(input.doc, { through, ...observe, ...(physicsMode === 'off' ? { physicsStep: () => false } : {}) });
       return corePosed(input, pose, through, [], values);
     },
-    animation: (name, skin, fps, count, visit, environment, channels, times, loop) => {
+    animation: (name, skin, fps, count, visit, environment, channels, times, loop, clockSteps, physicsMode) => {
       let values: ChannelValue[] | undefined;
       const observe = channels ? { readLocals: (bones: readonly import('./model.ts').ModelBone[], sliders: readonly import('./core/constraints_slider.ts').SliderApplication[]) => { values = localChannels(bones, sliders); } } : {};
       const input = inputOf(skin);
@@ -810,10 +827,12 @@ export function corePoser(
       const steppedNow = new Set<string>();
       const inner = plants.physicsStep ?? stepPhysics;
       const physicsStep: PhysicsStepper = (r, w, length, ctx) => {
+        if (physicsMode === 'off') return false;
         const moved = inner(r, w, length, ctx);
         if (ctx.time > 0 && ctx.states.get(r.name)?.lastTime === ctx.time) steppedNow.add(r.name);
         return moved;
       };
+      const clock = clockSteps === undefined ? undefined : steppedClock(clockSteps);
       walk(input.doc, name, times === undefined ? new Array<number>(count).fill(step) : times.slice(1).map((t, i) => t - times[i]), { through, physicsStep, ...observe }, (pose, i) => {
         const stepped = [...steppedNow].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
         steppedNow.clear();
@@ -823,7 +842,7 @@ export function corePoser(
         } catch (thrown) {
           drawFailed.push(thrown);
         }
-      }, environment, loop);
+      }, environment, loop, clock);
       if (drawFailed.length > 0) throw drawFailed[0];
     },
     rest: (skin, shown) => {

package/src/render_shared.ts

@@ -243,6 +243,8 @@ export interface FrameSet {
 }
 
 export interface FramesSidecar {
+  /** Absent means on, including frame sets written before this field existed. */
+  physicsMode?: 'off';
   spec: string;
   example?: string;
   rung?: string;
@@ -427,6 +429,8 @@ export interface UvWindow {
 
 /** Options for `piecesOf` and the samplers that call it. */
 export interface PoseOptions {
+  /** Suppress every physics constraint after animation application. */
+  physicsMode?: 'off';
   /** Also read local bone/deform channels and mapped slider times, and retain original attachment source identity outside JSON, for --extremes. */
   channels?: boolean;
   /** Also record each piece's original-art UVs — see `PieceTexture`. */
@@ -1184,7 +1188,7 @@ export interface Poser {
   /** `slotSubsetOf` against this skeleton posed under `skin` — refused by `SlotSubsetError`. */
   subset(opts: Pick<PoseOptions, 'slots' | 'hidden'> | undefined, skin: string | undefined): SlotSubset | undefined;
   /** The setup pose under `skin` (absent: no skin set at all). */
-  setup(skin: string | undefined, channels?: boolean): Posed;
+  setup(skin: string | undefined, channels?: boolean, physicsMode?: 'off'): Posed;
   /**
    * Animation `name` under `skin`, not looping: `visit(i, posed)` for every
    * `i` from 0 to `count`, the pose at `i/fps`. The caller has checked `name`.
@@ -1198,8 +1202,14 @@ export interface Poser {
    * animation time the track time wrapped by the duration, the physics carried
    * across every wrap, as a player's looping track carries it; absent, the
    * track holds at its duration as it always did.
+   * `clockSteps` (issue #1687, `render --preroll`), beside `times`, is what
+   * each step moves the physics clock by before the lead: step `i` (from 1)
+   * moves it by `physicsClockStep(clockSteps[i - 1])` in place of
+   * `physicsClockStep(times[i] - times[i - 1])`, while the track time still
+   * follows `times` (`prerollTimes` says why the two part). Absent, every
+   * step moves the physics clock by its own length, as it always did.
    */
-  animation(name: string, skin: string | undefined, fps: number, count: number, visit: (index: number, posed: Posed) => void, environment?: (index: number) => EnvironmentChange | undefined, channels?: boolean, times?: readonly number[], loop?: boolean): void;
+  animation(name: string, skin: string | undefined, fps: number, count: number, visit: (index: number, posed: Posed) => void, environment?: (index: number) => EnvironmentChange | undefined, channels?: boolean, times?: readonly number[], loop?: boolean, clockSteps?: readonly number[], physicsMode?: 'off'): void;
   /** The rest table for the (slot, attachment) pairs `shown` holds — see `AttachmentRest`. */
   rest(skin: string | undefined, shown: readonly AttachmentPose[][]): AttachmentRest[];
 }
@@ -1280,18 +1290,19 @@ export function sampleAnimation(source: PoseSource, name: string, fps: number, o
     if (!Number.isInteger(preroll) || preroll < 1) throw new Error(`preroll is ${String(preroll)}, not a whole number of loops at or above 1`);
     if (opts?.environment !== undefined) throw new Error('preroll and environment were both given: nothing settles which clock the schedule is read on under a pre-roll');
     // The track loops; every pose before track time `preroll · duration` is walked and drawn by no frame (issue #1684).
-    const { times, first } = prerollTimes(animation.duration, fps, preroll);
+    const { times, first, clock } = prerollTimes(animation.duration, fps, preroll);
     const recorded = (i: number, posed: Posed): void => {
       if (i >= first) frames.push(frameOf(i - first, (i - first) * step, posed, draw(), opts));
     };
-    poser.animation(name, opts?.skin, fps, times.length - 1, recorded, undefined, opts?.channels === true ? true : undefined, times, true);
+    poser.animation(name, opts?.skin, fps, times.length - 1, recorded, undefined, opts?.channels === true ? true : undefined, times, true, clock, opts?.physicsMode);
     return frames;
   }
   const visit = (i: number, posed: Posed): void => {
     frames.push(frameOf(i, i * step, posed, draw(), opts));
   };
   // Without an environment the call is the one it always was, so a poser that takes none is asked nothing new.
-  if (opts?.channels) poser.animation(name, opts.skin, fps, count, visit, opts.environment === undefined ? undefined : environmentAt(opts.environment, fps), true);
+  if (opts?.physicsMode === 'off') poser.animation(name, opts.skin, fps, count, visit, opts.environment === undefined ? undefined : environmentAt(opts.environment, fps), opts.channels, undefined, undefined, undefined, 'off');
+  else if (opts?.channels) poser.animation(name, opts.skin, fps, count, visit, opts.environment === undefined ? undefined : environmentAt(opts.environment, fps), true);
   else if (opts?.environment === undefined) poser.animation(name, opts?.skin, fps, count, visit);
   else poser.animation(name, opts.skin, fps, count, visit, environmentAt(opts.environment, fps));
   return frames;
@@ -1338,13 +1349,14 @@ export function prerollWarmPoints(start: number, fps: number): number {
 }
 
 /**
- * The track times a pre-roll of `preroll` loops walks, for `Poser.animation`'s
- * `times` (issue #1684): the render's grid `j / fps` up to the last point
- * before `prerollStart`, one shorter step onto it, then the loop recorded,
- * `start + i / fps` for `i = 1..count`. `first` is the index of `start` — the
- * pose frame 0 is.
+ * The walk a pre-roll of `preroll` loops takes, for `Poser.animation`'s `times`
+ * and `clockSteps` (issues #1684, #1687): the track times — the render's grid
+ * `j / fps` up to the last point before `prerollStart`, one step onto it, then
+ * the loop recorded, `start + i / fps` for `i = 1..count` — and what each step
+ * moves the physics clock by. `first` is the index of `start`, the pose frame 0
+ * is.
  *
- * ⭐ **The walk lands on `start` exactly.** Both posers step a track by the
+ * ⭐ **The track lands on `start` exactly.** Both posers step a track by the
  * differences of `times` and add them up (`trackTime += delta`), and every
  * difference before `start` is exact — two floats within a factor of two of
  * each other subtract without rounding — so each running sum is the time it
@@ -1352,15 +1364,48 @@ export function prerollWarmPoints(start: number, fps: number): number {
  * `preroll · count` steps instead lands on `preroll · count / fps`, which is
  * the wrap only where `duration · fps` is whole: elsewhere the loop recorded
  * started at the wrong phase while frame 0 was filed at time 0.
- */
-export function prerollTimes(duration: number, fps: number, preroll: number): { times: number[]; first: number } {
+ *
+ * ⭐ **The physics clock lands on the grid, not on `start`** (issue #1687). The
+ * step onto `start` is a frame only where the duration is exactly `count /
+ * fps`. Where it is not — a duration read as a float32, `count / fps` less
+ * `δ` — it is a frame short by `preroll · δ`: 3.2e-7 s at 2 loops of a
+ * 2.6666665 s idle at 12 fps, against the 5.0e-9 s of `PHYSICS_CLOCK_LEAD`
+ * the clock has gathered there. A physics constraint takes the whole steps
+ * that fit, so a clock moved by that short step takes one fewer (4 in place
+ * of 5 at 12 fps against 60 Hz) and leaves 0.99998 of a step remaining where
+ * the plain walk leaves 3e-7 of one; every frame after keeps that phase, and
+ * the loop recorded is a fresh transient — measured on the selftest's
+ * four-link `preroll_probe`, its springs 26.4 units off the plain walk's loop
+ * on a stepped idle and 37.6 on an eased one, and its seam 1.38× its largest
+ * step after 10 loops (`PRE08`). ⚠️ The ⭐ above once stood alone as the
+ * walk's whole claim: it is true of the track and said nothing of the
+ * physics, which took the same step.
+ *
+ * So the physics clock is stepped by the same differences except the step
+ * onto `start`, which moves it to the grid point nearest the wrap,
+ * `round(start · fps) / fps`, and not to `start`: a whole frame where the
+ * wrap sits just short of a grid point, and nothing where it sits just past
+ * one — `δ` below 0, where that grid point is the last before `start` and the
+ * step onto `start` is the sliver past it. The loop recorded is then loop
+ * `preroll + 1` of a plain looping walk on the uniform grid, its physics clock
+ * off that walk's by rounding alone (`PRE07`), and frame 0 is still the wrap:
+ * the animation is re-phased onto it by `preroll · δ`, the one difference
+ * between the two that the physics answers. Where the duration is exactly
+ * `count / fps`, `start` is that grid point and the clock steps are the
+ * track's, so nothing moves; on a loop that is no whole number of frames at
+ * all (`PRE06`'s 1.03 s at 12 fps) the physics stays on the frame grid the
+ * same way and the animation is re-phased by under half a frame.
+ */
+export function prerollTimes(duration: number, fps: number, preroll: number): { times: number[]; first: number; clock: number[] } {
   const start = prerollStart(duration, preroll);
   const count = Math.round(duration * fps);
   const first = prerollWarmPoints(start, fps);
   const times = Array.from({ length: first }, (_, j) => j / fps);
   times.push(start);
   for (let i = 1; i <= count; i++) times.push(start + i / fps);
-  return { times, first };
+  const clock = times.slice(1).map((t, i) => t - times[i]);
+  if (first > 0) clock[first - 1] = Math.round(start * fps) / fps - times[first - 1];
+  return { times, first, clock };
 }
 
 /**
@@ -1373,7 +1418,7 @@ export function prerollTimes(duration: number, fps: number, preroll: number): {
  */
 export function sampleSetupPose(source: PoseSource, opts?: PoseOptions): Frame[] {
   const poser = poserOf(source);
-  const posed = opts?.channels ? poser.setup(opts.skin, true) : poser.setup(opts?.skin);
+  const posed = opts?.physicsMode === 'off' ? poser.setup(opts.skin, opts.channels, 'off') : opts?.channels ? poser.setup(opts.skin, true) : poser.setup(opts?.skin);
   return [frameOf(0, 0, posed, drawResolver(poser, opts)(), opts)];
 }
 
@@ -1697,6 +1742,7 @@ export interface GeometryFile {
   /** The setup pose, sampled the way `sampleSetupPose` samples it. */
   setup: Omit<GeometryFrame, 'index' | 'time'>;
   frames: GeometryFrame[];
+  physicsMode?: 'off';
 }
 
 /**
@@ -1744,6 +1790,7 @@ export function geometryFileOf(
   skin: string | undefined,
   environment?: EnvironmentStep[],
   preroll?: number,
+  physicsMode?: 'off',
 ): GeometryFile {
   const geometryFrame = (frame: Frame, where: string): Omit<GeometryFrame, 'index' | 'time'> => {
     if (frame.bones === undefined || frame.attachments === undefined) {
@@ -1760,7 +1807,7 @@ export function geometryFileOf(
     ...geometryFrame(frame, `frame ${frame.index}`),
   }));
   const poser = poserOf(source);
-  const setupFrame = sampleSetupPose(poser, { ...(skin === undefined ? {} : { skin }), bones: true, geometry: true })[0];
+  const setupFrame = sampleSetupPose(poser, { ...(skin === undefined ? {} : { skin }), bones: true, geometry: true, ...(physicsMode === undefined ? {} : { physicsMode }) })[0];
   const setup = geometryFrame(setupFrame, 'the setup pose');
   const file: GeometryFile = {
     spec: GEOMETRY_SPEC,
@@ -1769,6 +1816,7 @@ export function geometryFileOf(
     ...(skin === undefined ? {} : { skin }),
     ...(environment === undefined ? {} : { environment }),
     ...(preroll === undefined ? {} : { preroll }),
+    ...(physicsMode === undefined ? {} : { physicsMode }),
     fps,
     viewport: sidecarViewport(viewport),
     bones: poser.bones.map(({ name, parent }) => ({ name, parent })),

package/src/sheet.ts

@@ -120,6 +120,7 @@ export interface SheetManifest {
   environment?: EnvironmentStep[];
   /** The whole loops walked before the loop these frames record (`render --preroll`, issue #1684); absent without it. */
   preroll?: number;
+  physicsMode?: 'off';
   pinned?: PinnedViewport;
   fps: number;
   duration: number;
@@ -185,6 +186,7 @@ export interface BuildSheetSetOptions {
   subset?: SlotSubset;
   environment?: EnvironmentStep[];
   preroll?: number;
+  physicsMode?: 'off';
   pinned?: PinnedViewport;
   /** For negative-control testing in `selftest.ts` only: reverse the input order handed to `packAtlas`. */
   reversePackInputs?: boolean;
@@ -276,6 +278,7 @@ export function sheetNamespaceOf(opts: {
   subset?: SlotSubset;
   environment?: EnvironmentStep[];
   preroll?: number;
+  physicsMode?: 'off';
 }): string {
   const rig = sanitizeNamespaceSegment(opts.rigName);
   const anim = sanitizeNamespaceSegment(opts.setName);
@@ -287,6 +290,7 @@ export function sheetNamespaceOf(opts: {
     variants.push(`env=${digest}`);
   }
   if (opts.preroll !== undefined) variants.push(`preroll=${opts.preroll}`);
+  if (opts.physicsMode !== undefined) variants.push(`physics=${opts.physicsMode}`);
   return variants.length === 0 ? `${rig}/${anim}` : `${rig}/${anim}/${variants.join('+')}`;
 }
 
@@ -721,6 +725,7 @@ export function buildSheetSet(opts: BuildSheetSetOptions): SheetSetPack {
     subset: opts.subset,
     environment: opts.environment,
     preroll: opts.preroll,
+    physicsMode: opts.physicsMode,
   });
 
   const padding = SHEET_PADDING;
@@ -875,6 +880,7 @@ export function buildSheetSet(opts: BuildSheetSetOptions): SheetSetPack {
         : { hidden: [...opts.subset.names] }),
     ...(opts.environment === undefined ? {} : { environment: opts.environment }),
     ...(opts.preroll === undefined ? {} : { preroll: opts.preroll }),
+    ...(opts.physicsMode === undefined ? {} : { physicsMode: opts.physicsMode }),
     ...(opts.pinned === undefined ? {} : { pinned: opts.pinned }),
     fps: opts.fps,
     duration,