@rig-c/pose 0.32.0 → 0.34.0

package/README.md

@@ -109,7 +109,7 @@ rig-pose retarget --rig out/rig --map map.json --sequence dance.pose.json --out
 
 **Names** ([#243](https://github.com/rig-c/pose/issues/243)). `--sequence` and `--animation` are the names the rest of the toolchain gives these inputs (rig-c/exam's grader, `rigc render --animation`); `--pose` and `--name`, this command's first names, are the same flags. Both of a pair given with the same value is accepted; with different values the run is refused before anything is read, naming both (`--pose "a.json" and --sequence "b.json" are both given and differ; --sequence is another name for --pose, so give one`). Either spelling writes the same bytes.
 
-**Paths** ([#239](https://github.com/rig-c/pose/issues/239)). `--rig` is the directory @rig-c/parts writes, `<out>/rig/`: it reads `rig.json` and the `motion.json` beside it. Naming the `rig.json` itself reads no motion spec, so a rig that needs its own animations — a slider applies one — is red before anything is added, and the `RIG_GATE_BASE` line says the `motion.json` beside it was not read and names the directory form (or `--base-motion`). A directory `--out`, `--report` or `--camera` names that is not there yet is made once the run is green, and a `made directory <dir>` line says so and which paths it holds; a red run makes none, and a file where a directory has to be made is refused (`ARG_PATH`). The report is always written: without `--report` it goes beside the motion as `<out>.report.json` (`motion.json` → `motion.report.json`), and its `wrote` line says it was the default. A report that is already at that path is replaced, and the `wrote` line names when the replaced one was last written (its mtime, ISO 8601), so a second run to the same path is never silent. None of this changes the motion's bytes.
+**Paths** ([#239](https://github.com/rig-c/pose/issues/239)). `--rig` is the directory @rig-c/parts writes, `<out>/rig/`: it reads `rig.json` and the `motion.json` beside it. Naming the `rig.json` itself reads no motion spec, so a rig that needs its own animations — a slider applies one — is red before anything is added, and the `RIG_GATE_BASE` line says the `motion.json` beside it was not read and names the directory form (or `--base-motion`). When the gate is green without it, the run goes on and `--out` carries none of the rig's own animations, so a `MOTION` line says the same thing, in every output mode ([#250](https://github.com/rig-c/pose/issues/250)). A directory `--out`, `--report` or `--camera` names that is not there yet is made once the run is green, and a `made directory <dir>` line says so and which paths it holds; a red run makes none, and a file where a directory has to be made is refused (`ARG_PATH`). The report is always written: without `--report` it goes beside the motion as `<out>.report.json` (`motion.json` → `motion.report.json`), and its `wrote` line says it was the default. A report that is already at that path is replaced, and the `wrote` line names when the replaced one was last written (its mtime, ISO 8601), so a second run to the same path is never silent. None of this changes the motion's bytes.
 
 For every frame of the pose and every bone the map names, the segment that bone carries (an upper arm: shoulder → elbow) points somewhere in the picture. The bone is turned so its segment points the same way: the picture angle, flipped into rig-c's y-up world, minus the bone's angle at the rig's setup pose (read through rig-c's own poser), less the turn of the mapped bone above it — because a `rotate` key in rig-c adds to the setup rotation and a child turns with its parent. The travel of the pelvis midpoint, scaled by a length measured on both the rig and the pose, moves the hip. When a head chain carries the eye line (`r_eye → l_eye`), the eyes' vertical travel against `neck` in the reference, scaled into the rig's units, keys a vertical `translate` nod channel on the head bone ([#111](https://github.com/rig-c/pose/issues/111)) clamped within `±2%` of the setup neck length (`head − neck`, [#181](https://github.com/rig-c/pose/issues/181)), while on sequences where that clamp acts, the clamped vertical nod (`clampedY`) is coupled in phase into `face.pitch`'s dial (`+2.8°/unit`, mapped through `face.pitch.range`) and the head bone's `rotate` track (`+1.6°/unit`, [#190](https://github.com/rig-c/pose/issues/190), [#205](https://github.com/rig-c/pose/issues/205); gains calibrated against the hand-polished reference `p1`). **How the nod's baseline is read** ([#241](https://github.com/rig-c/pose/issues/241)): on a sequence declared `"travel": "in-place"` it is frame 0, with no window, no clamp and so no coupling ([#242](https://github.com/rig-c/pose/issues/242)); otherwise it is a ±0.5 s running median of the eyes' height against the neck, averaged again over the same window, and the nod is the eyes' height less it. On a sequence `clean --loop` wrote (its `cleaned.params.loop`) and not declared in place, that window **wraps**, the last frame running into the first, as clean's own windows do; cut at the clip's ends instead, the two ends are read against one-sided baselines, and the coupling carries the difference into the head's rotate. On the tests' synthetic loop (#242's walk, 7 cycles of 24 frames, the eyes bobbing 3 px twice a cycle, `travel` deleted), the wrapped window puts cycle 7 on cycle 1 to 0.000° and 0.000 units; cut at the ends it was 1.057° on the rotate and 0.661 units on the nod. `"nod": false` on the eye-line chain ([below](#the-map-rig-pose-map1)) keys no nod and couples none. The `NOD` line says which of these happened. The result is one animation in rig-c's motion format (`rigc-motion/1`): a `rotate` track per mapped bone, a `translate` track on the hip (and on the head when the reference nods), one key per pose frame — and, when the map lists alternate drawings, an `attachment` track per slot they switch (and a `translate` track per bone a set offsets).
 
@@ -126,6 +126,7 @@ Nothing is written until every check passes:
 and what the run cannot decide for you it lists:
 
 - `CLEAN` — what `rig-pose clean` did to the sequence: its windows, spikes, jitter before → after, and the stillness hold counted — holds, joints, regions and their frames, the joint spans not held, the seams ([#238](https://github.com/rig-c/pose/issues/238)). The per-joint record is the sequence's `cleaned` (`holds`, `unheld`, `seams`), which `--report` writes whole; `--verbose` prints it on the line.
+- `MOTION` — `--rig` named a `rig.json` with a `motion.json` beside it that was not read, and the gate passed anyway ([#250](https://github.com/rig-c/pose/issues/250)): the file, and the two forms that read it. Printed under `--summary` too.
 - `RIGC` — the rig-c version and entry that gated and posed the run (also `rigc` in the report): a later rig-c can change the bytes.
 - `SCALE` — when the map translates a bone: the figure scale, `scale.rig` over the median picture length of `scale.pose`, and ([#240](https://github.com/rig-c/pose/issues/240)) that median as a share of the segment's 95th percentile — under 1, the median frame foreshortens the segment and the factor is that much larger than the segment at its longest gives. Then a `bands` line: the rig-to-picture ratio of the legs (hip → ankle: the rig's at setup over the picture's 95th percentile, to over its median, either side) and of the hips (thigh roots apart at setup over `r_hip → l_hip`'s 95th percentile, to over its median), each `within` or `outside` — within when the rig's length carried into the picture by the factor (rig ÷ factor) lies between the picture's median and 95th percentile give or take one picture px, so a band the picture never widened is not missed by a rounding the picture cannot show (the wave re-cleaned with the hold on reads a factor of 1.00001 against a hip band of exactly 1.00000); an `outside both bands` line when the factor lies outside both — the scale pair sizes the figure as neither its legs nor its hips do; and a `hip travel` line, the translated joint's x and y range, the pose's in px beside the keyed bone's in units, each also in leg lengths (`legs`: the two sides' mean, the picture's 95th percentile and the rig's at setup) and hip widths (`hips`: the picture's 95th percentile, the rig's thigh roots at setup). A reading (`scaleFit` in the report); nothing it prints changes a key. The wave: leg 0.99698–0.99698 and hip 1.00000–1.00000, both within; no `outside both bands` line.
 - `HOLD` — a joint missing, or scored under `--min-score`, holds its last good value; one line per span, with the frames and the reason.
@@ -134,6 +135,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`.
@@ -150,7 +152,7 @@ and what the run cannot decide for you it lists:
 - `STANCE` — with `--stance` ([below](#the-legs-foreshortening-and-planted-feet)): a `unit` line first, naming the tolerance's unit (`FEET`'s leg length, each side's median hip → ankle) in px and as a share of the straight leg (the 95th percentile hip → ankle) ([#237](https://github.com/rig-c/pose/issues/237)); one line per run of frames planted both (with the stretch keyed, its largest k), lifted, or past the tolerance below (the pose's height kept, [#114](https://github.com/rig-c/pose/issues/114) — printed only where no `--leg-scale` clamp moved the free ankle; otherwise the frames it moved and how far, [#237](https://github.com/rig-c/pose/issues/237)), with the free side, the frames and the tolerance in leg lengths and px; and one per run whose stretch fell past its bounds (`past the bounds`), with the k the floor needed, the bound it had and how far the foot was left from it; and, where the leg's own range set a lower bound below 0.92, one `bound from the leg's own range` line with each side's lowest.
 - `SHEAR` — with `--leg-scale`: every scaled bone and every bone under one, how far its art is sheared and how long its world axes are against setup. A reading. Where the shear prints above 0.00°, the line names where it comes from ([#240](https://github.com/rig-c/pose/issues/240)): a bone that inherits `normal` from a scaled parent (or one under a scaled bone) takes its parent's unequal axes into its art (`it inherits "normal" from scaled "…"`), and `"inherit": "noScale"` on that bone in the rig spec is the fix — it still turns with its parent, and rig-pose keys it through its parent ([#153](https://github.com/rig-c/pose/issues/153)); `onlyTranslation` removes the shear too and also stops it turning. On the tests' bent knee under a scaled thigh, the shin's 5.27° is 0.00° with `noScale`.
 - `IDLE`, `IDLE-DROPPED`, `IDLE-KEPT-OUT`, `MERGE` — the rig's idle against the new animation, and what `--carry-idle` and `--merge` put back ([below](#the-idle-what-the-retarget-drops)).
-- `REDUCE` — with `--reduce` ([below](#few-keys---reduce)): per bone, its keys before and after and its largest error, with the frame; then the total. At the end of the run, one `ankle drift allowed` line per ankle ([#240](https://github.com/rig-c/pose/issues/240)): the tolerance its `LAND` line held it to, in units and in its side's rig leg at setup, split into the plant's and the reduction's, and the two-frame slide that allows.
+- `REDUCE` — with `--reduce` ([below](#few-keys---reduce)): per bone, its keys before and after and its largest error, with the frame; then the total. At the end of the run, one `ankle drift allowed` line per ankle ([#240](https://github.com/rig-c/pose/issues/240)): the tolerance its `LAND` line held it to, in units and in its side's rig leg at setup, split into the plant's and the reduction's, and the two-frame slide that allows; with `--reduce-keep-planted`, the same for its support frames (the plant's plus the hip's), or that its side never supports.
 - `NOD` — with a chain carrying the eye line ([#241](https://github.com/rig-c/pose/issues/241)): the head bone and chain, the keyed translate's y range in units over the frames, the window its baseline was read over (`none (in-place)`, or ±*h* frames `wrapped on the loop` or `cut at the clip's ends`), and outside in place the clamp (±2% of the neck's setup length) with the frames it acted on and the coupling that follows: `NOD    bone "head" (chain "head", r_eye → l_eye): translate y -0.400 … +0.400 units over 168 frame(s); window ±12 frame(s) (0.5 s) running median, detrended, wrapped on the loop; clamp ±0.400 units (2% of the neck's setup length) acted on 140 frame(s), so the clamped nod is coupled in phase into bone "head"'s rotate (+1.6°/unit) on every frame`. When no nod is keyed it says why instead: `"nod": false`, a translate on the bone (the map's or a set's offsets), a scaled bone above it, no good neck, no scale, or eyes that do not move against the neck (the example wave).
 - `FACE` — with `face` in the map ([#138](https://github.com/rig-c/pose/issues/138), [#173](https://github.com/rig-c/pose/issues/173)): per-frame yaw and pitch read from `nose` against the eye midpoint (`r_eye + l_eye`) and, when present, the ear midpoint (`r_ear + l_ear`), de-rolled by the eye line, then compressed into each configured axis's `[min, max]` range (`scale` and correlation `r`), and, when `face.yaw.sets` (or `face.sets`) is declared, every yaw-switched set's entered spans, swap count, and any `hides` slot keyed by another track, written as `face` in `--report`.
 - `BODY` — per-frame body yaw read from the camera-normalised shoulder width (`r_shoulder + l_shoulder`) and hip width (`r_hip + l_hip`) projected perpendicular to the trunk against the sequence's standing width (`yaw ≈ acos(w / w_standing)`, [#173](https://github.com/rig-c/pose/issues/173)): its overall and opening (`frames 0–47`) range, every span with `|yaw| ≥ 45°`, and, when `body.yaw` or `body.sets` is declared in the map, its knee-mapped dial keys and every yaw-switched set's entered spans, swap count, and any `hides` slot keyed by another track, written as `body` in `--report`.
@@ -166,8 +168,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; `reduceKeepPlanted: true` only with `--reduce-keep-planted`), `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 |
@@ -175,10 +177,12 @@ Report event objects with a pose `frame` or inclusive `frames` also carry exact
 | `holds` | `{ point, from, to, source, why }`: a joint held over frames `from`–`to` at frame `source`'s value |
 | `bends` | `{ chain, joint, frame, t, angle, side, rest }`: a hinge found bent the wrong way (`angle` in degrees, Spine's sense; `side` ±1, the side it may bend) |
 | `endOn` | `{ chain, bone, joints, frames, seconds, minFraction }`: a limb pointing at the camera for ≥ 0.15 s |
-| `landings` | `{ bone, worst, frame, kind, tolerance }`: where rig-c's poser put each bone, against the target. `kind` is `angle` (degrees), `origin` or `foot` (world units), or `scale` (a fraction of the setup length). A run writes only when every `worst` ≤ `tolerance` |
+| `landings` | `{ bone, worst, frame, kind, tolerance, on? }`: where rig-c's poser put each bone, against the target. `kind` is `angle` (degrees), `origin` or `foot` (world units), or `scale` (a fraction of the setup length). With `--reduce-keep-planted` each `foot` is two rows, `on: "support"` (the frames its side supports) and `on: "off-support"` (the rest), each with its own tolerance ([#251](https://github.com/rig-c/pose/issues/251)); a side with no frame in one of them has no row for it. A run writes only when every `worst` ≤ `tolerance` |
 | `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:
 
@@ -279,6 +283,7 @@ The retarget writes one key per pose frame on every mapped bone. That is faithfu
   - A scaled bone's `scalex` track is thinned within 5e-5 of its setup length: half of the scale landing check's 1e-4, so a reduced curve cannot fail that check.
   - A mapped bone under a scaled bone (keyed through its parent's posed matrix by `--leg-scale`) is solved again through its parent as reduced. Its rotate is then thinned with the error read as the world aim it lands on, and its `scalex` with the error read as the world length it lands on. Its world error is its own fit error, as down any other chain.
   - Each ankle is held to the plant's tolerance plus the most the reduction may move it: the hip's tolerance (with `--reduce-hip`), plus the leg from the hip to the ankle (each bone's setup offset from its parent and the last bone's length) times the largest scale asked, times the angle tolerance in radians plus 5e-5. The ankle's `LAND` line prints that tolerance, and at the end of the run `REDUCE ankle drift allowed: bone "…:tip" X units = Y leg lengths on any one frame` prints the same figure, split `(plant … + reduce …)` (`reduce.ankleDrift` in the report, `{ bone, side, plant, reduce, units, legLengths }`, the row's `units` the landing's `tolerance` itself), with the slide between two frames it lets through (2X) — so a slide bar is read against the reduction before it is run, not after ([#240](https://github.com/rig-c/pose/issues/240)). On the wave with `--leg-scale 0.8,1.05 --plant-feet --reduce 0.5 --reduce-hip 0.5`, that is 1.97 units = 0.0132 leg lengths a frame, 0.0263 between two.
+  - **`--reduce-keep-planted`** (only with `--reduce` and `--plant-feet`, refused by name otherwise; [#251](https://github.com/rig-c/pose/issues/251)) adds every frame of each support span to the frames kept regardless, on every mapped bone from the hip down to that side's ankle (rotate, and `scalex` where scaled). A kept frame is keyed at its target, so on its support frames the planted ankle lands as dense but for the hip: its `LAND` line there is `ankle on its support frames (kept dense)`, held to the plant's tolerance plus `--reduce-hip`'s (0 without it), and off them `ankle off its support frames`, held to the allowance above. `reduce.ankleDrift[].support` carries the tighter figure (`{ reduce, units, legLengths }`, `reduce` being the hip's share; `null` for a side that never supports). The tolerance has no separate rounding term: on the tests' synthetic walk (72 frames, six support spans) the supporting ankle on its support frames sits 1.22e-3 units from the dense run's, against the plant's 0.0253. Measured on that walk with `--reduce 1`, the FEET slide (the worst horizontal drift of a supporting ankle over a support span) goes from 0.0226 leg lengths to 0.00002, the dense run's; with `--reduce-hip 0.5` beside it, 0.0048, since the hip is not kept. The price is the keys: the supporting leg keeps one per support frame (the walk's four leg rotate tracks, 47 → 135 keys).
   - When `--leg-scale` is active, each trunk bone (`chest` and `head`, not an ancestor of any scaled bone) has its kept knots and Bézier handles smoothed within `deg` of its dense world aim to minimise the mean absolute second difference of its evaluated local angle and its child's compensated local angle, holding any limb children within 0.03° of their fitted world aim (rig-c/pose#116).
 
 Exit codes: `0` written, `1` refused (every reason printed, nothing written), `2` bad invocation. `rig-pose --help` has every flag.
@@ -517,10 +522,15 @@ The answer, since 0.2, is a second drawing of the arm for each of those poses, s
 
 ## What it does not do
 
+What 1.0 leaves out ([#217](https://github.com/rig-c/pose/issues/217)). Where an open issue carries the work, it is named; where none does, the line says what to do instead.
+
 - **Extract poses from video.** The input is joint positions. How you get them is up to you: a pose model, a dataset, or by hand.
-- **Turn the body.** It works in 2D only. A segment pointing at the camera foreshortens, and the rig cannot: the direction is matched, the length is not. With `--leg-scale`, leg segments are the exception.
-- **Read a moving camera.** A reference whose camera zooms or pans moves the planted floor with it under `--plant-feet` ([#52](https://github.com/rig-c/pose/issues/52)).
-- **Front and behind, blinks, mouth shapes.** The detector's scores and face points do not carry them ([#33](https://github.com/rig-c/pose/issues/33), [#46](https://github.com/rig-c/pose/issues/46)).
+- **Turn the body.** It works in 2D only. A segment pointing at the camera foreshortens, and the rig cannot: the direction is matched, the length is not. With `--leg-scale`, the leg segments and the trunk ([#172](https://github.com/rig-c/pose/issues/172)) are the exception. A body turned past what a stretch can show is drawn by switching to a set the map declares (`body.sets`, [#173](https://github.com/rig-c/pose/issues/173)), not by turning.
+- **Front and behind, per segment.** Which limb passes in front of which is not read. The keys carry no front/back slot order ([#33](https://github.com/rig-c/pose/issues/33)).
+- **Blinks and mouth shapes.** No eyelid or mouth key is written. The face points read the head's yaw and pitch (`face` in [the map](#the-map-rig-pose-map1)) and nothing more. No issue carries this.
+- **Fit cloth physics to the reference.** A skirt's physics is the rig's own. It is not fitted to how the cloth moved in the video ([#34](https://github.com/rig-c/pose/issues/34)).
+- **Clean detector errors by limb length.** `clean` reads spikes, occlusion and jitter. It does not find a joint the detector placed wrong from the limb lengths around it ([#75](https://github.com/rig-c/pose/issues/75)).
+- **Track the camera from the video.** A zoom or a pan is read from the sequence's `camera` ([above](#the-pose-rig-pose-sequence1)). Fitting it from pixels is the repository's `tools/` scripts, which are not shipped. Without a `camera`, the picture is read as a fixed camera.
 - **Hands and fingers.** There are no bones for them yet (rig-c/parts#171).
 
 ## Licence

package/cli.ts

@@ -170,6 +170,10 @@ retarget
                         at the end as "ankle drift allowed" in units and leg lengths (rig-c/pose#240)
   --reduce-hip <units>  with --reduce, thin the hip's translate keys too, its world origin within units
                         of the dense keys (default: the hip stays dense)
+  --reduce-keep-planted with --reduce and --plant-feet, keep every frame of each support span on the
+                        supporting leg (each mapped bone from the hip down to its ankle) at its dense key, so the
+                        planted ankle lands as dense on its support frames: its landing tolerance there is the
+                        plant's plus the hip's --reduce-hip, off them --reduce's allowance (rig-c/pose#251)
   --switch-tolerance <d>  a set of alternate drawings (the map's "alternates") may show on a frame where
                         every segment of its chains is within d degrees of its key skeleton (default: 25)
   --switch-min <s>      a run of one set shorter than s seconds is dropped (default: 0.25)
@@ -180,7 +184,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 +324,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', 'reduce-keep-planted', '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 +361,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'),
@@ -378,14 +388,19 @@ function floorOf(f: Map<string, string>): { floor?: number } {
   return { floor: v };
 }
 
-/** --reduce and --reduce-hip (rig-c/pose#32): off unless given; the hip only with the bones. */
-function reduceOf(f: Map<string, string>): { reduce?: number; reduceHip?: number } {
+/** --reduce and --reduce-hip (rig-c/pose#32): off unless given; the hip only with the bones. --reduce-keep-planted (rig-c/pose#251): only with both --reduce and --plant-feet. */
+function reduceOf(f: Map<string, string>): { reduce?: number; reduceHip?: number; reduceKeepPlanted?: true } {
+  if (f.has('reduce-keep-planted')) {
+    const missing = ['reduce', 'plant-feet'].filter((x) => !f.has(x));
+    if (missing.length > 0) throw new Usage(`--reduce-keep-planted is given without ${missing.map((x) => `--${x}`).join(' and ')}; it keeps the support spans --plant-feet reads at dense keys inside the reduction --reduce makes`);
+  }
   if (!f.has('reduce')) {
     if (f.has('reduce-hip')) throw new Usage('--reduce-hip is given without --reduce; the hip is thinned with the bones, not alone');
     return {};
   }
   const reduce = num(f, 'reduce', 0, (n) => n > 0 && n < 180, 'degrees in (0, 180)');
-  return f.has('reduce-hip') ? { reduce, reduceHip: num(f, 'reduce-hip', 0, (n) => n > 0, 'rig units > 0') } : { reduce };
+  const keep = f.has('reduce-keep-planted') ? { reduceKeepPlanted: true as const } : {};
+  return f.has('reduce-hip') ? { reduce, reduceHip: num(f, 'reduce-hip', 0, (n) => n > 0, 'rig units > 0'), ...keep } : { reduce, ...keep };
 }
 
 function compareArgs(argv: string[]): CompareArgs {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.32.0",
+  "version": "0.34.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). */
@@ -55,6 +58,8 @@ export interface RetargetArgs extends RetargetOptions {
   reduce?: number;
   /** With reduce: thin the hip's translate keys within this many rig units. */
   reduceHip?: number;
+  /** With reduce and plantFeet: keep each support span's frames on the supporting leg at its dense keys (#251). */
+  reduceKeepPlanted?: boolean;
   /**
    * What stdout carries (rig-c/pose#238). `default`: the CLEAN line's hold record
    * as a count and each hinge's wrong-way frames as one line; `verbose`: every
@@ -112,6 +117,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);
@@ -151,8 +161,11 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         }
       }
     }
-    tell(`rig-pose retarget: ${seq.frames.length} frame(s), ${r.animation.duration.toFixed(3)}s, onto "${input.name}" as "${a.name}" — ${r.animation.tracks.length} track(s); min-score ${a.minScore}, flip ${a.flip === 'off' ? 'off' : `${a.flip}°`}, short ${a.short}, bends ${a.bends} (tolerance ${a.bendTolerance}°)${a.legScale !== undefined && a.legScale !== 'off' ? `, leg-scale ${a.legScale[0]}–${a.legScale[1]}` : ''}${a.plantFeet === true ? ', plant-feet' : ''}${a.stance !== undefined && a.stance !== 'off' ? `, stance ${a.stance}` : ''}${a.raisedByHead === true ? ', raised-by-head' : ''}${a.carryIdle === true ? ', carry-idle' : ''}${a.merge !== undefined ? `, merge ${a.merge}` : ''}${a.reduce !== undefined ? `, reduce ${a.reduce}°${a.reduceHip !== undefined ? ` (hip ${a.reduceHip} units)` : ''}` : ''}`);
+    tell(`rig-pose retarget: ${seq.frames.length} frame(s), ${r.animation.duration.toFixed(3)}s, onto "${input.name}" as "${a.name}" — ${r.animation.tracks.length} track(s); min-score ${a.minScore}, flip ${a.flip === 'off' ? 'off' : `${a.flip}°`}, short ${a.short}, bends ${a.bends} (tolerance ${a.bendTolerance}°)${a.legScale !== undefined && a.legScale !== 'off' ? `, leg-scale ${a.legScale[0]}–${a.legScale[1]}` : ''}${a.plantFeet === true ? ', plant-feet' : ''}${a.stance !== undefined && a.stance !== 'off' ? `, stance ${a.stance}` : ''}${a.raisedByHead === true ? ', raised-by-head' : ''}${a.carryIdle === true ? ', carry-idle' : ''}${a.merge !== undefined ? `, merge ${a.merge}` : ''}${a.reduce !== undefined ? `, reduce ${a.reduce}°${a.reduceHip !== undefined ? ` (hip ${a.reduceHip} units)` : ''}${a.reduceKeepPlanted === true ? ', planted legs kept dense' : ''}` : ''}`);
     say(`  RIGC   rig-c ${rigc.version} (${rigc.entry}) gates and poses this run`);
+    // #250: the gate was green without it, so nothing else would say the rig's own animations are not in --out.
+    const unread = unreadMotionLine(a.rig, input.motion);
+    if (unread !== null) tell(`  MOTION ${unread}`);
     say(`  CLEAN  ${output === 'verbose' ? cleanLine(seq.cleaned!) : cleanSummaryLine(seq.cleaned!)}`);
     if (a.smoothAlias !== undefined) say(`  SMOOTH --smooth is carried by clean; ignored (given ${a.smoothAlias}; this sequence was cleaned with legs ${seq.cleaned!.params.legs}, rest ${seq.cleaned!.params.rest})`);
     if (seq.camera !== undefined) say(`  CAMERA ${cameraLine(seq.camera, times, seq.cameraSource)}`);
@@ -214,7 +227,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     if (r.body !== null) say(`  BODY   ${bodyLine(r.body)}`);
 
     // --reduce (#32): the dense keys thinned top-down, before anything reads the tracks.
-    const reduced = a.reduce === undefined ? null : reduceTracks(r, map, rest, a.reduce, a.reduceHip);
+    const reduced = a.reduce === undefined ? null : reduceTracks(r, map, rest, a.reduce, a.reduceHip, a.reduceKeepPlanted === true);
     if (reduced !== null) {
       for (const row of reduced.rows) {
         const [who, track, what, unit] = row.kind === 'angle' ? ['bone', 'rotate', 'aim', '°'] : row.kind === 'origin' ? ['hip', 'translate', 'origin', ' units'] : ['bone', 'scalex', 'scale', ' of its setup length'];
@@ -286,17 +299,25 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     // reduced bones above it may move it by (#94, `footReduce`). A scale keeps its own: it is reduced within half of it.
     // #240: each ankle's allowance is computed once, here, and both the LAND tolerance and the drift line read it.
     const drift: AnkleDrift[] = [];
-    const landings = measureLanding(doc, a.name, map, r, posed).map((l) => {
+    // #251: with --reduce-keep-planted, each ankle is held apart on its support frames, which were kept dense.
+    const support = a.reduce !== undefined && a.reduceKeepPlanted === true && r.feet !== null ? supportFrames(r.feet.supports) : undefined;
+    const landings = measureLanding(doc, a.name, map, r, posed, support).map((l) => {
       if (a.reduce === undefined) return l;
       if (l.kind === 'angle') return { ...l, tolerance: l.tolerance + a.reduce };
       if (l.kind === 'origin' && a.reduceHip !== undefined) return { ...l, tolerance: l.tolerance + a.reduceHip };
       if (l.kind !== 'foot') return l;
       const ankle = l.bone.replace(/:tip$/, '');
       const by = footReduce(rest, r, ankle, a.reduce, a.reduceHip);
-      const lb = legBonesOf(map);
-      const side = lb?.r.ankle === ankle ? 'r' : lb?.l.ankle === ankle ? 'l' : null;
-      drift.push({ bone: l.bone, side, plant: l.tolerance, reduce: by, units: l.tolerance + by, legLengths: side === null || r.rigLeg === null ? null : (l.tolerance + by) / r.rigLeg[side] });
-      return { ...l, tolerance: l.tolerance + by };
+      // #251: on its support frames every mapped bone from the hip down was kept at its target, so only the hip's tolerance moves it.
+      const hip = a.reduceHip ?? 0;
+      if (!drift.some((d) => d.bone === l.bone)) {
+        const lb = legBonesOf(map);
+        const side = lb?.r.ankle === ankle ? 'r' : lb?.l.ankle === ankle ? 'l' : null;
+        const legs = (u: number) => (side === null || r.rigLeg === null ? null : u / r.rigLeg[side]);
+        const held = support === undefined ? {} : { support: side === null || support[side].size === 0 ? null : { reduce: hip, units: l.tolerance + hip, legLengths: legs(l.tolerance + hip) } };
+        drift.push({ bone: l.bone, side, plant: l.tolerance, reduce: by, units: l.tolerance + by, legLengths: legs(l.tolerance + by), ...held });
+      }
+      return { ...l, tolerance: l.tolerance + (l.on === 'support' ? hip : by) };
     });
     const p = new Problems();
     // A carried idle track on a bone above a mapped one moves it where the keys did not ask (the key formula holds unmapped bones at setup).
@@ -311,10 +332,11 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     };
     for (const l of landings) {
       const unit = l.kind === 'angle' ? '°' : l.kind === 'scale' ? ' of its setup length' : ' units';
-      const what = l.kind === 'angle' ? 'aim' : l.kind === 'scale' ? 'scale' : l.kind === 'foot' ? 'ankle' : 'origin';
+      const what = l.kind === 'angle' ? 'aim' : l.kind === 'scale' ? 'scale' : l.kind === 'foot' ? (l.on === 'support' ? 'ankle on its support frames (kept dense)' : l.on === 'off-support' ? 'ankle off its support frames' : 'ankle') : 'origin';
       const tol = l.kind === 'foot' ? Number(l.tolerance.toPrecision(3)) : l.tolerance;
       const line = `bone "${l.bone}" ${what} — worst |reached − asked| ${l.worst.toPrecision(3)}${unit} at frame ${l.frame} (t=${r.times[l.frame]!.toFixed(3)}s); the tolerance is ${tol}${unit}`;
       if (landed(l)) say(`  LAND   ${line}`);
+      else if (l.on === 'support') p.add('POSE_LANDS', `${line} — --reduce-keep-planted holds every mapped bone from the hip down at its dense key on its side's support frames, so only the hip's --reduce-hip may move it; a frame missed here was not kept${carriedAbove(l.bone)}`);
       else p.add('POSE_LANDS', `${line} — the rig does not turn the way the key formula assumes (a constraint, a scaled or sheared parent, a non-normal inherit mode)${carriedAbove(l.bone)}`);
     }
     p.throwIfAny();
@@ -347,6 +369,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)}`);
 
@@ -359,7 +385,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         frames: seq.frames.length,
         duration: r.animation.duration,
         cleaned: seq.cleaned,
-        options: { minScore: a.minScore, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, switchAt: a.switchAt, profile: a.profile, legScale: a.legScale ?? 'off', plantFeet: a.plantFeet === true, stance: a.stance ?? 'off', floor: a.floor ?? null, raisedByHead: a.raisedByHead === true, idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null, reduce: a.reduce ?? 'off', reduceHip: a.reduceHip ?? 'off' },
+        options: { minScore: a.minScore, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, switchAt: a.switchAt, profile: a.profile, legScale: a.legScale ?? 'off', plantFeet: a.plantFeet === true, stance: a.stance ?? 'off', floor: a.floor ?? null, raisedByHead: a.raisedByHead === true, idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null, reduce: a.reduce ?? 'off', reduceHip: a.reduceHip ?? 'off', ...(a.reduceKeepPlanted === true ? { reduceKeepPlanted: true } : {}) },
         scale: r.scale,
         scaleFit: r.scaleFit,
         holds: r.holds,
@@ -372,6 +398,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 +439,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 });
@@ -556,6 +584,11 @@ const spanText = (x: [number, number]) => (x[0] === x[1] ? `${x[0]}` : `${x[0]}
  * chains it changes, and the edges of every FLIP spread, SHORT span and RANGE
  * run on it (the first and last frame the reducer keeps).
  *
+ * With `keepPlanted` (#251): every frame of each support span, on every mapped
+ * bone from the hip down to that side's ankle — kept frames are keyed at their
+ * target, so the planted ankle lands as dense there, but for the hip's own
+ * tolerance.
+ *
  * With scaled bones (`--leg-scale`, the stretches; #94): a scaled bone's
  * `scalex` is thinned within `SCALE_REDUCE`, and a mapped bone under a scaled
  * bone — keyed through its parent's posed matrix (legs.ts) — is re-solved
@@ -563,7 +596,7 @@ const spanText = (x: [number, number]) => (x[0] === x[1] ? `${x[0]}` : `${x[0]}
  * aim and length it lands on (`reduceUnderScale`). With none, this is #32's
  * reduction, unchanged.
  */
-function reduceTracks(r: ReturnType<typeof retarget>, map: JointMap, rest: Rest, tolerance: number, hipTolerance: number | undefined): Reduced {
+function reduceTracks(r: ReturnType<typeof retarget>, map: JointMap, rest: Rest, tolerance: number, hipTolerance: number | undefined, keepPlanted: boolean): Reduced {
   const n = r.times.length;
   const keep = new Map<string, Set<number>>();
   const add = (bone: string, ...frames: number[]) => {
@@ -576,6 +609,15 @@ function reduceTracks(r: ReturnType<typeof retarget>, map: JointMap, rest: Rest,
   }
   for (const x of [...r.flips, ...r.short, ...r.range]) add(x.bone, x.frames[0], x.frames[1]);
   const mapped = new Set(r.targets.keys());
+  if (keepPlanted && r.feet !== null && r.ankles !== null) {
+    for (const s of r.feet.supports) {
+      const frames = Array.from({ length: s.frames[1] - s.frames[0] + 1 }, (_, k) => s.frames[0] + k);
+      for (let b: string | null = r.ankles.bones[s.side]; b !== null; b = rest.get(b)!.parent) {
+        if (mapped.has(b)) add(b, ...frames);
+        if (b === r.origin?.bone) break;
+      }
+    }
+  }
   const above = (b: string): string | null => {
     for (let p = rest.get(b)!.parent; p !== null; p = rest.get(p)!.parent) if (mapped.has(p)) return p;
     return null;
@@ -1016,6 +1058,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`;
@@ -1042,6 +1131,17 @@ export function unreadMotionHint(rigArg: string, motion: string | null): string
   return `; ${beside} is beside it and was not read — --rig naming the rig.json reads no motion spec: pass --rig ${dirname(rigArg)} (the directory, which reads the motion.json beside its rig.json) or --base-motion ${beside}`;
 }
 
+/**
+ * rig-c/pose#250: the same reading when the base gate is green — the run goes on, and --out would carry
+ * none of the rig's own animations without a word. One line, whatever the gate said; null when nothing was left unread.
+ */
+export function unreadMotionLine(rigArg: string, motion: string | null): string | null {
+  if (motion !== null) return null;
+  const beside = join(dirname(rigArg), 'motion.json');
+  if (!existsSync(beside) || statSync(rigArg).isDirectory()) return null;
+  return `${beside} is beside ${rigArg} and was not read — --rig naming the rig.json reads no motion spec, so --out carries none of the rig's own animations: pass --rig ${dirname(rigArg)} (the directory, which reads the motion.json beside its rig.json) or --base-motion ${beside}`;
+}
+
 /** The SCALE line's own clause (rig-c/pose#240): the median it divides by, against the segment at its longest. */
 export function segmentClause(f: ScaleFit): string {
   const sg = f.segment;
@@ -1102,10 +1202,28 @@ export interface AnkleDrift {
   units: number;
   /** `units` in that side's rig leg at setup (thigh origin → ankle); null without both legs. */
   legLengths: number | null;
+  /**
+   * With --reduce-keep-planted (#251): the allowance on the frames its side supports, kept dense —
+   * the plant's plus the hip's --reduce-hip (`reduce`, 0 without it); null when its side never supports.
+   * Absent without the flag.
+   */
+  support?: { reduce: number; units: number; legLengths: number | null } | null;
+}
+
+/** #251: each side's support frames, from the spans --plant-feet read. */
+function supportFrames(supports: ReadonlyArray<{ side: 'r' | 'l'; frames: [number, number] }>): Record<'r' | 'l', Set<number>> {
+  const out = { r: new Set<number>(), l: new Set<number>() };
+  for (const s of supports) for (let i = s.frames[0]; i <= s.frames[1]; i++) out[s.side].add(i);
+  return out;
 }
 
 /** The drift line: the allowance on one frame, and what it lets a planted ankle slide between two. */
 export function ankleDriftLine(d: AnkleDrift): string {
   const legs = (v: number) => (d.legLengths === null ? '' : ` = ${(d.legLengths * v / d.units).toPrecision(3)} leg lengths`);
-  return `ankle drift allowed: bone "${d.bone}" ${d.units.toPrecision(3)} units${legs(d.units)} on any one frame (plant ${d.plant.toPrecision(3)} + reduce ${d.reduce.toPrecision(3)}); between two frames up to ${(2 * d.units).toPrecision(3)} units${legs(2 * d.units)} — a tighter slide bar needs a smaller --reduce`;
+  const line = `ankle drift allowed: bone "${d.bone}" ${d.units.toPrecision(3)} units${legs(d.units)} on any one frame (plant ${d.plant.toPrecision(3)} + reduce ${d.reduce.toPrecision(3)}); between two frames up to ${(2 * d.units).toPrecision(3)} units${legs(2 * d.units)}`;
+  if (d.support === undefined) return `${line} — a tighter slide bar needs a smaller --reduce`;
+  if (d.support === null) return `${line}; its side never supports, so --reduce-keep-planted keeps no frame of it`;
+  const s = d.support;
+  const sLegs = (v: number) => (s.legLengths === null ? '' : ` = ${(s.legLengths * v / s.units).toPrecision(3)} leg lengths`);
+  return `${line} off its support frames; on them, kept dense (--reduce-keep-planted), ${s.units.toPrecision(3)} units${sLegs(s.units)} (plant ${d.plant.toPrecision(3)} + hip ${s.reduce.toPrecision(3)}), between two frames of a support span up to ${(2 * s.units).toPrecision(3)} units${sLegs(2 * s.units)}`;
 }

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;
+}

package/src/verify.ts

@@ -26,6 +26,11 @@ export interface Landing {
   kind: 'angle' | 'origin' | 'scale' | 'foot';
   /** The tolerance it is held to. */
   tolerance: number;
+  /**
+   * A `foot` split by `--reduce-keep-planted` (#251): `support`, the frames its side supports
+   * (each support span kept dense); `off-support`, the rest. Absent: every frame, one row.
+   */
+  on?: 'support' | 'off-support';
 }
 
 /**
@@ -60,7 +65,7 @@ export function poseFrames(doc: CompiledDocument, animation: string, times: read
   return poses.map((p) => new Map(p.bones.map((b) => [b.name, b])));
 }
 
-export function measureLanding(doc: CompiledDocument, animation: string, map: JointMap, r: Retarget, posed = poseFrames(doc, animation, r.times)): Landing[] {
+export function measureLanding(doc: CompiledDocument, animation: string, map: JointMap, r: Retarget, posed = poseFrames(doc, animation, r.times), support?: Record<'r' | 'l', ReadonlySet<number>>): Landing[] {
   const out: Landing[] = [];
   const lengths = new Map(doc.bones.map((b) => [b.name, b.length ?? 0]));
   const faceBones = new Set([r.face?.yaw?.bone, r.face?.pitch?.bone].filter((b): b is string => b !== undefined));
@@ -163,18 +168,23 @@ export function measureLanding(doc: CompiledDocument, animation: string, map: Jo
       const tip0: [number, number] = [s0.worldX + s0.a * (lengths.get(bone) ?? 0), s0.worldY + s0.c * (lengths.get(bone) ?? 0)];
       const h0 = top === undefined ? null : setup.get(top)!;
       const lever = h0 === null ? Math.hypot(tip0[0], tip0[1]) : Math.hypot(tip0[0] - h0.worldX, tip0[1] - h0.worldY);
-      let worst = -1;
-      let frame = 0;
+      const tolerance = ORIGIN_TOLERANCE + FOOT_TOLERANCE_PER_UNIT * lever;
+      const rows = support === undefined ? [{ on: undefined, worst: -1, frame: 0, n: 0 }] : (['support', 'off-support'] as const).map((on) => ({ on, worst: -1, frame: 0, n: 0 }));
       posed.forEach((bones, i) => {
         const got = pointAt(bones, lengths, `${bone}:tip`)!;
         const want = r.ankles!.at[side][i]!;
         const e = Math.hypot(got[0] - want[0], got[1] - want[1]);
-        if (e > worst) {
-          worst = e;
-          frame = i;
+        const row = support === undefined ? rows[0]! : rows[support[side].has(i) ? 0 : 1]!;
+        row.n++;
+        if (e > row.worst) {
+          row.worst = e;
+          row.frame = i;
         }
       });
-      out.push({ bone: `${bone}:tip`, worst, frame, kind: 'foot', tolerance: ORIGIN_TOLERANCE + FOOT_TOLERANCE_PER_UNIT * lever });
+      for (const x of rows) {
+        if (x.n === 0) continue;
+        out.push({ bone: `${bone}:tip`, worst: x.worst, frame: x.frame, kind: 'foot', tolerance, ...(x.on === undefined ? {} : { on: x.on }) });
+      }
     }
   }
   return out;