rig-parts 1.83.2 → 1.84.0

package/docs/AUTHORING.md

@@ -5118,6 +5118,7 @@ and stay absent).
 | <a id="RIG_TURN_SURFACE_OVERLAP_DEPTH"></a>`RIG_TURN_SURFACE_OVERLAP_DEPTH` | same-group overlap neighbours demand incompatible emitted offsets at one target setup point | separate the conflicting support or provide coincident neighbour fields; the refusal names the fields and target vertex |
 | <a id="RIG_TURN_SURFACE_MESH_BINDINGS"></a>`RIG_TURN_SURFACE_MESH_BINDINGS` | an authored surface mesh has unresolved/nonclosing weights or shares a frame moved by a unit/rear turn carrier; declared stop draw aliases resolve to their links for setup sampling | provide weighted bindings closing at 1 in the authored frame; `<link>_d` resolves only for links declared in `config.stops`; use independent chains for parts with different roles |
 | <a id="RIG_TURN_SURFACE_MESH_ATTACHMENT"></a>`RIG_TURN_SURFACE_MESH_ATTACHMENT` | a surface mesh has an alternate drawing without its own registered depth sampling frame | use the base attachment; explicit islands retain their own slot, attachment and bindings |
+| <a id="RIG_TURN_BODY_UNCOVERED"></a>`RIG_TURN_BODY_UNCOVERED` | **Warning:** a shown part without a body role overlaps a moved `turn.body` surface at setup alpha >= 128 and has different emitted endpoint displacement | declare the intended body role and inspect both endpoints; no role or depth is inferred |
 | <a id="RIG_TURN_SURFACE_DEPTH_REQUIRED"></a>`RIG_TURN_SURFACE_DEPTH_REQUIRED` | a part with role `"surface"` in `config.turn.roles` or `config.turn.body.roles` carries no depth sheet in `parts.json` | run `assemble` with `config.depth` or provide `<part>_depth.png` in `parts.json` |
 | <a id="RIG_TURN_GRID_BUDGET"></a>`RIG_TURN_GRID_BUDGET` | a `"surface"` grid exceeds 2,400 triangles on one slot or 4,000 triangles across all `"surface"` slots | lower `config.turn.grid` / `config.turn.body.grid` `[cols, rows]` within the per-slot and total budgets |
 | <a id="RIG_TURN_HEAD_BONE"></a>`RIG_TURN_HEAD_BONE` | `buildRig` found no `"head"` (or body turn root) bone when emitting 2.5D turn carriers | declare `"head"` (or the body turn root bone) in `config.bones` |
