spine-rigc 3.1.0 → 3.2.0

package/docs/AUTHORING.md

@@ -129,7 +129,7 @@ commands take it and what its default is.
 | `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. a skeleton that declares no stage is carried as declaring none, `--stage x,y,w,h` adds a box to one — and is refused, rather than ignored, beside one that declares a box — and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all <a id="cmd-ingest"></a> |
 | `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. `--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 --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> |
 | `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,6 +389,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** |
 | `--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` |
@@ -5615,7 +5616,8 @@ that poses through its posers (`check`, `bonedist`, `inspect`, `--geometry`), ru
 the physics clock `2⁻³⁰` faster than the frames, so every such frame takes the steps
 exact arithmetic takes; the animation time is unchanged. A spring that has converged
 by the loop point therefore closes, which the loop-seam suite's `LS06` holds at all
-five rates. A player that steps the core entry's live tracks at a fixed rate — a
+five rates. A render from rest releases the spring at frame 0, so on a looping idle
+it has not converged by then; `render --preroll` (§8.13) walks whole loops first. A player that steps the core entry's live tracks at a fixed rate — a
 capture, an export, a test harness — is the render's case and takes the render's
 clock: `openTrack` and `openTracks` accept `clock`, what each step moves the physics
 clock by, and `physicsClockStep` (with `PHYSICS_CLOCK_LEAD`) is exported from
@@ -9825,6 +9827,100 @@ not draw order, colour, occlusion, tears, ghost lines or rendered optical flow.
 Compare the two fits, the per-sample curves and an explicit control before
 attributing residual to relief. No assertion, pass mark or build gate is added.
 
+### 8.13 A loop with its physics warm — `render --preroll`
+
+```bash
+bun cli.ts render --candidate path/to/spine --preroll 2 [--animation idle] [--geometry] [--sheet] [--poser core|spine]
+```
+
+A render walks one pass of each animation from rest: frame 0 resets the physics,
+and every later frame steps it. On a looping idle that is the one frame a player
+never shows — a player's looping track carries the physics across every wrap — so
+a video or a sprite sheet cut from one pass shows every spring released from rest
+at every wrap, and trimming or cross-fading frames hides it without making the
+loop honest. `--preroll <n>` sets the track **looping** and walks `n` whole loops
+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`
+  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
+  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
+  rounding, so the walk lands on `n · duration` exactly: recorded frame `i` is
+  the pose at animation time `i / fps`, filed under index `i` and time `i / fps`,
+  and the frame set has the shape a render from rest has.
+- **Why the shorter step.** A loop that is not a whole number of frames — 1.03 s
+  at 12 fps is 12.36 — is not `count` frames long, so `n · count` steps of
+  `1 / fps` land `n · (count / fps − duration)` seconds off the wrap: the loop
+  recorded would start mid-loop while frame 0 is filed at time 0, and
+  `frames.json` and `geometry.json` would misstate every frame's time. `PRE06`
+  holds a stepped key on such a loop — 0 on its first half, 12 on its second —
+  to the render from rest's at every frame of pre-rolls of 1 and 3, on both
+  posers, and the uniform grid planted on the core is red at frame 0 on both.
+  Both posers read a duration off float32 key times, so `n · duration` is a
+  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`).
+- **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
+  at 7, 13, 24 and 30 fps after 1 and 3 loops, no position or matrix entry moved
+  by more than 1.7e-13 — and on `PRE06`'s stepped key to the bit.
+- **Both posers, one walk.** The selftest's `render-preroll` suite renders three
+  rigs through the core and through `--poser spine` and holds every PNG,
+  `geometry.json`, sheet and `frames.json` equal (`PRE01`), and plants on the core
+  the two walks rejected — the loop flag ignored, so the track holds at its
+  duration through the pre-roll, and the pre-roll dropped, so the loop recorded is
+  walked from rest — each red against spine-core (`PRE03`).
+- **What it buys, measured.** On the skirt fixture (six chains of five links on
+  physics, swayed from the hip on a 2 s loop) at 12 fps, frame 0 against the last
+  frame of each physics bone — its tip and its rotation — ends past that bone's own
+  largest step between two adjacent frames on 29 of 30 bones from rest, the worst
+  at 4.5 times it; after one loop of pre-roll every bone ends within 0.015 of it
+  (`PRE02`, which reads it off the `geometry.json` the CLI wrote, on both posers).
+
+**The files.** `frames.json`, each `geometry.json` and each `sheet-manifest.json`
+record `preroll: <n>`, and a sheet's frame-key namespace ends `/preroll=<n>`, so a
+warm sheet and one from rest loaded into one texture cache do not share keys. The
+framing reads it, for `--environment`'s reason: a spring warmed swings otherwise
+than one released, and the box holds what the frames draw — so the grid can differ
+from the render from rest; compare the two in world units, in `geometry.json`.
+Without the flag every walk holds at its duration as it always did, spine-core's
+track is set not looping, and every file is the bytes it always was (`PRE04`, and
+the gallery's render and emit bases, `RH05` and `EH06`). `check` poses its
+candidate from rest, so a frame set drawn after a pre-roll is refused as a
+reference by name rather than scored.
+
+**Refused by name**, exit 2, nothing written (`PRE05`):
+
+- a value that is not a whole number of 1 or more — `--preroll <v>: negative`,
+  `not a whole number of loops`, `not a number`, and `--preroll 0 walks no loop
+  before the one recorded, which is the render from rest — leave --preroll out
+  for it`;
+- a walk past what a step list holds — `"<set>" would walk <N> steps at <fps> fps,
+  more than a walk's step list holds (4294967295)`;
+- a pre-roll this rig would not walk: a skeleton with no animation; one that
+  declares no physics constraint (`nothing carries from one loop into the next`);
+  a set of 0 frames at the rate (`"<set>" lasts <d>s, which is 0 frames at <fps>
+  fps`);
+- `--environment` beside it: a schedule's `t` could be read from the first frame
+  recorded or from the first loop walked, the two put the physics in different
+  worlds while it warms, and nothing settles which; and `--parallax`, whose dial
+  samples are independent reset poses.
+
+**Why loops and not a start in seconds.** A whole number of loops lands recorded
+frame `i` on the animation time the render from rest draws it at, so the two renders
+compare frame for frame and only the physics differs. A start in seconds would
+need a second rule for where the recorded window falls on the frame grid, and
+could put it mid-loop. The mesh comparison's `warmupSteps` (MESH_REDUCTION, P10),
+still refused above 0, would reach the same looping walk; counted in steps rather
+than loops, it would move every compared frame off its `FrameRef` time unless the
+steps were whole loops.
+
 ## 9. Checking against the frames — `rigc check`
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "3.1.0",
+  "version": "3.2.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/check.ts

@@ -1298,6 +1298,17 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
         'difference between two worlds. Render the reference frames without --environment.',
     );
   }
