spine-rigc 3.2.1 → 3.4.0

package/docs/AUTHORING.md

@@ -130,6 +130,7 @@ commands take it and what its default is.
 | `split --rig … --motion … --slot <name> --out <dir>` | the answer to a mesh refused because its triangles are **several pieces that share no vertex** — two legs after the triangles bridging them were deleted. It reads the two specs and writes them back into an absent or empty `--out` with one mesh per piece: piece 1 stays in the slot, piece k gets a new slot `<slot>_<k>` after it, each with the original's uvs and weights unchanged, its triangles renumbered outline first where the hull rule needs it, and every deform key re-sliced to the new indices — plus `split.json`, where every original vertex and triangle went. One piece is said so and nothing is written; what it cannot carry is refused by name ([AUTHORING §3.4.11](../docs/AUTHORING.md)) <a id="cmd-split"></a> |
 | `explain --rig … --motion …` | the compiled rig as a table — every bone with its resolved parent, the slots in draw order, every timeline key by key. Writes nothing. What to reach for when a rig compiles and still looks wrong <a id="cmd-explain"></a> |
 | `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`, one directory per set: `<anim>@<fps>fps/` rather than `<anim>/` at any rate but the default — `--fps 24` writes `<anim>@24fps/`, and the default 12 writes `<anim>/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid. `--folds` adds a `folds.json` per set and prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count and which triangles, their world box and their setup-pose area. `--pass-through <cloth>:<leg>` adds a `pass-through.json` per set and prints the frames where a cloth drawn over a leg has its side inside the leg's drawn outline, with the depth and the world box — a reading, not a gate. `--seam <slot>:<slot>` adds a `seam.json` per set and prints, per pair, the frames where two slots that meet open background inside the joint (a gap) or show the overlap band of one past the other (a ghost), with the worst frame's cell count and world box; `ghostA` and `ghostB` partition the same ghost by which named pair member drew it, each with its own frames, spans and worst; `gapOpen` and `gapCovered` partition `gap` by zero versus positive rendered alpha from the whole skeleton, including faint and clipped drawings; ghost counts only visible contributions after draw order; `exposureA`/`exposureB` report each named slot’s whole-drawing background exposure even without a band ([AUTHORING §8.8](../docs/AUTHORING.md#88-where-two-slots-stop-meeting--render---seam)) — a reading, not a gate; the exit status never moves. `--overlaps` adds an `overlaps.json` per set and prints one `OVERLAP "<under>" under "<over>"` line per pair of slots where the one drawn later covers the earlier one and the motion moves it — the frames, and the most pixels covered and the frame of them — with an outline plate per covered frame; the render reports what was drawn, and the draw-order key is the author's remedy — a reading, not a gate. `--extremes` adds `extremes.json` and a native six-panel `extremes.png` (setup, geometry-pair min/max and three premultiplied RGBA diffs with a legend), plus one `EXTREMES` line per set. Per-channel minima/maxima and the farthest original-vertex geometry pair are distinct readings; valid channel extrema survive a geometry/image SKIP, with channel refusals reported separately; still or uncomparable geometry reports a named SKIP without changing render exit status. `--extremes-only` writes the same `extremes.json` and readable `extremes.png` bytes while skipping ordinary frame rasterization/encoding, `contact.png` and `frames.json`; it implies `--extremes` and takes no other diagnostic or sheet output flags. Look at min, max and diff before a person does ([AUTHORING §8.11](../docs/AUTHORING.md#811-min-max-and-diff-before-a-person-looks--render---extremes)). `--angle-range <bone>:<relative-to>` prints how far one bone turns against another over each set: the lowest and highest angle and the frames they fall on — a reading, not a gate. `--viewport <x,y,w,h>` or `--viewport-from <frames.json>` draws over a given box instead of a fitted one, so two builds land on one pixel grid; a slot that reaches past it is named by set and frame, and `frames.json` records it. `--environment <schedule.json>` draws the rig under the wind and gravity its physics answers, in time — the same frames on the core and on spine-core; an inspection of the response the rig states, not a scene. `--preroll <n>` walks each set `n` whole loops on a looping track before the loop it records, so a looping idle is drawn with its physics already warm, as a player's looping track carries it ([AUTHORING §8.13](../docs/AUTHORING.md#813-a-loop-with-its-physics-warm--render---preroll)). `--sheet [--sheet-format json-hash] [--page-edges pot\|free]` also packs each set's straight-alpha transparent frames into `sheet.png` + `sheet.json` (TexturePacker JSON Hash with a shared world-origin `anchor` and `2`-px clamped edge extrusion, verified through `pixi.js@8.22.0` and `phaser@3.90.0` by `tools/sheet_readers.ts`) and `sheet-manifest.json` (`rigc-sheet/1`), leaving diagnostic `f####.png` and `contact.png` unchanged ([AUTHORING §8.10](../docs/AUTHORING.md#810-sprite-sheets-from-a-render--render---sheet)) — a self-contained sprite object per animation set; when animations play and how a scene is composed remains the consumer's <a id="cmd-render"></a> |
+| `render … --physics off --boundary-from <dir>` | Suppress every physics constraint on both posers and read visible boundary displacement from a second render on the same viewport and frame grid. `frames.json` records off, `check` refuses it as a reference, and `boundary.json` carries per-frame distances or named SKIPs. See §8.14. |
 | `preview --candidate <dir>` | one self-contained `.html` that plays it, headed by the line `validate <dir>` prints for it and the rigc version — a refused candidate is still previewed, and its header says so in the gate's words. Repeat `--candidate` for one page with a pane per candidate, in the order given; a green `build` ends by naming this command for its own `--out` <a id="cmd-preview"></a> |
 | `vote --candidate a --candidate b` | one `.html` that asks a human which; `vote --record <file>` checks the answer into `votes.jsonl` <a id="cmd-vote"></a> |
 | `pose --images <dir> --frame <png>` | reads part placements **out of** a picture <a id="cmd-pose"></a> |
@@ -377,11 +378,12 @@ What the flags mean:
 | `--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-only` | `render` only: imply `--extremes`, but write only `extremes.json` and readable `extremes.png` with the same bytes. Pose the same grid; rasterize only the setup/min/max pictures used by the plate. No ordinary frame PNGs, contact sheet or `frames.json`. Takes no `--sheet`, `--sheet-format`, `--page-edges`, `--geometry`, `--folds`, `--pass-through`, `--seam`, `--overlaps` or `--angle-range`; drop the named flag or use `--extremes` instead — **§8.11** |
