@rig-c/core 2.59.0 → 2.61.0

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. `--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,6 +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 |
 
 `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

@@ -141,6 +141,11 @@ bun cli.ts inspect --candidate path/to/spine --show art,bones,names --dim --out
 # them, ask a human — the one loop step this toolchain cannot run for you:
 bun cli.ts vote --candidate path/to/spine-a --candidate path/to/spine-b   # -> ballot.html
 bun cli.ts vote --record vote-<id>.json                                   # -> votes.jsonl
+
+# …and when the build is for a person to look at rather than for you to choose
+# between, hand it over: with @rig-c/review installed beside rigc, give the person
+# the loopback URL this prints (rigc review --help is review's own usage):
+bun cli.ts review open path/to/spine
 ```
 
 `build` compiles, runs the named assertions — through a `@esotericsoftware/spine-core`
@@ -255,6 +260,7 @@ What the flags mean:
 | `--geometry` | `render` only: also write a `geometry.json` into each frame directory — per frame, every bone's world transform and every slot's region or mesh vertices in world units after skinning, plus each attachment's rest geometry and topology, on the frames' own grid and viewport. Every other file is byte for byte what the render writes without it. Refused with `--slot`/`--hide`, because the geometry is the whole pose whatever is drawn — **§8.2** |
 | `--folds` | `render` only: also read which mesh triangles **fold** — turn over against the setup pose — and write a `folds.json` into each frame directory: per mesh, the frames with a folded triangle, the worst frame's count and which triangles, by index, with their world box and setup-pose area. One printed line per mesh that folds; a triangle degenerate or inverted at the setup pose is said once and never counted. A reading, not a gate. Every other file is byte for byte what the render writes without it, `geometry.json` included. Refused with `--slot`/`--hide`, for `--geometry`'s reason — **§8.3** |
 | `--pass-through` | `render` only: `<cloth>:<leg>[,<cloth>:<leg>…]` — also read where each cloth slot **passes through** its leg slot, and write a `pass-through.json` into each frame directory: the frames where the cloth draws over the leg and its drawn side lies inside the leg's drawn outline by 2 steps or more, each with the depth and the world box. One printed line per pair, and one per frame that passes through. The first name must draw over the second for a frame to be read — the declared order, never both. A reading, not a gate. Every other file is byte for byte what the render writes without it. An unknown slot, a slot that draws on no frame, a malformed list and a pair named twice are refused by name, and so is `--slot`/`--hide` beside it — **§8.5** |
+| `--seam` | `render` only: `<slot>:<slot>[,<slot>:<slot>…]` — also read, for each pair, where the two drawings **stop meeting**, and write a `seam.json` into each frame directory: per pair, the frames with a **gap** (background inside the joint, where the two covered together at the setup pose) and the frames with a **ghost** (the overlap band of one showing where, from its partner's point of view, nothing was drawn), each with its cell count, area and world box, and as runs of frames with their times. One printed line per pair; a pair whose drawings share no cell at the setup pose is a **SKIP**. A reading, not a gate: the exit status never moves. Every other file is byte for byte what the render writes without it. An unknown slot, a slot with itself, a slot that draws on no frame, a malformed list and a pair named twice in either order are refused by name, and so is `--slot`/`--hide` beside it — **§8.8** |
 | `--angle-range` | `render` only: `<bone>:<relative-to>[,<bone>:<relative-to>…]` — also read, for each pair, the range of the first bone's world direction against the second's over each set's frames, and print one line per pair per set: the lowest and the highest angle in degrees, the span, and the frame each was first reached on. A reading, not a gate: nothing is written, and every file is the bytes the render writes without it. An unknown bone (with the bones there are), a bone against itself, a malformed list and a pair named twice are refused by name, and so is a bone with no direction on a frame — **§8.7** |
 | `--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** |
@@ -1130,6 +1136,7 @@ bun cli.ts render   --candidate path/to/spine --slot <name,…> | --hide <name,
 bun cli.ts render   --candidate path/to/spine --geometry   # + geometry.json per set: the numbers the frames were drawn from
 bun cli.ts render   --candidate path/to/spine --folds      # + folds.json per set: which mesh triangles turn over, and when
 bun cli.ts render   --candidate path/to/spine --pass-through skirt:leg   # + pass-through.json: where a cloth goes through a leg
+bun cli.ts render   --candidate path/to/spine --seam thigh:shin   # + seam.json: where two slots that meet open a gap or show a ghost
 bun cli.ts render   --candidate path/to/spine --angle-range tail:hip   # how far a bone turns against another, per animation
 bun cli.ts render   --candidate path/to/spine --viewport-from render/   # an earlier render's grid: two builds, one pixel grid
 bun cli.ts preview  --candidate path/to/spine [--candidate path/to/another …] [--animation …] [--out preview.html]