+  // 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;
+  if (referencePreroll !== undefined) {
+    throw new CheckError(
+      `${FRAMES_SIDECAR} records that these frames were rendered after a pre-roll (\`rigc render --preroll ${String(referencePreroll)}\`: ` +
+        'that many loops walked on a looping track before the loop recorded, the physics carried), and check poses the candidate ' +
+        'from rest — so the comparison would be a number about the difference between a warm loop and a cold one. ' +
+        'Render the reference frames without --preroll.',
+    );
+  }
   if (referenceSkin === null && options.skin !== undefined) {
     notes.push(
       `the candidate is posed under skin ${JSON.stringify(options.skin)} and the reference frames record no skin ` +

package/src/cli/core_commands.ts

@@ -47,7 +47,7 @@ import { buildSheetSet, SHEET_MANIFEST_FILE, type SheetSetPack, SheetUsageError,
 import { readSeamPairs, SEAM_FILE, seamFileOf, seamLine, SeamError, type SeamPair, seamsOf, seamText } from '../seam.ts';
 import { environmentCollisions, environmentFrame, EnvironmentError, environmentResponse, readEnvironmentSchedule, type EnvironmentStep } from '../environment.ts';
 import { estimatePose, poseLines, type PoseOptions } from '../pose.ts';
-import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, frameSetDir, type FrameSet, type FramesSidecar, framingViewport, GEOMETRY_FILE, geometryFileOf, geometryText, loadCandidate, POSER_NAMES, type PoserName, PROTOCOL_FPS, refuseUnchosen, renderFrame, sampleAll, sampleAnimation, sampleSetupPose, SETUP_POSE_DIR, SHEET_FILE, SHEET_TILE, sidecarViewport, type SkeletonFacts, type SlotSubset, SlotSubsetError, throughPoser, type Viewport, viewportFor } from '../render_shared.ts';
+import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, frameSetDir, type FrameSet, type FramesSidecar, framingViewport, GEOMETRY_FILE, geometryFileOf, geometryText, loadCandidate, POSER_NAMES, type PoserName, prerollStart, prerollWarmPoints, PROTOCOL_FPS, refuseUnchosen, renderFrame, sampleAll, sampleAnimation, sampleSetupPose, SETUP_POSE_DIR, SHEET_FILE, SHEET_TILE, sidecarViewport, type SkeletonFacts, type SlotSubset, SlotSubsetError, throughPoser, type Viewport, viewportFor } from '../render_shared.ts';
 import { type CompileResult } from '../types.ts';
 import { attachmentRegionJoins } from '../region_joins.ts';
 import { cmdRepack } from './repack.ts';
@@ -507,6 +507,69 @@ function readEnvironmentFlag(flags: Record<string, string>): { path: string; ste
   }
 }
 
