@rig-c/core 2.60.0 → 2.61.0

package/README.md

@@ -433,7 +433,10 @@ frames. It draws with rigc's own rasteriser (the one `check` measures with), so
 it needs no browser and no network, and the `frames.json` it leaves beside the
 directories makes the result a frame set like any other — the world box every
 frame is a picture of. `--animation <name>` narrows it to one, `--fps` and
-`--max` change the rate and the frame size.
+`--max` change the rate and the frame size. A set drawn at any rate but the
+default is written to `<anim>@<fps>fps/` rather than `<anim>/`, so two rates sit
+side by side: `--fps 24` writes `<anim>@24fps/`, and the default 12 writes
+`<anim>/`. Each set's summary line ends with the directory it wrote.
 
 > 🚨 **`--skin <name>` if your rig has more than one.** With no `--skin` no skin
 > is set at all, so every slot resolves through the **default** skin alone — and
@@ -603,7 +606,7 @@ commands take it and what its default is.
 | `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. a skeleton that declares no stage is carried as declaring none, `--stage x,y,w,h` adds a box to one — and is refused, rather than ignored, beside one that declares a box — and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all |
 | `split --rig … --motion … --slot <name> --out <dir>` | the answer to a mesh refused because its triangles are **several pieces that share no vertex** — two legs after the triangles bridging them were deleted. It reads the two specs and writes them back into an absent or empty `--out` with one mesh per piece: piece 1 stays in the slot, piece k gets a new slot `<slot>_<k>` after it, each with the original's uvs and weights unchanged, its triangles renumbered outline first where the hull rule needs it, and every deform key re-sliced to the new indices — plus `split.json`, where every original vertex and triangle went. One piece is said so and nothing is written; what it cannot carry is refused by name ([AUTHORING §3.4.11](docs/AUTHORING.md)) |
 | `explain --rig … --motion …` | the compiled rig as a table — every bone with its resolved parent, the slots in draw order, every timeline key by key. Writes nothing. What to reach for when a rig compiles and still looks wrong |
-| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid. `--folds` adds a `folds.json` per set and prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count and which triangles, their world box and their setup-pose area. `--pass-through <cloth>:<leg>` adds a `pass-through.json` per set and prints the frames where a cloth drawn over a leg has its side inside the leg's drawn outline, with the depth and the world box — a reading, not a gate. `--seam <slot>:<slot>` adds a `seam.json` per set and prints, per pair, the frames where two slots that meet open background inside the joint (a gap) or show the overlap band of one past the other (a ghost), with the worst frame's cell count and world box — a reading, not a gate; the exit status never moves. `--angle-range <bone>:<relative-to>` prints how far one bone turns against another over each set: the lowest and highest angle and the frames they fall on — a reading, not a gate. `--viewport <x,y,w,h>` or `--viewport-from <frames.json>` draws over a given box instead of a fitted one, so two builds land on one pixel grid; a slot that reaches past it is named by set and frame, and `frames.json` records it. `--environment <schedule.json>` draws the rig under the wind and gravity its physics answers, in time — the same frames on the core and on spine-core; an inspection of the response the rig states, not a scene |
+| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`, one directory per set: `<anim>@<fps>fps/` rather than `<anim>/` at any rate but the default — `--fps 24` writes `<anim>@24fps/`, and the default 12 writes `<anim>/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid. `--folds` adds a `folds.json` per set and prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count and which triangles, their world box and their setup-pose area. `--pass-through <cloth>:<leg>` adds a `pass-through.json` per set and prints the frames where a cloth drawn over a leg has its side inside the leg's drawn outline, with the depth and the world box — a reading, not a gate. `--seam <slot>:<slot>` adds a `seam.json` per set and prints, per pair, the frames where two slots that meet open background inside the joint (a gap) or show the overlap band of one past the other (a ghost), with the worst frame's cell count and world box — a reading, not a gate; the exit status never moves. `--angle-range <bone>:<relative-to>` prints how far one bone turns against another over each set: the lowest and highest angle and the frames they fall on — a reading, not a gate. `--viewport <x,y,w,h>` or `--viewport-from <frames.json>` draws over a given box instead of a fitted one, so two builds land on one pixel grid; a slot that reaches past it is named by set and frame, and `frames.json` records it. `--environment <schedule.json>` draws the rig under the wind and gravity its physics answers, in time — the same frames on the core and on spine-core; an inspection of the response the rig states, not a scene |
 | `preview --candidate <dir>` | one self-contained `.html` that plays it, headed by the line `validate <dir>` prints for it and the rigc version — a refused candidate is still previewed, and its header says so in the gate's words. Repeat `--candidate` for one page with a pane per candidate, in the order given; a green `build` ends by naming this command for its own `--out` |
 | `vote --candidate a --candidate b` | one `.html` that asks a human which; `vote --record <file>` checks the answer into `votes.jsonl` |
 | `pose --images <dir> --frame <png>` | reads part placements **out of** a picture |

package/docs/AUTHORING.md

@@ -1242,7 +1242,11 @@ bun cli.ts pose     --images path/to/parts --frame poseA.png [--out pose.json]
   gate can know you did not mean them. `render` writes
   `render/<animation>/f0000.png…` with a `contact.png` grid of **every** frame
   beside them (open that one first — spacing is a comparison across frames) and a
-  `frames.json` sidecar naming the world box they are pictures of. `contact.png`
+  `frames.json` sidecar naming the world box they are pictures of. It also says
+  whether the physics ran: under each set's line, `physics: N constraint(s)
+  stepped at <fps> fps`, and the same two figures on that set in `frames.json` —
+  or, once, `physics: none in this rig` for a rig that declares no physics
+  constraint (§8.4). `contact.png`
   is for spacing across frames; a defect is read on **one frame at full size**,
   because a tile is too small to say which part a pixel belongs to. When a frame
   looks wrong, render it again with `--hide <slot>` — the **largest attachment**
@@ -6843,6 +6847,14 @@ it had nothing to step (`nanStepping=skipped`). What it does not see is a skin o
 than the default, which A10 does not pose. The sentence, and where to look for the
 number, is under *nothing to draw* in §3.4.
 
+⌨️ **An invocation missing a flag is one line, before any of these.** `build`,
+`explain` and `validate` given a cut spelled out with `--rig`, `--motion` or
+`--out` absent print `rigc: <command> needs --<flag> <value> (or --cut <name>
+--cuts <cuts.json>)` on stderr and exit 2 — the line alone, with no command
+catalogue under it. An input flag that names a **directory** is a compile error
+with a remedy in it: `CE_COMPILE_JSON_READ_FAILED` says what the flag wants and
+names the one file there that reads as it (§5.1.2). It is never read as that file.
+
 ### 5.1 Compile errors — before the gate
 
 A `CompileError` names the object and the field, and nothing is written. Its line
@@ -6919,7 +6931,7 @@ retain the minimal inputs and report that code rather than inventing author data
 | <a id="CE_COMPILE_RGBA_CHANNEL_COUNT"></a>`CE_COMPILE_RGBA_CHANNEL_COUNT` | “rgba value needs 4 channels, got &lt;value&gt;” | Supply four rgba channels. |
 | <a id="CE_COMPILE_RGBA2_CHANNEL_COUNT"></a>`CE_COMPILE_RGBA2_CHANNEL_COUNT` | “rgba2 value needs 7 channels, got &lt;value&gt;” | Supply seven rgba2 channels. |
 | <a id="CE_COMPILE_COLOUR_CHANNEL_COUNT"></a>`CE_COMPILE_COLOUR_CHANNEL_COUNT` | “&lt;value&gt; value needs &lt;value&gt; channel[ / s], got &lt;value&gt;” | Supply the channel count named for this colour shape. |
-| <a id="CE_COMPILE_JSON_READ_FAILED"></a>`CE_COMPILE_JSON_READ_FAILED` | “cannot read &lt;value&gt;: &lt;value&gt;”<br>Also: “&lt;value&gt; (line &lt;value&gt;, column &lt;value&gt;)” | Fix the named JSON file's path, permissions or JSON syntax. |
+| <a id="CE_COMPILE_JSON_READ_FAILED"></a>`CE_COMPILE_JSON_READ_FAILED` | “cannot read &lt;value&gt;: &lt;value&gt;”<br>Also: “&lt;value&gt; (line &lt;value&gt;, column &lt;value&gt;)”<br>Also, when `--rig`, `--motion` or `--manifest` names a directory: “&lt;value&gt; names a directory; it wants &lt;value&gt; — &lt;value&gt; exists there” · “… — &lt;value&gt; holds no .json file” · “… — &lt;value&gt; holds &lt;value&gt; .json file(s) and none reads as one: &lt;value&gt;” · “… — &lt;value&gt; .json files in &lt;value&gt; read as one, so name it: &lt;value&gt;”, a list cut at eight names with “, … &lt;value&gt; in all” | Fix the named JSON file's path, permissions or JSON syntax. For a directory, name the file the line names — the one `.json` there that reads as that input (a rig spec through the rig spec's parser, a motion spec through the motion spec's; for `--manifest`, any `.json`) — or pick one of the files it lists. A directory is never read as its file: rigc compiles what it was given. |
 | <a id="CE_COMPILE_IMAGE_MISSING"></a>`CE_COMPILE_IMAGE_MISSING` | “image "&lt;value&gt;" is not on disk at &lt;value&gt;”<br>Also: “&lt;value&gt;.png” | Supply the PNG at the named images path or correct the image name. |
 | <a id="CE_COMPILE_IMAGE_PNG_INVALID"></a>`CE_COMPILE_IMAGE_PNG_INVALID` | “&lt;value&gt; is &lt;value&gt;, not a PNG: its first &lt;value&gt; byte(s) are &lt;value&gt;, where a PNG's first 8 are &lt;value&gt;&lt;value&gt;. rigc reads PNG and nothing else — its page-size and alpha readers, its renderer and its region lift all decode PNG, and it links no decoder for any other format — so nothing in this file was measured. Re-export it as PNG”<br>“&lt;value&gt; is a PNG whose IHDR chunk declares &lt;value&gt; byte(s) of data, where the format's is 13”<br>“&lt;value&gt; is a PNG whose IHDR chunk states its size as &lt;value&gt;x&lt;value&gt;: &lt;value&gt; 0, where the format requires each dimension to be at least 1, so the file describes no texel and nothing in it can be measured or drawn. Re-export it”<br>“&lt;value&gt; is a PNG whose first chunk is &lt;value&gt; rather than the IHDR the format requires first”<br>“&lt;value&gt; is a truncated PNG: it is &lt;value&gt; byte(s) long and &lt;value&gt;, so no reader can decode it. Re-export or re-copy the file whole”<br>“&lt;value&gt; is a truncated PNG: it is &lt;value&gt; byte(s) long and ends &lt;value&gt; byte(s) into the 8-byte PNG signature, so no reader can decode it. Re-export or re-copy the file whole”<br>“&lt;value&gt; is a truncated PNG: it is &lt;value&gt; byte(s) long and ends after the signature with no IEND chunk, so no reader can decode it. Re-export or re-copy the file whole”<br>“&lt;value&gt; is a truncated PNG: it is &lt;value&gt; byte(s) long and its &lt;value&gt; chunk at byte &lt;value&gt; declares &lt;value&gt; byte(s) of data, which with its CRC runs to byte &lt;value&gt;, so no reader can decode it. Re-export or re-copy the file whole”<br>“&lt;value&gt; is a truncated PNG: it is &lt;value&gt; byte(s) long and {ends after &lt;value&gt; with no IEND chunk / ends &lt;value&gt; byte(s) into the header of the chunk after &lt;value&gt;}, so no reader can decode it. Re-export or re-copy the file whole”<br>“&lt;value&gt; is empty (0 bytes), and a PNG's first 8 bytes are &lt;value&gt;”<br>“[; its name ends in .png, and it is the bytes that decide what a file is / ]”<br>“[its width and its height are / [its width is / its height is]]”<br>“a &lt;value&gt; image”<br>“a WebP image (a RIFF/WEBP container whose first chunk is &lt;value&gt;)”<br>“image "&lt;value&gt;": &lt;value&gt;”<br>“in no image format rigc recognises by its signature (it names &lt;value&gt; when it meets them)”<br>Here the values named in the message include: “KTX2”, “GIF”, “JPEG”. | Supply a readable PNG with the required header and dimensions at the named path. |
 | <a id="CE_COMPILE_ATLAS_INPUT_MISSING"></a>`CE_COMPILE_ATLAS_INPUT_MISSING` | “--atlas-in names &lt;value&gt;, which is not on disk” | Correct --atlas-in or supply the atlas file at that path. |
@@ -8496,6 +8508,34 @@ from its own frame and no earlier (`RE02`); and plants on the core the readings
 mapping rejects — the schedule ignored, its y read up, each change a frame late or
 early — each red against spine-core (`RE03`).
 
+**Whether the physics ran.** Every render — with this flag or without — says, under
+each set's line, how many physics constraints the poser stepped on at least one of
+its frames, and at what rate:
+
+```text
+  ..    idle             25 frame(s), 2.000s + contact.png -> render/idle
+  ..    physics: 3 constraint(s) stepped at 12 fps
+```
+
+and `frames.json` carries the same two figures on that set, `"physics": { "stepped":
+3, "fps": 12 }`. The rate is the set's own: one physics update a frame. The count is
+read off the posed state, not off the declaration: a constraint counts when, after
+a step that moved the skeleton's clock, its own clock reads the skeleton's — which
+the physics update sets and every way of not running leaves behind. So a constraint
+that is inactive on every frame, or at a mix of 0, is not counted, and the line names
+it: `physics: 0 constraint(s) stepped at 12 fps — 1 of the 1 declared took none:
+"iris_settle" (inactive, or a mix of 0, on every frame)`; a set of one pose — an
+animation of no length, or the setup pose of a skeleton with none — takes no step
+and says so. A rig that declares no physics constraint prints `physics: none in this
+rig — it declares no physics constraint, so no frame steps one` once, before the
+sets, and its `frames.json` carries no `physics` field, as every frame set written
+before the field existed carries none. This is what tells a reading — a fold count
+from `--folds`, say (§8.3) — taken with the physics from one taken without. Both
+posers read the same constraints on every frame, and `cli.ts`, `cli.ts --poser
+spine` and `cli_core.ts` write the same files (`PH01`, `PH02`); the step removed —
+on the core, or spine-core's `PhysicsConstraint.update` made a no-op — reads 0
+(`PH03`), and a constraint at mix 0 is named (`PH04`).
+
 **The files.** `frames.json` and each `geometry.json` record the schedule as
 `environment`, its steps as read, `t`, `wind`, `gravity` in that order. The
 framing reads it too: a gust can carry a coat past the box a still rig fills, so

package/docs/INGEST.md

@@ -191,6 +191,7 @@ rigc render
   ..    atlas    …/examples/spineboy/export/spineboy.atlas
   ..    poser    spine-core — no skeleton.model.json beside …/examples/spineboy/export/spineboy-pro.json — a Spine export, not a rigc build
   ..    200x186px at 8 fps, 1 set(s) -> …/render/sb
+  ..    physics: none in this rig — it declares no physics constraint, so no frame steps one
   ..    walk             9 frame(s), 1.000s + contact.png -> …/render/sb/walk@8fps
 rigc: wrote …/render/sb/frames.json
 ```

