@rig-c/core 2.79.0 → 2.81.0

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/rig-c"><img src="https://img.shields.io/npm/v/rig-c.svg?style=flat-square&color=FF6B4A" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@rig-c/core"><img src="https://img.shields.io/npm/v/@rig-c/core.svg?style=flat-square&color=FF6B4A" alt="npm version" /></a>
   <a href="https://www.npmjs.com/package/rig-c"><img src="https://img.shields.io/npm/dm/rig-c.svg?style=flat-square&color=A855F7" alt="npm downloads" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-38BDF8.svg?style=flat-square" alt="license" /></a>
 </p>
@@ -14,9 +14,9 @@ format, with rigc's own compiled model beside it —
 gated by a list of named assertions before a byte is written — rigc's own validator in
 the published package, held to a `spine-core` round trip's verdicts in this
 repository's CI. Built so AI agents can author rigs and check their own work; it ships
-as an agent skill. On npm it is `rig-c` — the same package as `spine-rigc`, the name it
-first shipped under, and as `@rig-c/core`, its name under the toolchain's scope, both
-published beside it with the same files at every version.
+as an agent skill. Its canonical npm package is `@rig-c/core`, under the toolchain's
+scope. `rig-c` is the convenience install name; `spine-rigc` is the legacy install
+name. Both remain published alongside it with the same product files.
 
 ## What you get
 
@@ -177,22 +177,23 @@ name with exit 2 before upload. Use a published exact `X.Y.Z` (no `v` prefix,
 alias, range or prerelease), or retry a failed network fetch. This is repository
 verification tooling, not an installed `rigc` command or a change to CI's matrix.
 
-**The npm package is `rig-c`; the command it installs is `rigc`.** npm
+**The canonical npm package is `@rig-c/core`; the command it installs is `rigc`.**
+`rig-c` remains a convenience install name. npm
 refuses the name `rigc` as too similar to packages that already exist, so the