@@ -6020,6 +6021,71 @@ on a bone of length 0 are NOT MEASURABLE and the run is not PASS (`CK68`–`CK79
 frame the slide peaks; a seam on a rig with no `parts.json` is refused before anything
 is built (`CK83`–`CK85`, `RQ30`–`RQ35`).
 
+### Art joints on a fixed skeleton
+
+When art is fitted to a skeleton whose setup must stay fixed, declare
+`fixed_skeleton` in the existing `--requirements` file (issue #880):
+
+```json
+{
+  "spec": "spine-parts-requirements/1",
+  "fps": 12,
+  "requirements": [],
+  "fixed_skeleton": {
+    "source": "independent joint measurements on the fitted art",
+    "within_px": 4,
+    "joints": [
+      { "name": "shoulder", "bone": "upper_arm", "at": [26, 57] }
+    ]
+  }
+}
+```
+
+The block explicitly identifies this as a fixed-skeleton comparison; a generation
+control pose does not. `source` is required nonempty provenance text, recorded
+without interpretation. Each `at` is an independently measured point on the art
+**as placed on the rig's stage**, in stage pixels from its top-left, x right and y
+down, the same space as a requirement's `target.stage`. Convert painting/source
+coordinates through the actual placement before declaring them: raw source pixels,
+bone-local offsets and normalized coordinates are not stage pixels. Each nonempty
+`name` is unique and each `bone` explicitly names its matching bone origin in
+`rig.json`. No anatomical names, hidden joints, correspondences or positions are
+inferred; only the listed measurements are covered. An unmeasured joint must not
+be supplied as the bone's own position.
+
+`check` uses the existing setup-still renderer, requesting `--geometry`, and reads
+`geometry.json`'s `setup.bones` through its existing geometry reader. It converts
+the renderer's setup-world origin to stage pixels through the coordinate door;
+it never substitutes an animation's first frame or a bone's parent-local `x,y`.
+This also works for an external `rig.json` with no `parts.json` or idle. The
+Euclidean distance, art point and setup origin are printed **for every declared
+joint** and written to `check.json`'s `ART_JOINT_DISTANCE`, along with `source`,
+`instrument` and `within_px`. This is a setup-placement check, not a motion check
+or automatic detection of joints in an image.
+
+`within_px` is optional and, when present, must be finite and nonnegative. The
+example's `4` is an authored demonstration, not a calibrated or default tolerance.
+Distance **greater than** the declared limit fails; equality passes. Without a
+limit, the block and every joint are **SKIP**, with the measured distances and
+`within_px: null`; this line is excluded from measured bars and contributes no
+PASS. Other independent checks may still pass. With no `fixed_skeleton` block,
+this measurement adds no output or render call. `fps` and `requirements` remain
+required by the enclosing file; they do not change this setup measurement.
+
+| rule | change |
+| --- | --- |
+| <a id="CHECK_ART_JOINT_DISTANCE"></a>`CHECK_ART_JOINT_DISTANCE` | The named joint is farther from its setup bone origin than `fixed_skeleton.within_px`; the message gives distance and limit. Correct a wrong art measurement or bone correspondence, or supply art aligned to the fixed skeleton. Choose any changed limit explicitly from the consumer's requirement; bones and art are never moved by this check. |
+| <a id="CHECK_ART_JOINT_MEASURED"></a>`CHECK_ART_JOINT_MEASURED` | Supply a finite renderer setup origin and a finite measurable distance; missing geometry is never taken as zero. The existing `CHECK_GEOMETRY_FILE` refusal names missing/malformed geometry. |
+
+`REQUIREMENTS_FIELD` and `REQUIREMENTS_RESOLVES` cover malformed declarations:
+supply nonempty provenance and a nonempty joint list, unique joint names, finite
+`[x, y]` points, known bone names and an explicit valid limit or omit the limit.
+Unknown fields are refused.
+
+| line | measures | bar | SKIP |
+| --- | --- | --- | --- |
+| <a id="ART_JOINT_DISTANCE"></a>`ART_JOINT_DISTANCE` | Each independently measured art joint versus its explicitly named bone's renderer setup origin, in stage pixels; printed and recorded per joint | distance <= the declared `fixed_skeleton.within_px`, with no rounding slack | no limit declared: every row and the block retain their distances as SKIP, never a pass; no declaration: no line |
+
 ## 8. What one character costs
 
 | step | reference-sample | reference-demo | source |
@@ -6324,6 +6390,26 @@ art. An authored `parts.json` depth reference remains an active standalone
 guards still apply. With binding inactive there is no added reference, file or
 legacy-byte change. #773 adds no image generation, geometry or motion model.
 
+### Missing body-turn coverage
+
+`RIG_TURN_BODY_UNCOVERED` warns when a shown part without a
+`turn.body.roles` entry overlaps a moved body surface. It names both parts,
+both endpoint times, their actual emitted displacement vectors and the maximum
+relative displacement at a setup painting-pixel centre. Both drawings require
+alpha >= 128 and actual covering setup triangles; bounding boxes and transparent
+pixels alone do not count. Excluded alpha does not count. The diagnostic reads
+positive bindings in the declared torso subtree, excluding head/neck subtrees.
+Explicit body roles and bindings wholly inheriting an emitted body-turn carrier
+count as declared coverage; identical inherited motion needs no second role. Differences no larger than the producer's six-place
+encoding unit (0.000001 rig px) are ignored. This is a warning about a missing
+declaration, not an automatic seam verdict or a rule for limb crossings.
+
+Warnings belong to the stage report only. They add no rig, motion or PNG field
+and never assign a role, depth, binding or draw order. A part already bound to
+`chest` does not inherit a weighted topwear surface's per-vertex deform. Declare
+its actual intended role, then inspect setup, both turn endpoints and their diff;
+an explicit role alone does not establish that two drawings remain coincident.
+
 ### Unit depth precedence
 
 For `"unit"` roles, a transported part's sheet is recorded and validated but is not

package/docs/STABILITY.md

@@ -491,6 +491,13 @@ inverse-bind deform offsets in motion, without adding a Core attachment depth
 field. Head yaw/pitch and independent body yaw use their existing turn groups.
 Blended surfaces retain the documented per-group masks and setup-overlap
 neighbour field rules in [AUTHORING](AUTHORING.md#per-layer-depth-sheets-773).
+`RIG_TURN_BODY_UNCOVERED` is a report-only warning for a shown torso part
+without a body role that has opaque setup-triangle overlap with a moved body
+surface and different emitted endpoint displacement. It names the part, surface,
+times, vectors and relative travel. Head/neck bindings, transparent/excluded
+alpha, explicit/inherited body roles and identical inherited motion are excluded as
+described in [AUTHORING](AUTHORING.md#missing-body-turn-coverage). It assigns
+no role or depth and changes no emitted file bytes.
 The unit-depth precedence and its primary-surface sampling are documented in
 [AUTHORING](AUTHORING.md#unit-depth-precedence).
 The separate ordering scalar is unchanged. No-image outputs retain legacy bytes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "1.83.2",
+  "version": "1.84.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/artjoints.ts

@@ -0,0 +1,94 @@
+/** Explicit art-joint measurements on a fixed skeleton (issue #880). */
+import { refuseIfAny, type Problem } from './errors.ts';
+import { cropToSpineY } from './coords.ts';
+import { edgeLength } from './length.ts';
+
+export interface ArtJoint {
+  name: string;
+  bone: string;
+  /** Measured art point in stage pixels, x right and y down. */
+  at: [number, number];
+}
+export interface FixedSkeleton {
+  /** Where the independent art measurements came from; never interpreted. */
+  source: string;
+  joints: ArtJoint[];
+  /** Maximum Euclidean distance in stage pixels. Absent means measurement only. */
+  within_px?: number;
+}
+const object = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const finite = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+const free = (k: string, v: unknown): boolean => (k.startsWith('x-') && k.length > 2) || ((k === 'note' || k.endsWith('_note')) && typeof v === 'string');
+
+/** Validate without deriving any art point, bone correspondence or limit. */
+export function fixedSkeletonProblems(value: unknown, at: string): Problem[] {
+  const problems: Problem[] = [];
+  const fail = (where: string, detail: string): void => { problems.push({ code: 'REQUIREMENTS_FIELD', object: where, detail }); };
+  const keys = (v: Record<string, unknown>, allowed: string[], where: string): void => {
+    for (const k of Object.keys(v)) if (!allowed.includes(k) && !free(k, v[k])) fail(`${where}.${k}`, `is unknown; fields are ${allowed.join(', ')}`);
+  };
+  if (!object(value)) return [{ code: 'REQUIREMENTS_FIELD', object: at, detail: 'requires {source, joints, within_px?}; omit fixed_skeleton for a rig without this declaration' }];
+  keys(value, ['source', 'joints', 'within_px'], at);
+  if (typeof value.source !== 'string' || value.source.trim() === '') fail(`${at}.source`, 'requires the provenance of the independent art-joint measurements as nonempty text');
+  if ('within_px' in value && (!finite(value.within_px) || value.within_px < 0)) fail(`${at}.within_px`, `is ${JSON.stringify(value.within_px)}; a finite nonnegative stage-pixel limit is required, or omit it for a SKIP-class measurement`);
+  if (!Array.isArray(value.joints) || value.joints.length === 0) fail(`${at}.joints`, 'requires a nonempty list of {name, bone, at: [x, y]} measured on the art in stage pixels (x right, y down)');
+  else {
+    const seen = new Set<string>();
+    value.joints.forEach((joint, i) => {
+      const where = `${at}.joints[${i}]`;
+      if (!object(joint)) { fail(where, 'requires {name, bone, at: [x, y]}'); return; }
+      keys(joint, ['name', 'bone', 'at'], where);
+      for (const k of ['name', 'bone']) if (typeof joint[k] !== 'string' || joint[k].trim() === '') fail(`${where}.${k}`, 'requires a nonempty name');
+      if (typeof joint.name === 'string') {
+        if (seen.has(joint.name)) fail(`${where}.name`, `declares joint "${joint.name}" twice; each measured joint is declared once`);
+        seen.add(joint.name);
+      }
+      if (!Array.isArray(joint.at) || joint.at.length !== 2 || !joint.at.every(finite)) fail(`${where}.at`, 'requires a finite [x, y] measured on the art in stage pixels (x right, y down)');
+    });
+  }
+  return problems;
+}
+
+export const ART_JOINT_LINE = 'ART_JOINT_DISTANCE';
+export interface ArtJointRow extends ArtJoint {
+  /** Bone origin in the same stage-pixel space as at. */
+  bone_at: [number, number];
+  distance_px: number;
+  status: 'PASS' | 'FAIL' | 'SKIP';
+}
+export interface ArtJointLine {
+  status: 'PASS' | 'FAIL' | 'SKIP';
+  instrument: 'rigc-geometry/1 setup.bones';
+  source: string;
+  within_px: number | null;
+  joints: ArtJointRow[];
+  reason?: string;
+}
+
+/** Compare independent art points to renderer setup origins, never animation frame zero. */
+export function artJointLine(
+  fixed: FixedSkeleton,
+  stage: { x: number; y: number; height: number },
+  setup: (bone: string) => { worldX: number; worldY: number },
+  problems: Problem[],
+): ArtJointLine {
+  refuseIfAny(fixedSkeletonProblems(fixed, 'fixed_skeleton'));
+  const limit = fixed.within_px;
+  const joints = fixed.joints.map<ArtJointRow>(j => {
+    const world = setup(j.bone);
+    if (!Number.isFinite(world.worldX) || !Number.isFinite(world.worldY)) refuseIfAny([{ code: 'CHECK_ART_JOINT_MEASURED', object: `joint "${j.name}" (bone "${j.bone}")`, detail: 'has no finite renderer setup origin; a missing position is never a zero distance' }]);
+    const boneAt: [number, number] = [world.worldX - stage.x, cropToSpineY(world.worldY - stage.y, stage.height)];
+    const distance = edgeLength(j.at[0] - boneAt[0], j.at[1] - boneAt[1]);
+    if (!Number.isFinite(distance)) refuseIfAny([{ code: 'CHECK_ART_JOINT_MEASURED', object: `joint "${j.name}" (bone "${j.bone}")`, detail: 'has no finite art-to-setup distance; finite stage-pixel coordinates are required' }]);
+    const status = limit === undefined ? 'SKIP' : distance > limit ? 'FAIL' : 'PASS';
+    if (status === 'FAIL') problems.push({ code: 'CHECK_ART_JOINT_DISTANCE', object: `joint "${j.name}" (bone "${j.bone}")`, detail: `art at [${j.at.join(', ')}] is ${distance} stage px from setup origin [${boneAt.join(', ')}]; distance <= declared fixed_skeleton.within_px ${limit} px is required — correct the art measurement/correspondence if wrong, or supply art aligned to the fixed skeleton; bones are not moved` });
+    return { name: j.name, bone: j.bone, at: [...j.at] as [number, number], bone_at: boneAt, distance_px: distance, status };
+  });
+  return { status: limit === undefined ? 'SKIP' : joints.some(j => j.status === 'FAIL') ? 'FAIL' : 'PASS', instrument: 'rigc-geometry/1 setup.bones', source: fixed.source, within_px: limit ?? null, joints,
+    ...(limit === undefined ? { reason: 'fixed_skeleton.within_px is absent; distances are measured, no limit is invented and no joint passes' } : {}) };
+}
+
+export function artJointLines(line: ArtJointLine): string[] {
+  return [`${ART_JOINT_LINE}: ${line.status}${line.reason === undefined ? '' : ` — ${line.reason}`}; source ${JSON.stringify(line.source)}; ${line.instrument}`,
+    ...line.joints.map(j => `${ART_JOINT_LINE}: joint "${j.name}" (bone "${j.bone}") ${j.status} — art [${j.at.join(', ')}], setup [${j.bone_at.join(', ')}], distance ${j.distance_px} px; ${line.within_px === null ? 'no declared limit (SKIP)' : `limit <= ${line.within_px} px`}`)];
+}

package/src/build.ts

@@ -1,3 +1,4 @@
+import { ART_JOINT_LINE, artJointLines } from './artjoints.ts';
 import { applyTakenLayers } from './takelayers.ts';
 import { ownershipLines, provenanceLines } from './provenance.ts';
 import { readSourceDepth } from './depthsheets.ts';
@@ -1941,6 +1942,8 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   if (vsSource !== undefined) log(`  ${judgementLine(SOURCE_LINE, vsSource)}`);
   const windBand = fig[WIND_BAND_LINE];
   if (windBand !== undefined) for (const l of windBandLines(windBand)) log(`  ${l}`);
+  const artJoints = fig[ART_JOINT_LINE];
+  if (artJoints !== undefined) for (const line of artJointLines(artJoints)) log(`  ${line}`);
   if (r.requirements !== null) {
     for (const [name, line] of Object.entries(r.requirements.lines)) log(`  ${requirementText(name, line)}`);
     log(`  ${summaryText(r.requirements.summary)}`);

package/src/check.ts

@@ -1,3 +1,4 @@
+import { ART_JOINT_LINE, artJointLine, type ArtJointLine } from './artjoints.ts';
 import { baseAnchorMoves, type AnchorRegion } from './baseanchor.ts';
 /**
  * The check stage: build a rig through rig-c, gate it under both
@@ -2694,6 +2695,8 @@ export interface CheckFigures {
   config?: InputFileRecord;
   /** Written only under `--requirements` (issue #93): the file's fps, the summary, and one line per declared requirement, by name. */
   requirements?: RequirementsBlock;
+  /** Issue #880: only when requirements declares fixed_skeleton. */
+  [ART_JOINT_LINE]?: ArtJointLine;
   PASS: boolean;
 }
 
@@ -2940,7 +2943,7 @@ export function barsNotMet(fig: Readonly<Record<string, unknown>>): string[] {
     isRecord(fig.sets) &&
     Object.values(fig.sets).some((s) => isRecord(s) && typeof s.seam_mean === 'number' && typeof s.seam_px_over_40 === 'number' && seamFails(s.seam_mean, s.seam_px_over_40, typeof s.seam_frame_scale === 'number' ? s.seam_frame_scale : 1));
   if ((typeof fig.seam_mean === 'number' && typeof fig.seam_px_over_40 === 'number' && seamFails(fig.seam_mean, fig.seam_px_over_40, scale)) || setFailed) out.push('seam');
-  for (const n of [...JUDGEMENT_LINES, FOLD_LINE, LEVEL_LINE, STRESS_LINE, LIMB_LINE, SWEEP_LINE]) {
+  for (const n of [...JUDGEMENT_LINES, FOLD_LINE, LEVEL_LINE, STRESS_LINE, LIMB_LINE, SWEEP_LINE, ART_JOINT_LINE]) {
     const l = fig[n];
     if (typeof l === 'object' && l !== null && (l as { status?: unknown }).status === 'FAIL') out.push(n);
   }
@@ -3049,7 +3052,7 @@ export function checkStatuses(fig: CheckFigures): Record<string, CheckStatus> {
   const bar = (name: string, measured: boolean): CheckStatus => (!measured ? 'SKIP' : notMet.includes(name) ? 'FAIL' : 'PASS');
   const out: Record<string, CheckStatus> = { gate: bar('gate', true), loop: bar('loop', fig.loop_max_diff !== null), seam: bar('seam', fig.seam_mean !== null) };
   for (const n of JUDGEMENT_LINES) out[n] = fig[n].status;
-  for (const n of [FOLD_LINE, LEVEL_LINE, STRESS_LINE, LIMB_LINE, SWEEP_LINE, MOTION_SEAM_LINE, CLOTH_LINE, ...REPORTED_LINES, SOURCE_LINE, WIND_BAND_LINE] as const) {
+  for (const n of [FOLD_LINE, LEVEL_LINE, STRESS_LINE, LIMB_LINE, SWEEP_LINE, MOTION_SEAM_LINE, CLOTH_LINE, ...REPORTED_LINES, SOURCE_LINE, WIND_BAND_LINE, ART_JOINT_LINE] as const) {
     const l = fig[n];
     if (l !== undefined) out[n] = l.status;
   }
@@ -6402,7 +6405,9 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   const setsFigures: Record<string, SetCheckFigures> = {};
   // Issue #671: a failing set's hint, read with its seam; never written to check.json.
   const setHints = new Map<string, string>();
-  if (inp.parts !== null || inp.source !== null) {
+  const fixedSkeleton = reqFile?.fixed_skeleton;
+  let artJoints: ArtJointLine | null = null;
+  if (inp.parts !== null || inp.source !== null || fixedSkeleton !== undefined) {
     try {
       mkdirSync(stillDir, { recursive: true });
       const images = typeof inp.rig.images === 'string' ? resolve(inp.rigDir, inp.rig.images) : inp.rig.images;
@@ -6426,9 +6431,18 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
       if (sb.status !== 0) refuseIfAny(rigcFailed('build (the setup-pose still)', sb, buildGateLines(sb.out)));
       // The stage is the parts' canvas wherever parts.json is read (CHECK_RIG_STAGE_IS_THE_CANVAS), so this is its longest side.
       const maxSide = Math.ceil(Math.max(inp.stage.width, inp.stage.height));
-      const sr = rigc(['render', '--candidate', join(stillDir, 'build'), '--animation', 'still', '--fps', String(STILL_FPS), '--max', String(maxSide), '--out', join(stillDir, 'render')]);
+      const sr = rigc(['render', '--candidate', join(stillDir, 'build'), '--animation', 'still', '--fps', String(STILL_FPS), '--max', String(maxSide), ...(fixedSkeleton === undefined ? [] : ['--geometry']), '--out', join(stillDir, 'render')]);
       if (sr.status !== 0) refuseIfAny(rigcFailed('render (the setup-pose still)', sr, sr.out.split('\n').filter((l) => l.includes('FAIL'))));
       const stillSet = readFrameSet(join(stillDir, 'render'));
+      if (fixedSkeleton !== undefined) {
+        const geometryPath = join(stillSet.dir, GEOMETRY_FILE);
+        const geometry = readGeometry(geometryPath, stillSet.written);
+        artJoints = artJointLine(fixedSkeleton, inp.stage, bone => {
+          const track = boneTrackOf(geometry, geometryPath, stillSet, bone);
+          if (typeof track === 'string') return geometryProblem(geometryPath, track);
+          return track.setup;
+        }, problems);
+      }
       seamViewport = stillSet.viewport;
       if (keepStills) cpSync(join(stillDir, 'render'), inp.parts === null ? keptDir : join(out, 'setup_still_auto'), { recursive: true });
       if (inp.parts !== null) {
@@ -6621,6 +6635,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     ...(Object.keys(skipped).length === 0 ? {} : { skipped }),
     ...(Object.keys(setsFigures).length === 0 ? {} : { sets: setsFigures }),
     ...(config === undefined ? {} : { config }),
+    ...(artJoints === null ? {} : { [ART_JOINT_LINE]: artJoints }),
     ...(reqBlock === null ? {} : { requirements: reqBlock }),
     PASS: false,
   };
@@ -6684,6 +6699,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   }
   // Issues #320, #333: the fold bar is counted where it is written — on every rig whose motion holds an animation.
   if (folds !== null) tally(FOLD_LINE, null);
+  if (artJoints !== null) tally(ART_JOINT_LINE, artJoints.status === 'SKIP' ? (artJoints.reason ?? 'no declared limit') : null);
   // Issue #348: the level bar where it is written; a line whose every foot no frame posed says SKIP and is not measured.
   if (level !== null) tally(LEVEL_LINE, level.status === 'SKIP' ? (level.reason ?? '') : null);
   // Issue #347: the stress bar is counted where it is written — on every rig with a handwear part and an idle.

package/src/requirements.ts

@@ -1,3 +1,4 @@
+import { fixedSkeletonProblems, type FixedSkeleton } from './artjoints.ts';
 /**
  * What a scene requires of a rig's motion, declared in a file `check` is given
  * (`--requirements`, issue #93, increment 2 of #87) and measured from the
@@ -190,6 +191,8 @@ export interface RequirementsFile {
    * not declared: no fold in a named animation is meant.
    */
   may_fold: MayFold[];
+  /** Issue #880: an explicit fixed-skeleton art comparison, absent on other rigs. */
+  fixed_skeleton?: FixedSkeleton;
 }
 
 /** One declared fold (issue #320): a slot, a named animation, and why the fold is the art's. */
@@ -280,7 +283,8 @@ export function readRequirements(path: string): RequirementsFile {
     problems.push({ code: 'REQUIREMENTS_SELF_TARGET', object: `${label} field "target"`, detail });
   };
   if (raw.spec !== REQUIREMENTS_SPEC) field(`${at} field "spec"`, `is ${JSON.stringify(raw.spec)}; ${JSON.stringify(REQUIREMENTS_SPEC)} is required`);
-  for (const k of Object.keys(raw)) if (!['spec', 'fps', 'targets', 'requirements', ...EXCEPTION_LISTS, 'may_fold'].includes(k) && !freeKey(k, raw[k])) field(`${at} field "${k}"`, 'is not a field this format reads (spec, fps, targets, requirements, not_planted, not_swinging, rises, rests, may_fold; note or *_note as a string; x-<name> as a record)');
+  for (const k of Object.keys(raw)) if (!['spec', 'fps', 'targets', 'requirements', ...EXCEPTION_LISTS, 'may_fold', 'fixed_skeleton'].includes(k) && !freeKey(k, raw[k])) field(`${at} field "${k}"`, 'is not a field this format reads (spec, fps, targets, requirements, not_planted, not_swinging, rises, rests, may_fold, fixed_skeleton; note or *_note as a string; x-<name> as a record)');
+  if ('fixed_skeleton' in raw) problems.push(...fixedSkeletonProblems(raw.fixed_skeleton, `${at} fixed_skeleton`));
   let fps = NaN;
   if (!(finite(raw.fps) && raw.fps > 0)) field(`${at} field "fps"`, `is ${JSON.stringify(raw.fps)}; a positive number of frames per second is required — every named animation is sampled at it, and there is no default`);
   else fps = raw.fps;
@@ -464,7 +468,7 @@ export function readRequirements(path: string): RequirementsFile {
     }
   }
   refuseIfAny(problems);
-  return { path: at, fps, targets, requirements, not_planted: lists.not_planted, not_swinging: lists.not_swinging, rises: lists.rises, rests: lists.rests, may_fold: mayFold };
+  return { path: at, fps, targets, requirements, not_planted: lists.not_planted, not_swinging: lists.not_swinging, rises: lists.rises, rests: lists.rests, may_fold: mayFold, ...(raw.fixed_skeleton === undefined ? {} : { fixed_skeleton: raw.fixed_skeleton as FixedSkeleton }) };
 }
 
 // ---------------------------------------------------------------------------
@@ -542,6 +546,7 @@ export function resolveRequirements(file: RequirementsFile, rig: Record<string,
   const target = (object: string, t: TargetRef): void => {
     if ('bone' in t) bone(`${object} target`, t.bone);
   };
+  for (const j of file.fixed_skeleton?.joints ?? []) bone(`fixed_skeleton joint "${j.name}"`, j.bone);
   for (const r of file.requirements) {
     const object = `requirement "${r.name}" (${r.kind})`;
     animation(object, r.animation);

package/src/rig.ts

@@ -3668,6 +3668,7 @@ export function buildWaistPairSource(
       hasAlternateFaceSet,
       surfaceMeshes: turnSurfaceMeshes(cfg, rig, parts.rig_size),
       neighbourMeshes: turnNeighbourMeshes(cfg, rig, parts, new Map(outImages)),
+      coverageMeshes: cfg.turn.body === undefined ? undefined : turnNeighbourMeshes(cfg, rig, parts, new Map(outImages), true),
     });
   }
   bindFaceSurfaceDeform(motion, (merged) => {
@@ -4206,13 +4207,13 @@ function turnSurfaceMeshes(cfg: CharacterConfig, rig: RigSpec, canvas: readonly
 }
 
 /** Actual shown support; Core's own grid topology is inspection metadata only. */
-export function turnNeighbourMeshes(cfg: CharacterConfig, rig: RigSpec, parts: PartsFile, emittedImages: ReadonlyMap<string, Raster>) {
+export function turnNeighbourMeshes(cfg: CharacterConfig, rig: RigSpec, parts: PartsFile, emittedImages: ReadonlyMap<string, Raster>, coverage = false) {
   const meshes: NonNullable<Parameters<typeof buildDepth25DTurn>[2]['neighbourMeshes']>[number][] = [];
   const canvas = parts.rig_size;
   const aliases = new Map<string, string>((rig.stops ?? []).flatMap(s => s.links.map(link => [`${link}_d`, link])));
   const world = computeWorldTransforms(rig.bones.map(b => b.parent === undefined ? b : { ...b, parent: aliases.get(b.parent) ?? b.parent }));
-  for (const part of new Set([...Object.keys(cfg.turn?.roles ?? {}), ...Object.keys(cfg.turn?.body?.roles ?? {})])) {
-    if (cfg.meshes[part] !== undefined && [cfg.turn?.roles?.[part], cfg.turn?.body?.roles?.[part]].includes('surface')) continue;
+  for (const part of new Set([...Object.keys(cfg.turn?.roles ?? {}), ...Object.keys(cfg.turn?.body?.roles ?? {}), ...(coverage ? parts.parts.map(p => p.name) : [])])) {
+    if (!coverage && cfg.meshes[part] !== undefined && [cfg.turn?.roles?.[part], cfg.turn?.body?.roles?.[part]].includes('surface')) continue;
     const record = parts.parts.find(p => p.name === part);
     if (record === undefined) continue;
     const split = cfg.regions[part] !== undefined && cfg.motion.blink?.still?.[part] !== undefined

package/src/turn.ts

@@ -37,6 +37,7 @@ import { turnOverlapOwners } from './turnoverlap.ts';
 import { sampleTurnTriangleField, turnTriangleCoordinates } from './turnfield.ts';
 import { PartsError } from './errors.ts';
 import { f32 } from '@rig-c/core/compile';
+import { warnUncoveredBodyTurn } from './turncoverage.ts';
 import { evaluateDeformTransform } from '@rig-c/core/src/deformgen.ts';
 
 /**
@@ -1505,6 +1506,8 @@ export interface Depth25DTurnOptions {
   }>;
   /** Final weighted unit/rear drawings are support only, never surface targets. */
   neighbourMeshes?: Depth25DTurnOptions['surfaceMeshes'];
+  /** Shown setup geometry for coverage diagnostics only; never a role opt-in. */
+  coverageMeshes?: Depth25DTurnOptions['surfaceMeshes'];
 }
 
 interface Depth25DGroupSpec {
@@ -2216,4 +2219,5 @@ export function buildDepth25DTurn(
   }
 
   refuseIfAny(problems);
+  if (opts.warnings !== undefined) warnUncoveredBodyTurn(rig, motion, opts);
 }

package/src/turncoverage.ts

@@ -0,0 +1,156 @@
+/** Report missing body-turn declarations from shown setup alpha and emitted fields. */
+import { f32 } from '@rig-c/core/compile';
+import { DRAWN_ALPHA } from '@rig-c/core/src/passthrough.ts';
+import { evaluateDeformTransform, type DeformTransform } from '@rig-c/core/src/deformgen.ts';
+import { computeWorldTransforms, paintingToSetupPoint, toWorld } from './coords.ts';
+import { extendDepthSilhouette, sampleDepthFloat } from './depthsheets.ts';
+import { edgeLength } from './length.ts';
+import type { Depth25DTurnOptions } from './turn.ts';
+import { rasterTurnTriangleOwnership, type TurnTriangleQuery } from './turnfield.ts';
+
+type Mesh = NonNullable<Depth25DTurnOptions['coverageMeshes']>[number];
+type Rig = Parameters<typeof computeWorldTransforms>[0];
+interface Animation {
+  tracks: Array<{ bone?: string; group?: string; property: string; keys: Array<{ t: number; v?: number[] | Record<string, number[]>; derive?: { degrees: number; carried?: number; depth?: number | Record<string, number> } }> }>;
+  deform?: Array<{ slot: string; attachment: string; keys: Array<{ t: number; vertices?: number[]; transform?: DeformTransform }> }>;
+}
+
+/**
+ * Warning only: overlap cannot prove the author's intended role. Explicit or inherited body
+ * roles already declare coverage; this reader never assigns one. A one-millionth
+ * pixel is the producer's six-place encoding unit, not a visual acceptance bar.
+ */
+export function warnUncoveredBodyTurn(
+  rig: { bones: Rig; stops?: ReadonlyArray<{ links: readonly string[] }> },
+  motion: { groups?: Record<string, string[]>; animations: Record<string, unknown> },
+  opts: Depth25DTurnOptions,
+): void {
+  const body = opts.turn.body, meshes = opts.coverageMeshes;
+  const anim = motion.animations.body_turn as Animation | undefined;
+  if (body === undefined || meshes === undefined || anim === undefined || opts.warnings === undefined) return;
+  const aliases = new Map<string, string>((rig.stops ?? []).flatMap(s => s.links.map(b => [`${b}_d`, b] as const)));
+  const resolve = (b: string) => aliases.get(b) ?? b;
+  const bones = rig.bones.map(b => b.parent === undefined ? b : { ...b, parent: resolve(b.parent) });
+  const world = computeWorldTransforms(bones), parents = new Map(bones.map(b => [b.name, b.parent]));
+  const chain = (bone: string): string[] => {
+    const result: string[] = [];
+    for (let b: string | undefined = resolve(bone); b !== undefined && !result.includes(b); b = parents.get(b)) result.push(b);
+    return result;
+  };
+  const root = body.bone ?? (parents.has('chest') ? 'chest' : 'hip');
+  const torso = (m: Mesh) => m.weights.every(row => row.filter(w => w.weight > 0).every(w => {
+    const path = chain(w.bone);
+    return path.includes(root) && !path.some(b => ['head', 'head_ctl', 'neck', 'neck_ctl'].includes(b));
+  }));
+  const positions = new Map(meshes.map(m => [m, m.weights.map(row => {
+    let x = 0, y = 0;
+    for (const w of row) { const p = toWorld(world.get(resolve(w.bone))!, w.x, w.y); x += p[0] * w.weight; y += p[1] * w.weight; }
+    return [x, y];
+  })]));
+  const times = anim.tracks[0]?.keys;
+  if (times === undefined || times.length === 0) return;
+  const endpoints = [times[0], times[times.length - 1]].map(({ t }) => {
+    const translations = new Map<string, number[]>();
+    for (const tr of anim.tracks) {
+      const key = tr.keys.find(k => k.t === t);
+      if (key === undefined) continue;
+      for (const bone of tr.bone === undefined ? motion.groups?.[tr.group!] ?? [] : [tr.bone]) {
+        const derive = key.derive, depth = typeof derive?.depth === 'number' ? derive.depth : derive?.depth?.[bone];
+        const stated = Array.isArray(key.v) ? key.v[0] : key.v?.[bone]?.[0];
+        const value = f32(stated ?? -(depth! - (derive?.carried ?? 0)) * Math.sin(derive!.degrees * Math.PI / 180));
+        const parent = parents.get(bone), frame = parent === undefined ? undefined : world.get(resolve(parent));
+        const v = tr.property === 'translatex' ? [value, 0] : [0, value];
+        translations.set(bone, frame === undefined ? v : [frame.a * v[0] + frame.b * v[1], frame.c * v[0] + frame.d * v[1]]);
+      }
+    }
+    return new Map(meshes.map(m => {
+      const key = anim.deform?.find(d => d.slot === m.slot && d.attachment === m.attachment)?.keys.find(k => k.t === t);
+      let generated: number[] | undefined;
+      if (key?.transform !== undefined && m.gridSamples !== undefined) {
+        const p = opts.parts.find(p => p.name === m.part)!;
+        const ext = extendDepthSilhouette(opts.images.get(p.depth!.image)!, opts.images.get(p.name)!);
+        const z = m.gridSamples.map(([x, y]) => { const level = sampleDepthFloat(ext, x - p.x, y - p.y); return (p.depth!.near === 'black' ? 255 - level : level) * p.depth!.zScale / 255; });
+        generated = evaluateDeformTransform(key.transform, positions.get(m)!.flat(), f32, `body coverage "${m.part}"`, z).offsets;
+      }
+      let at = 0;
+      const vectors = m.weights.map((row, vi) => {
+        let x = 0, y = 0;
+        for (const w of row) {
+          const frame = world.get(resolve(w.bone))!;
+          const dx = f32(key?.vertices?.[at++] ?? 0), dy = f32(key?.vertices?.[at++] ?? 0);
+          let wx = generated === undefined ? frame.a * dx + frame.b * dy : generated[2 * vi];
+          let wy = generated === undefined ? frame.c * dx + frame.d * dy : generated[2 * vi + 1];
+          for (const b of chain(w.bone)) { const v = translations.get(b); if (v !== undefined) { wx += v[0]; wy += v[1]; } }
+          x += wx * w.weight; y += wy * w.weight;
+        }
+        return [x, y];
+      });
+      return [m, vectors] as const;
+    }));
+  });
+  const opaque = (name: string, x: number, y: number) => {
+    const p = opts.parts.find(p => p.name === name)!, image = opts.images.get(name)!;
+    const px = Math.floor(x - p.x), py = Math.floor(y - p.y);
+    return px >= 0 && py >= 0 && px < image.width && py < image.height && image.data[(py * image.width + px) * 4 + 3] >= DRAWN_ALPHA;
+  };
+  const sample = (m: Mesh, hit: { ids: number[]; weights: number[] }, endpoint: number): number[] => {
+    const field = endpoints[endpoint].get(m)!;
+    const [a, b, c] = hit.ids.map(i => field[i]), [u, v] = hit.weights;
+    // The same translation-invariant barycentric form as sampleTurnTriangleField.
+    return [0, 1].map(axis => c[axis] + u * (a[axis] - c[axis]) + v * (b[axis] - c[axis]));
+  };
+  const keyedBones = new Set(anim.tracks.flatMap(tr => tr.bone === undefined ? motion.groups?.[tr.group!] ?? [] : [tr.bone]));
+  const pairs: Array<{ part: Depth25DTurnOptions['parts'][number]; surface: string; source: Depth25DTurnOptions['parts'][number]; targets: Mesh[]; supports: Mesh[] }> = [];
+  for (const part of opts.parts) {
+    if (body.roles[part.name] !== undefined) continue;
+    const targets = meshes.filter(m => m.part === part.name && torso(m));
+    if (targets.length === 0 || targets.every(m => m.weights.every(row => row.filter(w => w.weight > 0).every(w => chain(w.bone).some(b => keyedBones.has(b)))))) continue;
+    for (const [surface, role] of Object.entries(body.roles)) {
+      if (role !== 'surface') continue;
+      const source = opts.parts.find(p => p.name === surface)!;
+      const supports = meshes.filter(m => m.part === surface);
+      pairs.push({ part, surface, source, targets, supports });
+    }
+  }
+  const requested = new Map<Mesh, Map<string, TurnTriangleQuery>>();
+  for (const { part, source, targets, supports } of pairs) {
+    for (let y = Math.max(part.y, source.y); y < Math.min(part.y + part.h, source.y + source.h); y++) {
+      for (let x = Math.max(part.x, source.x); x < Math.min(part.x + part.w, source.x + source.w); x++) {
+        if (!opaque(part.name, x + 0.5, y + 0.5) || !opaque(source.name, x + 0.5, y + 0.5)) continue;
+        for (const target of targets) {
+          const point = paintingToSetupPoint([x + 0.5, y + 0.5], target.canvas, target.canvas), key = `${point[0]},${point[1]}`;
+          for (const mesh of [target, ...supports]) {
+            let cells = requested.get(mesh);
+            if (cells === undefined) { cells = new Map(); requested.set(mesh, cells); }
+            if (!cells.has(key)) cells.set(key, { x: point[0], y: point[1], point });
+          }
+        }
+      }
+    }
+  }
+  const ownership = new Map([...requested].map(([mesh, cells]) => [mesh, rasterTurnTriangleOwnership(positions.get(mesh)!, mesh.triangles ?? [], [...cells.values()])]));
+  for (const { part, surface, source, targets, supports } of pairs) {
+    const readings = [0, 1].map(() => ({ relative: 0, point: [0, 0], part: [0, 0], surface: [0, 0] }));
+    for (let y = Math.max(part.y, source.y); y < Math.min(part.y + part.h, source.y + source.h); y++) {
+      for (let x = Math.max(part.x, source.x); x < Math.min(part.x + part.w, source.x + source.w); x++) {
+        const px = x + 0.5, py = y + 0.5;
+        if (!opaque(part.name, px, py) || !opaque(surface, px, py)) continue;
+        for (const target of targets) for (const support of supports) {
+          const p = paintingToSetupPoint([px, py], target.canvas, target.canvas);
+          const a = ownership.get(target)?.at(p[0], p[1]) ?? null;
+          const b = ownership.get(support)?.at(p[0], p[1]) ?? null;
+          if (a === null || b === null) continue;
+          for (const [endpoint, reading] of readings.entries()) {
+            const av = sample(target, a, endpoint), bv = sample(support, b, endpoint);
+            const relative = edgeLength(av[0] - bv[0], av[1] - bv[1]);
+            if (edgeLength(bv[0], bv[1]) > 0.000001 && relative > reading.relative) Object.assign(reading, { relative, point: [px, py], part: av, surface: bv });
+          }
+        }
+      }
+    }
+    if (readings.some(r => r.relative > 0.000001)) opts.warnings.push({
+      code: 'RIG_TURN_BODY_UNCOVERED', object: `part "${part.name}"`,
+      detail: `overlaps moved body surface "${surface}" at alpha >= ${DRAWN_ALPHA} without a config.turn.body role; body_turn endpoints ${readings.map((r, i) => `t=${i === 0 ? times[0].t : times[times.length - 1].t}: part displacement [${r.part.join(', ')}], surface displacement [${r.surface.join(', ')}], relative ${r.relative} rig px at setup painting [${r.point.join(', ')}]`).join('; ')}; declare the intended body role and inspect both endpoints; no role or depth is inferred`,
+    });
+  }
+}

package/src/turnfield.ts

@@ -22,6 +22,55 @@ export function turnTriangleCoordinates(points: ReadonlyArray<readonly number[]>
   return null;
 }
 
+/** A requested setup-grid cell and its exact caller-computed world point. */
+export interface TurnTriangleQuery { x: number; y: number; point: readonly number[] }
+
+/**
+ * Rasterise only requested cells, in triangle order. Sparse sorted sample rows
+ * bound the storage to the query set, not a world/canvas rectangle. One adjacent
+ * row/cell is conservatively visited at each bbox edge; this is a broad phase,
+ * never an epsilon in the barycentric test. The original arithmetic below is
+ * the sole acceptance rule, including zero-area skips and first-triangle ties.
+ */
+export function rasterTurnTriangleOwnership(points: ReadonlyArray<readonly number[]>, triangles: readonly number[], queries: readonly TurnTriangleQuery[]) {
+  const key = (x: number, y: number) => `${x},${y}`;
+  const unique = new Map(queries.map(q => [key(q.x, q.y), q]));
+  const byY = new Map<number, TurnTriangleQuery[]>();
+  for (const q of unique.values()) {
+    const row = byY.get(q.point[1]);
+    if (row === undefined) byY.set(q.point[1], [q]); else row.push(q);
+  }
+  const rows = [...byY].sort((a, b) => a[0] - b[0]).map(([y, cells]) => ({ y, cells: cells.sort((a, b) => a.point[0] - b.point[0]) }));
+  const bound = <T>(values: readonly T[], value: number, coordinate: (v: T) => number, upper: boolean): number => {
+    let lo = 0, hi = values.length;
+    while (lo < hi) { const mid = (lo + hi) >>> 1, n = coordinate(values[mid]); if (n < value || (upper && n === value)) lo = mid + 1; else hi = mid; }
+    return lo;
+  };
+  const owners = new Map<string, { ids: number[]; weights: number[] }>();
+  for (let i = 0; i < triangles.length; i += 3) {
+    const ids = triangles.slice(i, i + 3), [a, b, c] = ids.map(j => points[j]);
+    if (a === undefined || b === undefined || c === undefined) continue;
+    const area = (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
+    if (area === 0) continue;
+    const minX = Math.min(a[0], b[0], c[0]), maxX = Math.max(a[0], b[0], c[0]);
+    const minY = Math.min(a[1], b[1], c[1]), maxY = Math.max(a[1], b[1], c[1]);
+    const fromY = Math.max(0, bound(rows, minY, r => r.y, false) - 1), toY = Math.min(rows.length, bound(rows, maxY, r => r.y, true) + 1);
+    for (let yi = fromY; yi < toY; yi++) {
+      const row = rows[yi].cells;
+      const fromX = Math.max(0, bound(row, minX, q => q.point[0], false) - 1), toX = Math.min(row.length, bound(row, maxX, q => q.point[0], true) + 1);
+      for (let xi = fromX; xi < toX; xi++) {
+        const q = row[xi], k = key(q.x, q.y);
+        if (owners.has(k)) continue;
+        const [x, y] = q.point;
+        const cross = (p: readonly number[], r: readonly number[]) => (p[0] - x) * (r[1] - y) - (p[1] - y) * (r[0] - x);
+        const weights = [cross(b, c) / area, cross(c, a) / area, cross(a, b) / area];
+        if (weights.every(w => w >= 0)) owners.set(k, { ids, weights });
+      }
+    }
+  }
+  return { at: (x: number, y: number) => owners.get(key(x, y)) ?? null };
+}
+
 /** Named refusal outside support; never fall back to target depth or nearest geometry. */
 export function sampleTurnTriangleField(field: TurnTriangleField, point: readonly number[], object: string): [number, number] {
   const fail = (detail: string): never => { throw new PartsError([{ code: 'RIG_TURN_SURFACE_OVERLAP_SUPPORT', object, detail: `neighbour "${field.label}" ${detail}` }]); };