rig-parts 1.85.0 → 1.86.0

package/docs/AUTHORING.md

@@ -5120,6 +5120,28 @@ wind (1, 0), then (40, 0) from 0.5 s, reads `TEXTURE_STRETCH` 32.181 (FAIL, `hai
 triangle 258), two meshes folding under `ANIMATIONS_DO_NOT_FOLD` (FAIL; none without the
 flag) and 8 `CLOTH_SETTLES` warnings for 9 (selftest `CK515`).
 
+**Joint material contact** (issue #894). Each played `SEAM_OVER_MOTION.rows[]` adds
+`joint_contact`: `status` (`REPORTED` or `SKIP`), `joints` (declared limb joint
+labels or a proven body root's bone), and, when observed, the frame counts
+`joined`, `separated` and `unavailable`, plus `reasons` with each unavailable
+reason and its observed frame indices. `JOINT_CONTACT` prints one informational
+line per pair and animation; it is never a bar and changes no PASS, warning or
+exit status. It counts core 2.84.0's `jointContact.frames` from the same seam
+render. Core reads edge-connected half-opacity material: initially overlapping
+single-component pieces are joined when their posed union connects by an edge
+or overlap, separated when it does not. A diagonal contact is separated. Missing
+setup overlap, absent drawings, disconnected material or multiple fragments are
+unavailable with core's reason. A pair without a declared named joint is
+unavailable even if its arbitrary slot drawings connect. An absent core contact
+field is unavailable when the frame count is known; absent frame counts or zero
+samples are SKIP with a reason, never invented joined frames. Unavailable is
+never added to joined. No pair or animation is a named SKIP in the output.
+Contact reports material connectivity at core's texel grid, not anatomical
+intent, sub-cell contact or the absence of local holes. Raw gap, ghost, floor
+and body-root verdicts keep their existing producer readings. Core 2.83.0's
+visible-ghost and local-support gap definitions are inherited by the 2.84.0 pin;
+contact counts do not replace or reinterpret them.
+
 **Physics seam environments** (issue #591). Default: wind [1, 0], gravity [0, 1]. Still: wind [0, 0], gravity [0, 1]. In rig-play, environment(null) returns to Default; still air requires an explicit wind [0, 0]. For a physics rig with readable declared pairs and animations, SEAM_OVER_MOTION adds optional `worlds.default` and `worlds.still` readings. They are informational raw gap/ghost cell counts (including cells below the warning floor), never new bars or warnings; neither changes PASS, exit status or the bar count. Each world records its vectors, status and rows; each row names its pair, animation, drawn/banded frames and gap/ghost maximum and worst frame, cell size and world box. Per-frame hits are not embedded in check.json. A rendered world's `dir` is relative to check.json (`seam_motion/default` or `seam_motion/still`): it retains the complete rigc render, including frames.json, frame images and each animation's seam.json with all raw hits. The directories are published with check.json only after the readings are validated; scratch is removed, and an unrendered SKIP has no directory reference. The original reading and any custom `--environment` schedule keep their existing meaning; the two reference worlds are independent of that schedule. A rig with no wind response reports Still as SKIP with its reason; no band is SKIP, never a measured zero. With no readable declared pair or animation no worlds block is written. The same declared pair list is used for both reference worlds: neighbouring limb segments, explicit seam requirements and the proven body-root declarations described below. Thigh/hem pairs are not inferred. Adding reference worlds to a nonphysics reading stays byte-identical, with no extra key, line or render; issue #686 separately adds body-root declarations and their active-reading bar. Reference renders start physics at frame 0 at 12 fps; they do not certify a composed player scene or another sampling rate. Malformed sidecars or renderer failures remain named refusals.
 
 **Steady-wind seam band** (`--wind-band`, issue #590). `check --wind-band <spec.json>` (or `build --wind-band <spec.json>`, forwarded) sweeps steady horizontal wind across a caller-declared grid and reports the contiguous `[x_lo, x_hi]` band in which each declared seam pair holds `gap <= max_gap` and `ghost <= max_ghost` across every animation in `motion.json`. Every field in `{ "spec": "rig-parts-wind-band/1", "min", "max", "step", "fps", "max_gap", "max_ghost", "pairs" }` is required — nothing falls back to `SEAM_OVER_MOTION`'s pairs, one-cell floor, or fps. At each swept step `x = min + k * step`, `check` runs `rigc render --seam <pairs> --fps <fps> --max 16 --environment` with a single-step steady schedule `{ "spec": "rigc-environment/1", "steps": [{ "t": 0, "wind": [x, 0], "gravity": [0, 1] }] }` (`seam.json` cells are in each pair's coarser drawing texels, independent of `--max`). **What it does not measure:** the sweep is steady wind (`wind: [x, 0], gravity: [0, 1]` at `t = 0`), not a time-varying gust (`x ± a` at 0.2 Hz); transient overshoot from a changing wind is not read by a steady sweep, and the band is documented and reported as the steady-wind band (`mode: "steady"`, `gravity: [0, 1]`). It is a reported line (`status: "REPORTED"`), never a bar: it prints one `WIND_BAND:` summary line plus one `WIND_BAND:` line per pair that breaks inside `[min, max]`, and writes `WIND_BAND` in `check.json` before `PASS`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "1.85.0",
+  "version": "1.86.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": {
@@ -67,7 +67,7 @@
   },
   "dependencies": {
     "ag-psd": "^31.0.2",
-    "@rig-c/core": "2.82.0"
+    "@rig-c/core": "2.84.0"
   },
   "devDependencies": {
     "@esotericsoftware/spine-core": "4.3.13",

package/src/build.ts

@@ -81,7 +81,7 @@ import {
   splitSchedule,
   untestedIntervals,
 } from './autoreplay.ts';
-import { besideIdleLine, checkSummaryLine, inputFileRecord, type InputFileRecord, CLOTH_LINE, type ClothLine, clothWarnText, frameRuns, MOTION_SEAM_LINE, type MotionSeamLine, type MotionSeamPlant, motionSeamWarnText, FOLD_LINE, type FoldsLine, LEVEL_LINE, type LevelLine, LIMB_LINE, type LimbLine, STRESS_LINE, SWEEP_LINE, type SweepLine, buildGateLines, causeLines, environmentLine, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, GATE_PROFILE, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, readCheckEnvironment, readWindBand, type PackShape, type PageEdges, readFrameSet, rigcFailed, rigcIdentity, rigcRanClause, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR, WIND_BAND_LINE, windBandLines } from './check.ts';
+import { besideIdleLine, checkSummaryLine, inputFileRecord, type InputFileRecord, CLOTH_LINE, type ClothLine, clothWarnText, frameRuns, MOTION_SEAM_LINE, type MotionSeamLine, type MotionSeamPlant, motionSeamWarnText, motionJointContactLines, FOLD_LINE, type FoldsLine, LEVEL_LINE, type LevelLine, LIMB_LINE, type LimbLine, STRESS_LINE, SWEEP_LINE, type SweepLine, buildGateLines, causeLines, environmentLine, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, GATE_PROFILE, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, readCheckEnvironment, readWindBand, type PackShape, type PageEdges, readFrameSet, rigcFailed, rigcIdentity, rigcRanClause, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR, WIND_BAND_LINE, windBandLines } from './check.ts';
 import { type Cut, type Extend, type Limb, loadConfigAndAnimations, loadConfigWithBytes, loadEarlyConfig, type Patch, type PlanEntry } from './config.ts';
 import { coreCompileGuideLine, failLine, PartsError, type Problem, refuseIfAny } from './errors.ts';
 import type { MeshQualityReport, MotionSchedule } from '@rig-c/core/mesh';
@@ -1824,7 +1824,7 @@ export function sweepCheckLines(line: SweepLine, steps: ReadonlyMap<string, { le
 export function motionSeamLines(line: MotionSeamLine, plant: MotionSeamPlant = {}): string[] {
   const unmeasured = (line.roots?.unmeasured ?? []).map(root => `root pair for ${root.limb} (${root.part}, bone "${root.bone}", parent "${root.parent}", candidates ${root.candidates.join('/')}): SKIP — ${root.reason}`);
   const rootStatus = line.roots === undefined ? '' : '; body-root gap-open+under-ghost gate ' + line.roots.status + ' (' + line.roots.pairs.length + ' pair(s)); ghost ownership from resolved draw order' + (line.roots.reason === undefined ? '' : ' — ' + line.roots.reason);
-  if (line.worlds === undefined && line.status === 'SKIP' && line.rows.length === 0 && line.pairs.every((p) => p.unread === undefined)) return [`${MOTION_SEAM_LINE}: SKIP — ${String(line.reason)}${unmeasured.length === 0 ? '' : rootStatus}`, ...unmeasured];
+  if (line.worlds === undefined && line.status === 'SKIP' && line.rows.length === 0 && line.pairs.every((p) => p.unread === undefined)) return [`${MOTION_SEAM_LINE}: SKIP — ${String(line.reason)}${unmeasured.length === 0 ? '' : rootStatus}`, ...unmeasured, ...motionJointContactLines(line)];
   const read = `${line.pairs.length} declared pair(s) in ${line.animations.length} animation(s) (${line.animations.join(', ')}), read by rigc render --seam at ${line.fps} fps on the build as played`;
   const head =
     line.status === 'SKIP'
@@ -1832,6 +1832,7 @@ export function motionSeamLines(line: MotionSeamLine, plant: MotionSeamPlant = {
       : `${MOTION_SEAM_LINE}: ${line.status} — ${read}: ${line.warnings} warning(s), never a bar${rootStatus}; ${line.floor}`;
   return [
     head,
+    ...motionJointContactLines(line),
     ...unmeasured,
     ...line.pairs.filter((p) => p.unread !== undefined).map((p) => `seam "${p.pair}" (${p.declared.join('; ')}): not read — ${String(p.unread)}`),
     ...line.rows.filter((r) => r.status === 'skip').map((r) => `seam "${r.pair}" in "${r.animation}": SKIP — rigc read no band on any of the ${r.drawn} frame(s) both slots draw, so there is no seam to read`),

package/src/check.ts

@@ -83,6 +83,7 @@ import { baseAnchorMoves, type AnchorRegion } from './baseanchor.ts';
  * the last idle frame is refused unless it sits at t = duration (within
  * `TIME_SLACK`, issue #244).
  */
+import { jointContactReading, type JointContactReading } from './jointcontact.ts';
 import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
 import type { Viewport as RootCoverageViewport } from '@rig-c/core/render-shared';
@@ -4341,6 +4342,8 @@ export interface MotionSeamPair {
   a: string;
   b: string;
   declared: string[];
+  /** Explicit limb joint labels or a proven body root's bone; never inferred for arbitrary seams. */
+  joints?: string[];
   /** Why the pair is not read: a slot `rig.json` does not have. */
   unread?: string;
   /** Issue #686: segment-zero provenance and its immediate named body carrier. */
@@ -4374,6 +4377,8 @@ export interface MotionSeamSelection {
 export interface MotionSeamRow {
   pair: string;
   animation: string;
+  /** Report-only core connectivity, independent of raw counts and verdicts. */
+  joint_contact?: JointContactReading;
   /** rigc's: `skip` when no frame has a band to read — nothing measured, not a seam that held. */
   status: 'read' | 'skip';
   /** Frames both slots draw, and of those the frames read (rigc's `drawn`, `banded`). */
@@ -4426,10 +4431,12 @@ export function motionSeamPairs(parts: PartsFile, seams: ReadonlyArray<{ name: s
 export function motionSeamSelection(parts: PartsFile, seams: ReadonlyArray<{ name: string; part: string; neighbour: string }>, rig?: Record<string, unknown>, readSetup?: (candidates: readonly MotionSeamPair[]) => readonly MotionRootSetupRow[]): MotionSeamSelection {
   const out: MotionSeamPair[] = [];
   const unmeasuredRoots: MotionUnmeasuredRoot[] = [];
-  const add = (a: string, b: string, declared: string): void => {
+  const add = (a: string, b: string, declared: string, joint?: string): void => {
     const hit = out.find((p) => (p.a === a && p.b === b) || (p.a === b && p.b === a));
-    if (hit !== undefined) hit.declared.push(declared);
-    else out.push({ pair: `${a}|${b}`, a, b, declared: [declared] });
+    if (hit !== undefined) {
+      hit.declared.push(declared);
+      if (joint !== undefined && !hit.joints?.includes(joint)) (hit.joints ??= []).push(joint);
+    } else out.push({ pair: `${a}|${b}`, a, b, declared: [declared], ...(joint === undefined ? {} : { joints: [joint] }) });
   };
   const limbs: string[] = [];
   for (const p of parts.parts) if (p.limb !== undefined && !limbs.includes(p.limb.name)) limbs.push(p.limb.name);
@@ -4437,7 +4444,7 @@ export function motionSeamSelection(parts: PartsFile, seams: ReadonlyArray<{ nam
     const segs = parts.parts.filter((p) => p.limb?.name === limb).sort((x, y) => (x.limb as LimbRecord).segment - (y.limb as LimbRecord).segment);
     for (let i = 1; i < segs.length; i++) {
       const lower = segs[i].limb as LimbRecord;
-      add(segs[i - 1].name, segs[i].name, `config.limbs.${limb} segment ${lower.segment}${lower.joint === undefined ? '' : `, joint "${lower.joint}"`}`);
+      add(segs[i - 1].name, segs[i].name, `config.limbs.${limb} segment ${lower.segment}${lower.joint === undefined ? '' : `, joint "${lower.joint}"`}`, lower.joint);
     }
   }
   for (const r of seams) add(r.part, r.neighbour, `requirement "${r.name}" (seam)`);
@@ -4473,7 +4480,7 @@ export function motionSeamSelection(parts: PartsFile, seams: ReadonlyArray<{ nam
     }
   }
   for (const root of selected) {
-    add(root.a, root.b, root.declared[0]);
+    add(root.a, root.b, root.declared[0], root.root?.bone);
     const pair = out.find(p => (p.a === root.a && p.b === root.b) || (p.a === root.b && p.b === root.a));
     if (pair !== undefined) pair.root = root.root;
   }
@@ -4578,7 +4585,7 @@ function motionRootCandidates(parts: PartsFile, rig: Record<string, unknown>): M
     }
     for (const { part: body } of eligible) out.push({ pair: body.name + '|' + root.name, a: body.name, b: root.name,
       declared: ['config.limbs.' + limb + ' segment 0, body carrier "' + parent + '" from ' + body.from],
-      root: { limb, bone: l.bone, parent } });
+      joints: [l.bone], root: { limb, bone: l.bone, parent } });
   }
   refuseIfAny(problems);
   return out;
@@ -4923,11 +4930,14 @@ function readSeamRows(dir: string, animations: readonly string[], fps: number, p
           }
         }
       }
+      const contact = setup ? undefined : jointContactReading(p.jointContact, want.joints ?? [], set.written ?? set.sampled, at, problems);
+      if (contact === null) return;
       worldRows?.push({ pair: want.pair, animation, status: p.status, drawn: p.drawn, banded: p.banded, gap: kinds.gap, ghost: kinds.ghost });
       const opens = [...over.keys()].sort((x, y) => x - y);
       rows.push({
         pair: want.pair,
         animation,
+        ...(setup ? {} : { joint_contact: contact }),
         status: p.status,
         drawn: p.drawn,
         banded: p.banded,
@@ -5081,6 +5091,21 @@ export function enrichMotionSeamPoses(dir: string, rig: Record<string, unknown>,
   }
 }
 
+/** One informational line per observed pair/animation; missing readings are named SKIP. */
+export function motionJointContactLines(line: MotionSeamLine): string[] {
+  if (line.rows.length === 0) return ['JOINT_CONTACT: SKIP — ' + (line.reason ?? 'no sampled pair/animation reading')];
+  const lines = line.rows.map(row => {
+    const c = row.joint_contact;
+    const head = 'JOINT_CONTACT: "' + row.pair + '" in "' + row.animation + '"';
+    if (c === undefined || c.status === 'SKIP') return head + ': SKIP — ' + (c?.reason ?? 'no contact observation');
+    return head + ', joint ' + (c.joints.length === 0 ? 'unavailable' : c.joints.map(n => JSON.stringify(n)).join(', ')) +
+      ': joined ' + c.joined + ', separated ' + c.separated + ', unavailable ' + c.unavailable + ' frame(s)' +
+      (c.reasons.length === 0 ? '' : '; ' + c.reasons.map(r => r.reason + (r.frames === undefined ? '' : ' on frames ' + frameRuns(r.frames))).join('; ')) + '; report only';
+  });
+  for (const pair of line.pairs) if (!line.rows.some(row => row.pair === pair.pair)) lines.push('JOINT_CONTACT: "' + pair.pair + '": SKIP — ' + (pair.unread ?? line.reason ?? 'no sampled animation'));
+  return lines;
+}
+
 /** One warning as the console prints it (issue #493's form, the floor's clause after it). */
 export function motionSeamWarnText(r: MotionSeamRow): string {
   const pose = r.pose_at_worst;

package/src/jointcontact.ts

@@ -0,0 +1,59 @@
+/** Report core's material connectivity; no count here participates in a bar. */
+import { PartsError, type Problem } from './errors.ts';
+
+export interface JointContactReading {
+  status: 'REPORTED' | 'SKIP';
+  joints: string[];
+  joined?: number;
+  separated?: number;
+  unavailable?: number;
+  reasons: Array<{ reason: string; frames?: number[] }>;
+  reason?: string;
+}
+const record = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** Count only producer observations; invalid input adds a problem and yields no reading when a collector is supplied. */
+export function jointContactReading(raw: unknown, joints: readonly string[], sampled: unknown, object: string, problems?: Problem[]): JointContactReading | null {
+  const names = [...new Set(joints)];
+  const fail = (detail: string): null => {
+    const problem = { code: 'FRAMES_SIDECAR', object, detail: 'jointContact: ' + detail };
+    if (problems === undefined) throw new PartsError([problem]);
+    problems.push(problem);
+    return null;
+  };
+  const knownCount = typeof sampled === 'number' && Number.isSafeInteger(sampled) && sampled >= 0 ? sampled : undefined;
+  if (raw === undefined) {
+    const reason = names.length === 0 ? 'pair has no declared named joint' : 'core seam reading has no jointContact.frames';
+    return knownCount === undefined || knownCount === 0
+      ? { status: 'SKIP', joints: names, reasons: [], reason: knownCount === 0 ? 'no sampled frames' : 'sample count unavailable: ' + reason }
+      : { status: 'REPORTED', joints: names, joined: 0, separated: 0, unavailable: knownCount, reasons: [{ reason }] };
+  }
+  if (!record(raw) || !Array.isArray(raw.frames)) return fail('requires { frames: [...] }');
+  if (knownCount !== undefined && raw.frames.length !== knownCount) return fail('has ' + raw.frames.length + ' frame(s); frames.json records ' + knownCount);
+  const frames: Array<{ index: number; time: number; status: 'joined' | 'separated' | 'unavailable'; reason: string | null }> = [];
+  for (const f of raw.frames) {
+    if (!record(f) || typeof f.index !== 'number' || !Number.isSafeInteger(f.index) || f.index < 0 ||
+        typeof f.time !== 'number' || !Number.isFinite(f.time) || f.time < 0 ||
+        (f.status !== 'joined' && f.status !== 'separated' && f.status !== 'unavailable') ||
+        (f.status === 'unavailable' ? typeof f.reason !== 'string' || f.reason.trim() === '' : f.reason !== null)) return fail('requires nonnegative index/time, joined/separated with null reason, or unavailable with a nonempty reason');
+    const previous = frames.at(-1);
+    if (previous !== undefined && (f.index <= previous.index || f.time <= previous.time)) return fail('frame indices and times must increase strictly');
+    frames.push({ index: f.index, time: f.time, status: f.status, reason: f.reason as string | null });
+  }
+  if (frames.length === 0) return { status: 'SKIP', joints: names, reasons: [], reason: 'no sampled frames' };
+  const out: JointContactReading = { status: 'REPORTED', joints: names, joined: 0, separated: 0, unavailable: 0, reasons: [] };
+  for (const f of frames) {
+    const status = names.length === 0 ? 'unavailable' : f.status;
+    const reason = names.length === 0 ? 'pair has no declared named joint' : f.reason;
+    if (status === 'joined') out.joined = (out.joined ?? 0) + 1;
+    else if (status === 'separated') out.separated = (out.separated ?? 0) + 1;
+    else {
+      out.unavailable = (out.unavailable ?? 0) + 1;
+      const why = reason as string;
+      let hit = out.reasons.find(r => r.reason === why);
+      if (hit === undefined) { hit = { reason: why, frames: [] }; out.reasons.push(hit); }
+      hit.frames?.push(f.index);
+    }
+  }
+  return out;
+}