+/**
+ * `--preroll <n>` read (issue #1684): how many whole loops of each animation the
+ * render walks on a looping track before the loop it records — or refused as a
+ * usage error, naming the value found and what is required, before anything is
+ * read off the candidate. `undefined` without the flag, which is the render from
+ * rest it always was.
+ *
+ * ⭐ A count of loops rather than a start in seconds: a whole number of loops
+ * puts the recorded frame `i` at the loop time the render without the flag draws
+ * it at (to the running sum's rounding), so the two renders compare frame for
+ * frame and only the physics differs — a start in seconds would need a second
+ * rule for where the window falls on the frame grid, and could land mid-loop.
+ */
+function readPrerollFlag(flags: Record<string, string>): number | undefined {
+  const given = flags.preroll;
+  if (given === undefined) return undefined;
+  const wants = 'it takes how many whole loops of each animation to walk, on a looping track, before the loop it records — 1 or more';
+  const value = given.trim() === '' ? Number.NaN : Number(given);
+  if (!Number.isFinite(value)) throw new UsageError(`--preroll ${JSON.stringify(given)}: not a number — ${wants}`);
+  if (value < 0) throw new UsageError(`--preroll ${given}: negative — ${wants}`);
+  if (!Number.isInteger(value)) throw new UsageError(`--preroll ${given}: not a whole number of loops — ${wants}`);
+  if (value === 0) throw new UsageError(`--preroll 0 walks no loop before the one recorded, which is the render from rest — leave --preroll out for it; ${wants}`);
+  return value;
+}
+
+/** The most steps a walk's step list holds: the longest array the language makes (`2^32 − 1`). */
+const WALK_STEPS_HELD = 2 ** 32 - 1;
+
+/**
+ * The refusal of a pre-roll this candidate, at this rate, would not walk (issue
+ * #1684), each a frame set from rest printed under a flag that says it is warm,
+ * or a walk that could not be taken:
+ *
+ * - a skeleton with no animation, whose one frame is the setup pose;
+ * - a skeleton that declares no physics constraint, where nothing carries from
+ *   one loop into the next;
+ * - a set drawn that spans no frame at `fps`, whose loop takes no step;
+ * - a walk longer than a step list holds (`WALK_STEPS_HELD`), which would
+ *   otherwise die on the array's own error rather than on a name.
+ *
+ * `durations` are the poser's, of the sets this run draws; `physics` the
+ * physics constraints the skeleton declares.
+ */
+function prerollRefusal(preroll: number, fps: number, durations: ReadonlyArray<{ name: string; duration: number }>, physics: readonly string[]): string | null {
+  if (durations.length === 0) return `--preroll ${preroll}: the skeleton has no animation — its one frame is the setup pose, where nothing loops and no physics step runs`;
+  if (physics.length === 0) {
+    return `--preroll ${preroll}: the skeleton declares no physics constraint, so nothing carries from one loop into the next and the loop recorded would be the render from rest`;
+  }
+  const still = durations.find(({ duration }) => Math.round(duration * fps) === 0);
+  if (still !== undefined) {
+    return (
+      `--preroll ${preroll}: "${still.name}" lasts ${still.duration}s, which is 0 frames at ${fps} fps — a loop of it walks no step, so no pre-roll ` +
+      'moves its physics. Name another set with --animation, or raise --fps'
+    );
+  }
+  for (const { name, duration } of durations) {
+    // `prerollTimes`' own length, counted rather than built: the grid before the wrap, the step onto it, and the loop recorded.
+    const steps = prerollWarmPoints(prerollStart(duration, preroll), fps) + Math.round(duration * fps);
+    if (steps > WALK_STEPS_HELD) return `--preroll ${preroll}: "${name}" would walk ${steps} steps at ${fps} fps, more than a walk's step list holds (${WALK_STEPS_HELD})`;
+  }
+  return null;
+}
+
 /**
  * The refusals of a well-formed schedule that this candidate, at this rate,
  * would quietly not draw (issue #1416) — each one a render that would print a
@@ -657,6 +720,15 @@ export function cmdRender(flags: Record<string, string>): void {
   const fps = readPositiveNumber(flags, 'fps', PROTOCOL_FPS, 1);
   // Read before anything is read off the candidate, so a malformed schedule is refused before a line is printed.
   const environment = readEnvironmentFlag(flags);
+  // 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 (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, ` +
+        'and the two put the physics in different worlds while it warms. Render with one of them',
+    );
+  }
   const maxSide = readPositiveNumber(flags, 'max', 256, 16);
   // A box given rather than fitted (issue #1414), read before a line is printed, so a malformed one is refused first.
   const given = readGivenViewport(flags);
@@ -778,7 +850,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', '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', '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');
@@ -824,15 +896,22 @@ export function cmdRender(flags: Record<string, string>): void {
   // the frames draw the subset and the box is still the whole rig's.
   // The environment rides on the same object for the same reason (issue #1416): the framing reads it, so the box holds
   // 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
+    skin === undefined && subset === undefined && environment === undefined && preroll === undefined
       ? undefined
-      : { ...(skin === undefined ? {} : { skin }), ...subsetFields(subset), ...(environment === undefined ? {} : { environment: environment.steps }) };
+      : {
+          ...(skin === undefined ? {} : { skin }),
+          ...subsetFields(subset),
+          ...(environment === undefined ? {} : { environment: environment.steps }),
+          ...(preroll === undefined ? {} : { preroll }),
+        };
   if (skin !== undefined) console.log(`  ..    skin     ${skin}`);
   if (subset !== undefined) console.log(`  ..    ${subset.mode.padEnd(8)} ${subset.names.join(', ')}`);
   if (environment !== undefined && facts.animations.length === 0) {
     throw new UsageError(environmentRefusal(flags.environment, environment.steps, skeletonText, fps, []) ?? '');
   }
+  if (preroll !== undefined && facts.animations.length === 0) throw new UsageError(prerollRefusal(preroll, fps, [], physicsDeclared) ?? '');
 
   // Rigc's own core when the candidate is a rigc build, and spine-core
   // otherwise, or where the core refuses the input by name. Never silently:
@@ -853,6 +932,11 @@ export function cmdRender(flags: Record<string, string>): void {
       const refusal = environmentRefusal(flags.environment, environment.steps, skeletonText, fps, drawn);
       if (refusal !== null) throw new UsageError(refusal);
     }
+    // A pre-roll this candidate would not walk is refused off the same durations, for the same reason (issue #1684).
+    if (preroll !== undefined) {
+      const refusal = prerollRefusal(preroll, fps, poser.animations.filter((a) => only === undefined || a.name === only), physicsDeclared);
+      if (refusal !== null) throw new UsageError(refusal);
+    }
     // `null` is a skeleton that posed no vertex at all. One that posed a vertex
     // it cannot frame — Infinity or NaN — is thrown from the framing as a
     // `GeometryError` naming the number (issue #873), and one whose every vertex
@@ -935,7 +1019,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)));
+        geometryTexts.set(name, geometryText(geometryFileOf(poser, animation, fps, frames, viewport, skin, environment?.steps, preroll)));
       }
     }
     // The fold reading, off the very attachments the frames were drawn from, against the rest table the geometry
@@ -1066,6 +1150,7 @@ export function cmdRender(flags: Record<string, string>): void {
               skin,
               subset,
               environment: environment?.steps,
+              preroll,
               pinned,
             }),
           );
@@ -1086,6 +1171,12 @@ export function cmdRender(flags: Record<string, string>): void {
         `wind answered by ${response.wind.join(', ') || 'none'}; gravity by ${response.gravity.join(', ') || 'none'}`,
     );
   }
+  if (preroll !== undefined) {
+    console.log(
+      `  ..    preroll  ${preroll} loop(s) of each set walked 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',
+    );
+  }
   console.log(`  ..    ${viewport.width}x${viewport.height}px at ${fps} fps, ${sampled.size} set(s) -> ${outRoot}`);
   // Whether physics ran (issue #1467): said once for a rig with nothing to step, and per set below for one with.
   if (physicsDeclared.length === 0) console.log(`  ..    ${PHYSICS_NONE_LINE}`);
@@ -1237,6 +1328,8 @@ export function cmdRender(flags: Record<string, string>): void {
     ...subsetFields(subset),
     // Written only when a schedule was given (issue #1416): a render without one says nothing and stays the bytes it was.
     ...(environment === undefined ? {} : { environment: environment.steps }),
+    // Written only when a pre-roll was asked for (issue #1684), for the same reason.
+    ...(preroll === undefined ? {} : { preroll }),
     // 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,

package/src/cli/shared.ts

@@ -1071,7 +1071,7 @@ const FLAG_MEANINGS: Record<string, string> = {
     'Each frame with a moving pair also gets an outline plate, overlaps-f<NNNN>.png: every slot in a moving pair as its contour in its own ' +
     'colour, dashed where a slot drawn later covers it, named at its top. The render reports what was drawn; who should be in front is the ' +
     "author's, and the draw-order key in the motion spec is the remedy. A reading, not a gate. Not with --slot/--hide",
-  parallax: 'read one named slider dial through the core poser on 9 evenly spaced values: parallax.json plus setup/extreme/diff/affine-residual heat-map parallax.png; geometry only, no assertion or pass threshold. A separate dial render mode; takes no animation, fps, other diagnostics, sheet, subset, environment or viewport flags',
+  parallax: 'read one named slider dial through the core poser on 9 evenly spaced values: parallax.json plus setup/extreme/diff/affine-residual heat-map parallax.png; geometry only, no assertion or pass threshold. A separate dial render mode; takes no animation, fps, other diagnostics, sheet, subset, environment, preroll or viewport flags',
   'extremes-only': 'write only extremes.json and readable extremes.png per set, with the same posed grid and bytes as --extremes; no ordinary frame PNGs, contact.png or frames.json. Implies --extremes; takes no --sheet, --sheet-format, --page-edges, --geometry, --folds, --pass-through, --seam, --overlaps or --angle-range',
   extremes: 'also write extremes.json and a native six-panel extremes.png per set: setup, geometry-pair min/max and premultiplied RGBA diffs, with a legend. Per-channel extrema are recorded separately and valid channels survive geometry/image SKIPs; channel refusals are named separately. Still geometry reports SKIP; a reading, not a gate. Attachment identity/count changes record a named SKIP without changing render exit; supports --slot/--hide on both posers',
   seam:
@@ -1108,6 +1108,13 @@ 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',
+  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 ' +
+    'pose at track time (n·count + i)/fps, filed under index i and time i/fps; on either poser. frames.json, geometry.json and ' +
+    'sheet-manifest.json record it, 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, and --environment or --parallax beside it ' +
+    'are refused by name; check refuses such a frame set as a reference',
   poser:
     "`render`, `inspect` and `check`: which implementation poses the frames (on `check`, the candidate's) — `core` (rigc's own, reading the skeleton.model.json a " +
     'build writes beside the pair) or `spine` (spine-core). Default: `core` when that document and the atlas sit ' +
@@ -1300,6 +1307,7 @@ const FLAG_VALUES: Record<string, string> = {
   'texture-from': '<path>',
   poser: 'core|spine',
   environment: '<schedule.json>',
+  preroll: '<n>',
   'pass-through': '<cloth>:<leg>[,<cloth>:<leg>…]',
   seam: '<slot>:<slot>[,<slot>:<slot>…]',
   'angle-range': '<bone>:<relative-to>[,…]',
@@ -1768,6 +1776,7 @@ export const COMMANDS: CommandDoc[] = [
       'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--geometry] [--folds] [--extremes | --extremes-only] [--poser core|spine] [--out render/]',
       'rigc render … --slot <name[,name…]> | --hide <name[,name…]>   (a subset of the slots, on the whole rig\'s grid)',
       'rigc render … --environment <schedule.json>   (the wind and gravity the physics answers, in time)',
+      'rigc render … --preroll <n>   (n whole loops walked on a looping track first, so the loop recorded has its physics warm)',
       'rigc render … --pass-through <cloth>:<leg>[,…]   (the frames where a cloth drawn over a leg passes through it)',
       'rigc render … --seam <slot>:<slot>[,…]   (joint gaps, visible ghosts and each named slot’s background exposure)',
       'rigc render … --parallax <dial>   (geometry reading on the named dial, model/core only)',
@@ -1776,7 +1785,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', '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', 'poser', 'out'],
     overrides: {
       'page-edges': {
         meaning:

package/src/core/raw.ts

@@ -620,6 +620,26 @@ export function poseRawAnimationEach(doc: CompiledDocument, animation: string, s
   walkEach(doc, animation, steps, plant, reset, clock === undefined ? RAW_MODE : { ...RAW_MODE, clock: (dt) => clock(dt) }, RAW_SHAPE, visit, environment);
 }
 
+/**
+ * The live track's looping mode (`./track.ts`, issue #1276) as a batch walk's:
+ * the animation time the track time wrapped by the duration, `reset` keys
+ * fired across the wrap, the clipped rows cut as the raw entry cuts them, and
+ * no value that is not finite kept.
+ */
+const RAW_LOOPED_MODE: WalkMode = { loop: true, keep: false, live: true };
+
+/**
+ * `poseRawAnimationEach` on a looping track (issue #1684): the same walk in the
+ * live track's looping mode (`RAW_LOOPED_MODE`) — the walk `render --preroll`
+ * takes, which carries the physics across every wrap as a player's looping
+ * track does. Not part of the entry's promised surface: `src/render_core.ts`
+ * is its one caller, and spine-core's poser takes the same walk through
+ * `setAnimation(0, name, true)`.
+ */
+export function poseRawLoopEach(doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant, reset: RawReset, visit: (pose: RawPose, index: number) => void, clock?: (dt: number) => number, environment?: StepEnvironment): void {
+  walkEach(doc, animation, steps, plant, reset, clock === undefined ? RAW_LOOPED_MODE : { ...RAW_LOOPED_MODE, clock: (dt) => clock(dt) }, RAW_SHAPE, visit, environment);
+}
+
 /**
  * What a batch walk sets on its physics before a pose (issue #1416, part C):
  * pose `index`'s change to the world every physics constraint answers — either

package/src/render.ts

@@ -503,12 +503,14 @@ export function spinePoser(data: SkeletonData): Poser {
     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) => {
+    animation: (name, skin, fps, count, visit, environment, _channels, times, loop) => {
       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
-      // entry would wrap it back onto the first pose.
-      state.setAnimation(0, name, false);
+      // entry would wrap it back onto the first pose. Looping only when asked (issue
+      // #1684, `render --preroll`): the walk a player's looping track takes, the
+      // physics carried across every wrap — the core walks it as `poseRawLoopEach`.
+      state.setAnimation(0, name, loop === true);
       skeleton.setupPose();
       const step = 1 / fps;
       // The physics clock runs `PHYSICS_CLOCK_LEAD` fast, so no frame ends on a physics step's tie (issue #1380).

package/src/render_core.ts

@@ -18,7 +18,7 @@ import type { ChannelValue } from './render_shared.ts';
  * with the runtime it replaces — and "the core poser imports nothing from
  * spine-core" could then only be said, not read off the file. Here it can be:
  * the value imports below are the core, the atlas reader and nothing else, and
- * the one thing taken from `render.ts` is its types (erased at run time). The
+ * the renderer's types come from `render_shared.ts` (nothing from `render.ts`). The
  * modules that link spine-core stay three (`CUR07`).
  *
  * ## What each part of a pose is read from
@@ -98,12 +98,12 @@ import type {
   Poser,
   SkinRoster,
   SlotSubset,
-} from './render.ts';
+} from './render_shared.ts';
 import { atlasRegionLookup, parseAtlasText } from './atlas.ts';
 import { pagesOfAtlas, spineFileSha256, type ModelPage } from './model.ts';
 import { clipThrough, type ClipShape, type ShapeClipper } from './core/clipping.ts';
 import { activeBones, CoreInputError, readModel, sourceOfDoc, underNoSkin, underSkin, type CompiledDocument, type CoreSlotRow } from './core/index.ts';
-import { PHYSICS_CLOCK_LEAD, physicsClockStep, poseRawAnimationEach, poseRawDial, poseRawSetup, type RawDrawn, type RawPose, type StepEnvironment } from './core/raw.ts';
+import { PHYSICS_CLOCK_LEAD, physicsClockStep, poseRawAnimationEach, poseRawDial, poseRawLoopEach, poseRawSetup, type RawDrawn, type RawPose, type StepEnvironment } from './core/raw.ts';
 import type { TimelinePlant } from './core/animation.ts';
 import { stepPhysics, type PhysicsStepper } from './core/constraints_physics.ts';
 import { CORE_DEFAULT_SKIN, lookupSkins } from './core/skins.ts';
@@ -367,14 +367,18 @@ 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) => void;
+export type CoreRawWalk = (doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant, visit: (pose: RawPose, index: number) => void, environment?: StepEnvironment, loop?: boolean) => 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`).
+ * 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.
  */
