@rig-c/core 2.60.0 → 2.61.1

package/README.md

@@ -433,7 +433,10 @@ frames. It draws with rigc's own rasteriser (the one `check` measures with), so
 it needs no browser and no network, and the `frames.json` it leaves beside the
 directories makes the result a frame set like any other — the world box every
 frame is a picture of. `--animation <name>` narrows it to one, `--fps` and
-`--max` change the rate and the frame size.
+`--max` change the rate and the frame size. A set drawn at any rate but the
+default is written to `<anim>@<fps>fps/` rather than `<anim>/`, so two rates sit
+side by side: `--fps 24` writes `<anim>@24fps/`, and the default 12 writes
+`<anim>/`. Each set's summary line ends with the directory it wrote.
 
 > 🚨 **`--skin <name>` if your rig has more than one.** With no `--skin` no skin
 > is set at all, so every slot resolves through the **default** skin alone — and
@@ -603,7 +606,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 |
 | `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)) |
 | `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 |
-| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`. `--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 — a reading, not a gate; the exit status never moves. `--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 |
+| `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 — a reading, not a gate; the exit status never moves. `--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 |
 | `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` |
 | `vote --candidate a --candidate b` | one `.html` that asks a human which; `vote --record <file>` checks the answer into `votes.jsonl` |
 | `pose --images <dir> --frame <png>` | reads part placements **out of** a picture |
@@ -614,7 +617,7 @@ commands take it and what its default is.
 | `bench <rung> --candidate <dir>` | one rung of the benchmark ladder |
 | `guide <RULE>` / `guide §<n>[.<m>[.<k>]] [--all]` | the guide's row for the rule a failure line names — every `FAIL` line, `vote --record` refusal, `ingest` finding and coded compile error ends with ` (see rigc guide <RULE>)`; only legacy uncoded library errors point at `§5.1` — or a section's heading, own prose and subsection index, read from the installed `docs/AUTHORING.md` when it runs. `--all` includes the subsection bodies; a leaf prints its full text either way. Sizes describe full ledger spans. `--all` with a rule is refused, exit 2; an unknown name is refused with the nearest real ones, exit 1 |
 | `skills install [--dir …] [--copy]` | links every agent skill the package ships into `.agents/skills` (or `--dir`) as relative symlinks, or copies them with `--copy` — where Codex, Gemini CLI and Antigravity look. A second run has nothing to do; an entry already there that is not this command's is refused by name and nothing is written |
-| `review <dir> […]` | the human review of a build, handed to the `rig-review` bin of `@rig-c/review` installed beside the package, with every argument untouched and its exit code returned: `rigc review open <dir>` prints a loopback URL to give a person, `check <dir>` validates the folder it would serve, `feedback <dir>` prints what they left, and `rigc review --help` is review's own usage. rigc does not depend on it: without it the command prints `rigc review: @rig-c/review is not installed — npm i -D @rig-c/review` and exits 2 |
+| `review <dir> […]` | the human review of a build, handed to the `rig-review` bin of `@rig-c/review` installed beside the package, with every argument untouched and its exit code returned: `rigc review open <dir>` prints a loopback URL to give a person, `check <dir>` validates the folder it would serve, `feedback <dir>` prints what they left, and `rigc review --help` is review's own usage. rigc does not depend on it: without it the command prints `rigc review: @rig-c/review is not installed — npm i -D @rig-c/review` and exits 2. An empty argument (`""`) is handed over only where the running Bun keeps one when it starts a process — Bun 1.2.0 drops it, measured by a probe rather than by version — and is otherwise refused by name, `rigc review: argument N is empty, and Bun <version>, the Bun running this, drops an empty argument when it starts a process — …`, exit 2 |
 
 `diff`, `bonedist`, `check` and `bench` measure against something you were given; the
 first three work on any reference you have, and `bench` is a repository workflow that needs a clone

package/docs/AUTHORING.md

@@ -1242,7 +1242,11 @@ bun cli.ts pose     --images path/to/parts --frame poseA.png [--out pose.json]
   gate can know you did not mean them. `render` writes
   `render/<animation>/f0000.png…` with a `contact.png` grid of **every** frame
   beside them (open that one first — spacing is a comparison across frames) and a
-  `frames.json` sidecar naming the world box they are pictures of. `contact.png`
+  `frames.json` sidecar naming the world box they are pictures of. It also says
+  whether the physics ran: under each set's line, `physics: N constraint(s)
+  stepped at <fps> fps`, and the same two figures on that set in `frames.json` —
+  or, once, `physics: none in this rig` for a rig that declares no physics
+  constraint (§8.4). `contact.png`
   is for spacing across frames; a defect is read on **one frame at full size**,
   because a tile is too small to say which part a pixel belongs to. When a frame
   looks wrong, render it again with `--hide <slot>` — the **largest attachment**
@@ -6843,6 +6847,14 @@ it had nothing to step (`nanStepping=skipped`). What it does not see is a skin o
 than the default, which A10 does not pose. The sentence, and where to look for the
 number, is under *nothing to draw* in §3.4.
 
+⌨️ **An invocation missing a flag is one line, before any of these.** `build`,
+`explain` and `validate` given a cut spelled out with `--rig`, `--motion` or
+`--out` absent print `rigc: <command> needs --<flag> <value> (or --cut <name>
+--cuts <cuts.json>)` on stderr and exit 2 — the line alone, with no command
+catalogue under it. An input flag that names a **directory** is a compile error
+with a remedy in it: `CE_COMPILE_JSON_READ_FAILED` says what the flag wants and
+names the one file there that reads as it (§5.1.2). It is never read as that file.
+
 ### 5.1 Compile errors — before the gate
 
 A `CompileError` names the object and the field, and nothing is written. Its line
@@ -6919,7 +6931,7 @@ retain the minimal inputs and report that code rather than inventing author data
 | <a id="CE_COMPILE_RGBA_CHANNEL_COUNT"></a>`CE_COMPILE_RGBA_CHANNEL_COUNT` | “rgba value needs 4 channels, got &lt;value&gt;” | Supply four rgba channels. |
 | <a id="CE_COMPILE_RGBA2_CHANNEL_COUNT"></a>`CE_COMPILE_RGBA2_CHANNEL_COUNT` | “rgba2 value needs 7 channels, got &lt;value&gt;” | Supply seven rgba2 channels. |
 | <a id="CE_COMPILE_COLOUR_CHANNEL_COUNT"></a>`CE_COMPILE_COLOUR_CHANNEL_COUNT` | “&lt;value&gt; value needs &lt;value&gt; channel[ / s], got &lt;value&gt;” | Supply the channel count named for this colour shape. |
-| <a id="CE_COMPILE_JSON_READ_FAILED"></a>`CE_COMPILE_JSON_READ_FAILED` | “cannot read &lt;value&gt;: &lt;value&gt;”<br>Also: “&lt;value&gt; (line &lt;value&gt;, column &lt;value&gt;)” | Fix the named JSON file's path, permissions or JSON syntax. |
+| <a id="CE_COMPILE_JSON_READ_FAILED"></a>`CE_COMPILE_JSON_READ_FAILED` | “cannot read &lt;value&gt;: &lt;value&gt;”<br>Also: “&lt;value&gt; (line &lt;value&gt;, column &lt;value&gt;)”<br>Also, when `--rig`, `--motion` or `--manifest` names a directory: “&lt;value&gt; names a directory; it wants &lt;value&gt; — &lt;value&gt; exists there” · “… — &lt;value&gt; holds no .json file” · “… — &lt;value&gt; holds &lt;value&gt; .json file(s) and none reads as one: &lt;value&gt;” · “… — &lt;value&gt; .json files in &lt;value&gt; read as one, so name it: &lt;value&gt;”, a list cut at eight names with “, … &lt;value&gt; in all” | Fix the named JSON file's path, permissions or JSON syntax. For a directory, name the file the line names — the one `.json` there that reads as that input (a rig spec through the rig spec's parser, a motion spec through the motion spec's; for `--manifest`, any `.json`) — or pick one of the files it lists. A directory is never read as its file: rigc compiles what it was given. |
 | <a id="CE_COMPILE_IMAGE_MISSING"></a>`CE_COMPILE_IMAGE_MISSING` | “image "&lt;value&gt;" is not on disk at &lt;value&gt;”<br>Also: “&lt;value&gt;.png” | Supply the PNG at the named images path or correct the image name. |
 | <a id="CE_COMPILE_IMAGE_PNG_INVALID"></a>`CE_COMPILE_IMAGE_PNG_INVALID` | “&lt;value&gt; is &lt;value&gt;, not a PNG: its first &lt;value&gt; byte(s) are &lt;value&gt;, where a PNG's first 8 are &lt;value&gt;&lt;value&gt;. rigc reads PNG and nothing else — its page-size and alpha readers, its renderer and its region lift all decode PNG, and it links no decoder for any other format — so nothing in this file was measured. Re-export it as PNG”<br>“&lt;value&gt; is a PNG whose IHDR chunk declares &lt;value&gt; byte(s) of data, where the format's is 13”<br>“&lt;value&gt; is a PNG whose IHDR chunk states its size as &lt;value&gt;x&lt;value&gt;: &lt;value&gt; 0, where the format requires each dimension to be at least 1, so the file describes no texel and nothing in it can be measured or drawn. Re-export it”<br>“&lt;value&gt; is a PNG whose first chunk is &lt;value&gt; rather than the IHDR the format requires first”<br>“&lt;value&gt; is a truncated PNG: it is &lt;value&gt; byte(s) long and &lt;value&gt;, so no reader can decode it. Re-export or re-copy the file whole”<br>“&lt;value&gt; is a truncated PNG: it is &lt;value&gt; byte(s) long and ends &lt;value&gt; byte(s) into the 8-byte PNG signature, so no reader can decode it. Re-export or re-copy the file whole”<br>“&lt;value&gt; is a truncated PNG: it is &lt;value&gt; byte(s) long and ends after the signature with no IEND chunk, so no reader can decode it. Re-export or re-copy the file whole”<br>“&lt;value&gt; is a truncated PNG: it is &lt;value&gt; byte(s) long and its &lt;value&gt; chunk at byte &lt;value&gt; declares &lt;value&gt; byte(s) of data, which with its CRC runs to byte &lt;value&gt;, so no reader can decode it. Re-export or re-copy the file whole”<br>“&lt;value&gt; is a truncated PNG: it is &lt;value&gt; byte(s) long and {ends after &lt;value&gt; with no IEND chunk / ends &lt;value&gt; byte(s) into the header of the chunk after &lt;value&gt;}, so no reader can decode it. Re-export or re-copy the file whole”<br>“&lt;value&gt; is empty (0 bytes), and a PNG's first 8 bytes are &lt;value&gt;”<br>“[; its name ends in .png, and it is the bytes that decide what a file is / ]”<br>“[its width and its height are / [its width is / its height is]]”<br>“a &lt;value&gt; image”<br>“a WebP image (a RIFF/WEBP container whose first chunk is &lt;value&gt;)”<br>“image "&lt;value&gt;": &lt;value&gt;”<br>“in no image format rigc recognises by its signature (it names &lt;value&gt; when it meets them)”<br>Here the values named in the message include: “KTX2”, “GIF”, “JPEG”. | Supply a readable PNG with the required header and dimensions at the named path. |
 | <a id="CE_COMPILE_ATLAS_INPUT_MISSING"></a>`CE_COMPILE_ATLAS_INPUT_MISSING` | “--atlas-in names &lt;value&gt;, which is not on disk” | Correct --atlas-in or supply the atlas file at that path. |
@@ -7370,7 +7382,7 @@ retain the minimal inputs and report that code rather than inventing author data
 | <a id="CE_STOP_LINK_UNDRIVEN"></a>`CE_STOP_LINK_UNDRIVEN` | “&lt;stop.who&gt;: links[&lt;k&gt;] "&lt;link&gt;" is written by no constraint of this rig spec — a stop holds a link something swings (a physics, ik, transform or path constraint in "constraints"), and its copy and clamp run right after that. A physics constraint in the motion spec's table is emitted after every rig constraint, past the clamp; declare it here” | Declare the swinging physics, ik, transform or path constraint in the rig spec's constraints before its stop clamp. |
 | <a id="CE_STOP_LINK_PARENT_CHAIN"></a>`CE_STOP_LINK_PARENT_CHAIN` | “&lt;stop.who&gt;: links[&lt;k&gt;] "&lt;links[k]&gt;" does not hang below "&lt;names.drawn[k - 1]&gt;", the drawn link of links[&lt;k - 1&gt;] — a chain's next link hangs from the drawn link above it, so the clamp that holds that one carries this one; parent it there” | Parent each lower link under the preceding generated drawn link. |
 | <a id="CE_STOP_AGAINST_MOVES_WITH_STOP"></a>`CE_STOP_AGAINST_MOVES_WITH_STOP` | “&lt;stop.who&gt;: "against" "&lt;stop.against&gt;" hangs below "&lt;under&gt;", which the stop moves — the point would swing with the chain it holds off; name the leg” | Name an against bone outside the subtree moved by the stop. |
-| <a id="CE_STOP_LOCAL_BOUND_RANGE"></a>`CE_STOP_LOCAL_BOUND_RANGE` | “&lt;stop.who&gt;: "&lt;field&gt;&lt;end&gt;" &lt;range[end]&gt; puts &lt;what&gt;'s bound at &lt;value&gt;°, past ±&lt;BOUND&gt;° — the clamp reads a local rotation in (-180, 180], so a bound past it is never reached and the range it states is not the one that holds”<br>On the first link it goes on: “. "&lt;stop.links[0]&gt;" hangs at &lt;at.hang&gt;° from its root at [&lt;at.root&gt;], and "&lt;stop.names.point&gt;" ("at" [&lt;stop.at&gt;] on "&lt;stop.against&gt;") sits at [&lt;at.point&gt;] — Spine world, y up, at the setup pose — so the aim from that root to the point lies &lt;off&gt;° off the hang (rest &lt;rest&gt;°): \|rest\| &lt;off&gt;° + "&lt;end&gt;" &lt;e&gt;° is &lt;sum&gt;°”, then one of “, above &lt;BOUND&gt;°. Move "&lt;stop.names.point&gt;" to within &lt;BOUND − e&gt;° (&lt;BOUND&gt;° − "&lt;end&gt;") of the direction "&lt;stop.links[0]&gt;" hangs in from its root, &lt;at.hang&gt;°, or state "&lt;end&gt;" at most &lt;BOUND − off&gt;°”, “, above &lt;BOUND&gt;°, and no point lowers it: \|rest\| is above 0° for every point a stop accepts. State "&lt;end&gt;" below &lt;BOUND&gt;°”, “, below -&lt;BOUND&gt;°. State "&lt;end&gt;" at least &lt;−BOUND − off&gt;°”<br>Here the values named in the message include: “inward”, “outward”. | On the first link the bound is \|rest\| + the end, where rest is the angle from the link's hang to the aim at `<chain>_touch`, both read from the link's root: move `<chain>_touch` (its `at` on `against`) to within 180° − `outward` of the direction the link hangs in from its root — on a link hanging straight down with `outward` at most 90°, any point below the root — or lower `outward` to at most 180° − \|rest\|. A leg that rises from behind the cloth, as on a prone figure, puts a point at its far end above the root; put it at the knee. On a lower link, bring `lower`'s ends within ±180° of the link's own rest bend. |
+| <a id="CE_STOP_LOCAL_BOUND_RANGE"></a>`CE_STOP_LOCAL_BOUND_RANGE` | “&lt;stop.who&gt;: "&lt;field&gt;&lt;end&gt;" &lt;range[end]&gt; puts &lt;what&gt;'s bound at &lt;value&gt;°, past ±&lt;BOUND&gt;° — the clamp reads a local rotation in (-180, 180], so a bound past it is never reached and the range it states is not the one that holds”<br>On the first link it goes on: “. "&lt;stop.links[0]&gt;" hangs at &lt;at.hang&gt;° from its root at [&lt;at.root&gt;], and "&lt;stop.names.point&gt;" ("at" [&lt;stop.at&gt;] on "&lt;stop.against&gt;") sits at [&lt;at.point&gt;] — Spine world, y up, at the setup pose — so the aim from that root to the point lies &lt;off&gt;° off the hang (rest &lt;rest&gt;°): \|rest\| &lt;off&gt;° + "&lt;end&gt;" &lt;e&gt;° is &lt;sum&gt;°”, then one of “, above &lt;BOUND&gt;°. Move "&lt;stop.names.point&gt;" to within &lt;BOUND − e&gt;° (&lt;BOUND&gt;° − "&lt;end&gt;") of the direction "&lt;stop.links[0]&gt;" hangs in from its root, &lt;at.hang&gt;°, or state "&lt;end&gt;" at most &lt;BOUND − off&gt;°”, “, above &lt;BOUND&gt;°, and no point lowers it: \|rest\| is above 0° for every point a stop accepts. State "&lt;end&gt;" below &lt;BOUND&gt;°”, “, below -&lt;BOUND&gt;°. State "&lt;end&gt;" at least &lt;−BOUND − off&gt;°”<br>Here the values named in the message include: “inward”, “outward”. | On the first link the bound is \|rest\| + the end, where rest is the angle from the link's hang to the aim at `<chain>_touch`, both read from the link's root: move `<chain>_touch` (its `at` on `against`) to within 180° − `outward` of the direction the link hangs in from its root — on a link hanging straight down with `outward` at most 90°, any point below the root — or lower `outward` to at most 180° − \|rest\|. A leg that rises from behind the cloth, as on a prone figure, puts a point at its far end above the root; put it at the knee. On a lower link, bring `lower`'s ends within ±180° of the link's own rest bend. The values you stated (`inward`, `outward`, `at`) are echoed as written; every figure the expansion derived prints to three decimals, a figure past ±180° rounded away from zero so it never reads as on the bound, and a remedy (`at most`, `at least`, `within`) rounded toward zero, so stating the printed value is accepted. |
 | <a id="CE_STOP_DEPENDENCY_ORDER"></a>`CE_STOP_DEPENDENCY_ORDER` | “&lt;who&gt;: "&lt;tip&gt;" hangs below "&lt;name&gt;", which a later stop generates — declare that stop first, so its angles are known when this one is read”<br>Also: “&lt;value&gt;: stop "&lt;value&gt;"” | Declare the stop generating the parent before the stop depending on it. |
 | <a id="CE_STOP_ANCESTOR_MANIFEST_POSITION"></a>`CE_STOP_ANCESTOR_MANIFEST_POSITION` | “&lt;who&gt;: "&lt;name&gt;" takes its place from the manifest ("from"), and a stop's angles are read off the setup pose this rig spec states — state its x, y and rotation”<br>Also: “&lt;value&gt;: stop "&lt;value&gt;"” | State x, y and rotation for the named setup-pose ancestor instead of from. |
 | <a id="CE_STOP_FRAME_PARENT_TRANSFORM"></a>`CE_STOP_FRAME_PARENT_TRANSFORM` | “&lt;who&gt;: "&lt;parent&gt;", where the frame hangs, is scaled unevenly, sheared or reflected at the setup pose — the frame's angles add to its parent's only through a rotation and an even scale, and inward is a turn's sense”<br>Also: “&lt;value&gt;: stop "&lt;value&gt;"” | Use a frame parent with rotation and even positive scale, without shear or reflection. |
@@ -8496,6 +8508,34 @@ from its own frame and no earlier (`RE02`); and plants on the core the readings
 mapping rejects — the schedule ignored, its y read up, each change a frame late or
 early — each red against spine-core (`RE03`).
 
+**Whether the physics ran.** Every render — with this flag or without — says, under
+each set's line, how many physics constraints the poser stepped on at least one of
+its frames, and at what rate:
+
+```text
+  ..    idle             25 frame(s), 2.000s + contact.png -> render/idle
+  ..    physics: 3 constraint(s) stepped at 12 fps
+```
+
+and `frames.json` carries the same two figures on that set, `"physics": { "stepped":
+3, "fps": 12 }`. The rate is the set's own: one physics update a frame. The count is
+read off the posed state, not off the declaration: a constraint counts when, after
+a step that moved the skeleton's clock, its own clock reads the skeleton's — which
+the physics update sets and every way of not running leaves behind. So a constraint
+that is inactive on every frame, or at a mix of 0, is not counted, and the line names
+it: `physics: 0 constraint(s) stepped at 12 fps — 1 of the 1 declared took none:
+"iris_settle" (inactive, or a mix of 0, on every frame)`; a set of one pose — an
+animation of no length, or the setup pose of a skeleton with none — takes no step
+and says so. A rig that declares no physics constraint prints `physics: none in this
+rig — it declares no physics constraint, so no frame steps one` once, before the
+sets, and its `frames.json` carries no `physics` field, as every frame set written
+before the field existed carries none. This is what tells a reading — a fold count
+from `--folds`, say (§8.3) — taken with the physics from one taken without. Both
+posers read the same constraints on every frame, and `cli.ts`, `cli.ts --poser
+spine` and `cli_core.ts` write the same files (`PH01`, `PH02`); the step removed —
+on the core, or spine-core's `PhysicsConstraint.update` made a no-op — reads 0
+(`PH03`), and a constraint at mix 0 is named (`PH04`).
+
 **The files.** `frames.json` and each `geometry.json` record the schedule as
 `environment`, its steps as read, `t`, `wind`, `gravity` in that order. The
 framing reads it too: a gust can carry a coat past the box a still rig fills, so

package/docs/INGEST.md

@@ -191,6 +191,7 @@ rigc render
   ..    atlas    …/examples/spineboy/export/spineboy.atlas
   ..    poser    spine-core — no skeleton.model.json beside …/examples/spineboy/export/spineboy-pro.json — a Spine export, not a rigc build
   ..    200x186px at 8 fps, 1 set(s) -> …/render/sb
+  ..    physics: none in this rig — it declares no physics constraint, so no frame steps one
   ..    walk             9 frame(s), 1.000s + contact.png -> …/render/sb/walk@8fps
 rigc: wrote …/render/sb/frames.json
 ```

