rig-parts 1.1.1 → 1.2.0

package/cli.ts

@@ -186,7 +186,10 @@ usage:
       states no motion.blink, and a blink group that names no bone, or one
       bone twice, is refused by the loader, CONFIG_BLINK_GROUP_MEMBERS or
       CONFIG_BLINK_GROUP_UNIQUE, before rigc starts, as are two tracks on one
-      bone property, CONFIG_BONE_PROPERTY_KEYED_ONCE. --parts is the
+      bone property, CONFIG_BONE_PROPERTY_KEYED_ONCE. Beside the idle,
+      every animation of the file config.motion.animations_from names is
+      written into motion.json as read, for rigc's gate to judge (AUTHORING
+      §3). --parts is the
       directory holding parts.json and parts/<name>.png. The result is built
       through rig-c (profile spine-html, packed with --page-edges and
       --pack-shape as for check; rigc's build gates the compile and the packed pages on disk) in a

package/docs/AUTHORING.md

@@ -90,6 +90,7 @@ read by no CPU stage).
 | `motion.tracks` | rig | **proposed**, then tuned. Single `{bone, prop, amp, period, phase, base?}` or chain `{chain, amps, period, phase, lag}` — one amplitude per link, link `i` at phase `phase + lag·i`. Every `period` must divide `duration` (`CONFIG_PERIOD_DIVIDES_DURATION`). A bone property is keyed by one track (`CONFIG_BONE_PROPERTY_KEYED_ONCE`): a chain keys `rotate` on every link, the blink's `eyes` group `scaley` and its `brows` group `translatey` on every member, so a single track on any of those is a second track on it — rigc would refuse it one stage later, `animation "idle" has two tracks on eye.scaley`. A chain link is turned along its chain (the `bones` row), so a `translatex`/`translatey` key on a bone whose parent is a turned link, or a `scale`/`shear` key on a turned link, would move or stretch along the link and not along the picture's axis: the rig stage refuses it (`RIG_KEY_FRAME_UNTURNED`); `rotate` is keyed on any bone |
 | `motion.blink` | rig | **proposed**: `{t, eyes, brows, squash, brow_drop}`; the whole blink, `t` to `t + 0.364` s (`t + 0.314` s without brows: the brows' keys are the ones that end last), must fit inside the idle (`RIG_BLINK_INSIDE_IDLE`). The `eyes` group's `scaley` squashes every part on the eye bones about the bone's origin, the eyewhite's centre. Optional: a figure with no `eyewhite-r`/`-l` part has no eye bone, so `propose` writes no `blink` and notes `no blink: no eyewhite part (looked for: eyewhite-r, eyewhite-l), …`; with eyes and no `eyebrow-r`/`-l` part it writes the blink without `brows` and `brow_drop` and notes `blink without brows: …`. `brows` and `brow_drop` are stated together or not at all (`CONFIG_BLINK_BROWS_PAIRED`), and a group that names no bone is refused (`CONFIG_BLINK_GROUP_MEMBERS`) — rigc would refuse it one stage later, `group "eyes" declares no members` — as is a group that names one bone twice (`CONFIG_BLINK_GROUP_UNIQUE`; rigc: `group "eyes" names member "eye" twice`). An `irides-*` or `eyelash-*` part on a side with no eyewhite has no eye bone to ride: `propose` places it on `head` as a region, which the blink does not move, and notes `no eyewhite part for eye_r (looked for: eyewhite-r): iris (head:irides-r) is placed on head as a region, …`. The timing is fixed, not a field (table below) |
 | `motion.blink.still` | rig | **proposed** only for a lash `propose` notes (below), then checked: `{<part>: {row, bone}}` — the rows of that region part above `row` (rig px, y down) are drawn by a second slot `<part>_still` on `bone` and do not blink; rows from `row` down keep the part's slot and blink. The part must be a region on a bone `eyes` names, `bone` one it does not (`CONFIG_STILL_OFF_THE_BLINK`), and `row` a row of the part with no art across its whole width (`RIG_STILL_ROW_CLEAR`) |
+| `motion.animations_from` | rig; check (named, not measured) | optional, never proposed (issue #183): a path, relative to the config file's directory, to a file in rig-c's motion-spec shape, `{"spec": "rigc-motion/1", "animations": {"<name>": {"duration": …, "tracks": [...]}, …}}` — an expression, a gesture, anything beside the idle. On every `rig` and `build` each of its animations is written into `rig/motion.json` after `idle`, as read: nothing added, re-keyed or judged here, and each is rigc's to accept or refuse at the rig stage's gate, in rigc's words. It may name what `motion.json` already holds — the bones `bones` declares, the easings `shut` and `open`, the groups `eyes` and `brows` when the blink writes them — and nothing else from the file reaches it. The loader refuses, every problem at once: no such file or one that cannot be read (`CONFIG_FILE_PRESENT`), text that is not JSON (`CONFIG_IS_JSON`), a file that is not an object, a `spec` other than `"rigc-motion/1"`, an `animations` that is not a table of objects (`CONFIG_FIELD_TYPE`), any other key — rig-c's `easings`, `groups`, `setup`, `physics`, `mix`, `archetype` and `cut` included, which would be read and not written (`CONFIG_KEY_KNOWN`), an animation named `idle` (`CONFIG_ANIMATION_NAME_FREE`), and a key written twice in one object of the file, which JSON would fold into its last value without a word (`CONFIG_KEY_UNIQUE`). `check` measures the idle alone and prints one line naming the others (`beside the idle: …`). Absent, `motion.json` holds the idle alone, byte for byte as before |
 | `constraints` | rig (handed to rig-c as `rig.json`'s `constraints`); `compare` and the coverage lines (roles) | **authored**, optional; `propose` writes none. A list of constraints in **rig-c's own rig-spec shape** (`RigConstraint`: `ik`, `transform`, `path`, `physics`, `slider` — rig-c's `src/rig.ts` documents every field), in the order rigc applies them. The loader checks only what this package owns: each entry is an object with a `type` rigc names (`CONFIG_CONSTRAINT_TYPE_KNOWN`) and a non-empty `name`, unique within its kind as rigc finds constraints (`CONFIG_CONSTRAINT_NAME_UNIQUE`; an ik and a transform may share one); every bone it names — `bones`, an ik's `target`, a transform's `source`, a physics or slider constraint's `bone` — is a bone `bones` declares, a chain link as `<chain><i>` (`CONFIG_NAME_RESOLVES`); the bone a constraint follows does not sit under a bone it drives (`CONFIG_CONSTRAINT_TARGET_DETACHED`). Every other field (`mix`, `softness`, `properties`, a path's `slot`, a slider's `animation`) and every value is rigc's to accept or refuse at the rig stage's gate, in rigc's words (`RIG_RIGC_GREEN`) — an ik's `bones` as a shape too: from rig-c 2.15.0 rigc refuses an ik over more than two bones, or over a pair whose second bone is not the first's child (issue #103; this loader refused both itself until then). A note and an `x-` record may ride on an entry; the rig stage leaves them out of what it hands rigc. Under the default `--idle-keys ctl` a two-bone ik whose child link the idle keys is split by that link's control, and rigc refuses the pair: run `rig --idle-keys direct` or `build --idle-keys direct` (the rig stage adds that sentence, naming the flag on the command that ran, to rigc's line; `build` forwards it to its rig stage, issue #95). Each bone a constraint follows is declared to rigc as `invariants.detached` from every bone it drives, which rigc's gate rule `A25` checks |
 
 **A scene target is an ordinary bone.** A target the scene places — a point a hand
@@ -981,7 +982,7 @@ proposal in as the steps above say (`RL01`); every step must exit 0.
 | `propose` | `note:` lines, `LINT` lines, the `coverage` lines, `landmarks.png`, `basis.json` | no LINT line: every chain link lies on its mesh's art, and the hip is below the chest and the figure's top quarter; the `coverage:` summary says how many bones that verdict covers — a `not checked` bone was read by no check (its line says why), and a `ratio` or `fallback` bone in `basis.json` is a guess | a link off the art (a bone on the background) — move it onto the layer; `LINT hip at [x, y] is not below chest at [x, y]: …` or `LINT hip at [x, y] is above 0.25 of the figure height (figure y T..B, so hip y must be at least L): a hip at the shoulders` — move `hip` down to the waist (and `chest` between it and the neck); a `hanging strand … -- no chain proposed` note — that strand hangs stiff until you add a chain down the x and rows it names (§3); a `no blink: …` or `blink without brows: …` note — the idle will not blink (or its brows will not drop), because no part came from an `eyewhite` (or `eyebrow`) layer; the note names the tags looked for; a `no eyewhite part for eye_<s> …` note — the iris and lash parts it names ride `head` and do not blink, because no `eyewhite-<s>` part made that side's eye bone: take the eyewhite from the other run, or keep them on `head`; a `no face part: face box derived from …` note (always the first) — `head`, `neck` and every face-height scale come from a box guessed off the hair and neck (§3): check `head` and `neck` on `landmarks_head.png` and move them; when it adds `the blink shuts the eyes over no face part`, read `BLINK_NO_HOLE` after `check` — an eye with no face under it can open a hole (the `sample` with only its face removed: 587 px). Under `--keypoints`: the `lint rule set:` line first (joints, or screen and why), then the joint notes — `missing: the rule "…" placed bone X instead` is a bone still guessed; `not used — …` names why an arm's joints did not place its sleeve; `LINT chest at … is not between the neck joint …`, `LINT hip at … is not past chest …`, `LINT hip at … is nearer the neck joint …` and `LINT <chain><i> at … does not advance from <s>_shoulder toward <s>_wrist` are the joint-frame lines: move that bone between, past or along the joints they name |
 | `compare` | one line per pair (origin, parent, tip, length, direction — or SKIP and why), then the per-row summary, the unmapped bones of each side, `required:`, each side's roles and the `controls:` line | proposal against the config you corrected: the rows you changed and no others. Config against the `rig.json` `build` writes for it: measured on both examples, every origin within 6.19e-7 px (the rig's offsets are written to 6 places) and every chain link's tip and length within 4.99e-4 px (`length` is written to 3), printed to three places as `0.000` (a signed figure as `+0.000` or `-0.000`); `parent … is the right's ancestor at depth 2, <bone>_ctl between` for every keyed mesh bone, no `DIFFERENT` and no `NOT MAPPED` | `parent DIFFERENT: left a, right b` — a bone hangs from another parent than the other side's; `frames not related` — a rig with no stage (`skeleton.width`/`height`), two configs at different `rig_scale`: the distance rows SKIP, so declare the frame in a `--map` file if the author knows it; `FAIL  STRUCTURE_REQUIRED_PRESENT` — a bone the map requires is missing through its pairs |
 | `rig` (inside `build`) | one line per mesh: vertices, triangles, bones, influences, `cover`; the `bones` line; the `idle keys` line; then rigc's gate lines (with A15's declared SKIP under `--idle-keys direct`); in `rig.json`, each chain link's (or its `_ctl`'s) `length` and `rotation` | `cover 1.00000` on every mesh, both gate summaries `0 failed` (the compile and the packed pages); every link's `length` the distance to the next link and `rotation` its direction (Spine degrees, counter-clockwise, y up, local to the parent), every offset under it — a child bone's `x, y`, a weight's bind `x, y`, a region's `x, y` — in that turned frame, and a region on a link carrying `rotation` that turns it back upright. Nothing moved: `flattenRig` (`src/rig.ts`) turns every offset back and gives the unturned numbers | `RIG_LATTICE_ONE_LOOP`: change that mesh's `grid` |
-| `check` (inside `build`) | the gate lines verbatim, the pack line, `loop:`, `seam:`, the six judgement lines, `RECOMPOSITE_HOLES` and, under `--source`, `SETUP_POSE_VS_SOURCE` (§7), `check.json`; the last line says how many of the nine bars measured and names the ones that said SKIP | `check: PASS; 9 of 9 bar(s) measured, 0 skipped` on the examples, and a judgement line SKIP only where the character lacks what it reads; on a rig spec with no `parts.json` or no `idle` (a merged rig, §7 *Measuring a rig rig-parts did not assemble*), PASS with the skipped bars named | `CHECK_SEAM_WITHIN_BAR` or `CHECK_LOOP_CLOSES` (§6) |
+| `check` (inside `build`) | the gate lines verbatim, the pack line, `loop:` (and `loop physics:` when the rig declares a physics constraint, §7), `seam:`, the six judgement lines, `RECOMPOSITE_HOLES` and, under `--source`, `SETUP_POSE_VS_SOURCE` (§7), `check.json`; the last line says how many of the nine bars measured and names the ones that said SKIP | `check: PASS; 9 of 9 bar(s) measured, 0 skipped` on the examples, and a judgement line SKIP only where the character lacks what it reads; on a rig spec with no `parts.json` or no `idle` (a merged rig, §7 *Measuring a rig rig-parts did not assemble*), PASS with the skipped bars named | `CHECK_SEAM_WITHIN_BAR` or `CHECK_LOOP_CLOSES` (§6) |
 | `check --requirements` (and `build --requirements`) | after the lines above, one line per declared requirement, `NAME: PASS`, `FAIL` or `NOT MEASURABLE — …` with its figures, the bar as declared and the worst frame; then `requirements: N declared — M measured (P PASS, F FAIL), K NOT MEASURABLE; not declared: <kinds>`; `check.json`'s `requirements` block; the renders under `requirements/` (§7, *Declared requirements*) | every line PASS and `0 NOT MEASURABLE`; a follow's `released_copy` says whether rigc's consumer-driven door was taken on the throwaway copy | `CHECK_REQUIREMENT_MET` (a figure past its bar; the line names the frame) or `CHECK_REQUIREMENT_MEASURABLE` (the quantity is undefined in the frames: a tip or an axis on a bone of length 0, an aim with no line, a follow no frame of which reaches its least drive); the last line then reads `check: FAIL — B bar(s) not met, R declared requirement(s) not PASS` |
 | `compose` | the `[compose]` lines: one per character (its offset, its placed bounds, the shift and how many first-level bones, regions on `root` and weights bound to `root` it moved, its bone, slot, track and constraint counts, its `rig_scale` and idle), the declared order and the slot count it expands to, rigc's gate lines; then the `[check]` lines as for `check`, and `scene.json` | both gate summaries `0 failed`, `check: PASS` with the bars that measured and the ones that said SKIP named — on a composed rig `4 of 9`: the gate, the loop, `CHAIN_LAG` and `TEXTURE_STRETCH` (there is no `parts.json`; each character's own `build` measured all nine). `scene.json`'s `order.slots` is the order the compiled skeleton draws | a `SCENE_*` refusal (§6, *compose*) — the scene file, a build, or the order; `COMPOSE_RIGC_GREEN` — rigc's own line, quoted |
 | `loop` (inside `build --loop`, or `loop --frames … --out …`) | the dropped-duplicate line, each file's line, then `loop: idle.png N B (lossless); idle-indexed.png N B (max …, mean …); idle.gif N B (max …, mean …)` | `f0048.png equals f0000.png byte for byte, so it is dropped` | `LOOP_ENCODE` (§6) |
@@ -1408,7 +1409,7 @@ See-through with another seed.
 | `CHECK_RIGC_ENTRY`, `CHECK_RIGC_ENTRY_READS` | `rigc --version` names no entry (a rigc below 2.0.0), or names one in neither launcher form (`entry: cli.ts — @esotericsoftware/spine-core <v> present`, `entry: cli_core.ts — @esotericsoftware/spine-core absent — …`); `check.json`'s `rigc_entry` records the one that gated the build | `bun install` |
 | `CHECK_RIGC_GREEN` | a rigc step failed; its line is quoted | as `RIG_RIGC_GREEN` |
 | `CHECK_LOOP_LAST_FRAME_AT_DURATION` | the idle's last frame does not sit at `duration` | `motion.duration` — a whole number of 1/12 s |
-| `CHECK_LOOP_CLOSES` | frame 0 and the frame at `duration` differ (max and first pixel quoted) | a track whose last key is not its first |
+| `CHECK_LOOP_CLOSES` | frame 0 and the frame at `duration` differ (max and first pixel quoted); with a physics constraint, the frames of the rig with every physics constraint left out, and the object says so (§7, *loop*) | a track whose last key is not its first |
 | `CHECK_SEAM_WITHIN_BAR` | the setup pose does not reproduce the flat stack of parts | usually a region or mesh placed off its part; compare with `recomposite_rig.png` |
 | `CHECK_BREATH_VISIBLE` | the torso (`topwear`), rendered alone, barely moves over the idle — or the feet (`footwear`), rendered alone, move at all | the chest's breath tracks (`motion.tracks` on `chest`), or the torso mesh's `segments`; for the feet, the bone their region rides (`regions.<part>`, `root` in both examples) |
 | `CHECK_BLINK_NO_HOLE` | with the blink held shut, the eyewhite box shows the page where the open eye had art | the layer under the eye: the `face` part has no art there. Take the face from the other run, or add a part under the eye; `motion.blink.squash` only hides the hole less |
@@ -1476,7 +1477,17 @@ assemble*, at the end of this section):
   holds it on every fetched example);
 - **seam**: the setup-pose render against the flat composite of `parts/`: mean
   max-channel |d| ≤ 1.0 of 255, and at most 50 pixels over 40;
-- **loop**: idle frame 0 against the frame at `t = duration`: max |d| exactly 0.
+- **loop**: idle frame 0 against the frame at `t = duration`: max |d| exactly 0. The bar
+  measures the keys (issue #183): a rig that declares a physics constraint — a `rig.json`
+  `constraints` entry of `type` `"physics"`, or an entry of `motion.json`'s `physics`
+  table — has the two frames read from the same rig and motion with every one left out
+  (with a skin's `physics` list and any track keying one), built and rendered as the idle
+  is, because rig-c's render resets physics at frame 0 and steps it, so the last frame
+  differs from the first by what the simulation is still doing. The constraints left out
+  are printed on one line of their own, `loop physics: … "<name>" on bone "<bone>"
+  (rig.json|motion.json)`, and written as `check.json`'s `loop_physics` after
+  `loop_max_diff`; they are reported, not judged. A rig with none is measured from the
+  idle render itself, exactly as before, and writes no such line or key.
 
 On the examples: `sample` 23/23, seam 0.207 with 0 pixels over 40, loop 0;
 `demo` (default rule) 23/23, seam 0.326 with 2 pixels over 40, loop 0.

package/docs/STABILITY.md

@@ -127,11 +127,12 @@ part name, `[i]` an entry of a list):
 - **meshes.<part>.auto.regions[i]** — required: `name`, `shape`, `maxEdgeLength`, `transition`, `grade`, `minArtSamples`, and `cx`, `cy`, `r` for a circle or `points` for a polygon; optional: `bone`, `band` (both or neither; with neither the region is density only)
 - **meshes.<part>.auto.boundaryRuns** — required: `maxVertices`
 - **regions.<part>** — a bone name
-- **motion** — required: `duration`, `tracks`; optional: `blink`
+- **motion** — required: `duration`, `tracks`; optional: `blink`, `animations_from`
 - **motion.tracks[i]**, a single track — required: `bone`, `prop`, `amp`, `period`, `phase`; optional: `base`
 - **motion.tracks[i]**, a chain track — required: `chain`, `amps`, `period`, `phase`, `lag`
 - **motion.blink** — required: `t`, `eyes`, `squash`; optional: `brows`, `brow_drop`, `still`
 - **motion.blink.still.<part>** — required: `row`, `bone`
+- **motion.animations_from**, the file it names — required: `spec`, `animations`
 - **proposal.json**, the file propose writes — `bones`, `meshes`, `regions`, `motion` under the rules above, and `notes`
 <!-- /stable:config -->
 
@@ -152,7 +153,7 @@ every number) are AUTHORING §3's tables, and the loader refuses any other by na
 | `parts.json`, `parts/<name>.png` | `assemble`, `build` | one record per part: `from`, the box `x`, `y`, `w`, `h` (rig px), the pixel counts `src/parts.ts` documents (`opaque_px`, `visible_px`, `occluded_px`, `projected_core_px`, `source_px_taken`, `visible_not_projected_px`, `refused_drift_px`, `merged_px`, `seam_override_px`, and `fringe_pushed_back` when not empty); `rig_size`, `scale_rig_per_source`, `ghost_px`, `recomposite` |
 | `rig/rig.json`, `rig/motion.json`, `rig/images/` | `rig`, `build`, `compose` | rig-c's rig spec and motion spec, `spec` `rigc-rig/1` and `rigc-motion/1`: the format is rig-c's, and this package writes only what rig-c's parser accepts |
 | `rig/mesh_report.json` | `rig`, `build` | one row per mesh: `part`, `vertices`, `triangles`, `hull`, `bones`, `max_influences`, `mean_influences`, `art_coverage`, then `grid` (a lattice); `mode` "contour" with `params`, `contour`, `regions`; or `mode` "auto" with `settings`, `source`, `result`, `residuals`, `worst_residual`, `worst_region`, `motion_amplitude`, `termination`, `weights`, `regions`, `deformation`, `quality_report` (rig-c's `mesh-quality-report/1` document whole), `motion_report`, and, only when they apply, `stray_cleared` (after `source`, when `source.stray` is declared), `skinning_residual` and `replay` (`AutoMeshReport` in `src/rig.ts`); in every mode, `exponent` when the mesh declares one (after `grid`, or after `mode`) |
-| `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode`, `loop_max_diff`, the seam figures), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `RECOMPOSITE_HOLES`, `SETUP_POSE_VS_SOURCE`, `skipped`, a `requirements` block under `--requirements`, and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes |
+| `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode`, `loop_max_diff`, the seam figures), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `RECOMPOSITE_HOLES`, `SETUP_POSE_VS_SOURCE`, `skipped`, a `requirements` block under `--requirements`, and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes |
 | `proposal.json`, `render/landmarks*.png` | `propose` | the config's four rig sections and `notes` |
 | `basis.json` | `propose` | spec `spine-parts-basis/1` |
 | the scene report | `compose` | spec `spine-parts-scene-report/1` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
   "type": "module",
   "bin": {

package/src/build.ts

@@ -70,12 +70,12 @@ import {
   splitSchedule,
   untestedIntervals,
 } from './autoreplay.ts';
-import { BARS, causeLines, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, type PageEdges, readFrameSet, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_MEAN_BAR, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK } from './check.ts';
-import { loadConfig, loadEarlyConfig } from './config.ts';
+import { BARS, besideIdleLine, causeLines, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, type PageEdges, readFrameSet, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_MEAN_BAR, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK } from './check.ts';
+import { loadConfig, loadConfigAndAnimations, loadEarlyConfig } from './config.ts';
 import { PartsError, type Problem, problemLine, refuseIfAny } from './errors.ts';
 import type { MeshQualityReport, MotionSchedule } from 'rig-c/mesh';
 import { encodeGif } from './gif.ts';
-import { CONTROL_SUFFIX } from './motion.ts';
+import { CONTROL_SUFFIX, withAnimations } from './motion.ts';
 import type { PaletteError } from './palette.ts';
 import { type LayerSet, readLayers } from './layers.ts';
 import { type PartRecord, readParts, writeParts } from './parts.ts';
@@ -637,7 +637,7 @@ function multiIntervalRun(
  * accepted it (issue #126 item 3; {@link motionGates}).
  */
 export function rigStage(input: RigStageInput, rigc: RigcRunner, scratch: string, log: Log): RigOutput {
-  const cfg = loadConfig(input.config);
+  const { config: cfg, animations: from } = loadConfigAndAnimations(input.config);
   const parts = readParts(join(input.parts, 'parts.json'));
   const images = new Map<string, Raster>();
   for (const p of parts.parts) {
@@ -647,7 +647,7 @@ export function rigStage(input: RigStageInput, rigc: RigcRunner, scratch: string
   const first = buildRig(cfg, parts, images, undefined, input.idleKeys ?? DEFAULT_IDLE_KEYS, input.reduce);
   const textsOf = (r: RigOutput): Array<[string, string]> => [
     ['rig.json', rigJsonText(r.rig)],
-    ['motion.json', rigJsonText(r.motion)],
+    ['motion.json', rigJsonText(withAnimations(r.motion, from === null ? null : from.table))],
     ['mesh_report.json', rigJsonText(r.meshReport)],
   ];
   const firstTexts = textsOf(first);
@@ -735,6 +735,7 @@ export function rigStage(input: RigStageInput, rigc: RigcRunner, scratch: string
   log(
     `  bones ${rig.rig.bones.length} (${rig.controls.length} control) slots ${rig.rig.slots.length} meshes ${rig.meshReport.length} regions ${regions} vertices ${vertices}; idle ${rig.motion.animations.idle.duration} s, ${tracks.length} track(s), ${keys} key(s)`,
   );
+  if (from !== null) log(`  animations beside the idle, from ${from.file} as written: ${Object.keys(from.table).join(', ') || 'none'}`);
   log(
     rig.idleKeys === 'ctl'
       ? `  idle keys ctl: ${rig.meshKeyed.length} mesh-driving bone(s) keyed by the idle, each keyed through a same-origin <bone>_ctl parent`
@@ -875,6 +876,9 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   const fig = r.figures;
   if (r.idle === null) log(`  loop: SKIP — ${fig.skipped?.loop ?? ''}`);
   else log(`  loop: idle ${r.idle.frames} frame(s) at ${r.idle.fps} fps, f0000 vs f${String(r.idle.lastIndex).padStart(4, '0')} (t = ${r.idle.duration}s): max |d| ${fig.loop_max_diff} (0 required)`);
+  if (r.loopPhysics !== null) log(`  ${r.loopPhysics}`);
+  const beside = besideIdleLine(r.besideIdle);
+  if (beside !== null) log(`  ${beside}`);
   if (r.seamViewport === null || fig.seam_mean === null) log(`  seam: SKIP — ${fig.skipped?.seam ?? ''}`);
   else {
     log(

package/src/check.ts

@@ -919,6 +919,70 @@ export function readFrameSet(path: string): FrameSet {
   };
 }
 
+// ---------------------------------------------------------------------------
+// the keyed loop: physics left out (issue #183)
+// ---------------------------------------------------------------------------
+
+/** A physics constraint the loop's frames leave out, as the `loop:` physics line names it. */
+export interface LoopPhysics {
+  name: string;
+  bone: string;
+  /** Where it was declared: rig.json's `constraints`, or motion.json's `physics` table. */
+  in: 'rig.json' | 'motion.json';
+}
+
+/**
+ * The rig spec and motion spec with every physics constraint left out, and
+ * the constraints it left out; null when there is none, so a rig without one
+ * is measured from the very build and render it always was.
+ *
+ * rig-c's render resets physics at frame 0 and steps it by 1/fps (its
+ * `spinePoser`), so a constraint still moving at the idle's duration makes
+ * the last frame differ from the first by what the simulation is doing, not by
+ * what the keys say. `CHECK_LOOP_CLOSES` measures the keys: a rig-c
+ * `constraints` entry of `type` `"physics"` and every entry of motion.json's
+ * `physics` table are dropped, with what names them only to activate or key
+ * them — a skin's `physics` list, and an animation track whose target is a
+ * `physics` constraint. Nothing else is touched, and nothing here judges the
+ * constraints: the line that names them reports.
+ */
+export function withoutPhysics(rig: Record<string, unknown>, motion: Record<string, unknown>): { rig: Record<string, unknown>; motion: Record<string, unknown>; physics: LoopPhysics[] } | null {
+  const physics: LoopPhysics[] = [];
+  const constraints = Array.isArray(rig.constraints) ? rig.constraints : null;
+  if (constraints !== null) {
+    for (const c of constraints) if (isRecord(c) && c.type === 'physics') physics.push({ name: String(c.name), bone: String(c.bone), in: 'rig.json' });
+  }
+  const table = isRecord(motion.physics) ? motion.physics : null;
+  if (table !== null) for (const [name, e] of Object.entries(table)) physics.push({ name, bone: isRecord(e) ? String(e.bone) : '', in: 'motion.json' });
+  if (physics.length === 0) return null;
+  const r: Record<string, unknown> = { ...rig };
+  if (constraints !== null) {
+    const kept = constraints.filter((c) => !(isRecord(c) && c.type === 'physics'));
+    if (kept.length > 0) r.constraints = kept;
+    else delete r.constraints;
+  }
+  if (isRecord(rig.skins)) {
+    r.skins = Object.fromEntries(Object.entries(rig.skins).map(([skin, entry]) => {
+      if (!isRecord(entry) || !('physics' in entry)) return [skin, entry];
+      return [skin, Object.fromEntries(Object.entries(entry).filter(([k]) => k !== 'physics'))];
+    }));
+  }
+  const m: Record<string, unknown> = { ...motion };
+  delete m.physics;
+  if (isRecord(motion.animations)) {
+    m.animations = Object.fromEntries(Object.entries(motion.animations).map(([name, a]) => {
+      if (!isRecord(a) || !Array.isArray(a.tracks)) return [name, a];
+      return [name, { ...a, tracks: a.tracks.filter((t) => !(isRecord(t) && 'physics' in t)) }];
+    }));
+  }
+  return { rig: r, motion: m, physics };
+}
+
+/** The one line naming what {@link withoutPhysics} left out of the loop's frames: reported, not judged. */
+export function loopPhysicsLine(physics: readonly LoopPhysics[]): string {
+  return `loop physics: ${physics.length} physics constraint(s) left out of the loop's frames, reported, not judged — ${physics.map((p) => `"${p.name}" on bone "${p.bone}" (${p.in})`).join(', ')}`;
+}
+
 // ---------------------------------------------------------------------------
 // pixel measurements
 // ---------------------------------------------------------------------------
@@ -1188,6 +1252,12 @@ export interface CheckFigures {
   pack_mode: { page_edges: PageEdges; pack_shape: PackShape };
   /** Null when the rig has no idle (issue #77); `skipped.loop` then says why. */
   loop_max_diff: number | null;
+  /**
+   * Written only when the rig declares a physics constraint (issue #183):
+   * each one {@link withoutPhysics} left out of the frames `loop_max_diff` was
+   * read from. Reported, not judged; a rig without one writes the keys it always wrote.
+   */
+  loop_physics?: LoopPhysics[];
   /** The three seam figures: null when there is no parts.json (issue #77); `skipped.seam` then says why. */
   seam_mean: number | null;
   seam_px_over_40: number | null;
@@ -1232,6 +1302,8 @@ export interface CheckReport {
   packOpaque: Array<{ page: string; share: number }>;
   /** Null when the rig has no idle. */
   idle: { frames: number; fps: number; duration: number; lastIndex: number; loopAt: { x: number; y: number } } | null;
+  /** The physics line ({@link loopPhysicsLine}); null when the rig declares no physics constraint or has no idle. */
+  loopPhysics: string | null;
   /** The setup-pose still's grid; null when nothing read the still (no parts.json and no `--source`). */
   seamViewport: Viewport | null;
   /** Every bar in {@link BARS} that measured, and every one that did not with its reason. */
@@ -1241,6 +1313,22 @@ export interface CheckReport {
   written: string[];
   /** Under `--requirements` only (issue #93): what `check.json`'s `requirements` block holds; null without the flag. */
   requirements: RequirementsBlock | null;
+  /**
+   * The animations `motion.json` holds beside the idle (issue #183), in its
+   * order: built and gated with the rig, measured by nothing here — every bar
+   * reads the idle. Empty when the idle is alone.
+   */
+  besideIdle: string[];
+}
+
+/**
+ * The one line `check` prints when `motion.json` holds animations beside the
+ * idle (issue #183), or null when it holds none, so a rig of the idle alone
+ * prints what it printed before.
+ */
+export function besideIdleLine(names: readonly string[]): string | null {
+  if (names.length === 0) return null;
+  return `beside the idle: ${names.length} animation(s), ${names.join(', ')} — built and gated by rigc with the rig, not measured: every bar here reads the idle`;
 }
 
 /**
@@ -1323,7 +1411,8 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   const idleDir = join(out, 'idle_frames');
   const stillDir = join(out, '_still');
   const isoDir = join(out, '_isolated');
-  for (const d of [buildDir, idleDir, stillDir, isoDir]) rmSync(d, { recursive: true, force: true });
+  const loopDir = join(out, '_loop');
+  for (const d of [buildDir, idleDir, stillDir, isoDir, loopDir]) rmSync(d, { recursive: true, force: true });
   const written: string[] = [];
   const write = (name: string, data: string): void => {
     writeFileSync(join(out, name), data);
@@ -1352,6 +1441,8 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   // 3. the idle, the loop, the heat — only when there is an idle
   let idle: FrameSet | null = null;
   let loop: { max: number; x: number; y: number } | null = null;
+  let loopSet: FrameSet | null = null;
+  let loopPhysics: LoopPhysics[] | null = null;
   if (inp.idleDuration !== null) {
     const render = rigc(['render', '--candidate', buildDir, '--animation', 'idle', '--fps', String(IDLE_FPS), '--max', String(IDLE_MAX_PX), '--geometry', '--out', idleDir]);
     if (render.status !== 0) refuseIfAny(rigcFailed('render --animation idle --geometry', render, render.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
@@ -1372,6 +1463,39 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
       written.push('contact.png');
     }
     loop = maxRgbDiff(idle.frames[0].image, last.image);
+    loopSet = idle;
+    // The keyed loop (issue #183): with a physics constraint, the same rig and motion with every one left out, built
+    // the same way and rendered the same way, is what frame 0 and the frame at the duration are read from.
+    const stripped = withoutPhysics(inp.rig, inp.motion);
+    if (stripped !== null) {
+      loopPhysics = stripped.physics;
+      try {
+        mkdirSync(loopDir, { recursive: true });
+        const images = typeof inp.rig.images === 'string' ? resolve(inp.rigDir, inp.rig.images) : inp.rig.images;
+        writeFileSync(join(loopDir, 'rig.json'), JSON.stringify({ ...stripped.rig, images }));
+        writeFileSync(join(loopDir, 'motion.json'), JSON.stringify(stripped.motion));
+        const what = 'the idle with its physics constraint(s) left out';
+        const lb = rigc(['build', '--rig', join(loopDir, 'rig.json'), '--motion', join(loopDir, 'motion.json'), '--out', join(loopDir, 'build'), ...packedBuildArgs(mode)]);
+        if (lb.status !== 0) refuseIfAny(rigcFailed(`${packedBuildLabel(mode)} (${what})`, lb, buildGateLines(lb.out)));
+        const lr = rigc(['render', '--candidate', join(loopDir, 'build'), '--animation', 'idle', '--fps', String(IDLE_FPS), '--max', String(IDLE_MAX_PX), '--out', join(loopDir, 'frames')]);
+        if (lr.status !== 0) refuseIfAny(rigcFailed(`render --animation idle (${what})`, lr, lr.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
+        const kept = readFrameSet(join(loopDir, 'frames'));
+        const keptLast = kept.frames[kept.frames.length - 1];
+        if (kept.stride !== 1 || kept.written !== kept.sampled || keptLast.index !== last.index) {
+          refuseIfAny([
+            {
+              code: 'CHECK_LOOP_LAST_FRAME_AT_DURATION',
+              object: `idle frame ${keptLast.name} (${what})`,
+              detail: `rigc sampled ${kept.sampled} frame(s), wrote ${kept.written} at stride ${kept.stride}; the idle as written ends at ${last.name}, and the loop compares frame 0 with that frame`,
+            },
+          ]);
+        }
+        loop = maxRgbDiff(kept.frames[0].image, keptLast.image);
+        loopSet = kept;
+      } finally {
+        rmSync(loopDir, { recursive: true, force: true });
+      }
+    }
     const idleImages = idle.frames.map((f) => f.image);
     writePng(join(out, 'motion_heat.png'), motionHeat(idleImages));
     written.push('motion_heat.png');
@@ -1491,6 +1615,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     rigc_entry: rigcEntry,
     pack_mode: { page_edges: mode.pageEdges, pack_shape: mode.packShape },
     loop_max_diff: loop === null ? null : loop.max,
+    ...(loopPhysics === null ? {} : { loop_physics: loopPhysics }),
     seam_mean: seam === null ? null : round3(seam.mean),
     seam_px_over_40: seam === null ? null : seam.over40,
     seam_px_over_80: seam === null ? null : seam.over80,
@@ -1508,12 +1633,12 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   };
   const barProblems: Problem[] = [];
   if (!htmlGreen) barProblems.push(...rigcFailed(packedBuildLabel(mode), build, gateHtml));
-  if (loop !== null && idle !== null && loop.max !== LOOP_MAX_BAR) {
+  if (loop !== null && idle !== null && loopSet !== null && loop.max !== LOOP_MAX_BAR) {
     const last = idle.frames[idle.frames.length - 1];
     barProblems.push({
       code: 'CHECK_LOOP_CLOSES',
-      object: `idle frame f0000.png vs ${last.name} (t = ${idle.duration}s)`,
-      detail: `max |d| ${loop.max}/255, first at pixel ${loop.x},${loop.y} of ${idle.viewport.pixelWidth}x${idle.viewport.pixelHeight}; ${LOOP_MAX_BAR} is required — the idle's last key must equal its first`,
+      object: `idle frame f0000.png vs ${last.name} (t = ${idle.duration}s)${loopPhysics === null ? '' : ', its physics constraint(s) left out'}`,
+      detail: `max |d| ${loop.max}/255, first at pixel ${loop.x},${loop.y} of ${loopSet.viewport.pixelWidth}x${loopSet.viewport.pixelHeight}; ${LOOP_MAX_BAR} is required — the idle's last key must equal its first`,
     });
   }
   if (figures.seam_mean !== null && figures.seam_px_over_40 !== null && (figures.seam_mean > SEAM_MEAN_BAR || figures.seam_px_over_40 > SEAM_PX_BAR)) {
@@ -1546,11 +1671,13 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     pack,
     packOpaque,
     idle: idle === null || loop === null ? null : { frames: idle.frames.length, fps: idle.fps, duration: idle.duration, lastIndex: idle.frames[idle.frames.length - 1].index, loopAt: { x: loop.x, y: loop.y } },
+    loopPhysics: loopPhysics === null ? null : loopPhysicsLine(loopPhysics),
     seamViewport,
     bars,
     problems,
     written,
     requirements: reqBlock,
+    besideIdle: isRecord(inp.motion.animations) ? Object.keys(inp.motion.animations).filter((n) => n !== 'idle') : [],
   };
 }
 

package/src/config.ts

@@ -54,8 +54,22 @@
  * (`x-…`) and an annotation (`note`, `…_note`) ride on a constraint as on any
  * object the loader vouches for, and the rig stage leaves them out of what it
  * hands rigc ({@link constraintForRig}).
+ *
+ * 🔗 **`motion.animations_from` is rig-c's too, verbatim (issue #183).** An
+ * optional path, relative to the config file's directory, to a file in
+ * rig-c's motion-spec shape whose `animations` are written into `motion.json`
+ * beside the idle on every `rig` and `build`, untouched. The loader owns what
+ * the merge needs and nothing else ({@link readAnimationsFrom}): the file
+ * exists and parses; it is an object holding `spec` ("rigc-motion/1") and an
+ * `animations` table of objects, nothing else that would be dropped; no
+ * animation is named `idle`; and no key in it is written twice. What an
+ * animation holds is rigc's to accept or refuse, at the rig stage's gate. The
+ * file is read where the config is read from a path ({@link loadConfig});
+ * {@link parseConfig}, which has no path to resolve against, checks only that
+ * the field is a non-empty string.
  */
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
 import { RIG_SKIN_CONSTRAINT_KEYS, type RigConstraint, type RigSkinConstraintKey } from 'rig-c/src/rig.ts';
 import { GRID, MAX_SIDE } from './contour.ts';
 import { type Problem, refuseIfAny } from './errors.ts';
@@ -473,6 +487,28 @@ export interface Motion {
   duration: number;
   tracks: Track[];
   blink?: Blink;
+  /**
+   * A file in rig-c's motion-spec shape whose `animations` are written beside
+   * the idle (issue #183), its path relative to the config file's directory.
+   * Absent, `motion.json` holds the idle alone.
+   */
+  animations_from?: string;
+}
+
+/** The motion-spec version a file `motion.animations_from` names must state: rig-c's, the one `motion.json` states. */
+export const ANIMATIONS_FROM_SPEC = 'rigc-motion/1';
+
+/**
+ * The animations `motion.animations_from` names, as read: `table` is the file's
+ * `animations` object itself, each animation untouched, in the order
+ * `JSON.parse` gives its keys (the file's order, except that a name that is an
+ * array index, `"0"` to `"4294967294"`, comes first, in numeric order — the
+ * JavaScript object's own key order, which no writer here can change).
+ */
+export interface AnimationsFrom {
+  /** The file, resolved against the config's directory. */
+  file: string;
+  table: Record<string, unknown>;
 }
 
 /**
@@ -687,7 +723,16 @@ function readConfigFile(path: string): Json {
 }
 
 export function loadConfig(path: string): CharacterConfig {
-  return parseConfig(readConfigFile(path));
+  return loadConfigAndAnimations(path).config;
+}
+
+/**
+ * The full loader with the file `motion.animations_from` names read beside it,
+ * relative to the config's directory: every problem in either is one refusal.
+ * `animations` is null when the config names no file.
+ */
+export function loadConfigAndAnimations(path: string): { config: CharacterConfig; animations: AnimationsFrom | null } {
+  return parseConfigFrom(readConfigFile(path), dirname(resolve(path)));
 }
 
 // ---------------------------------------------------------------------------
@@ -830,8 +875,16 @@ export function loadEarlyConfig(path: string, door: EarlyDoor): PaintConfig | Ea
   return parseEarlyConfig(raw, 'assemble');
 }
 
-/** Validate a parsed config. Every problem found is thrown at once, as one `PartsError`. */
+/**
+ * Validate a parsed config. Every problem found is thrown at once, as one
+ * `PartsError`. With no path to resolve against, `motion.animations_from` is
+ * checked as a non-empty string and its file is not read ({@link loadConfig} reads it).
+ */
 export function parseConfig(raw: Json): CharacterConfig {
+  return parseConfigFrom(raw, null).config;
+}
+
+function parseConfigFrom(raw: Json, base: string | null): { config: CharacterConfig; animations: AnimationsFrom | null } {
   const c = new Check();
   const required = topRequired('full');
   const top = c.object('config', raw, required, TOP_KEYS.filter((k) => !required.includes(k)));
@@ -847,8 +900,151 @@ export function parseConfig(raw: Json): CharacterConfig {
   if ('meshes' in t && 'regions' in t && 'assemble' in t) checkCoverage(c, parts, patches, t.meshes, t.regions);
   if ('motion' in t) checkMotion(c, t.motion, names.bones, names.chains, 'regions' in t ? t.regions : undefined);
   if ('constraints' in t) checkConstraints(c, t.constraints, names.bones, names.parents);
+  const from = isPlainObject(t.motion) ? t.motion.animations_from : undefined;
+  const animations = base !== null && typeof from === 'string' && from !== '' ? readAnimationsFrom(c, resolve(base, from)) : null;
   refuseIfAny(c.problems);
-  return raw as CharacterConfig;
+  return { config: raw as CharacterConfig, animations };
+}
+
+function isPlainObject(v: Json): v is Record<string, Json> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Read the file `motion.animations_from` names (issue #183) and vouch for what
+ * merging its animations beside the idle needs, every problem collected in `c`:
+ *
+ * - `CONFIG_FILE_PRESENT`: no such file, or a file that cannot be read.
+ * - `CONFIG_IS_JSON`: the text does not parse.
+ * - `CONFIG_FIELD_TYPE`: the file is not an object, its `spec` is not
+ *   "rigc-motion/1", its `animations` is not an object, or an animation in it
+ *   is not one. `CONFIG_KEY_KNOWN` / `CONFIG_FIELD_PRESENT`: a key besides
+ *   `spec` and `animations` (and the annotation and record doors), or one of
+ *   the two absent. rig-c's `easings`, `groups`, `setup`, `physics` and `mix`
+ *   are refused rather than dropped: `motion.json`'s own are this package's,
+ *   and a table read and not written would be a value lost without a word.
+ * - `CONFIG_ANIMATION_NAME_FREE`: an animation named `idle`, the one the
+ *   config's own `motion` writes.
+ * - `CONFIG_KEY_UNIQUE`: a key written twice in one object of the file.
+ *   `JSON.parse` keeps the last and drops the others silently, so the file's
+ *   text is read for it ({@link repeatedKeys}).
+ *
+ * Returns the animations when this file added no problem, else null.
+ */
+function readAnimationsFrom(c: Check, file: string): AnimationsFrom | null {
+  const field = 'config.motion.animations_from';
+  const shape = `a file in rig-c's motion-spec shape, {"spec": "${ANIMATIONS_FROM_SPEC}", "animations": {"<name>": {"duration": …, "tracks": [...]}}}, its path relative to the config's directory`;
+  if (!existsSync(file) || !statSync(file).isFile()) {
+    c.fail('CONFIG_FILE_PRESENT', field, `names ${file}, which is no such file; ${shape} is required`);
+    return null;
+  }
+  let text: string;
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch (err) {
+    c.fail('CONFIG_FILE_PRESENT', field, `names ${file}, which cannot be read: ${(err as Error).message}; ${shape} is required`);
+    return null;
+  }
+  let raw: Json;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    c.fail('CONFIG_IS_JSON', `${field} (${file})`, `does not parse as JSON: ${(err as Error).message}`);
+    return null;
+  }
+  const before = c.problems.length;
+  const at = `${field} (${file})`;
+  if (!isPlainObject(raw)) {
+    c.fail('CONFIG_FIELD_TYPE', at, `is ${show(raw)}; ${shape} is required`);
+    return null;
+  }
+  for (const r of repeatedKeys(text)) {
+    c.fail(
+      'CONFIG_KEY_UNIQUE',
+      `${at}${r.at === '' ? '' : `.${r.at}`}`,
+      `names "${r.key}" ${r.count === 2 ? 'twice' : `${r.count} times`}; each key once is required — JSON keeps only the last, so ${r.at === 'animations' ? 'every animation of that name but the last' : 'every value but the last'} would be dropped without a word`,
+    );
+  }
+  const o = c.object(at, raw, ['spec', 'animations'], []);
+  if (o !== null && 'spec' in o && o.spec !== ANIMATIONS_FROM_SPEC) {
+    c.fail('CONFIG_FIELD_TYPE', `${at}.spec`, `is ${show(o.spec)}; "${ANIMATIONS_FROM_SPEC}" is required, the motion-spec version motion.json states`);
+  }
+  if (o !== null && 'animations' in o) {
+    if (!isPlainObject(o.animations)) {
+      c.fail('CONFIG_FIELD_TYPE', `${at}.animations`, `is ${show(o.animations)}; a table keyed by animation name is required, {"<name>": {"duration": …, "tracks": [...]}}`);
+    } else {
+      for (const [name, anim] of Object.entries(o.animations)) {
+        if (name === 'idle') {
+          c.fail('CONFIG_ANIMATION_NAME_FREE', `${at}.animations.idle`, 'is the idle, which config.motion writes; an animation beside it needs another name');
+        } else if (!isPlainObject(anim)) {
+          c.fail('CONFIG_FIELD_TYPE', `${at}.animations.${name}`, `is ${show(anim)}; an animation object in rig-c's motion-spec shape is required ({"duration": …, "tracks": [...]}, and what else rigc reads)`);
+        }
+      }
+    }
+  }
+  if (c.problems.length > before || o === null) return null;
+  return { file, table: o.animations as Record<string, unknown> };
+}
+
+/**
+ * Every key an object in the JSON `text` names more than once, with the
+ * object's dotted path (`""` for the top level, `animations.smile.tracks[0]`
+ * below it) and how many times — what `JSON.parse` folds into its last value
+ * without a word. `text` must already parse; the walk is a reader of valid
+ * JSON only, and keys are compared after their escapes are decoded.
+ */
+export function repeatedKeys(text: string): Array<{ at: string; key: string; count: number }> {
+  const out: Array<{ at: string; key: string; count: number }> = [];
+  let i = 0;
+  const ws = (): void => {
+    while (i < text.length && ' \t\n\r'.includes(text[i])) i++;
+  };
+  const str = (): string => {
+    const start = i;
+    i++;
+    while (text[i] !== '"') i += text[i] === '\\' ? 2 : 1;
+    i++;
+    return JSON.parse(text.slice(start, i)) as string;
+  };
+  const value = (at: string): void => {
+    ws();
+    const ch = text[i];
+    if (ch === '{') {
+      i++;
+      const seen = new Map<string, number>();
+      ws();
+      if (text[i] === '}') {
+        i++;
+        return;
+      }
+      for (;;) {
+        ws();
+        const key = str();
+        seen.set(key, (seen.get(key) ?? 0) + 1);
+        ws();
+        i++; // the colon
+        value(at === '' ? key : `${at}.${key}`);
+        ws();
+        if (text[i++] === '}') break;
+      }
+      for (const [key, count] of seen) if (count > 1) out.push({ at, key, count });
+    } else if (ch === '[') {
+      i++;
+      ws();
+      if (text[i] === ']') {
+        i++;
+        return;
+      }
+      for (let k = 0; ; k++) {
+        value(`${at}[${k}]`);
+        ws();
+        if (text[i++] === ']') break;
+      }
+    } else if (ch === '"') str();
+    else while (i < text.length && !',]} \t\n\r'.includes(text[i])) i++;
+  };
+  value('');
+  return out;
 }
 
 /** The four sections `propose` drafts and a config carries: what a skeleton comparison reads of either. */
@@ -1499,9 +1695,10 @@ const BLINK_GROUP_EMPTY: Readonly<Record<'eyes' | 'brows', string>> = {
 };
 
 function checkMotion(c: Check, v: Json, bones: Set<string>, chains: Map<string, number>, regions: Json): void {
-  const m = c.object('config.motion', v, ['duration', 'tracks'], ['blink']);
+  const m = c.object('config.motion', v, ['duration', 'tracks'], ['blink', 'animations_from']);
   if (m === null) return;
   const p = 'config.motion';
+  if ('animations_from' in m) c.string(`${p}.animations_from`, m.animations_from);
   // Every bone property the idle will key, and the tracks that key it, in the
   // order idleMotion writes them: single and chain tracks, then the eyes
   // group, then the brows group.

package/src/motion.ts

@@ -130,6 +130,18 @@ export interface MotionSpec {
   animations: { idle: { duration: number; loop: true; note: string; tracks: MotionTrack[] } };
 }
 
+/**
+ * The motion `motion.json` holds: the idle, and after it every animation the
+ * file `config.motion.animations_from` names, as read (issue #183) — nothing
+ * added, nothing re-keyed, nothing judged; each is rigc's to accept at the
+ * gate. With none, `motion` itself, so a config that names no file writes the
+ * bytes it wrote before the field existed.
+ */
+export function withAnimations(motion: MotionSpec, extra: Readonly<Record<string, unknown>> | null): MotionSpec | Record<string, unknown> {
+  if (extra === null) return motion;
+  return { ...motion, animations: { ...motion.animations, ...extra } };
+}
+
 /** One sine channel over an idle of `duration` seconds. */
 export function sineTrack(bone: string, property: string, amp: number, period: number, phase: number, base: number, duration: number): MotionTrack {
   const n = Math.round((duration / period) * KEYS_PER_PERIOD);