-export const CORE_RAW_WALK: CoreRawWalk = (doc, animation, steps, plant, visit, environment) => poseRawAnimationEach(doc, animation, steps, plant, 'animation', visit, physicsClockStep, environment);
+export const CORE_RAW_WALK: CoreRawWalk = (doc, animation, steps, plant, visit, environment, loop) =>
+  loop === true
+    ? poseRawLoopEach(doc, animation, steps, plant, 'animation', visit, physicsClockStep, environment)
+    : poseRawAnimationEach(doc, animation, steps, plant, 'animation', visit, physicsClockStep, environment);
 
 /**
  * The render's physics clock (issue #1380): defined beside the walk that takes it (`./core/raw.ts`), where the mesh
@@ -790,7 +794,7 @@ export function corePoser(
       const pose = poseRawSetup(input.doc, { through, ...observe });
       return corePosed(input, pose, through, [], values);
     },
-    animation: (name, skin, fps, count, visit, environment, channels, times) => {
+    animation: (name, skin, fps, count, visit, environment, channels, times, loop) => {
       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);
@@ -819,7 +823,7 @@ export function corePoser(
         } catch (thrown) {
           drawFailed.push(thrown);
         }
-      }, environment);
+      }, environment, loop);
       if (drawFailed.length > 0) throw drawFailed[0];
     },
     rest: (skin, shown) => {

package/src/render_shared.ts

@@ -283,6 +283,16 @@ export interface FramesSidecar {
    * it as a reference by name.
    */
   environment?: EnvironmentStep[];
