spine-rigc 3.2.1 → 3.3.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> |
@@ -9950,6 +9951,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.3.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';
@@ -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', '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
@@ -850,7 +854,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', '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 +902,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 +1024,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
@@ -1151,6 +1156,7 @@ export function cmdRender(flags: Record<string, string>): void {
               subset,
               environment: environment?.steps,
               preroll,
+              physicsMode,
               pinned,
             }),
           );
@@ -1194,6 +1200,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 +1297,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 +1338,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 +1349,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 +1387,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

@@ -1108,6 +1108,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 +1309,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 +1789,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', '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/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,