rig-parts 1.51.0 → 1.52.0

package/cli.ts

@@ -30,6 +30,7 @@ import { checkImageSize, choosePerson, KEYPOINTS_SPEC, loadKeypoints, type RigJo
 import { basisLines, branchSqueezeLine, checkProposal, compare, compareLines, DEFAULT_GRID_RULE, draftTurn, drawLandmarks, FIGURE_GRID_DIVISOR, FRINGE_STEP_PX, GRID_RULES, type GridRule, HIP_MIN_FRACTION, type DraftLintFinding, lint, lintLine, type PartSet, proposeWithBasis, readPartSet, serializeProposal, withTurn, WRIST_ON_PART_PX } from './src/propose.ts';
 import { BASIS_FILE, BASIS_SPEC, basisFile, basisLine, coverageLines, serializeBasis } from './src/diagnostics.ts';
 import { BEND_DEGREES, BEND_WORST_SHARE, DUST_MAX_PX, DUST_MAX_SHARE, IDLE_BOUND_PX, MESH_DRAFT_REPORT, MESH_DRAFT_SPEC, meshDraftStage, MORE_TRIANGLES_FLAG, relativeConfigPaths, TOLERANCE_FIGURE_DIVISOR } from './src/meshdraft.ts';
+import { meshStatsStage } from './src/meshstats.ts';
 import { clothConfigEdits, editPaths, previousCount, writtenClothConfig } from './src/clothconfig.ts';
 import { PROVENANCE_FILE, REMESH_SPEC, remeshStage } from './src/remesh.ts';
 import { RETUNE_FILE, RETUNE_SPEC, retuneStage } from './src/retune.ts';
@@ -373,6 +374,21 @@ usage:
       Written only when the drafted config's check is PASS. --requirements, --idle-keys,
       --page-edges and --pack-shape are as for rig and check.
 
+  rig-parts mesh-stats --config <config.json> --parts <dir>
+      Print the vertices and triangles of every mesh the config states, as the
+      rig stage would make them from the parts in --parts (the directory
+      holding parts.json and parts/<name>.png), and their total, in seconds:
+      the rig stage's own mesh construction, without rigc, without assemble
+      and without check (issue #566). One line per mesh in parts.json's order,
+      "mesh-stats: <part> — <mode> <V> vertices, <T> triangles" (mode lattice,
+      contour, auto or influence), then "mesh-stats: total <N> triangles over
+      <M> mesh(es)"; the counts are the ones the rig stage writes to
+      mesh_report.json, except an auto part's when rigc's motion gate refuses
+      its reduction and the rig stage replays an earlier accepted step, which
+      the auto line says. A problem the rig stage refuses (a missing part PNG,
+      an outline that does not close, a bone no config entry declares) is the
+      rig stage's own refusal, exit 1. Writes nothing.
+
   rig-parts remesh --rig <dir> --config <config.json> --parts <dir> --part <name>
                    --mesh <entry.json> --out <dir> [--requirements <file.json>]
                    (or --delta <mesh-edit.json> in place of --mesh)
@@ -934,6 +950,7 @@ const TAKES = {
   build: { valued: ['--config', '--source', '--full', '--head', '--out', '--seam', '--project', '--page-edges', '--pack-shape', '--requirements', '--idle-keys', '--lead-in', '--alt', '--set', '--environment'], switches: ['--loop', '--seam-pairs', '--keep-stills', '--all-sets'] },
   compose: { valued: ['--scene', '--out', '--requirements', '--accept'], switches: [] },
   'mesh-draft': { valued: ['--config', '--parts', '--out', '--requirements', '--idle-keys', '--page-edges', '--pack-shape'], switches: ['--more-triangles'] },
+  'mesh-stats': { valued: ['--config', '--parts'], switches: [] },
   remesh: { valued: ['--rig', '--config', '--parts', '--part', '--mesh', '--delta', '--out', '--requirements', '--idle-keys', '--page-edges', '--pack-shape'], switches: [] },
   retune: { valued: ['--rig', '--config', '--parts', '--out', '--requirements', '--idle-keys', '--page-edges', '--pack-shape'], switches: [] },
   painting: { valued: ['--keypoints', '--person'], switches: [] },
@@ -1789,6 +1806,18 @@ function cmdMeshDraft(args: string[]): number {
   }
 }
 
+/** `mesh-stats --config <config.json> --parts <dir>` (issue #566): every configured mesh's counts, through the rig stage's own `buildRig`, without rigc. Writes nothing. */
+function cmdMeshStats(args: string[]): number {
+  const f = flags(args, 'mesh-stats', ['--config', '--parts']);
+  if (typeof f === 'string') return usage(f);
+  try {
+    meshStatsStage({ config: f.get('--config') as string, parts: f.get('--parts') as string }, console.log);
+    return EXIT_OK;
+  } catch (err) {
+    return printRefusal(err);
+  }
+}
+
 /** `remesh` (issue #495): one part of a gated rig re-fitted under a requested mesh entry, into a new revision. */
 function cmdRemesh(args: string[]): number {
   const f = flags(args, 'remesh', ['--rig', '--config', '--parts', '--part', '--out']);
@@ -1937,6 +1966,7 @@ function main(argv: string[]): number | Promise<number> {
   if (command === 'build') return cmdBuild(rest);
   if (command === 'compose') return cmdCompose(rest);
   if (command === 'mesh-draft') return cmdMeshDraft(rest);
+  if (command === 'mesh-stats') return cmdMeshStats(rest);
   if (command === 'remesh') return cmdRemesh(rest);
   if (command === 'retune') return cmdRetune(rest);
   if (command === 'painting') return cmdPainting(rest);

package/docs/AUTHORING.md

@@ -107,7 +107,7 @@ read by no CPU stage).
 | `assemble.plan` | assemble; also the list every `meshes`/`regions` key must come from | **proposed** by `assemble --propose-plan`. `[part name, "full" \| "head", See-through tag]`, in draw order back to front. Names are free; roles come from the tag. A layer the author made and added to a run takes `author:<label>` in the tag's place, and has no role (§5, *A layer the author made*). When `generation.control.skeleton` is present and a full-run `handwear-r` or `handwear-l` layer merges sleeve, bare hand and overgarment drape into one layer — a skin-coloured hand cluster (`>= 40` run px, `GHOST_MIN_AREA`, measured `516..4,787` run px across the 9-standee corpus) lies within `0.35` forearm lengths of `<s>_wrist` and non-skin pixels reach more than `1.0x` the forearm length (`<s>_elbow -> <s>_wrist`) below `<s>_wrist` (issue #490; measured `-0.15x..0.45x` on the 6 clean standees vs `1.25x..2.02x` on the 3 merged standees, placing `1.0x` inside the `0.45x..1.25x` gap) — the layer is split into `drape-<s>`, `handwear-<s>` and `hand-<s>` (back to front) when the Euclidean RGB distance between the sleeve median colour above `<s>_wrist` and the drape median colour below `<s>_wrist` is at least `80` (`ARM_DRAPE_COLOR_DISTANCE`, measured `103.6..236.0` on the two distinct-colour merged standees vs `20.8..28.2` on the same-colour merged standee, placing `80` between `28.2` and `103.6`), or refused with `SEETHROUGH_ARM_RUN_MERGED` when the distance is under `80` |
 | `assemble.extend_below_crop` | assemble | **proposed** with the plan: `{part, run, tag}` — a head-run part that reaches the bottom of the head crop is continued from a full-run layer, whole connected components |
 | `assemble.patches` | assemble; `meshes`/`regions` keys may name them too | **authored**, optional: `[{name, box, alpha, draw}]` — an extra part cut from the **painting** itself, for figure no See-through layer holds (a hem both runs dropped). `box` is `[x0, y0, x1, y1]` in **rig** pixels, `x1`/`y1` exclusive — the space of `parts.json` and `recomposite_rig.png`, where the hole is found; `alpha` is `"silhouette"` (the painting's figure silhouette inside the box, the one `--seam silhouette` uses) or `"box"` (the whole box); `draw` is `"back"`, `"front"` or `{"before": "<plan part>"}`. A patch is always a region: its bone is `regions.<name>`, in the one place every region's bone lives, and a `meshes` entry for it is refused. See §5 for how to place one |
-| `assemble.cuts` | assemble; `meshes`/`regions` keys may name the new parts too, and must (each is a part like any other) | **authored**, optional (issue #170): `[{from, into, polygon, draw, overlap, under, under_fill}]`, `under` and `under_fill` optional — a plan part's layer cut by a polygon the author draws: the pixels of plan part `from` whose **centre** lies inside `polygon` (even-odd; a centre exactly on an edge is outside) leave `from` and make the new part `into`, colour and alpha, so every pixel of the layer ends in exactly one of the two. `polygon` is `[[x, y], …]`, at least three points, non-negative integer **rig** pixels — the space of `parts.json` and of the patches' boxes. The file that shows the layer in those coordinates is `assemble`'s own `rig/parts/<from>.png`, placed at its `parts.json` `x`, `y` (the PNG's pixel `(i, j)` is rig pixel `(x + i, y + j)`), or `render/recomposite_rig.png`, the whole rig 1:1; the contact sheets (`sheet`) are scaled and carry no coordinates. `draw` is `"back"`, `"front"` or `{"before": "<plan part>"}`, as for a patch (to keep the setup pose, draw the piece immediately in front of `from` — `{"before": "<the plan part after from>"}`, or `"front"` when `from` is the last plan part; `{"before": "<from>"}` draws it behind `from`, which `under` refuses as `ASSEMBLE_UNDER_DRAW` because the fill would hide it). `from` must be a plan part (`CONFIG_NAME_RESOLVES`; a patch or another cut's piece is refused), `into` a new name (`CONFIG_PART_UNIQUE`), the polygon three or more integer points (`CONFIG_FIELD_TYPE`). The piece's `parts.json` record carries `from`'s `<run>:<tag>` and its own counts, each split from the layer's by where the pixel lies; it is a mesh or a region under its own name, and the coverage rule holds it like a plan part. What the config cannot know the stage refuses: a polygon point past the rig (`ASSEMBLE_CUT_INSIDE`), two cuts of one part sharing a pixel (`ASSEMBLE_CUT_OVERLAP`), a cut that takes none of the layer's opaque pixels or leaves `from` none (`ASSEMBLE_CUT_PIXELS`). `overlap` is required, a non-negative integer of rig pixels with no default (`CONFIG_FIELD_TYPE`): the **band** — the polygon's pixels within `overlap` px of its edge by Chebyshev distance (the polygon's mask less its erosion by a `2 * overlap + 1` square) — stays in `from` as well as going to the piece, so the piece's resampled edge has art under it; the counts stay a strict partition and the band is the base's extra copy, printed on the `cut:` line. At `0` the two abut and `check`'s seam bar judges the edge between them (`CHECK_SEAM_WITHIN_BAR`, §5). A band only covers the edge at rest: a piece that swings well clear of where it was painted shows the hole it leaves, and a thin piece's band shows a ghost of the piece. `under` (issue #193), optional, is the author's image of what lies under the piece: a PNG path relative to the config's directory (`CONFIG_FIELD_TYPE` unless a non-empty string), in rig pixels over the polygon's **bounding box** — the least and greatest polygon x and y, so the image is `max x − min x` by `max y − min y` and its pixel `(i, j)` is rig pixel `(min x + i, min y + j)`. Where the cut removed pixels from `from` — the piece's pixels (alpha above 0) less the band — `from` takes the image's pixel, colour and alpha wherever the image's alpha is at least the alpha the cut removed there (**filled**); elsewhere `from` stays empty there (**left empty**): a transparent pixel is the author's statement that nothing lies under it (the background, or a part drawn behind), and a less opaque one is not half-filled. The image is read nowhere else, so its pixels over the band, over the box outside the polygon or where the layer had no art never change `from`. The `cut:` line then ends `; under <n> px filled, <m> px left empty` (`n + m` is every removed pixel), so an unintended hole is a number in the log, not a guess; the filled pixels count in `from`'s `opaque_px` and `occluded_px` (the piece is drawn over them), never as visible or projected. The stage refuses: a file that is not there (`ASSEMBLE_UNDER_PRESENT`) or not a PNG (`ASSEMBLE_UNDER_DECODES`), an image not exactly the box's size (`ASSEMBLE_UNDER_SIZE`, both sizes given), an image that fills none of the removed pixels — all transparent there, or another file (`ASSEMBLE_UNDER_EMPTY`; to leave the whole hole, drop `under`), and a piece drawn behind `from` (`ASSEMBLE_UNDER_DRAW`: the fill would hide it; draw it `"front"` or `{"before": "<the plan part after from>"}`). Producing the image is the author's, by whatever means; absent, `from` keeps only its band. `under_fill` (issue #360), optional, is the one value `"colour"` (`CONFIG_FIELD_TYPE` on any other): the same pixels are filled and left empty, and a filled pixel takes the image's **colour** at the alpha the cut removed there instead of the image's alpha, so `from`'s alpha is the uncut layer's wherever the image fills and its silhouette does not grow — an opaque image over a soft edge leaves the edge soft. It applies to the part's hidden-art layer as well as to a file; a cut with neither is refused (`ASSEMBLE_UNDER_FILL_SOURCE`). The `cut:` line's filled count then says how many took the colour only: `; under 190 px filled (190 colour only, at the alpha the cut removed), 0 px left empty`. Absent, a filled pixel takes the image's colour and alpha, as above |
+| `assemble.cuts` | assemble; `meshes`/`regions` keys may name the new parts too, and must (each is a part like any other) | **authored**, optional (issue #170): `[{from, into, polygon, draw, overlap, under, under_fill}]`, `under` and `under_fill` optional — a plan part's layer cut by a polygon the author draws: the pixels of plan part `from` whose **centre** lies inside `polygon` (even-odd; a centre exactly on an edge is outside) leave `from` and make the new part `into`, colour and alpha, so every pixel of the layer ends in exactly one of the two. `polygon` is `[[x, y], …]`, at least three points, non-negative integer **rig** pixels — the space of `parts.json` and of the patches' boxes. The file that shows the layer in those coordinates is `assemble`'s own `rig/parts/<from>.png`, placed at its `parts.json` `x`, `y` (the PNG's pixel `(i, j)` is rig pixel `(x + i, y + j)`), or `render/recomposite_rig.png`, the whole rig 1:1; the contact sheets (`sheet`) are scaled and carry no coordinates. `draw` is `"back"`, `"front"` or `{"before": "<plan part>"}`, as for a patch (to keep the setup pose, draw the piece immediately in front of `from` — `{"before": "<the plan part after from>"}`, or `"front"` when `from` is the last plan part; `{"before": "<from>"}` draws it behind `from`, which `under` refuses as `ASSEMBLE_UNDER_DRAW` because the fill would hide it). `from` must be a plan part (`CONFIG_NAME_RESOLVES`; a patch or another cut's piece is refused; a part a limb takes may be cut where no segment of the limb holds it, issue #564, §5 *Limbs*), `into` a new name (`CONFIG_PART_UNIQUE`), the polygon three or more integer points (`CONFIG_FIELD_TYPE`). The piece's `parts.json` record carries `from`'s `<run>:<tag>` and its own counts, each split from the layer's by where the pixel lies; it is a mesh or a region under its own name, and the coverage rule holds it like a plan part. What the config cannot know the stage refuses: a polygon point past the rig (`ASSEMBLE_CUT_INSIDE`), two cuts of one part sharing a pixel (`ASSEMBLE_CUT_OVERLAP`), a cut that takes none of the layer's opaque pixels or leaves `from` none (`ASSEMBLE_CUT_PIXELS`), a cut of a part a limb takes that takes a pixel a segment of the limb holds (`ASSEMBLE_CUT_CROSSES_LIMB`). `overlap` is required, a non-negative integer of rig pixels with no default (`CONFIG_FIELD_TYPE`): the **band** — the polygon's pixels within `overlap` px of its edge by Chebyshev distance (the polygon's mask less its erosion by a `2 * overlap + 1` square) — stays in `from` as well as going to the piece, so the piece's resampled edge has art under it; the counts stay a strict partition and the band is the base's extra copy, printed on the `cut:` line. At `0` the two abut and `check`'s seam bar judges the edge between them (`CHECK_SEAM_WITHIN_BAR`, §5). A band only covers the edge at rest: a piece that swings well clear of where it was painted shows the hole it leaves, and a thin piece's band shows a ghost of the piece. `under` (issue #193), optional, is the author's image of what lies under the piece: a PNG path relative to the config's directory (`CONFIG_FIELD_TYPE` unless a non-empty string), in rig pixels over the polygon's **bounding box** — the least and greatest polygon x and y, so the image is `max x − min x` by `max y − min y` and its pixel `(i, j)` is rig pixel `(min x + i, min y + j)`. Where the cut removed pixels from `from` — the piece's pixels (alpha above 0) less the band — `from` takes the image's pixel, colour and alpha wherever the image's alpha is at least the alpha the cut removed there (**filled**); elsewhere `from` stays empty there (**left empty**): a transparent pixel is the author's statement that nothing lies under it (the background, or a part drawn behind), and a less opaque one is not half-filled. The image is read nowhere else, so its pixels over the band, over the box outside the polygon or where the layer had no art never change `from`. The `cut:` line then ends `; under <n> px filled, <m> px left empty` (`n + m` is every removed pixel), so an unintended hole is a number in the log, not a guess; the filled pixels count in `from`'s `opaque_px` and `occluded_px` (the piece is drawn over them), never as visible or projected. The stage refuses: a file that is not there (`ASSEMBLE_UNDER_PRESENT`) or not a PNG (`ASSEMBLE_UNDER_DECODES`), an image not exactly the box's size (`ASSEMBLE_UNDER_SIZE`, both sizes given), an image that fills none of the removed pixels — all transparent there, or another file (`ASSEMBLE_UNDER_EMPTY`; to leave the whole hole, drop `under`), and a piece drawn behind `from` (`ASSEMBLE_UNDER_DRAW`: the fill would hide it; draw it `"front"` or `{"before": "<the plan part after from>"}`). Producing the image is the author's, by whatever means; absent, `from` keeps only its band. `under_fill` (issue #360), optional, is the one value `"colour"` (`CONFIG_FIELD_TYPE` on any other): the same pixels are filled and left empty, and a filled pixel takes the image's **colour** at the alpha the cut removed there instead of the image's alpha, so `from`'s alpha is the uncut layer's wherever the image fills and its silhouette does not grow — an opaque image over a soft edge leaves the edge soft. It applies to the part's hidden-art layer as well as to a file; a cut with neither is refused (`ASSEMBLE_UNDER_FILL_SOURCE`). The `cut:` line's filled count then says how many took the colour only: `; under 190 px filled (190 colour only, at the alpha the cut removed), 0 px left empty`. Absent, a filled pixel takes the image's colour and alpha, as above |
 | `assemble.alternates` | assemble, rig, check (`--set`, `--all-sets`) | **authored**, optional (issues #454, #465, #472, #473, #476): `[{name, source?, full?, head?, head_box?, parts?, hides?, cuts?, skeleton?, drawn?}]` — alternate painting sets assembled into `<out>/rig/parts/<set>_<part>.png` (`parts.json` `alternates`), attached on each covered slot in `rig.json` as `<set>_<part>` beside the base attachment, and indexed in `<out>/rig/sets.json` (`rig-parts-sets/1`: `sets.<set>.slots`, `.hides`, `.drawn` when present, and `.threshold: {yaw: 15, pitch: 12}` when the set replaces `face` on a rig with `turn` or `turn`/`tilt` slider animations). `source`, `full` and `head` may instead be given on the CLI with `--alt <name>=<source>:<full>[:<head>]`. `parts` lists the subset of parts the set replaces (default: every part not in `hides`); a **subset set** (issue #473, e.g. mouth visemes `a`, `i`, `u` with `"parts": ["mouth"]`) cuts only its covered parts from the alternate runs (refusing with `ASSEMBLE_ALT_INPUT_PRESENT` if a covered part's layer is missing or empty), writes only `{slot: "<set>_<slot>"}` in `sets.json` so `@rig-c/play`'s `setSet(name)` switches those slots while leaving every other slot on its base attachment (and `setSet(null)` restores the base pose), may be keyed on a slot attachment track in `motion.animations_from` as `{"t": …, "set": "<name>" \| null}` (`CONFIG_SET_COVERS_SLOT` if `"set"` is undeclared or does not cover the track's slot), and under `check --set <name>` counts `ANIMATIONS_DO_NOT_FOLD` only on its own covered slots; `hides` lists slots the set hides (`null` in `sets.json`). A **gesture subset set** (issue #476) covers a limb chain declared in `config.limbs.<limb>` (all of its segment `part`s; with `drawn` alone, cut at the base's joints posed to the set's own `drawn` angles by `poseBoneEntriesForDrawn`, each segment keeping the base's length; with `skeleton` (issue #539), cut at the skeleton's own joint positions by `placeBoneEntriesForSkeleton` — each covered bone the body-18 table names (`sleeve_*`, `arm_*0`/`arm_*1`, `leg_*0`/`leg_*1`) at its skeleton origin with the skeleton segment's own length and direction (`drawn` overriding the direction of a bone it names), and a covered bone the table does not name (a hand link `arm_r2`, a single `foot_r`) placed from its parent's new place — its base offset from the parent, stretched along the parent by the parent's length change and turned by its turn, so a link or a foot at the parent's end lands on the skeleton's end — with its base length and the drawn or base direction, so a foreshortened shin or forearm is cut where it is painted; naming the unsplit `from` layer, covering only some segments of the limb, or declaring polygon `cuts` on a limb set is refused with `CONFIG_LIMB_SET_JOINTS`) and carries `drawn` (or `skeleton`) for the covered bones only (giving `drawn` for an uncovered bone is refused with `CONFIG_SET_COVERS_BONE` / `RIG_SET_COVERS_BONE`; uncovered bones keep the base's `drawn`). `skeleton` (a pose file path relative to the config's directory, `{"width": W, "height": H, "points": {…}}` with all 18 body-18 keypoints on the canvas, validated by the same rules as `generation.control.skeleton`: `CONFIG_FILE_PRESENT`, `CONFIG_IS_JSON`, `CONFIG_FIELD_TYPE`, `CONFIG_KEY_KNOWN`, `CONFIG_KEY_UNIQUE`, `CONFIG_POSE_CANVAS`, `CONFIG_POSE_KEYPOINTS`, `CONFIG_POSE_IN_CANVAS`) or `drawn` (`{<bone>: <worldDegrees>}`, each bone resolved against `bones`, `CONFIG_NAME_RESOLVES`) declares the posed angles the alternate was painted at (issue #465); when `skeleton` is given, `assemble` derives `drawn` from its 18 keypoints (filtered to covered bones on a subset set, with `drawn` overriding any bone named in both), records both `skeleton` (scaled by `assemble.rig_scale` to rig px) and `drawn` in `parts.json` `alternates` — and, when the skeleton placed the set's limb bones (issue #539), `drawnLength` (`{<bone>: <ratio>}`, each covered table bone's skeleton segment length over its base length, 6 places) and `registration` (`{offset: [dx, dy], scale}`: the similarity without rotation, about the canvas origin, that maps the skeleton's torso — the mean of its shoulders `r_shoulder`/`l_shoulder` to the mean of its hips `r_hip`/`l_hip`, read where the base declares the bone rooted there, `sleeve_*0`/`arm_*0` and `leg_*0` — onto those base bones' origins, 6 places), both also written to `sets.json`; the set's painting must be registered, its torso within 1 rig px and 1 % in scale of the base's, or the set is refused by name before any joint is cut (`ASSEMBLE_ALT_SKELETON_REGISTERED`, with the offset and scale the painting would need) — and the `rig` stage writes `<set>_*` region and mesh attachments in the bone-local frame of `poseRigBonesForDrawn(bones, drawn)` (weighting limb segments directly from `skeleton`'s joint endpoints when `skeleton` is present) and emits `drawn` in `sets.json` so `rig-pose` and `check --set <name>` / `--all-sets` pose the bones at `drawn` without rotating the already-posed art a second time |
 | `assemble.head_face_underfill` | assemble, `assemble --propose-plan` | **authored**, optional (issue #492): `boolean` (`CONFIG_FIELD_TYPE` on any other). When both runs exist and `full:face` has at least `200` opaque run px (`PROPOSE_MIN_PX`), the stage maps `full:face` into the head canvas via `fullLayerToHead` and measures how much of its hole-filled silhouette (`alpha > 8`) is covered by `head:face` (`alpha > 8`). A head-run `face` covering less than `75 %` (`HEAD_FACE_COVERAGE_FLOOR`, measured `0.0 %..48.6 %` on hollow/omitted head runs vs `84.8 %..99.6 %` on clean head runs across the 4 public examples and 9-standee corpus) is refused with `SEETHROUGH_HEAD_RUN_HOLLOW` unless `head_face_underfill: true` is declared. When `head_face_underfill: true` is declared and `head:face` exists (`opaqueRunPx >= 200`), `fullLayerToHead(full:face)` is composited under `head:face` on the head canvas (`alpha = max(headAlpha, fullAlpha)`, RGB blended by `headAlpha / 255`) before `head:face` is placed in rig space (`underfill=<N>px(full:face)` on the `face` part log line and a `face: head_face_underfill composited …` note in `assemble --propose-plan`). The fill restores transparent pixels only and leaves the cut's own edge where it is — a hollow whose edge is not under hair stays visible, and that is the author's to fix at the cut. When `head:face` has fewer than `200` opaque pixels, `SEETHROUGH_HEAD_RUN_HOLLOW` still fires even under `head_face_underfill: true` because the head run omitted the face layer and cannot supply a jawline |
 | `limbs` | assemble (the cut and the caps), rig (through `regions`), check (`LIMB_ONE_BONE`) | **proposed** by `propose --keypoints` (issue #349), then checked: `{<limb>: {segments: [{part, from, bone}, {part, from, bone, joint, range?, cap?, edge?, cap_shape?, cut_band?}, …]}}`, the upper segment first. The rule is *Limbs: cut at their joints* below the table. `part` is a new part (`CONFIG_PART_NAME`, `CONFIG_PART_UNIQUE` against the plan, patches, cuts and every other limb part); `from` a plan part or a cut's piece (`CONFIG_NAME_RESOLVES`) — the layer the segment's pixels come from, which is cut into the limb parts and is not itself made: a `meshes` or `regions` entry for it is `CONFIG_NAME_RESOLVES`, and the segments of one limb that take one part are consecutive (`CONFIG_LIMB_FROM_RUN`); `bone` a declared bone, each segment's the child of the one before (`CONFIG_LIMB_BONES_CHAIN`); the upper segment names no `joint`, `range`, `cap`, `edge`, `cap_shape` or `cut_band` (`CONFIG_KEY_KNOWN`), every other names its `joint` (`CONFIG_FIELD_PRESENT`) — the joint is its bone's origin; `range` is `[min, max]` degrees from rest with `min <= 0 <= max` (`CONFIG_LIMB_RANGE`), which `assemble` writes into the lower part's `parts.json` record and `check` poses the joint at — its two ends and its middle — reading the seam there (`SEAM_OVER_RANGE`, issue #360; rig-c needs no rotation limit); `cap` a PNG path relative to the config's directory (`CONFIG_FIELD_TYPE`); `edge` `"feather"` and `cap_shape` `"disc"` (issue #360), each the one value its field takes (`CONFIG_FIELD_TYPE` on any other) — the cut's geometry at that joint, *Limbs: cut at their joints* below; absent, the cut is hard and the cap the layer's half-disc of half the limb's width; `cut_band` a whole number of px, 1 or more (`CONFIG_FIELD_TYPE`), on a segment that takes the segment above's part — between two layers nothing is cut, so a band there is `CONFIG_KEY_KNOWN` — places the cut within that many px of the joint line (issue #360, *Limbs: cut at their joints*); absent, the cut is the joint line. Each limb part is attached like any part — `regions.<part>`, which must be the segment's `bone` (`CONFIG_LIMB_BONE`), or a mesh, which `check` holds to that bone alone (`LIMB_ONE_BONE`). With `limbs`, `assemble` reads `bones` too (`CONFIG_FIELD_PRESENT` without it). Absent, nothing is cut at a joint and no byte of any output moves |
@@ -597,6 +597,23 @@ layers, as follows; every step is arithmetic on the declared bones and the layer
   line crosses <m> (stroke: luma <T> or below, the Otsu split of the <px> px …)`, and the record
   `cut_band`, `cut_offset`, `cut_at`, `cut_crossed`, `joint_crossed`, `band_px` and, when the band has
   a split, `stroke_luma_max`.
+- **A cut from a limb's layer** (issue #564). An `assemble.cuts` entry may take pixels from a part a
+  limb takes — the top of a shoe See-through painted into `legwear`, which the shin would otherwise
+  hold and draw a second time over the foot. The cut is made first and the limb cuts what the part
+  keeps, so the pixels leave the shin and are drawn once, by the piece; `parts.json` records the
+  piece's `cut_from` as the limb's part, which the reader finds as the segments' `limb.of`. The cut
+  may lie only where no segment of the limb holds the layer: the segments taking the part run from
+  the joint above the first of them (when it sits below one) to the joint below the last (when one
+  follows), and every pixel the cut takes must lie **past the lower line** (the ankle under a shin) or
+  **before the upper line and outside that joint's cap disc**, which the run's own layer fills there.
+  A pixel anywhere between is `ASSEMBLE_CUT_CROSSES_LIMB`, naming the limb, the first pixel, the
+  segment's band it lies in (or the cap) and the line it must lie past. The piece is a part like any
+  other: give it a `regions` (or `meshes`) entry — for a piece past the lower line, the bone of the
+  segment below that joint, which the `cut:` line names
+  (`; "shoe_top" lies past joint "ankle" of limb "leg_r", in the band of "foot_r" on bone "foot_r"`).
+  A cap is read from the parts after the cut, so its `short_px` counts what the cut left; a piece
+  past the lower line takes nothing a cap reads (a cap is the disc's upper side), and leaves it as it
+  was.
 - **Draw order.** A limb stands where its upper segment's part stood in the plan, its parts
   lowest first, so the upper is drawn over the lower at every joint: upper arm over forearm,
   thigh over shin, shin over foot. The parts it took leave the order.
@@ -1325,23 +1342,51 @@ that crosses the region with no point of it inside to split at — is still stop
 
 The package proposes no expression and keys nothing but the idle; what it gives is a rig whose
 face is bones (`eye_r`, `eye_l`, `brow_r`, `brow_l`, `mouth` on `reference-sample`) and one door for
-animations you write over them, `motion.animations_from` (the row above, issue #183). Write a
-file in rig-c's motion-spec shape beside the config and name it:
+animations you write over them, `motion.animations_from` (the row above, issues #183 and #569).
+Name a file in rig-c's motion-spec shape, its path relative to the directory `config.json` sits
+in — not the working directory:
 
 ```jsonc
 // config.json
 "motion": { "duration": 4.0, "tracks": [ … ], "blink": { … },
-            "animations_from": "expressions.json" }
+            "animations_from": "animations.json" }
+```
+
+A whole file, one looping animation over two bones the config declares — an expression is the
+same shape over the face bones, and `examples/demo/animations.json` holds seven more:
 
-// expressions.json — the bones the config declares, keyed as rig-c keys them
+```json
 { "spec": "rigc-motion/1",
   "animations": {
-    "surprised": { "duration": 0.5, "tracks": [
-      { "bone": "brow_r", "property": "translatey", "keys": [ { "t": 0, "v": [0] }, { "t": 0.25, "v": [2] }, { "t": 0.5, "v": [0] } ] },
-      { "bone": "brow_l", "property": "translatey", "keys": [ { "t": 0, "v": [0] }, { "t": 0.25, "v": [2] }, { "t": 0.5, "v": [0] } ] },
-      { "bone": "mouth",  "property": "scaley",     "keys": [ { "t": 0, "v": [1] }, { "t": 0.25, "v": [1.4] }, { "t": 0.5, "v": [1] } ] } ] } } }
+    "sway": { "duration": 2, "loop": true, "tracks": [
+      { "bone": "chest", "property": "rotate", "keys": [
+        { "t": 0, "v": [0] }, { "t": 0.5, "v": [3] }, { "t": 1.5, "v": [-3] }, { "t": 2, "v": [0] } ] },
+      { "bone": "head", "property": "rotate", "keys": [
+        { "t": 0, "v": [0] }, { "t": 1, "v": [-2] }, { "t": 2, "v": [0] } ] } ] } } }
 ```
 
+- **`spec` is required.** Without it the loader refuses
+  `CONFIG_FIELD_PRESENT: config.motion.animations_from (<file>).spec — is absent and required:
+  write "spec": "rigc-motion/1" beside "animations", …`, and another value is `CONFIG_FIELD_TYPE`
+  naming the value found and `"rigc-motion/1"`.
+- **Key times strictly increase within a track, and the last is at `duration`** — rig-c's rule
+  (its AUTHORING §4.5, "`t` is in seconds and must strictly increase"; R7: no key past the
+  declared duration, and a duration more than a frame longer than the last key is refused).
+  `loop` is a player hint rigc does not emit (its §4.3).
+- **The cycle-boundary trap.** A looping animation's boundary is one key, at `t = duration`; to
+  close the loop without a jump give it the value of the key at `t = 0`, as both tracks above do.
+  Writing that boundary key twice (`t: 2` and `t: 2` here) is a duplicate time, and it is rigc's
+  verdict at the rig stage's gate, not this loader's: `RIG_RIGC_GREEN` quotes rigc's
+  `CE_COMPILE_KEY_TIMES_NOT_INCREASING` line, `animation "<name>" bone "<bone>" <property>: key
+  times must strictly increase (at t=<t>)`. That line names the animation, the track and the time,
+  and the file it came from is the one the rig stage's line just above it names
+  (`animations beside the idle, from <file> as written: …`) — rigc reads the merged `motion.json`
+  in a scratch directory, so its own path is not yours. Remove the second key.
+- **The path resolves beside the config.** A file that is not there is `CONFIG_FILE_PRESENT:
+  config.motion.animations_from — names "<as typed>", resolved against the config's directory
+  <dir> (not the working directory) to <file>, which is no such file; …`: move the file there, or
+  write the path from that directory.
+
 **Which way a key moves a bone.** A `rotate` value is degrees added to the bone's setup
 rotation, counter-clockwise positive in the rig's y-up space — rig-c's convention (its
 AUTHORING §3.2, `rotation`: "degrees, counter-clockwise, y up"; its `src/transform.ts`, "World
@@ -1543,6 +1588,15 @@ fragment below, cut to the bust:
 - **A `physics` constraint** on that bone in `constraints`, in rig-c's shape; every field but
   the bone is rigc's to accept.
 
+A region adds vertices: its `spacing` is finer than the mesh's, and every one of them is a
+triangle more for the runtime to skin. Before the first build, count them:
+`rig-parts mesh-stats --config config.json --parts work/rig` (issue #566; `work` is step 7's `assemble --out`, §4) runs the rig stage's own
+mesh construction over the assembled parts, without rigc, without `check`, and prints one line
+per mesh — `mesh-stats: topwear — contour 320 vertices, 568 triangles` on `reference-sample` —
+and the total, `mesh-stats: total 1908 triangles over 6 mesh(es)`, the counts the build's
+`mesh_report.json` will hold (§4, *Counting the triangles before a build*). On `reference-sample`
+it runs in under a second; the build it saves runs the render and `check` as well.
+
 `build` on `reference-sample` as tracked (PR #187; the values above are the ones tuned for its `hop`, issue #183):
 
 ```
@@ -2187,6 +2241,31 @@ The selftest runs this order, with the README's flags, on each fetched example f
 a config holding only `key`, `seethrough` and `assemble.rig_scale`, pasting each
 proposal in as the steps above say (`RL01`); every step must exit 0.
 
+### Counting the triangles before a build (`mesh-stats`, issue #566)
+
+`rig-parts mesh-stats --config config.json --parts work/rig` prints the vertices and triangles of
+every mesh the config states and their total, against the parts `assemble` wrote (step 7's
+`work/rig`, or a `build --out` directory, which holds `parts.json` and `parts/` itself), in seconds.
+It is the rig stage's mesh construction itself — the same function the rig stage writes
+`mesh_report.json` from — run without rigc, without `check` and without writing a file, so a
+config can be tuned to a triangle budget before the first build and between builds:
+
+```
+mesh-stats: hair_back — lattice 155 vertices, 226 triangles
+…
+mesh-stats: total 1816 triangles over 9 mesh(es)
+```
+
+(`demo` as tracked, nine lattices.) The package holds no triangle budget: a budget is the
+consumer's, and the command prints no line against one. One line per mesh, in parts.json's
+order, the row order of `mesh_report.json`; the mode is `lattice` for a `grid` entry,
+`contour`, `auto` or `influence`. An `auto` part's count is its reduction's result: when rigc's
+motion gate refuses that result, the rig stage replays an earlier accepted step, which needs
+rigc, and the line says so. A problem the rig stage would refuse — a part with no PNG, an
+outline that does not close, a name `bones` does not declare — is the rig stage's own refusal,
+by the same name, exit 1; it takes no `--requirements`, because the rig stage's meshes read
+none, and no `--idle-keys`, because where the idle's keys go moves no vertex.
+
 ### For artists: your own layered file (issue #359)
 
 An artist's layered file is an input in its own right: you paint the figure in
@@ -2579,6 +2658,11 @@ pass, which the records are counted after):
 
     cut: "topwear" opaque 134452 = "topwear" 118973 + "scarf" 15479; band 593 px held by both
 
+A part a limb takes may be cut too — the shoe's top painted into `legwear`, cut below the
+ankle so the shin does not hold it — where no segment of the limb holds the pixels; the `cut:`
+line then names the joint the piece lies past and the bone of the segment there (§5, *Limbs*,
+*A cut from a limb's layer*, issue #564).
+
 Give the piece a `meshes` entry over the bones that should carry it, and take those
 bones out of the part it left: on the public `scarf`, the scarf end `robe_r` runs down,
 cut out of `topwear` into its own mesh on `robe_r` (and `robe_r` dropped from `topwear`'s
@@ -2806,8 +2890,8 @@ See-through with another seed.
 
 | rule | means | change |
 | --- | --- | --- |
-| <a id="CONFIG_FILE_PRESENT"></a><a id="CONFIG_IS_JSON"></a>`CONFIG_FILE_PRESENT`, `CONFIG_IS_JSON` | no such file, or not JSON | `--config` |
-| <a id="CONFIG_KEY_KNOWN"></a><a id="CONFIG_KEY_RETIRED"></a><a id="CONFIG_FIELD_PRESENT"></a><a id="CONFIG_FIELD_TYPE"></a>`CONFIG_KEY_KNOWN`, `CONFIG_KEY_RETIRED`, `CONFIG_FIELD_PRESENT`, `CONFIG_FIELD_TYPE` | an unknown key (a retired one says what replaces it), a missing one, a wrong type (`bones[i].link_inherit` must be an object whose values are strings); a project's own record under a plain key, or an annotation (`note`, `<name>_note`) holding something other than a string; in `meshes.<part>.auto` (§3, *An automatic mesh*), a missing or out-of-range number, a Stage B opt-in that is not exactly a value rig-c accepts, or a field the mode does not have — a bound on one of the five allocation rows, or an authored `motionAmplitude` (it is derived, never written); under `comfy paint`, `CONFIG_FIELD_PRESENT` on `config.generation`: a config with no `generation` block (the line names the fields it holds) | the named field; a record goes under a key beginning `x-` (any JSON, read by nothing), a remark under `note` or `<name>_note` (a string) — §3; under `comfy paint`, `config.generation` |
+| <a id="CONFIG_FILE_PRESENT"></a><a id="CONFIG_IS_JSON"></a>`CONFIG_FILE_PRESENT`, `CONFIG_IS_JSON` | no such file, or not JSON; for a file the config names (`motion.animations_from`, `requirements`), the path is read relative to the config's directory, and the `motion.animations_from` line names the path as typed, that directory and what the two resolved to (issue #569) | `--config`; a file the config names: put it at the resolved path, or write the path from the config's directory |
+| <a id="CONFIG_KEY_KNOWN"></a><a id="CONFIG_KEY_RETIRED"></a><a id="CONFIG_FIELD_PRESENT"></a><a id="CONFIG_FIELD_TYPE"></a>`CONFIG_KEY_KNOWN`, `CONFIG_KEY_RETIRED`, `CONFIG_FIELD_PRESENT`, `CONFIG_FIELD_TYPE` | an unknown key (a retired one says what replaces it), a missing one (a `motion.animations_from` file with no `spec` is told to write `"spec": "rigc-motion/1"` and the whole file's shape, issue #569), a wrong type (`bones[i].link_inherit` must be an object whose values are strings); a project's own record under a plain key, or an annotation (`note`, `<name>_note`) holding something other than a string; in `meshes.<part>.auto` (§3, *An automatic mesh*), a missing or out-of-range number, a Stage B opt-in that is not exactly a value rig-c accepts, or a field the mode does not have — a bound on one of the five allocation rows, or an authored `motionAmplitude` (it is derived, never written); under `comfy paint`, `CONFIG_FIELD_PRESENT` on `config.generation`: a config with no `generation` block (the line names the fields it holds) | the named field; a record goes under a key beginning `x-` (any JSON, read by nothing), a remark under `note` or `<name>_note` (a string) — §3; under `comfy paint`, `config.generation` |
 | <a id="CONFIG_KEY_UNIQUE"></a>`CONFIG_KEY_UNIQUE` | a key written twice in one object of a file the config names — the pose file `generation.control.skeleton` names, or the `motion.animations_from` file; JSON keeps only the last value, so every other would be dropped without a word | that file: each key once |
 | <a id="CONFIG_ANIMATION_NAME_FREE"></a>`CONFIG_ANIMATION_NAME_FREE` | the `motion.animations_from` file holds an animation named `idle`, the animation `config.motion` writes | rename that animation |
 | <a id="CONFIG_HEAD_BOX_SQUARE"></a>`CONFIG_HEAD_BOX_SQUARE` | `seethrough.head_box` is not a non-empty square | `head_box` — take `propose --head-box`'s |
@@ -2912,6 +2996,7 @@ says why each requirement exists and what breaks without it.
 | <a id="ASSEMBLE_CUT_INSIDE"></a>`ASSEMBLE_CUT_INSIDE` | a cut's polygon has a point past the rig (the detail gives the points and the size) | that cut's `polygon` — it is in rig pixels, not painting pixels |
 | <a id="ASSEMBLE_CUT_OVERLAP"></a>`ASSEMBLE_CUT_OVERLAP` | two cuts of one part share a rig pixel (the detail gives the count and the first, `x,y`) | one of the two polygons: a pixel goes to one part |
 | <a id="ASSEMBLE_CUT_PIXELS"></a>`ASSEMBLE_CUT_PIXELS` | a cut takes none of its part's opaque pixels (alpha above 8), or a part's cuts leave it none | draw the polygon over the art; to move the whole layer, rename the plan part instead |
+| <a id="ASSEMBLE_CUT_CROSSES_LIMB"></a>`ASSEMBLE_CUT_CROSSES_LIMB` | a cut whose `from` a limb takes takes a pixel inside the limb: between the joint above its segments that take the part and the joint below them, or in the upper joint's cap disc (the detail gives the limb, the count, the first `x,y`, the segment's band or the cap, and the line it must lie past) | the polygon: past the lower joint's line or before the upper's and outside its cap — or leave the pixels to the limb's segments (§5, *Limbs*) |
 | <a id="ASSEMBLE_UNDER_PRESENT"></a><a id="ASSEMBLE_UNDER_DECODES"></a>`ASSEMBLE_UNDER_PRESENT`, `ASSEMBLE_UNDER_DECODES` | a cut's `under` names no file (relative to the config's directory), or a file that is not a PNG; every cut's is named in one refusal | that cut's `under` |
 | <a id="ASSEMBLE_UNDER_SIZE"></a>`ASSEMBLE_UNDER_SIZE` | a cut's `under` image is not the size of its polygon's bounding box (the detail gives both, and the box's corner) | the image: `max x − min x` by `max y − min y` of the polygon, in rig pixels |
 | <a id="ASSEMBLE_UNDER_EMPTY"></a>`ASSEMBLE_UNDER_EMPTY` | a cut's `under` image fills none of the pixels the cut removed: its alpha is below the alpha removed at every one (all transparent there, or another file) | the image or its path; to leave the whole hole, drop `under` |

package/docs/PAINTING.md

@@ -59,6 +59,27 @@ nothing. It prints the figure, every joint and every gap with its count, then
 with `(see rig-parts guide <RULE>)`, which prints the rule's row in
 [AUTHORING §6](AUTHORING.md#6-refusals-the-rule-and-what-has-to-change).
 
+**DWPose on a faceless figure** (issue #578). Measured on eight seeds of one
+frontal, faceless wooden-mannequin painting (SDXL base 1.0, legs apart,
+1664x2432), DWPose `dw-ll_ucoco_384` through ComfyUI's DWPreprocessor at
+resolution 1024, it did three things a keypoint file must not keep:
+
+- **It may find no person.** With its default bbox detector (`yolox_l.onnx`) it
+  returned no person on 8 of the 8 seeds; with `bbox_detector` None it returned
+  one on 8 of 8. Run it with `bbox_detector` None.
+- **It may read the figure from behind.** With `bbox_detector` None the sides came
+  back mirrored on 7 of the 8: `r_shoulder` image-right of `l_shoulder` (on one
+  seed x 978 against 697) and `r_hip` image-right of `l_hip` (907 against 753).
+  The keypoint file's `r` / `l` are the subject's sides, so on a figure facing the
+  viewer `r_shoulder` is on the image's left (`src/keypoints.ts`, AUTHORING §3).
+  Check that `r_shoulder` lies image-left of `l_shoulder` and `r_hip` image-left of
+  `l_hip`, and swap each `r_` / `l_` pair of a file where they do not.
+- **Its hips may sit on the pelvis.** On that seed, after the swap, the hips were
+  at painting y 1117.0 and 1113.1 and the hip domes at y 1246 — 129 and 133
+  painting px lower (64.5 and 66.5 rig px at an `assemble.rig_scale` of 0.5). The shoulders
+  landed on the torso's edge (x 697.4 and 978.5) rather than on the balls (652 and
+  1010). Move the hips and the shoulders onto the joints before `propose`.
+
 What it reads, each a definition with no tuned number:
 
 - **Ground** — a pixel the package already calls background: alpha 8 or less
@@ -100,8 +121,12 @@ joints line counts occluded hips apart (`joints: 16 observed, 2 occluded with a
 position (r_hip, l_hip), 18 on the figure`), and an arm's gap line says when it was
 read from one.
 
-What it does not read: a front view, the feet, a prop that does not join the
-hands, anything on an elbow (a cape, a sleeve's frill, a bow), the hands' fingers,
+What it does not read: a front view (a file with every `r_` / `l_` pair swapped
+draws the same lines between the same points — the two arm lines trade names, the
+hands, knees and ankles lines run between the same two joints — so it reads as the
+unswapped file does: on the selftest's painting fixture both print the same counts
+and `PASS`), the feet, a prop that does not join the hands, anything on an elbow (a
+cape, a sleeve's frill, a bow), the hands' fingers,
 the face. A green `painting` says
 the joints and the silhouette hold the requirements it reads, not that the
 painting is good. A shadow or a floor enclosed by the background is figure to it;

package/docs/STABILITY.md

@@ -61,6 +61,7 @@ defaults are the help's too, and none is guessed from the art.
 | `build` | `--config`, `--source`, `--full`, `--out`; optional `--head` (as for `assemble`), `--seam`, `--project`, `--page-edges`, `--pack-shape`, `--loop`, `--lead-in`, `--requirements`, `--idle-keys`, `--seam-pairs`, `--keep-stills`, `--alt` (as for `assemble`, issue #454), `--set` or `--all-sets` (as for `check`, issue #454), `--environment` (as for `check`, issue #538, additive) |
 | `compose` | `--scene`, `--out`; optional `--requirements`, `--accept` |
 | `mesh-draft` | `--config`, `--parts`, `--out`; optional `--requirements`, `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon), `--more-triangles` |
+| `mesh-stats` | `--config`, `--parts` (issue #566, additive: prints, writes nothing) |
 | `remesh` | `--rig`, `--config`, `--parts`, `--part`, `--out`, and one of `--mesh` or `--delta` (issue #526); optional `--requirements`, `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon) |
 | `retune` | `--rig`, `--config`, `--parts`, `--out`; optional `--requirements`, `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon) |
 | `painting` | one positional path, the painting; `--keypoints`; optional `--person` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "1.51.0",
+  "version": "1.52.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/assemble.ts

@@ -2571,6 +2571,8 @@ export interface CutCount {
   underEmpty?: number;
   /** With `under_fill: "colour"` only (issue #360): the `under` pixels took the image's colour at the alpha the cut removed; absent without it. */
   underFill?: 'colour';
+  /** Issue #564, only on a cut from a part a limb takes, lying past the limb: the joint it lies past and the segment below it, with its bone. */
+  limb?: { limb: string; joint: string; part: string; bone: string };
 }
 
 /**
@@ -2588,7 +2590,8 @@ export function cutLines(cuts: readonly CutCount[]): string[] {
     const colour = cs.some((c) => c.underFill === 'colour') ? ` (${cs.reduce((a, c) => a + (c.underFill === 'colour' ? (c.under ?? 0) : 0), 0)} colour only, at the alpha the cut removed)` : '';
     return (
       `  cut: "${from}" opaque ${cs[0].before} = "${from}" ${cs[0].kept} + ${cs.map((c) => `"${c.into}" ${c.taken}`).join(' + ')}; band ${cs.reduce((a, c) => a + c.band, 0)} px held by both` +
-      (cs.some((c) => c.under !== undefined) ? `; under ${cs.reduce((a, c) => a + (c.under ?? 0), 0)} px filled${colour}, ${cs.reduce((a, c) => a + (c.underEmpty ?? 0), 0)} px left empty` : '')
+      (cs.some((c) => c.under !== undefined) ? `; under ${cs.reduce((a, c) => a + (c.under ?? 0), 0)} px filled${colour}, ${cs.reduce((a, c) => a + (c.underEmpty ?? 0), 0)} px left empty` : '') +
+      cs.map((c) => (c.limb === undefined ? '' : `; "${c.into}" lies past joint "${c.limb.joint}" of limb "${c.limb.limb}", in the band of "${c.limb.part}" on bone "${c.limb.bone}"`)).join('')
     );
   });
 }
@@ -2838,6 +2841,108 @@ function shiftedAt(line: JointLine, offset: number): [number, number] {
   return [pyRound(line.at[0] + offset * line.axis[0], 3), pyRound(line.at[1] + offset * line.axis[1], 3)];
 }
 
+/**
+ * Issue #564: where an `assemble.cuts` entry from a part a limb takes lies
+ * against that limb. The segments of a limb that take the part are a run
+ * `k0 .. k1` (`CONFIG_LIMB_FROM_RUN` keeps them consecutive), and the run's
+ * pixels lie between two joint lines: the line of the joint above `k0` when
+ * `k0` sits below one (a joint between two layers), and the line of the joint
+ * below `k1` when a segment follows it (the ankle under a shin that takes the
+ * legwear). A pixel the cut takes (alpha above 0 in its piece) is outside the
+ * run when it lies past the lower line, or not past the upper line and — read
+ * after the limbs are cut, with `caps` — outside the disc of that joint's cap,
+ * which the run's own layer fills there first. Anything else lies in a
+ * segment's band, and the cut is refused: the pixels would leave a segment
+ * that holds them, and the bend would open where the layer was cut. Every
+ * limb taking the part is read. `past` is the segment a taken pixel lies in
+ * when every one lies past the lower line — the one below that joint, or
+ * below the deepest joint line all of them are past — and is what the `cut:`
+ * line names. Without `caps` the lines alone are read; with them only the
+ * discs, for the pixels the lines let through.
+ */
+function limbBands(
+  cuts: readonly Cut[],
+  pieces: ReadonlyArray<Built | null>,
+  limbs: Readonly<Record<string, Limb>>,
+  bones: readonly BoneEntry[],
+  W: number,
+  H: number,
+  caps: ((limb: string, segment: number) => CapRecord | undefined) | null,
+): { problems: Problem[]; past: Map<number, { limb: string; joint: string; part: string; bone: string }> } {
+  const problems: Problem[] = [];
+  const past = new Map<number, { limb: string; joint: string; part: string; bone: string }>();
+  const places = bonePlaces(bones);
+  const lineAbove = (l: string, k: number): JointLine | null => {
+    const segs = limbs[l].segments;
+    const up = places.get(segs[k - 1].bone);
+    const me = places.get(segs[k].bone);
+    if (up === undefined || me === undefined) return null;
+    const end = me.end ?? (k + 1 < segs.length ? (places.get(segs[k + 1].bone)?.at ?? null) : null);
+    return jointLine(up.at, me.at, end);
+  };
+  const fmt = (q: readonly number[]): string => `[${q.map((n) => pyRound(n, 3)).join(', ')}]`;
+  cuts.forEach((q, i) => {
+    const piece = pieces[i];
+    if (piece === null) return;
+    const taken: number[] = [];
+    for (let p = 0; p < W * H; p++) if (piece.r.data[p * 4 + 3] > 0) taken.push(p);
+    for (const l of Object.keys(limbs)) {
+      const segs = limbs[l].segments;
+      const k0 = segs.findIndex((sg) => sg.from === q.from);
+      if (k0 < 0) continue;
+      let k1 = k0;
+      while (k1 + 1 < segs.length && segs[k1 + 1].from === q.from) k1++;
+      const upper = k0 > 0 ? lineAbove(l, k0) : null;
+      const lower = k1 + 1 < segs.length ? lineAbove(l, k1 + 1) : null;
+      // A joint with no line is ASSEMBLE_LIMB_JOINT, refused by cutLimbs by name; nothing is read about it here.
+      if ((k0 > 0 && upper === null) || (k1 + 1 < segs.length && lower === null)) continue;
+      const cap = caps === null || upper === null ? undefined : caps(l, k0);
+      const inside: number[] = [];
+      let below = 0;
+      for (const p of taken) {
+        const x = p % W;
+        const y = Math.floor(p / W);
+        if (lower !== null && pastJoint(lower, x, y)) {
+          below++;
+          continue;
+        }
+        if (upper !== null && !pastJoint(upper, x, y)) {
+          if (caps === null || cap === undefined || !inDisc(cap.at, cap.radius, x, y)) continue;
+        } else if (caps !== null) continue;
+        inside.push(p);
+      }
+      const object = `config.assemble.cuts[${i}] (part "${q.into}")`;
+      const wanted = [
+        ...(lower === null ? [] : [`past joint "${String(segs[k1 + 1].joint)}"'s line (through ${fmt(lower.at)}, axis ${fmt(lower.axis)})`]),
+        ...(upper === null ? [] : [`before joint "${String(segs[k0].joint)}"'s line (through ${fmt(upper.at)}, axis ${fmt(upper.axis)})${cap === undefined ? '' : ` and outside its cap's disc, radius ${cap.radius} px about ${fmt(cap.at)}`}`]),
+      ];
+      if (inside.length > 0) {
+        const f = inside[0];
+        const fx = f % W;
+        const fy = Math.floor(f / W);
+        let k = k0;
+        if (caps === null) {
+          for (let ln = k < k1 ? lineAbove(l, k + 1) : null; ln !== null && pastJoint(ln, fx, fy); ln = k < k1 ? lineAbove(l, k + 1) : null) k++;
+        }
+        const band =
+          caps !== null
+            ? `the cap of joint "${String(segs[k0].joint)}" on "${segs[k0].part}" (radius ${(cap as CapRecord).radius} px about ${fmt((cap as CapRecord).at)}), which "${q.from}"'s pixels fill there`
+            : `the band of "${segs[k].part}"${k > 0 ? ` below joint "${String(segs[k].joint)}"` : ''}${k + 1 < segs.length ? `${k > 0 ? ' and' : ''} above joint "${String(segs[k + 1].joint)}"` : ' to the limb\'s end'}`;
+        problems.push({
+          code: 'ASSEMBLE_CUT_CROSSES_LIMB',
+          object,
+          detail: `takes ${inside.length} of its ${taken.length} pixel(s) of "${q.from}" inside limb "${l}", the first at ${fx},${fy}, in ${band}; "${q.from}" is the layer config.limbs.${l} cuts at its joints, and a cut from it may lie only where no segment of the limb holds it — every pixel it takes ${wanted.length === 0 ? `outside the limb, and the limb has no joint before or past its segments that take "${q.from}" (they are all of it), so no pixel is` : wanted.join(', or ')} is required: move the polygon, or give the pixels to a segment of the limb instead`,
+        });
+      } else if (caps === null && lower !== null && below === taken.length && taken.length > 0) {
+        let j = k1 + 1;
+        for (let ln = j + 1 < segs.length ? lineAbove(l, j + 1) : null; ln !== null && taken.every((p) => pastJoint(ln as JointLine, p % W, Math.floor(p / W))); ln = j + 1 < segs.length ? lineAbove(l, j + 1) : null) j++;
+        if (!past.has(i)) past.set(i, { limb: l, joint: String(segs[j].joint), part: segs[j].part, bone: segs[j].bone });
+      }
+    }
+  });
+  return { problems, past };
+}
+
 /**
  * Cut every declared limb (module comment of `src/limbs.ts`): each part a limb
  * takes is split among the limbs that take it (nearest polyline), then each
@@ -3719,6 +3824,15 @@ export function assemble(input: AssembleInput): AssembleResult {
   // In cut order, as the config lists them.
   cutCounts.sort((a, b) => cuts.findIndex((q) => q.into === a.into) - cuts.findIndex((q) => q.into === b.into));
 
+  // Issue #564: a cut from a part a limb takes lies outside the limb's segments, read before the limbs are cut.
+  const bands = input.limbs === undefined || cuts.length === 0 ? null : limbBands(cuts, pieces, input.limbs, input.bones ?? [], W, H, null);
+  if (bands !== null) {
+    refuseIfAny(bands.problems);
+    for (const [i, at] of bands.past) {
+      const c = cutCounts.find((q) => q.into === cuts[i].into);
+      if (c !== undefined) c.limb = at;
+    }
+  }
   // Issue #349: the limbs, after the cuts (a limb may take a cut's piece, and a cut's under image fills its base first).
   const lim = cutLimbs(input.limbs ?? {}, input.bones ?? [], input.caps ?? new Map(), W, H, (name) => {
     const pi = plan.findIndex((e) => e[0] === name);
@@ -3726,6 +3840,8 @@ export function assemble(input: AssembleInput): AssembleResult {
     const ci = cuts.findIndex((q) => q.into === name);
     return ci >= 0 ? pieces[ci] : null;
   }, opaqueOf, mergedIn, count, (name) => hiddenArt.get(name) ?? null, (layer, by) => hiddenUses.get(layer)?.push(by));
+  // Issue #564: and the cap a run's own layer fills above its upper joint, read once the limbs are cut.
+  if (bands !== null) refuseIfAny(limbBands(cuts, pieces, input.limbs ?? {}, input.bones ?? [], W, H, (l, k) => lim.parts.find((q) => q.limb === l && q.segment === k)?.record.cap).problems);
   const limbPieces = lim.pieces;
   const order = limbOrder(order0, plan, cuts, lim.parts);
   const pieceAt = (d: { plan: number } | { cut: number } | { limb: number }): { name: string; b: Built } =>

package/src/build.ts

@@ -1146,21 +1146,39 @@ function multiIntervalRun(
  * the gate is green — and, for every automatic mesh, only when its motion gate
  * accepted it (issue #126 item 3; {@link motionGates}).
  */
-export function rigStage(input: RigStageInput, rigc: RigcRunner, scratch: string, log: Log): RigOutput {
-  const { config: cfg, animations: from } = loadConfigAndAnimations(input.config);
-  const parts = readParts(join(input.parts, 'parts.json'));
+/** What the rig stage reads before it builds anything: the config with its `animations_from` table, parts.json, and each part's PNG (and each alternate set's) that exists. */
+export interface RigInputs {
+  cfg: ReturnType<typeof loadConfigAndAnimations>['config'];
+  from: ReturnType<typeof loadConfigAndAnimations>['animations'];
+  parts: ReturnType<typeof readParts>;
+  images: Map<string, Raster>;
+}
+
+/**
+ * The rig stage's inputs, read as {@link rigStage} reads them: `rigStage` and `mesh-stats` (issue #566,
+ * `src/meshstats.ts`) both start here, so the two read the same config, the same parts and the same images, and a
+ * PNG that is missing is left out of the map for `buildRig` to refuse by name (`RIG_PNG_PRESENT`).
+ */
+export function readRigInputs(config: string, partsDir: string): RigInputs {
+  const { config: cfg, animations: from } = loadConfigAndAnimations(config);
+  const parts = readParts(join(partsDir, 'parts.json'));
   const images = new Map<string, Raster>();
   for (const p of parts.parts) {
-    const png = join(input.parts, 'parts', `${p.name}.png`);
+    const png = join(partsDir, 'parts', `${p.name}.png`);
     if (existsSync(png)) images.set(p.name, readPng(png));
   }
   for (const alt of parts.alternates ?? []) {
     for (const p of alt.records) {
       const attName = `${alt.name}_${p.name}`;
-      const png = join(input.parts, 'parts', `${attName}.png`);
+      const png = join(partsDir, 'parts', `${attName}.png`);
       if (existsSync(png)) images.set(attName, readPng(png));
     }
   }
+  return { cfg, from, parts, images };
+}
+
+export function rigStage(input: RigStageInput, rigc: RigcRunner, scratch: string, log: Log): RigOutput {
+  const { cfg, from, parts, images } = readRigInputs(input.config, input.parts);
   const first = buildRig(cfg, parts, images, undefined, input.idleKeys ?? DEFAULT_IDLE_KEYS, input.reduce);
   const textsOf = (r: RigOutput): Array<[string, string]> => {
     const mergedMotion = withAnimations(r.motion, from === null ? null : from.table);

package/src/config.ts

@@ -213,7 +213,9 @@ export interface Patch {
  * `draw` places a patch. What the config alone cannot know — whether the
  * polygon lies inside the rig, takes any of the layer's art, or overlaps
  * another cut of the same part — the assemble stage refuses
- * (`ASSEMBLE_CUT_INSIDE`, `ASSEMBLE_CUT_PIXELS`, `ASSEMBLE_CUT_OVERLAP`).
+ * (`ASSEMBLE_CUT_INSIDE`, `ASSEMBLE_CUT_PIXELS`, `ASSEMBLE_CUT_OVERLAP`), and,
+ * for a `from` a limb takes (issue #564), whether the polygon takes a pixel a
+ * segment of the limb holds (`ASSEMBLE_CUT_CROSSES_LIMB`).
  */
 export interface Cut {
   from: string;
@@ -1537,7 +1539,7 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   if ('cloth' in t) checkCloth(c, t.cloth);
   if ('requirements' in t && c.string('config.requirements', t.requirements) && base !== null) checkRequirementsFile(c, resolve(base, t.requirements));
   const from = isPlainObject(t.motion) ? t.motion.animations_from : undefined;
-  const animations = base !== null && typeof from === 'string' && from !== '' ? readAnimationsFrom(c, resolve(base, from)) : null;
+  const animations = base !== null && typeof from === 'string' && from !== '' ? readAnimationsFrom(c, base, from) : null;
   if (animations !== null) {
     checkFaceAnimationBand(c, animations, hasAltFace, t.turn, attached);
     checkAnimationSetKeys(c, animations, t.assemble, new Set<string>([...parts, ...patches, ...cuts, ...(limbs?.parts.keys() ?? [])]));
@@ -1592,13 +1594,18 @@ function checkRequirementsFile(c: Check, file: string): void {
  * 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_FILE_PRESENT`: no such file, or a file that cannot be read. The
+ *   line names the path as typed, the config's directory it was resolved
+ *   against and what that gave (issue #569): the path is read beside the
+ *   config, not in the working directory, and a reader who cannot see the
+ *   disk needs all three to tell which was wrong.
  * - `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`
+ *   the two absent; an absent `spec` is told the line to write and the whole
+ *   file's shape (issue #569), from {@link ANIMATIONS_FROM_SPEC}. 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
@@ -1609,18 +1616,21 @@ function checkRequirementsFile(c: Check, file: string): void {
  *
  * Returns the animations when this file added no problem, else null.
  */
-function readAnimationsFrom(c: Check, file: string): AnimationsFrom | null {
+function readAnimationsFrom(c: Check, base: string, from: 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`;
+  const file = resolve(base, from);
+  const form = `{"spec": "${ANIMATIONS_FROM_SPEC}", "animations": {"<name>": {"duration": …, "tracks": [...]}}}`;
+  const shape = `a file in rig-c's motion-spec shape, ${form}, its path relative to the config's directory`;
+  const where = `names ${JSON.stringify(from)}, resolved against the config's directory ${base} (not the working directory) to ${file}`;
   if (!existsSync(file) || !statSync(file).isFile()) {
-    c.fail('CONFIG_FILE_PRESENT', field, `names ${file}, which is no such file; ${shape} is required`);
+    c.fail('CONFIG_FILE_PRESENT', field, `${where}, 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`);
+    c.fail('CONFIG_FILE_PRESENT', field, `${where}, which cannot be read: ${(err as Error).message}; ${shape} is required`);
     return null;
   }
   let raw: Json;
@@ -1643,7 +1653,13 @@ function readAnimationsFrom(c: Check, file: string): AnimationsFrom | null {
       `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'], []);
+  // Both keys are required; `c.object` is given them as optional so an absent
+  // `spec` can be told the line to write, in the order `c.object` names them.
+  const o = c.object(at, raw, [], ['spec', 'animations']);
+  if (o !== null && !('spec' in o)) {
+    c.fail('CONFIG_FIELD_PRESENT', `${at}.spec`, `is absent and required: write "spec": "${ANIMATIONS_FROM_SPEC}" beside "animations", the motion-spec version motion.json states — the whole file is ${form}`);
+  }
+  if (o !== null && !('animations' in o)) c.fail('CONFIG_FIELD_PRESENT', `${at}.animations`, 'is absent and required');
   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`);
   }

package/src/meshstats.ts

@@ -0,0 +1,57 @@
+/**
+ * `mesh-stats` (issue #566): the vertices and triangles of every mesh a config states, against an assembled parts
+ * directory, before a build.
+ *
+ * It is the rig stage without rigc: the same inputs ({@link readRigInputs}) through the same `buildRig`, whose
+ * `meshReport` rows are what `rig/mesh_report.json` is written from. Nothing triangulates a second time, so a count
+ * printed here is the count the rig stage writes for the same config and parts — with one exception, which the line
+ * says: an `auto` part whose motion gate refuses the full reduction is replayed by the rig stage to an earlier
+ * accepted step (`rigStage`, `src/autoreplay.ts`), and that search runs rigc, so it does not run here. A problem
+ * `buildRig` refuses is the build's own refusal, by the same name. Nothing is written: no skeleton data leaves memory,
+ * no image, no report; rigc's gate is the gate of the commands that emit, and this one emits nothing.
+ */
+import { readRigInputs } from './build.ts';
+import { buildRig, DEFAULT_IDLE_KEYS, type MeshReport } from './rig.ts';
+
+/** One mesh's counts, as the rig stage's `mesh_report.json` row holds them; `mode` is `lattice` for a `grid` entry, whose row carries no mode. */
+export interface MeshStatsRow {
+  part: string;
+  mode: 'lattice' | 'contour' | 'auto' | 'influence';
+  vertices: number;
+  triangles: number;
+}
+
+/** The counts of each row of a mesh report, in its order (parts.json's, the order the rig stage writes). */
+export function meshStatsRows(report: readonly MeshReport[]): MeshStatsRow[] {
+  return report.map((m) => ({ part: m.part, mode: 'mode' in m ? m.mode : 'lattice', vertices: m.vertices, triangles: m.triangles }));
+}
+
+/** What `auto` adds to its line: the count is the reduction's, before the motion gate that may replay it. */
+export const AUTO_BEFORE_GATE = "the reduction's result; when rigc's motion gate refuses it, the rig stage replays an earlier accepted step, which this command does not run";
+
+/** The printed lines: one per mesh, then the total. No budget line: the tree holds no triangle budget. */
+export function meshStatsLines(rows: readonly MeshStatsRow[]): string[] {
+  const out = rows.map((r) => `mesh-stats: ${r.part} — ${r.mode} ${r.vertices} vertices, ${r.triangles} triangles${r.mode === 'auto' ? ` (${AUTO_BEFORE_GATE})` : ''}`);
+  const total = rows.reduce((n, r) => n + r.triangles, 0);
+  out.push(`mesh-stats: total ${total} triangles over ${rows.length} mesh(es)`);
+  return out;
+}
+
+export interface MeshStatsInput {
+  /** The config, as `rig --config` reads it. */
+  config: string;
+  /** The directory holding parts.json and parts/<name>.png, as `rig --parts` reads it. */
+  parts: string;
+}
+
+/**
+ * The counts of every mesh `buildRig` makes from the config and the parts, printed through `log`. The idle's keys
+ * go where `rig` puts them by default (`ctl`): where they go moves no vertex and no triangle, since a control bone
+ * stands at its bone's origin and no mesh is weighted to it. Throws the rig stage's own `PartsError` on a refusal.
+ */
+export function meshStatsStage(input: MeshStatsInput, log: (line: string) => void): MeshStatsRow[] {
+  const { cfg, parts, images } = readRigInputs(input.config, input.parts);
+  const rows = meshStatsRows(buildRig(cfg, parts, images, undefined, DEFAULT_IDLE_KEYS).meshReport);
+  for (const l of meshStatsLines(rows)) log(l);
+  return rows;
+}

package/src/parts.ts

@@ -42,7 +42,9 @@
  * cut from, which shares its `from`. The record is in draw order, and a piece
  * drawn `"back"` comes before its base, so order cannot say which of two parts
  * sharing a layer is the piece; this field does. A `parts.json` written before
- * 1.6.0 has none, and still reads. `limb`, written only on a part a
+ * 1.6.0 has none, and still reads. A piece cut from a part a limb took
+ * (issue #564) names that part, which is not written itself: its base is the
+ * limb segments whose `limb.of` it is, with the same `from`. `limb`, written only on a part a
  * `config.limbs` segment made (issue #349), names the limb, the segment's
  * index (0 the upper), the part it was cut from (`of`), the one bone it rides
  * and, below a joint, the joint, its declared `range` when there is one
@@ -563,6 +565,14 @@ function checkParts(raw: unknown, path: string): PartsFile {
     // single plan part behind it; the config loader refuses one).
     const recs = o.parts.filter((p): p is Record<string, unknown> => typeof p === 'object' && p !== null && !Array.isArray(p));
     const byName = new Map<unknown, Record<string, unknown>>(recs.map((r) => [r.name, r]));
+    // Issue #564: a plan part a limb took is not written itself; its segments are, each naming it (`limb.of`) with its layer.
+    const limbOf = new Map<string, Record<string, unknown>>();
+    for (const r of recs) {
+      const l = r[LIMB_KEY];
+      if (typeof l !== 'object' || l === null || Array.isArray(l)) continue;
+      const of = (l as Record<string, unknown>).of;
+      if (typeof of === 'string' && !limbOf.has(of)) limbOf.set(of, r);
+    }
     for (const r of recs) {
       if (!(CUT_FROM_KEY in r)) continue;
       const object = `part "${String(r.name)}" field "${CUT_FROM_KEY}"`;
@@ -572,7 +582,10 @@ function checkParts(raw: unknown, path: string): PartsFile {
         continue;
       }
       const b = byName.get(base);
-      if (b === undefined) fail('PARTS_CUT_FROM_KNOWN', object, `names "${base}", which is no part of this file; the plan part the cut took this piece from is required`);
+      const seg = b === undefined ? limbOf.get(base) : undefined;
+      if (seg !== undefined) {
+        if (seg.from !== r.from) fail('PARTS_CUT_FROM_KNOWN', object, `names "${base}", which limb segment "${String(seg.name)}" was cut from, with from ${show(seg.from)}; this piece's is ${show(r.from)}, and a piece shares its base's layer`);
+      } else if (b === undefined) fail('PARTS_CUT_FROM_KNOWN', object, `names "${base}", which is no part of this file and no limb segment's "of"; the plan part the cut took this piece from is required`);
       else if (base === r.name) fail('PARTS_CUT_FROM_KNOWN', object, `names the piece itself; the plan part the cut took it from is required`);
       else if (CUT_FROM_KEY in b) fail('PARTS_CUT_FROM_KNOWN', object, `names "${base}", which is itself a piece (cut from ${show(b[CUT_FROM_KEY])}); a plan part is required, as a cut of a cut has no single layer behind it`);
       else if (b.from !== r.from) fail('PARTS_CUT_FROM_KNOWN', object, `names "${base}", whose from is ${show(b.from)}; this piece's is ${show(r.from)}, and a piece shares its base's layer`);