+  /**
+   * The whole loops each set walked on a looping track before the loop its
+   * frames record, when `render --preroll` gave them (issue #1684).
+   *
+   * ⭐ Absent on a render without it, for `skin`'s reason: every frame set
+   * written before the field existed is a render from rest, and says the same.
+   * A frame set carrying it shows the physics warm, which `check` does not
+   * pose, so `check` refuses it as a reference by name.
+   */
+  preroll?: number;
   /**
    * The box was given rather than fitted, when `render --viewport` or
    * `render --viewport-from` gave it (issue #1414): which flag, and every slot
@@ -501,6 +511,23 @@ export interface PoseOptions {
   environment?: readonly EnvironmentStep[];
   /** Also record the physics constraints the step that posed each frame stepped — see `Frame.physics` (issue #1467). */
   physics?: boolean;
+  /**
+   * Whole loops walked before the loop recorded — `render --preroll` (issue
+   * #1684): the track set looping, walked and drawn by no frame up to track
+   * time `preroll · duration` (`prerollTimes`), then the `count + 1` frames of
+   * the next loop, frame `i` the pose at track time `preroll · duration + i /
+   * fps` — animation time `i / fps` — filed under index `i` and time `i / fps`.
+   * The physics is carried across every wrap, as
+   * a player's looping track carries it, so a spring that converges is warm
+   * on the first frame recorded. Absent, the track holds at its duration and
+   * every pose is the one it always was. A whole number at or above 1; not
+   * with `environment`, whose clock under a pre-roll nothing settles.
+   *
+   * ⭐ **It is part of the shot, so the framing reads it**, for `environment`'s
+   * reason: a spring warmed from rest swings differently from one released
+   * from it, and the box holds what the frames draw.
+   */
+  preroll?: number;
 }
 
 /**
@@ -1165,9 +1192,14 @@ export interface Poser {
    * answers set before the step that poses frame `i` (issue #1416).
    * Optional `times` replaces the uniform grid with increasing absolute times
    * starting at 0 (count = times.length - 1), stepped by adjacent differences.
-   * Used by texture-scale to include key times; ordinary renders are unchanged.
+   * Used by texture-scale to include key times, and by a pre-roll to land on
+   * the wrap (`prerollTimes`); ordinary renders are unchanged.
+   * `loop` (issue #1684, `render --preroll`) sets the track looping — the
+   * 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.
    */