+| `--extremes-only` | `render` only: imply `--extremes`, but write only `extremes.json` and readable `extremes.png` with the same bytes. Pose the same grid; rasterize only the setup/min/max pictures used by the plate. No ordinary frame PNGs, contact sheet or `frames.json`. Takes no `--sheet`, `--sheet-format`, `--page-edges`, `--geometry`, `--folds`, `--pass-through`, `--seam`, `--seam-cells`, `--overlaps` or `--angle-range`; drop the named flag or use `--extremes` instead — **§8.11** |
 | `--parallax` | `render` only: a named slider dial, through the core poser. Write `parallax.json` and a readable `parallax.png` into `--out` on a fixed 9-value grid. This is a separate dial render mode, with `--skin`, `--max`, `--candidate`, `--atlas` and `--poser core`; it takes no animation, fps, subset, other diagnostic, sheet, environment or viewport flag. A missing dial is refused by name; unavailable fits report SKIP, never a pass — **§8.12** |
 | `--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-cells` | `render` only, with `--seam`: add exact `cells` lists to `gapOpen`/`gapCovered` hits (including `worst`), with setup-pose top and underlying slot names at the same world cell. Without `--seam` it is refused before output. No effect on the counts — **§8.8** |
 | `--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 visible overlap band of one showing where, from its partner's point of view, nothing was drawn), plus `exposureA`/`exposureB` for each named slot’s positive-alpha drawing on otherwise empty skeleton background, 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** |
 | `--overlaps` | `render` only: also read **which slot each frame drew over which**, and write an `overlaps.json` into each frame directory: per frame, every pair of slots where the slot drawn later covers pixels the earlier one drew (drawn at 128 of 255 or more, on the frames' own pixels), with the pixel count and the pixel box. One `OVERLAP` line per pair that covers anything — its frames as runs, how many of the set, and the most pixels and the frame of them — and one line counting the pairs that are layering the motion does not move. 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. Every other file is byte for byte what the render writes without it, and `frames.json` gains each set's `overlaps` record. Refused beside `--slot`/`--hide` — **§8.9** |
 | `--angle-range` | `render` only: `<bone>:<relative-to>[,<bone>:<relative-to>…]` — also read, for each pair, the range of the first bone's world direction against the second's over each set's frames, and print one line per pair per set: the lowest and the highest angle in degrees, the span, and the frame each was first reached on. A reading, not a gate: nothing is written, and every file is the bytes the render writes without it. An unknown bone (with the bones there are), a bone against itself, a malformed list and a pair named twice are refused by name, and so is a bone with no direction on a frame — **§8.7** |
@@ -9395,6 +9397,33 @@ block carries the definitions above in words.
 | hit `area` | number | world units² | `px × cell²` |
 | hit `box` | `[minX, minY, maxX, maxY]` | world units, y up | the counted cells' whole squares, in Spine world |
 
+**Exact cells, opt-in.** Add `--seam-cells` beside `--seam` to retain the
+cells counted by the existing gap classifier. Only `gapOpen` and `gapCovered`
+hits gain `cells`; `gap`, `ghost` and exposure hits keep their old shape. Each
+entry is `{ x, y, setupTop, setupUnder }`: `x,y` are the cell **centre** in world
+units, y up; the hit's `cell` gives the square's side. Lists are in descending
+`y`, then ascending `x` order (top row first, left to right), with no duplicates.
+Every nonempty hit has `cells.length === px`; absent hits still mean zero and
+SKIP pairs remain unmeasured. `worst` carries the same list as its frame hit.
+
+`setupTop` is the topmost slot whose setup drawing emits positive rendered alpha
+at that **same world cell**, and `setupUnder` is the next distinct covering slot
+beneath it in setup draw order. Each is a slot name or `null` if absent. All
+slots participate, including third slots, faint alpha, texture holes and clipped
+fragments; multiple fragments of one slot count as one layer. These are setup
+layers, not the current frame's cover, not spatial neighbors, and not a cell
+carried back by the seam's inverse attachment maps. A currently open cell can
+therefore name setup art; a cell beyond all setup art has two null names.
+
+This is an additive opt-in extension of **`rigc-seam/1`**: readers ignoring
+unknown hit keys retain every existing number and meaning. Exact-object readers
+must opt into the new shape. With the flag absent no setup attribution is sampled
+or rasterized and the sidecar bytes remain unchanged. With it present, setup is
+sampled lazily once per recipe/skin and its rendered-alpha layers are cached per
+distinct seam cell side across pairs and animation sets; only listed cells query
+the cache. Determinism controls compare two complete flagged renders, not just
+list lengths.
+
 A downstream warning is a projection of this file and needs nothing re-measured:
 one span of one kind is `{ pair: "<a>|<b>", frames: span.frames, times:
 span.times, maxPx: span.maxPx, kind }`, and one pair over one animation is
@@ -9950,6 +9979,53 @@ still refused above 0, would reach the same looping walk; counted in steps rathe
 than loops, it would move every compared frame off its `FrameRef` time unless the
 steps were whole loops.
 
+### 8.14 Physics-off renders and boundary comparisons
+
+`rigc render --candidate <dir> --physics off --out <off>` suppresses every physics
+constraint on both posers, after the animation timelines apply. Every other
+constraint and the animation clock keep their ordinary walk. `--physics on` is the
+default. Any other value is refused by name. An omitted mode retains the existing
+render bytes. Off records `physicsMode: "off"` in `frames.json`, geometry and sheet
+metadata, and adds a `physics=off` variant to sheet frame keys. A reference
+without the field means on. `check` refuses an off reference because its candidate
+is posed with physics on.
+
+To compare two whole-figure renders, first render the reference, then render the
+second with `--viewport-from <reference-dir> --boundary-from <reference-dir>`.
+For example, render the public gallery physics recipe normally, then render it
+with those two flags and `--physics off`. Use the same animation selection, skin,
+fps and pre-roll on both runs. The shared viewport fixes the world box, scale and
+pixel dimensions. Check the viewport's recorded `pinned.outside` when interpreting
+an outline that reaches the canvas edge.
+
+`boundary.json` (`rigc-boundary-difference/1`) records each matching frame's maximum
+symmetric nearest-boundary distance in **L-infinity pixels**, and the maximum over
+the frames read. A boundary pixel is visible foreground with at least one
+four-neighbour background pixel, or a foreground pixel on the canvas edge. Holes
+contribute boundaries too. Foreground means the rendered RGBA differs from the
+recorded background exactly. Background-coloured art has no observable coverage
+in this reading, and anything outside the viewport is absent. This is a pixel
+reading with no registration, threshold or pass verdict.
+
+An identical on/on pair reads zero. An on/off pair measures the visible outline
+change on the chosen grid. Empty boundaries report `SKIP`, never zero. A frame
+schedule, viewport, background, skin, set roster or file mismatch also reports
+`SKIP` with a reason. Missing or unreadable frames remain unavailable. Mixed
+readable and empty frames report `PARTIAL` with the per-frame reasons. Both sides
+must record the same slot selection. `scope` records that selection explicitly. A backdrop is part of the visible outline when it is drawn, so a
+full-canvas opaque backdrop can make the distance zero even while the character
+moves. For `gallery/look`, use `--hide plate` on both renders to read the character
+without its backdrop. Every other drawn slot still contributes to that outline.
+`--extremes-only` takes no `--boundary-from`, and the reference directory must differ
+from `--out`. Reusing an output directory clears its previous `boundary.json`
+before writing the new render, including an `--extremes-only` render.
+
+`--extremes` chooses a pair within one animation and reads corresponding authored
+vertices and local channels. Subtracting two extreme readings does not compare
+the same frames' visible outlines. `diff` compares skeleton data, and `check`
+reposes and registers a candidate against reference pictures. Neither reads two
+already-rendered whole-figure boundaries on an unchanged grid.
+
 ## 9. Checking against the frames — `rigc check`
 
 ```bash

package/package.json

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

package/src/boundary.ts

