@rig-c/pose 0.32.0 → 0.33.0

package/README.md

@@ -134,6 +134,7 @@ and what the run cannot decide for you it lists:
 - `FLIP` — a segment that turns more than `--flip` degrees in one frame (with `--flip <deg>`; off by default) is spread over the frames around the jump; one line per spread, with the chain, the segment, the jump, the frames and h. Below.
 - `BEND` — with `--bends clamp`, a hinge bent the wrong way is straightened on that frame instead of refusing; one line per hinge with the count, the frame range and the worst angle (one per frame with `--verbose`; every frame in the report's `bends`).
 - `FOLD` — `rigc render --folds` over the new animation: every mesh that folds, and when. A reading, not a gate.
+- `SEAM` — rig-c's seam reading (`rigc render --seam`, rig-c ≥ 2.60.0) over the new animation, for the rig's declared neighbour pairs ([#216](https://github.com/rig-c/pose/issues/216)): one line per span of a **gap** (background inside the joint) or a **ghost** (one piece's overlap swung clear of its partner) over the one-cell floor, with the pair, the frames and their times, the rate and the most cells; per pair the frames rigc named that were one cell thick (`under the floor — not reported`), a pair not read and why, or rigc's SKIP (the two drawings share no cell at rest — nothing measured, never a seam that held); then `n span(s) over k pair(s) at <fps> fps — r of d declared pair(s) read`. **The pairs**: a rig spec carries none — `rig.json` holds bones, slots and skins — so they come from @rig-c/parts' `parts.json`, named with `--parts <file or directory>` (its build's `--out`, beside `rig/`): each limb's consecutive segments (a part's `limb` record: `name`, `segment`, and below a joint `joint`), a pair named twice counting once, each part drawn by the slot of its name — the pairs @rig-c/parts' own `check` reads (rig-c/parts#503). A pair whose part has no slot of its name is `not read`, named. Without `--parts`, or with a `parts.json` that holds no limb, the line is `SEAM   no neighbour pair declared — <why>; seams: []`, and where the rig's parent directory holds a `parts.json` it says so. **The floor** is @rig-c/parts' so the two tools agree: a frame's gap or ghost counts when it holds more cells than its box is long (its longer side, in cells) — thicker than one cell; a crack one cell deep is the half-opacity edge moving by less than a cell. Its own render, at the rate the folds are read at; it moves no byte of the motion or the build, and never changes the exit or the gate. A malformed `parts.json` is an input and is refused (`PARTS_JSON`).
 - `JITTER` — one line per bone a chain keys (a face or body dial bone excepted), in map order ([#236](https://github.com/rig-c/pose/issues/236)): the mean |second difference| of its local rotation as rig-c's poser posed the gated build (its world matrix in its parent's axes, so the rotate key up to a constant), against the same figure of its map pair's picture angle less the pair of the nearest keyed bone above it, in °/frame², and the ratio. Both are read on the same triples, three consecutive frames on which every pose point the two pairs need is good. A pair whose figure rounds to 0 is still, and gets no ratio. A group's jitter ratio is its bones' together; the line names the bone that moved it. A reading, not a gate.
 - `REACH` — a `reach` chain ([below](#the-map-rig-pose-map1)) whose aim departs from its own pair's angle ([#236](https://github.com/rig-c/pose/issues/236)): why (its origin sits off the anchor's at setup, a lever; and the bones above it the animation turns, or translates other than by the anchor's travel), the largest departure with its frame, the departure's mean |second difference|, and the aim's against the pair's, in °/frame², with the ratio. A reach whose bone sits on the anchor's origin with nothing above it moved is aimed along the pair and prints none. This line also names, with `--raised-by-head` or a `"by-hip"` set, a placed arm out of reach (below); the two read `REACH  chain …` and `REACH  set …`. A reading, not a gate.
 - `POSTURE` — when the map has a pelvis chain (joints `r_hip`, `l_hip`) and a `translate`: the hip line's tilt range, and the sway — the x-range of mid_hip − mid_shoulder — in rig units and in shoulder widths, the pose's beside the posed rig's. A reading, not a gate. A frame on which either hip is `inferred` is left out of the tilt. When that is every frame, as after `clean --hips-inferred`, the line is `hip tilt not read: hips inferred (declared at clean)` and the report's `posture` has `"tilt": null` with `"tiltWhy"`; on some frames only, the tilt is read over the others and the line counts the frames left out (`posture.hipsInferred`). The source is read from the clean record, or is `source not stated` when the joints carry the state and the record does not. With a `measured` record ([#86](https://github.com/rig-c/pose/issues/86), [#106](https://github.com/rig-c/pose/issues/106)), the read, interpolated, scaled and held frames are the measurement, so the tilt is read on all four, while `unmeasured` frames (`fit.corr < 0.9`) are left out and named. The line adds `tilt measured (<method>) on N frame(s): R read, I interpolated, H held (held: <spans>)` (plus `scaled` and `unmeasured` spans when present). The report's `posture` carries `tiltMeasured`. The sway reads the hips as before. With `--plant-feet`, `POSTURE` also prints one `bounce` line per support span ([#107](https://github.com/rig-c/pose/issues/107), `posture.bounce` in the report): the detrended (centred ±12-frame moving mean removed) vertical standard deviation, rig/reference ratio and correlation for the hip, the neck and `eyes − neck`.
@@ -166,8 +167,8 @@ and what the run cannot decide for you it lists:
 
 Each figure is formatted as the full line formats it, from the same record. Refusals print the same in every mode, and the exit code and the gate do not change with it; `--verbose` with `--summary` is a usage error.
 
-`--report <file>` writes all of it as JSON (`rig-pose-report/1`): `spec`, `rigc` (`{ version, entry }`: the rig-c that gated it), `rig`, `animation`, `inputs` (consumed rig spec, map and pose files, each with invocation-relative `path` and exact-byte `sha256`; a folder rig resolves to its actual rig.json; these three identities do not claim to bind optional base motion, sets or images), `frames`, `duration`, `frameTimes` (the exact motion-key time for each pose frame; never FPS inferred from duration), `render` (the separate renderer sampling domain, `{ fps, frames }` from frame-set metadata, or `null` when not measured), `cleaned` (the sequence's `cleaned` record, [above](#clean-first-rig-pose-clean)), `options` (every figure the run used, `switchTolerance`, `switchMin`, `switchAt`, `legScale`, `plantFeet`, `stance`, `floor` and `raisedByHead` included), `scale`, `scaleFit` (the `SCALE` reading: `segment`, `leg`, `hip`, `outside`, `travel`; `null` without a scale), `holds`, `short`, `endOn`, `bends`, `flips`, `gate` (rig-c's gate summary, a string), `landings`, `jitter`, `reach`, `posture`, `folds`, `body` (`standing`, `read`, `over45`, `framesOver45`, and with `body.yaw` or `body.sets` in the map, `yaw` and `sets`), `legScale`, `pivot`, `feet` (`planted`, `legLength`, `straight`, `rigLeg`, `segments`, `supports`, `jumps`, `jumpEvents`, `steps`, `changes`, `lowered`, `floor`, `shifts`, `blend`, `closure`, and the posed `reading`; `straight` is each side's 95th-percentile picture length hip → ankle in px and `rigLeg` each side's rig leg at setup (thigh origin → ankle) in world units, both `null` without both legs; `segments` holds one `{ chain, bone, joints, straight, ratio: { min, median, max }, why? }` per mapped leg segment, read with or without `--leg-scale` (`straight` and `ratio` `null`, and `why` said, where it was not measured), [#237](https://github.com/rig-c/pose/issues/237); a jump is an inclusive `[first, last]` pair of frames; `lowered` holds `{ frames, was, now, cause? }` runs (`cause`, where `now` is `null`: `released` or `higher`), present only with `--plant-feet` on a sequence not declared in place ([#113](https://github.com/rig-c/pose/issues/113)); `floor` is the world y every support span was planted on and `shifts` holds one `{ side, frames, shift }` per support span in world units, `null` and empty without `--plant-feet`; `blend` is `{ bounds, runs: [{ side, frames, k: { min, max } }], over: [{ side, frames, needed, left }] }`, the supporting leg stretched on the blend frames, `null` without `--plant-feet`; `closure` is `{ drift, frames }`, the hip's x drift closed over an in-place loop, `null` unless the sequence is `"in-place"` and `--plant-feet` is given), `stance` (`tolerance`, `release`, `minSeconds`, `bounds`, `runs`: `{ state, side, frames, maxHeight, maxDepth?, k, absorbed?, moved? }` (`state` is `both`, `lifted` or `below`; `maxDepth`, on a `below` run, is the free ankle's largest distance below the supporting one in leg lengths; `moved`, on a `lifted` or `below` run, the frames whose free ankle a `--leg-scale` clamp moved off the pose's height, as `legScale[].free` is written, [#237](https://github.com/rig-c/pose/issues/237)), `over`: `{ side, frames, needed, left }`; `null` without `--stance`), `shear`, `idleDropped`, `idleKeptOut` and `merged` ([below](#the-idle-what-the-retarget-drops)), `reduce` (the tolerances, each row of `REDUCE` and `ankleDrift`, [below](#few-keys---reduce)), and the demand lists. The fields a run is graded by:
-Report event objects with a pose `frame` or inclusive `frames` also carry exact `t` or `times` from `frameTimes`; existing `seconds` remain span lengths, with additive `spanSeconds`. Holds preserve their frame-index `from`/`to`. Existing scan joint/chain identities remain beside map-derived `bone` (a unique mapped target) or `bones` (all actual mapped targets); no joint-name heuristic chooses a target. `feet.jumps` stays an array of original frame pairs; `feet.jumpEvents` adds matching `{ frames, times }` objects. Fold and uncovered rows preserve their discrete `times` and gaps, declare `domain: "render"`, and use the separate root `render` domain, never fabricated nearest pose-frame indices. The run hashes map/pose from the exact buffers passed to their readers, snapshots the resolved rig file before its gate, and rechecks all three before user-output writes. The writer validates coordinates before output writes and never changes motion keys. The switch diagnostic `moved.frame` is a selected-to-keyed pair with signed `frames`/`seconds` displacement; it is preserved as diagnostic data, not reinterpreted as an inclusive interval. An explicitly supplied uniform writer clock requires both positive `fps` and seconds offset `frame0`; canonical pose input does not yet declare FPS, so the retarget producer always writes exact `frameTimes`.
+`--report <file>` writes all of it as JSON (`rig-pose-report/1`): `spec`, `rigc` (`{ version, entry }`: the rig-c that gated it), `rig`, `animation`, `inputs` (consumed rig spec, map and pose files, each with invocation-relative `path` and exact-byte `sha256`; a folder rig resolves to its actual rig.json; these three identities do not claim to bind optional base motion, sets or images), `frames`, `duration`, `frameTimes` (the exact motion-key time for each pose frame; never FPS inferred from duration), `render` (the separate renderer sampling domain, `{ fps, frames }` from frame-set metadata, or `null` when not measured), `cleaned` (the sequence's `cleaned` record, [above](#clean-first-rig-pose-clean)), `options` (every figure the run used, `switchTolerance`, `switchMin`, `switchAt`, `legScale`, `plantFeet`, `stance`, `floor` and `raisedByHead` included), `scale`, `scaleFit` (the `SCALE` reading: `segment`, `leg`, `hip`, `outside`, `travel`; `null` without a scale), `holds`, `short`, `endOn`, `bends`, `flips`, `gate` (rig-c's gate summary, a string), `landings`, `jitter`, `reach`, `posture`, `folds`, `seams`, `seamPairs`, `body` (`standing`, `read`, `over45`, `framesOver45`, and with `body.yaw` or `body.sets` in the map, `yaw` and `sets`), `legScale`, `pivot`, `feet` (`planted`, `legLength`, `straight`, `rigLeg`, `segments`, `supports`, `jumps`, `jumpEvents`, `steps`, `changes`, `lowered`, `floor`, `shifts`, `blend`, `closure`, and the posed `reading`; `straight` is each side's 95th-percentile picture length hip → ankle in px and `rigLeg` each side's rig leg at setup (thigh origin → ankle) in world units, both `null` without both legs; `segments` holds one `{ chain, bone, joints, straight, ratio: { min, median, max }, why? }` per mapped leg segment, read with or without `--leg-scale` (`straight` and `ratio` `null`, and `why` said, where it was not measured), [#237](https://github.com/rig-c/pose/issues/237); a jump is an inclusive `[first, last]` pair of frames; `lowered` holds `{ frames, was, now, cause? }` runs (`cause`, where `now` is `null`: `released` or `higher`), present only with `--plant-feet` on a sequence not declared in place ([#113](https://github.com/rig-c/pose/issues/113)); `floor` is the world y every support span was planted on and `shifts` holds one `{ side, frames, shift }` per support span in world units, `null` and empty without `--plant-feet`; `blend` is `{ bounds, runs: [{ side, frames, k: { min, max } }], over: [{ side, frames, needed, left }] }`, the supporting leg stretched on the blend frames, `null` without `--plant-feet`; `closure` is `{ drift, frames }`, the hip's x drift closed over an in-place loop, `null` unless the sequence is `"in-place"` and `--plant-feet` is given), `stance` (`tolerance`, `release`, `minSeconds`, `bounds`, `runs`: `{ state, side, frames, maxHeight, maxDepth?, k, absorbed?, moved? }` (`state` is `both`, `lifted` or `below`; `maxDepth`, on a `below` run, is the free ankle's largest distance below the supporting one in leg lengths; `moved`, on a `lifted` or `below` run, the frames whose free ankle a `--leg-scale` clamp moved off the pose's height, as `legScale[].free` is written, [#237](https://github.com/rig-c/pose/issues/237)), `over`: `{ side, frames, needed, left }`; `null` without `--stance`), `shear`, `idleDropped`, `idleKeptOut` and `merged` ([below](#the-idle-what-the-retarget-drops)), `reduce` (the tolerances, each row of `REDUCE` and `ankleDrift`, [below](#few-keys---reduce)), and the demand lists. The fields a run is graded by:
+Report event objects with a pose `frame` or inclusive `frames` also carry exact `t` or `times` from `frameTimes`; existing `seconds` remain span lengths, with additive `spanSeconds`. Holds preserve their frame-index `from`/`to`. Existing scan joint/chain identities remain beside map-derived `bone` (a unique mapped target) or `bones` (all actual mapped targets); no joint-name heuristic chooses a target. `feet.jumps` stays an array of original frame pairs; `feet.jumpEvents` adds matching `{ frames, times }` objects. Fold, uncovered and seam rows preserve their discrete `times` and gaps, declare `domain: "render"`, and use the separate root `render` domain, never fabricated nearest pose-frame indices. The run hashes map/pose from the exact buffers passed to their readers, snapshots the resolved rig file before its gate, and rechecks all three before user-output writes. The writer validates coordinates before output writes and never changes motion keys. The switch diagnostic `moved.frame` is a selected-to-keyed pair with signed `frames`/`seconds` displacement; it is preserved as diagnostic data, not reinterpreted as an inclusive interval. An explicitly supplied uniform writer clock requires both positive `fps` and seconds offset `frame0`; canonical pose input does not yet declare FPS, so the retarget producer always writes exact `frameTimes`.
 
 
 | field | each entry |
@@ -179,6 +180,8 @@ Report event objects with a pose `frame` or inclusive `frames` also carry exact
 | `jitter` | `{ bone, chain, joints, against, rig, pair, ratio, triples, reach }`: the `JITTER` line's figures, one per bone a chain keys. `rig` and `pair` are mean \|second difference\| in °/frame², `against` the keyed bone above whose pair the pose's local angle is read against (`null` at the top), `ratio` = `rig` ÷ `pair` (`null` when the pair is still: its figure rounds to 0), `triples` how many three-frame runs both were read over, `reach` whether the chain has `"reach"` |
 | `reach` | `{ chain, bone, joints, anchor, offset: { units, ofLength }, above: [{ bone, property, chain }], departure: { max, frame, t, meanD2 }, aimD2, pairD2, ratio }`: the `REACH` line's figures, one per `reach` chain whose aim departs from its pair; empty when none does. `offset` is the bone's setup distance from the anchor's origin (units, and a fraction of the reached length), `above` the bones over it the animation turns (`rotate`, with the chain that turns it) or translates other than by the anchor's travel (`translate`), `departure` the aim − the pair's angle (largest \|·\| in degrees, its frame, and its mean \|second difference\|), `aimD2` and `pairD2` the two angles' mean \|second difference\| over every frame, `ratio` = `aimD2` ÷ `pairD2` |
 | `folds` | `{ slot, attachment, times }`: every mesh `rigc render --folds` saw fold, at those seconds; `null` when it did not read |
+| `seams` | `{ pair, kind, frames: [first, last], times: [first, last], maxPx, domain: "render" }`: one per consecutive span of one kind (`gap` or `ghost`) over the one-cell floor, per declared pair (`"<a>\|<b>"`), in the pairs' order, gap before ghost; `frames` are the seam render's frame indices (rigc's `f<index>.png`) and `times` rigc's seconds, `maxPx` the most cells on a frame of the span. `[]` when none opens, when no pair is declared, and when none was read — `seamPairs` says which. Always present: the writer refuses a report without it (`REPORT_SEAMS`) |
+| `seamPairs` | `{ pair, declared, status, opens, maxPx, underFloor, reason? }`: one per declared pair. `status` is `read`, `skip` (rigc read no band: nothing measured) or `unread` (not rendered; `reason` says why); `opens` the render frames over the floor, `underFloor` those rigc named that were one cell thick, `declared` where `parts.json` declared it. `[]` when no pair is declared. Always present (`REPORT_SEAMS`) |
 
 The demand lists:
 

package/cli.ts

@@ -180,7 +180,12 @@ retarget
   --profile spine|spine-html  rigc's gate profile (default: spine, rigc's own default)
   --build <dir>         keep the gated build (skeleton.json, .atlas, .model.json) here
   --render <dir>        keep rigc's render of the animation (frames, contact.png, folds.json) here
-  --report <file>       write the run's measurements (holds, short, endOn, flips, bends, landings, folds,
+  --parts <path>        @rig-c/parts' parts.json, or the directory holding it (its build's --out, beside rig/):
+                        the neighbour pairs the seam reading reads — each limb's consecutive segments. Each
+                        pair is read by rigc render --seam over the new animation and every span of a gap or
+                        a ghost thicker than one cell prints a SEAM line and a report seams row; a reading,
+                        never a gate. Without it no pair is declared (a rig spec carries none): seams: []
+  --report <file>       write the run's measurements (holds, short, endOn, flips, bends, landings, folds, seams,
                         switches, uncovered, turns, range, artRange, raised, byHip,
                         idleDropped, idleKeptOut, merged, reduce) as JSON (default: <out>.report.json beside
                         the motion, a trailing .json of --out replaced); its wrote line names the mtime of a
@@ -315,7 +320,7 @@ function legScaleOf(f: Map<string, string>): [number, number] | 'off' {
 const RETARGET_ALIASES = { sequence: 'pose', animation: 'name' } as const;
 
 function retargetArgs(argv: string[]): RetargetArgs {
-  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'images', 'min-score', 'smooth', 'flip', 'short', 'bends', 'bend-tolerance', 'switch-tolerance', 'switch-min', 'switch-at', 'profile', 'build', 'render', 'report', 'camera', 'leg-scale', 'idle', 'merge', 'reduce', 'reduce-hip', 'stance', 'floor'], ['coco', 'plant-feet', 'carry-idle', 'raised-by-head', 'verbose', 'summary'], RETARGET_ALIASES);
+  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'images', 'min-score', 'smooth', 'flip', 'short', 'bends', 'bend-tolerance', 'switch-tolerance', 'switch-min', 'switch-at', 'profile', 'build', 'render', 'parts', 'report', 'camera', 'leg-scale', 'idle', 'merge', 'reduce', 'reduce-hip', 'stance', 'floor'], ['coco', 'plant-feet', 'carry-idle', 'raised-by-head', 'verbose', 'summary'], RETARGET_ALIASES);
   if (f.has('verbose') && f.has('summary')) throw new Usage('--verbose and --summary are both given; --verbose prints every line in full and --summary one line per measure, so give one');
   const bends = f.get('bends') ?? 'refuse';
   if (bends !== 'refuse' && bends !== 'clamp') throw new Usage(`--bends is "${bends}"; it must be refuse or clamp`);
@@ -352,6 +357,7 @@ function retargetArgs(argv: string[]): RetargetArgs {
     profile,
     build: f.get('build'),
     render: f.get('render'),
+    parts: f.get('parts'),
     report: f.get('report'),
     camera: f.get('camera'),
     idle: f.get('idle'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Puts motion from a body-18 pose sequence onto a rig built with rig-c: bone keys in rig-c's motion format, checked through rig-c's gate before anything is written. A CLI for agents that cannot see the rig.",
   "type": "module",
   "bin": {
@@ -46,7 +46,7 @@
     "prepublishOnly": "bun run typecheck && bun run lint && bun run test"
   },
   "dependencies": {
-    "rig-c": "^2.47.1"
+    "rig-c": "^2.60.0"
   },
   "devDependencies": {
     "@esotericsoftware/spine-core": "4.3.13",

package/src/report.ts

@@ -56,10 +56,12 @@ export function enrichReport(input:Record<string,unknown>,map:JointMap,clock:Rep
     if(Array.isArray(value)){value.forEach((row,i)=>visit(row,`${where}[${i}]`));return;}
     if(!isObject(value))return;
     // Preserve uncovered's discrete renderer times; they do not index the pose.
-    if(where.startsWith('report.uncovered[')||where.startsWith('report.folds[')){
+    if(where.startsWith('report.uncovered[')||where.startsWith('report.folds[')||where.startsWith('report.seams[')){
       if(!render)fail(where,'render-domain event requires declared renderer metadata');
       add(value,'domain','render',where);return;
     }
+    // seamPairs' frame lists are the seam render's indices (#216); they carry no pose coordinate.
+    if(where.startsWith('report.seamPairs['))return;
     let coordinates=false;
     if(poseEvent(where)&&value.frame!==undefined&&typeof value.frame!=='number')fail(where+'.frame','expected nonnegative integer pose frame');
     if(typeof value.frame==='number'){add(value,'t',time(value.frame,where+'.frame'),where);coordinates=true;}
@@ -85,4 +87,26 @@ export function enrichReport(input:Record<string,unknown>,map:JointMap,clock:Rep
   if(inputs!==undefined){if(!isObject(inputs))throw new Refusal([{code:'REPORT_INPUTS',text:'inputs: expected rig, map and pose file identities'}]);for(const key of ['rig','map','pose'] as const){const entry=inputs[key];if(!isObject(entry)||typeof entry.path!=='string'||!entry.path||entry.path.startsWith('/')||entry.path.charCodeAt(0)===92||/^[A-Za-z]:/.test(entry.path)||typeof entry.sha256!=='string'||! /^[a-f0-9]{64}$/.test(entry.sha256))throw new Refusal([{code:'REPORT_INPUTS',text:`inputs.${key}: expected invocation-relative consumed file path and exact SHA-256`}]);}add(report,'inputs',clone(inputs),'report');}
   problems.throwIfAny();return report;
 }
-export function writeReport(input:Record<string,unknown>,map:JointMap,clock:ReportClock,render:RenderDomain|null,inputs:ReportInputs):string {if(inputs===undefined)throw new Refusal([{code:'REPORT_INPUTS',text:'inputs: expected rig, map and pose file identities'}]);return JSON.stringify(enrichReport(input,map,clock,render,inputs),null,2)+'\n';}
+/**
+ * rig-c/pose#216: `seams` and `seamPairs` are declared fields, not optional by
+ * accident — a report without them is a run whose seam reading never ran, and
+ * the writer refuses it by name. Each `seams` row is one span of one kind:
+ * `{ pair, kind, frames: [first, last], times: [first, last], maxPx }`.
+ */
+export function checkSeams(input:Record<string,unknown>):void {
+  const p=new Problems();
+  if(!Array.isArray(input.seams))p.add('REPORT_SEAMS',`seams: found ${input.seams===undefined?'no field':JSON.stringify(input.seams)}; the report declares the seam reading's spans (rig-c/pose#216), [] when none opens or no pair is declared, and seamPairs says which`);
+  if(!Array.isArray(input.seamPairs))p.add('REPORT_SEAMS',`seamPairs: found ${input.seamPairs===undefined?'no field':JSON.stringify(input.seamPairs)}; the report declares what the seam reading said of each declared pair (rig-c/pose#216), [] when none is declared`);
+  p.throwIfAny();
+  const int=(v:unknown)=>Number.isSafeInteger(v)&&(v as number)>=0;
+  (input.seams as unknown[]).forEach((row,i)=>{
+    const ok=isObject(row)&&typeof row.pair==='string'&&row.pair.includes('|')&&(row.kind==='gap'||row.kind==='ghost')&&Array.isArray(row.frames)&&row.frames.length===2&&row.frames.every(int)&&(row.frames[1] as number)>=(row.frames[0] as number)&&Array.isArray(row.times)&&row.times.length===2&&row.times.every(t=>typeof t==='number'&&Number.isFinite(t)&&t>=0)&&(row.times[1] as number)>=(row.times[0] as number)&&int(row.maxPx)&&(row.maxPx as number)>0;
+    if(!ok)p.add('REPORT_SEAMS',`seams[${i}]: found ${JSON.stringify(row)}; expected { pair: "<a>|<b>", kind: "gap"|"ghost", frames: [first, last], times: [first, last], maxPx > 0 }`);
+  });
+  (input.seamPairs as unknown[]).forEach((row,i)=>{
+    const ok=isObject(row)&&typeof row.pair==='string'&&(row.status==='read'||row.status==='skip'||row.status==='unread')&&(row.status!=='unread'||typeof row.reason==='string');
+    if(!ok)p.add('REPORT_SEAMS',`seamPairs[${i}]: found ${JSON.stringify(row)}; expected { pair, status: "read"|"skip"|"unread", reason when unread }`);
+  });
+  p.throwIfAny();
+}
+export function writeReport(input:Record<string,unknown>,map:JointMap,clock:ReportClock,render:RenderDomain|null,inputs:ReportInputs):string {checkSeams(input);if(inputs===undefined)throw new Refusal([{code:'REPORT_INPUTS',text:'inputs: expected rig, map and pose file identities'}]);return JSON.stringify(enrichReport(input,map,clock,render,inputs),null,2)+'\n';}

package/src/rigc.ts

@@ -231,6 +231,24 @@ export function folds(build: string, animation: string, dir: string, fps: number
   };
 }
 
+/**
+ * `rigc render --seam <a>:<b>,…` over one animation (rig-c/pose#216): its own
+ * render, apart from the folds' so a seam refusal cannot cost the fold reading
+ * and the fold render's arguments stay what they were. `seam` is the set's
+ * `seam.json` text, null when the render did not run green; `frames` is its
+ * `frames.json`, for the render domain.
+ */
+export function seamRender(build: string, animation: string, dir: string, fps: number, pairs: ReadonlyArray<readonly [string, string]>): { run: RigcRun; seam: { text: string; path: string } | null; frames: unknown } {
+  const out = join(dir, 'render');
+  const run = runRigc(['render', '--candidate', build, '--animation', animation, '--seam', pairs.map(([a, b]) => `${a}:${b}`).join(','), '--fps', String(fps), '--out', out]);
+  if (run.status !== 0 || !existsSync(join(out, 'frames.json'))) return { run, seam: null, frames: null };
+  const framesDoc = JSON.parse(readFileSync(join(out, 'frames.json'), 'utf8')) as { sets: Array<{ dir: string; animation: string }> };
+  const set = framesDoc.sets.find((s) => s.animation === animation);
+  const path = set === undefined ? null : join(resolve(out), set.dir, 'seam.json');
+  if (path === null || !existsSync(path)) return { run, seam: null, frames: framesDoc };
+  return { run, seam: { text: readFileSync(path, 'utf8'), path }, frames: framesDoc };
+}
+
 /** rig-c's version and the entry its launcher picked (`rigc --version`), so a run names the compiler that gated it. */
 export function rigcVersion(): { version: string; entry: string } {
   const r = runRigc(['--version']);

package/src/run.ts

@@ -14,7 +14,8 @@ import { convertCoco17, personTrack, readPoseSequence, TRAVEL_IN_PLACE, type Cam
 import { isObject, lineOf, parseJson, Problems, Refusal, type Problem } from './problems.ts';
 import { boneIdentity, droppedLine, keptOutLine, mergeProblems, readFragment, readIdle, targetOf, trackLabel, type IdleReading, type RigcTrack, type Target } from './idle.ts';
 import { bendGroupLine, bendGroups, bendLine, endOnLine, flipLine, holdLine, nodLine, rangeLine, reachCostLine, retarget, shortLine, turnLine, type MotionTrack, type RetargetOptions, type ScaleBand, type ScaleFit } from './retarget.ts';
-import { attachmentBones, baseMotionOf, buildInto, rigcVersion, folds, gate, readBuild, resolveRig, restOf, slotsOf } from './rigc.ts';
+import { attachmentBones, baseMotionOf, buildInto, rigcVersion, folds, gate, readBuild, resolveRig, restOf, seamRender, slotsOf } from './rigc.ts';
+import { partsPath, projectSeams, readSeamDoc, readSeamPairs, seamLines, type SeamPair } from './seams.ts';
 import { artRangeLine, chainsMoving, raisedLine, RAISED_WITHIN, reachLine, switchLine, uncoveredFolds } from './switch.ts';
 import { jitterLine, landed, type FeetReading, type JitterRow, type Landing, measureFeet, measureJitter, measureLanding, measurePosture, measureShear, poseFrames, postureLines } from './verify.ts';
 import { legsOf, PLANT_SWITCH, STANCE_BOUNDS } from './legs.ts';
@@ -41,6 +42,8 @@ export interface RetargetArgs extends RetargetOptions {
   build?: string;
   /** Keep rigc's render of the animation (frames, contact sheet, folds.json) here. */
   render?: string;
+  /** @rig-c/parts' `parts.json` (or the directory holding it): the neighbour pairs the seam reading reads (#216). */
+  parts?: string;
   /** Write the run's measurements as JSON here. */
   report?: string;
   /** Write the sequence's per-frame relative figure scale and pan as a sidecar JSON here (#161). */
@@ -112,6 +115,11 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
   if (!(idleName in animations) && (a.idle !== undefined || a.carryIdle === true)) {
     refuse([{ code: 'IDLE_NAME', text: `${a.idle !== undefined ? `--idle "${idleName}"` : '--carry-idle reads the animation "idle", and'} the rig's motion spec ${input.motion === null ? '— there is none, so it has no animations' : `${input.motion} has no animation "${idleName}" (it has ${Object.keys(animations).join(', ') || 'none'})`}; name the rig's idle with --idle` }]);
   }
+  // #216: the neighbour pairs, read before any work so a bad --parts is refused first.
+  const seamDecl = a.parts === undefined ? null : (() => {
+    const path = partsPath(a.parts);
+    return { path, pairs: readSeamPairs(readFileSync(path, 'utf8'), path) };
+  })();
   const fragment = a.merge === undefined ? [] : readFragment(parseJson(readFileSync(a.merge, 'utf8'), a.merge, 'MERGE_JSON'), a.merge);
   const mapSnapshot = readReportInput(a.map), poseSnapshot = readReportInput(a.pose);
   const map = readMap(mapSnapshot.bytes.toString('utf8'), a.map);
@@ -347,6 +355,10 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       for (const u of uncovered) say(`  UNCOVERED mesh "${u.attachment}" (slot "${u.slot}"; chains ${u.chains.length === 0 ? 'none' : u.chains.join(', ')}) folds with no switch covering it on ${u.times.length} frame(s): t=${spans(u.times, 1 / fps)}`);
     }
 
+    // #216: the seam reading over the declared neighbour pairs — a reading, never a gate.
+    const seamRead = readSeams(seamDecl, input.rig, doc.slots.map((s) => s.name), g1.build, a.name, join(scratch, 'seams'), fps);
+    for (const l of seamRead.lines) say(`  SEAM   ${l}`);
+
     // #240: what --reduce allowed each ankle, at the end of the run, from the same figure the LAND check applied.
     for (const d of drift) say(`  REDUCE ${ankleDriftLine(d)}`);
 
@@ -372,6 +384,8 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         jitter,
         posture,
         folds: f.meshes,
+        seams: seamRead.seams,
+        seamPairs: seamRead.seamPairs,
         switches: r.switches,
         uncovered,
         turns: r.turns,
@@ -411,7 +425,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         idleKeptOut: idle === null ? null : idle.keptOut,
         merged: fragment.map((tr) => ({ track: trackLabel(tr, groups), keys: tr.keys.length })),
         reduce: reduced === null ? null : { tolerance: a.reduce, hipTolerance: a.reduceHip ?? null, rows: reduced.rows, ankleDrift: drift },
-      }, map, { frameTimes: r.times }, f.meshes !== null && doc.slots.length > 0 ? reportRenderDomain(JSON.parse(readFileSync(join(f.frames, '..', 'frames.json'), 'utf8')), a.name) : null, {rig:rigSnapshot.identity,map:mapSnapshot.identity,pose:poseSnapshot.identity});
+      }, map, { frameTimes: r.times }, f.meshes !== null && doc.slots.length > 0 ? reportRenderDomain(JSON.parse(readFileSync(join(f.frames, '..', 'frames.json'), 'utf8')), a.name) : seamRead.frames === null ? null : reportRenderDomain(seamRead.frames, a.name), {rig:rigSnapshot.identity,map:mapSnapshot.identity,pose:poseSnapshot.identity});
     if (a.build !== undefined) {
       // Built again where it will live, not copied: rigc's page paths are relative to the build (#18).
       rmSync(a.build, { recursive: true, force: true });
@@ -1016,6 +1030,53 @@ export function assertReportInputs(inputs:readonly ReportInputSnapshot[]):void {
   for(const expected of inputs){const current=readReportInput(expected.file);if(current.identity.path!==expected.identity.path||current.identity.sha256!==expected.identity.sha256)throw new Refusal([{code:'REPORT_INPUTS_CHANGED',text:`${expected.identity.path}: consumed input changed before output writes; expected SHA-256 ${expected.identity.sha256}, found ${current.identity.sha256}`}]);}
 }
 
+/**
+ * #216: the seam reading end to end — the declared pairs, each pair whose part
+ * has no slot of its name left unread (rigc would refuse the whole render for
+ * it), one `rigc render --seam` over the rest, and its projection. Whatever it
+ * finds, or fails to read, it says so and refuses nothing.
+ */
+function readSeams(decl: { path: string; pairs: SeamPair[] } | null, rig: string, slotNames: string[], build: string, animation: string, dir: string, fps: number): ReturnType<typeof projectSeams> & { lines: string[]; frames: unknown } {
+  if (decl === null || decl.pairs.length === 0) {
+    let why: string;
+    if (decl !== null) why = `${decl.path} holds no limb segment below another (a part's "limb" record), so it declares no pair`;
+    else {
+      // @rig-c/parts writes rig/ and parts.json side by side under its --out; a rig spec itself carries no pair.
+      const home = dirname(dirname(rig));
+      why = `a rig spec carries none and no --parts was named${existsSync(join(home, 'parts.json')) ? ` (${home} holds parts.json: --parts ${home} reads its limbs)` : ''}`;
+    }
+    return { seams: [], seamPairs: [], frames: null, lines: [`no neighbour pair declared — ${why}; seams: []`] };
+  }
+  const have = new Set(slotNames);
+  const unread = new Map<string, string>();
+  for (const p of decl.pairs) {
+    const missing = [p.a, p.b].filter((n) => !have.has(n));
+    if (missing.length > 0) unread.set(p.pair, `${missing.map((n) => `part "${n}"`).join(' and ')} has no slot of its name in the rig (a part is drawn by the slot of its name)`);
+  }
+  const toRead = decl.pairs.filter((p) => !unread.has(p.pair));
+  let rows: ReturnType<typeof readSeamDoc> = [];
+  let frames: unknown = null;
+  if (toRead.length > 0) {
+    const s = seamRender(build, animation, dir, fps, toRead.map((p) => [p.a, p.b] as const));
+    let why: string | null = null;
+    if (s.seam === null) {
+      const said = s.run.out.split('\n').map((l) => l.trim()).find((l) => l.startsWith('rigc: ') && !l.startsWith('rigc: wrote'));
+      why = `rigc render --seam did not read (exit ${s.run.status})${said === undefined ? '' : `: ${said}`}`;
+    } else {
+      try {
+        rows = readSeamDoc(s.seam.text, s.seam.path);
+        frames = s.frames;
+      } catch (e) {
+        if (!(e instanceof Refusal)) throw e;
+        why = e.message;
+      }
+    }
+    if (why !== null) for (const p of toRead) unread.set(p.pair, why);
+  }
+  const projected = projectSeams(decl.pairs, rows, unread);
+  return { ...projected, frames, lines: seamLines(projected, fps) };
+}
+
 /** rig-c/pose#239: the report's path when --report is not given — `<out>.report.json`, beside the motion (a trailing `.json` of --out is replaced). */
 export function defaultReportPath(out: string): string {
   return `${out.endsWith('.json') ? out.slice(0, -'.json'.length) : out}.report.json`;

package/src/seams.ts

@@ -0,0 +1,241 @@
+/**
+ * The seam reading's projection (rig-c/pose#216): which neighbour pairs a rig
+ * declares, and what `rigc render --seam` found between them, as report rows.
+ * Pure — the render itself is `src/rigc.ts`'s.
+ *
+ * **Where the pairs come from.** A rig spec does not carry them: `rig.json`
+ * holds bones, slots and skins, and @rig-c/parts records a limb's segments in
+ * `parts.json` beside the rig directory (each part's `limb`: `name`,
+ * `segment`, and below a joint `joint`). So the pairs are read from the
+ * `parts.json` the run is given (`--parts`), the way @rig-c/parts' own
+ * `check` reads them (rig-c/parts#503): each limb's consecutive segments, the
+ * upper and the one below, a pair named twice counting once in either order.
+ * Each part is drawn by the slot of its name.
+ *
+ * **The floor** is @rig-c/parts' (#503), so the two tools agree on what a seam
+ * opening is: a frame's gap or ghost counts when it holds more cells than its
+ * box is long (its longer side, in cells) — thicker than one cell. rigc counts
+ * a cell drawn when its centre is painted at half opacity, so an outline that
+ * moves by less than a cell flips the cells along it: a line one cell deep
+ * holds at most as many cells as its box is long, and a hole of any area more.
+ * The rule types no number; it reads rigc's own `px`, `cell` and `box`.
+ *
+ * A reading, never a gate: nothing here refuses a run for what it finds.
+ */
+import { existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { isObject, parseJson, Refusal } from './problems.ts';
+
+export type SeamKind = 'gap' | 'ghost';
+export const SEAM_KINDS: readonly SeamKind[] = ['gap', 'ghost'];
+
+/** One declared neighbour pair: two part names, each drawn by the slot of its name. */
+export interface SeamPair {
+  /** `"<a>|<b>"`, the form rigc and @rig-c/parts name a pair by. */
+  pair: string;
+  a: string;
+  b: string;
+  /** Where it was declared: `config.limbs.<limb> segment <n>, joint "<joint>"`, once per declaration. */
+  declared: string[];
+}
+
+/** One `report.json` `seams` row: one consecutive span of one kind over the floor (#216). */
+export interface SeamSpan {
+  pair: string;
+  kind: SeamKind;
+  /** Inclusive render frame indices, rigc's `f<index>.png`. */
+  frames: [number, number];
+  /** Those frames' times in seconds, rigc's. */
+  times: [number, number];
+  /** The most cells of this kind on any frame of the span. */
+  maxPx: number;
+}
+
+/** One `report.json` `seamPairs` row: what the reading said of one declared pair. */
+export interface SeamPairReading {
+  pair: string;
+  declared: string[];
+  /** `read`: rigc read a band; `skip`: rigc read none (the two drawings share no cell at rest); `unread`: not rendered, `reason` says why. */
+  status: 'read' | 'skip' | 'unread';
+  /** Frames over the floor, of either kind, ascending. */
+  opens: number[];
+  /** The most cells over the floor on any frame; 0 when none opens. */
+  maxPx: number;
+  /** Frames rigc named open whose every opening is one cell thick — under the floor, not in `seams`. */
+  underFloor: number[];
+  reason?: string;
+}
+
+const PARTS_SPEC = 'PARTS_JSON';
+
+/** `--parts`: a `parts.json`, or a directory holding one. */
+export function partsPath(path: string): string {
+  if (!existsSync(path)) throw new Refusal([{ code: 'ARG_PATH', text: `--parts ${path} does not exist` }]);
+  if (statSync(path).isDirectory()) {
+    const file = join(path, 'parts.json');
+    if (!existsSync(file)) throw new Refusal([{ code: 'ARG_PATH', text: `--parts ${path} is a directory with no parts.json (@rig-c/parts writes it to <out>/, beside rig/)` }]);
+    return file;
+  }
+  return path;
+}
+
+/**
+ * The neighbour pairs `parts.json` declares, in its limbs' order: each limb's
+ * consecutive segments by `segment`. A record that is not one is refused by
+ * name; a part with no `limb` declares nothing.
+ */
+export function readSeamPairs(text: string, path: string): SeamPair[] {
+  const doc = parseJson(text, path, PARTS_SPEC);
+  if (!isObject(doc) || !Array.isArray(doc.parts)) throw new Refusal([{ code: PARTS_SPEC, text: `${path} is not @rig-c/parts' parts.json: it has no "parts" array` }]);
+  const problems: Array<{ code: string; text: string }> = [];
+  const limbs = new Map<string, Array<{ part: string; segment: number; joint: string | undefined }>>();
+  doc.parts.forEach((p: unknown, i: number) => {
+    if (!isObject(p) || typeof p.name !== 'string' || p.name === '') {
+      problems.push({ code: PARTS_SPEC, text: `${path} parts[${i}]: expected a record with a "name" string` });
+      return;
+    }
+    if (p.limb === undefined) return;
+    const l = p.limb;
+    if (!isObject(l) || typeof l.name !== 'string' || !Number.isSafeInteger(l.segment) || (l.segment as number) < 0 || (l.joint !== undefined && typeof l.joint !== 'string')) {
+      problems.push({ code: PARTS_SPEC, text: `${path} parts[${i}] ("${p.name}") limb: expected { name: string, segment: integer ≥ 0, joint?: string }, found ${JSON.stringify(l)}` });
+      return;
+    }
+    const segs = limbs.get(l.name) ?? [];
+    if (segs.some((s) => s.segment === l.segment)) problems.push({ code: PARTS_SPEC, text: `${path} parts[${i}] ("${p.name}"): limb "${l.name}" segment ${String(l.segment)} is already part "${segs.find((s) => s.segment === l.segment)!.part}"` });
+    segs.push({ part: p.name, segment: l.segment as number, joint: l.joint as string | undefined });
+    limbs.set(l.name, segs);
+  });
+  if (problems.length > 0) throw new Refusal(problems);
+  const out: SeamPair[] = [];
+  for (const [limb, segs] of limbs) {
+    segs.sort((x, y) => x.segment - y.segment);
+    for (let i = 1; i < segs.length; i++) {
+      const [up, low] = [segs[i - 1]!, segs[i]!];
+      const declared = `config.limbs.${limb} segment ${low.segment}${low.joint === undefined ? '' : `, joint "${low.joint}"`}`;
+      const hit = out.find((x) => (x.a === up.part && x.b === low.part) || (x.a === low.part && x.b === up.part));
+      if (hit !== undefined) hit.declared.push(declared);
+      else out.push({ pair: `${up.part}|${low.part}`, a: up.part, b: low.part, declared: [declared] });
+    }
+  }
+  return out;
+}
+
+/** A frame's opening of one kind is over the floor when it holds more cells than its box, in cells, is long. */
+export function overFloor(hit: { px: number; cell: number; box: readonly number[] }): boolean {
+  const long = Math.round(Math.max(hit.box[2]! - hit.box[0]!, hit.box[3]! - hit.box[1]!) / hit.cell);
+  return hit.px > long;
+}
+
+interface SeamHit {
+  index: number;
+  time: number;
+  px: number;
+  cell: number;
+  box: number[];
+}
+interface SeamDocPair {
+  a: string;
+  b: string;
+  status: 'read' | 'skip';
+  opens: number[];
+  gap: { frames: SeamHit[] };
+  ghost: { frames: SeamHit[] };
+}
+
+/** `seam.json` (`rigc-seam/1`): the fields this projection reads, checked; anything else is rigc's. */
+export function readSeamDoc(text: string, path: string): SeamDocPair[] {
+  const doc = parseJson(text, path, 'SEAM_JSON');
+  const bad = (what: string): never => {
+    throw new Refusal([{ code: 'SEAM_JSON', text: `${path}: ${what}; rig-c's rigc-seam/1 (its AUTHORING §8.8) is the contract this reads` }]);
+  };
+  if (!isObject(doc) || doc.spec !== 'rigc-seam/1' || !Array.isArray(doc.pairs)) return bad('expected spec "rigc-seam/1" with a "pairs" array');
+  return doc.pairs.map((p: unknown, i: number) => {
+    if (!isObject(p) || typeof p.a !== 'string' || typeof p.b !== 'string' || (p.status !== 'read' && p.status !== 'skip') || !Array.isArray(p.opens)) return bad(`pairs[${i}]: expected a, b, status read|skip, opens`);
+    const kind = (k: SeamKind) => {
+      const o = p[k];
+      if (!isObject(o) || !Array.isArray(o.frames)) return bad(`pairs[${i}].${k}: expected { frames }`);
+      const frames = o.frames.map((h: unknown, j: number) => {
+        if (!isObject(h) || !Number.isSafeInteger(h.index) || typeof h.time !== 'number' || !Number.isSafeInteger(h.px) || typeof h.cell !== 'number' || !(h.cell > 0) || !Array.isArray(h.box) || h.box.length !== 4 || !h.box.every((v) => typeof v === 'number')) {
+          return bad(`pairs[${i}].${k}.frames[${j}]: expected index, time, px, cell > 0, box [minX, minY, maxX, maxY]`);
+        }
+        return { index: h.index as number, time: h.time, px: h.px as number, cell: h.cell, box: h.box as number[] };
+      });
+      return { frames };
+    };
+    return { a: p.a, b: p.b, status: p.status, opens: p.opens.filter((n): n is number => typeof n === 'number'), gap: kind('gap'), ghost: kind('ghost') };
+  });
+}
+
+/** Runs of consecutive frame indices among `hits` (ascending), each with its first and last time and its most cells. */
+function runsOf(hits: readonly SeamHit[]): Array<{ frames: [number, number]; times: [number, number]; maxPx: number }> {
+  const out: Array<{ frames: [number, number]; times: [number, number]; maxPx: number }> = [];
+  for (const h of hits) {
+    const last = out[out.length - 1];
+    if (last !== undefined && h.index === last.frames[1] + 1) {
+      last.frames[1] = h.index;
+      last.times[1] = h.time;
+      last.maxPx = Math.max(last.maxPx, h.px);
+    } else out.push({ frames: [h.index, h.index], times: [h.time, h.time], maxPx: h.px });
+  }
+  return out;
+}
+
+/**
+ * The report's rows from one `seam.json`: per declared pair its reading, and
+ * per pair and kind one row per consecutive span of frames over the floor —
+ * in the pairs' order, gap before ghost, spans in frame order.
+ */
+export function projectSeams(pairs: readonly SeamPair[], doc: readonly SeamDocPair[], unread: ReadonlyMap<string, string>): { seams: SeamSpan[]; seamPairs: SeamPairReading[] } {
+  const seams: SeamSpan[] = [];
+  const seamPairs: SeamPairReading[] = [];
+  for (const p of pairs) {
+    const why = unread.get(p.pair);
+    const d = doc.find((x) => x.a === p.a && x.b === p.b);
+    if (why !== undefined || d === undefined) {
+      seamPairs.push({ pair: p.pair, declared: p.declared, status: 'unread', opens: [], maxPx: 0, underFloor: [], reason: why ?? 'seam.json holds no row for it' });
+      continue;
+    }
+    const opens = new Set<number>();
+    let maxPx = 0;
+    for (const k of SEAM_KINDS) {
+      const over = d[k].frames.filter(overFloor);
+      for (const h of over) {
+        opens.add(h.index);
+        maxPx = Math.max(maxPx, h.px);
+      }
+      for (const r of runsOf(over)) seams.push({ pair: p.pair, kind: k, frames: r.frames, times: r.times, maxPx: r.maxPx });
+    }
+    const sorted = [...opens].sort((x, y) => x - y);
+    seamPairs.push({ pair: p.pair, declared: p.declared, status: d.status, opens: sorted, maxPx, underFloor: d.opens.filter((f) => !opens.has(f)) });
+  }
+  return { seams, seamPairs };
+}
+
+/** Frame indices as runs, `[0-6, 8, 13]`, the form rigc prints a frame list in. */
+export function frameRuns(frames: readonly number[]): string {
+  const runs: string[] = [];
+  for (let i = 0; i < frames.length; ) {
+    let j = i;
+    while (j + 1 < frames.length && frames[j + 1] === frames[j]! + 1) j++;
+    runs.push(i === j ? String(frames[i]) : `${frames[i]}-${frames[j]}`);
+    i = j + 1;
+  }
+  return `[${runs.join(', ')}]`;
+}
+
+/** The run's `SEAM` lines: one per span, one per pair not read or skipped, and the count. */
+export function seamLines(r: { seams: readonly SeamSpan[]; seamPairs: readonly SeamPairReading[] }, fps: number): string[] {
+  const out: string[] = [];
+  for (const s of r.seams) {
+    out.push(`pair "${s.pair}" ${s.kind} on frame(s) ${s.frames[0]}-${s.frames[1]} (t=${s.times[0].toFixed(3)}–${s.times[1].toFixed(3)}s) at ${fps} fps, max ${s.maxPx} px — over the one-cell floor; a reading, not a gate`);
+  }
+  for (const p of r.seamPairs) {
+    if (p.status === 'unread') out.push(`pair "${p.pair}": not read — ${p.reason}`);
+    else if (p.status === 'skip') out.push(`pair "${p.pair}": SKIP — rigc read no band (the two drawings share no cell at the setup pose), so nothing was measured`);
+    else if (p.underFloor.length > 0) out.push(`pair "${p.pair}": ${p.underFloor.length} frame(s) ${frameRuns(p.underFloor)} open one cell thick, under the floor — not reported`);
+  }
+  const read = r.seamPairs.filter((p) => p.status === 'read').length;
+  const pairsOpen = new Set(r.seams.map((s) => s.pair)).size;
+  out.push(`${r.seams.length} span(s) over ${pairsOpen} pair(s) at ${fps} fps — ${read} of ${r.seamPairs.length} declared pair(s) read; a reading, not a gate`);
+  return out;
+}