-project and the executable keep their name and the registry entry carries one
-hyphen; the repository is [`rig-c/core`](https://github.com/rig-c/core). **`spine-rigc` is the same package**: it is the name
+project and the executable keep their name; the convenience name `rig-c` carries one
+hyphen; the repository is [`rig-c/core`](https://github.com/rig-c/core). **`spine-rigc` is the legacy install name for the same package**: it is the name
 every version up to 2.20.4 shipped under, and it stays published as an alias —
 every version from 2.20.4 on is on both names, with the same files — so a
 project that depends on `spine-rigc` keeps receiving every release. A new
-project installs `rig-c`; `@rig-c/core` is the same package under the scope.
+project installs `@rig-c/core`, the canonical package under the toolchain's scope.
 
 ```bash
-bunx rig-c --help    # run it without installing
-bun add -g rig-c     # or install the command
-bun add -d rig-c     # or pin it in a project
+bunx @rig-c/core --help    # run it without installing
+bun add -g @rig-c/core     # or install the command
+bun add -d @rig-c/core     # or pin it in a project
 ```
 
-`npx rig-c` works too, as long as Bun is on `PATH` — the executable is a
+`npx @rig-c/core` works too, as long as Bun is on `PATH` — the executable is a
 Bun script, and npm only writes the shim that calls it.
 
 Installed, the command is `rigc`. The examples below spell it `bun cli.ts`
@@ -242,7 +243,7 @@ plugin marketplace:
 /plugin install rigc@rigc
 ```
 
-With the package already installed, `claude --plugin-dir node_modules/rig-c`
+With the package already installed, `claude --plugin-dir node_modules/@rig-c/core`
 loads the same skills without a marketplace. The plugin carries no version of its
 own — `/plugin update` follows `main` commit by commit, and the only version on
 disk stays the one in `package.json`.
@@ -254,8 +255,8 @@ Codex, Gemini CLI and Antigravity read skills from one directory in the workspac
 `node_modules`. With the package installed, one command puts every skill there:
 
 ```shell
-bun add -d rig-c
-bun rigc skills install          # relative links: .agents/skills/rigc -> ../../node_modules/rig-c/skills/rigc
+bun add -d @rig-c/core
+bun rigc skills install          # relative links: .agents/skills/rigc -> ../../node_modules/@rig-c/core/skills/rigc
 bun rigc skills install --copy   # the folders themselves, for a host that does not follow a link
 ```
 
@@ -290,11 +291,11 @@ reference export, so nothing you read in a quickstart is an answer to anything
 **1. Install the command.**
 
 ```bash
-bun add -g rig-c     # installs `rigc`
+bun add -g @rig-c/core     # installs `rigc`
 ```
 
 Or skip the install and prefix every command below with `bunx `, e.g.
-`bunx rig-c build …`.
+`bunx @rig-c/core build …`.
 
 **2. Make a directory and three plates.** rigc measures PNGs rather than trusting
 a number you typed (R5), so the art has to exist. These three are solid colours a
@@ -646,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
@@ -9464,6 +9467,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
@@ -11267,6 +11352,27 @@ Everything above is what the editor **does**. This is what it **returns** — wh
 matters to you for one reason: a construct nobody has carried through the editor
 is a construct that might vanish there, and an agent cannot see that it did.
 
+`tools/editor_roundtrip.ts` also names a clipping semantic change after export
+(issue #1630), including under `--exported`. If the export adds `convex: true`
+where the same skin/slot/attachment in the build did not state true, and the
+build's authored setup polygon has a reflex vertex, it prints:
+
+```text
+FAIL  EDITOR_ADDED_CONVEX_ON_CONCAVE_CLIP skin "S" slot "C" attachment "A" end "E": export convex=true, build convex is not true; setup reflex vertices=N; the editor's export clips with the convex hull of the authored concave polygon
+```
+
+The setup polygon is read through the runtime with that skin applied, setup
+bones and constraints posed, and the slot's deform empty, as for the renderer's
+authored rest geometry. Weighted vertex runs are therefore read as posed points,
+not mistaken for coordinate pairs; animation-time deformation is not substituted
+for the authored setup shape. Reflex turns are counted in either winding and
+straight boundary vertices do not make a convex polygon concave. A convex setup
+polygon or a build already stating `convex: true` adds no line. The named failure
+makes the trip exit nonzero **after** the existing per-skin render/check figures
+are printed; it does not replace those measurements. It changes neither compiler
+emission nor coordinates, and does not imply that removing the export's flag
+undoes the editor's other changes.
+
 🔬 The source is one run: eight discriminator rigs, each built to isolate a group
 of fields, compiled by rigc **0.21.0** (emitting 4.3.13), imported into a licensed
 Spine **4.3.26** through the documented CLI and exported back, with the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.79.0",
+  "version": "2.81.0",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/skills/rigc/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc
 description: Author, build and validate Spine 4.3 skeleton data (skeleton.json plus its .atlas) from loose part PNGs with rigc, the rig compiler that verifies its own output with named assertions before writing it. Use for any request to make a Spine rig or Spine animation from PNG parts, or where the source is a Live2D, Unity or video model whose pictures you can render, to run or read rigc build, validate, render, preview, check or vote, or to write or fix a *.rig.json or *.motion.json spec; it says which shipped guide to open for the need at hand. Not for Live2D conversion, cutting an illustration into parts, or real-time face tracking.
 license: MIT
-compatibility: Requires Bun 1.4 or later. The tool is the npm package rig-c (bunx rig-c, or bun add -d rig-c); the command it installs is rigc.
+compatibility: Requires Bun 1.4 or later. The canonical npm package is @rig-c/core (bunx @rig-c/core, or bun add -d @rig-c/core); the command it installs is rigc. rig-c is the convenience install name; spine-rigc is the legacy install name.
 ---
 
 # rigc — a rig compiler for agents
@@ -46,8 +46,8 @@ index within that same limit; only legacy uncoded library errors point at `§5.1
 ## Install
 
 ```shell
-bunx rig-c --help       # run it without installing
-bun add -d rig-c        # or pin it in the project; the command is `rigc`
+bunx @rig-c/core --help       # run it without installing
+bun add -d @rig-c/core        # or pin it in the project; the command is `rigc`
 bun rigc skills install      # then link these skills into .agents/skills
 ```
 
@@ -145,8 +145,8 @@ spec files field by field, the emission rules, the loop, and the failure map. Th
 | a **skeleton.json somebody else authored** — read it, repair it, extend it | [INGEST.md](https://github.com/rig-c/core/blob/main/docs/INGEST.md) | `rigc-ingest` |
 | you are the **person operating** the agent rather than the agent | [PROMPTING.md](https://github.com/rig-c/core/blob/main/docs/PROMPTING.md) | — |
 
-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/`.
 Formats, the CLI reference and the licence chain:
-[README.md](https://github.com/rig-c/core/blob/main/README.md), installed at `node_modules/rig-c/README.md`.
+[README.md](https://github.com/rig-c/core/blob/main/README.md), installed at `node_modules/@rig-c/core/README.md`.

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;
+    },
   };
 }
 
@@ -581,6 +596,28 @@ function setupPosed(data: SkeletonData, skin: string | undefined): Skeleton {
   return skeleton;
 }
 
+/** A named clip's authored setup polygon under its own skin, with no deform. */
+export function setupClipPolygon(
+  data: SkeletonData,
+  skin: string,
+  slotName: string,
+  attachmentName: string,
+): number[] {
+  const skeleton = setupPosed(data, skin);
+  const index = data.findSlot(slotName)?.index ?? -1;
+  const slot = skeleton.slots[index];
+  const attachment = data.findSkin(skin)?.getAttachment(index, attachmentName);
+  if (slot === undefined || !(attachment instanceof ClippingAttachment)) {
+    throw new Error(
+      `setup clip skin ${JSON.stringify(skin)} slot ${JSON.stringify(slotName)} attachment ${JSON.stringify(attachmentName)} did not resolve`,
+    );
+  }
+  slot.appliedPose.deform.length = 0;
+  const polygon = new Array<number>(attachment.worldVerticesLength).fill(0);
+  attachment.computeWorldVertices(skeleton, slot, 0, attachment.worldVerticesLength, polygon, 0, 2);
+  return polygon;
+}
+
 /**
  * Both posers for the skeleton at `skeletonPath` drawn through the atlas at
  * `atlasPath`, with spine-core's parse of it already in hand (`data`) — the
@@ -781,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)];
 }
 

package/tools/editor_roundtrip.ts

@@ -917,6 +917,75 @@ export function skinRoster(
   };
 }
 
+/** An attachment's declaration key, kept separate from its skin and slot. */
+interface ClipFlagSkin {
+  name: string;
+  attachments?: Record<string, Record<string, { type?: string; convex?: boolean; end?: string }>>;
+}
+
+/** Reflex turns of the world's own doubles, winding independent; straight turns are not reflex. */
+function reflexVertices(polygon: readonly number[]): number {
+  const n = polygon.length / 2;
+  let area2 = 0;
+  for (let i = 0; i < n; i++) {
+    const j = (i + 1) % n;
+    area2 += polygon[2 * i] * polygon[2 * j + 1] - polygon[2 * j] * polygon[2 * i + 1];
+  }
+  const winding = Math.sign(area2);
+  if (winding === 0) return 0; // Degenerate geometry is the validator's refusal.
+  let count = 0;
+  for (let i = 0; i < n; i++) {
+    const j = (i + 1) % n;
+    const k = (i + 2) % n;
+    const turn =
+      (polygon[2 * j] - polygon[2 * i]) * (polygon[2 * k + 1] - polygon[2 * j + 1]) -
+      (polygon[2 * j + 1] - polygon[2 * i + 1]) * (polygon[2 * k] - polygon[2 * j]);
+    if (turn !== 0 && Math.sign(turn) !== winding) count++;
+  }
+  return count;
+}
+
+/**
+ * An editor-added convex flag changes a concave clip's meaning (issue #1630).
+ * Compare the same skin/slot/attachment, then read the BUILD's posed authored
+ * setup polygon. Weighted runs are not points; an animation deform is not the
+ * authored setup shape. Empty deform follows the renderer's `restOf` convention.
+ * Imports are lazy so the existing no-editor/trial/read refusals need no runtime.
+ */
+async function addedConvexClipFailures(build: string, exported: string, buildDir: string): Promise<string[]> {
+  const before = (JSON.parse(readFileSync(build, 'utf8')) as { skins?: ClipFlagSkin[] }).skins;
+  const after = (JSON.parse(readFileSync(exported, 'utf8')) as { skins?: ClipFlagSkin[] }).skins;
+  const candidates: Array<{ skin: string; slot: string; attachment: string; end: string | null }> = [];
+  for (const skin of Array.isArray(after) ? after : []) {
+    const originalSkin = (Array.isArray(before) ? before : []).find((s) => s.name === skin.name);
+    for (const [slot, attachments] of Object.entries(skin.attachments ?? {})) {
+      for (const [attachment, clip] of Object.entries(attachments)) {
+        const original = originalSkin?.attachments?.[slot]?.[attachment];
+        if (clip.type === 'clipping' && clip.convex === true && original?.type === 'clipping' && original.convex !== true) {
+          candidates.push({ skin: skin.name, slot, attachment, end: original.end ?? null });
+        }
+      }
+    }
+  }
+  if (candidates.length === 0) return [];
+  const { posableFromText, setupClipPolygon } = await import('../src/render.ts');
+  const atlas = readdirSync(buildDir).find((name) => name.endsWith('.atlas'))!;
+  const { data } = posableFromText(readFileSync(build, 'utf8'), readFileSync(join(buildDir, atlas), 'utf8'), buildDir);
+  const lines: string[] = [];
+  for (const candidate of candidates) {
+    const polygon = setupClipPolygon(data, candidate.skin, candidate.slot, candidate.attachment);
+    const reflex = reflexVertices(polygon);
+    if (reflex > 0) {
+      lines.push(
+        `  FAIL  EDITOR_ADDED_CONVEX_ON_CONCAVE_CLIP skin ${JSON.stringify(candidate.skin)} slot ${JSON.stringify(candidate.slot)} ` +
+          `attachment ${JSON.stringify(candidate.attachment)} end ${JSON.stringify(candidate.end)}: export convex=true, build convex is not true; ` +
+          `setup reflex vertices=${reflex}; the editor's export clips with the convex hull of the authored concave polygon`,
+      );
+    }
+  }
+  return lines;
+}
+
 /**
  * One measure of a `diff --json` report as `matched/total (ratio)`, or `null`
  * when the report or the measure is not there — read off the report for the
@@ -1185,7 +1254,7 @@ function imagesProbeFault(skeleton: Record<string, unknown>): string | null {
   return null;
 }
 
-function main(): void {
+async function main(): Promise<void> {
   const opts = parseArgs(process.argv.slice(2));
   const rigc = rigcCommand();
 
@@ -1489,6 +1558,21 @@ function main(): void {
   // console layout for them would break the first time that layout is tidied.
   for (const line of diffSummaryLines(diffJson)) emit(`  ${line}`);
 
+  // Report the changed meaning without skipping any later per-skin figures.
+  let clipFailures: string[];
+  try {
+    // An unreadable export has no semantic comparison. Leave its established
+    // gate/read failure intact (including the late-read planted controls).
+    clipFailures = gate.status === 0 ? await addedConvexClipFailures(source, join(cand, 'skeleton.json'), opts.build) : [];
+  } catch (error) {
+    return fail(`could not measure clipping setup geometry: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (clipFailures.length > 0) {
+    emit('');
+    emit('## 4.1 clipping semantics');
+    for (const line of clipFailures) emit(line);
+  }
+
   // 🔒 The skins come off BOTH files, compared before anything is rendered
   // (issue #801). A skin the export dropped is named here as LOST BY THE EXPORT
   // and fails the run; enumerating the export's skins alone would quietly stop
@@ -1627,7 +1711,7 @@ function main(): void {
   // is the half a single un-skinned check could not say.
   // A version line that disagrees with the export is red too (issue #1199): the
   // report would otherwise name an editor the trip did not run on, green.
-  process.exit(gate.status === 0 && checksClean && rosterClean && !versionDisagrees ? 0 : 1);
+  process.exit(gate.status === 0 && checksClean && rosterClean && !versionDisagrees && clipFailures.length === 0 ? 0 : 1);
 }
 
 // ⭐ Guarded so `shapeOf`, `shapeDiff`, `skinsDeclaredBy` and `skinBlocks` can be
@@ -1638,4 +1722,4 @@ function main(): void {
 // reach either would be paying for a round trip to test arithmetic. Run as a
 // program this is unchanged: `bun tools/editor_roundtrip.ts …` makes this module
 // the entry, so `import.meta.main` is true.
-if (import.meta.main) main();
+if (import.meta.main) await main();