@rig-c/pose 0.9.0 → 0.10.0

package/README.md

@@ -54,9 +54,10 @@ and what the run cannot decide for you it lists:
 - `PIVOT` — when the map translates a bone and has both legs: the translated bone's origin against its thigh roots' midpoint at setup, in units and hip widths — the pivot every hip turn swings the legs about.
 - `FEET` — when the map has both legs: the supports and jumps read off the reference ankles (planted or not), and on the posed build, outside the jumps, the lowest ankle's vertical range and each support span's worst vertical range and horizontal drift of the supporting ankle, in leg lengths.
 - `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.
+- `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)).
 - `TURN` — a line across the body (hips, shoulders, eyes) shorter in the picture than 0.5 of its median length, or reversed, for at least 0.15 s: the body or the head turned. A reading of the pose, made whether or not the map uses the line; it changes no key. The demand for a turned-body drawing, as `END-ON` is for a foreshortened limb.
 
-`--report <file>` writes all of it as JSON (`rig-pose-report/1`): `options` (every figure the run used, `switchTolerance`, `switchMin`, `switchAt`, `legScale` and `plantFeet` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate`, `landings`, `posture`, `folds`, `legScale`, `pivot`, `feet` (`planted`, `legLength`, `floor`, `supports`, `jumps`, `changes`, and the posed `reading`), `shear`, and the demand lists:
+`--report <file>` writes all of it as JSON (`rig-pose-report/1`): `options` (every figure the run used, `switchTolerance`, `switchMin`, `switchAt`, `legScale` and `plantFeet` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate`, `landings`, `posture`, `folds`, `legScale`, `pivot`, `feet` (`planted`, `legLength`, `floor`, `supports`, `jumps`, `changes`, and the posed `reading`), `shear`, `idleDropped`, `idleKeptOut` and `merged` ([below](#the-idle-what-the-retarget-drops)), and the demand lists:
 
 - `switches: [{ set, chains, slots, hides, offsets, from, to, frames: [first, last], distance: { max, median }, artTurn: { <bone>: { max, median } }, moved: { on, off } }]` — one per span shown; `from` is the first frame's time, `to` the time the base art comes back (the animation's end when the span runs to it), `distance` in degrees over the frames shown, `artTurn` |wrap(target − drawn)| in degrees per bone the set has a `drawn` angle for. `moved.on` is the boundary the span starts on (null from the first frame), `moved.off` the one the base art or the next set comes back on (null to the end), each `{ frame: [selected, keyed], frames, seconds, window: [first, last], speed: { old, new } }`: signed frames and seconds, the frames it could move to, and the speed in degrees per frame on the old and the new frame. A boundary between two sets is the same entry in both.
 - `uncovered: [{ slot, attachment, chains, times }]` — every entry of `folds` on the times its slot still shows that mesh, with the map's chains that move it (the deepest: the arm, not the trunk it hangs from). `rigc render --folds` reads only what the pose shows, so a mesh swapped out or hidden by a switch is not read on those frames at all; `uncovered` is the fold times less the switched ones.
@@ -109,6 +110,31 @@ rig-c's `scalex` multiplies the bone's x axis, and a child with the `normal` inh
 
 Both are checked on the gated build: every scale lands, each ankle lands where the keys put it, and the hip's origin where the plant put it. The figures were fixed in #47 before the dancer was measured; the defaults stay off until they pass.
 
+### The idle: what the retarget drops
+
+A rig's motion spec usually has an `idle` — a blink, a breath, hair and hem sway — and the new animation keys none of it ([#43](https://github.com/rig-c/pose/issues/43), item 2). The run reads that animation (`--idle <name>` names another; naming one the spec lacks is `IDLE_NAME`) track by track against the new one, channel by channel — `translate` poses `translatex` and `translatey`, a `group` track poses each of its members, a slot's `rgba` its `rgb` and `alpha`:
+
+- `IDLE-DROPPED` — a track the new animation keys on none of its channels, and that turns no mapped bone (below): its target, property, keys and the idle's duration. The report lists them under `idleDropped` (`target`, `members`, `property`, `keys`, `duration`, `carried`, `notCarried`).
+- `IDLE-KEPT-OUT` — never carried (`idleKeptOut`), with the reason: a track the new animation keys itself, naming the track that keys it; or a `rotate`, `scale` or `shear` (any axis) of a bone **above** a mapped bone — between mapped bones, or above the first one (the map's chains and its translated bone) — naming the mapped bones below it: the retarget's keys hold every unmapped bone at its setup pose, so such a track would turn them off the angles the pose asks. A `translate` of such a bone is carried: it moves the bones under it and turns none. The exception is a translate of a bone above the **translated** bone (the hip), which is kept out because the retarget places that bone's origin. (Folding a carried parent's motion into the mapped bones' keys is a later card.) The idle's `drawOrder`, `events`, `ik`, `transform`, `deform` and `sequence` timelines are not tracks, and are listed here too.
+
+**`--carry-idle`** (off by default: a blink keyed over a set's art may not suit it, and that is the author's call) loops every dropped track into the new animation: the idle's keys repeated every idle duration and cut at the new animation's end, with the value interpolated there.
+
+- A key's `ease` or `curve` describes the segment to the next key, so a loop is built key by key. Where the idle's last key is at its duration and its first at 0, the two are one key at each seam (the next cycle's first; if their values differ, the line says where the loop jumps, as a player looping the idle does). Where the last key is earlier, it is keyed `stepped`, so it holds to the cycle's end as it does in the idle. Where the first key is later than 0, each later cycle opens with a stepped setup key: 0 for a bone's translate, shear and rotate, 1 for its scale, the slot's setup attachment; for any other property such a track is not carried, and the line says why.
+- A raw `curve` states absolute times, so a repeated one is shifted with its key. The segment the cut falls in is split there: linear and stepped as they are, a Bézier (a raw `curve`, or a named easing turned into one as rigc does) by de Casteljau, so the part kept is the same cubic and the last key carries neither ease nor curve. rig-c draws a Bézier as Spine's polyline, so a split segment and the idle's whole one sit off the cubic, and off each other, by that alone (measured on the test's eased segment: the idle's own up to 2.6e-3, the carried part up to 9.3e-4).
+- A track with `lag` or `stagger`, or whose values are per-member maps or models, is not carried, and the line says so.
+
+Every bone still has to land with the carried tracks in. A carried translate above the translated bone moves its origin off the pose's travel, and the run refuses with `POSE_LANDS`, naming the carried tracks above the bone that missed.
+
+On HQ's dancer (`--flip 90 --short 0.35 --bends clamp --carry-idle`) the idle has 26 tracks. Kept out: the four arm rotates, which the dance keys, and `chest_ctl` scalex, `neck` rotate and `head_ctl` rotate, which sit above the mapped chest, head and arms — carried, they missed the chest, the head and the arms by 0.16°–1.37°. Carried: the other 19, the blink (`group "eyes"` scaley) and the breath (`bone "chest_ctl"` translatey) among them. The gate is green, every bone lands (worst 0.00167°), and rig-c's poser shows the blink at every cycle (scaleY 0.12 at 2.37 s, 5.70 s, 9.08 s and 12.41 s, against the idle's at t mod 3.333 s within 8.9e-6) and the breath's chest_ctl offset (5.02 at 0.833, 4.167, 7.5, 10.833 s; 0 at 2.5, 5.833, 9.167, 12.5 s; 1.035 at the cut, 13 s).
+
+**`--merge <file>`** merges a timed track fragment into the new animation, at absolute times from its start — blinks read off the video, for example:
+
+```json
+{ "spec": "rig-pose-tracks/1", "tracks": [ { "group": "eyes", "property": "scaley", "keys": [ { "t": 2.3, "v": [1] }, { "t": 2.37, "v": [0.12] }, { "t": 2.45, "v": [1] } ] } ] }
+```
+
+Each track is a rigc-motion track. One posing a channel the new animation (or a carried idle track, or an earlier fragment track) already keys is refused by name (`MERGE_CONFLICT`): a fragment adds a track, it never replaces one. So is a key before 0 or past the animation's duration (`MERGE_TIME`), and a file of any other shape (`MERGE_SPEC`). What the track means — its target, property and values — is rigc's to judge: its gate checks every merged track like any other (`RIG_GATE`). `MERGE` lists each track merged; the report lists them under `merged`.
+
 Exit codes: `0` written, `1` refused (every reason printed, nothing written), `2` bad invocation. `rig-pose --help` has every flag.
 
 ## The pose: `rig-pose-sequence/1`

package/cli.ts

@@ -64,6 +64,17 @@ retarget
                         travel and re-plants on landing; a supporting ankle moving > 0.03 leg lengths a frame
                         releases its plant to the other foot, or to the pose's travel, until it is still
                         (< 0.01 for 2 frames) (FEET lines)
+  --idle <name>         the rig's animation read as its idle (default: idle). Every idle track the new
+                        animation does not key, on any channel, is listed as IDLE-DROPPED (a blink, a
+                        breath); one it keys is IDLE-KEPT-OUT, naming the track that keys it, and so is a
+                        rotate, scale or shear of a bone above a mapped bone (a translate of one is carried)
+  --carry-idle          loop the IDLE-DROPPED tracks into the new animation: the idle's keys repeated
+                        every idle duration and cut at the new animation's end, with the value
+                        interpolated there (default: off — a blink keyed over a set's art is the author's call)
+  --merge <file>        merge rig-pose-tracks/1 into the new animation: { "spec": "rig-pose-tracks/1",
+                        "tracks": [ <rigc-motion track> … ] } at absolute times from its start (blinks read
+                        off the video); a track on a target and property it already keys is refused
+                        (MERGE_CONFLICT), and so is a key past its duration (MERGE_TIME)
   --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)
@@ -75,7 +86,8 @@ retarget
   --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,
-                        switches, uncovered, turns, range, artRange) as JSON
+                        switches, uncovered, turns, range, artRange,
+                        idleDropped, idleKeptOut, merged) as JSON
 
   It writes nothing until rigc's gate is green with the animation in, every mapped bone lands on
   the angle the pose asks for (posed by rig-c's own poser), and no hinge bends the wrong way.
@@ -179,7 +191,7 @@ function legScaleOf(f: Map<string, string>): [number, number] | 'off' {
 }
 
 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', 'leg-scale'], ['coco', 'plant-feet']);
+  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', 'leg-scale', 'idle', 'merge'], ['coco', 'plant-feet', 'carry-idle']);
   const bends = f.get('bends') ?? 'refuse';
   if (bends !== 'refuse' && bends !== 'clamp') throw new Usage(`--bends is "${bends}"; it must be refuse or clamp`);
   const switchAt = f.get('switch-at') ?? 'first';
@@ -213,6 +225,9 @@ function retargetArgs(argv: string[]): RetargetArgs {
     build: f.get('build'),
     render: f.get('render'),
     report: f.get('report'),
+    idle: f.get('idle'),
+    carryIdle: f.has('carry-idle'),
+    merge: f.get('merge'),
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.9.0",
+  "version": "0.10.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": {

package/src/idle.ts

@@ -0,0 +1,421 @@
+/**
+ * The tracks a retarget drops, and the two ways to put them back (rig-c/pose#43
+ * item 2): the rig's idle read against the new animation, its dropped tracks
+ * looped into it with `--carry-idle`, and a timed fragment merged with `--merge`.
+ *
+ * Pure: the motion spec's own track objects in, track objects out. What a
+ * merged or carried track means (its bone, its property, its values) is rig-c's
+ * to judge, and its gate judges it with the animation in.
+ *
+ * A key's `ease` or `curve` describes the segment from that key to the next
+ * (rig-c docs/AUTHORING.md §4.5), so a loop is built key by key: where one
+ * cycle meets the next, the key that ends a cycle and the one that starts the
+ * next must not share a time, and the segment into the seam must ease toward
+ * the value the loop shows there. A raw `curve` states absolute times, so a
+ * repeated one is shifted with its key. The last key of the whole track carries
+ * neither.
+ */
+import { isObject, Problems, typeName, type Problem } from './problems.ts';
+
+/** A rigc-motion track as the motion spec states it: one target field, a property, keys, and whatever else it carries. */
+export type RigcTrack = Record<string, unknown> & { property: string; keys: RigcKey[] };
+export type RigcKey = Record<string, unknown> & { t: number; v: unknown; ease?: string; curve?: number[] };
+
+/** The six target fields of a track (AUTHORING §4.4). */
+const TARGET_FIELDS = ['bone', 'slot', 'group', 'physics', 'path', 'slider'] as const;
+type TargetKind = (typeof TARGET_FIELDS)[number];
+
+/** What each bone and slot property poses, channel by channel: two tracks that share a channel key the same thing. */
+const BONE_CHANNELS: Readonly<Record<string, readonly string[]>> = {
+  translate: ['translatex', 'translatey'], translatex: ['translatex'], translatey: ['translatey'],
+  scale: ['scalex', 'scaley'], scalex: ['scalex'], scaley: ['scaley'],
+  shear: ['shearx', 'sheary'], shearx: ['shearx'], sheary: ['sheary'],
+  rotate: ['rotate'], inherit: ['inherit'],
+};
+const SLOT_CHANNELS: Readonly<Record<string, readonly string[]>> = {
+  attachment: ['attachment'], rgba: ['rgb', 'alpha'], rgb: ['rgb'], alpha: ['alpha'], rgba2: ['rgb', 'alpha', 'dark'], rgb2: ['rgb', 'dark'],
+};
+/** A bone property whose setup value, as a key states it, is known without reading the rig: translate and shear add to setup (0), scale multiplies it (1). */
+const BONE_IDENTITY: Readonly<Record<string, number>> = {
+  translate: 0, translatex: 0, translatey: 0, shear: 0, shearx: 0, sheary: 0, rotate: 0, scale: 1, scalex: 1, scaley: 1,
+};
+/** The bone properties that only move a bone: a child's angle is unchanged, so one on a bone above a mapped bone is carried. */
+const TRANSLATES = new Set(['translate', 'translatex', 'translatey']);
+/** Timelines stepped by the format: a key carries no ease and no curve, and no value lies between two keys. */
+const STEPPED_BY_NATURE = new Set(['attachment', 'inherit', 'reset']);
+
+/** A target and its name: `bone "neck"`, `group "eyes"`. */
+export interface Target {
+  kind: TargetKind;
+  name: string;
+}
+
+export function targetOf(track: Record<string, unknown>): Target | null {
+  const found = TARGET_FIELDS.filter((f) => typeof track[f] === 'string');
+  return found.length === 1 ? { kind: found[0]!, name: track[found[0]!] as string } : null;
+}
+
+/** `group "eyes" (eye_r, eye_l) scaley`, `bone "chest_ctl" translatey`. */
+export function trackLabel(track: RigcTrack, groups: Readonly<Record<string, readonly string[]>>): string {
+  const t = targetOf(track);
+  if (t === null) return `a track with no single target, property ${JSON.stringify(track.property)}`;
+  const members = t.kind === 'group' && groups[t.name] !== undefined ? ` (${groups[t.name]!.join(', ')})` : '';
+  return `${t.kind} "${t.name}"${members} ${track.property}`;
+}
+
+/**
+ * Every channel a track poses, as `family:name:channel`: a group's members are
+ * bones, slots or physics constraints by its property (AUTHORING §4.3), so a
+ * group track collides with a bone track on one of its members.
+ */
+function cellsOf(track: RigcTrack, groups: Readonly<Record<string, readonly string[]>>): string[] {
+  const t = targetOf(track);
+  if (t === null) return [];
+  const p = track.property;
+  const family = (kind: TargetKind): 'bone' | 'slot' | 'physics' | 'path' | 'slider' => {
+    if (kind !== 'group') return kind;
+    if (p in BONE_CHANNELS) return 'bone';
+    if (p in SLOT_CHANNELS) return 'slot';
+    return 'physics';
+  };
+  const fam = family(t.kind);
+  const channels = fam === 'bone' ? BONE_CHANNELS[p] ?? [p] : fam === 'slot' ? SLOT_CHANNELS[p] ?? [p] : [p];
+  const names = t.kind === 'group' ? groups[t.name] ?? [] : [t.name];
+  return names.flatMap((n) => channels.map((c) => `${fam}:${n}:${c}`));
+}
+
+/** Which channels the tracks pose, each with the label of the track posing it. */
+export function keyedBy(tracks: readonly RigcTrack[], groups: Readonly<Record<string, readonly string[]>>): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const tr of tracks) for (const c of cellsOf(tr, groups)) if (!out.has(c)) out.set(c, trackLabel(tr, groups));
+  return out;
+}
+
+/** The labels of the tracks in `keyed` that pose a channel `track` poses. */
+function collisions(track: RigcTrack, keyed: ReadonlyMap<string, string>, groups: Readonly<Record<string, readonly string[]>>): string[] {
+  return [...new Set(cellsOf(track, groups).flatMap((c) => (keyed.has(c) ? [keyed.get(c)!] : [])))];
+}
+
+export interface IdleDropped {
+  target: Target;
+  /** A group's members, as the motion spec's `groups` names them. */
+  members: string[] | null;
+  property: string;
+  /** The track's keys in the idle. */
+  keys: number;
+  /** The idle's duration, seconds. */
+  duration: number;
+  /** With --carry-idle: the looped track's keys, the cycles they span, and where a seam jumps. */
+  carried: { keys: number; cycles: number; seams: string | null } | null;
+  /** With --carry-idle: why this track was not carried. */
+  notCarried: string | null;
+}
+
+export interface IdleKeptOut {
+  target: Target;
+  property: string;
+  reason: string;
+}
+
+export interface IdleReading {
+  animation: string;
+  duration: number;
+  tracks: number;
+  dropped: IdleDropped[];
+  keptOut: IdleKeptOut[];
+  /** The idle's timelines that are not tracks (drawOrder, events, ik, transform, deform, sequence): never compared, never carried. */
+  notTracks: string[];
+  /** With --carry-idle: the looped tracks, in the idle's order. */
+  carriedTracks: RigcTrack[];
+}
+
+const NOT_TRACKS = ['drawOrder', 'events', 'ik', 'transform', 'deform', 'sequence'] as const;
+
+/**
+ * The idle against the new animation: every idle track the new one does not
+ * key on any channel is dropped (and, with `carry`, looped into it); every one
+ * it keys is kept out, naming the track that keys it.
+ */
+export function readIdle(
+  name: string,
+  /** The new animation's name. */
+  into: string,
+  idle: Record<string, unknown>,
+  newTracks: readonly RigcTrack[],
+  duration: number,
+  motion: { groups: Readonly<Record<string, readonly string[]>>; easings: Readonly<Record<string, readonly number[]>> },
+  /** The setup value a key on this target and property states (`sample` is one of its keys' values), or undefined when it is not read. */
+  setupOf: (target: Target, property: string, sample: unknown) => unknown,
+  carry: boolean,
+  /** The mapped bones (chains and the translated bone) under a bone, in map order. */
+  mappedBelow: (bone: string) => readonly string[] = () => [],
+  /** The translated bone (the hip) when it lies under this bone, else null: a translate above it moves the origin the retarget places. */
+  translatedBelow: (bone: string) => string | null = () => null,
+): IdleReading {
+  const D = idle.duration as number;
+  const tracks = (Array.isArray(idle.tracks) ? idle.tracks : []) as RigcTrack[];
+  const keyed = keyedBy(newTracks, motion.groups);
+  const dropped: IdleDropped[] = [];
+  const keptOut: IdleKeptOut[] = [];
+  const carriedTracks: RigcTrack[] = [];
+  for (const tr of tracks) {
+    const target = targetOf(tr);
+    if (target === null) continue;
+    const hit = collisions(tr, keyed, motion.groups);
+    if (hit.length > 0) {
+      keptOut.push({ target, property: tr.property, reason: `"${into}"'s own ${hit.join(', ')} keys it` });
+      continue;
+    }
+    // A rotate, scale or shear above a mapped bone turns it off the angle its keys assume (the key formula holds unmapped bones at setup).
+    const bones = target.kind === 'bone' ? [target.name] : target.kind === 'group' && tr.property in BONE_CHANNELS ? [...(motion.groups[target.name] ?? [])] : [];
+    const under = TRANSLATES.has(tr.property) ? [] : [...new Set(bones.flatMap((b) => mappedBelow(b)))];
+    const hipBelow = TRANSLATES.has(tr.property) ? bones.map((b) => translatedBelow(b)).find((h) => h !== null) ?? null : null;
+    if (hipBelow !== null) {
+      keptOut.push({ target, property: tr.property, reason: `moves the translated bone "${hipBelow}" below it; the retarget places its origin` });
+      continue;
+    }
+    if (under.length > 0) {
+      keptOut.push({ target, property: tr.property, reason: `moves mapped bone(s) ${under.map((b) => `"${b}"`).join(', ')} below it; the retarget's keys assume it at setup` });
+      continue;
+    }
+    const entry: IdleDropped = { target, members: target.kind === 'group' ? [...(motion.groups[target.name] ?? [])] : null, property: tr.property, keys: tr.keys.length, duration: D, carried: null, notCarried: null };
+    if (carry) {
+      const c = loopTrack(tr, D, duration, motion.easings, () => setupOf(target, tr.property, tr.keys[0]?.v));
+      if ('reason' in c) entry.notCarried = c.reason;
+      else {
+        entry.carried = { keys: c.track.keys.length, cycles: c.cycles, seams: c.seams };
+        carriedTracks.push(c.track);
+      }
+    }
+    dropped.push(entry);
+  }
+  const notTracks = NOT_TRACKS.filter((k) => idle[k] !== undefined);
+  return { animation: name, duration: D, tracks: tracks.length, dropped, keptOut, notTracks, carriedTracks };
+}
+
+const r6 = (v: number): number => Math.round(v * 1e6) / 1e6;
+/** Two times this close are one time (key times are written to 1e-6 s). */
+const EPS = 1e-7;
+
+const numeric = (v: unknown): v is number[] => Array.isArray(v) && v.length > 0 && v.every((x) => typeof x === 'number' && Number.isFinite(x));
+
+/**
+ * One idle track looped to `T` seconds: its keys repeated every `D` seconds and
+ * cut at `T`, with the value interpolated there.
+ *
+ * - Where the idle's last key is at `D` and its first at 0 (a closed loop), the
+ *   two are one key at each seam: the next cycle's first. A last key that
+ *   differs from the first is a jump in the idle as a player loops it (at `D`
+ *   it shows the first key), and the seam keys the first; `seams` says so.
+ * - Where the last key is before `D`, the player holds it to `D`: it is keyed
+ *   `stepped` (a timeline stepped by the format holds anyway).
+ * - Where the first key is after 0, the player shows the setup value from each
+ *   cycle's start to that key: a stepped setup key opens each later cycle. That
+ *   needs the setup value as a key states it, which this reads only for a bone's
+ *   translate, scale, shear and rotate (0, 1, 0, 0) and a slot's attachment.
+ */
+export function loopTrack(
+  track: RigcTrack,
+  D: number,
+  T: number,
+  easings: Readonly<Record<string, readonly number[]>>,
+  setup: () => unknown,
+): { track: RigcTrack; cycles: number; seams: string | null } | { reason: string } {
+  if (track.lag !== undefined || track.stagger !== undefined) return { reason: `it carries ${track.lag !== undefined ? '"lag"' : '"stagger"'}, which shifts its keys per track or per member; a loop is cut by key time, so it is not carried` };
+  const keys = track.keys;
+  if (keys.length === 0) return { reason: 'it has no keys' };
+  const nature = STEPPED_BY_NATURE.has(track.property);
+  if (!nature && !keys.every((k) => numeric(k.v))) return { reason: 'a key\'s value is not a list of numbers (a per-member map or a model), and a cut needs the value between two keys' };
+  if (!(D > 0)) return { reason: `the idle's duration is ${D}` };
+  const first = keys[0]!.t;
+  const last = keys[keys.length - 1]!.t;
+  let setupKey: unknown;
+  if (first > EPS) {
+    setupKey = setup();
+    if (setupKey === undefined) return { reason: `its first key is at t=${first}s, so a loop shows the setup value of ${track.property} before it in every cycle, and this package does not read that value for this target` };
+  }
+
+  const shift = (k: RigcKey, off: number): RigcKey => {
+    const out: RigcKey = { ...k, t: r6(off + k.t) };
+    if (Array.isArray(k.curve)) out.curve = k.curve.map((x, i) => (i % 2 === 0 ? r6(off + x) : x));
+    return out;
+  };
+  const hold = (k: RigcKey): void => {
+    if (nature) return;
+    delete k.curve;
+    k.ease = 'stepped';
+  };
+  const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
+  const out: RigcKey[] = [];
+  const jumps: number[] = [];
+  let cycles = 0;
+  for (let k = 0; k * D <= T + EPS; k++) {
+    const off = k * D;
+    if (k > 0) {
+      const prev = out[out.length - 1]!;
+      const opens: unknown = first > EPS ? setupKey : keys[0]!.v;
+      if (prev.t >= r6(off) - EPS) {
+        // The key that ends the last cycle sits on the seam: the loop shows the next cycle's start there.
+        out.pop();
+        if (!same(prev.v, opens)) jumps.push(r6(off));
+      } else hold(prev);
+      if (first > EPS) {
+        const s: RigcKey = { t: r6(off), v: setupKey };
+        if (!nature) s.ease = 'stepped';
+        out.push(s);
+      }
+    }
+    for (const key of keys) out.push(shift(key, off));
+    cycles++;
+    if (out[out.length - 1]!.t > T + EPS) break;
+  }
+
+  // The cut at T.
+  const kept = out.filter((x) => x.t <= T + EPS);
+  if (kept.length === 0) return { reason: `its first key, at t=${first}s, is past the new animation's ${T}s` };
+  for (const x of kept) if (Math.abs(x.t - T) <= EPS) x.t = T;
+  const after = out[kept.length];
+  const end = kept[kept.length - 1]!;
+  if (after !== undefined && end.t < T - EPS && !nature) {
+    const c = cutAt(end, after, T, easings);
+    if ('reason' in c) return c;
+    kept.push({ t: T, v: c.v });
+  }
+  const tail = kept[kept.length - 1]!;
+  delete tail.ease;
+  delete tail.curve;
+  const seams = jumps.length === 0 ? null : `the idle's last key (t=${last}s, ${JSON.stringify(keys[keys.length - 1]!.v)}) is not what it shows at its start (${JSON.stringify(first > EPS ? setupKey : keys[0]!.v)}); the loop keys the start at each seam, so it jumps at t=${jumps.map((t) => t.toFixed(3)).join(', ')}s`;
+  return { track: { ...track, keys: kept }, cycles, seams };
+}
+
+/**
+ * The value at `T` inside the segment from `a` to `b`, and `a`'s segment cut
+ * there: stepped holds `a`; linear interpolates; a Bézier (a raw `curve`, or a
+ * named easing turned into one as rigc turns it, AUTHORING §4.1) is split at
+ * `T` by de Casteljau, so the part kept is the same curve.
+ */
+function cutAt(a: RigcKey, b: RigcKey, T: number, easings: Readonly<Record<string, readonly number[]>>): { v: number[] } | { reason: string } {
+  const va = a.v as number[];
+  const vb = b.v as number[];
+  if (a.ease === 'stepped') return { v: [...va] };
+  let curve: number[] | null = null;
+  if (Array.isArray(a.curve)) curve = a.curve;
+  else if (typeof a.ease === 'string') {
+    const h = easings[a.ease];
+    if (h === undefined || h.length !== 4) return { reason: `its easing "${a.ease}" is not in the motion spec's easings` };
+    curve = va.flatMap((v0, c) => [a.t + (b.t - a.t) * h[0]!, v0 + (vb[c]! - v0) * h[1]!, a.t + (b.t - a.t) * h[2]!, v0 + (vb[c]! - v0) * h[3]!]);
+  }
+  if (curve === null) return { v: va.map((v0, c) => r6(v0 + ((T - a.t) / (b.t - a.t)) * (vb[c]! - v0))) };
+  const kept: number[] = [];
+  const v: number[] = [];
+  va.forEach((v0, c) => {
+    const [x1, y1, x2, y2] = curve.slice(c * 4, c * 4 + 4) as [number, number, number, number];
+    const bez = (p0: number, p1: number, p2: number, p3: number, s: number) => {
+      const u = 1 - s;
+      return u * u * u * p0 + 3 * u * u * s * p1 + 3 * u * s * s * p2 + s * s * s * p3;
+    };
+    let lo = 0;
+    let hi = 1;
+    for (let i = 0; i < 60; i++) {
+      const mid = (lo + hi) / 2;
+      if (bez(a.t, x1, x2, b.t, mid) < T) lo = mid;
+      else hi = mid;
+    }
+    const s = (lo + hi) / 2;
+    const lerp = (p: number, q: number) => p + (q - p) * s;
+    const split = (p0: number, p1: number, p2: number, p3: number): [number, number, number] => {
+      const p01 = lerp(p0, p1);
+      const p12 = lerp(p1, p2);
+      const p23 = lerp(p2, p3);
+      const p012 = lerp(p01, p12);
+      return [p01, p012, lerp(p012, lerp(p12, p23))];
+    };
+    const xs = split(a.t, x1, x2, b.t);
+    const ys = split(v0, y1, y2, vb[c]!);
+    kept.push(r6(xs[0]), r6(ys[0]), r6(xs[1]), r6(ys[1]));
+    v.push(r6(ys[2]));
+  });
+  delete a.ease;
+  a.curve = kept;
+  return { v };
+}
+
+/** The setup value a key states for a bone's translate, scale, shear and rotate (`numbers` channels), or undefined. */
+export function boneIdentity(property: string, channels: number): number[] | undefined {
+  const v = BONE_IDENTITY[property];
+  return v === undefined ? undefined : Array.from({ length: channels }, () => v);
+}
+
+// --- the fragment ------------------------------------------------------------
+
+export const FRAGMENT_SPEC = 'rig-pose-tracks/1';
+
+/**
+ * A `rig-pose-tracks/1` fragment: `{ "spec": "rig-pose-tracks/1", "tracks": [ … ] }`,
+ * each a rigc-motion track at absolute times from the animation's start. The
+ * shape is read here (one target, a property, keys with a time); what a track
+ * means is rigc's gate's to judge.
+ */
+export function readFragment(doc: unknown, where: string): RigcTrack[] {
+  const p = new Problems();
+  if (!isObject(doc) || doc.spec !== FRAGMENT_SPEC || !Array.isArray(doc.tracks)) {
+    p.add('MERGE_SPEC', `${where}: "spec" is ${isObject(doc) ? typeName(doc.spec) : typeName(doc)} and "tracks" ${isObject(doc) ? typeName(doc.tracks) : '-'}; a fragment is { "spec": "${FRAGMENT_SPEC}", "tracks": [ <rigc-motion track> … ] }`);
+    p.throwIfAny();
+  }
+  const tracks = (doc as { tracks: unknown[] }).tracks;
+  if (tracks.length === 0) p.add('MERGE_SPEC', `${where}: "tracks" is empty; a fragment adds at least one track`);
+  tracks.forEach((tr, i) => {
+    const at = `${where} tracks[${i}]`;
+    if (!isObject(tr)) {
+      p.add('MERGE_SPEC', `${at} is ${typeName(tr)}; a track is an object`);
+      return;
+    }
+    const fields = TARGET_FIELDS.filter((f) => tr[f] !== undefined);
+    if (fields.length !== 1 || typeof tr[fields[0]!] !== 'string') p.add('MERGE_SPEC', `${at} names ${fields.length === 0 ? 'no target' : fields.map((f) => `"${f}" (${typeName(tr[f])})`).join(' and ')}; a track names exactly one of ${TARGET_FIELDS.join(', ')}, as a string`);
+    if (typeof tr.property !== 'string') p.add('MERGE_SPEC', `${at} "property" is ${typeName(tr.property)}; it is the timeline's name, a string`);
+    if (!Array.isArray(tr.keys) || tr.keys.length === 0) {
+      p.add('MERGE_SPEC', `${at} "keys" is ${typeName(tr.keys)}; it is a non-empty array of { "t": <seconds>, "v": … }`);
+      return;
+    }
+    tr.keys.forEach((k, j) => {
+      if (!isObject(k) || typeof k.t !== 'number' || !Number.isFinite(k.t)) p.add('MERGE_SPEC', `${at} keys[${j}] ${isObject(k) ? `"t" is ${typeName(k.t)}` : `is ${typeName(k)}`}; a key states its time "t" in seconds`);
+    });
+  });
+  p.throwIfAny();
+  return tracks as RigcTrack[];
+}
+
+/**
+ * A fragment against the new animation: a track posing a channel the animation
+ * (or an earlier fragment track) already keys is MERGE_CONFLICT, and a key
+ * before 0 or past the duration is MERGE_TIME — each named.
+ */
+export function mergeProblems(fragment: readonly RigcTrack[], where: string, animation: string, tracks: readonly RigcTrack[], duration: number, groups: Readonly<Record<string, readonly string[]>>): Problem[] {
+  const out: Problem[] = [];
+  const keyed = keyedBy(tracks, groups);
+  fragment.forEach((tr, i) => {
+    const label = trackLabel(tr, groups);
+    const hit = collisions(tr, keyed, groups);
+    if (hit.length > 0) out.push({ code: 'MERGE_CONFLICT', text: `${where} tracks[${i}] (${label}) — "${animation}" already keys it: ${hit.join(', ')}; a fragment adds a track where nothing keys that target and property, it never replaces one` });
+    for (const c of cellsOf(tr, groups)) if (!keyed.has(c)) keyed.set(c, `${where} tracks[${i}] (${label})`);
+    tr.keys.forEach((k, j) => {
+      if (k.t < 0 || k.t > duration) out.push({ code: 'MERGE_TIME', text: `${where} tracks[${i}] (${label}) keys[${j}] at t=${k.t}s is ${k.t < 0 ? 'before 0' : `past "${animation}"'s duration ${duration}s`}; a fragment's times are absolute, from the animation's start, within [0, ${duration}]` });
+    });
+  });
+  return out;
+}
+
+// --- lines ---------------------------------------------------------------
+
+const targetText = (t: Target, members: readonly string[] | null) => `${t.kind} "${t.name}"${members !== null && members.length > 0 ? ` (${members.join(', ')})` : ''}`;
+
+export function droppedLine(d: IdleDropped, animation: string, carry: boolean, duration: number): string {
+  const head = `${targetText(d.target, d.members)} ${d.property}: ${d.keys} key(s) over the idle's ${d.duration.toFixed(3)}s; "${animation}" does not key it`;
+  if (!carry) return `${head} — not carried (no --carry-idle)`;
+  if (d.carried !== null) return `${head} — carried: ${d.carried.keys} key(s), ${d.carried.cycles} cycle(s), cut at ${duration.toFixed(3)}s${d.carried.seams === null ? '' : `; ${d.carried.seams}`}`;
+  return `${head} — not carried: ${d.notCarried}`;
+}
+
+export function keptOutLine(k: IdleKeptOut): string {
+  return `${targetText(k.target, null)} ${k.property}: ${k.reason}, so the idle's track is not carried`;
+}

package/src/run.ts

@@ -9,7 +9,8 @@ import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { readMap, resolveMap, type JointMap } from './map.ts';
 import { convertCoco17, personTrack, readPoseSequence } from './pose.ts';
-import { lineOf, Problems, Refusal, type Problem } from './problems.ts';
+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 { bendLine, endOnLine, flipLine, holdLine, rangeLine, retarget, shortLine, turnLine, type RetargetOptions } from './retarget.ts';
 import { attachmentBones, baseMotionOf, buildInto, rigcVersion, folds, gate, readBuild, resolveRig, restOf, slotsOf } from './rigc.ts';
 import { artRangeLine, chainsMoving, switchLine, uncoveredFolds } from './switch.ts';
@@ -35,6 +36,12 @@ export interface RetargetArgs extends RetargetOptions {
   render?: string;
   /** Write the run's measurements as JSON here. */
   report?: string;
+  /** The rig's animation read as its idle (default: idle); naming one the motion spec lacks is refused. */
+  idle?: string;
+  /** Loop the idle's dropped tracks into the new animation (#43 item 2). */
+  carryIdle?: boolean;
+  /** A rig-pose-tracks/1 fragment merged into the new animation. */
+  merge?: string;
 }
 
 export interface RunResult {
@@ -52,8 +59,8 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     throw new Refusal(problems);
   };
   const args = new Problems();
-  for (const [flag, path] of [['--map', a.map], ['--pose', a.pose]] as const) {
-    if (!existsSync(path)) args.add('ARG_PATH', `${flag} ${path} does not exist`);
+  for (const [flag, path] of [['--map', a.map], ['--pose', a.pose], ['--merge', a.merge]] as const) {
+    if (path !== undefined && !existsSync(path)) args.add('ARG_PATH', `${flag} ${path} does not exist`);
   }
   // A file this run writes goes into a directory that is there already; --build and --render make theirs.
   for (const [flag, path] of [['--out', a.out], ['--report', a.report]] as const) {
@@ -67,6 +74,11 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
   const base = baseMotionOf(input);
   const animations = base.animations as Record<string, unknown>;
   if (a.name in animations) refuse([{ code: 'MOTION_NAME_FREE', text: `the rig's motion spec already has an animation "${a.name}" (it has ${Object.keys(animations).join(', ')}); name this one with --name` }]);
+  const idleName = a.idle ?? 'idle';
+  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` }]);
+  }
+  const fragment = a.merge === undefined ? [] : readFragment(parseJson(readFileSync(a.merge, 'utf8'), a.merge, 'MERGE_JSON'), a.merge);
   const map = readMap(readFileSync(a.map, 'utf8'), a.map);
   const poseText = readFileSync(a.pose, 'utf8');
   const seq = a.coco ? convertCoco17(poseText, a.pose) : readPoseSequence(poseText, a.pose);
@@ -87,7 +99,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     resolveMap(map, rest, a.map, slots);
 
     const r = retarget(rest, map, frames, times, a, slots);
-    say(`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}, smooth ${a.smooth}, 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' : ''}`);
+    say(`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}, smooth ${a.smooth}, 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.carryIdle === true ? ', carry-idle' : ''}${a.merge !== undefined ? `, merge ${a.merge}` : ''}`);
     say(`  RIGC   rig-c ${rigc.version} (${rigc.entry}) gates and poses this run`);
     if (r.scale !== null) say(`  SCALE  ${r.scale.factor.toFixed(5)} rig units per picture px (rig ${r.scale.rig.toFixed(2)} / pose median ${r.scale.pose.toFixed(2)})`);
     for (const h of r.holds) say(`  HOLD   ${holdLine(h, r.times)}`);
@@ -117,7 +129,48 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       say(`  FEET   steps (the supporting ankle > 0.03 leg lengths a frame; re-planted after 2 frames < 0.01): ${f.steps.map((x) => `${x.side} ${span(x.frames)} → ${x.to === null ? 'the pose\'s travel' : `${x.to} supports`}, ${x.replant === null ? 'never re-planted' : `re-planted at ${x.replant}`}`).join('; ') || 'none'}`);
     }
 
-    const motion = { ...base, animations: { ...animations, [a.name]: r.animation } };
+    // The idle against the new animation (#43 item 2): what it drops, and with --carry-idle, looped back in.
+    const groups = (isObject(base.groups) ? base.groups : {}) as Record<string, string[]>;
+    const easings = (isObject(base.easings) ? base.easings : {}) as Record<string, number[]>;
+    const own = r.animation.tracks as unknown as RigcTrack[];
+    const T = r.animation.duration;
+    let idle: IdleReading | null = null;
+    if (!(idleName in animations)) say(`  IDLE   ${input.motion === null ? 'the rig has no motion spec' : `the rig's motion spec has no animation "idle" (it has ${Object.keys(animations).join(', ') || 'none'})`}; no idle read (--idle names another)`);
+    else {
+      const setupOf = (t: Target, property: string, sample: unknown): unknown => {
+        if (t.kind === 'slot' && property === 'attachment') return slots.get(t.name)?.setup;
+        if ((t.kind === 'bone' || t.kind === 'group') && Array.isArray(sample)) return boneIdentity(property, sample.length);
+        return undefined;
+      };
+      const mapped = [...map.chains.flatMap((c) => c.bones), ...(map.translate === null ? [] : [map.translate.bone])];
+      const below = new Map<string, string[]>();
+      for (const m of new Set(mapped)) {
+        for (let b = rest.get(m)?.parent ?? null; b !== null; b = rest.get(b)?.parent ?? null) {
+          const list = below.get(b) ?? [];
+          if (!list.includes(m)) list.push(m);
+          below.set(b, list);
+        }
+      }
+      idle = readIdle(idleName, a.name, animations[idleName] as Record<string, unknown>, own, T, { groups, easings }, setupOf, a.carryIdle === true, (bone) => below.get(bone) ?? [], (bone) => {
+        const hip = map.translate?.bone;
+        if (hip === undefined) return null;
+        for (let b = rest.get(hip)?.parent ?? null; b !== null; b = rest.get(b)?.parent ?? null) if (b === bone) return hip;
+        return null;
+      });
+      say(`  IDLE   animation "${idleName}" (${idle.duration.toFixed(3)}s, ${idle.tracks} track(s)) against "${a.name}": ${idle.dropped.length} dropped (${a.carryIdle === true ? `${idle.carriedTracks.length} carried, looped to ${T.toFixed(3)}s` : 'not carried; --carry-idle loops them in'}), ${idle.keptOut.length} kept out`);
+      for (const d of idle.dropped) say(`  IDLE-DROPPED ${droppedLine(d, a.name, a.carryIdle === true, T)}`);
+      for (const k of idle.keptOut) say(`  IDLE-KEPT-OUT ${keptOutLine(k)}`);
+      for (const n of idle.notTracks) say(`  IDLE-KEPT-OUT "${idleName}"'s ${n} timeline(s): not a track; neither compared nor carried`);
+    }
+    const carried = idle?.carriedTracks ?? [];
+    if (fragment.length > 0) {
+      const problems = mergeProblems(fragment, a.merge!, a.name, [...own, ...carried], T, groups);
+      if (problems.length > 0) refuse(problems);
+      for (const tr of fragment) say(`  MERGE  ${a.merge}: ${trackLabel(tr, groups)}, ${tr.keys.length} key(s) at t=${tr.keys[0]!.t}${tr.keys.length > 1 ? `–${tr.keys[tr.keys.length - 1]!.t}` : ''}s`);
+    }
+    const added = [...carried, ...fragment];
+    const animation = added.length === 0 ? r.animation : { ...r.animation, tracks: [...own, ...added] };
+    const motion = { ...base, animations: { ...animations, [a.name]: animation } };
     const g1 = gate(input.rig, motion, join(scratch, 'with'), a.profile, a.images);
     if (!g1.green) {
       refuse([{ code: 'RIG_GATE', text: `rigc build --profile ${a.profile} is red with "${a.name}" in (exit ${g1.run.status}); nothing written` }, ...g1.fails.map((f) => ({ code: 'RIGC', text: f }))]);
@@ -128,13 +181,23 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     const posed = poseFrames(doc, a.name, r.times);
     const landings = measureLanding(doc, a.name, map, r, posed);
     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).
+    const carriedAbove = (bone: string): string => {
+      const above = new Set<string>();
+      for (let b = rest.get(bone)?.parent ?? null; b !== null; b = rest.get(b)?.parent ?? null) above.add(b);
+      const hits = carried.filter((tr) => {
+        const t = targetOf(tr);
+        return t !== null && (t.kind === 'bone' ? above.has(t.name) : t.kind === 'group' && (groups[t.name] ?? []).some((m) => above.has(m)));
+      });
+      return hits.length === 0 ? '' : `; --carry-idle carried ${hits.map((tr) => trackLabel(tr, groups)).join(', ')} onto bones above it`;
+    };
     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 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 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)`);
+      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();
 
@@ -186,7 +249,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         animation: a.name,
         frames: seq.frames.length,
         duration: r.animation.duration,
-        options: { minScore: a.minScore, smooth: a.smooth, 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 },
+        options: { minScore: a.minScore, smooth: a.smooth, 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, idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null },
         scale: r.scale,
         holds: r.holds,
         short: r.short,
@@ -206,6 +269,9 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         pivot: r.pivot,
         feet: r.feet === null ? null : { planted: r.planted, legLength: r.feet.legLength, supports: r.feet.supports, jumps: r.feet.jumps, steps: r.feet.steps, changes: r.feet.changes, reading: feetReading },
         shear,
+        idleDropped: idle === null ? null : idle.dropped,
+        idleKeptOut: idle === null ? null : idle.keptOut,
+        merged: fragment.map((tr) => ({ track: trackLabel(tr, groups), keys: tr.keys.length })),
       }, null, 2)}\n`);
     }
     say(`  wrote ${a.out} — animations: ${Object.keys(motion.animations).join(', ')}`);