package/docs/MOTION.md

@@ -1067,6 +1067,7 @@ rigc render --candidate spine --fps 24 --max 200
 
 ```
   ..    134x200px at 24 fps, 1 set(s) -> …/semaphore/render
+  ..    physics: none in this rig — it declares no physics constraint, so no frame steps one
   ..    raise            14 frame(s), 0.542s + contact.png -> …/semaphore/render/raise@24fps
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.60.0",
+  "version": "2.61.1",
   "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/cli/core_commands.ts

@@ -736,6 +736,8 @@ export function cmdRender(flags: Record<string, string>): void {
   const only = readAnimationFlag(flags, [...facts.animations]);
   const skin = readSkinFlag(flags, [...facts.skins]);
   const subset = readSlotSubsetFlags(flags, facts, skin);
+  // The physics constraints the skeleton declares, off the Spine file both posers read (issue #1467).
+  const physicsDeclared = environmentResponse(skeletonText).declared;
   const passPairs = readPassThroughFlag(passThrough, facts);
   const seamPairs = readSeamFlag(seam, facts);
   // The angle reading (issue #1414) reads bones, which a subset of the drawn slots does not change, so it takes --slot/--hide.
@@ -810,7 +812,14 @@ export function cmdRender(flags: Record<string, string>): void {
     // The bones ride along for --geometry and --angle-range, the whole attachments for --geometry and the two readings off them.
     const wantsBones = geometry || anglePairs !== undefined;
     const wantsGeometry = geometry || folds || passPairs !== undefined || seamPairs !== undefined;
-    const sampling = !wantsBones && !wantsGeometry ? pose : { ...pose, ...(wantsBones ? { bones: true } : {}), ...(wantsGeometry ? { geometry: true } : {}) };
+    // The physics constraints each frame's step stepped ride along whenever the rig declares one (issue #1467): the
+    // `physics:` line and frames.json's `physics` field are read off them.
+    const sampling = {
+      ...pose,
+      ...(wantsBones ? { bones: true } : {}),
+      ...(wantsGeometry ? { geometry: true } : {}),
+      ...(physicsDeclared.length > 0 ? { physics: true } : {}),
+    };
     const sampled: Map<string, Frame[]> =
       only === undefined
         ? sampleAll(poser, fps, sampling)
@@ -916,6 +925,8 @@ export function cmdRender(flags: Record<string, string>): void {
     );
   }
   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}`);
   if (!facts.declaresStage) console.log(`  ..    ${STAGELESS_FRAMING.render}`);
   // A given box (issue #1414): said with the box it replaced, and every slot it leaves part of out, by set and frame.
   const outside = given === undefined ? [] : outsideViewport(sampled, viewport);