@@ -0,0 +1,129 @@
+/** Visible boundary displacement on the recorded pixel grid, without registration or thresholds. */
+import { readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { readPlate, type Plate, type RGBA } from '../tools/plate.ts';
+import { FRAMES_SPEC, type FramesSidecar } from './render_shared.ts';
+
+type DistanceReading = { status: 'READ'; maxPixels: number } | { status: 'SKIP'; reason: string };
+
+/** Background-coloured pixels carry no observable foreground coverage. */
+export function visibleBoundary(plate: Plate, background: RGBA): number[] {
+  const { width, height, data } = plate;
+  const foreground = new Uint8Array(width * height);
+  for (let pixel = 0; pixel < foreground.length; pixel++) {
+    foreground[pixel] = background.some((value, channel) => data[pixel * 4 + channel] !== value) ? 1 : 0;
+  }
+  const boundary: number[] = [];
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const pixel = y * width + x;
+      if (foreground[pixel] && (
+        x === 0 || y === 0 || x === width - 1 || y === height - 1 ||
+        !foreground[pixel - 1] || !foreground[pixel + 1] ||
+        !foreground[pixel - width] || !foreground[pixel + width]
+      )) boundary.push(pixel);
+    }
+  }
+  return boundary;
+}
+
+/** Exact eight-neighbour nearest-boundary distance in L-infinity pixels. Linear in canvas area. */
+function distances(width: number, height: number, boundary: readonly number[]): Int32Array {
+  const distance = new Int32Array(width * height).fill(-1);
+  const queue = new Int32Array(distance.length);
+  let end = 0;
+  for (const pixel of boundary) {
+    distance[pixel] = 0;
+    queue[end++] = pixel;
+  }
+  for (let head = 0; head < end; head++) {
+    const pixel = queue[head];
+    const x = pixel % width;
+    const y = Math.floor(pixel / width);
+    for (let dy = -1; dy <= 1; dy++) {
+      for (let dx = -1; dx <= 1; dx++) {
+        const nextX = x + dx, nextY = y + dy;
+        if (nextX < 0 || nextY < 0 || nextX >= width || nextY >= height) continue;
+        const next = nextY * width + nextX;
+        if (distance[next] !== -1) continue;
+        distance[next] = distance[pixel] + 1;
+        queue[end++] = next;
+      }
+    }
+  }
+  return distance;
+}
+
+export function boundaryDistance(a: Plate, b: Plate, background: RGBA): DistanceReading {
+  if (a.width !== b.width || a.height !== b.height) return { status: 'SKIP', reason: 'pixel dimensions differ' };
+  const left = visibleBoundary(a, background), right = visibleBoundary(b, background);
+  if (left.length === 0 || right.length === 0) {
+    return { status: 'SKIP', reason: 'one or both frames have no visible foreground boundary' };
+  }
+  const toLeft = distances(a.width, a.height, left), toRight = distances(a.width, a.height, right);
+  let maxPixels = 0;
+  for (const pixel of left) maxPixels = Math.max(maxPixels, toRight[pixel]);
+  for (const pixel of right) maxPixels = Math.max(maxPixels, toLeft[pixel]);
+  return { status: 'READ', maxPixels };
+}
+
+const SCHEDULE_FIELDS = ['animation', 'fps', 'sampled', 'written', 'stride', 'duration'] as const;
+
+/** A failed observation remains a named SKIP and never becomes a zero distance. */
+export function boundaryComparison(reference: string, current: string, sidecar: FramesSidecar) {
+  const spec = 'rigc-boundary-difference/1';
+  const skip = (reason: string) => ({ spec, status: 'SKIP' as const, reason });
+  try {
+    if (realpathSync(reference) === realpathSync(current)) return skip('reference and output directories are the same');
+    const before = JSON.parse(readFileSync(join(reference, 'frames.json'), 'utf8')) as FramesSidecar;
+    if (before.spec !== FRAMES_SPEC || !Array.isArray(before.sets)) return skip('reference requires a render frames.json');
+    const coordinates = Object.keys(sidecar.viewport) as Array<keyof typeof sidecar.viewport>;
+    if (!before.viewport || coordinates.some((key) => !Number.isFinite(before.viewport[key]) || before.viewport[key] !== sidecar.viewport[key])) {
+      return skip('world viewport or pixel grid differs, use --viewport-from');
+    }
+    if (JSON.stringify(before.background) !== JSON.stringify(sidecar.background)) return skip('recorded backgrounds differ');
+    if (before.skin !== sidecar.skin || JSON.stringify(before.slots) !== JSON.stringify(sidecar.slots) || JSON.stringify(before.hidden) !== JSON.stringify(sidecar.hidden)) {
+      return skip(`skin or drawn slot selection differs: reference ${JSON.stringify({ skin: before.skin ?? null, slots: before.slots ?? null, hidden: before.hidden ?? null })}, current ${JSON.stringify({ skin: sidecar.skin ?? null, slots: sidecar.slots ?? null, hidden: sidecar.hidden ?? null })}. Required equal recorded selections`);
+    }
+    const frames: Array<{ set: string; file: string } & DistanceReading> = [];
+    for (const set of sidecar.sets) {
+      const match = before.sets.find((other) => other.dir === set.dir);
+      if (!match || SCHEDULE_FIELDS.some((key) => match[key] !== set[key])) {
+        return skip(`set ${JSON.stringify(set.dir)} has a different frame schedule`);
+      }
+      if (!set.dir || set.dir === '..' || set.dir === '.' || set.dir.includes('/') || set.dir.includes('\\')) {
+        return skip('set directory must be one relative directory name');
+      }
+      const names = (root: string): string[] => readdirSync(join(root, set.dir)).filter((name) => /^f\d+\.png$/.test(name)).sort();
+      const left = names(reference), right = names(current);
+      if (left.length === 0 || left.length !== set.written || JSON.stringify(left) !== JSON.stringify(right)) {
+        return skip(`set ${JSON.stringify(set.dir)} has missing or different frame files`);
+      }
+      for (const file of left) {
+        const a = readPlate(join(reference, set.dir, file)), b = readPlate(join(current, set.dir, file));
+        if ([a, b].some((plate) => plate.width !== sidecar.viewport.pixelWidth || plate.height !== sidecar.viewport.pixelHeight)) {
+          return skip(`set ${JSON.stringify(set.dir)} frame ${file} pixel dimensions disagree with frames.json`);
+        }
+        frames.push({ set: set.dir, file, ...boundaryDistance(a, b, sidecar.background) });
+      }
+    }
+    if (before.sets.length !== sidecar.sets.length || frames.length === 0) return skip('set roster differs or no frames were compared');
+    const readings = frames.filter((frame) => frame.status === 'READ');
+    let maxPixels = 0;
+    for (const frame of readings) if (frame.status === 'READ') maxPixels = Math.max(maxPixels, frame.maxPixels);
+    return {
+      spec,
+      status: readings.length === frames.length ? 'READ' : readings.length ? 'PARTIAL' : 'SKIP',
+      metric: 'symmetric Hausdorff L-infinity pixels',
+      coverage: 'visible pixels differing from the recorded background. Four-neighbour boundary including holes, clipped to viewport',
+      referencePhysics: before.physicsMode ?? 'on',
+      physics: sidecar.physicsMode ?? 'on',
+      scope: { slots: sidecar.slots ?? null, hidden: sidecar.hidden ?? null },
+      viewport: sidecar.viewport,
+      maxPixels: readings.length ? maxPixels : null,
+      frames,
+    };
+  } catch (error) {
+    return skip(`boundary unavailable: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}

package/src/check.ts

@@ -1298,6 +1298,9 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
         'difference between two worlds. Render the reference frames without --environment.',
     );
   }
+  if (located.sidecar?.physicsMode === 'off') {
+    throw new CheckError('frames.json records physicsMode off, while check poses the candidate with physics on. Render the reference with --physics on.');
+  }
   // A frame set drawn after a pre-roll (`render --preroll`, issue #1684) shows the physics warm; check poses the
   // candidate from rest, so the score would be a number about the difference between a warm loop and a cold one.
   const referencePreroll = located.sidecar?.preroll;

package/src/cli/core_commands.ts

@@ -1,3 +1,4 @@
+import { boundaryComparison } from '../boundary.ts';
 import { sampleParallax, parallaxPlate } from '../parallax_render.ts';
 import { textureScaleReading, textureScaleLines, TEXTURE_SCALE_FPS } from '../texture_scale.ts';
 import { extremesOf, extremesText, extremesPlate, extremesLine, extremesRefusal } from '../extremes.ts';
@@ -44,7 +45,7 @@ import { PASS_THROUGH_FILE, passFrameLine, type PassPair, passSummaryLine, passT
 import type { Plate } from '../../tools/plate.ts';
 import { OVERLAPS_FILE, OverlapError, overlapLine, overlapPlate, overlapsFileOf, overlapsOf, overlapsPlateFile, overlapsText, plateParticipants, staticLine } from '../overlaps.ts';
 import { buildSheetSet, SHEET_MANIFEST_FILE, type SheetSetPack, SheetUsageError, sheetRigNameOf, sheetSidecarRecord, sheetSourceOf } from '../sheet.ts';
-import { readSeamPairs, SEAM_FILE, seamFileOf, seamLine, SeamError, type SeamPair, seamsOf, seamText } from '../seam.ts';
+import { readSeamPairs, SEAM_FILE, seamFileOf, seamLine, SeamError, type SeamPair, seamsOf, seamText, setupCellReader } 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, prerollStart, prerollWarmPoints, PROTOCOL_FPS, refuseUnchosen, renderFrame, sampleAll, sampleAnimation, sampleSetupPose, SETUP_POSE_DIR, SHEET_FILE, SHEET_TILE, sidecarViewport, type SkeletonFacts, type SlotSubset, SlotSubsetError, throughPoser, type Viewport, viewportFor } from '../render_shared.ts';
@@ -723,6 +724,8 @@ export function cmdRender(flags: Record<string, string>): void {
   // The pre-roll (issue #1684), read and refused as early, and refused beside a schedule: under a pre-roll a schedule's
   // `t` could be read on the recording's clock or on the walk's, the two give different physics, and nothing settles it.
   const preroll = readPrerollFlag(flags);
+  if (flags.physics !== undefined && flags.physics !== 'on' && flags.physics !== 'off') throw new UsageError(`--physics ${JSON.stringify(flags.physics)}: required on or off`);
+  const physicsMode = flags.physics === 'off' ? 'off' as const : undefined;
   if (preroll !== undefined && environment !== undefined) {
     throw new UsageError(
       `--preroll takes no --environment: a schedule's t could be read from the first frame recorded or from the first loop walked, ` +
@@ -734,7 +737,7 @@ export function cmdRender(flags: Record<string, string>): void {
   const given = readGivenViewport(flags);
   const extremesOnly = flags['extremes-only'] !== undefined;
   if (extremesOnly) {
-    for (const flag of ['sheet', 'sheet-format', 'page-edges', 'geometry', 'folds', 'pass-through', 'seam', 'overlaps', 'angle-range']) {
+    for (const flag of ['sheet', 'sheet-format', 'page-edges', 'geometry', 'folds', 'pass-through', 'seam', 'seam-cells', 'overlaps', 'angle-range', 'boundary-from']) {
       if (flags[flag] !== undefined) {
         throw new UsageError(`--extremes-only takes no --${flag}: it writes only extremes.json and, when readable, extremes.png. Drop --${flag}, or use --extremes for ordinary frames and additional outputs`);
       }
@@ -753,6 +756,7 @@ export function cmdRender(flags: Record<string, string>): void {
   const sheetFormat = wantsSheet ? readSheetFormat(flags) : undefined;
   const sheetPageEdges = wantsSheet ? readPageEdges(flags) : undefined;
   const outRoot = resolve(flags.out ?? 'render');
+  if (flags['boundary-from'] !== undefined && realpathAhead(flags['boundary-from']) === realpathAhead(outRoot)) throw new UsageError('--boundary-from must name an earlier render directory different from --out');
   const geometry = flags.geometry !== undefined;
   const extremes = extremesOnly || flags.extremes !== undefined;
   // The fold reading (issue #1383) is its own flag rather than a part of --geometry, so a caller that asked for
@@ -823,6 +827,8 @@ export function cmdRender(flags: Record<string, string>): void {
   // The seam reading (issue #1456) is its own flag for --folds' reason, and refused beside a subset for --pass-through's:
   // it reads the two slots as the whole rig draws them.
   const seam = flags.seam;
+  const seamCells = flags['seam-cells'] !== undefined;
+  if (seamCells && seam === undefined) throw new UsageError('--seam-cells needs --seam <slot>:<slot>[,…]; no pair was supplied');
   if (seam !== undefined) {
     for (const flag of ['slot', 'hide'] as const) {
       if (flags[flag] !== undefined) {
@@ -850,7 +856,7 @@ export function cmdRender(flags: Record<string, string>): void {
     posersAsked(flags),
   );
   if (flags.parallax !== undefined) {
-    for (const flag of ['animation', 'fps', 'slot', 'hide', 'geometry', 'folds', 'extremes', 'extremes-only', 'pass-through', 'seam', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'preroll', 'viewport', 'viewport-from']) {
+    for (const flag of ['animation', 'fps', 'slot', 'hide', 'geometry', 'folds', 'extremes', 'extremes-only', 'pass-through', 'seam', 'seam-cells', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'preroll', 'physics', 'boundary-from', 'viewport', 'viewport-from']) {
       if (flags[flag] !== undefined) throw new UsageError(`--parallax takes no --${flag}: it samples one named dial on its own 9-value grid; drop --${flag} or run ordinary render separately`);
     }
     if (flags.poser !== undefined && flags.poser !== 'core') throw new UsageError('--parallax requires --poser core: it reads only a rigc compiled model');
@@ -898,13 +904,14 @@ export function cmdRender(flags: Record<string, string>): void {
   // what the frames under it draw.
   // The pre-roll rides on it for the environment's reason (issue #1684): it changes the pose, so the framing reads it.
   const pose =
-    skin === undefined && subset === undefined && environment === undefined && preroll === undefined
+    skin === undefined && subset === undefined && environment === undefined && preroll === undefined && physicsMode === undefined
       ? undefined
       : {
           ...(skin === undefined ? {} : { skin }),
           ...subsetFields(subset),
           ...(environment === undefined ? {} : { environment: environment.steps }),
           ...(preroll === undefined ? {} : { preroll }),
+          ...(physicsMode === undefined ? {} : { physicsMode }),
         };
   if (skin !== undefined) console.log(`  ..    skin     ${skin}`);
   if (subset !== undefined) console.log(`  ..    ${subset.mode.padEnd(8)} ${subset.names.join(', ')}`);
@@ -1019,7 +1026,7 @@ export function cmdRender(flags: Record<string, string>): void {
     if (geometry) {
       for (const [name, frames] of sampled) {
         const animation = name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name;
-        geometryTexts.set(name, geometryText(geometryFileOf(poser, animation, fps, frames, viewport, skin, environment?.steps, preroll)));
+        geometryTexts.set(name, geometryText(geometryFileOf(poser, animation, fps, frames, viewport, skin, environment?.steps, preroll, physicsMode)));
       }
     }
     // The fold reading, off the very attachments the frames were drawn from, against the rest table the geometry
@@ -1065,6 +1072,7 @@ export function cmdRender(flags: Record<string, string>): void {
     // whose slot draws on no frame of any set drawn is refused, as --pass-through refuses it, rather than read as a SKIP.
     const seamReadings = new Map<string, ReturnType<typeof seamFileOf>>();
     if (seamPairs !== undefined) {
+      const cells = seamCells ? setupCellReader(() => sampleSetupPose(poser, { skin })[0].pieces, pages) : undefined;
       const draws = new Set<string>();
       for (const frames of sampled.values()) for (const frame of frames) for (const piece of frame.pieces) draws.add(piece.slot);
       for (const pair of seamPairs) {
@@ -1082,7 +1090,7 @@ export function cmdRender(flags: Record<string, string>): void {
         const shown = frames.map((frame) => frame.attachments ?? []);
         const read = frames.map((frame) => ({ index: frame.index, time: frame.time, pieces: frame.pieces, attachments: frame.attachments ?? [] }));
         try {
-          seamReadings.set(name, seamFileOf(animation, fps, skin, seamsOf(seamPairs, poser.rest(skin, shown), read, pages)));
+          seamReadings.set(name, seamFileOf(animation, fps, skin, seamsOf(seamPairs, poser.rest(skin, shown), read, pages, {}, { cells })));
         } catch (err) {
           if (err instanceof SeamError) throw new UsageError(`--seam, ${JSON.stringify(name)}: ${err.message}`);
           throw err;
@@ -1151,6 +1159,7 @@ export function cmdRender(flags: Record<string, string>): void {
               subset,
               environment: environment?.steps,
               preroll,
+              physicsMode,
               pinned,
             }),
           );
@@ -1194,6 +1203,8 @@ export function cmdRender(flags: Record<string, string>): void {
   }
 
   mkdirSync(outRoot, { recursive: true });
+  // A prior observation cannot describe the new frames, including an observation-only render.
+  rmSync(join(outRoot, 'boundary.json'), { force: true });
   if (extremesOnly) {
     // Reuse the same posed grid and plates; selecting extremes needs no ordinary pixels.
     // Clear only the selected sets, just as the ordinary render does. No frames.json
@@ -1289,7 +1300,7 @@ export function cmdRender(flags: Record<string, string>): void {
         : ` + ${sheetPack.pages.map((p) => `${p.image} + ${p.table}`).join(' + ')} + ${SHEET_MANIFEST_FILE} (${sheetPack.pages.length} page(s), ${sheetPack.pageEdges})`;
     const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${sheetNote}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}${passNote}${seamNote}${overlapNote}`;
     console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${extras} -> ${dir}`);
-    if (physics !== undefined) console.log(`  ..    ${physicsLine(physics.stepped, physicsDeclared, fps, frames.length)}`);
+    if (physics !== undefined) console.log(`  ..    ${physicsLine(physics.stepped, physicsDeclared, fps, frames.length, physicsMode)}`);
     for (const mesh of foldReading?.meshes ?? []) {
       const key = `${mesh.slot}\u0000${mesh.attachment}`;
       const fault = faultsSaid.has(key) ? null : setupFaultLine(mesh);
@@ -1330,6 +1341,7 @@ export function cmdRender(flags: Record<string, string>): void {
     ...(environment === undefined ? {} : { environment: environment.steps }),
     // Written only when a pre-roll was asked for (issue #1684), for the same reason.
     ...(preroll === undefined ? {} : { preroll }),
+    ...(physicsMode === undefined ? {} : { physicsMode }),
     // Written only when the box was given (issue #1414): a fitted render says nothing and stays the bytes it was.
     ...(given === undefined ? {} : { pinned: pinnedRecord(given.by, outside) }),
     background: BACKGROUND,
@@ -1340,6 +1352,13 @@ export function cmdRender(flags: Record<string, string>): void {
   };
   writeFileSync(join(outRoot, FRAMES_SIDECAR), `${JSON.stringify(sidecar, null, 2)}\n`);
   console.log(`rigc: wrote ${join(outRoot, FRAMES_SIDECAR)}`);
+  if (flags['boundary-from'] !== undefined) {
+    const reading = boundaryComparison(resolve(flags['boundary-from']), outRoot, sidecar);
+    writeFileSync(join(outRoot, 'boundary.json'), `${JSON.stringify(reading, null, 2)}\n`);
+    const detail = 'reason' in reading ? reading.reason : `max ${String(reading.maxPixels)} L-infinity px over ${reading.frames.length} frame(s)`;
+    console.log(`  ..    boundary ${reading.status}: ${detail}`);
+    console.log(`rigc: wrote ${join(outRoot, 'boundary.json')}`);
+  }
 }
 
 /**
@@ -1371,11 +1390,11 @@ export function physicsSteppedOf(frames: readonly Frame[], fps: number): { stepp
  * `render`'s `physics:` line for one set (issue #1467): how many constraints were stepped at the set's rate, and — when
  * fewer than the rig declares — the ones that took no step, by name, with why a constraint takes none.
  */
-export function physicsLine(stepped: readonly string[], declared: readonly string[], fps: number, frames: number): string {
+export function physicsLine(stepped: readonly string[], declared: readonly string[], fps: number, frames: number, physicsMode?: 'off'): string {
   const head = `physics: ${stepped.length} constraint(s) stepped at ${fps} fps`;
   const idle = declared.filter((name) => !stepped.includes(name));
   if (idle.length === 0) return head;
-  const why = frames === 1 ? 'a single pose takes no step' : 'inactive, or a mix of 0, on every frame';
+  const why = physicsMode === 'off' ? '--physics off suppresses every physics constraint' : frames === 1 ? 'a single pose takes no step' : 'inactive, or a mix of 0, on every frame';
   return `${head} — ${idle.length} of the ${declared.length} declared took none: ${idle.map((n) => JSON.stringify(n)).join(', ')} (${why})`;
 }
 

package/src/cli/shared.ts

@@ -151,7 +151,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', 'extremes', 'extremes-only', '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', 'seam-cells', 'folds', 'extremes', 'extremes-only', 'overlaps', 'sheet', 'accept-skeleton-differences', 'keep-pages', 'dim']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -1072,8 +1072,9 @@ const FLAG_MEANINGS: Record<string, string> = {
     'colour, dashed where a slot drawn later covers it, named at its top. The render reports what was drawn; who should be in front is the ' +
     "author's, and the draw-order key in the motion spec is the remedy. A reading, not a gate. Not with --slot/--hide",
   parallax: 'read one named slider dial through the core poser on 9 evenly spaced values: parallax.json plus setup/extreme/diff/affine-residual heat-map parallax.png; geometry only, no assertion or pass threshold. A separate dial render mode; takes no animation, fps, other diagnostics, sheet, subset, environment, preroll or viewport flags',
-  'extremes-only': 'write only extremes.json and readable extremes.png per set, with the same posed grid and bytes as --extremes; no ordinary frame PNGs, contact.png or frames.json. Implies --extremes; takes no --sheet, --sheet-format, --page-edges, --geometry, --folds, --pass-through, --seam, --overlaps or --angle-range',
+  'extremes-only': 'write only extremes.json and readable extremes.png per set, with the same posed grid and bytes as --extremes; no ordinary frame PNGs, contact.png or frames.json. Implies --extremes; takes no --sheet, --sheet-format, --page-edges, --geometry, --folds, --pass-through, --seam, --seam-cells, --overlaps or --angle-range',
   extremes: 'also write extremes.json and a native six-panel extremes.png per set: setup, geometry-pair min/max and premultiplied RGBA diffs, with a legend. Per-channel extrema are recorded separately and valid channels survive geometry/image SKIPs; channel refusals are named separately. Still geometry reports SKIP; a reading, not a gate. Attachment identity/count changes record a named SKIP without changing render exit; supports --slot/--hide on both posers',
+  'seam-cells': 'with --seam, include exact world-grid cells on gapOpen/gapCovered hits, with setupTop/setupUnder slots; absent by default',
   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 carried overlap hull and a local sweep of the same setup band cell through both drawings — ' +
@@ -1108,6 +1109,8 @@ const FLAG_MEANINGS: Record<string, string> = {
     'runtime\'s, wind [1, 0] and gravity [0, 1]. frames.json and geometry.json record it, and the framing reads it. A ' +
     'malformed file, a half no physics constraint answers, two steps on one frame and a step after every set\'s last frame ' +
     'are refused by name. An inspection of what the rig offers, not a scene',
+  physics: 'pose with physics on (default) or off. Off suppresses every physics constraint after timeline application on both posers. frames.json records physicsMode off and check refuses that reference',
+  'boundary-from': 'read visible whole-figure pixel-boundary displacement against an earlier render on the identical viewport and frame grid. Writes boundary.json, no threshold or pass verdict',
   preroll:
     'walk each set this many whole loops on a looping track before the loop recorded, drawn by no frame, the physics carried ' +
     'across every wrap as a player\'s looping track carries it — so a spring that converges is warm on the first frame. Frame i is the ' +
@@ -1307,6 +1310,8 @@ const FLAG_VALUES: Record<string, string> = {
   'texture-from': '<path>',
   poser: 'core|spine',
   environment: '<schedule.json>',
+  physics: '<on|off>',
+  'boundary-from': '<dir>',
   preroll: '<n>',
   'pass-through': '<cloth>:<leg>[,<cloth>:<leg>…]',
   seam: '<slot>:<slot>[,<slot>:<slot>…]',
@@ -1785,7 +1790,7 @@ export const COMMANDS: CommandDoc[] = [
       'rigc render … --viewport <x,y,w,h> | --viewport-from <frames.json>   (a box given, not fitted: two renders on one pixel grid)',
       'rigc render … --sheet [--sheet-format json-hash] [--page-edges pot|free]   (deterministic sprite sheets + JSON hash table + sheet-manifest.json per set)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'extremes', 'extremes-only', 'parallax', 'pass-through', 'seam', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'preroll', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'extremes', 'extremes-only', 'parallax', 'pass-through', 'seam', 'seam-cells', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'preroll', 'physics', 'boundary-from', 'poser', 'out'],
     overrides: {
       'page-edges': {
         meaning:

package/src/render.ts

@@ -502,8 +502,8 @@ export function spinePoser(data: SkeletonData): Poser {
     bones: data.bones.map((bone) => ({ name: bone.name, parent: bone.parent?.name ?? null })),
     slots: data.slots.map((slot) => ({ name: slot.name, bone: slot.boneData.name })),
     subset: (opts, skin) => slotSubsetOf(data, opts, skin),
-    setup: (skin) => spinePosed(setupPosed(data, skin)),
-    animation: (name, skin, fps, count, visit, environment, _channels, times, loop, clockSteps) => {
+    setup: (skin, _channels, physicsMode) => spinePosed(setupPosed(data, skin, physicsMode)),
+    animation: (name, skin, fps, count, visit, environment, _channels, times, loop, clockSteps, physicsMode) => {
       const skeleton = skeletonUnderSkin(data, skin);
       const state = new AnimationState(new AnimationStateData(data));
       // Not looping: the last frame sits at the animation's duration, and a looping
@@ -524,12 +524,12 @@ export function spinePoser(data: SkeletonData): Poser {
           setSkeletonEnvironment(skeleton, environment?.(i));
           // `clockSteps` (issue #1687, `render --preroll`): what the step moves the physics clock by, where that is not its own length.
           skeleton.update(times === undefined ? clock : physicsClockStep(clockSteps?.[i - 1] ?? delta));
-          skeleton.updateWorldTransform(Physics.update);
+          skeleton.updateWorldTransform(physicsMode === 'off' ? Physics.none : Physics.update);
         } else {
           state.apply(skeleton);
           setSkeletonEnvironment(skeleton, environment?.(i));
           skeleton.update(0);
-          skeleton.updateWorldTransform(Physics.reset);
+          skeleton.updateWorldTransform(physicsMode === 'off' ? Physics.none : Physics.reset);
         }
         visit(i, posed);
       }
@@ -592,11 +592,11 @@ function steppedPhysicsOf(skeleton: Skeleton): string[] {
  * `sampleSetupPose` and the geometry export's `rest` table both pose from, so
  * the two cannot come to describe different rest poses.
  */
-function setupPosed(data: SkeletonData, skin: string | undefined): Skeleton {
+function setupPosed(data: SkeletonData, skin: string | undefined, physicsMode?: 'off'): Skeleton {
   const skeleton = skeletonUnderSkin(data, skin);
   skeleton.setupPose();
   skeleton.update(0);
-  skeleton.updateWorldTransform(Physics.reset);
+  skeleton.updateWorldTransform(physicsMode === 'off' ? Physics.none : Physics.reset);
   return skeleton;
 }
 

package/src/render_core.ts

@@ -804,14 +804,14 @@ export function corePoser(
       const result = poseRawDial(input.doc, override, name, { through });
       return { posed: corePosed(input, result.pose, through, []), read: result.read, applied: result.applied };
     },
-    setup: (skin, channels) => {
+    setup: (skin, channels, physicsMode) => {
       const input = inputOf(skin);
       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 });
+      const pose = poseRawSetup(input.doc, { through, ...observe, ...(physicsMode === 'off' ? { physicsStep: () => false } : {}) });
       return corePosed(input, pose, through, [], values);
     },
-    animation: (name, skin, fps, count, visit, environment, channels, times, loop, clockSteps) => {
+    animation: (name, skin, fps, count, visit, environment, channels, times, loop, clockSteps, physicsMode) => {
       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);
@@ -827,6 +827,7 @@ export function corePoser(
       const steppedNow = new Set<string>();
       const inner = plants.physicsStep ?? stepPhysics;
       const physicsStep: PhysicsStepper = (r, w, length, ctx) => {
+        if (physicsMode === 'off') return false;
         const moved = inner(r, w, length, ctx);
         if (ctx.time > 0 && ctx.states.get(r.name)?.lastTime === ctx.time) steppedNow.add(r.name);
         return moved;

package/src/render_shared.ts

@@ -243,6 +243,8 @@ export interface FrameSet {
 }
 
 export interface FramesSidecar {
+  /** Absent means on, including frame sets written before this field existed. */
+  physicsMode?: 'off';
   spec: string;
   example?: string;
   rung?: string;
@@ -427,6 +429,8 @@ export interface UvWindow {
 
 /** Options for `piecesOf` and the samplers that call it. */
 export interface PoseOptions {
+  /** Suppress every physics constraint after animation application. */
+  physicsMode?: 'off';
   /** 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`. */
@@ -1184,7 +1188,7 @@ 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, channels?: boolean): Posed;
+  setup(skin: string | undefined, channels?: boolean, physicsMode?: 'off'): 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`.
@@ -1205,7 +1209,7 @@ export interface Poser {
    * follows `times` (`prerollTimes` says why the two part). Absent, every
    * step moves the physics clock by its own length, as it always did.
    */
-  animation(name: string, skin: string | undefined, fps: number, count: number, visit: (index: number, posed: Posed) => void, environment?: (index: number) => EnvironmentChange | undefined, channels?: boolean, times?: readonly number[], loop?: boolean, clockSteps?: readonly number[]): void;
+  animation(name: string, skin: string | undefined, fps: number, count: number, visit: (index: number, posed: Posed) => void, environment?: (index: number) => EnvironmentChange | undefined, channels?: boolean, times?: readonly number[], loop?: boolean, clockSteps?: readonly number[], physicsMode?: 'off'): void;
   /** The rest table for the (slot, attachment) pairs `shown` holds — see `AttachmentRest`. */
   rest(skin: string | undefined, shown: readonly AttachmentPose[][]): AttachmentRest[];
 }
@@ -1290,14 +1294,15 @@ export function sampleAnimation(source: PoseSource, name: string, fps: number, o
     const recorded = (i: number, posed: Posed): void => {
       if (i >= first) frames.push(frameOf(i - first, (i - first) * step, posed, draw(), opts));
     };
-    poser.animation(name, opts?.skin, fps, times.length - 1, recorded, undefined, opts?.channels === true ? true : undefined, times, true, clock);
+    poser.animation(name, opts?.skin, fps, times.length - 1, recorded, undefined, opts?.channels === true ? true : undefined, times, true, clock, opts?.physicsMode);
     return frames;
   }
   const visit = (i: number, posed: Posed): void => {
     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?.channels) poser.animation(name, opts.skin, fps, count, visit, opts.environment === undefined ? undefined : environmentAt(opts.environment, fps), true);
+  if (opts?.physicsMode === 'off') poser.animation(name, opts.skin, fps, count, visit, opts.environment === undefined ? undefined : environmentAt(opts.environment, fps), opts.channels, undefined, undefined, undefined, 'off');
+  else 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;
@@ -1413,7 +1418,7 @@ export function prerollTimes(duration: number, fps: number, preroll: number): {
  */
 export function sampleSetupPose(source: PoseSource, opts?: PoseOptions): Frame[] {
   const poser = poserOf(source);
-  const posed = opts?.channels ? poser.setup(opts.skin, true) : poser.setup(opts?.skin);
+  const posed = opts?.physicsMode === 'off' ? poser.setup(opts.skin, opts.channels, 'off') : opts?.channels ? poser.setup(opts.skin, true) : poser.setup(opts?.skin);
   return [frameOf(0, 0, posed, drawResolver(poser, opts)(), opts)];
 }
 
@@ -1737,6 +1742,7 @@ export interface GeometryFile {
   /** The setup pose, sampled the way `sampleSetupPose` samples it. */
   setup: Omit<GeometryFrame, 'index' | 'time'>;
   frames: GeometryFrame[];
+  physicsMode?: 'off';
 }
 
 /**
@@ -1784,6 +1790,7 @@ export function geometryFileOf(
   skin: string | undefined,
   environment?: EnvironmentStep[],
   preroll?: number,
+  physicsMode?: 'off',
 ): GeometryFile {
   const geometryFrame = (frame: Frame, where: string): Omit<GeometryFrame, 'index' | 'time'> => {
     if (frame.bones === undefined || frame.attachments === undefined) {
@@ -1800,7 +1807,7 @@ export function geometryFileOf(
     ...geometryFrame(frame, `frame ${frame.index}`),
   }));
   const poser = poserOf(source);
-  const setupFrame = sampleSetupPose(poser, { ...(skin === undefined ? {} : { skin }), bones: true, geometry: true })[0];
+  const setupFrame = sampleSetupPose(poser, { ...(skin === undefined ? {} : { skin }), bones: true, geometry: true, ...(physicsMode === undefined ? {} : { physicsMode }) })[0];
   const setup = geometryFrame(setupFrame, 'the setup pose');
   const file: GeometryFile = {
     spec: GEOMETRY_SPEC,
@@ -1809,6 +1816,7 @@ export function geometryFileOf(
     ...(skin === undefined ? {} : { skin }),
     ...(environment === undefined ? {} : { environment }),
     ...(preroll === undefined ? {} : { preroll }),
+    ...(physicsMode === undefined ? {} : { physicsMode }),
     fps,
     viewport: sidecarViewport(viewport),
     bones: poser.bones.map(({ name, parent }) => ({ name, parent })),

package/src/seam.ts

@@ -133,6 +133,69 @@ export interface SeamFrame {
 /** A world box `[minX, minY, maxX, maxY]`, world units, y up. */
 export type SeamBox = [number, number, number, number];
 
+/** One counted gap cell: centre in world units, y up. */
+export interface SeamCell {
+  x: number;
+  y: number;
+  setupTop: string | null;
+  setupUnder: string | null;
+}
+
+/** Optional detail; absent preserves the existing sidecar bytes. */
+export interface SeamOptions {
+  cells?: SeamCellReader;
+}
+
+/** Fills setup attribution for counted cells; reusable across pairs and frame sets. */
+export type SeamCellReader = (cells: SeamCell[], side: number) => void;
+
+/**
+ * Lazy setup raster, once per distinct cell side. Slot occupancy uses the same
+ * positive rendered-alpha traversal as gap coverage, without source-over hiding
+ * the layer below. Repeated fragments of one slot are one layer.
+ */
+export function setupCellReader(setup: () => readonly Piece[], pages: ReadonlyMap<string, Plate>): SeamCellReader {
+  const cache = new Map<number, { viewport: Viewport; names: string[]; top: Int32Array; under: Int32Array } | null>();
+  let pieces: readonly Piece[] | undefined;
+  return (cells, side) => {
+    if (cells.length === 0) return;
+    if (!cache.has(side)) {
+      pieces ??= setup();
+      if (pieces.length === 0) cache.set(side, null);
+      else {
+        const { viewport } = gridOf([], side, pieces);
+        const top = new Int32Array(viewport.width * viewport.height).fill(-1);
+        const under = new Int32Array(top.length).fill(-1);
+        const names = [...new Set(pieces.map(p => p.slot))];
+        const ids = new Map(names.map((name, i) => [name, i]));
+        const project = projector(viewport);
+        for (const piece of pieces) {
+          const page = pages.get(piece.page);
+          if (page === undefined) throw new SeamError(`setup slot "${piece.slot}" samples missing atlas page "${piece.page}"; available [${[...pages.keys()].join(', ')}]`);
+          const id = ids.get(piece.slot)!;
+          rasterisePiece(page, piece, project, viewport, (x, y, _r, _g, _b, alpha) => {
+            const k = y * viewport.width + x;
+            if (alpha > 0 && top[k] !== id) { under[k] = top[k]; top[k] = id; }
+          });
+        }
+        cache.set(side, { viewport, names, top, under });
+      }
+    }
+    const read = cache.get(side);
+    for (const cell of cells) {
+      cell.setupTop = null; cell.setupUnder = null;
+      if (read == null) continue;
+      const { viewport, names, top, under } = read;
+      const x = Math.round((cell.x - viewport.minX) / side - 0.5);
+      const y = Math.round((viewport.maxY - cell.y) / side - 0.5);
+      if (x < 0 || y < 0 || x >= viewport.width || y >= viewport.height) continue;
+      const k = y * viewport.width + x;
+      cell.setupTop = names[top[k]] ?? null;
+      cell.setupUnder = names[under[k]] ?? null;
+    }
+  };
+}
+
 /** What one frame reads of one kind. */
 export interface SeamHit {
   index: number;
@@ -146,6 +209,8 @@ export interface SeamHit {
   area: number;
   /** The counted cells' whole squares, world units, y up. */
   box: SeamBox;
+  /** Opt-in on gapOpen/gapCovered only; descending y, then ascending x. */
+  cells?: SeamCell[];
 }
 
 /** A run of consecutive frames of one kind — first and last frame, their times, the most cells on any of them. */
@@ -385,6 +450,7 @@ interface Side {
 interface Cells {
   px: number;
   box: SeamBox | null;
+  cells?: SeamCell[];
 }
 
 const restPiece = (side: Side): Piece => ({ ...side.piece, world: Array.from(side.rest) });
@@ -530,7 +596,7 @@ function contactOf(restA: Uint8Array, restB: Uint8Array, drawnA: Uint8Array, dra
 }
 
 /** One frame's counts, or `null` when the two drawings share no cell at the setup pose. See the module comment. */
-function readFrame(A: Side, B: Side, cell: number, plant: SeamPlant, frame: SeamFrame, pages: ReadonlyMap<string, Plate>, grid: Grid, visibility: readonly Uint8Array[]): { gap: Cells; ghost: Cells; ghostA: Cells; ghostB: Cells; gapOpen: Cells; gapCovered: Cells; contact: Contact } | null {
+function readFrame(A: Side, B: Side, cell: number, plant: SeamPlant, frame: SeamFrame, pages: ReadonlyMap<string, Plate>, grid: Grid, visibility: readonly Uint8Array[], options: SeamOptions): { gap: Cells; ghost: Cells; ghostA: Cells; ghostB: Cells; gapOpen: Cells; gapCovered: Cells; contact: Contact } | null {
   const { width, height } = grid.viewport;
   const restA = restPiece(A);
   const restB = restPiece(B);
@@ -589,8 +655,8 @@ function readFrame(A: Side, B: Side, cell: number, plant: SeamPlant, frame: Seam
   const ghost: Cells = { px: 0, box: null };
   const ghostA: Cells = { px: 0, box: null };
   const ghostB: Cells = { px: 0, box: null };
-  const gapOpen: Cells = { px: 0, box: null };
-  const gapCovered: Cells = { px: 0, box: null };
+  const gapOpen: Cells = { px: 0, box: null, ...(options.cells ? { cells: [] } : {}) };
+  const gapCovered: Cells = { px: 0, box: null, ...(options.cells ? { cells: [] } : {}) };
   let alphaCells: Uint8Array | null = null;
   const take = (into: Cells, qx: number, qy: number): void => takeCell(into, qx, qy, cell);
   if (plant.never) return { gap, ghost, ghostA, ghostB, gapOpen, gapCovered, contact };
@@ -610,7 +676,9 @@ function readFrame(A: Side, B: Side, cell: number, plant: SeamPlant, frame: Seam
           take(gap, qx, qy);
           const covered = plant.gapCoverage === 'covered' || (plant.gapCoverage !== 'open' &&
             (alphaCells ??= frameAlphaCells(plant.gapCoverage === 'pair' ? [A.piece, B.piece] : frame.pieces, pages, grid.viewport, plant.gapCoverage === 'half'))[k] !== 0);
-          take(covered ? gapCovered : gapOpen, qx, qy);
+          const into = covered ? gapCovered : gapOpen;
+          take(into, qx, qy);
+          into.cells?.push({ x: qx, y: qy, setupTop: null, setupUnder: null });
         }
         continue;
       }
@@ -665,6 +733,7 @@ export function seamsOf(
   frames: readonly SeamFrame[],
   pages: ReadonlyMap<string, Plate>,
   plant: SeamPlant = {},
+  options: SeamOptions = {},
 ): SeamPairReading[] {
   const restOf = new Map(rest.map((r) => [restKey(r.slot, r.attachment), r]));
   const sideOf = (frame: SeamFrame, slot: string): Side | null => {
@@ -711,13 +780,17 @@ export function seamsOf(
       if (A === null || B === null) continue;
       drawn++;
       const cell = exposureCell;
-      const read = readFrame(A, B, cell, plant, frame, pages, exposureGrid, exposure.map((m) => m.visible));
+      const read = readFrame(A, B, cell, plant, frame, pages, exposureGrid, exposure.map((m) => m.visible), options);
       if (read === null) { contact(unavailableContact('no shared half-opacity cell at the setup pose; no band to identify a joint')); continue; }
       const fragmented = [a, b].some(slot => frame.pieces.filter(p => p.slot === slot).length !== 1);
       contact(fragmented ? unavailableContact('each named slot must draw exactly one fragment for material contact') : read.contact);
       banded++;
+      if (options.cells) {
+        options.cells(read.gapOpen.cells!, cell);
+        options.cells(read.gapCovered.cells!, cell);
+      }
       for (const [cells, into] of [[read.gap, gaps], [read.ghost, ghosts], [read.ghostA, ghostsA], [read.ghostB, ghostsB], [read.gapOpen, openGaps], [read.gapCovered, coveredGaps]] as const) {
-        if (cells.px > 0 && cells.box !== null) into.push({ index: frame.index, time: frame.time, px: cells.px, cell, area: cells.px * cell * cell, box: cells.box });
+        if (cells.px > 0 && cells.box !== null) into.push({ index: frame.index, time: frame.time, px: cells.px, cell, area: cells.px * cell * cell, box: cells.box, ...(cells.cells === undefined ? {} : { cells: cells.cells }) });
       }
     }
     const gap = kindOf(gaps);

package/src/sheet.ts

@@ -120,6 +120,7 @@ export interface SheetManifest {
   environment?: EnvironmentStep[];
   /** The whole loops walked before the loop these frames record (`render --preroll`, issue #1684); absent without it. */
   preroll?: number;
+  physicsMode?: 'off';
   pinned?: PinnedViewport;
   fps: number;
   duration: number;
@@ -185,6 +186,7 @@ export interface BuildSheetSetOptions {
   subset?: SlotSubset;
   environment?: EnvironmentStep[];
   preroll?: number;
+  physicsMode?: 'off';
   pinned?: PinnedViewport;
   /** For negative-control testing in `selftest.ts` only: reverse the input order handed to `packAtlas`. */
   reversePackInputs?: boolean;
@@ -276,6 +278,7 @@ export function sheetNamespaceOf(opts: {
   subset?: SlotSubset;
   environment?: EnvironmentStep[];
   preroll?: number;
+  physicsMode?: 'off';
 }): string {
   const rig = sanitizeNamespaceSegment(opts.rigName);
   const anim = sanitizeNamespaceSegment(opts.setName);
@@ -287,6 +290,7 @@ export function sheetNamespaceOf(opts: {
     variants.push(`env=${digest}`);
   }
   if (opts.preroll !== undefined) variants.push(`preroll=${opts.preroll}`);
+  if (opts.physicsMode !== undefined) variants.push(`physics=${opts.physicsMode}`);
   return variants.length === 0 ? `${rig}/${anim}` : `${rig}/${anim}/${variants.join('+')}`;
 }
 
@@ -721,6 +725,7 @@ export function buildSheetSet(opts: BuildSheetSetOptions): SheetSetPack {
     subset: opts.subset,
     environment: opts.environment,
     preroll: opts.preroll,
+    physicsMode: opts.physicsMode,
   });
 
   const padding = SHEET_PADDING;
@@ -875,6 +880,7 @@ export function buildSheetSet(opts: BuildSheetSetOptions): SheetSetPack {
         : { hidden: [...opts.subset.names] }),
     ...(opts.environment === undefined ? {} : { environment: opts.environment }),
     ...(opts.preroll === undefined ? {} : { preroll: opts.preroll }),
+    ...(opts.physicsMode === undefined ? {} : { physicsMode: opts.physicsMode }),
     ...(opts.pinned === undefined ? {} : { pinned: opts.pinned }),
     fps: opts.fps,
     duration,