-  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[]): 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): void;
   /** The rest table for the (slot, attachment) pairs `shown` holds — see `AttachmentRest`. */
   rest(skin: string | undefined, shown: readonly AttachmentPose[][]): AttachmentRest[];
 }
@@ -1242,6 +1274,19 @@ export function sampleAnimation(source: PoseSource, name: string, fps: number, o
   const count = Math.round(animation.duration * fps);
   const draw = drawResolver(poser, opts);
   const frames: Frame[] = [];
+  const preroll = opts?.preroll;
+  if (preroll !== undefined) {
+    // Refused by name at the CLI first (`readPrerollFlag`); here so no other caller walks a pre-roll nobody defined.
+    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 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);
+    return frames;
+  }
   const visit = (i: number, posed: Posed): void => {
     frames.push(frameOf(i, i * step, posed, draw(), opts));
   };
@@ -1252,6 +1297,72 @@ export function sampleAnimation(source: PoseSource, name: string, fps: number, o
   return frames;
 }
 
+/**
+ * The track time `render --preroll`'s loop recorded starts at (issue #1684): the
+ * end of `preroll` whole loops, `preroll · duration` — where the track has
+ * wrapped `preroll` times and the animation time is 0.
+ *
+ * ⚠️ The product is a float only when `preroll · duration` fits one; where it
+ * does not, it rounds to the nearer float, and that can sit just short of the
+ * wrap — at `duration · 3` for a duration of 1.03, measured — where the
+ * animation time is the duration less an ulp: the pose at the loop's end, not
+ * its start. So a product that lands short is moved to the next float above
+ * it, past the wrap, where the animation time is under one ulp of the product
+ * past 0. No float lies on the wrap there, and this is the one past it.
+ */
+export function prerollStart(duration: number, preroll: number): number {
+  let start = preroll * duration;
+  while (duration > 0 && start % duration > duration / 2) start = nextFloatAbove(start);
+  return start;
+}
+
+/** The float just above a positive finite `x`. */
+function nextFloatAbove(x: number): number {
+  const box = new Float64Array([x]);
+  const bits = new BigUint64Array(box.buffer);
+  bits[0] += 1n;
+  return box[0];
+}
+
+/**
+ * How many points of the render's grid, `j / fps` from `j = 0`, lie strictly
+ * before track time `start` — the steps a pre-roll walks before the one that
+ * lands on `start` (`prerollTimes`).
+ */
+export function prerollWarmPoints(start: number, fps: number): number {
+  if (!(start > 0)) return 0;
+  let m = Math.max(0, Math.ceil(start * fps) - 1);
+  while ((m + 1) / fps < start) m++;
+  while (m > 0 && m / fps >= start) m--;
+  return m + 1;
+}
+
+/**
+ * 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 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
+ * steps to, by induction, and the last is `start`. A uniform grid of
+ * `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 } {
+  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 };
+}
+
 /**
  * The setup pose as a single frame — what a skeleton with **no animation at all**
  * looks like.
@@ -1570,6 +1681,8 @@ export interface GeometryFile {
   skin?: string;
   /** The schedule the physics answered (`render --environment`, issue #1416) — `frames.json`'s own `environment`; absent without it. */
   environment?: EnvironmentStep[];
