@rig-c/core 2.80.0 → 2.81.1

package/NOTICE.md

@@ -8,8 +8,8 @@ Copyright (c) 2013-2025 Esoteric Software LLC, licensed under the
 [Spine Runtimes License Agreement](https://esotericsoftware.com/spine-runtimes-license),
 as a **development dependency**: a clone and CI install it, and every Spine file
 `rigc build` writes there is read back through it before it is written. **The
-published package does not carry it** — an install of `rig-c` (or of
-`spine-rigc`, the same files under the name the package first shipped as) has no
+published package does not carry it** — an install of `@rig-c/core` (or of `rig-c` or
+`spine-rigc`, the same product files under the convenience or legacy name) has no
 Spine runtime in it unless one is installed beside it, and then the same `rigc`
 uses it.
 

package/README.md

@@ -223,7 +223,7 @@ candidate chooser (`loadCandidate`, `throughPoser`), setup and animation sampler
 `rasterisePiece`, `renderFrame`), with their argument/result types and named
 failures. It loads without the optional Spine runtime; a Spine input requires
 explicitly loading `rig-c/render`, whose eager runtime dependency is unchanged.
-The promised scope and planned first minor release are in
+The promised scope and the first release (2.69.0) are in
 [RELEASING.md, The import surface](https://github.com/rig-c/core/blob/main/RELEASING.md#the-import-surface);
 [AUTHORING §0.5](docs/AUTHORING.md#05-reading-a-build-from-code) shows the call chain.
 
@@ -647,7 +647,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/`, one directory per set: `<anim>@<fps>fps/` rather than `<anim>/` at any rate but the default — `--fps 24` writes `<anim>@24fps/`, and the default 12 writes `<anim>/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid. `--folds` adds a `folds.json` per set and prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count and which triangles, their world box and their setup-pose area. `--pass-through <cloth>:<leg>` adds a `pass-through.json` per set and prints the frames where a cloth drawn over a leg has its side inside the leg's drawn outline, with the depth and the world box — a reading, not a gate. `--seam <slot>:<slot>` adds a `seam.json` per set and prints, per pair, the frames where two slots that meet open background inside the joint (a gap) or show the overlap band of one past the other (a ghost), with the worst frame's cell count and world box; `ghostA` and `ghostB` partition the same ghost by which named pair member drew it, each with its own frames, spans and worst; `gapOpen` and `gapCovered` partition `gap` by zero versus positive rendered alpha from the whole skeleton, including faint and clipped drawings ([AUTHORING §8.8](docs/AUTHORING.md#88-where-two-slots-stop-meeting--render---seam)) — a reading, not a gate; the exit status never moves. `--overlaps` adds an `overlaps.json` per set and prints one `OVERLAP "<under>" under "<over>"` line per pair of slots where the one drawn later covers the earlier one and the motion moves it — the frames, and the most pixels covered and the frame of them — with an outline plate per covered frame; the render reports what was drawn, and the draw-order key is the author's remedy — a reading, not a gate. `--angle-range <bone>:<relative-to>` prints how far one bone turns against another over each set: the lowest and highest angle and the frames they fall on — a reading, not a gate. `--viewport <x,y,w,h>` or `--viewport-from <frames.json>` draws over a given box instead of a fitted one, so two builds land on one pixel grid; a slot that reaches past it is named by set and frame, and `frames.json` records it. `--environment <schedule.json>` draws the rig under the wind and gravity its physics answers, in time — the same frames on the core and on spine-core; an inspection of the response the rig states, not a scene. `--sheet [--sheet-format json-hash] [--page-edges pot\|free]` also packs each set's straight-alpha transparent frames into `sheet.png` + `sheet.json` (TexturePacker JSON Hash with a shared world-origin `anchor` and `2`-px clamped edge extrusion, verified through `pixi.js@8.22.0` and `phaser@3.90.0` by `tools/sheet_readers.ts`) and `sheet-manifest.json` (`rigc-sheet/1`), leaving diagnostic `f####.png` and `contact.png` unchanged ([AUTHORING §8.10](docs/AUTHORING.md#810-sprite-sheets-from-a-render--render---sheet)) — a self-contained sprite object per animation set; when animations play and how a scene is composed remains the consumer's |
+| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`, one directory per set: `<anim>@<fps>fps/` rather than `<anim>/` at any rate but the default — `--fps 24` writes `<anim>@24fps/`, and the default 12 writes `<anim>/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid. `--folds` adds a `folds.json` per set and prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count and which triangles, their world box and their setup-pose area. `--pass-through <cloth>:<leg>` adds a `pass-through.json` per set and prints the frames where a cloth drawn over a leg has its side inside the leg's drawn outline, with the depth and the world box — a reading, not a gate. `--seam <slot>:<slot>` adds a `seam.json` per set and prints, per pair, the frames where two slots that meet open background inside the joint (a gap) or show the overlap band of one past the other (a ghost), with the worst frame's cell count and world box; `ghostA` and `ghostB` partition the same ghost by which named pair member drew it, each with its own frames, spans and worst; `gapOpen` and `gapCovered` partition `gap` by zero versus positive rendered alpha from the whole skeleton, including faint and clipped drawings ([AUTHORING §8.8](docs/AUTHORING.md#88-where-two-slots-stop-meeting--render---seam)) — a reading, not a gate; the exit status never moves. `--overlaps` adds an `overlaps.json` per set and prints one `OVERLAP "<under>" under "<over>"` line per pair of slots where the one drawn later covers the earlier one and the motion moves it — the frames, and the most pixels covered and the frame of them — with an outline plate per covered frame; the render reports what was drawn, and the draw-order key is the author's remedy — a reading, not a gate. `--extremes` adds `extremes.json` and a native six-panel `extremes.png` (setup, geometry-pair min/max and three premultiplied RGBA diffs with a legend), plus one `EXTREMES` line per set. Per-channel minima/maxima and the farthest original-vertex geometry pair are distinct readings; valid channel extrema survive a geometry/image SKIP, with channel refusals reported separately; still or uncomparable geometry reports a named SKIP without changing render exit status. Look at min, max and diff before a person does ([AUTHORING §8.11](docs/AUTHORING.md#811-min-max-and-diff-before-a-person-looks--render---extremes)). `--angle-range <bone>:<relative-to>` prints how far one bone turns against another over each set: the lowest and highest angle and the frames they fall on — a reading, not a gate. `--viewport <x,y,w,h>` or `--viewport-from <frames.json>` draws over a given box instead of a fitted one, so two builds land on one pixel grid; a slot that reaches past it is named by set and frame, and `frames.json` records it. `--environment <schedule.json>` draws the rig under the wind and gravity its physics answers, in time — the same frames on the core and on spine-core; an inspection of the response the rig states, not a scene. `--sheet [--sheet-format json-hash] [--page-edges pot\|free]` also packs each set's straight-alpha transparent frames into `sheet.png` + `sheet.json` (TexturePacker JSON Hash with a shared world-origin `anchor` and `2`-px clamped edge extrusion, verified through `pixi.js@8.22.0` and `phaser@3.90.0` by `tools/sheet_readers.ts`) and `sheet-manifest.json` (`rigc-sheet/1`), leaving diagnostic `f####.png` and `contact.png` unchanged ([AUTHORING §8.10](docs/AUTHORING.md#810-sprite-sheets-from-a-render--render---sheet)) — a self-contained sprite object per animation set; when animations play and how a scene is composed remains the consumer's |
 | `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 |

package/docs/AUTHORING.md

@@ -146,6 +146,9 @@ bun cli.ts check \
 # read the table → fix the spec → build again → check again
 #   ↳ read its per-frame column before its MAE — §9.2
 
+# Before a person looks: inspect each motion's min, max and diff (§8.11).
+bun cli.ts render --candidate path/to/spine --extremes --out frames/
+
 # …and if nobody gave you frames, LOOK at it instead — neither needs a reference:
 bun cli.ts render  --candidate path/to/spine    # PNG frames + a contact sheet grid
 bun cli.ts preview --candidate path/to/spine    # one .html that plays it in Spine's own player
@@ -277,8 +280,13 @@ What the flags mean:
 | `--report` | `build` and `repack`: also write the gate's report as a JSON document (`build-report/1`) to this file — every gate's `PASS`, `SKIP` and `FAIL` rows, its summary figures and stats line, which supplier judged it, and every `pack:` line's figures. Written when the command writes `--out` and when a gate is red, before the exit; a file already at the path is removed first, so a compile error or a refused repack leaves none. Never inside `--out`, refused by name. The printed lines are byte-identical with it and without it — **§5.3** |
 | `--candidate` | `check`, `bench`, `render`, `inspect`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. A directory holding no `skeleton.json`, or a path with nothing at it, is refused `nothing at <path>`, exit 2, nothing written, by every command that takes a build — `validate <dir>` and a directory given to `diff` included (`RC27`). `--atlas <path>` names the atlas when it does not sit beside the skeleton. On `render` and `check` a rigc build whose `skeleton.model.json` is `rigc-compiled/3` or `/2` needs no atlas at all: with no `--atlas` and no atlas beside it, it is drawn from the document's `pages`, the same frames, geometry and figures as with it, and the `atlas` line says `— not there`. An atlas that is there is still read, and held to `pages`: one that differs (edited after the build) is drawn through spine-core, and the `poser` line names the first difference. A build drawn through an atlas that is not there — a `rigc-compiled/1` document, or a build the core refuses — is refused `nothing at <the atlas>: … is drawn through its atlas (<why>)`, exit 2, nothing written; a Spine export without its atlas is refused `nothing at <the atlas>` as it always was. A directory whose files are not one build — a `skeleton.json` or a `skeleton.atlas` from another build beside this one's `skeleton.model.json` — is drawn through spine-core where the runtime can load the pair, the `poser` line naming the two digests or the atlas's first difference; where it cannot, it is refused `<skeleton> does not load against <the atlas>: spine-core draws this pair (<the poser line's why>) and could not resolve it — "<the runtime's own words>". <dir> is not one build: …`, exit 2, nothing written (`RC18`) — another build's skeleton beside this build's atlas typically ends `"Region not found in atlas: <region> (attachment: <name>)"`. Rebuild, or put the build's own three files back beside each other. A Spine export beside an atlas it was not exported with is refused in the same words, ending `The skeleton and the atlas are not one pair`. An atlas copied from another build's directory usually stops earlier, at its pages — their paths are relative to the directory it was written in — and is refused naming the first one: `nothing at <the page>: <the atlas> names it as a page, and spine-core draws this pair through that atlas (<why>). … <dir> is not one build: …`, exit 2, nothing written (`RC18`); an export whose atlas names a page that is not there is refused the same way, ending `and the page has to be there`. A build moved or copied whole away from the directory it was built in stops at the same place, on either poser, and is refused naming the page and the file that names it: `nothing at <the page>: <the skeleton.model.json> names it as a page, and the core draws this build from it. A page path is relative to the build's directory, so a build moved or copied away from the directory it was built in names pages that are not here — build it again where it is, or build it with --copy-images, which writes its pages beside it` (under `--poser spine`, `<the atlas> names it as a page, and spine-core draws this pair through that atlas (--poser spine)` with the same ending), exit 2, nothing written (`RC21`); only where the core refused the files does a page refusal say the directory is not one build. `bench --bones` and `rigc bonedist` — on its `--candidate` and on its `--reference` — refuse a pair the runtime cannot load in the words above with `spine-core poses this pair (bonedist's candidate: …)` or `(bonedist's reference: …)`, exit 2, nothing written (`RC20`); they read no page image, so a build whose pages are elsewhere is measured as it is in place. A `skeleton.json` that is not JSON is refused `rigc: cannot read <the file>: <the parser's words> (line N, column N)`, exit 2, by `render`, `check`, `bench` and `bonedist` as by every other command that reads one (`RC22`). With the atlas gone, `check` on a `rigc-compiled/3` build reads its pages' `scale:` lines off the document, so its texture note and `check.json`'s `textureFrom.candidateScales` are what they are with the atlas; on a `/2` build its texture note says whether the atlas declares a `scale:` line is not read (that document does not state one), and `candidateScales` is `null` (`RC13`). **`vote` and `preview` take it more than once**: `vote` 2–4 times, one per pane, labelled A, B, C, D in the order given; `preview` any number of times, one pane per candidate in the order given, each headed by its path and its gate line, and the same skeleton twice (a directory and its `skeleton.json` are one) is refused by name. `--atlas` goes with one candidate only. Everywhere else a repeat is a typo and is refused |
 | `--animation` | `render`, `preview` and `vote` only: which animation to show. The default is **every** one for `render`, the **first** for `preview` (each candidate's own first, with several), and for `vote` the first of candidate A. A name the skeleton does not have is refused, with the ones it does have listed — and for `vote` and a several-candidate `preview`, so is a name that only *some* candidates have, naming the one that lacks it |
+| `--slot` | On `render`: draw only these comma-separated slot names, in draw order, on the **same grid** as the whole rig (the viewport still fits every slot). Default: all slots. Unknown names or art available only in another skin are refused by name. `frames.json` records the subset, and `check` refuses it as a reference. `split` uses this flag to name the mesh to separate — **§3.4.11** |
+| `--hide` | On `render`: draw every slot except these comma-separated names, on the same grid and with the same subset record and refusals as `--slot`. Default: hide none. Refused with `--slot` |
+| `--fps` | On `render`: frames per second to sample (default `12`, finite and at least `1`); a non-default rate writes `<anim>@<fps>fps/`, while `12` writes `<anim>/`. `bonedist` samples both skeletons at this rate (default `12`); `inspect` uses it for the `--at` grid (default `12`, **§13**); `check` uses it only for a frame set with no `frames.json` sidecar (**§9**) |
+| `--max` | `render` and `inspect`: the longest side of the frame in pixels (default `256`, finite and at least `16`). On `render`, refused with `--viewport-from`, which already fixes the pixel size — **§8.6**, **§13** |
 | `--show`, `--dim`, `--at`, `--zoom` | `inspect` only — what it draws, whether the art is faded, which times of `--animation` it poses and the bone, slot or folds it frames to; §13 says each, with the refusals |
 | `--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** |
+| `--extremes` | `render` only: add `extremes.json` and an `EXTREMES` line per set; a moving set with comparable geometry and readable images also gets a native six-panel `extremes.png`: setup, geometry-pair min/max and three premultiplied RGBA diffs with a legend. Per-channel extrema are independent of that geometry pair; valid channels survive geometry/image SKIPs, and channel refusals are named separately. Still or uncomparable geometry is a named SKIP, with no invented pair or PNG; observation failures do not change a successful render's exit status. Supports `--slot`/`--hide` on both posers, on the whole rig's viewport. Without the flag, no extremes observations are added — **§8.11** |
 | `--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** |
@@ -1643,9 +1651,9 @@ written`, followed by `rigc repack: nothing was written to <out>; the work direc
 ### 0.5 Reading a build from code
 
 The named `rig-c/render-shared` entry promises the official renderer reads for
-checked consumers (issue #1561). It is planned for the next minor, 2.69.0; wait
-for the measured release before using `>=2.69.0 <3.0.0`. It requires Bun and the
-candidate's real files, but imports no optional Spine runtime. The existing
+checked consumers (issue #1561), available since 2.69.0; pin
+`>=2.69.0 <3.0.0`. It requires Bun and the candidate's real files, but imports
+no optional Spine runtime. The existing
 `rig-c/render` entry still eagerly imports that runtime.
 
 ```ts
@@ -9464,6 +9472,88 @@ bounds plus its `2`-px border on each side exceed `2048` (`w + 4 > 2048` or
 
 ---
 
+### 8.11 Min, max and diff before a person looks — `render --extremes`
+
+```sh
+bun cli.ts render --candidate path/to/build --extremes [--animation turn] [--fps 12] [--max 256]
+```
+
+Look at **min · max · diff before a person does**. A baked line carried by a
+moving part can be obvious in the difference image while a seam metric misses
+it. This flag makes the picture; it does not classify tears or ghosts and does
+not change the seam metric.
+
+Each set gets `extremes.json` and one `EXTREMES` line. A moving set also gets
+`extremes.png`, with six panels from left to right:
+**setup | min | max | abs(max-min) | abs(min-setup) | abs(max-setup)**.
+Every panel has the render's native viewport width, height and scale; the legend
+is appended below, wrapping its text without shrinking any picture. The three
+pose panels are transparent renders. Each diff pixel is opaque greyscale on
+black, with luminance
+`round(max(abs(Ra*Aa/255-Rb*Ab/255), abs(Ga*Aa/255-Gb*Ab/255), abs(Ba*Aa/255-Bb*Ab/255), abs(Aa-Ab)))`.
+Alpha participates; RGB behind alpha zero contributes zero. There is no contrast
+amplification or additional scaling.
+
+The JSON keeps two different observations separate:
+
+- **`channels`**: every sampled local bone rotation, componentwise translation,
+  signed scale and shear, deform offset coordinate (per influence for weighted
+  meshes), and each applied slider's mapped time, with its minimum and maximum,
+  exact frame timestamp and selection reason. Held bone components are included
+  explicitly. A slider applies its own mapping; its time is read from the pose,
+  rather than guessed from elapsed time. A mix-zero slider or one whose driver
+  bone is inactive did not apply a mapping and contributes no stale time.
+- **`geometryPair`**: exhaustively compare frame pairs on the set's own grid.
+  For a pair, measure the Euclidean world distance of each corresponding original
+  attachment vertex with the shared deterministic `sqrt(dx*dx+dy*dy)` length
+  helper, and take the greatest. Select the pair with the greatest
+  such distance. Record that maximum in world units and its slot, attachment and
+  vertex witness. `min` and `max` in the picture mean the earlier and later
+  frame of **this pair**; they are not a pose combining every channel's minima
+  or maxima. The channel table can choose entirely different frames.
+
+`channelStatus` (`READ`, `PARTIAL` or `SKIP`) and `channelRefusals` describe
+channel validity separately from the picture's `status` and `reason`. A geometry
+correspondence failure or failed optional image read **preserves every valid
+independent channel extremum**; an image failure also retains a valid geometry
+pair if one was measured. A non-finite scalar refuses only that channel. If a
+whole frame's channel reader failed, extrema on the full grid are unknown and
+the channel table is a named SKIP while geometry can still be read.
+
+Deform samples are offsets from their original source, read only where that
+posed attachment supplies the coordinate. A deform path names slot, attachment
+display name and coordinate. If two different original sources share that path,
+its extrema cannot be represented unambiguously under the name: refuse that
+series by name in `channelRefusals`, preserving unrelated bone, slider and other
+deform series. Missing original deform-source identity is refused the same way;
+never merge unrelated coordinates because their names happen to match.
+
+Ties keep the earliest frame for a channel and the earliest ordered frame pair
+for geometry, then the first attachment identity in UTF-16 code-unit order and
+vertex index. Times are copied from sampled frames. No continuous-time extremum
+between grid points is claimed. A single frame or a set with no selected vertex
+motion has `status: "SKIP"`, a named reason and no invented pair or PNG. Channels
+still describe the samples, including any local change leaving geometry still.
+
+Both posers support `--slot` and `--hide`: resolve the flags normally, then filter
+original attachment geometry by those slot names. The viewport stays the whole
+rig's. This reads original vertices **before clipping, occlusion and tint alpha**;
+re-clipped triangles never supply cross-frame indices. An attachment switch,
+missing attachment or changed vertex count cannot establish correspondence.
+The flag also checks the actual original source identity: two different
+attachments can have the same display name and vertex count. That identity is
+kept outside serialized geometry so existing geometry files are unchanged.
+If the optional source identity was not captured, correspondence is unavailable
+and is refused by name too. When correspondence cannot be established, the
+set writes a named `EXTREMES_OBSERVATION_REFUSED` SKIP instead of comparing
+unrelated indices. Optional image failures preserve the independently collected
+channels. Channel failures are reported separately as described above.
+**Observation failures do not change a successful render's exit status.** Invalid CLI arguments retain their normal refusal semantics.
+
+Without `--extremes` the existing frames and files are unchanged. The flag adds
+its observations alongside them. A SKIP removes a stale `extremes.png` for that
+set so an earlier pair cannot masquerade as the current reading.
+
 ## 9. Checking against the frames — `rigc check`
 
 ```bash

package/docs/FACE.md

@@ -545,9 +545,9 @@ renderer must never idle-skip a mesh. Keying the pivot one link up satisfies it,
 and **the rig that satisfies the assertion is the better rig anyway.**
 
 ⚠️ **A15 assumes the meshes are mostly static, and that assumption is the rule's
-whole premise.** The `spine-html` renderer skips redrawing a mesh nothing moved, so a
-face whose `idle` breathes through one pivot keeps every mesh under it cheap only if
-nothing keys the meshes' own bones. The rule reads bone **names**: keying `headroll`
+whole premise.** The `@rig-c/play` renderer (the `rig-play` profile's player) skips
+redrawing a mesh nothing moved, so a face whose `idle` breathes through one pivot
+keeps every mesh under it cheap only if nothing keys the meshes' own bones. The rule reads bone **names**: keying `headroll`
 passes it, and `head`'s mesh still moves, because a child's world transform is
 composed from its parent's — so pivoting is right here for the anatomical reason
 above, not because it stops a redraw. A **painting rig** is the genre where the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.80.0",
+  "version": "2.81.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/skills/rigc-face/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc-face
 description: Author a face on plain Spine data with rigc — a blink, a gaze shift, a breathing portrait and a head turn a few degrees off axis, built from deform timelines and per-part parallax. Use when the request is a talking or living portrait, a standing character, an expression or a head turn, such as "rig this face", "make the portrait blink and look around" or "turn the head". Not for Live2D file conversion, cutting a face illustration into parts, or VTuber-style real-time face tracking.
 license: MIT
-compatibility: Requires Bun 1.4 or later and the npm package rig-c.
+compatibility: Requires Bun 1.4 or later and the npm package @rig-c/core (rig-c is the convenience name).
 ---
 
 # Face — a turn, a gaze and a blink
@@ -63,7 +63,7 @@ differential audit and the three limits it does not lift.
    rather than this closed form, and [INGEST.md](https://github.com/rig-c/core/blob/main/docs/INGEST.md) if the head
    arrived as a compiled skeleton.
 
-Every guide linked here is in the installed package at `node_modules/rig-c/docs/`,
+Every guide linked here is in the installed package at `node_modules/@rig-c/core/docs/`,
 which is the copy that matches the rigc you run; the links go to the repository's
 `main`. Inside the Claude Code plugin the same files are at `${CLAUDE_PLUGIN_ROOT}/docs/`.
 

package/skills/rigc-ingest/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc-ingest
 description: Work with a Spine skeleton.json somebody else authored — exported from the Spine editor or another tool — using rigc. Read and validate it, understand a complaint rigc raised about it, decompile it into rigc specs with `rigc ingest`, normalise, re-pivot or rename it, and extend it with an animation it does not have. Use when the input is an existing skeleton.json with its .atlas and page images rather than loose part PNGs. Not for Live2D file conversion or runtime tracking.
 license: MIT
-compatibility: Requires Bun 1.4 or later and the npm package rig-c.
+compatibility: Requires Bun 1.4 or later and the npm package @rig-c/core (rig-c is the convenience name).
 ---
 
 # Ingest — a skeleton you did not author
@@ -81,7 +81,7 @@ thing to reach for; transcription by hand is what you fall back on for a constru
 3. Then [RIGGING.md](https://github.com/rig-c/core/blob/main/docs/RIGGING.md) for why the re-pivot edit has the shape
    it has, and [MOTION.md](https://github.com/rig-c/core/blob/main/docs/MOTION.md) for the animation you are adding.
 
-Every guide linked here is in the installed package at `node_modules/rig-c/docs/`,
+Every guide linked here is in the installed package at `node_modules/@rig-c/core/docs/`,
 which is the copy that matches the rigc you run; the links go to the repository's
 `main`. Inside the Claude Code plugin the same files are at `${CLAUDE_PLUGIN_ROOT}/docs/`.
 

package/skills/rigc-motion/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc-motion
 description: Author a Spine animation with rigc from key poses — an idle, a loop, a move from one picture to another — with timing and spacing, ease in and out, anticipation, arcs, overlap, follow-through, squash and stretch, and candidate variants a person can choose between. Use when the request is a movement on an existing or planned rig, in the animator's words too: "animate this rig", "make it breathe", "go from pose A to pose B", "make it feel heavier", "the cape should follow through". Not for Live2D, separating an image into parts, or real-time tracking.
 license: MIT
-compatibility: Requires Bun 1.4 or later and the npm package rig-c.
+compatibility: Requires Bun 1.4 or later and the npm package @rig-c/core (rig-c is the convenience name).
 ---
 
 # Motion — what goes between two poses
@@ -54,7 +54,7 @@ thing that judges a movement is a person's eye through `rigc vote` — MOTION §
    head turn; [INGEST.md](https://github.com/rig-c/core/blob/main/docs/INGEST.md) if the rig arrived as a compiled
    skeleton rather than loose parts.
 
-Every guide linked here is in the installed package at `node_modules/rig-c/docs/`,
+Every guide linked here is in the installed package at `node_modules/@rig-c/core/docs/`,
 which is the copy that matches the rigc you run; the links go to the repository's
 `main`. Inside the Claude Code plugin the same files are at `${CLAUDE_PLUGIN_ROOT}/docs/`.
 

package/skills/rigc-rigging/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc-rigging
 description: Decide a Spine rig's hierarchy with rigc — how many bones, where each pivot sits, what hangs off what, offsets, chains and what a chain can reach, siblings versus chains, constraints as structure — and which of those decisions the reference frames can check. Use when the request is a skeleton from loose part PNGs, such as "rig these parts", "make a Spine skeleton" or "where do the joints go", before any motion is authored. Not for Live2D, cutting an illustration into parts, or VTuber-style tracking.
 license: MIT
-compatibility: Requires Bun 1.4 or later and the npm package rig-c.
+compatibility: Requires Bun 1.4 or later and the npm package @rig-c/core (rig-c is the convenience name).
 ---
 
 # Rigging — the hierarchy itself
@@ -52,7 +52,7 @@ are named in RIGGING §11 — neither as a pass bar.
    [INGEST.md](https://github.com/rig-c/core/blob/main/docs/INGEST.md) if the skeleton was handed to you already
    compiled.
 
-Every guide linked here is in the installed package at `node_modules/rig-c/docs/`,
+Every guide linked here is in the installed package at `node_modules/@rig-c/core/docs/`,
 which is the copy that matches the rigc you run; the links go to the repository's
 `main`. Inside the Claude Code plugin the same files are at `${CLAUDE_PLUGIN_ROOT}/docs/`.
 

package/src/cli/core_commands.ts

@@ -1,3 +1,4 @@
+import { extremesOf, extremesText, extremesPlate, extremesLine, extremesRefusal } from '../extremes.ts';
 /**
  * The bodies of the commands that reach nothing of spine-core — `explain`,
  * `ingest`, `diff`, `check`, `render`, `inspect`, `pose`, `chainfit` and `skills` —
@@ -44,7 +45,7 @@ import { buildSheetSet, SHEET_MANIFEST_FILE, type SheetSetPack, SheetUsageError,
 import { readSeamPairs, SEAM_FILE, seamFileOf, seamLine, SeamError, type SeamPair, seamsOf, seamText } from '../seam.ts';
 import { environmentCollisions, environmentFrame, EnvironmentError, environmentResponse, readEnvironmentSchedule, type EnvironmentStep } from '../environment.ts';
 import { estimatePose, poseLines, type PoseOptions } from '../pose.ts';
-import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, frameSetDir, type FrameSet, type FramesSidecar, framingViewport, GEOMETRY_FILE, geometryFileOf, geometryText, loadCandidate, POSER_NAMES, type PoserName, PROTOCOL_FPS, refuseUnchosen, renderFrame, sampleAll, sampleAnimation, SETUP_POSE_DIR, SHEET_FILE, SHEET_TILE, sidecarViewport, type SkeletonFacts, type SlotSubset, SlotSubsetError, throughPoser, type Viewport, viewportFor } from '../render_shared.ts';
+import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, frameSetDir, type FrameSet, type FramesSidecar, framingViewport, GEOMETRY_FILE, geometryFileOf, geometryText, loadCandidate, POSER_NAMES, type PoserName, PROTOCOL_FPS, refuseUnchosen, renderFrame, sampleAll, sampleAnimation, sampleSetupPose, SETUP_POSE_DIR, SHEET_FILE, SHEET_TILE, sidecarViewport, type SkeletonFacts, type SlotSubset, SlotSubsetError, throughPoser, type Viewport, viewportFor } from '../render_shared.ts';
 import { type CompileResult } from '../types.ts';
 import { attachmentRegionJoins } from '../region_joins.ts';
 import { cmdRepack } from './repack.ts';
@@ -671,6 +672,7 @@ export function cmdRender(flags: Record<string, string>): void {
   const sheetPageEdges = wantsSheet ? readPageEdges(flags) : undefined;
   const outRoot = resolve(flags.out ?? 'render');
   const geometry = flags.geometry !== undefined;
+  const extremes = flags.extremes !== undefined;
   // The fold reading (issue #1383) is its own flag rather than a part of --geometry, so a caller that asked for
   // neither, or for --geometry alone, gets the bytes it always got: geometry.json is the pose, and a reading derived
   // from it is a second file beside it, written only when asked for.
@@ -843,11 +845,12 @@ export function cmdRender(flags: Record<string, string>): void {
     // the export's grid is this frame set's by construction.
     // 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 wantsGeometry = extremes || geometry || folds || passPairs !== undefined || seamPairs !== undefined;
     // 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,
+      ...(extremes ? { channels: true } : {}),
       ...(wantsBones ? { bones: true } : {}),
       ...(wantsGeometry ? { geometry: true } : {}),
       ...(physicsDeclared.length > 0 ? { physics: true } : {}),
@@ -856,6 +859,36 @@ export function cmdRender(flags: Record<string, string>): void {
       only === undefined
         ? sampleAll(poser, fps, sampling)
         : new Map([[only, sampleAnimation(poser, only, fps, sampling)]]);
+    const extremeReadings = new Map<string, { reading: ReturnType<typeof extremesOf>; plate: Plate | null }>();
+    if (extremes) {
+      // Setup is an optional observation too: a failed extra read cannot turn a drawable set into a gate failure.
+      let setup: Frame | undefined;
+      let setupFailure: string | undefined;
+      for (const [name, frames] of sampled) {
+        let reading: ReturnType<typeof extremesOf> | undefined;
+        try {
+          reading = extremesOf(name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name, fps, frames, pose);
+          let plate: Plate | null = null;
+          if (reading.geometryPair !== null) {
+            if (setupFailure !== undefined) throw new Error(setupFailure);
+            if (setup === undefined) {
+              try {
+                setup = sampleSetupPose(poser, pose)[0];
+                if (setup === undefined) throw new Error('setup pose sample is absent');
+              } catch (err) {
+                setupFailure = `setup pose observation failed: ${err instanceof Error ? err.message : String(err)}`;
+                throw new Error(setupFailure);
+              }
+            }
+            plate = extremesPlate(reading, setup, frames, pages, viewport);
+          }
+          extremeReadings.set(name, { reading, plate });
+        } catch (err) {
+          const refused = extremesRefusal(name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name, fps, frames, err instanceof Error ? err.message : String(err), reading);
+          extremeReadings.set(name, { reading: refused, plate: null });
+        }
+      }
+    }
     // Every file's text before the first write, so a refused number leaves the
     // output directory as it was rather than half of a frame set behind it.
     const geometryTexts = new Map<string, string>();
@@ -1002,9 +1035,9 @@ export function cmdRender(flags: Record<string, string>): void {
         }
       }
     }
-    return { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings, overlapReadings, sheetPacks };
+    return { viewport, fitted, sampled, extremeReadings, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings, overlapReadings, sheetPacks };
   });
-  const { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings, overlapReadings, sheetPacks } = posed.value;
+  const { viewport, fitted, sampled, extremeReadings, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings, overlapReadings, sheetPacks } = posed.value;
   console.log(`  ..    poser    ${posed.note}`);
   if (environment !== undefined) {
     const response = environmentResponse(skeletonText);
@@ -1056,6 +1089,13 @@ export function cmdRender(flags: Record<string, string>): void {
     if (foldReading !== undefined) writeFileSync(join(dir, FOLDS_FILE), foldsText(foldReading));
     const passReading = passReadings.get(name);
     if (passReading !== undefined) writeFileSync(join(dir, PASS_THROUGH_FILE), passThroughText(passReading));
+    const extreme = extremeReadings.get(name);
+    if (extreme !== undefined) {
+      writeFileSync(join(dir, 'extremes.json'), extremesText(extreme.reading));
+      if (extreme.plate === null) rmSync(join(dir, 'extremes.png'), { force: true });
+      else extreme.plate.writePng(join(dir, 'extremes.png'));
+      console.log(`  ..    ${extremesLine(extreme.reading)}`);
+    }
     const seamReading = seamReadings.get(name);
     if (seamReading !== undefined) writeFileSync(join(dir, SEAM_FILE), seamText(seamReading));
     const overlapReading = overlapReadings.get(name);

package/src/cli/shared.ts

@@ -152,7 +152,7 @@ export { PACKAGE_ROOT, readPackageMeta, readVersion };
  * needs a value` (issue #328). `CLI10`/`CLI11` in `selftest.ts` now hold the two
  * halves together by reading `--help` rather than by naming a flag.
  */
-const BOOLEAN_FLAGS = new Set(['all', 'all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'folds', 'overlaps', 'sheet', 'accept-skeleton-differences', 'keep-pages', 'dim']);
+const BOOLEAN_FLAGS = new Set(['all', 'all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'folds', 'extremes', 'overlaps', 'sheet', 'accept-skeleton-differences', 'keep-pages', 'dim']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -1066,6 +1066,7 @@ const FLAG_MEANINGS: Record<string, string> = {
     'Each frame with a moving pair also gets an outline plate, overlaps-f<NNNN>.png: every slot in a moving pair as its contour in its own ' +
     'colour, dashed where a slot drawn later covers it, named at its top. The render reports what was drawn; who should be in front is the ' +
     "author's, and the draw-order key in the motion spec is the remedy. A reading, not a gate. Not with --slot/--hide",
+  extremes: 'also write extremes.json and a native six-panel extremes.png per set: setup, geometry-pair min/max and premultiplied RGBA diffs, with a legend. Per-channel extrema are recorded separately and valid channels survive geometry/image SKIPs; channel refusals are named separately. Still geometry reports SKIP; a reading, not a gate. Attachment identity/count changes record a named SKIP without changing render exit; supports --slot/--hide on both posers',
   seam:
     `also read, for each <slot>:<slot> pair, where the two drawings stop meeting, and write ${SEAM_FILE} into each frame directory: ` +
     'per pair, the frames with a gap — background inside the hull of the band the two drawings share at the setup pose, carried to the frame by both — ' +
@@ -1756,7 +1757,7 @@ export const COMMANDS: CommandDoc[] = [
     runtime: false,
     spineFormat: false,
     usage: [
-      'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--geometry] [--folds] [--poser core|spine] [--out render/]',
+      'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--geometry] [--folds] [--extremes] [--poser core|spine] [--out render/]',
       'rigc render … --slot <name[,name…]> | --hide <name[,name…]>   (a subset of the slots, on the whole rig\'s grid)',
       'rigc render … --environment <schedule.json>   (the wind and gravity the physics answers, in time)',
       'rigc render … --pass-through <cloth>:<leg>[,…]   (the frames where a cloth drawn over a leg passes through it)',
@@ -1766,7 +1767,7 @@ export const COMMANDS: CommandDoc[] = [
       'rigc render … --viewport <x,y,w,h> | --viewport-from <frames.json>   (a box given, not fitted: two renders on one pixel grid)',
       'rigc render … --sheet [--sheet-format json-hash] [--page-edges pot|free]   (deterministic sprite sheets + JSON hash table + sheet-manifest.json per set)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'pass-through', 'seam', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'extremes', 'pass-through', 'seam', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'poser', 'out'],
     overrides: {
       'page-edges': {
         meaning:

package/src/core/animation.ts

@@ -1033,7 +1033,7 @@ function posedBoneStep(doc: CompiledDocument, timelines: CoreAnimationTimelines,
     const records = pathDeformed(doc, posedRecords(setupRecords, constraints, t), timelines, t, plant);
     // A path constraint may read a slot bone the runtime has not yet brought up to date in this pass, as the previous pass left it (`./constraints_path.ts`, *Which slot bone*); `poseAnimations` holds that pass to the setup pose's reading.
     const previous = setupRecords.some((r) => r.kind === 'path') ? applyConstraints(doc.bones, (plant.evaluate ?? worldTransforms)(doc.bones, active), active, plant.constraints ? plant.constraints(setupRecords) : setupRecords, null, undefined, undefined, undefined, solverRules(plant.solver)) : null;
-    world = applyConstraints(bones, initialWorld, active, plant.constraints ? plant.constraints(records) : records, previous, sliders, undefined, undefined, solverRules(plant.solver));
+    world = applyConstraints(bones, initialWorld, active, plant.constraints ? plant.constraints(records) : records, previous, sliders, undefined, plant.readLocals === undefined ? undefined : (state) => plant.readLocals?.(state.bones, sliders ?? []), solverRules(plant.solver));
     if (stage !== undefined) stage.end('constraints');
   }
   for (const b of bones) if (world.get(b.name) === undefined) throw new CoreInputError(`the evaluator returned no transform for bone "${b.name}"`);
@@ -1066,7 +1066,7 @@ function steppedLocals(doc: CompiledDocument, bones: ModelBone[], plant: Timelin
     stage.begin('constraints');
   }
   const stepped = stepPhysicsRecords(records(), physicsKeyed, t, active, step.ctx, step.before);
-  const world = applyConstraints(bones, initialWorld, active, plant.constraints ? plant.constraints(stepped) : stepped, null, sliders, step.ctx, undefined, solverRules(plant.solver));
+  const world = applyConstraints(bones, initialWorld, active, plant.constraints ? plant.constraints(stepped) : stepped, null, sliders, step.ctx, plant.readLocals === undefined ? undefined : (state) => plant.readLocals?.(state.bones, sliders ?? []), solverRules(plant.solver));
   if (stage !== undefined) stage.end('constraints');
   for (const b of bones) if (world.get(b.name) === undefined) throw new CoreInputError(`the evaluator returned no transform for bone "${b.name}"`);
   return { bones, world, active, round: plant.round ?? gridRound };

package/src/core/index.ts

@@ -1085,6 +1085,8 @@ export interface StageHooks {
  * channel misread — and nothing else passes any.
  */
 export interface CorePlant {
+  /** Optional read of the solved local channels and applied slider mappings; never modifies the pose. */
+  readLocals?: (bones: readonly ModelBone[], sliders: readonly SliderApplication[]) => void;
   evaluate?: SetupEvaluator;
   shown?: ShownResolver;
   colour?: ColourReader;
@@ -1335,7 +1337,7 @@ export function poseSetup(doc: CompiledDocument, plant: CorePlant = {}, physics?
   if (bonesWhy === null) {
     const active = activeBones(doc);
     const records = constraintRecords(doc);
-    setupWorld = applyConstraints(doc.bones, evaluate(doc.bones, active), active, plant.constraints ? plant.constraints(records) : records, null, applied, physics, undefined, solverRules(plant.solver));
+    setupWorld = applyConstraints(doc.bones, evaluate(doc.bones, active), active, plant.constraints ? plant.constraints(records) : records, null, applied, physics, plant.readLocals === undefined ? undefined : (state) => plant.readLocals?.(state.bones, applied), solverRules(plant.solver));
     const world = setupWorld;
     bones = doc.bones.map((b): CoreBoneRow => {
       const t = world.get(b.name);

package/src/extremes.ts

@@ -0,0 +1,198 @@
+/** render --extremes: observations on one already-sampled set, never a quality gate. */
+import { Plate } from '../tools/plate.ts';
+import { hypot2 } from './numeric.ts';
+import { attachmentSource } from './render_channels.ts';
+import { renderFrame, TRANSPARENT_BACKGROUND, type Frame, type PoseOptions, type Viewport } from './render_shared.ts';
+
+export class ExtremesError extends Error {}
+export interface ExtremeFrame { index: number; time: number }
+export interface ChannelExtreme {
+  path: string[];
+  min: ExtremeFrame & { value: number; reason: string };
+  max: ExtremeFrame & { value: number; reason: string };
+}
+export interface ExtremesReading {
+  spec: 'rigc-extremes/1';
+  animation: string | null;
+  fps: number;
+  grid: ExtremeFrame[];
+  method: {
+    channels: string;
+    geometry: string;
+    ties: string;
+    geometryScope: string;
+    panels: string;
+    diff: string;
+  };
+  channels: ChannelExtreme[];
+  channelStatus: 'READ' | 'PARTIAL' | 'SKIP';
+  channelRefusals: Array<{ path: string[] | null; reason: string }>;
+  status: 'READ' | 'SKIP';
+  reason: string;
+  geometryPair: { frames: [ExtremeFrame, ExtremeFrame]; maxVertexDistance: number; witness: { slot: string; attachment: string; vertex: number } } | null;
+}
+
+const stamp = (f: Frame): ExtremeFrame => ({ index: f.index, time: f.time });
+
+/** Channel validity is independent of geometry and of an image. A bad series cannot erase another series. */
+function channelExtrema(frames: readonly Frame[]): Pick<ExtremesReading, 'channels' | 'channelStatus' | 'channelRefusals'> {
+  const channels = new Map<string, ChannelExtreme>();
+  const refusals = new Map<string, { path: string[] | null; reason: string }>();
+  const sources = new Map<string, object>();
+  const refuse = (path: string[] | null, why: string): void => {
+    const key = JSON.stringify(path);
+    channels.delete(key);
+    refusals.set(key, { path, reason: `EXTREMES_CHANNEL_REFUSED: ${why}` });
+  };
+  for (const f of frames) {
+    if (f.channelError !== undefined || f.channels === undefined) {
+      // A failed whole-frame read leaves every series' extrema unknown on this grid.
+      return { channels: [], channelStatus: 'SKIP', channelRefusals: [{ path: null, reason: `EXTREMES_CHANNEL_REFUSED: frame ${f.index}: ${f.channelError ?? 'local channels were not sampled'}` }] };
+    }
+    for (const sample of f.channels) {
+      const { path, value } = sample;
+      const key = JSON.stringify(path);
+      if (refusals.has(key)) continue;
+      if (!Number.isFinite(value)) { refuse(path, `frame ${f.index}, channel ${key}: found ${value}, required finite`); continue; }
+      if (path[0] === 'deform') {
+        const source = attachmentSource(sample);
+        if (source === undefined) { refuse(path, `frame ${f.index}, deform channel ${key}: original source identity unavailable`); continue; }
+        const before = sources.get(key);
+        if (before !== undefined && before !== source) {
+          refuse(path, `frame ${f.index}, deform channel ${key}: one slot/display-name/coordinate names different original attachment sources; separate extrema under that name are unavailable`);
+          continue;
+        }
+        sources.set(key, source);
+      }
+      const read = channels.get(key);
+      if (read === undefined) {
+        channels.set(key, { path,
+          min: { ...stamp(f), value, reason: 'minimum supplied local channel value on this grid; earliest tie; deform/slider samples only where applicable' },
+          max: { ...stamp(f), value, reason: 'maximum supplied local channel value on this grid; earliest tie; deform/slider samples only where applicable' },
+        });
+      } else {
+        if (value < read.min.value) read.min = { ...read.min, ...stamp(f), value };
+        if (value > read.max.value) read.max = { ...read.max, ...stamp(f), value };
+      }
+    }
+  }
+  const byKey = <T>(rows: Map<string, T>): T[] => [...rows].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([, row]) => row);
+  return { channels: byKey(channels), channelStatus: refusals.size === 0 ? 'READ' : channels.size === 0 ? 'SKIP' : 'PARTIAL', channelRefusals: byKey(refusals) };
+}
+
+/** Original attachment identity, independent of draw order and of a clipper's triangles. */
+function geometryPair(frames: readonly Frame[], subset?: Pick<PoseOptions, 'slots' | 'hidden'>): ExtremesReading['geometryPair'] {
+  const selected = (slot: string): boolean => (subset?.slots === undefined || subset.slots.includes(slot)) && !subset?.hidden?.includes(slot);
+  const geometry = frames.map((f) => {
+    if (f.attachments === undefined) throw new ExtremesError(`frame ${f.index}: original attachment geometry was not sampled`);
+    const attachments = f.attachments.filter((a) => selected(a.slot));
+    for (const a of attachments) if (attachmentSource(a) === undefined) {
+      throw new ExtremesError(`frame ${f.index}, slot ${JSON.stringify(a.slot)}, attachment ${JSON.stringify(a.attachment)}: original source identity unavailable; required stable original-vertex correspondence`);
+    }
+    const byId = new Map(attachments.map((a) => [JSON.stringify([a.slot, a.attachment]), a]));
+    return [...byId].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  });
+  const first = geometry[0] ?? [];
+  for (let i = 0; i < geometry.length; i++) {
+    const row = geometry[i];
+    if (row.length !== first.length || row.some(([key, a], k) => key !== first[k]?.[0] || a.vertices.length !== first[k]?.[1].vertices.length || attachmentSource(a) !== attachmentSource(first[k][1]))) {
+      throw new ExtremesError(`frame ${frames[i].index}: attachment identity or vertex count changed (including actual source identity); cannot compare corresponding original vertices (expected ${first.map(([k, a]) => `${k}:${a.vertices.length / 2}`).join(', ')}, found ${row.map(([k, a]) => `${k}:${a.vertices.length / 2}`).join(', ')})`);
+    }
+    for (const [, a] of row) {
+      if (a.vertices.length % 2 || a.vertices.some((v) => !Number.isFinite(v))) throw new ExtremesError(`frame ${frames[i].index}, slot ${JSON.stringify(a.slot)}, attachment ${JSON.stringify(a.attachment)}: expected finite x/y vertex pairs`);
+    }
+  }
+  let best = 0;
+  let pair: ExtremesReading['geometryPair'] = null;
+  for (let i = 0; i < frames.length; i++) for (let j = i + 1; j < frames.length; j++) {
+    for (let k = 0; k < first.length; k++) {
+      const a = geometry[i][k][1];
+      const b = geometry[j][k][1];
+      for (let v = 0; v < a.vertices.length; v += 2) {
+        const distance = hypot2(a.vertices[v] - b.vertices[v], a.vertices[v + 1] - b.vertices[v + 1]);
+        if (!Number.isFinite(distance)) throw new ExtremesError(`frames ${frames[i].index}/${frames[j].index}, slot ${JSON.stringify(a.slot)} vertex ${v / 2}: world distance is not finite`);
+        if (distance > best) {
+          best = distance;
+          pair = { frames: [stamp(frames[i]), stamp(frames[j])], maxVertexDistance: distance, witness: { slot: a.slot, attachment: a.attachment, vertex: v / 2 } };
+        }
+      }
+    }
+  }
+  return pair;
+}
+
+export function extremesOf(animation: string | null, fps: number, frames: readonly Frame[], subset?: Pick<PoseOptions, 'slots' | 'hidden'>): ExtremesReading {
+  const observedChannels = channelExtrema(frames);
+  let pair: ExtremesReading['geometryPair'] = null;
+  let geometryFailure: string | undefined;
+  try { pair = geometryPair(frames, subset); }
+  catch (err) { geometryFailure = `EXTREMES_OBSERVATION_REFUSED: geometry: ${err instanceof Error ? err.message : String(err)}`; }
+  return {
+    spec: 'rigc-extremes/1', animation, fps, grid: frames.map(stamp),
+    method: {
+      channels: 'Sampled posed local bone rotate, translate.x/y, scale.x/y, shear.x/y (including held components), deform offsets per coordinate, and actually applied slider mapped-time; channelStatus/channelRefusals describe independent failures. Deform series with one display-name path but different original sources are refused individually; independent of geometry pair. No key-time interpolation outside this grid.',
+      geometry: 'Exhaustive frame pairs i<j; distance=max over corresponding original attachment vertices of hypot2(dx,dy)=sqrt(dx*dx+dy*dy), dx/dy in world units (the shared deterministic length helper).',
+      ties: 'First in frame-grid order; geometry ties keep earliest (i,j), then attachment identity in UTF-16 code-unit order, then vertex index. Timestamps are copied from sampled frames.',
+      geometryScope: 'Original region/mesh vertices, before clipping, occlusion and tint alpha; filtered explicitly by --slot/--hide. Changing attachment source identity/count is refused, including different sources with equal display names and vertex counts.',
+      panels: 'setup | min | max | abs(max-min) | abs(min-setup) | abs(max-setup). min/max label earlier/later frame of the geometry pair, not joint channel minima/maxima. Native viewport size and scale, legend appended below.',
+      diff: 'L=round(max(abs(Ra*Aa/255-Rb*Ab/255),abs(Ga*Aa/255-Gb*Ab/255),abs(Ba*Aa/255-Bb*Ab/255),abs(Aa-Ab))); opaque (L,L,L,255) on black. No amplification or scaling.',
+    },
+    ...observedChannels,
+    status: pair === null ? 'SKIP' : 'READ',
+    reason: geometryFailure ?? (pair === null ? 'no motion in corresponding selected original vertices on this frame grid' : 'farthest geometry pair on this frame grid; see method and witness'),
+    geometryPair: pair,
+  };
+}
+
+/** A refused observation is a named SKIP, never a failed render. */
+export function extremesRefusal(animation: string | null, fps: number, frames: readonly Frame[], reason: string, prior?: ExtremesReading): ExtremesReading {
+  const reading = prior ?? { ...extremesOf(animation, fps, []), ...channelExtrema(frames) };
+  return { ...reading, grid: frames.map(stamp), status: 'SKIP', reason: `EXTREMES_OBSERVATION_REFUSED: image: ${reason}` };
+}
+
+export function extremesText(reading: ExtremesReading): string { return JSON.stringify(reading, null, 2) + '\n'; }
+export function extremesLine(reading: ExtremesReading): string {
+  const name = JSON.stringify(reading.animation ?? 'setup-pose');
+  const p = reading.geometryPair;
+  const channels = `; channels ${reading.channelStatus} (${reading.channels.length} valid, ${reading.channelRefusals.length} refused)`;
+  return reading.status === 'SKIP' || p === null ? `EXTREMES ${name} SKIP: ${reading.reason}${channels}` : `EXTREMES ${name} geometry pair f${p.frames[0].index} @ ${p.frames[0].time}s / f${p.frames[1].index} @ ${p.frames[1].time}s; max vertex distance ${p.maxVertexDistance} world units${channels}`;
+}
+
+/** Alpha participates as a fourth premultiplied channel; RGB at alpha zero contributes zero. */
+export function premultipliedDiff(a: Plate, b: Plate): Plate {
+  if (a.width !== b.width || a.height !== b.height) throw new ExtremesError('diff dimensions differ; required identical native pixel grids');
+  const out = new Plate(a.width, a.height);
+  for (let i = 0; i < out.data.length; i += 4) {
+    let d = Math.abs(a.data[i + 3] - b.data[i + 3]);
+    for (let c = 0; c < 3; c++) d = Math.max(d, Math.abs(a.data[i + c] * a.data[i + 3] / 255 - b.data[i + c] * b.data[i + 3] / 255));
+    out.data[i] = out.data[i + 1] = out.data[i + 2] = Math.round(d);
+    out.data[i + 3] = 255;
+  }
+  return out;
+}
+
+export function extremesPlate(reading: ExtremesReading, setup: Frame, frames: readonly Frame[], pages: Map<string, Plate>, viewport: Viewport): Plate | null {
+  const pair = reading.geometryPair;
+  if (reading.status === 'SKIP' || pair === null) return null;
+  const find = (index: number): Frame => {
+    const f = frames.find((f) => f.index === index);
+    if (f === undefined) throw new ExtremesError(`chosen frame ${index} is absent`);
+    return f;
+  };
+  const base = renderFrame(setup, pages, viewport, TRANSPARENT_BACKGROUND);
+  const min = renderFrame(find(pair.frames[0].index), pages, viewport, TRANSPARENT_BACKGROUND);
+  const max = renderFrame(find(pair.frames[1].index), pages, viewport, TRANSPARENT_BACKGROUND);
+  const panels = [base, min, max, premultipliedDiff(max, min), premultipliedDiff(min, base), premultipliedDiff(max, base)];
+  const width = viewport.width * 6;
+  const legend = `1 setup | 2 min=f${pair.frames[0].index} (${pair.frames[0].time}s) | 3 max=f${pair.frames[1].index} (${pair.frames[1].time}s) | 4 abs(max-min) | 5 abs(min-setup) | 6 abs(max-setup). Geometry pair ordered by frame; channels listed separately in JSON. Diff: max premultiplied RGBA incl alpha, luminance on black, no amplification. Scale ${viewport.scale} px/world-unit.`;
+  const columns = Math.max(1, Math.floor(width / 6));
+  const rows = Math.ceil(legend.length / columns);
+  const out = new Plate(width, viewport.height + rows * 9 + 4);
+  // Legend black, all pixels opaque there; pictures retain their native alpha.
+  for (let i = viewport.height * width * 4 + 3; i < out.data.length; i += 4) out.data[i] = 255;
+  panels.forEach((panel, k) => {
+    for (let y = 0; y < viewport.height; y++) out.data.set(panel.data.subarray(y * panel.width * 4, (y + 1) * panel.width * 4), (y * width + k * panel.width) * 4);
+  });
+  for (let row = 0; row < rows; row++) out.text(legend.slice(row * columns, (row + 1) * columns), 0, viewport.height + 2 + row * 9, 1, [255, 255, 255, 255]);
+  return out;
+}

package/src/render.ts

@@ -1,3 +1,4 @@
+import { localChannels, deformChannels, identifyAttachment } from './render_channels.ts';
 /**
  * The rasteriser — one code path for reference frames and for candidates.
  *
@@ -118,6 +119,7 @@ import {
   Skeleton,
   SkeletonClipping,
   SkeletonJson,
+  Slider,
   TextureAtlas,
   TextureAtlasRegion,
   SkeletonData,
@@ -548,8 +550,21 @@ function spinePosed(skeleton: Skeleton): Posed {
   return {
     pieces: (draw) => drawPieces(skeleton, draw),
     bones: () => boneSnapshots(skeleton),
-    attachments: () => attachmentsOf(skeleton),
+    attachments: (identity) => attachmentsOf(skeleton, identity),
     physics: () => steppedPhysicsOf(skeleton),
+    channels: () => {
+      const values = localChannels(skeleton.bones.map((b) => {
+        const p = b.appliedPose;
+        return { name: b.data.name, rotation: p.rotation, x: p.x, y: p.y, scaleX: p.scaleX, scaleY: p.scaleY, shearX: p.shearX, shearY: p.shearY };
+      }), skeleton.constraints.filter((c): c is Slider => c instanceof Slider && c.active && c.appliedPose.mix !== 0 && (c.bone === null || c.bone.active)).map((c) => ({ name: c.data.name, time: c.appliedPose.time })));
+      for (const slot of skeleton.slots) {
+        const a = slot.appliedPose.attachment;
+        if (!(a instanceof MeshAttachment)) continue;
+        const setup = a.bones === null ? Array.from(a.vertices) : new Array<number>(a.vertices.length / 3 * 2).fill(0);
+        values.push(...deformChannels(slot.data.name, a.name, slot.appliedPose.deform, setup, a));
+      }
+      return values;
+    },
   };
 }
 
@@ -803,17 +818,18 @@ function worldVerticesOf(skeleton: Skeleton, slot: Slot, attachment: MeshAttachm
  * Every slot's region or mesh attachment, whole, in the posed draw order — see
  * `Frame.attachments`. No subset and no clip: those are `piecesOf`'s business.
  */
-function attachmentsOf(skeleton: Skeleton): AttachmentPose[] {
+function attachmentsOf(skeleton: Skeleton, identity = false): AttachmentPose[] {
   const out: AttachmentPose[] = [];
   for (const slot of skeleton.drawOrder.appliedPose) {
     const attachment = slot.appliedPose.attachment;
     if (!(attachment instanceof MeshAttachment) && !(attachment instanceof RegionAttachment)) continue;
-    out.push({
+    const row = {
       slot: slot.data.name,
       attachment: attachment.name,
       vertices: worldVerticesOf(skeleton, slot, attachment),
       color: tintOf(slot, attachment),
-    });
+    };
+    out.push(identity ? identifyAttachment(row, attachment) : row);
   }
   return out;
 }

package/src/render_channels.ts

@@ -0,0 +1,36 @@
+/** Local scalar readings shared by the two posers; no stepping or inferred world decomposition. */
+import type { ModelBone } from './model.ts';
+import type { ChannelValue } from './render_shared.ts';
+
+const FIELDS = {
+  rotation: ['rotate', 0], x: ['translate.x', 0], y: ['translate.y', 0],
+  scaleX: ['scale.x', 1], scaleY: ['scale.y', 1], shearX: ['shear.x', 0], shearY: ['shear.y', 0],
+} as const;
+
+export function localChannels(bones: readonly ModelBone[], sliders: readonly { name: string; time: number }[]): ChannelValue[] {
+  const out: ChannelValue[] = [];
+  for (const bone of bones) {
+    for (const field of Object.keys(FIELDS) as Array<keyof typeof FIELDS>) {
+      const [name, setup] = FIELDS[field];
+      out.push({ path: ['bone', bone.name, name], value: bone[field] ?? setup });
+    }
+  }
+  for (const slider of sliders) out.push({ path: ['slider', slider.name, 'mapped-time'], value: slider.time });
+  return out;
+}
+
+/** Offsets from setup, x/y per influence for weighted meshes, x/y per vertex otherwise. */
+export function deformChannels(slot: string, attachment: string, deform: readonly number[], setup: readonly number[], source?: object): ChannelValue[] {
+  return setup.map((v, i) => {
+    const read = { path: ['deform', slot, attachment, String(i)], value: deform.length === 0 ? 0 : deform[i] - v };
+    return source === undefined ? read : identifyAttachment(read, source);
+  });
+}
+
+// The display name can be overridden by an export. Keep actual source identity out of serialized geometry.
+const attachmentSources = new WeakMap<object, object>();
+export function identifyAttachment<T extends object>(pose: T, source: object): T {
+  attachmentSources.set(pose, source);
+  return pose;
+}
+export function attachmentSource(pose: object): object | undefined { return attachmentSources.get(pose); }

package/src/render_core.ts

@@ -1,3 +1,5 @@
+import { localChannels, deformChannels, identifyAttachment } from './render_channels.ts';
+import type { ChannelValue } from './render_shared.ts';
 /**
  * The render's second poser (issue #968, step 3d of issue #380): the posing
  * seam of `src/render.ts` (`Poser` / `Posed`) implemented over rigc's own
@@ -462,7 +464,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, stepped: readonly string[]): Posed {
+function corePosed(input: CoreInput, pose: RawPose, through: ShapeClipper, stepped: readonly string[], channels?: ChannelValue[]): 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> => {
@@ -504,8 +506,25 @@ function corePosed(input: CoreInput, pose: RawPose, through: ShapeClipper, stepp
         scaleY: b.scaleY,
       }) : inactiveBoneSnapshot(b.name));
     },
-    attachments: (): AttachmentPose[] =>
-      pose.drawn.map((d) => ({ slot: d.slot, attachment: d.attachment, vertices: [...d.vertices], color: tintOf(d) })),
+    attachments: (identity = false): AttachmentPose[] =>
+      pose.drawn.map((d) => {
+        const row = { slot: d.slot, attachment: d.attachment, vertices: [...d.vertices], color: tintOf(d) };
+        if (!identity) return row;
+        const source = pose.shown.find((s) => s.slot === d.slot)?.geometry;
+        if (source === undefined) throw new CoreInputError(`slot "${d.slot}" has no original attachment identity`);
+        return identifyAttachment(row, source);
+      }),
+    ...(channels === undefined ? {} : { channels: (): ChannelValue[] => {
+      const out = [...channels];
+      for (const shown of pose.shown) {
+        const g = shown.geometry;
+        const v = g.kind === 'mesh' ? g.vertices : g.kind === 'linkedmesh' ? sourceOfDoc(input.doc)(g.skin, g.slot, g.source) : null;
+        if (v === null || typeof v === 'string') continue;
+        const setup = v.weighted ? new Array<number>(v.bindings.reduce((n, b) => n + b.length * 2, 0)).fill(0) : v.xy;
+        out.push(...deformChannels(shown.slot, shown.name, shown.deform ?? [], setup, g));
+      }
+      return out;
+    } }),
     physics: (): string[] => [...stepped],
   };
 }
@@ -756,11 +775,16 @@ export function corePoser(
     bones: doc.bones.map((b) => ({ name: b.name, parent: b.parent ?? null })),
     slots: doc.slots.map((s) => ({ name: s.name, bone: s.bone })),
     subset: (opts, skin) => subsetOver(roster, opts, skin),
-    setup: (skin) => {
+    setup: (skin, channels) => {
       const input = inputOf(skin);
-      return corePosed(input, poseRawSetup(input.doc, { through }), through, []);
+      let values: ChannelValue[] | undefined;
+      const observe = channels ? { readLocals: (bones: readonly import('./model.ts').ModelBone[], sliders: readonly import('./core/constraints_slider.ts').SliderApplication[]) => { values = localChannels(bones, sliders); } } : {};
+      const pose = poseRawSetup(input.doc, { through, ...observe });
+      return corePosed(input, pose, through, [], values);
     },
-    animation: (name, skin, fps, count, visit, environment) => {
+    animation: (name, skin, fps, count, visit, environment, channels) => {
+      let values: ChannelValue[] | undefined;
+      const observe = channels ? { readLocals: (bones: readonly import('./model.ts').ModelBone[], sliders: readonly import('./core/constraints_slider.ts').SliderApplication[]) => { values = localChannels(bones, sliders); } } : {};
       const input = inputOf(skin);
       const step = 1 / fps;
       // Each pose is drawn as it is posed and released before the next (issue #1180), so the walk holds one pose and not
@@ -778,12 +802,12 @@ export function corePoser(
         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) => {
+      walk(input.doc, name, new Array<number>(count).fill(step), { through, physicsStep, ...observe }, (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, stepped));
+          visit(i, corePosed(input, pose, through, stepped, values));
         } catch (thrown) {
           drawFailed.push(thrown);
         }

package/src/render_shared.ts

@@ -415,6 +415,8 @@ export interface UvWindow {
 
 /** Options for `piecesOf` and the samplers that call it. */
 export interface PoseOptions {
+  /** Also read local bone/deform channels and mapped slider times, and retain original attachment source identity outside JSON, for --extremes. */
+  channels?: boolean;
   /** Also record each piece's original-art UVs — see `PieceTexture`. */
   texture?: boolean;
   /**
@@ -595,7 +597,13 @@ export interface ClipSource {
 /** One drawable in a posed frame. */
 export type Piece = Quad | Mesh;
 
+export interface ChannelValue { path: string[]; value: number }
+
 export interface Frame {
+  /** Sampled local channels, only when requested. */
+  channels?: ChannelValue[];
+  /** A failed optional observation does not fail the draw. */
+  channelError?: string;
   /** Index within the sampled sequence — the number in `f0000.png`. */
   index: number;
   time: number;
@@ -1107,12 +1115,14 @@ export interface DrawOptions {
  * what it needs before the next frame is posed.
  */
 export interface Posed {
+  /** Optional channel read, on the very pose drawn; no extra stepping. */
+  channels?(): ChannelValue[];
   /** The drawables in draw order — see `piecesOf` for the walk and the clip. */
   pieces(draw: DrawOptions): Piece[];
   /** Every bone's world transform, in the skeleton's declaration order. */
   bones(): BoneSnapshot[];
-  /** Every slot's region or mesh attachment, whole, in the posed draw order. */
-  attachments(): AttachmentPose[];
+  /** Every slot's region or mesh attachment, whole, in draw order; identity=true retains the original source in an out-of-JSON registry for --extremes. */
+  attachments(identity?: boolean): 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
@@ -1143,14 +1153,14 @@ export interface Poser {
   /** `slotSubsetOf` against this skeleton posed under `skin` — refused by `SlotSubsetError`. */
   subset(opts: Pick<PoseOptions, 'slots' | 'hidden'> | undefined, skin: string | undefined): SlotSubset | undefined;
   /** The setup pose under `skin` (absent: no skin set at all). */
-  setup(skin: string | undefined): Posed;
+  setup(skin: string | undefined, channels?: boolean): Posed;
   /**
    * Animation `name` under `skin`, not looping: `visit(i, posed)` for every
    * `i` from 0 to `count`, the pose at `i/fps`. The caller has checked `name`.
    * `environment(i)`, when given, is the change to the world the physics
    * answers set before the step that poses frame `i` (issue #1416).
    */
-  animation(name: string, skin: string | undefined, fps: number, count: number, visit: (index: number, posed: Posed) => void, environment?: (index: number) => EnvironmentChange | undefined): void;
+  animation(name: string, skin: string | undefined, fps: number, count: number, visit: (index: number, posed: Posed) => void, environment?: (index: number) => EnvironmentChange | undefined, channels?: boolean): void;
   /** The rest table for the (slot, attachment) pairs `shown` holds — see `AttachmentRest`. */
   rest(skin: string | undefined, shown: readonly AttachmentPose[][]): AttachmentRest[];
 }
@@ -1188,12 +1198,21 @@ function drawResolver(poser: Poser, opts: PoseOptions | undefined): () => DrawOp
 
 /** One frame off one posed moment, with what `opts` asked to record beside the pieces. */
 function frameOf(index: number, time: number, posed: Posed, draw: DrawOptions, opts: PoseOptions | undefined): Frame {
+  let channels: Pick<Frame, 'channels' | 'channelError'> = {};
+  if (opts?.channels) {
+    try {
+      if (posed.channels === undefined) throw new Error('poser does not expose local channels');
+      channels = { channels: posed.channels() };
+    }
+    catch (err) { channels = { channelError: `frame ${index}: local channel read failed: ${err instanceof Error ? err.message : String(err)}` }; }
+  }
   return {
     index,
     time,
     pieces: posed.pieces(draw),
+    ...channels,
     ...(opts?.bones ? { bones: posed.bones() } : {}),
-    ...(opts?.geometry ? { attachments: posed.attachments() } : {}),
+    ...(opts?.geometry ? { attachments: opts.channels ? posed.attachments(true) : posed.attachments() } : {}),
     ...(opts?.physics ? { physics: posed.physics() } : {}),
   };
 }
@@ -1220,7 +1239,8 @@ export function sampleAnimation(source: PoseSource, name: string, fps: number, o
     frames.push(frameOf(i, i * step, posed, draw(), opts));
   };
   // Without an environment the call is the one it always was, so a poser that takes none is asked nothing new.
-  if (opts?.environment === undefined) poser.animation(name, opts?.skin, fps, count, visit);
+  if (opts?.channels) poser.animation(name, opts.skin, fps, count, visit, opts.environment === undefined ? undefined : environmentAt(opts.environment, fps), true);
+  else if (opts?.environment === undefined) poser.animation(name, opts?.skin, fps, count, visit);
   else poser.animation(name, opts.skin, fps, count, visit, environmentAt(opts.environment, fps));
   return frames;
 }
@@ -1235,7 +1255,7 @@ export function sampleAnimation(source: PoseSource, name: string, fps: number, o
  */
 export function sampleSetupPose(source: PoseSource, opts?: PoseOptions): Frame[] {
   const poser = poserOf(source);
-  const posed = poser.setup(opts?.skin);
+  const posed = opts?.channels ? poser.setup(opts.skin, true) : poser.setup(opts?.skin);
   return [frameOf(0, 0, posed, drawResolver(poser, opts)(), opts)];
 }