@@ -959,6 +970,7 @@ export function cmdRender(flags: Record<string, string>): void {
     const seamReading = seamReadings.get(name);
     if (seamReading !== undefined) writeFileSync(join(dir, SEAM_FILE), seamText(seamReading));
     const duration = frames[frames.length - 1].time;
+    const physics = physicsDeclared.length === 0 ? undefined : physicsSteppedOf(frames, fps);
     sets.push({
       dir: dirName,
       animation: name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name,
@@ -967,6 +979,7 @@ export function cmdRender(flags: Record<string, string>): void {
       written: frames.length,
       stride: 1,
       duration,
+      ...(physics === undefined ? {} : { physics: { stepped: physics.stepped.length, fps } }),
     });
     const how = frames.length === 1 ? 'a single pose' : `${duration.toFixed(3)}s`;
     const folding = foldReading?.meshes.filter((m) => m.worst !== null).length ?? 0;
@@ -977,6 +990,7 @@ export function cmdRender(flags: Record<string, string>): void {
     const seamNote = seamReading === undefined ? '' : ` + ${SEAM_FILE} (${opening} of ${seamReading.pairs.length} pair(s) open)`;
     const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}${passNote}${seamNote}`;
     console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${extras} -> ${dir}`);
+    if (physics !== undefined) console.log(`  ..    ${physicsLine(physics.stepped, physicsDeclared, fps, frames.length)}`);
     for (const mesh of foldReading?.meshes ?? []) {
       const key = `${mesh.slot}\u0000${mesh.attachment}`;
       const fault = faultsSaid.has(key) ? null : setupFaultLine(mesh);
@@ -1022,6 +1036,28 @@ export function cmdRender(flags: Record<string, string>): void {
   console.log(`rigc: wrote ${join(outRoot, FRAMES_SIDECAR)}`);
 }
 
+/** `render`'s line for a rig that declares no physics constraint (issue #1467): nothing was stepped because nothing could be. */
+export const PHYSICS_NONE_LINE = 'physics: none in this rig — it declares no physics constraint, so no frame steps one';
+
+/** The physics constraints any frame of a set stepped (issue #1467), by name in code-unit order. */
+export function physicsSteppedOf(frames: readonly Frame[], fps: number): { stepped: string[]; fps: number } {
+  const names = new Set<string>();
+  for (const frame of frames) for (const name of frame.physics ?? []) names.add(name);
+  return { stepped: [...names].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)), fps };
+}
+
+/**
+ * `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 {
+  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';
+  return `${head} — ${idle.length} of the ${declared.length} declared took none: ${idle.map((n) => JSON.stringify(n)).join(', ')} (${why})`;
+}
+
 /** Where `inspect` writes when `--out` is not given, and the name it takes inside a directory `--out` names. */
 export const DEFAULT_INSPECT_OUT = 'inspect.png';
 