@@ -1235,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**
@@ -4518,6 +4529,17 @@ rest; a frame parent scaled unevenly, sheared or reflected, or such a bone
 between two links; a link below a bone a later stop generates; a `from` bone in
 the angles' path.
 
+On the first link that bound is |rest| + `outward`, where rest is the angle
+between the direction the link hangs in and the aim from its root at
+`<chain>_touch`, so where the point sits decides it as much as `outward` does.
+The refusal names the link, its root's world position and hang, the point's world
+position, rest, the end and the sum, and says what to move: `<chain>_touch` to
+within 180° − `outward` of the link's hang direction — below the root, for a link
+that hangs straight down and `outward` up to 90° — or `outward` down to
+180° − |rest|. A leg that rises from behind the cloth, as on a prone figure,
+runs its local +x up the screen, so `at` at its far end lands above the chain's
+root; put it at the knee, below the root (`LG34`).
+
 The stop decides nothing about *when* — it is what the object can do. Read it
 with `render --pass-through <cloth>:<leg>` (§8.5) on the motion that swung
 through before.
@@ -6825,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
@@ -6901,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. |
@@ -7352,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>Here the values named in the message include: “inward”, “outward”. | Adjust the printed limits so the local clamp bounds stay within its supported angular range. |
+| <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_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. |
@@ -8478,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
@@ -8696,6 +8754,131 @@ one scaled to nothing — named with the frame.
 **A reading, not a gate.** Whether a range is too wide is yours; §4.6 says which
 values move it.
 