+  /** The whole loops walked before the loop these frames record (`render --preroll`, issue #1684) — `frames.json`'s own `preroll`; absent without it. */
+  preroll?: number;
   fps: number;
   /** The box the PNG frames beside this file were drawn over — `frames.json`'s own `viewport`. */
   viewport: FramesSidecar['viewport'];
@@ -1630,6 +1743,7 @@ export function geometryFileOf(
   viewport: Viewport,
   skin: string | undefined,
   environment?: EnvironmentStep[],
+  preroll?: number,
 ): GeometryFile {
   const geometryFrame = (frame: Frame, where: string): Omit<GeometryFrame, 'index' | 'time'> => {
     if (frame.bones === undefined || frame.attachments === undefined) {
@@ -1654,6 +1768,7 @@ export function geometryFileOf(
     animation,
     ...(skin === undefined ? {} : { skin }),
     ...(environment === undefined ? {} : { environment }),
+    ...(preroll === undefined ? {} : { preroll }),
     fps,
     viewport: sidecarViewport(viewport),
     bones: poser.bones.map(({ name, parent }) => ({ name, parent })),

package/src/sheet.ts

@@ -118,6 +118,8 @@ export interface SheetManifest {
   slots?: string[];
   hidden?: string[];
   environment?: EnvironmentStep[];
+  /** The whole loops walked before the loop these frames record (`render --preroll`, issue #1684); absent without it. */
+  preroll?: number;
   pinned?: PinnedViewport;
   fps: number;
   duration: number;
@@ -182,6 +184,7 @@ export interface BuildSheetSetOptions {
   skin?: string;
   subset?: SlotSubset;
   environment?: EnvironmentStep[];
+  preroll?: number;
   pinned?: PinnedViewport;
   /** For negative-control testing in `selftest.ts` only: reverse the input order handed to `packAtlas`. */
   reversePackInputs?: boolean;
@@ -262,9 +265,9 @@ function sanitizeNamespaceSegment(segment: string): string {
 
 /**
  * Build the collision-free frame-key namespace `<rig>/<anim>[/<variant>]` for a
- * rendered set. Non-default skin, slot subset, or environment schedule are
- * encoded in `<variant>` in fixed order so multiple exports loaded into a shared
- * texture cache cannot collide on frame keys.
+ * rendered set. Non-default skin, slot subset, environment schedule or pre-roll
+ * are encoded in `<variant>` in fixed order so multiple exports loaded into a
+ * shared texture cache cannot collide on frame keys.
  */
 export function sheetNamespaceOf(opts: {
   rigName: string;
@@ -272,6 +275,7 @@ export function sheetNamespaceOf(opts: {
   skin?: string;
   subset?: SlotSubset;
   environment?: EnvironmentStep[];
+  preroll?: number;
 }): string {
   const rig = sanitizeNamespaceSegment(opts.rigName);
   const anim = sanitizeNamespaceSegment(opts.setName);
@@ -282,6 +286,7 @@ export function sheetNamespaceOf(opts: {
     const digest = createHash('sha256').update(JSON.stringify(opts.environment)).digest('hex').slice(0, 8);
     variants.push(`env=${digest}`);
   }
+  if (opts.preroll !== undefined) variants.push(`preroll=${opts.preroll}`);
   return variants.length === 0 ? `${rig}/${anim}` : `${rig}/${anim}/${variants.join('+')}`;
 }
 
@@ -715,6 +720,7 @@ export function buildSheetSet(opts: BuildSheetSetOptions): SheetSetPack {
     skin: opts.skin,
     subset: opts.subset,
     environment: opts.environment,
+    preroll: opts.preroll,
   });
 
   const padding = SHEET_PADDING;
@@ -868,6 +874,7 @@ export function buildSheetSet(opts: BuildSheetSetOptions): SheetSetPack {
         ? { slots: [...opts.subset.names] }
         : { hidden: [...opts.subset.names] }),
     ...(opts.environment === undefined ? {} : { environment: opts.environment }),
+    ...(opts.preroll === undefined ? {} : { preroll: opts.preroll }),
     ...(opts.pinned === undefined ? {} : { pinned: opts.pinned }),
     fps: opts.fps,
     duration,