@@ -1351,7 +1387,7 @@ export function cmdExplain(flags: Record<string, string>): void {
   const leverFold = flags['lever-fold'] === undefined ? null : Number(flags['lever-fold']);
   const leverWhy = leverFold === null ? null : leverFractionWhy(leverFold);
   if (leverWhy !== null) throw new UsageError(`--lever-fold ${JSON.stringify(flags['lever-fold'])}: ${leverWhy}`);
-  const { label, opts } = resolveCut(flags);
+  const { label, opts } = resolveCut(flags, 'explain');
   console.log(`rigc explain ${label}`);
   // See the identical pair of lines in `cmdBuild` for why both paths are named
   // here rather than only the one the header's `label` happens to carry.
@@ -2203,6 +2239,39 @@ function resolveDelegate(name: string): string | null {
   return null;
 }
 
+/**
+ * Whether the Bun running this hands an empty argument to a process it starts
+ * (issue #1465). Bun 1.2.0 — the declared minimum — does not: `["a", "", "b"]`
+ * reaches the child as `["a", "b"]`, through `spawnSync` and `Bun.spawnSync`
+ * alike and whatever the child is; 1.4.2 hands it over. That is measured here
+ * rather than read off a version number, by starting this Bun twice with
+ * `-e` and comparing how many arguments arrived: `[pad, "x"]` and
+ * `[pad, "", "x"]` differ by one exactly where the empty one survives. The pad
+ * is there because 1.2.0's `-e` also swallows the first argument after the
+ * script; it is the same on both runs, so the difference is the empty one's.
+ */
+export function spawnKeepsEmptyArguments(): boolean {
+  const count = (args: string[]): string =>
+    spawnSync(process.execPath, ['-e', 'process.stdout.write(String(process.argv.length))', ...args], { encoding: 'utf8' }).stdout;
+  return Number(count(['pad', '', 'x'])) === Number(count(['pad', 'x'])) + 1;
+}
+
+/**
+ * The refusal for a delegated command line this Bun cannot hand over whole, or
+ * `null` (issue #1465): an empty argument, under a Bun that drops one, would
+ * reach the package with the others and nothing would say so. `keeps` is asked
+ * only when there is an empty argument, so a command line without one never
+ * starts the probe.
+ */
+export function emptyArgumentRefusal(pkg: string, raw: readonly string[], keeps: () => boolean, bun: string): string | null {
+  const at = raw.indexOf('');
+  if (at < 0 || keeps()) return null;
+  return (
+    `argument ${at + 1} is empty, and Bun ${bun}, the Bun running this, drops an empty argument when it starts a process — ` +
+    `${pkg} would receive the others without it, and nothing would say so. Give it a value, or run rigc under a Bun that keeps it`
+  );
+}
+
 /**
  * A delegating command's body (`CommandDoc.delegate`, issue #1457): resolve the
  * package's bin and run it under the Bun running this — the bin is a Bun script
@@ -2225,6 +2294,8 @@ function cmdDelegate(command: string, raw: readonly string[]): void {
       2,
     );
   }
+  const dropped = emptyArgumentRefusal(delegate.package, raw, spawnKeepsEmptyArguments, process.versions.bun ?? 'unknown');
+  if (dropped !== null) throw new DelegateError(dropped, 2);
   const ran = spawnSync(process.execPath, [bin, ...raw], { stdio: 'inherit' });
   // ⚠️ The exit and the signal are read before `error`: Bun 1.2.0 — the declared minimum — sets `error` on every
   // child that exits non-zero, so reading it first refused review's own exit 7 as "could not run". `error` is a

package/src/cli/shared.ts

@@ -94,6 +94,19 @@ export type CutTable = Record<string, CutEntry>;
 
 export class UsageError extends Error {}
 
+/**
+ * A usage error that is one required flag missing from a spelled-out cut —
+ * printed as its one line and exit 2, without the usage block under it (issue
+ * #1466). The catalogue under `--out is required` buried the only line that
+ * said what to add, which is `PoseError`'s reason for printing alone. Still a
+ * `UsageError`, so every reader that asks whether an invocation was refused
+ * reads it as one.
+ */
+export class MissingFlagError extends UsageError {}
+
+/** The `<value>` each flag of a spelled-out cut takes, for the line that names a missing one. */
+const CUT_FLAG_VALUES = { rig: '<rig.json>', motion: '<motion.json>', out: '<dir>' } as const;
+
 /**
  * `explain` refusing a pair it cannot pose — a usage error in kind, printed
  * without the usage block for `PoseError`'s and `IngestError`'s reason: the
@@ -264,7 +277,7 @@ function entryToOptions(dir: string, name: string, entry: CutEntry): CompileOpti
  * Resolve the cut a command was pointed at, either spelled out on the command
  * line or looked up by name in a cuts.json.
  */
-export function resolveCut(flags: Record<string, string>): { label: string; opts: CompileOptions } {
+export function resolveCut(flags: Record<string, string>, command: 'build' | 'explain' | 'validate'): { label: string; opts: CompileOptions } {
   const explicit =
     flags.rig !== undefined || flags.manifest !== undefined || flags.motion !== undefined || flags.out !== undefined;
   if (explicit) {
@@ -272,7 +285,7 @@ export function resolveCut(flags: Record<string, string>): { label: string; opts
       throw new UsageError('--rig/--motion/--out and --cut/--cuts are two ways to say the same thing; pick one');
     }
     for (const key of ['rig', 'motion', 'out'] as const) {
-      if (flags[key] === undefined) throw new UsageError(`--${key} is required when the cut is spelled out`);
+      if (flags[key] === undefined) throw new MissingFlagError(`${command} needs --${key} ${CUT_FLAG_VALUES[key]} (or --cut <name> --cuts <cuts.json>)`);
     }
     const opts: CompileOptions = {
       rigPath: resolve(flags.rig),
@@ -2291,7 +2304,7 @@ function pageRectangle(region: AtlasRegion): string {
  * alone (`./core_commands.ts`). Moved here unchanged from `cmdBuild`.
  */
 export function readBuildInvocation(flags: Record<string, string>): { label: string; opts: CompileOptions; profile: AssertionProfile; packing: boolean } {
-  const { label, opts } = resolveCut(flags);
+  const { label, opts } = resolveCut(flags, 'build');
   const profile = readProfile(flags);
   const packing = flags.pack !== undefined;
   // Two combinations are refused rather than silently resolved, because in each
@@ -3001,6 +3014,10 @@ export function runCli(entry: CliEntry, argv: readonly string[]): void {
  * (`CliEntry.refusals`). Anything else is not a refusal and is thrown on.
  */
 function refuse(err: unknown, command: string | undefined, USAGE: string, entry: CliEntry): never {
+  if (err instanceof MissingFlagError) {
+    console.error(`rigc: ${err.message}`);
+    process.exit(2);
+  }
   if (err instanceof UsageError) {
     console.error(`rigc: ${err.message}\n\n${USAGE}`);
     process.exit(2);

package/src/cli/spine_commands.ts

@@ -76,7 +76,7 @@ export function cmdValidate(flags: Record<string, string>, positional: string[])
   // a directory alone cannot supply — and the report says which it had.
   const named = flags.cut !== undefined || flags.rig !== undefined;
   const profile = readProfile(flags);
-  const derivedOpts = named ? resolveCut(flags).opts : null;
+  const derivedOpts = named ? resolveCut(flags, 'validate').opts : null;
   // Both files there before the first line, from the one statement of a build (issue #1046): a directory without them
   // read the skeleton unguarded and died on an ENOENT and a stack.
   const { skeletonPath, atlasPath } = spinePairOf(resolveBuild(derivedOpts ? derivedOpts.outDir : (positional[0] ?? '.'), flags.atlas));

package/src/compile.ts

@@ -18,7 +18,7 @@
  * the two emits byte for byte (assertion A18).
  */
 import { basename, dirname, join, relative, resolve } from 'node:path';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { readPngHeader, readPngInfo } from './png.ts';
 import {
   DEPTH_TONE_IDENTITY,
@@ -1649,8 +1649,62 @@ function easingCurve(
 // inputs
 // ---------------------------------------------------------------------------
 
-function readJson<T>(path: string): T {
+/**
+ * Which input a JSON path was given as, for the refusal a directory gets: the
+ * flag that named it, the file it wants, and whether a file's contents read as
+ * one (`null` where no parser exists here — the manifest is cast, not parsed).
+ */
+interface JsonInputRole {
+  flag: '--rig' | '--motion' | '--manifest';
+  wants: string;
+  reads: ((raw: unknown, where: string) => unknown) | null;
+}
+
+const RIG_INPUT: JsonInputRole = { flag: '--rig', wants: 'the rig spec file', reads: parseRigSpec };
+const MOTION_INPUT: JsonInputRole = { flag: '--motion', wants: 'the motion spec file', reads: parseMotionSpec };
+const MANIFEST_INPUT: JsonInputRole = { flag: '--manifest', wants: 'the cut manifest file', reads: null };
+
+/** The most `.json` names a directory refusal lists before it says how many there are. */
+const LISTED_JSON_NAMES = 8;
+
+/**
+ * The refusal for an input flag that names a directory (issue #1466): what the
+ * flag wants, and what the directory holds — the one file there that reads as
+ * that input, named by its path, or every `.json` there when that is not
+ * exactly one. Nothing is accepted on the strength of it: the caller is told
+ * the path, and the compile still reads only what it was given. The names are
+ * sorted, so the sentence is the same on every machine.
+ */
+function directoryInputRefusal(dir: string, role: JsonInputRole): string {
+  const head = `${role.flag} names a directory; it wants ${role.wants} —`;
+  const names = readdirSync(dir)
+    .filter((name) => name.endsWith('.json') && statSync(join(dir, name)).isFile())
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  if (names.length === 0) return `${head} ${dir} holds no .json file`;
+  const reading = names.filter((name) => {
+    if (role.reads === null) return true;
+    const file = join(dir, name);
+    try {
+      role.reads(parseJsonWithPosition(readFileSync(file, 'utf8')), file);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  if (reading.length === 1) return `${head} ${join(dir, reading[0])} exists there`;
+  const listed = (list: string[]): string =>
+    list.slice(0, LISTED_JSON_NAMES).join(', ') + (list.length > LISTED_JSON_NAMES ? `, … ${list.length} in all` : '');
+  if (reading.length === 0) {
+    return `${head} ${dir} holds ${names.length} .json file(s) and none reads as one: ${listed(names)}`;
+  }
+  return `${head} ${reading.length} .json files in ${dir} read as one, so name it: ${listed(reading)}`;
+}
+
+function readJson<T>(path: string, role: JsonInputRole): T {
   let text: string;
+  if (existsSync(path) && statSync(path).isDirectory()) {
+    throw new CompileError(directoryInputRefusal(path, role), 'CE_COMPILE_JSON_READ_FAILED');
+  }
   try {
     text = readFileSync(path, 'utf8');
   } catch (err) {
@@ -2309,11 +2363,11 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   const manifestPath = opts.manifestPath === undefined ? null : resolve(opts.manifestPath);
   const manifestDir = manifestPath === null ? null : dirname(manifestPath);
 
-  const rig = parseRigSpec(readJson<unknown>(rigPath), rigPath);
+  const rig = parseRigSpec(readJson<unknown>(rigPath, RIG_INPUT), rigPath);
   // Parsed, not cast, since issue #307 — `src/motion.ts` states what it proves
   // and which refusals it deliberately leaves in this file.
-  const motion = parseMotionSpec(readJson<unknown>(motionPath), motionPath);
-  const manifest = manifestPath === null ? null : readJson<FaceManifest>(manifestPath);
+  const motion = parseMotionSpec(readJson<unknown>(motionPath, MOTION_INPUT), motionPath);
+  const manifest = manifestPath === null ? null : readJson<FaceManifest>(manifestPath, MANIFEST_INPUT);
   // The manifest is the record of what was measured, and its numbers become
   // bone positions and the stage: a `crop.h` of 1e309 built as `"height": null`
   // before issue #881. The rig spec's walk is `parseRigSpec`'s; this is the

package/src/render.ts

@@ -549,9 +549,25 @@ function spinePosed(skeleton: Skeleton): Posed {
     pieces: (draw) => drawPieces(skeleton, draw),
     bones: () => boneSnapshots(skeleton),
     attachments: () => attachmentsOf(skeleton),
+    physics: () => steppedPhysicsOf(skeleton),
   };
 }
 
+/**
+ * `Posed.physics` on spine-core (issue #1467): every physics constraint whose
+ * `lastTime` reads the skeleton's `time` after a step that moved it — which
+ * `PhysicsConstraint.update` sets under `Physics.update` and `Physics.reset`,
+ * and which an inactive constraint, a mix of 0 or `Physics.none` leaves where
+ * it was. The setup pose and frame 0 sit at time 0 and step none.
+ */
+function steppedPhysicsOf(skeleton: Skeleton): string[] {
+  if (!(skeleton.time > 0)) return [];
+  return skeleton.physics
+    .filter((c) => c.lastTime === skeleton.time)
+    .map((c) => c.data.name)
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
 /**
  * A fresh skeleton under `skin`, stepped into its setup pose — the one recipe
  * `sampleSetupPose` and the geometry export's `rest` table both pose from, so

package/src/render_core.ts

@@ -102,6 +102,7 @@ import { clipThrough, type ClipShape, type ShapeClipper } from './core/clipping.
 import { activeBones, CoreInputError, readModel, sourceOfDoc, underNoSkin, underSkin, type CompiledDocument, type CoreSlotRow } from './core/index.ts';
 import { PHYSICS_CLOCK_LEAD, physicsClockStep, poseRawAnimationEach, 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';
 import { documentPageLookup, drawnRegions, meshPageUvs, readUvSequences, regionPageUvs, type DrawnRegion, type UvRegion, type UvSource } from './core/uvs.ts';
 import { regionCorners, worldVertices } from './core/vertices.ts';
@@ -378,10 +379,14 @@ export const CORE_RAW_WALK: CoreRawWalk = (doc, animation, steps, plant, visit,
  */
 export { PHYSICS_CLOCK_LEAD, physicsClockStep };
 
-/** What a suite passes `corePoser` in place of the poser's own parts — `PieceArrays` (`RC43`) and the raw walk (`RC44`). */
+/**
+ * What a suite passes `corePoser` in place of the poser's own parts — `PieceArrays` (`RC43`), the raw walk (`RC44`), and
+ * the physics step the walk runs (issue #1467: a step that does nothing has to read 0 on the render's `physics:` line).
+ */
 export interface CorePoserPlants {
   arrays?: () => PieceArrays;
   walk?: CoreRawWalk;
+  physicsStep?: PhysicsStepper;
 }
 
 /**
@@ -457,7 +462,7 @@ function clipCover(pose: RawPose, active: ReadonlySet<string>): Map<string, Clip
 }
 
 /** One posed moment of the core, read through the seam's `Posed`. */
-function corePosed(input: CoreInput, pose: RawPose, through: ShapeClipper): Posed {
+function corePosed(input: CoreInput, pose: RawPose, through: ShapeClipper, stepped: readonly string[]): Posed {
   const slotRows = new Map<string, CoreSlotRow>(pose.slots.map((row) => [row[0], row]));
   let regions: Map<string, DrawnRegion> | null = null;
   const regionsOf = (): Map<string, DrawnRegion> => {
@@ -501,6 +506,7 @@ function corePosed(input: CoreInput, pose: RawPose, through: ShapeClipper): Pose
     },
     attachments: (): AttachmentPose[] =>
       pose.drawn.map((d) => ({ slot: d.slot, attachment: d.attachment, vertices: [...d.vertices], color: tintOf(d) })),
+    physics: (): string[] => [...stepped],
   };
 }
 
@@ -752,7 +758,7 @@ export function corePoser(
     subset: (opts, skin) => subsetOver(roster, opts, skin),
     setup: (skin) => {
       const input = inputOf(skin);
-      return corePosed(input, poseRawSetup(input.doc, { through }), through);
+      return corePosed(input, poseRawSetup(input.doc, { through }), through, []);
     },
     animation: (name, skin, fps, count, visit, environment) => {
       const input = inputOf(skin);
@@ -762,10 +768,22 @@ export function corePoser(
       // walk that refuses a later pose still refuses the call, and a draw that throws is re-thrown once the walk has
       // finished without refusing — the first such throw, by frame — and no frame after it is drawn.
       const drawFailed: unknown[] = [];
-      walk(input.doc, name, new Array<number>(count).fill(step), { through }, (pose, i) => {
+      // `Posed.physics` on the core (issue #1467): the constraints whose state's clock reads the skeleton's after a step
+      // that moved it — spine-core's reading (`steppedPhysicsOf` in `src/render.ts`), taken off the same state the step
+      // writes, as each constraint is stepped, and handed to the pose the step made.
+      const steppedNow = new Set<string>();
+      const inner = plants.physicsStep ?? stepPhysics;
+      const physicsStep: PhysicsStepper = (r, w, length, ctx) => {
+        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;
+      };
+      walk(input.doc, name, new Array<number>(count).fill(step), { through, physicsStep }, (pose, i) => {
+        const stepped = [...steppedNow].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+        steppedNow.clear();
         if (drawFailed.length > 0) return;
         try {
-          visit(i, corePosed(input, pose, through));
+          visit(i, corePosed(input, pose, through, stepped));
         } catch (thrown) {
           drawFailed.push(thrown);
         }

package/src/render_shared.ts

@@ -190,6 +190,20 @@ export interface FrameSet {
    * file could only ever be the stale one.
    */
   duration: number;
+  /**
+   * Whether the physics ran while these frames were posed (issue #1467): how
+   * many physics constraints the poser stepped on at least one frame of this
+   * set, and the rate it stepped them at — the set's own `fps`, one skeleton
+   * update a frame. `render` prints the same two figures on its `physics:` line.
+   *
+   * ⭐ Absent on a rig that declares no physics constraint, for `skin`'s
+   * reason in `FramesSidecar`: there is nothing for the field to count, and
+   * every frame set written before it existed says the same. Present, a 0 is a
+   * claim — the rig declares physics and no constraint took a step on any
+   * frame — and that is what tells a reading taken with physics from one
+   * taken without.
+   */
+  physics?: { stepped: number; fps: number };
 }
 
 export interface FramesSidecar {
@@ -445,6 +459,8 @@ export interface PoseOptions {
    * so `framingViewport` keeps it and the box holds what the frames draw.
    */
   environment?: readonly EnvironmentStep[];
+  /** Also record the physics constraints the step that posed each frame stepped — see `Frame.physics` (issue #1467). */
+  physics?: boolean;
 }
 
 /**
@@ -586,6 +602,12 @@ export interface Frame {
    * second derivation of it.
    */
   attachments?: AttachmentPose[];
+  /**
+   * The physics constraints the step that posed this frame stepped, by name in
+   * code-unit order — present only when `PoseOptions.physics` asked for it
+   * (issue #1467). See `Posed.physics` for what counts as a step.
+   */
+  physics?: string[];
 }
 
 /**
@@ -1055,6 +1077,16 @@ export interface Posed {
   bones(): BoneSnapshot[];
   /** Every slot's region or mesh attachment, whole, in the posed draw order. */
   attachments(): AttachmentPose[];
+  /**
+   * The physics constraints the step that posed this moment stepped, by name in
+   * code-unit order (issue #1467). A constraint is stepped when, after a step
+   * that moved the skeleton's clock, its own clock reads the skeleton's: the
+   * physics update sets it there, and every way of not running — inactive, a
+   * mix of 0, the step skipped — leaves it behind. Read off the posed state on
+   * both posers, never off which call was made, so a step removed reads 0. The
+   * setup pose and a reset pose, where the clock has not moved, step none.
+   */
+  physics(): string[];
 }
 
 /**
@@ -1126,6 +1158,7 @@ function frameOf(index: number, time: number, posed: Posed, draw: DrawOptions, o
     pieces: posed.pieces(draw),
     ...(opts?.bones ? { bones: posed.bones() } : {}),
     ...(opts?.geometry ? { attachments: posed.attachments() } : {}),
+    ...(opts?.physics ? { physics: posed.physics() } : {}),
   };
 }
 

package/src/stop.ts

@@ -126,6 +126,37 @@ interface FirstLink {
   point: readonly [number, number];
 }
 
+/**
+ * Every number a stop's refusal prints, in one place (issue #1463). How it is
+ * printed depends on what the number is to the author:
+ *
+ *   - `stated` — a value the author typed (`inward`, `outward`, `at`), echoed
+ *     exactly as JavaScript reads it back, so it can be found in the rig spec.
+ *     It is never rounded: two stated ends 2.60251 and 2.60249 would both print
+ *     2.603, and the refusal would read "2.603 is greater than 2.603";
+ *   - `reading` — a figure the expansion derived (a hang, a world position, a
+ *     rest angle), at the three decimals the compiler's other degree refusals
+ *     print, rounded to nearest;
+ *   - `past` — a figure refused for lying past ±180°, rounded **away from
+ *     zero**, so it never prints on the bound: 180.0000001 prints 180.001,
+ *     not 180.000, which would read as inside the range;
+ *   - `remedy` — a figure the refusal offers the author to state ("at most",
+ *     "at least", "within"), rounded **toward zero**, so stating the printed
+ *     value is accepted rather than refused again by the digits dropped.
+ *
+ * The rule is that rounding never moves a figure across the line the
+ * refusal is about: a `past` figure stays past it, a `remedy` stays inside.
+ */
+function stopFigure(v: number, how: 'stated' | 'reading' | 'past' | 'remedy'): string {
+  if (how === 'stated') return String(v);
+  const near = Number(v.toFixed(3));
+  let r = near;
+  if (how === 'past' && Math.abs(near) < Math.abs(v)) r = near + Math.sign(v) * 0.001;
+  if (how === 'remedy' && Math.abs(near) > Math.abs(v)) r = near - Math.sign(v) * 0.001;
+  const text = r.toFixed(3);
+  return text === '-0.000' ? '0.000' : text;
+}
+
 /** An angle in (-540, 540) brought into (-180, 180] by at most one whole turn. */
 function halfTurn(deg: number): number {
   if (deg > 180) return deg - 360;
@@ -216,7 +247,7 @@ export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {})
       }
       if (out.inward > out.outward) {
         throw new CompileError(
-          `${who}: "${field}inward" ${out.inward} is greater than "${field}outward" ${out.outward} — the range is [inward, outward] in degrees counted positive away from "${against}", and this one holds no angle`, 'CE_STOP_RANGE_REVERSED',
+          `${who}: "${field}inward" ${stopFigure(out.inward, 'stated')} is greater than "${field}outward" ${stopFigure(out.outward, 'stated')} — the range is [inward, outward] in degrees counted positive away from "${against}", and this one holds no angle`, 'CE_STOP_RANGE_REVERSED',
         );
       }
       return out;
@@ -350,15 +381,16 @@ export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {})
     const e = stop[end];
     const off = Math.abs(rest);
     const sum = off + e;
+    const position = (p: readonly number[], how: 'stated' | 'reading'): string => p.map((v) => stopFigure(v, how)).join(', ');
     const geometry =
-      `. "${stop.links[0]}" hangs at ${at.hang}° from its root at [${at.root.join(', ')}], and "${stop.names.point}" ("at" [${stop.at.join(', ')}] on "${stop.against}") ` +
-      `sits at [${at.point.join(', ')}] — Spine world, y up, at the setup pose — so the aim from that root to the point lies ${off}° off the hang (rest ${rest}°): ` +
-      `|rest| ${off}° + "${end}" ${e}° is ${sum}°`;
-    if (sum < -BOUND) return `${geometry}, below -${BOUND}°. State "${end}" at least ${-BOUND - off}°`;
+      `. "${stop.links[0]}" hangs at ${stopFigure(at.hang, 'reading')}° from its root at [${position(at.root, 'reading')}], and "${stop.names.point}" ("at" [${position(stop.at, 'stated')}] on "${stop.against}") ` +
+      `sits at [${position(at.point, 'reading')}] — Spine world, y up, at the setup pose — so the aim from that root to the point lies ${stopFigure(off, 'reading')}° off the hang (rest ${stopFigure(rest, 'reading')}°): ` +
+      `|rest| ${stopFigure(off, 'reading')}° + "${end}" ${stopFigure(e, 'stated')}° is ${stopFigure(sum, 'past')}°`;
+    if (sum < -BOUND) return `${geometry}, below -${BOUND}°. State "${end}" at least ${stopFigure(-BOUND - off, 'remedy')}°`;
     if (e >= BOUND) return `${geometry}, above ${BOUND}°, and no point lowers it: |rest| is above 0° for every point a stop accepts. State "${end}" below ${BOUND}°`;
     return (
-      `${geometry}, above ${BOUND}°. Move "${stop.names.point}" to within ${BOUND - e}° (${BOUND}° − "${end}") of the direction "${stop.links[0]}" hangs in from its root, ${at.hang}°, ` +
-      `or state "${end}" at most ${BOUND - off}°`
+      `${geometry}, above ${BOUND}°. Move "${stop.names.point}" to within ${stopFigure(BOUND - e, 'remedy')}° (${BOUND}° − "${end}") of the direction "${stop.links[0]}" hangs in from its root, ${stopFigure(at.hang, 'reading')}°, ` +
+      `or state "${end}" at most ${stopFigure(BOUND - off, 'remedy')}°`
     );
   };
   const bounds = (stop: ReadStop, rest: number, sign: number, range: { inward: number; outward: number }, field: string, what: string, first?: FirstLink): [number, number] => {
@@ -368,7 +400,7 @@ export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {})
       if (Math.abs(value) > BOUND) {
         const why = first === undefined ? '' : aimed(stop, rest, end, first);
         throw new CompileError(
-          `${stop.who}: "${field}${end}" ${range[end]} puts ${what}'s bound at ${value}°, past ±${BOUND}° — the clamp reads a local rotation in (-180, 180], so a bound past it is never reached and the range it states is not the one that holds${why}`, 'CE_STOP_LOCAL_BOUND_RANGE',
+          `${stop.who}: "${field}${end}" ${stopFigure(range[end], 'stated')} puts ${what}'s bound at ${stopFigure(value, 'past')}°, past ±${BOUND}° — the clamp reads a local rotation in (-180, 180], so a bound past it is never reached and the range it states is not the one that holds${why}`, 'CE_STOP_LOCAL_BOUND_RANGE',
         );
       }
     }
@@ -422,7 +454,7 @@ export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {})
     const dx = target[0] - linkFrame.worldX;
     const dy = target[1] - linkFrame.worldY;
     if (dx === 0 && dy === 0) {
-      throw new CompileError(`${who}: "at" [${stop.at.join(', ')}] on "${stop.against}" sits on the root of "${links[0]}" at the setup pose — the frame aims from the root at the point, and there is no direction to a point it stands on`, 'CE_STOP_POINT_AT_ROOT');
+      throw new CompileError(`${who}: "at" [${stop.at.map((v) => stopFigure(v, 'stated')).join(', ')}] on "${stop.against}" sits on the root of "${links[0]}" at the setup pose — the frame aims from the root at the point, and there is no direction to a point it stands on`, 'CE_STOP_POINT_AT_ROOT');
     }
     const aim = directionDegrees(dx, dy);
     // Each angle is brought into (-180, 180] by one whole turn at most, so a
@@ -431,7 +463,7 @@ export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {})
     const rest = halfTurn(halfTurn(linkFrame.worldRotation) - aim);
     if (rest === 0) {
       throw new CompileError(
-        `${who}: "at" [${stop.at.join(', ')}] on "${stop.against}" lies on "${links[0]}"'s own line at the setup pose — inward is the turn from the link toward the point, and a point on the link's line has no side`, 'CE_STOP_POINT_ON_LINK_LINE',
+        `${who}: "at" [${stop.at.map((v) => stopFigure(v, 'stated')).join(', ')}] on "${stop.against}" lies on "${links[0]}"'s own line at the setup pose — inward is the turn from the link toward the point, and a point on the link's line has no side`, 'CE_STOP_POINT_ON_LINK_LINE',
       );
     }
     // Inward turns the link toward the aim line: counter-clockwise when the link