+### 8.8 Where two slots stop meeting — `render --seam`
+
+A cut rig can tear in motion: two pieces painted to overlap at a joint pull apart
+and the background shows between them, or one swings clear of the piece it was
+tucked under and the overlap it carries shows where nothing was. Both pass every
+assertion and every check, and either can be intended — so `--seam` names the
+frames and decides nothing. On the selftest's probe (`pass_through_probe`,
+`fixtures/public.ts`: a skirt whose hip swings 30° and back over a leg that hangs
+inside it, and a second copy of the leg on the same bone):
+
+```bash
+bun cli.ts render --candidate path/to/spine --animation swing --seam skirt:leg,leg_front:leg [--skin …] [--fps 12]
+# rigc render
+#   ..    swing            25 frame(s), 2.000s + contact.png + seam.json (1 of 2 pair(s) open) -> …/swing
+#   ..    seam     "swing": seam "skirt" | "leg" opens on 23 of 25 frame(s) read [1-23] at 12 fps, max 1606 px — gap on 13 frame(s) [6-18], worst frame 12 (t=1.0000s): 616 px (616.00 units² at 1.0000 units a px) in world box x [-7.00, 19.00] y [105.99, 196.00] (26.00 × 90.00); ghost on 23 frame(s) [1-23], worst frame 12 (t=1.0000s): 1606 px (1606.00 units² at 1.0000 units a px) in world box x [-27.00, 41.00] y [104.99, 198.00] (68.00 × 93.00)
+#   ..    seam     "swing": seam "leg_front" | "leg" stays closed on all 25 frame(s) read at 12 fps — no gap, no ghost
+```
+
+The skirt swinging off the leg opens background between the leg's right edge and
+the skirt's swung side (the gap, widest at the top of the swing), and uncovers the
+top of the leg the skirt hid at rest (the ghost). The two copies of the leg move
+on one bone and never open. A pair with nothing to read says so —
+`seam "a" | "b": SKIP — the two drawings share no cell at the setup pose on any of
+the N frame(s) both draw, so there is no band to read` — and a closed pair says
+`stays closed on all N frame(s) read`; the two are never the same line.
+
+**The frame of reference.** A seam is not read in the world: a limb that swings
+moves both of its pieces from where they were at the setup pose, and that is
+motion, not a tear. It is read **from each piece's own point of view**. A world
+point of a frame is carried back into a piece's setup pose by the affine map of
+that piece's triangle holding it as the frame poses it; outside the piece's mesh,
+by the map of the triangle it is least outside of (the largest smallest
+barycentric weight, the lowest index on a tie) — exact for a region and for any
+mesh one bone moves, the nearest affine piece of a skinned one. Two pieces that
+move together carry a point back to one place, so a pair moved whole reads nothing.
+
+**Every number, and where it comes from.** Nothing here is a threshold the rig
+did not declare; each figure is the posed vertices (`--geometry`'s), the rest
+table's vertices, and the atlas alpha:
+
+- **The cell** is one texel of the coarser of the two drawings at the setup pose,
+  in world units — the step `--pass-through` steps by (§8.5) — on multiples of it
+  from the world origin. `px` counts cells: on art drawn one texel to a unit, a
+  cell is a world unit and a px is a pixel of the art.
+- **Drawn** is the renderer painting a cell's centre at **128 of 255** or more —
+  the half-opacity line `--pass-through` draws outlines at, the frame's tint
+  included, the setup pose drawn at the same tint (so a slot faded out is not a
+  tear: it is faded in both). No other alpha enters.
+- **The band** is the cells both drawings draw at the setup pose — where the two
+  were painted to overlap. It has **no width of its own**: it is the overlap the
+  art states, dilated by nothing. A frame whose band is empty is not read; a pair
+  whose band is empty on every frame both draw is a SKIP.
+- **gap** — a cell inside the convex hull of the band's cell centres, carried to
+  the frame by both pieces (the region the joint occupies now, as both place it),
+  that neither piece draws at the frame, and that at least one piece, carrying it
+  back, finds drawn by either drawing at the setup pose: the two no longer cover
+  what they covered together. The hull is the joint's own extent, which is what
+  keeps a piece's far end swinging away from reading as a tear; the rest test is
+  what keeps a band that is concave at the setup pose from reading its own notch.
+- **ghost** — a cell one piece draws at the frame and the other does not, which
+  the drawing piece, carrying it back, lands in the band, and which the other,
+  carrying it back, finds neither drawing at at the setup pose: the overlap swung
+  clear of its partner.
+
+Draw order does not enter: a cell is covered or bare whichever piece is in front.
+
+**Its reach, stated.** A piece folded right back over its partner carries the band
+across the region it vacated, so a hull that wide reads the vacated cells its
+partner's view still finds drawn. And no size is too small to print: on
+`gallery/walk`, built as its README says, `--seam thigh_f:shin_f,arm_f:hand_f`
+reads gaps of 1–2 px on 5 of the 12 frames at the knee and of 1 px on 2 at the
+wrist — the wrist's, drawn at 20 pixels a unit, is the V where the two outlines
+meet at an angle, one cell deep. Whether that is a tear is yours.
+
+**The file.** `seam.json`, `rigc-seam/1`, beside each set's frames — the contract
+a consumer reads it by. Every unit is in this table; the file's own `reading`
+block carries the definitions above in words.
+
+| Field | Type | Unit | Meaning |
+| --- | --- | --- | --- |
+| `spec` | string | — | `"rigc-seam/1"` |
+| `animation` | string or `null` | — | the set's animation; `null` for a skeleton with none (its one frame is the setup pose) |
+| `skin` | string | — | the skin asked for; **absent** when none was |
+| `fps` | number | frames per second | the rate the set was sampled at |
+| `reading` | object | — | `read`, `cell`, `drawn`, `band`, `carried`, `gap`, `ghost`, `box`, `status`: the definitions, in words |
+| `pairs[]` | array | — | one per pair, in the flag's order |
+| `pairs[].a`, `pairs[].b` | string | — | the two slots, as the flag names them |
+| `pairs[].drawn` | integer | frames | frames on which both slots draw |
+| `pairs[].banded` | integer | frames | of those, frames whose two drawings share a cell at the setup pose — the frames read |
+| `pairs[].status` | `"read"` or `"skip"` | — | `skip` when `banded` is 0: nothing measured, which is **not** a seam that held |
+| `pairs[].opens` | integer[] | frame indices | every frame with a gap or a ghost, ascending |
+| `pairs[].maxPx` | integer | px (cells) | the most cells of either kind on any frame; 0 when none opens |
+| `pairs[].gap`, `pairs[].ghost` | object | — | one per kind, each `{ frames, spans, worst }` |
+| `<kind>.frames[]` | hit[] | — | only the frames with a cell of that kind, in frame order |
+| `<kind>.spans[]` | array | — | `<kind>.frames` as runs of consecutive indices: `{ frames: [first, last], times: [first, last], maxPx }` — frame indices, seconds, px |
+| `<kind>.worst` | hit or `null` | — | the frame with the most cells, the earliest on a tie; `null` when none |
+| hit `index` | integer | frame index | the frame — `f<index>.png`, zero-padded |
+| hit `time` | number | seconds | the frame's time |
+| hit `px` | integer | px (cells) | cells of that kind on the frame |
+| hit `cell` | number | world units | a cell's side |
+| hit `area` | number | world units² | `px × cell²` |
+| hit `box` | `[minX, minY, maxX, maxY]` | world units, y up | the counted cells' whole squares, in Spine world |
+
+A downstream warning is a projection of this file and needs nothing re-measured:
+one span of one kind is `{ pair: "<a>|<b>", frames: span.frames, times:
+span.times, maxPx: span.maxPx, kind }`, and one pair over one animation is
+`opens.length` frame(s) `[opens]`, max `maxPx` px — with `status: "skip"` the case
+to say SKIP for.
+
+**Refused, nothing written:** a slot the skeleton does not have (with the slots it
+does), an entry without exactly one `:`, an empty entry or name, a slot paired with
+itself (a seam is between two drawings), a pair named twice in either order (the
+reading is symmetric, so `b:a` is `a:b` again), a slot that draws on no frame of
+the sets drawn, a slot a clip cuts (its drawing is no longer its attachment's, so
+it cannot be carried back), and `--slot`/`--hide` beside the flag, for
+`--pass-through`'s reason.
+
+**Nothing else moves.** The PNGs, `contact.png`, `frames.json` and `geometry.json`
+are byte for byte what the render writes without the flag, both posers write the
+same file, and two runs write the same bytes (the selftest's `seam` suite).
+
+**A reading, not a gate.** It never changes the exit status, whatever it finds. To
+look at a frame it names, draw that set over the box it printed:
+`render --animation <name> --viewport <x,y,w,h> --max 400`.
+
 ---
 
 ## 9. Checking against the frames — `rigc check`
@@ -11522,6 +11705,7 @@ pixel (`IN09`).
 | What does this bone move? | `--show art,mesh,weights:<bone> --dim` | the bone's weight over every region and mesh it moves, as a heat: a pixel whose centre lies in a triangle is painted the ramp's colour at the blend of its corners' weights — blue near 0, yellow at 0.5, red at 1 (the stops are in the legend) — and a weight of 0 is not painted, so the art shows where the bone does not reach. A region and an unweighted mesh are moved whole by their slot's bone. The weights are read off `skeleton.json`, the file both posers skin from; a bone that weights nothing paints nothing and the run says so on a line of its own |
 | Does this part's edge follow that bone? | `--show art,weights:<bone>,mesh --overlay-slot <part> --zoom slot:<part>` | the part's own triangles and the bone's weight over them alone, over the whole painting. Where slots stack — a neck under the face, the hair, a collar — every mesh crossing the box is drawn and the heat is the union of every slot the bone moves, so the part's edge has no pixel of its own until the others are left out. The legend's `meshes[]` gives the part's weight for the bone at every vertex, so "does the top row follow the head" is read as numbers as well as colour |
 | Is this rig's density where its motion is? | `--show art,density --dim` | each region and mesh filled by its **ratio** — its triangles per world unit² over the figure's — on one ramp, log-scaled and centred on 1×: grey is as dense as the figure, pink to magenta denser (4×, 16×), light to dark green sparser (1/4×, 1/16×), clamped past the end stops (the stops are in the legend). A part's area is its posed mesh's own, the sum of its triangles' areas at the pose drawn, not the image's box; a region is two triangles over its quad. Where parts overlap the pixel is the part drawn last, as in the art, so a part under others is read with `--overlay-slot <part>`. The figure's totals are always over every slot the pose shows — the filter picks what is drawn and listed, never what the figure is — and the legend's `density` gives each slot's attachment, kind, vertices, triangles, hull, area, triangles per area, ratio and the bones it is weighted to, in draw order. A measurement, not a verdict: no bar is drawn, and `A13_MESH_BUDGET` stays the one gate on counts |
+| Does a joint tear in this animation? | `render --seam <a>:<b> --animation <name>` (§8.8) | One line per pair: the frames where background opens inside the joint (gap) or the overlap band of one piece shows past its partner (ghost), with the worst frame's cell count and world box; `seam.json` carries every frame and its time, and the runs of frames. A pair whose drawings never overlap is a SKIP, said by name. A reading, not a verdict — the exit status never moves |
 | Does anything fold in this animation? | `render --folds --animation <name>` (§8.3), then `inspect --show art,folds,mesh --animation <name> --at <the worst frame's time> --zoom folds` | `render --folds` prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count, which triangles, their world box at that frame and their setup-pose area. The view fills those triangles at the pose drawn — every pixel whose centre a folded triangle holds — in the colour the legend's `folds` states, and the legend's `folds[]` names, per mesh, the folded triangles by index with the same box and area, and the setup pose's degenerate and inverted ones, which are never counted. A fold is usually a sliver a few units across, invisible in a picture of the whole mesh: `--zoom folds` frames the picture to the folded triangles' box. A thin sliver still needs pixels — raise `--max` when the fill is a line. A reading, not a verdict |
 | How is this part triangulated? | `--show art,mesh,hull --zoom slot:<slot>` | each mesh's triangle edges, and over them its hull — vertex 0 to 1 to … to `hull − 1` and back. Regions are not drawn: a region is not a mesh. The legend lists every vertex in world units and in pixels |
 | Which is drawn over which? | `--show art,slots` | each slot that shows a region or mesh numbered by its place in the draw order **at the pose drawn** (0 is drawn first), on a white box at the centre of its attachment's box — so a `drawOrder` key (§4.7) shows from the first frame `render` draws it on |

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.59.0",
+  "version": "2.61.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": {