package/docs/MOTION.md

@@ -1067,6 +1067,7 @@ rigc render --candidate spine --fps 24 --max 200
 
 ```
   ..    134x200px at 24 fps, 1 set(s) -> …/semaphore/render
+  ..    physics: none in this rig — it declares no physics constraint, so no frame steps one
   ..    raise            14 frame(s), 0.542s + contact.png -> …/semaphore/render/raise@24fps
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.60.0",
+  "version": "2.61.0",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/cli/core_commands.ts

@@ -736,6 +736,8 @@ export function cmdRender(flags: Record<string, string>): void {
   const only = readAnimationFlag(flags, [...facts.animations]);
   const skin = readSkinFlag(flags, [...facts.skins]);
   const subset = readSlotSubsetFlags(flags, facts, skin);
+  // The physics constraints the skeleton declares, off the Spine file both posers read (issue #1467).
+  const physicsDeclared = environmentResponse(skeletonText).declared;
   const passPairs = readPassThroughFlag(passThrough, facts);
   const seamPairs = readSeamFlag(seam, facts);
   // The angle reading (issue #1414) reads bones, which a subset of the drawn slots does not change, so it takes --slot/--hide.
@@ -810,7 +812,14 @@ export function cmdRender(flags: Record<string, string>): void {
     // The bones ride along for --geometry and --angle-range, the whole attachments for --geometry and the two readings off them.
     const wantsBones = geometry || anglePairs !== undefined;
     const wantsGeometry = geometry || folds || passPairs !== undefined || seamPairs !== undefined;
-    const sampling = !wantsBones && !wantsGeometry ? pose : { ...pose, ...(wantsBones ? { bones: true } : {}), ...(wantsGeometry ? { geometry: true } : {}) };
+    // The physics constraints each frame's step stepped ride along whenever the rig declares one (issue #1467): the
+    // `physics:` line and frames.json's `physics` field are read off them.
+    const sampling = {
+      ...pose,
+      ...(wantsBones ? { bones: true } : {}),
+      ...(wantsGeometry ? { geometry: true } : {}),
+      ...(physicsDeclared.length > 0 ? { physics: true } : {}),
+    };
     const sampled: Map<string, Frame[]> =
       only === undefined
         ? sampleAll(poser, fps, sampling)
@@ -916,6 +925,8 @@ export function cmdRender(flags: Record<string, string>): void {
     );
   }
   console.log(`  ..    ${viewport.width}x${viewport.height}px at ${fps} fps, ${sampled.size} set(s) -> ${outRoot}`);
+  // Whether physics ran (issue #1467): said once for a rig with nothing to step, and per set below for one with.
+  if (physicsDeclared.length === 0) console.log(`  ..    ${PHYSICS_NONE_LINE}`);
   if (!facts.declaresStage) console.log(`  ..    ${STAGELESS_FRAMING.render}`);
   // A given box (issue #1414): said with the box it replaced, and every slot it leaves part of out, by set and frame.
   const outside = given === undefined ? [] : outsideViewport(sampled, viewport);
@@ -959,6 +970,7 @@ export function cmdRender(flags: Record<string, string>): void {
     const seamReading = seamReadings.get(name);
     if (seamReading !== undefined) writeFileSync(join(dir, SEAM_FILE), seamText(seamReading));
     const duration = frames[frames.length - 1].time;
+    const physics = physicsDeclared.length === 0 ? undefined : physicsSteppedOf(frames, fps);
     sets.push({
       dir: dirName,
       animation: name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name,
@@ -967,6 +979,7 @@ export function cmdRender(flags: Record<string, string>): void {
       written: frames.length,
       stride: 1,
       duration,
+      ...(physics === undefined ? {} : { physics: { stepped: physics.stepped.length, fps } }),
     });
     const how = frames.length === 1 ? 'a single pose' : `${duration.toFixed(3)}s`;
     const folding = foldReading?.meshes.filter((m) => m.worst !== null).length ?? 0;
@@ -977,6 +990,7 @@ export function cmdRender(flags: Record<string, string>): void {
     const seamNote = seamReading === undefined ? '' : ` + ${SEAM_FILE} (${opening} of ${seamReading.pairs.length} pair(s) open)`;
     const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}${passNote}${seamNote}`;
     console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${extras} -> ${dir}`);
+    if (physics !== undefined) console.log(`  ..    ${physicsLine(physics.stepped, physicsDeclared, fps, frames.length)}`);
     for (const mesh of foldReading?.meshes ?? []) {
       const key = `${mesh.slot}\u0000${mesh.attachment}`;
       const fault = faultsSaid.has(key) ? null : setupFaultLine(mesh);
@@ -1022,6 +1036,28 @@ export function cmdRender(flags: Record<string, string>): void {
   console.log(`rigc: wrote ${join(outRoot, FRAMES_SIDECAR)}`);
 }
 
+/** `render`'s line for a rig that declares no physics constraint (issue #1467): nothing was stepped because nothing could be. */
+export const PHYSICS_NONE_LINE = 'physics: none in this rig — it declares no physics constraint, so no frame steps one';
+
+/** The physics constraints any frame of a set stepped (issue #1467), by name in code-unit order. */
+export function physicsSteppedOf(frames: readonly Frame[], fps: number): { stepped: string[]; fps: number } {
+  const names = new Set<string>();
+  for (const frame of frames) for (const name of frame.physics ?? []) names.add(name);
+  return { stepped: [...names].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)), fps };
+}
+
+/**
+ * `render`'s `physics:` line for one set (issue #1467): how many constraints were stepped at the set's rate, and — when
+ * fewer than the rig declares — the ones that took no step, by name, with why a constraint takes none.
+ */
+export function physicsLine(stepped: readonly string[], declared: readonly string[], fps: number, frames: number): string {
+  const head = `physics: ${stepped.length} constraint(s) stepped at ${fps} fps`;
+  const idle = declared.filter((name) => !stepped.includes(name));
+  if (idle.length === 0) return head;
+  const why = frames === 1 ? 'a single pose takes no step' : 'inactive, or a mix of 0, on every frame';
+  return `${head} — ${idle.length} of the ${declared.length} declared took none: ${idle.map((n) => JSON.stringify(n)).join(', ')} (${why})`;
+}
+
 /** Where `inspect` writes when `--out` is not given, and the name it takes inside a directory `--out` names. */
 export const DEFAULT_INSPECT_OUT = 'inspect.png';
 
@@ -1351,7 +1387,7 @@ export function cmdExplain(flags: Record<string, string>): void {
   const leverFold = flags['lever-fold'] === undefined ? null : Number(flags['lever-fold']);
   const leverWhy = leverFold === null ? null : leverFractionWhy(leverFold);
   if (leverWhy !== null) throw new UsageError(`--lever-fold ${JSON.stringify(flags['lever-fold'])}: ${leverWhy}`);
-  const { label, opts } = resolveCut(flags);
+  const { label, opts } = resolveCut(flags, 'explain');
   console.log(`rigc explain ${label}`);
   // See the identical pair of lines in `cmdBuild` for why both paths are named
   // here rather than only the one the header's `label` happens to carry.

package/src/cli/shared.ts

@@ -94,6 +94,19 @@ export type CutTable = Record<string, CutEntry>;
 
 export class UsageError extends Error {}
 
+/**
+ * A usage error that is one required flag missing from a spelled-out cut —
+ * printed as its one line and exit 2, without the usage block under it (issue
+ * #1466). The catalogue under `--out is required` buried the only line that
+ * said what to add, which is `PoseError`'s reason for printing alone. Still a
+ * `UsageError`, so every reader that asks whether an invocation was refused
+ * reads it as one.
+ */
+export class MissingFlagError extends UsageError {}
+
+/** The `<value>` each flag of a spelled-out cut takes, for the line that names a missing one. */
+const CUT_FLAG_VALUES = { rig: '<rig.json>', motion: '<motion.json>', out: '<dir>' } as const;
+
 /**
  * `explain` refusing a pair it cannot pose — a usage error in kind, printed
  * without the usage block for `PoseError`'s and `IngestError`'s reason: the
@@ -264,7 +277,7 @@ function entryToOptions(dir: string, name: string, entry: CutEntry): CompileOpti
  * Resolve the cut a command was pointed at, either spelled out on the command
  * line or looked up by name in a cuts.json.
  */
-export function resolveCut(flags: Record<string, string>): { label: string; opts: CompileOptions } {
+export function resolveCut(flags: Record<string, string>, command: 'build' | 'explain' | 'validate'): { label: string; opts: CompileOptions } {
   const explicit =
     flags.rig !== undefined || flags.manifest !== undefined || flags.motion !== undefined || flags.out !== undefined;
   if (explicit) {
@@ -272,7 +285,7 @@ export function resolveCut(flags: Record<string, string>): { label: string; opts
       throw new UsageError('--rig/--motion/--out and --cut/--cuts are two ways to say the same thing; pick one');
     }
     for (const key of ['rig', 'motion', 'out'] as const) {
-      if (flags[key] === undefined) throw new UsageError(`--${key} is required when the cut is spelled out`);
+      if (flags[key] === undefined) throw new MissingFlagError(`${command} needs --${key} ${CUT_FLAG_VALUES[key]} (or --cut <name> --cuts <cuts.json>)`);
     }
     const opts: CompileOptions = {
       rigPath: resolve(flags.rig),
@@ -2291,7 +2304,7 @@ function pageRectangle(region: AtlasRegion): string {
  * alone (`./core_commands.ts`). Moved here unchanged from `cmdBuild`.
  */
 export function readBuildInvocation(flags: Record<string, string>): { label: string; opts: CompileOptions; profile: AssertionProfile; packing: boolean } {
-  const { label, opts } = resolveCut(flags);
+  const { label, opts } = resolveCut(flags, 'build');
   const profile = readProfile(flags);
   const packing = flags.pack !== undefined;
   // Two combinations are refused rather than silently resolved, because in each
@@ -3001,6 +3014,10 @@ export function runCli(entry: CliEntry, argv: readonly string[]): void {
  * (`CliEntry.refusals`). Anything else is not a refusal and is thrown on.
  */
 function refuse(err: unknown, command: string | undefined, USAGE: string, entry: CliEntry): never {
+  if (err instanceof MissingFlagError) {
+    console.error(`rigc: ${err.message}`);
+    process.exit(2);
+  }
   if (err instanceof UsageError) {
     console.error(`rigc: ${err.message}\n\n${USAGE}`);
     process.exit(2);

package/src/cli/spine_commands.ts

@@ -76,7 +76,7 @@ export function cmdValidate(flags: Record<string, string>, positional: string[])
   // a directory alone cannot supply — and the report says which it had.
   const named = flags.cut !== undefined || flags.rig !== undefined;
   const profile = readProfile(flags);
-  const derivedOpts = named ? resolveCut(flags).opts : null;
+  const derivedOpts = named ? resolveCut(flags, 'validate').opts : null;
   // Both files there before the first line, from the one statement of a build (issue #1046): a directory without them
   // read the skeleton unguarded and died on an ENOENT and a stack.
   const { skeletonPath, atlasPath } = spinePairOf(resolveBuild(derivedOpts ? derivedOpts.outDir : (positional[0] ?? '.'), flags.atlas));

package/src/compile.ts

@@ -18,7 +18,7 @@
  * the two emits byte for byte (assertion A18).
  */
 import { basename, dirname, join, relative, resolve } from 'node:path';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { readPngHeader, readPngInfo } from './png.ts';
 import {
   DEPTH_TONE_IDENTITY,
@@ -1649,8 +1649,62 @@ function easingCurve(
 // inputs
 // ---------------------------------------------------------------------------
 
-function readJson<T>(path: string): T {
+/**
+ * Which input a JSON path was given as, for the refusal a directory gets: the
+ * flag that named it, the file it wants, and whether a file's contents read as
+ * one (`null` where no parser exists here — the manifest is cast, not parsed).
+ */
+interface JsonInputRole {
+  flag: '--rig' | '--motion' | '--manifest';
+  wants: string;
+  reads: ((raw: unknown, where: string) => unknown) | null;
+}
+
+const RIG_INPUT: JsonInputRole = { flag: '--rig', wants: 'the rig spec file', reads: parseRigSpec };
+const MOTION_INPUT: JsonInputRole = { flag: '--motion', wants: 'the motion spec file', reads: parseMotionSpec };
+const MANIFEST_INPUT: JsonInputRole = { flag: '--manifest', wants: 'the cut manifest file', reads: null };
+
+/** The most `.json` names a directory refusal lists before it says how many there are. */
+const LISTED_JSON_NAMES = 8;
+
+/**
+ * The refusal for an input flag that names a directory (issue #1466): what the
+ * flag wants, and what the directory holds — the one file there that reads as
+ * that input, named by its path, or every `.json` there when that is not
+ * exactly one. Nothing is accepted on the strength of it: the caller is told
+ * the path, and the compile still reads only what it was given. The names are
+ * sorted, so the sentence is the same on every machine.
+ */
+function directoryInputRefusal(dir: string, role: JsonInputRole): string {
+  const head = `${role.flag} names a directory; it wants ${role.wants} —`;
+  const names = readdirSync(dir)
+    .filter((name) => name.endsWith('.json') && statSync(join(dir, name)).isFile())
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  if (names.length === 0) return `${head} ${dir} holds no .json file`;
+  const reading = names.filter((name) => {
+    if (role.reads === null) return true;
+    const file = join(dir, name);
+    try {
+      role.reads(parseJsonWithPosition(readFileSync(file, 'utf8')), file);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  if (reading.length === 1) return `${head} ${join(dir, reading[0])} exists there`;
+  const listed = (list: string[]): string =>
+    list.slice(0, LISTED_JSON_NAMES).join(', ') + (list.length > LISTED_JSON_NAMES ? `, … ${list.length} in all` : '');
+  if (reading.length === 0) {
+    return `${head} ${dir} holds ${names.length} .json file(s) and none reads as one: ${listed(names)}`;
+  }
+  return `${head} ${reading.length} .json files in ${dir} read as one, so name it: ${listed(reading)}`;
+}
+
+function readJson<T>(path: string, role: JsonInputRole): T {
   let text: string;
+  if (existsSync(path) && statSync(path).isDirectory()) {
+    throw new CompileError(directoryInputRefusal(path, role), 'CE_COMPILE_JSON_READ_FAILED');
+  }
   try {
     text = readFileSync(path, 'utf8');
   } catch (err) {
@@ -2309,11 +2363,11 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   const manifestPath = opts.manifestPath === undefined ? null : resolve(opts.manifestPath);
   const manifestDir = manifestPath === null ? null : dirname(manifestPath);
 
-  const rig = parseRigSpec(readJson<unknown>(rigPath), rigPath);
+  const rig = parseRigSpec(readJson<unknown>(rigPath, RIG_INPUT), rigPath);
   // Parsed, not cast, since issue #307 — `src/motion.ts` states what it proves
   // and which refusals it deliberately leaves in this file.
-  const motion = parseMotionSpec(readJson<unknown>(motionPath), motionPath);
-  const manifest = manifestPath === null ? null : readJson<FaceManifest>(manifestPath);
+  const motion = parseMotionSpec(readJson<unknown>(motionPath, MOTION_INPUT), motionPath);
+  const manifest = manifestPath === null ? null : readJson<FaceManifest>(manifestPath, MANIFEST_INPUT);
   // The manifest is the record of what was measured, and its numbers become
   // bone positions and the stage: a `crop.h` of 1e309 built as `"height": null`
   // before issue #881. The rig spec's walk is `parseRigSpec`'s; this is the

package/src/render.ts

@@ -549,9 +549,25 @@ function spinePosed(skeleton: Skeleton): Posed {
     pieces: (draw) => drawPieces(skeleton, draw),
     bones: () => boneSnapshots(skeleton),
     attachments: () => attachmentsOf(skeleton),
+    physics: () => steppedPhysicsOf(skeleton),
   };
 }
 
+/**
+ * `Posed.physics` on spine-core (issue #1467): every physics constraint whose
+ * `lastTime` reads the skeleton's `time` after a step that moved it — which
+ * `PhysicsConstraint.update` sets under `Physics.update` and `Physics.reset`,
+ * and which an inactive constraint, a mix of 0 or `Physics.none` leaves where
+ * it was. The setup pose and frame 0 sit at time 0 and step none.
+ */
+function steppedPhysicsOf(skeleton: Skeleton): string[] {
+  if (!(skeleton.time > 0)) return [];
+  return skeleton.physics
+    .filter((c) => c.lastTime === skeleton.time)
+    .map((c) => c.data.name)
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
 /**
  * A fresh skeleton under `skin`, stepped into its setup pose — the one recipe
  * `sampleSetupPose` and the geometry export's `rest` table both pose from, so

package/src/render_core.ts

@@ -102,6 +102,7 @@ import { clipThrough, type ClipShape, type ShapeClipper } from './core/clipping.
 import { activeBones, CoreInputError, readModel, sourceOfDoc, underNoSkin, underSkin, type CompiledDocument, type CoreSlotRow } from './core/index.ts';
 import { PHYSICS_CLOCK_LEAD, physicsClockStep, poseRawAnimationEach, poseRawSetup, type RawDrawn, type RawPose, type StepEnvironment } from './core/raw.ts';
 import type { TimelinePlant } from './core/animation.ts';
+import { stepPhysics, type PhysicsStepper } from './core/constraints_physics.ts';
 import { CORE_DEFAULT_SKIN, lookupSkins } from './core/skins.ts';
 import { documentPageLookup, drawnRegions, meshPageUvs, readUvSequences, regionPageUvs, type DrawnRegion, type UvRegion, type UvSource } from './core/uvs.ts';
 import { regionCorners, worldVertices } from './core/vertices.ts';
@@ -378,10 +379,14 @@ export const CORE_RAW_WALK: CoreRawWalk = (doc, animation, steps, plant, visit,
  */
 export { PHYSICS_CLOCK_LEAD, physicsClockStep };
 
-/** What a suite passes `corePoser` in place of the poser's own parts — `PieceArrays` (`RC43`) and the raw walk (`RC44`). */
+/**
+ * What a suite passes `corePoser` in place of the poser's own parts — `PieceArrays` (`RC43`), the raw walk (`RC44`), and
+ * the physics step the walk runs (issue #1467: a step that does nothing has to read 0 on the render's `physics:` line).
+ */
 export interface CorePoserPlants {
   arrays?: () => PieceArrays;
   walk?: CoreRawWalk;
+  physicsStep?: PhysicsStepper;
 }
 
 /**
@@ -457,7 +462,7 @@ function clipCover(pose: RawPose, active: ReadonlySet<string>): Map<string, Clip
 }
 
 /** One posed moment of the core, read through the seam's `Posed`. */
-function corePosed(input: CoreInput, pose: RawPose, through: ShapeClipper): Posed {
+function corePosed(input: CoreInput, pose: RawPose, through: ShapeClipper, stepped: readonly string[]): Posed {
   const slotRows = new Map<string, CoreSlotRow>(pose.slots.map((row) => [row[0], row]));
   let regions: Map<string, DrawnRegion> | null = null;
   const regionsOf = (): Map<string, DrawnRegion> => {
@@ -501,6 +506,7 @@ function corePosed(input: CoreInput, pose: RawPose, through: ShapeClipper): Pose
     },
     attachments: (): AttachmentPose[] =>
       pose.drawn.map((d) => ({ slot: d.slot, attachment: d.attachment, vertices: [...d.vertices], color: tintOf(d) })),
+    physics: (): string[] => [...stepped],
   };
 }
 
@@ -752,7 +758,7 @@ export function corePoser(
     subset: (opts, skin) => subsetOver(roster, opts, skin),
     setup: (skin) => {
       const input = inputOf(skin);
-      return corePosed(input, poseRawSetup(input.doc, { through }), through);
+      return corePosed(input, poseRawSetup(input.doc, { through }), through, []);
     },
     animation: (name, skin, fps, count, visit, environment) => {
       const input = inputOf(skin);
@@ -762,10 +768,22 @@ export function corePoser(
       // walk that refuses a later pose still refuses the call, and a draw that throws is re-thrown once the walk has
       // finished without refusing — the first such throw, by frame — and no frame after it is drawn.
       const drawFailed: unknown[] = [];
-      walk(input.doc, name, new Array<number>(count).fill(step), { through }, (pose, i) => {
+      // `Posed.physics` on the core (issue #1467): the constraints whose state's clock reads the skeleton's after a step
+      // that moved it — spine-core's reading (`steppedPhysicsOf` in `src/render.ts`), taken off the same state the step
+      // writes, as each constraint is stepped, and handed to the pose the step made.
+      const steppedNow = new Set<string>();
+      const inner = plants.physicsStep ?? stepPhysics;
+      const physicsStep: PhysicsStepper = (r, w, length, ctx) => {
+        const moved = inner(r, w, length, ctx);
+        if (ctx.time > 0 && ctx.states.get(r.name)?.lastTime === ctx.time) steppedNow.add(r.name);
+        return moved;
+      };
+      walk(input.doc, name, new Array<number>(count).fill(step), { through, physicsStep }, (pose, i) => {
+        const stepped = [...steppedNow].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+        steppedNow.clear();
         if (drawFailed.length > 0) return;
         try {
-          visit(i, corePosed(input, pose, through));
+          visit(i, corePosed(input, pose, through, stepped));
         } catch (thrown) {
           drawFailed.push(thrown);
         }

package/src/render_shared.ts

@@ -190,6 +190,20 @@ export interface FrameSet {
    * file could only ever be the stale one.
    */
   duration: number;
+  /**
+   * Whether the physics ran while these frames were posed (issue #1467): how
+   * many physics constraints the poser stepped on at least one frame of this
+   * set, and the rate it stepped them at — the set's own `fps`, one skeleton
+   * update a frame. `render` prints the same two figures on its `physics:` line.
+   *
+   * ⭐ Absent on a rig that declares no physics constraint, for `skin`'s
+   * reason in `FramesSidecar`: there is nothing for the field to count, and
+   * every frame set written before it existed says the same. Present, a 0 is a
+   * claim — the rig declares physics and no constraint took a step on any
+   * frame — and that is what tells a reading taken with physics from one
+   * taken without.
+   */
+  physics?: { stepped: number; fps: number };
 }
 
 export interface FramesSidecar {
@@ -445,6 +459,8 @@ export interface PoseOptions {
    * so `framingViewport` keeps it and the box holds what the frames draw.
    */
   environment?: readonly EnvironmentStep[];
+  /** Also record the physics constraints the step that posed each frame stepped — see `Frame.physics` (issue #1467). */
+  physics?: boolean;
 }
 
 /**
@@ -586,6 +602,12 @@ export interface Frame {
    * second derivation of it.
    */
   attachments?: AttachmentPose[];
+  /**
+   * The physics constraints the step that posed this frame stepped, by name in
+   * code-unit order — present only when `PoseOptions.physics` asked for it
+   * (issue #1467). See `Posed.physics` for what counts as a step.
+   */
+  physics?: string[];
 }
 
 /**
@@ -1055,6 +1077,16 @@ export interface Posed {
   bones(): BoneSnapshot[];
   /** Every slot's region or mesh attachment, whole, in the posed draw order. */
   attachments(): AttachmentPose[];
+  /**
+   * The physics constraints the step that posed this moment stepped, by name in
+   * code-unit order (issue #1467). A constraint is stepped when, after a step
+   * that moved the skeleton's clock, its own clock reads the skeleton's: the
+   * physics update sets it there, and every way of not running — inactive, a
+   * mix of 0, the step skipped — leaves it behind. Read off the posed state on
+   * both posers, never off which call was made, so a step removed reads 0. The
+   * setup pose and a reset pose, where the clock has not moved, step none.
+   */
+  physics(): string[];
 }
 
 /**
@@ -1126,6 +1158,7 @@ function frameOf(index: number, time: number, posed: Posed, draw: DrawOptions, o
     pieces: posed.pieces(draw),
     ...(opts?.bones ? { bones: posed.bones() } : {}),
     ...(opts?.geometry ? { attachments: posed.attachments() } : {}),
+    ...(opts?.physics ? { physics: posed.physics() } : {}),
   };
 }