@rig-c/parts 1.60.2 → 1.61.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/check.ts CHANGED
@@ -78,6 +78,8 @@
78
78
  * `TIME_SLACK`, issue #244).
79
79
  */
80
80
  import { createHash } from 'node:crypto';
81
+ import { createRequire } from 'node:module';
82
+ import type { Frame as RootCoverageFrame, Piece as RootCoveragePiece, Viewport as RootCoverageViewport } from 'rig-c/render-shared';
81
83
  import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
82
84
  import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
83
85
  import { measureRecomposite, type RecompositeFigures, recompositeRecord, scenePhrase, sourceInRig } from './assemble.ts';
@@ -129,7 +131,8 @@ import {
129
131
  } from './instruments.ts';
130
132
  import { type AlternatePartsRecord, FRONT_SUFFIX, type LimbRecord, type PartRecord, type PartsFile, readParts } from './parts.ts';
131
133
  import { ARM_SPLIT_MIGRATION, poseRigBonesForDrawn, type RigBone, SETS_FILE } from './rig.ts';
132
- import { turnTwin } from './turn.ts';
134
+ import { TURN_BONE, turnConstraintName, turnTwin } from './turn.ts';
135
+ import { ROOT_BONE } from './config.ts';
133
136
  import {
134
137
  aimLine,
135
138
  contactLine,
@@ -1219,6 +1222,8 @@ export function motionHeat(frames: readonly Raster[]): Raster {
1219
1222
  }
1220
1223
 
1221
1224
  export interface SeamFigures {
1225
+ /** Authored support size for a canonical union; absent for the unchanged auto reading. */
1226
+ denominator?: number;
1222
1227
  mean: number;
1223
1228
  over40: number;
1224
1229
  over80: number;
@@ -1454,6 +1459,8 @@ export function seamFigures(
1454
1459
  background: readonly [number, number, number, number],
1455
1460
  map: ScaleTranslate = rigToFrameMap(stage, composite.height, vp),
1456
1461
  scene = false,
1462
+ effect?: Uint8Array,
1463
+ sourceGrid = false,
1457
1464
  ): SeamFigures {
1458
1465
  const [W, H] = [composite.width, composite.height];
1459
1466
  const src = newFloatImage(W, H, 3);
@@ -1470,11 +1477,23 @@ export function seamFigures(
1470
1477
  const counted: number[] = [];
1471
1478
  const countedDiff: number[] = [];
1472
1479
  const n = vp.pixelWidth * vp.pixelHeight;
1480
+ if (effect !== undefined && effect.length !== n) refuseIfAny([{ code: 'CHECK_SEAM_SUPPORT', object: 'the effect mask', detail: 'does not have the source grid size' }]);
1473
1481
  // Issue #242: on a scene, the frame columns and rows whose composite sample reaches the painting's border.
1474
1482
  const onEdge = (i: number, t: number, s: number, size: number): boolean => {
1475
1483
  const k = Math.floor((i - t) / s);
1476
1484
  return k <= 0 || k + 1 >= size - 1;
1477
1485
  };
1486
+ // Original authored border, evaluated on its own cells, not on union padding.
1487
+ let authoredA = W * H;
1488
+ if (sourceGrid) {
1489
+ if (vp.scale !== 1 || ![map.tx, map.ty].every(x => Number.isSafeInteger(x) && Math.fround(x) === x))
1490
+ refuseIfAny([{ code: 'CHECK_SEAM_DOMAIN', object: 'the source-grid sample map', detail: 'requires exact integer offsets at scale 1' }]);
1491
+ if (scene) {
1492
+ authoredA = 0;
1493
+ for (let v = 0; v < H; v++) for (let u = 0; u < W; u++)
1494
+ if (!onEdge(u, 0, 1, W) && !onEdge(v, 0, 1, H)) authoredA++;
1495
+ }
1496
+ }
1478
1497
  const edgeCol = scene ? Array.from({ length: vp.pixelWidth }, (_, x) => onEdge(x, map.tx, map.sx, W)) : null;
1479
1498
  const edgeRow = scene ? Array.from({ length: vp.pixelHeight }, (_, y) => onEdge(y, map.ty, map.sy, H)) : null;
1480
1499
  for (let p = 0; p < n; p++) {
@@ -1484,11 +1503,16 @@ export function seamFigures(
1484
1503
  const d = Math.abs(w - frame.data[p * 4 + c]);
1485
1504
  if (d > m) m = d;
1486
1505
  }
1487
- if (edgeCol !== null && edgeRow !== null && (edgeCol[p % vp.pixelWidth] || edgeRow[Math.floor(p / vp.pixelWidth)])) {
1506
+ const u = p % vp.pixelWidth - map.tx, v = Math.floor(p / vp.pixelWidth) - map.ty;
1507
+ const excluded = sourceGrid && scene
1508
+ ? u < 0 || v < 0 || u >= W || v >= H || onEdge(u, 0, 1, W) || onEdge(v, 0, 1, H)
1509
+ : edgeCol !== null && edgeRow !== null && (edgeCol[p % vp.pixelWidth] || edgeRow[Math.floor(p / vp.pixelWidth)]);
1510
+ if (excluded) {
1488
1511
  borderPx++;
1489
1512
  if (m > SEAM_PX_LEVEL) borderOver40++;
1490
1513
  continue;
1491
1514
  }
1515
+ if (effect !== undefined && effect[p] === 0) continue;
1492
1516
  sum += m;
1493
1517
  if (m > SEAM_PX_LEVEL) {
1494
1518
  over40++;
@@ -1497,13 +1521,357 @@ export function seamFigures(
1497
1521
  }
1498
1522
  if (m > SEAM_PX_LEVEL_HIGH) over80++;
1499
1523
  }
1500
- return { mean: scene ? (n - borderPx === 0 ? 0 : sum / (n - borderPx)) : sum / n, over40, over80, border: scene ? { framePx: borderPx, over40: borderOver40 } : null, counted, countedDiff, map };
1524
+ const denominator = sourceGrid ? authoredA : n - borderPx;
1525
+ if (denominator <= 0) refuseIfAny([{ code: 'CHECK_SEAM_SUPPORT', object: 'the seam mean denominator', detail: 'has no source cells after the declared scene-border exclusion' }]);
1526
+ return { ...(sourceGrid ? { denominator } : {}), mean: sum / denominator, over40, over80, border: scene ? { framePx: borderPx, over40: borderOver40 } : null, counted, countedDiff, map };
1527
+ }
1528
+
1529
+ export interface SeamSupportUnavailable {
1530
+ code: 'RENDERER_API_UNAVAILABLE' | 'SOURCE_RIG_UNREADABLE' | 'SOURCE_SKIN_UNSUPPORTED' |
1531
+ 'SOURCE_ATTACHMENT_MISSING' | 'SOURCE_ATTACHMENT_AMBIGUOUS' | 'SOURCE_MAPPING_UNSUPPORTED' |
1532
+ 'SOURCE_IMAGE_UNREADABLE' | 'POSE_EXPORT_UNREADABLE' | 'POSE_MISMATCH' |
1533
+ 'POSE_ATTACHMENT_MISSING' | 'RASTER_READ_UNAVAILABLE';
1534
+ slot?: string;
1535
+ attachment?: string;
1536
+ feature?: 'clipping' | 'sequence-or-non-image-attachment';
1537
+ }
1538
+
1539
+ class SeamSupportError extends Error {
1540
+ constructor(readonly reason: SeamSupportUnavailable) { super(reason.code); }
1541
+ }
1542
+
1543
+ /** Sort object keys only; array order is part of UV/topology/weight semantics. */
1544
+ function seamSourceValue(value: unknown): unknown {
1545
+ if (Array.isArray(value)) return value.map(seamSourceValue);
1546
+ if (isRecord(value)) return Object.fromEntries(Object.keys(value).sort().map(k => [k, seamSourceValue(value[k])]));
1547
+ return value;
1548
+ }
1549
+
1550
+ /**
1551
+ * One semantic drawing identity, never an atlas or a frame ordinal. Source
1552
+ * UVs, triangles, weights and all other declared attachment fields stay in the
1553
+ * signature. Only the image path is replaced by its resolved OWN image content;
1554
+ * page UVs, packed page bytes, and piece bookkeeping are not arguments.
1555
+ */
1556
+ export function seamDrawingSignature(input: {
1557
+ slot: string; attachment: string; source: Record<string, unknown>;
1558
+ image: { width: number; height: number; rgba_sha256: string };
1559
+ vertices: readonly number[]; color: readonly number[];
1560
+ }): string {
1561
+ const source = Object.fromEntries(Object.entries(input.source).filter(([key]) => key !== 'image'));
1562
+ return JSON.stringify(seamSourceValue({ slot: input.slot, attachment: input.attachment, source, image: input.image, vertices: input.vertices, color: input.color }));
1563
+ }
1564
+
1565
+ /** Resolve only the actually selected default-skin identity, not a filename suffix. */
1566
+ export function seamSourceAttachment(rig: Record<string, unknown>, slot: string, attachment: string): Record<string, unknown> {
1567
+ const skins = isRecord(rig.skins) ? rig.skins : null;
1568
+ const skin = skins !== null && isRecord(skins.default) ? skins.default : null;
1569
+ if (skin === null) throw new SeamSupportError({ code: 'SOURCE_SKIN_UNSUPPORTED', slot, attachment });
1570
+ const drawings = isRecord(skin[slot]) ? skin[slot] : {};
1571
+ const matches = Object.entries(drawings).filter(([key, value]) => isRecord(value) && (typeof value.name === 'string' ? value.name : key) === attachment);
1572
+ if (matches.length !== 1) throw new SeamSupportError({ code: matches.length === 0 ? 'SOURCE_ATTACHMENT_MISSING' : 'SOURCE_ATTACHMENT_AMBIGUOUS', slot, attachment });
1573
+ const source = matches[0][1];
1574
+ if (!isRecord(source) || !['region', 'mesh'].includes(typeof source.type === 'string' ? source.type : 'region') || typeof source.image !== 'string' || source.image.length === 0 || source.sequence !== undefined) {
1575
+ throw new SeamSupportError({ code: 'SOURCE_MAPPING_UNSUPPORTED', slot, attachment, feature: 'sequence-or-non-image-attachment' });
1576
+ }
1577
+ return source;
1578
+ }
1579
+
1580
+ /** #705: ordered contributor identities on the fixed source grid, before residuals. */
1581
+ export interface SeamSupport {
1582
+ reference: Int32Array;
1583
+ posed: Int32Array;
1584
+ referenceDepth: Uint8Array;
1585
+ posedDepth: Uint8Array;
1586
+ unavailable?: SeamSupportUnavailable;
1587
+ drawings?: Array<{ scope: 'reference' | 'posed'; name: string; identity: string; order: number; geometry: string; art: string; source_png_sha256?: string }>;
1588
+ }
1589
+
1590
+ export interface SeamEffects {
1591
+ mask: Uint8Array;
1592
+ /** Indices into SEAM_EFFECT_REASONS, used only for the raw pair audit. */
1593
+ cellReasons: Uint8Array;
1594
+ reasons: { reference_changed: number; posed_changed: number; no_art_or_singleton: number; unavailable: number; inherited: number };
1595
+ changes: Array<{ scope: 'reference' | 'posed'; drawing: string; reasons: string[] }>;
1596
+ }
1597
+
1598
+ const SEAM_EFFECT_REASONS = ['reference_changed', 'posed_changed', 'no_art_or_singleton', 'unavailable', 'inherited'] as const;
1599
+
1600
+ /** Exact stack equality proves inheritance; missing/singleton provenance never proves exclusion. */
1601
+ export function seamEffectSelection(base: SeamSupport, selected: SeamSupport): SeamEffects {
1602
+ const n = base.reference.length;
1603
+ if ([base.posed, base.referenceDepth, base.posedDepth, selected.reference, selected.posed, selected.referenceDepth, selected.posedDepth].some(a => a.length !== n)) {
1604
+ refuseIfAny([{ code: 'CHECK_SEAM_SUPPORT', object: 'the alternate effect grid', detail: 'does not have the base source grid size' }]);
1605
+ }
1606
+ const mask = new Uint8Array(n), cellReasons = new Uint8Array(n);
1607
+ const reasons: SeamEffects['reasons'] = { reference_changed: 0, posed_changed: 0, no_art_or_singleton: 0, unavailable: 0, inherited: 0 };
1608
+ for (let q = 0; q < n; q++) {
1609
+ const reason: keyof typeof reasons = base.unavailable !== undefined || selected.unavailable !== undefined ? 'unavailable'
1610
+ : base.reference[q] !== selected.reference[q] ? 'reference_changed'
1611
+ : base.posed[q] !== selected.posed[q] ? 'posed_changed'
1612
+ : Math.min(base.referenceDepth[q], selected.referenceDepth[q]) < 2 ? 'no_art_or_singleton' : 'inherited';
1613
+ reasons[reason]++;
1614
+ cellReasons[q] = SEAM_EFFECT_REASONS.indexOf(reason);
1615
+ if (reason !== 'inherited') mask[q] = 1;
1616
+ }
1617
+ const changes: SeamEffects['changes'] = [];
1618
+ const before = base.drawings ?? [], after = selected.drawings ?? [];
1619
+ for (const scope of ['reference', 'posed'] as const) {
1620
+ const names = [...new Set([...before, ...after].filter(d => d.scope === scope).map(d => d.name))];
1621
+ for (const name of names) {
1622
+ const b = before.find(d => d.scope === scope && d.name === name), a = after.find(d => d.scope === scope && d.name === name);
1623
+ const fields = b === undefined ? ['added'] : a === undefined ? ['hidden/removed'] :
1624
+ (['identity', 'order', 'geometry', 'art'] as const).filter(k => b[k] !== a[k]);
1625
+ if (fields.length > 0) changes.push({ scope, drawing: name, reasons: fields });
1626
+ }
1627
+ }
1628
+ return { mask, cellReasons, reasons, changes };
1629
+ }
1630
+
1631
+ /** Public state evidence excludes raw candidate bytes: compiler image paths vary with output location. */
1632
+ export interface SeamStateBounds {
1633
+ state: string;
1634
+ frames: number;
1635
+ pieces: number;
1636
+ bounds: { minX: number; minY: number; maxX: number; maxY: number } | null;
1637
+ pose_sha256: string;
1638
+ }
1639
+
1640
+ /** The promised read facade (rig-c >=2.69.0 <3); optional Spine registration
1641
+ * follows rigc's own package-root resolution. No candidate error selects a
1642
+ * different API. Importing check, or constructing a root-free reader, loads none.
1643
+ */
1644
+ type OfficialRenderer = typeof import('rig-c/render-shared');
1645
+ function officialRenderer(): OfficialRenderer {
1646
+ const require = createRequire(import.meta.url);
1647
+ const coreRoot = dirname(require.resolve('rig-c/package.json'));
1648
+ let runtimePresent = false;
1649
+ try { require.resolve('@esotericsoftware/spine-core/package.json', { paths: [coreRoot] }); runtimePresent = true; } catch { /* Optional runtime is absent, as in rigc's launcher. */ }
1650
+ if (runtimePresent) require('rig-c/render');
1651
+ return require('rig-c/render-shared') as OfficialRenderer;
1652
+ }
1653
+
1654
+ /** One decoder/poser lifetime per state; retain only finite bounds and identities, never atlas pages or rasters. */
1655
+ export function seamStateBounds(build: string, state: string): SeamStateBounds {
1656
+ try {
1657
+ type Renderer = OfficialRenderer;
1658
+ const api = officialRenderer();
1659
+ if (['loadCandidate', 'throughPoser', 'sampleAnimation'].some(k => typeof api[k as keyof Renderer] !== 'function')) throw new Error('official posed-piece API unavailable');
1660
+ const skeleton = join(build, 'skeleton.json'), atlas = join(build, 'skeleton.atlas');
1661
+ const skeletonText = readFileSync(skeleton, 'utf8'), atlasText = readFileSync(atlas, 'utf8');
1662
+ const loaded = api.loadCandidate({ skeletonText, atlasText, atlasDir: build, label: 'setup seam union' }, { skeleton, atlas }, undefined);
1663
+ const frames = api.throughPoser(loaded.choice, poser => api.sampleAnimation(poser, 'still', STILL_FPS, { geometry: true })).value;
1664
+ if (frames.length === 0) throw new Error('no actual still frames');
1665
+ let bounds: SeamStateBounds['bounds'] = null, pieces = 0;
1666
+ const digest = createHash('sha256');
1667
+ for (const frame of frames) {
1668
+ if (!Number.isSafeInteger(frame.index) || !Number.isFinite(frame.time)) throw new Error('unreadable still identity');
1669
+ digest.update(JSON.stringify([frame.index, frame.time]));
1670
+ for (const piece of frame.pieces) {
1671
+ if (piece.world.length === 0 || piece.world.length % 2 !== 0 || !piece.world.every(Number.isFinite)) throw new Error('unreadable drawn vertices');
1672
+ pieces++;
1673
+ digest.update(JSON.stringify([piece.slot, piece.world, piece.tint]));
1674
+ for (let i = 0; i < piece.world.length; i += 2) {
1675
+ const x = piece.world[i], y = piece.world[i + 1];
1676
+ if (bounds === null) bounds = { minX: x, minY: y, maxX: x, maxY: y };
1677
+ else { bounds.minX = Math.min(bounds.minX, x); bounds.minY = Math.min(bounds.minY, y); bounds.maxX = Math.max(bounds.maxX, x); bounds.maxY = Math.max(bounds.maxY, y); }
1678
+ }
1679
+ }
1680
+ }
1681
+ return { state, frames: frames.length, pieces, bounds,
1682
+ pose_sha256: digest.digest('hex') };
1683
+ } catch {
1684
+ refuseIfAny([{ code: 'CHECK_SEAM_DOMAIN', object: 'setup seam union state ' + JSON.stringify(state), detail: 'official selected candidate/still drawn-piece bounds are unavailable; no guessed or empty bounds are substituted' }]);
1685
+ throw new Error('unreachable');
1686
+ }
1687
+ }
1688
+
1689
+ /** Source-relative integer lattice: odd-width canvases keep their half-integer world origin. */
1690
+ export function seamUnionViewport(stage: StageBox, states: readonly Pick<SeamStateBounds, 'state' | 'bounds'>[]): Viewport {
1691
+ const bad = (detail: string): never => { refuseIfAny([{ code: 'CHECK_SEAM_DOMAIN', object: 'the common setup-seam union', detail }]); throw new Error('unreachable'); };
1692
+ if (![stage.x, stage.y, stage.width, stage.height].every(Number.isFinite) ||
1693
+ !Number.isSafeInteger(stage.width) || !Number.isSafeInteger(stage.height) || stage.width <= 0 || stage.height <= 0 || states.length === 0) return bad('requires finite authored bounds and actual state readings');
1694
+ let minX = stage.x, minY = stage.y, maxX = stage.x + stage.width, maxY = stage.y + stage.height;
1695
+ if (![maxX, maxY].every(Number.isFinite)) return bad('authored endpoints are not finite');
1696
+ for (const state of states) {
1697
+ const b = state.bounds;
1698
+ if (b === null) continue; // Actual empty drawn roster; the authored stage remains in U.
1699
+ if (![b.minX, b.minY, b.maxX, b.maxY].every(Number.isFinite) || b.maxX < b.minX || b.maxY < b.minY) return bad('state ' + JSON.stringify(state.state) + ' has unavailable finite bounds');
1700
+ minX = Math.min(minX, b.minX); minY = Math.min(minY, b.minY); maxX = Math.max(maxX, b.maxX); maxY = Math.max(maxY, b.maxY);
1701
+ }
1702
+ const left = Math.floor(minX - stage.x), bottom = Math.floor(minY - stage.y);
1703
+ const right = Math.ceil(maxX - stage.x), top = Math.ceil(maxY - stage.y);
1704
+ const width = right - left, height = top - bottom;
1705
+ const x = stage.x + left, y = stage.y + bottom;
1706
+ if (![left, bottom, right, top, width, height, -left, top - stage.height].every(n => Number.isSafeInteger(n) && Math.fround(n) === n) ||
1707
+ width <= 0 || height <= 0 || x > minX || y > minY || x + width < maxX || y + height < maxY ||
1708
+ x - stage.x !== left || y - stage.y !== bottom || x + width - stage.x !== right || y + height - stage.y !== top) return bad('union endpoints/offsets cannot preserve the exact finite source-relative float32 sample map');
1709
+ const cells = width * height, authored = stage.width * stage.height;
1710
+ // Known live lower bound: two RGBA still frames (8U), RGB Float32 warp (12U),
1711
+ // RGB Float32 source (12D). Refuse before these alone exceed the existing6GiB
1712
+ // execution guard (#677/#705); this is not a claim that other heap/atlas work fits that guard.
1713
+ const knownBytes = 20 * cells + 12 * authored;
1714
+ if (!Number.isSafeInteger(cells) || !Number.isSafeInteger(knownBytes) || knownBytes > 6 * 1024 ** 3) return bad('union ' + width + 'x' + height + ' requires at least ' + knownBytes + ' known raster bytes, beyond the existing 6 GiB execution budget');
1715
+ return { x, y, width, height, scale: 1, pixelWidth: width, pixelHeight: height };
1716
+ }
1717
+
1718
+ /** U is a picture, not the mean denominator. Strict outside metadata checks every actual still frame. */
1719
+ export function seamCanonicalViewport(stage: StageBox, vp: Viewport, sidecar: unknown, expected: Viewport = { ...stage, scale: 1, pixelWidth: stage.width, pixelHeight: stage.height }): Viewport {
1720
+ const pinned = isRecord(sidecar) && isRecord(sidecar.pinned) ? sidecar.pinned : null;
1721
+ const map = rigToFrameMap(stage, stage.height, expected);
1722
+ if (![map.tx, map.ty].every(n => Number.isSafeInteger(n) && Math.fround(n) === n) ||
1723
+ Object.keys(expected).some(k => vp[k as keyof Viewport] !== expected[k as keyof Viewport]) || pinned?.by !== '--viewport' || !Array.isArray(pinned.outside) || pinned.outside.length !== 0) {
1724
+ refuseIfAny([{ code: 'CHECK_SEAM_DOMAIN', object: 'the source-anchored setup seam', detail: `requires the fixed common union at scale1 and official pinned.outside=[]; viewport ${JSON.stringify(vp)}, pinned ${JSON.stringify(pinned)}; an incomplete or unavailable union cannot pass` }]);
1725
+ }
1726
+ return expected;
1727
+ }
1728
+
1729
+ /** Collision-free interning: a stack is its exact preceding stack and drawing identity. */
1730
+ class SeamStacks {
1731
+ private readonly signatures = new Map<string, number>();
1732
+ private readonly links = new Map<string, number>();
1733
+ append(previous: number, signature: string): number {
1734
+ let drawing = this.signatures.get(signature);
1735
+ if (drawing === undefined) { drawing = this.signatures.size + 1; this.signatures.set(signature, drawing); }
1736
+ const key = `${previous},${drawing}`;
1737
+ let id = this.links.get(key);
1738
+ if (id === undefined) {
1739
+ id = this.links.size + 1;
1740
+ if (id > 0x7fffffff) refuseIfAny([{ code: 'CHECK_SEAM_SUPPORT', object: 'the contributor stack', detail: 'exceeds the signed 32-bit index domain' }]);
1741
+ this.links.set(key, id);
1742
+ }
1743
+ return id;
1744
+ }
1745
+ }
1746
+
1747
+ type SeamPlaced = PlacedAlpha & { png?: string };
1748
+
1749
+ /**
1750
+ * Reference alpha uses the same 2x2 gather as seamPairRows. Actual support is
1751
+ * rasterised by the official renderer, never by a copied triangle algorithm.
1752
+ * Full ordered stacks retain third-party occlusion and gathering dependencies,
1753
+ * including translucent layers; unchanged names alone cannot establish inheritance.
1754
+ */
1755
+ function seamSupport(build: string, rigPath: string, set: FrameSet, placed: readonly SeamPlaced[], stacks: SeamStacks, stage: StageBox): SeamSupport {
1756
+ const [W, H] = [set.viewport.pixelWidth, set.viewport.pixelHeight];
1757
+ const n = W * H;
1758
+ const support: SeamSupport = { reference: new Int32Array(n), posed: new Int32Array(n), referenceDepth: new Uint8Array(n), posedDepth: new Uint8Array(n), drawings: [] };
1759
+ const touched = new Int32Array(n);
1760
+ const map = rigToFrameMap(stage, stage.height, set.viewport);
1761
+ placed.forEach((p, i) => {
1762
+ const art = createHash('sha256').update(p.image.data).digest('hex');
1763
+ const shape = [p.x, p.y, p.image.width, p.image.height];
1764
+ const signature = JSON.stringify(['reference', p.name, shape, art]);
1765
+ support.drawings?.push({ scope: 'reference', name: p.name, identity: p.name, order: i, geometry: createHash('sha256').update(JSON.stringify(shape)).digest('hex'), art });
1766
+ for (let y = 0; y < p.image.height; y++) for (let x = 0; x < p.image.width; x++) {
1767
+ if (p.image.data[(y * p.image.width + x) * 4 + 3] === 0) continue;
1768
+ // Each integer source sample gathers its own and the next row/column.
1769
+ for (const v of [p.y + y - 1, p.y + y]) for (const u of [p.x + x - 1, p.x + x]) {
1770
+ if (u < 0 || v < 0 || u >= stage.width || v >= stage.height) continue;
1771
+ const fx = u + map.tx, fy = v + map.ty;
1772
+ if (fx < 0 || fy < 0 || fx >= W || fy >= H) continue;
1773
+ const q = fy * W + fx;
1774
+ if (touched[q] === i + 1) continue;
1775
+ touched[q] = i + 1;
1776
+ support.reference[q] = stacks.append(support.reference[q], signature);
1777
+ support.referenceDepth[q] = Math.min(255, support.referenceDepth[q] + 1);
1778
+ }
1779
+ }
1780
+ });
1781
+ let boundary: SeamSupportUnavailable = { code: 'RENDERER_API_UNAVAILABLE' };
1782
+ try {
1783
+ type Renderer = OfficialRenderer;
1784
+ const api = officialRenderer();
1785
+ if (['loadCandidate', 'throughPoser', 'sampleAnimation', 'pageFor', 'projector', 'rasterisePiece'].some(k => typeof api[k as keyof Renderer] !== 'function')) throw new SeamSupportError(boundary);
1786
+ boundary = { code: 'SOURCE_RIG_UNREADABLE' };
1787
+ const sourceRig: unknown = JSON.parse(readFileSync(rigPath, 'utf8'));
1788
+ if (!isRecord(sourceRig) || (sourceRig.images !== undefined && typeof sourceRig.images !== 'string')) throw new SeamSupportError(boundary);
1789
+ const imageHome = resolve(dirname(rigPath), typeof sourceRig.images === 'string' ? sourceRig.images : '.');
1790
+ boundary = { code: 'RASTER_READ_UNAVAILABLE' };
1791
+ const skeleton = join(build, 'skeleton.json'), atlas = join(build, 'skeleton.atlas');
1792
+ const candidate = api.loadCandidate({ skeletonText: readFileSync(skeleton, 'utf8'), atlasText: readFileSync(atlas, 'utf8'), atlasDir: build, label: 'setup seam effects' }, { skeleton, atlas }, undefined);
1793
+ const pose = api.throughPoser(candidate.choice, p => api.sampleAnimation(p, 'still', STILL_FPS, { geometry: true })).value[0];
1794
+ boundary = { code: 'POSE_EXPORT_UNREADABLE' };
1795
+ const geometry: unknown = JSON.parse(readFileSync(join(set.dir, GEOMETRY_FILE), 'utf8'));
1796
+ const captured = isRecord(geometry) && Array.isArray(geometry.frames) ? geometry.frames[0] : null;
1797
+ if (pose === undefined || !isRecord(captured) || captured.index !== pose.index || captured.time !== pose.time || JSON.stringify(captured.attachments) !== JSON.stringify(pose.attachments)) throw new SeamSupportError({ code: 'POSE_MISMATCH' });
1798
+ const vp: RootCoverageViewport = { minX: set.viewport.x, minY: set.viewport.y, maxX: set.viewport.x + W, maxY: set.viewport.y + H, scale: 1, width: W, height: H };
1799
+ const project = api.projector(vp);
1800
+ pose.pieces.forEach((piece, i) => {
1801
+ if ('source' in piece) throw new SeamSupportError({ code: 'SOURCE_MAPPING_UNSUPPORTED', slot: piece.slot, feature: 'clipping' });
1802
+ const page = api.pageFor(candidate.pages, piece);
1803
+ const matches = pose.attachments?.filter(a => a.slot === piece.slot) ?? [];
1804
+ if (matches.length !== 1) throw new SeamSupportError({ code: 'POSE_ATTACHMENT_MISSING', slot: piece.slot });
1805
+ const posed = matches[0], identity = posed.attachment;
1806
+ const source = seamSourceAttachment(sourceRig, piece.slot, identity);
1807
+ boundary = { code: 'SOURCE_IMAGE_UNREADABLE', slot: piece.slot, attachment: identity };
1808
+ const imagePath = resolve(imageHome, String(source.image));
1809
+ const own = readPng(imagePath);
1810
+ const art = createHash('sha256').update(own.data).digest('hex');
1811
+ const signature = seamDrawingSignature({ slot: piece.slot, attachment: identity, source,
1812
+ image: { width: own.width, height: own.height, rgba_sha256: art }, vertices: posed.vertices, color: posed.color });
1813
+ // Reporting may name a global draw index; it never enters the signature.
1814
+ support.drawings?.push({ scope: 'posed', name: piece.slot, identity, order: i,
1815
+ geometry: createHash('sha256').update(JSON.stringify(seamSourceValue({ source: Object.fromEntries(Object.entries(source).filter(([key]) => key !== 'image')), vertices: posed.vertices, color: posed.color }))).digest('hex'), art, source_png_sha256: createHash('sha256').update(readFileSync(imagePath)).digest('hex') });
1816
+ boundary = { code: 'RASTER_READ_UNAVAILABLE', slot: piece.slot, attachment: identity };
1817
+ api.rasterisePiece(page, piece, project, vp, (x, y, _r, _g, _b, alpha) => {
1818
+ if (alpha <= 0) return;
1819
+ const q = y * W + x;
1820
+ // A mesh may emit more than one clipped triangle from the same drawing.
1821
+ if (touched[q] === -(i + 1)) return;
1822
+ touched[q] = -(i + 1);
1823
+ support.posed[q] = stacks.append(support.posed[q], signature);
1824
+ support.posedDepth[q] = Math.min(255, support.posedDepth[q] + 1);
1825
+ });
1826
+ });
1827
+ } catch (error) {
1828
+ support.unavailable = error instanceof SeamSupportError ? error.reason : boundary;
1829
+ }
1830
+ return support;
1831
+ }
1832
+
1833
+ export interface SeamReading {
1834
+ mean: number;
1835
+ display_mean: number;
1836
+ denominator_px: number;
1837
+ px_over_40: number;
1838
+ px_over_80: number;
1839
+ frame_scale: number;
1840
+ viewport: Viewport;
1841
+ }
1842
+
1843
+ export interface SeamScope {
1844
+ mode: 'source-grid/base' | 'source-grid/affected-set';
1845
+ domain?: { viewport: Viewport; authored: StageBox; numerator: 'whole-union' | 'authored-scene-interior'; states: SeamStateBounds[] };
1846
+ denominator_px: number;
1847
+ /** The unchanged auto-fitted reading is diagnostic, never another acceptance bar. */
1848
+ auto_frame_raw: SeamReading;
1849
+ /** All canonical residuals, including inherited ones, before selecting effects. */
1850
+ whole: SeamReading;
1851
+ effects?: SeamEffects['reasons'];
1852
+ changes?: SeamEffects['changes'];
1853
+ unavailable?: SeamSupportUnavailable;
1854
+ whole_pairs?: Array<Omit<SeamPairRow, 'picture'>>;
1855
+ pairs?: Array<{ parts: [string, string]; whole_px_over_40: number; affected_px_over_40: number; inherited_px_over_40: number; reasons: Partial<SeamEffects['reasons']> }>;
1856
+ }
1857
+
1858
+ function canonicalDenominator(seam: SeamFigures): number {
1859
+ const denominator = seam.denominator;
1860
+ if (denominator === undefined) {
1861
+ refuseIfAny([{ code: 'CHECK_SEAM_SUPPORT', object: 'the canonical seam denominator', detail: 'the fixed authored support was not read' }]);
1862
+ throw new Error('unreachable');
1863
+ }
1864
+ return denominator;
1865
+ }
1866
+
1867
+ function seamReading(seam: SeamFigures, viewport: Viewport): SeamReading {
1868
+ return { mean: seam.mean, display_mean: round3(seam.mean), denominator_px: seam.denominator ?? viewport.pixelWidth * viewport.pixelHeight - (seam.border?.framePx ?? 0), px_over_40: seam.over40, px_over_80: seam.over80, frame_scale: viewport.scale, viewport };
1501
1869
  }
1502
1870
 
1503
1871
  /**
1504
1872
  * Where `check --keep-stills` leaves the setup-pose still under `--out`
1505
1873
  * (issue #209): rigc's own render directory as `render` wrote it —
1506
- * `frames.json` (the viewport the seam and the source line map by, and the
1874
+ * `frames.json` (the canonical viewport the seam maps by, and the
1507
1875
  * background) and the set directory beside it — so a reader compares against
1508
1876
  * the frame the bars read rather than rebuilding it. Removed at the start of
1509
1877
  * every run, so it is on disk only after a run that asked for it.
@@ -1554,6 +1922,8 @@ export interface SeamPairRow {
1554
1922
  frame_box: [number, number, number, number];
1555
1923
  rig_box: [number, number, number, number];
1556
1924
  cut?: { from: string; differing_copies_px: number };
1925
+ /** Counted sample centres outside the authored source; clamped rig_box is not source provenance there. */
1926
+ outside_authored_px?: number;
1557
1927
  picture: string;
1558
1928
  }
1559
1929
 
@@ -1609,7 +1979,7 @@ export function seamPairRows(seam: SeamFigures, parts: readonly PlacedAlpha[], r
1609
1979
  const db = parts[b].image.data;
1610
1980
  return da[oa] !== db[ob] || da[oa + 1] !== db[ob + 1] || da[oa + 2] !== db[ob + 2];
1611
1981
  };
1612
- interface Acc { a: number; b: number; over40: number; over80: number; f: [number, number, number, number]; r: [number, number, number, number]; pixels: number[]; differing: number }
1982
+ interface Acc { a: number; b: number; over40: number; over80: number; f: [number, number, number, number]; r: [number, number, number, number]; pixels: number[]; differing: number; outside: number }
1613
1983
  const byPair = new Map<string, Acc>();
1614
1984
  seam.counted.forEach((p, idx) => {
1615
1985
  const fx = p % vp.pixelWidth;
@@ -1652,11 +2022,12 @@ export function seamPairRows(seam: SeamFigures, parts: readonly PlacedAlpha[], r
1652
2022
  const key = `${a},${b}`;
1653
2023
  let acc = byPair.get(key);
1654
2024
  if (acc === undefined) {
1655
- acc = { a, b, over40: 0, over80: 0, f: [fx, fy, fx, fy], r: [rx0, ry0, rx1, ry1], pixels: [], differing: 0 };
2025
+ acc = { a, b, over40: 0, over80: 0, f: [fx, fy, fx, fy], r: [rx0, ry0, rx1, ry1], pixels: [], differing: 0, outside: 0 };
1656
2026
  byPair.set(key, acc);
1657
2027
  }
1658
2028
  if (a >= 0 && parts[a].from === parts[b].from && read.some(([u, v]) => differ(a, b, u, v))) acc.differing++;
1659
2029
  acc.over40++;
2030
+ if (u0 < 0 || v0 < 0 || u0 >= W || v0 >= H) acc.outside++;
1660
2031
  acc.pixels.push(p);
1661
2032
  if (seam.countedDiff[idx] > SEAM_PX_LEVEL_HIGH) acc.over80++;
1662
2033
  acc.f = [Math.min(acc.f[0], fx), Math.min(acc.f[1], fy), Math.max(acc.f[2], fx), Math.max(acc.f[3], fy)];
@@ -1670,7 +2041,8 @@ export function seamPairRows(seam: SeamFigures, parts: readonly PlacedAlpha[], r
1670
2041
  const pair: [string, string] = acc.a < 0 ? [name(acc.b), SEAM_NO_ART] : [name(acc.a), name(acc.b)];
1671
2042
  const file = `${String(i + 1).padStart(Math.max(2, width), '0')}_${pair.map((n) => (n === SEAM_NO_ART ? 'no-art' : n)).join('_')}.png`;
1672
2043
  const cut = acc.a >= 0 && parts[acc.a].from === parts[acc.b].from ? { cut: { from: parts[acc.a].from, differing_copies_px: acc.differing } } : {};
1673
- return { row: { parts: pair, px_over_40: acc.over40, px_over_80: acc.over80, frame_box: acc.f, rig_box: acc.r, ...cut, picture: `${SEAM_DIR}/${file}` }, pixels: acc.pixels };
2044
+ return { row: { parts: pair, px_over_40: acc.over40,
2045
+ ...(acc.outside > 0 ? { outside_authored_px: acc.outside } : {}), px_over_80: acc.over80, frame_box: acc.f, rig_box: acc.r, ...cut, picture: `${SEAM_DIR}/${file}` }, pixels: acc.pixels };
1674
2046
  });
1675
2047
  }
1676
2048
 
@@ -1911,6 +2283,8 @@ export interface CheckFigures {
1911
2283
  * divided by its square ({@link seamRigPx}). Null with the other three.
1912
2284
  */
1913
2285
  seam_frame_scale: number | null;
2286
+ /** Canonical acceptance scope and separately labelled diagnostic/raw readings (#705). */
2287
+ seam_scope?: SeamScope;
1914
2288
  /**
1915
2289
  * Written only when `parts.json` declares a scene (issue #242): the frame pixels
1916
2290
  * on the painting's border that the seam figures above leave out, and how many
@@ -1976,6 +2350,7 @@ export interface SetCheckFigures {
1976
2350
  seam_px_over_40: number;
1977
2351
  seam_px_over_80: number;
1978
2352
  seam_frame_scale: number;
2353
+ seam_scope?: SeamScope;
1979
2354
  seam_border?: { frame_px_left_out: number; px_over_40_left_out: number };
1980
2355
  seam_pairs?: SeamPairRow[];
1981
2356
  RECOMPOSITE_HOLES: ReportedLine;
@@ -2151,13 +2526,44 @@ export const STRESS_LINE = 'STRESS_OFF_CHAIN';
2151
2526
  /** The bars `PASS` reads, in the order the summary counts them: the gate, the reference's two, then the judgement lines. */
2152
2527
  export const BARS = ['gate', 'loop', 'seam', ...JUDGEMENT_LINES] as const;
2153
2528
 
2529
+ /**
2530
+ * `SEAM_OVER_MOTION` (issue #493): every declared neighbour pair read in every
2531
+ * animation `motion.json` holds, the idle included, by rig-c's seam reading
2532
+ * (`rigc render --seam`, rig-c 2.60.0). Existing internal-joint and explicit-seam pairs remain **warnings, never bars**. Proven body-root pairs are the exception (issue #686): an active-reading tear fails a counted bar. The
2533
+ * owner's ruling (2026-10-18): a seam opening in motion may be intentional, so
2534
+ * the line names the pair, the animation, the frames and the cells, and moves
2535
+ * neither the exit status nor `check: PASS` for those existing pairs; the summary counts their warnings apart from the bars.
2536
+ *
2537
+ * The pairs are the ones the inputs declare and nothing else: each limb's
2538
+ * consecutive segments in `parts.json` (`config.limbs`, the upper and the
2539
+ * segment below each joint) and, under `--requirements`, each `seam`
2540
+ * requirement's part and neighbour, then proven body-to-segment-zero pairs resolved from hierarchy, slots and provenance. None declared, the line is a SKIP naming
2541
+ * why, never a pass, and `check.json` carries no key for it.
2542
+ *
2543
+ * **The floor** ({@link openingOverFloor}): a frame's gap or ghost is reported
2544
+ * when it holds more cells than its box is long — when it is thicker than one
2545
+ * cell. rigc counts a cell drawn when the renderer paints its centre at half
2546
+ * opacity or more, so a boundary that moves by less than a cell flips the
2547
+ * cells along it in or out: a line of cells one deep, scattered or joined,
2548
+ * holds at most as many cells as its box's longer side. A hole of any area
2549
+ * holds more. The rule types no number; it is read off rigc's own cell and
2550
+ * box, and measured, not chosen: on `examples/wind`'s idle rigc names 43
2551
+ * openings over its six limb pairs (28 and 15 frames of the two elbows, 1 to
2552
+ * 5 cells, boxes up to 17 cells long) and every one is one cell thick; on
2553
+ * rig-c's `gallery/walk` its 13 joint cracks of 1 to 3 cells are too; the
2554
+ * ghost rig-c's own reading names on a skirt swung clear of a leg (1564 cells
2555
+ * in a box 92 long) is far over it.
2556
+ */
2557
+ export const MOTION_SEAM_LINE = 'SEAM_OVER_MOTION';
2558
+
2154
2559
  /**
2155
2560
  * The bars a character's own check may have failed and `compose --accept`
2156
2561
  * still take (issue #203): every bar of {@link BARS} but the gate, which is
2157
2562
  * rig-c's and never accepted, {@link FOLD_LINE} (issue #320) and
2158
- * {@link STRESS_LINE} (issue #347).
2563
+ * {@link STRESS_LINE} (issue #347), and the failing body-root bar of
2564
+ * {@link MOTION_SEAM_LINE} (issue #686).
2159
2565
  */
2160
- export const ACCEPTABLE_BARS: readonly string[] = [...BARS.filter((b) => b !== 'gate'), FOLD_LINE, LEVEL_LINE, STRESS_LINE, LIMB_LINE, SWEEP_LINE];
2566
+ export const ACCEPTABLE_BARS: readonly string[] = [...BARS.filter((b) => b !== 'gate'), FOLD_LINE, LEVEL_LINE, STRESS_LINE, LIMB_LINE, SWEEP_LINE, MOTION_SEAM_LINE];
2161
2567
 
2162
2568
  /**
2163
2569
  * The bars a `check.json`, as `check` writes it, says were not met, in
@@ -2184,6 +2590,8 @@ export function barsNotMet(fig: Readonly<Record<string, unknown>>): string[] {
2184
2590
  const l = fig[n];
2185
2591
  if (typeof l === 'object' && l !== null && (l as { status?: unknown }).status === 'FAIL') out.push(n);
2186
2592
  }
2593
+ const motion = fig[MOTION_SEAM_LINE];
2594
+ if (isRecord(motion) && isRecord(motion.roots) && motion.roots.status === 'FAIL') out.push(MOTION_SEAM_LINE);
2187
2595
  return out;
2188
2596
  }
2189
2597
 
@@ -2208,7 +2616,7 @@ export interface CheckReport {
2208
2616
  idle: { frames: number; fps: number; duration: number; lastIndex: number; loopAt: { x: number; y: number } } | null;
2209
2617
  /** The physics line ({@link loopPhysicsLine}); null when the rig declares no physics constraint or has no idle. */
2210
2618
  loopPhysics: string | null;
2211
- /** The setup-pose still's grid; null when nothing read the still (no parts.json and no `--source`). */
2619
+ /** The canonical seam grid with parts; otherwise the source-only fitted still grid. Null when neither was read. */
2212
2620
  seamViewport: Viewport | null;
2213
2621
  /** Every bar in {@link BARS} that measured, and every one that did not with its reason. */
2214
2622
  bars: { measured: string[]; skipped: Array<{ bar: string; reason: string }> };
@@ -2248,7 +2656,7 @@ export function barsSummary(r: Pick<CheckReport, 'bars'>): string {
2248
2656
 
2249
2657
  /** The summary's warning clause: each warning line that read something, named, with the warnings they printed together; empty when none read. */
2250
2658
  export function warningsClause(r: Pick<CheckReport, 'motionSeam' | 'cloth'>): string {
2251
- const read = [...(r.motionSeam.status === 'SKIP' ? [] : [{ name: MOTION_SEAM_LINE, n: r.motionSeam.warnings }]), ...(r.cloth.status === 'SKIP' ? [] : [{ name: CLOTH_LINE, n: r.cloth.warnings }])];
2659
+ const read = [...(r.motionSeam.status === 'SKIP' || (r.motionSeam.roots !== undefined && r.motionSeam.pairs.every(p => p.root !== undefined)) ? [] : [{ name: MOTION_SEAM_LINE, n: r.motionSeam.warnings }]), ...(r.cloth.status === 'SKIP' ? [] : [{ name: CLOTH_LINE, n: r.cloth.warnings }])];
2252
2660
  if (read.length === 0) return '';
2253
2661
  return `; ${read.reduce((a, x) => a + x.n, 0)} warning(s) (${read.map((x) => x.name).join(', ')}, not a bar)`;
2254
2662
  }
@@ -3513,36 +3921,7 @@ export function sweepLine(
3513
3921
  // the seam over every animation (issue #493; the line is {@link MOTION_SEAM_LINE}'s)
3514
3922
  // ---------------------------------------------------------------------------
3515
3923
 
3516
- /**
3517
- * `SEAM_OVER_MOTION` (issue #493): every declared neighbour pair read in every
3518
- * animation `motion.json` holds, the idle included, by rig-c's seam reading
3519
- * (`rigc render --seam`, rig-c 2.60.0) — a **warning, never a bar**. The
3520
- * owner's ruling (2026-10-18): a seam opening in motion may be intentional, so
3521
- * the line names the pair, the animation, the frames and the cells, and moves
3522
- * neither the exit status nor `check: PASS`; the summary counts it apart from
3523
- * the bars.
3524
- *
3525
- * The pairs are the ones the inputs declare and nothing else: each limb's
3526
- * consecutive segments in `parts.json` (`config.limbs`, the upper and the
3527
- * segment below each joint) and, under `--requirements`, each `seam`
3528
- * requirement's part and neighbour. None declared, the line is a SKIP naming
3529
- * why, never a pass, and `check.json` carries no key for it.
3530
- *
3531
- * **The floor** ({@link openingOverFloor}): a frame's gap or ghost is reported
3532
- * when it holds more cells than its box is long — when it is thicker than one
3533
- * cell. rigc counts a cell drawn when the renderer paints its centre at half
3534
- * opacity or more, so a boundary that moves by less than a cell flips the
3535
- * cells along it in or out: a line of cells one deep, scattered or joined,
3536
- * holds at most as many cells as its box's longer side. A hole of any area
3537
- * holds more. The rule types no number; it is read off rigc's own cell and
3538
- * box, and measured, not chosen: on `examples/wind`'s idle rigc names 43
3539
- * openings over its six limb pairs (28 and 15 frames of the two elbows, 1 to
3540
- * 5 cells, boxes up to 17 cells long) and every one is one cell thick; on
3541
- * rig-c's `gallery/walk` its 13 joint cracks of 1 to 3 cells are too; the
3542
- * ghost rig-c's own reading names on a skirt swung clear of a leg (1564 cells
3543
- * in a box 92 long) is far over it.
3544
- */
3545
- export const MOTION_SEAM_LINE = 'SEAM_OVER_MOTION';
3924
+
3546
3925
 
3547
3926
  /** The seam reading's scratch build and renders, under `--out`; removed before the stage returns. */
3548
3927
  const MOTION_SEAM_SCRATCH = '_seam_motion';
@@ -3564,6 +3943,31 @@ export interface MotionSeamPair {
3564
3943
  declared: string[];
3565
3944
  /** Why the pair is not read: a slot `rig.json` does not have. */
3566
3945
  unread?: string;
3946
+ /** Issue #686: segment-zero provenance and its immediate named body carrier. */
3947
+ root?: { limb: string; bone: string; parent: string };
3948
+ }
3949
+
3950
+ /** Stock setup-only seam rows: banded > 0, not distance or mesh influence, proves alpha overlap. */
3951
+ export interface MotionRootSetupRow {
3952
+ pair: string;
3953
+ drawn: number;
3954
+ banded: number;
3955
+ status: 'read' | 'skip';
3956
+ }
3957
+
3958
+ /** Eligible, readable setup drawings with no overlap band: not a measured root. */
3959
+ export interface MotionUnmeasuredRoot {
3960
+ limb: string;
3961
+ bone: string;
3962
+ parent: string;
3963
+ part: string;
3964
+ candidates: string[];
3965
+ reason: string;
3966
+ }
3967
+
3968
+ export interface MotionSeamSelection {
3969
+ pairs: MotionSeamPair[];
3970
+ unmeasuredRoots: MotionUnmeasuredRoot[];
3567
3971
  }
3568
3972
 
3569
3973
  /** One pair in one animation, as the floor reads rigc's file. */
@@ -3577,37 +3981,51 @@ export interface MotionSeamRow {
3577
3981
  banded: number;
3578
3982
  /** The frames over the floor, ascending: the warning's frames. */
3579
3983
  opens: number[];
3580
- /** Beside `opens`, frame by frame: the most cells of either kind on that frame. */
3984
+ /** Beside `opens`: GAP only on roots; the legacy maximum of both kinds elsewhere. */
3581
3985
  px: number[];
3582
- /** The most cells of either kind on any frame over the floor; 0 when none is. */
3986
+ /** Maximum gated/warned count over the floor; root ghost is separate INFO. */
3583
3987
  max_px: number;
3584
3988
  /** The frames rigc names open whose every opening is one cell thick: under the floor, not reported. */
3585
3989
  under_floor: number[];
3990
+ /** New roots only: the worst above-floor hit, retaining rigc's cell and world box. */
3991
+ worst?: MotionSeamHit & { kind: 'gap' | 'ghost' };
3992
+ /** Roots only: preserve mixed ghost without inferring an owner from rigc-seam/1. */
3993
+ ghost_info?: MotionSeamWorldKind & { owner: 'unavailable'; frames: number };
3994
+ /** Roots only, above-floor raw GAP hits: sufficient whole-box proof, never a GAP mask. */
3995
+ coverage?: RootGapCoverage[];
3586
3996
  }
3587
3997
 
3588
- /** The line: `WARN` with at least one warning, `CLEAR` with none, `SKIP` with nothing declared or nothing to read. */
3998
+ /** Existing pairs warn; new body roots alone can FAIL. Unavailable readings are named SKIP, never measured zero. */
3589
3999
  export interface MotionSeamLine {
3590
- status: 'WARN' | 'CLEAR' | 'SKIP';
4000
+ status: 'WARN' | 'CLEAR' | 'SKIP' | 'FAIL';
3591
4001
  reason?: string;
3592
4002
  fps: number;
3593
4003
  floor: string;
3594
4004
  pairs: MotionSeamPair[];
3595
4005
  animations: string[];
3596
- /** Rows with a frame over the floor: the WARN lines. */
4006
+ /** Existing non-root rows with a frame over the floor: the WARN lines. */
3597
4007
  warnings: number;
3598
4008
  rows: MotionSeamRow[];
3599
4009
  /** Physics-only reference worlds (issue #591); do not participate in warnings or bars. */
3600
4010
  worlds?: MotionSeamWorlds;
4011
+ /** Selected body-root pairs and named zero-band roots; existing internal seams remain warnings. */
4012
+ roots?: { status: 'PASS' | 'FAIL' | 'SKIP'; mode: 'gap-only'; ghost_owner: 'unavailable'; ghost_followup: 'rig-c/core#1555'; pairs: string[]; failed: number; reason?: string; unmeasured?: MotionUnmeasuredRoot[] };
3601
4013
  }
3602
4014
 
3603
4015
  /**
3604
4016
  * The neighbour pairs the inputs declare, in their order: each limb's
3605
4017
  * consecutive segments (`parts.json`'s limb records, by segment), then each
3606
- * `seam` requirement's part and neighbour. A pair named twice, in either
4018
+ * `seam` requirement's part and neighbour, then proven roots when rig.json is supplied. A pair named twice, in either
3607
4019
  * order, is one pair with both declarations.
3608
4020
  */
3609
- export function motionSeamPairs(parts: PartsFile, seams: ReadonlyArray<{ name: string; part: string; neighbour: string }>): MotionSeamPair[] {
4021
+ export function motionSeamPairs(parts: PartsFile, seams: ReadonlyArray<{ name: string; part: string; neighbour: string }>, rig?: Record<string, unknown>, readSetup?: (candidates: readonly MotionSeamPair[]) => readonly MotionRootSetupRow[]): MotionSeamPair[] {
4022
+ return motionSeamSelection(parts, seams, rig, readSetup).pairs;
4023
+ }
4024
+
4025
+ /** Complete selection: a valid zero setup band is named separately, never a fabricated pair or PASS. */
4026
+ export function motionSeamSelection(parts: PartsFile, seams: ReadonlyArray<{ name: string; part: string; neighbour: string }>, rig?: Record<string, unknown>, readSetup?: (candidates: readonly MotionSeamPair[]) => readonly MotionRootSetupRow[]): MotionSeamSelection {
3610
4027
  const out: MotionSeamPair[] = [];
4028
+ const unmeasuredRoots: MotionUnmeasuredRoot[] = [];
3611
4029
  const add = (a: string, b: string, declared: string): void => {
3612
4030
  const hit = out.find((p) => (p.a === a && p.b === b) || (p.a === b && p.b === a));
3613
4031
  if (hit !== undefined) hit.declared.push(declared);
@@ -3623,6 +4041,142 @@ export function motionSeamPairs(parts: PartsFile, seams: ReadonlyArray<{ name: s
3623
4041
  }
3624
4042
  }
3625
4043
  for (const r of seams) add(r.part, r.neighbour, `requirement "${r.name}" (seam)`);
4044
+ const candidates = rig === undefined ? [] : motionRootCandidates(parts, rig);
4045
+ const selected: MotionSeamPair[] = [];
4046
+ if (candidates.length > 0) {
4047
+ const rows = readSetup?.(candidates);
4048
+ const problems: Problem[] = [];
4049
+ const bad = (object: string, detail: string): void => { problems.push({ code: 'CHECK_MOTION_SEAM_ROOT', object, detail }); };
4050
+ if (rows === undefined || rows.length !== candidates.length) {
4051
+ bad('body-root setup reading', 'requires one stock setup-only seam row per eligible candidate; found ' + (rows === undefined ? 'no reader' : rows.length) + ', required ' + candidates.length + '; unavailable is not zero overlap');
4052
+ } else {
4053
+ for (const candidate of candidates) {
4054
+ const matches = rows.filter(row => row.pair === candidate.pair);
4055
+ const row = matches[0];
4056
+ if (matches.length !== 1 || row.drawn !== 1 || (row.banded !== 0 && row.banded !== 1) || row.status !== (row.banded === 1 ? 'read' : 'skip')) {
4057
+ bad(candidate.pair, 'requires one setup frame with both drawings present and banded 0/1 matching status skip/read; the stock reading is missing, duplicate or unreadable');
4058
+ } else if (row.banded > 0) selected.push(candidate);
4059
+ }
4060
+ }
4061
+ // Missing, duplicate or undrawn data must refuse before a zero-band result exists.
4062
+ refuseIfAny(problems);
4063
+ for (const candidate of candidates) {
4064
+ const root = candidate.root;
4065
+ if (root === undefined || selected.some(p => p.root?.limb === root.limb) || unmeasuredRoots.some(p => p.limb === root.limb)) continue;
4066
+ const names = candidates.filter(p => p.root?.limb === root.limb).map(p => p.a);
4067
+ unmeasuredRoots.push({ ...root, part: candidate.b, candidates: names,
4068
+ reason: 'no setup band with ' + names.join('/') + ' — not measured' });
4069
+ }
4070
+ }
4071
+ for (const root of selected) {
4072
+ add(root.a, root.b, root.declared[0]);
4073
+ const pair = out.find(p => (p.a === root.a && p.b === root.b) || (p.a === root.b && p.b === root.a));
4074
+ if (pair !== undefined) pair.root = root.root;
4075
+ }
4076
+ return { pairs: out, unmeasuredRoots };
4077
+ }
4078
+
4079
+
4080
+ /**
4081
+ * Only the immediate named carrier is eligible. Slot binding and source provenance
4082
+ * establish candidates; stock setup alpha overlap selects all matching drawings.
4083
+ * No body provenance means legacy input, not proof of closed body-root seams.
4084
+ */
4085
+ function motionRootCandidates(parts: PartsFile, rig: Record<string, unknown>): MotionSeamPair[] {
4086
+ const limbs = [...new Set(parts.parts.flatMap(p => p.limb === undefined ? [] : [p.limb.name]))];
4087
+ // Root-free inputs keep the old selector without inspecting irrelevant body bindings.
4088
+ if (limbs.length === 0) return [];
4089
+ const bodies = partsTagged(parts, ['topwear', 'bottomwear']).filter(p => p.limb === undefined);
4090
+ if (bodies.length === 0) return [];
4091
+ const problems: Problem[] = [];
4092
+ const bad = (object: string, detail: string): void => { problems.push({ code: 'CHECK_MOTION_SEAM_ROOT', object, detail }); };
4093
+ const bones = (Array.isArray(rig.bones) ? rig.bones : []).filter(isRecord);
4094
+ const slots = (Array.isArray(rig.slots) ? rig.slots : []).filter(isRecord);
4095
+ const skin = isRecord(rig.skins) && isRecord(rig.skins.default) ? rig.skins.default : {};
4096
+ const binding = (part: PartRecord): Record<string, unknown> | null => {
4097
+ const matches = slots.filter(s => s.name === part.name);
4098
+ const on = skin[part.name];
4099
+ const slot = matches.length === 1 ? matches[0] : null;
4100
+ const attachment = slot !== null && typeof slot.attachment === 'string' && isRecord(on) ? on[slot.attachment] : undefined;
4101
+ if (parts.parts.filter(p => p.name === part.name).length !== 1 || slot === null || typeof slot.bone !== 'string' || !isRecord(attachment)) {
4102
+ bad('part "' + part.name + '"', 'requires one part, one slot of that name and its named setup attachment in the default skin; found ' + matches.length + ' slot(s)');
4103
+ return null;
4104
+ }
4105
+ return slot;
4106
+ };
4107
+ const carriers = bodies.map(part => ({ part, slot: binding(part) }));
4108
+ // Match applyTurn's emitted structure, not a name prefix or a nearby ancestor.
4109
+ // Its leaf/control bones have exactly these fields; no transform tolerance is introduced.
4110
+ const keys = (record: Record<string, unknown>, wanted: readonly string[]): boolean =>
4111
+ Object.keys(record).sort().join(',') === [...wanted].sort().join(',');
4112
+ const identity = (bone: Record<string, unknown>, parent: string): boolean =>
4113
+ keys(bone, ['name', 'parent', 'x', 'y']) && bone.parent === parent && bone.x === 0 && bone.y === 0;
4114
+ const generatedBodyTurn = (part: PartRecord, slot: Record<string, unknown>, parent: string): boolean => {
4115
+ const twin = turnTwin(part.name, parent);
4116
+ if (slot.bone !== twin) return false;
4117
+ const children = bones.filter(bone => bone.name === twin);
4118
+ const controls = bones.filter(bone => bone.name === TURN_BONE);
4119
+ if (children.length !== 1 || !identity(children[0], parent) ||
4120
+ controls.length !== 1 || !identity(controls[0], ROOT_BONE)) return false;
4121
+ const constraints = (Array.isArray(rig.constraints) ? rig.constraints : []).filter(isRecord)
4122
+ .filter(constraint => constraint.name === turnConstraintName(part.name));
4123
+ if (constraints.length !== 1) return false;
4124
+ const constraint = constraints[0];
4125
+ if (!keys(constraint, ['type', 'name', 'bones', 'source', 'localSource', 'additive', 'properties']) ||
4126
+ constraint.type !== 'transform' || constraint.source !== TURN_BONE ||
4127
+ constraint.localSource !== true || constraint.additive !== true || !Array.isArray(constraint.bones) ||
4128
+ constraint.bones.length === 0 || constraint.bones.some(name => typeof name !== 'string') ||
4129
+ new Set(constraint.bones).size !== constraint.bones.length || !constraint.bones.includes(twin)) return false;
4130
+ // Every target belongs to this part's generated row, even on a multi-bone body mesh.
4131
+ if (!constraint.bones.every(name => {
4132
+ const targets = bones.filter(bone => bone.name === name);
4133
+ if (targets.length !== 1 || typeof targets[0].parent !== 'string') return false;
4134
+ const carrier = targets[0].parent;
4135
+ return targets[0].name === turnTwin(part.name, carrier) && identity(targets[0], carrier) &&
4136
+ bones.filter(bone => bone.name === carrier).length === 1;
4137
+ })) return false;
4138
+ const properties = constraint.properties;
4139
+ if (!isRecord(properties) || !keys(properties, ['x']) || !isRecord(properties.x) ||
4140
+ !keys(properties.x, ['to']) || !isRecord(properties.x.to) || !keys(properties.x.to, ['x']) ||
4141
+ !isRecord(properties.x.to.x) || !keys(properties.x.to.x, ['scale'])) return false;
4142
+ const fraction = properties.x.to.x.scale;
4143
+ // applyTurn emits no row/twin at fraction0; its nonzero fraction is finite, not guessed here.
4144
+ return typeof fraction === 'number' && Number.isFinite(fraction) && fraction !== 0;
4145
+ };
4146
+ const out: MotionSeamPair[] = [];
4147
+ for (const limb of limbs) {
4148
+ const roots = parts.parts.filter(p => p.limb?.name === limb && p.limb.segment === 0);
4149
+ if (roots.length !== 1) {
4150
+ bad('config.limbs.' + limb, 'has ' + roots.length + ' segment-zero part(s); exactly one is required to identify its body-root seam');
4151
+ continue;
4152
+ }
4153
+ const root = roots[0];
4154
+ const l = root.limb as LimbRecord;
4155
+ const object = 'root part "' + root.name + '" (config.limbs.' + limb + ', bone "' + l.bone + '")';
4156
+ const named = bones.filter(b => b.name === l.bone);
4157
+ if (named.length !== 1 || typeof named[0].parent !== 'string' || bones.filter(b => b.name === named[0].parent).length !== 1) {
4158
+ bad(object, 'requires one declared bone and its one named immediate parent in rig.json; found ' + named.length + ' bone(s), parent ' + JSON.stringify(named[0]?.parent));
4159
+ continue;
4160
+ }
4161
+ const parent = named[0].parent;
4162
+ const slot = binding(root);
4163
+ if (slot === null) continue;
4164
+ const twin = turnTwin(root.name, l.bone);
4165
+ const twinBones = bones.filter(b => b.name === twin);
4166
+ if (slot.bone !== l.bone && !(slot.bone === twin && twinBones.length === 1 && twinBones[0].parent === l.bone)) {
4167
+ bad(object, 'slot binds "' + String(slot.bone) + '"; the declared bone "' + l.bone + '" or its named turn child is required');
4168
+ continue;
4169
+ }
4170
+ const eligible = carriers.filter(c => c.slot !== null && (c.slot.bone === parent || generatedBodyTurn(c.part, c.slot, parent)));
4171
+ if (eligible.length === 0) {
4172
+ bad(object, 'requires a topwear/bottomwear body drawing whose slot binds its immediate parent "' + parent + '" directly or through its verified generated turn child; found none; no nearest, name or mesh-influence fallback');
4173
+ continue;
4174
+ }
4175
+ for (const { part: body } of eligible) out.push({ pair: body.name + '|' + root.name, a: body.name, b: root.name,
4176
+ declared: ['config.limbs.' + limb + ' segment 0, body carrier "' + parent + '" from ' + body.from],
4177
+ root: { limb, bone: l.bone, parent } });
4178
+ }
4179
+ refuseIfAny(problems);
3626
4180
  return out;
3627
4181
  }
3628
4182
 
@@ -3655,13 +4209,203 @@ export interface MotionSeamPlant {
3655
4209
  }
3656
4210
 
3657
4211
 
3658
- /** One raw opening, in rigc cells; its frame time is index / the line's fps. */
4212
+ /** One raw opening in rigc cells; actual raw frame time is read separately for coverage. */
3659
4213
  export interface MotionSeamHit {
3660
4214
  index: number;
3661
4215
  px: number;
3662
4216
  cell: number;
3663
4217
  box: [number, number, number, number];
3664
4218
  }
4219
+
4220
+ /** Match rig-c's DRAWN_ALPHA (passthrough): alpha, never RGB brightness. */
4221
+ const ROOT_DRAWN_ALPHA = 128;
4222
+ const ROOT_COVERAGE_DIR = 'root_gap_coverage';
4223
+ export interface RootGapCoverage extends MotionSeamHit {
4224
+ status: 'exempt' | 'conservative' | 'unavailable';
4225
+ reason: string;
4226
+ /** Whole box cell centres, NOT the unavailable exact GAP subset. */
4227
+ box_cells?: number;
4228
+ covered_cells?: number;
4229
+ /** Deterministic sidecar relative to check.json, written only for actual examined hits. */
4230
+ evidence?: string;
4231
+ }
4232
+ export type RootGapCoverageReader = (pair: MotionSeamPair, animation: string, hit: MotionSeamHit, time: number | undefined) => RootGapCoverage;
4233
+
4234
+ /** All-box coverage is sufficient because the raw GAP cells are a subset of the box. */
4235
+ export function rootGapBoxCoverage(hit: MotionSeamHit, alpha: readonly number[] | null, reason = 'composite metadata unavailable', worldMagnitude?: number): RootGapCoverage {
4236
+ const width = Math.round((hit.box[2] - hit.box[0]) / hit.cell);
4237
+ const height = Math.round((hit.box[3] - hit.box[1]) / hit.cell);
4238
+ const unavailable = (): RootGapCoverage => ({ ...hit, status: 'unavailable', reason });
4239
+ // Binary64 unit roundoff u. Core seam.ts readFrame/centreX/centreY/take
4240
+ // forms each edge with grid-origin multiply, offset multiply, centre add and
4241
+ // half-cell add: four rounded operations (cell/2 and integer+.5 are exact
4242
+ // in the normal/safe-index domain below). For M bounding the SAME pair's
4243
+ // rest/posed coordinates, |origin| <= M+4c, |offset| <= 2M+8c;
4244
+ // B=4(M+4c) bounds every intermediate magnitude, including cancellation.
4245
+ // Each edge's forward error is <= gamma(4)B. Add both edge errors, the
4246
+ // subtraction error u(|lo|+|hi|), and division error u|q|/(1-u).
4247
+ // gamma(32) rounds outward over at most 32 arithmetic operations, including
4248
+ // B, both gamma evaluations and the error expression below. A bound
4249
+ // >= half a cell cannot identify a unique integer and remains unavailable.
4250
+ // Without the coordinate bound only EXACT integer extents are accepted.
4251
+ const u = Number.EPSILON / 2;
4252
+ const gamma = (n: number): number => n * u / (1 - n * u);
4253
+ const integerExtent = (lo: number, hi: number, cells: number): boolean => {
4254
+ const q = (hi - lo) / hit.cell;
4255
+ if (worldMagnitude === undefined) return q === cells;
4256
+ const B = 4 * (worldMagnitude + 4 * hit.cell);
4257
+ if (!Number.isFinite(worldMagnitude) || worldMagnitude < Math.max(Math.abs(lo), Math.abs(hi)) ||
4258
+ hit.cell < 2 ** -1021 || !Number.isFinite(B) || B / hit.cell >= 2 ** 51) return false;
4259
+ const error = ((2 * gamma(4) * B + u * (Math.abs(lo) + Math.abs(hi))) / hit.cell +
4260
+ u * Math.abs(q) / (1 - u)) / (1 - gamma(32)) + Number.MIN_VALUE;
4261
+ return error < 0.5 && Math.abs(q - cells) <= error;
4262
+ };
4263
+ if (!Number.isFinite(hit.cell) || hit.cell <= 0 || !hit.box.every(Number.isFinite) ||
4264
+ !Number.isSafeInteger(width * height) || width <= 0 || height <= 0 ||
4265
+ !integerExtent(hit.box[0], hit.box[2], width) || !integerExtent(hit.box[1], hit.box[3], height) ||
4266
+ alpha === null || alpha.length !== width * height || alpha.some(a => !Number.isFinite(a) || a < 0 || a > 255)) return unavailable();
4267
+ const covered = alpha.filter(a => a >= ROOT_DRAWN_ALPHA).length;
4268
+ return { ...hit, status: covered === alpha.length ? 'exempt' : 'conservative',
4269
+ reason: covered === alpha.length ? 'whole world-cell box covered at DRAWN_ALPHA 128' : 'uncovered box cells: retain the entire original GAP count; exact GAP subset unavailable',
4270
+ box_cells: alpha.length, covered_cells: covered };
4271
+ }
4272
+
4273
+ /**
4274
+ * Root-only lazy reader. The render already made by runCheck supplies every
4275
+ * used world vertex, tint, frame time and draw order. The public renderer entry
4276
+ * supplies packed UV/page metadata and rasterisation, not a second seam metric.
4277
+ * Unsupported clipping/binding or even one replay pixel mismatch retains raw.
4278
+ */
4279
+ export function motionRootCoverageReader(build: string, rendered: string, out: string): RootGapCoverageReader {
4280
+ type Renderer = OfficialRenderer;
4281
+ type PoseAttachment = NonNullable<RootCoverageFrame['attachments']>[number];
4282
+ interface Prepared { api: Renderer; pages: ReturnType<Renderer['loadCandidate']>['pages']; pieces: RootCoveragePiece[]; attachments: PoseAttachment[] }
4283
+ interface Animation { frames: Map<number, { frame: RootCoverageFrame; alphaReplayExact: boolean }>; restMagnitude: number }
4284
+ let prepared: Prepared | undefined;
4285
+ const animations = new Map<string, Animation>();
4286
+ const read = (path: string): unknown => JSON.parse(readFileSync(path, 'utf8')) as unknown;
4287
+ const same = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b);
4288
+ class CoverageUnavailable extends Error {}
4289
+ const requireFact = (condition: unknown, reason: string): void => { if (!condition) throw new CoverageUnavailable(reason); };
4290
+ const attachments = (value: unknown): PoseAttachment[] => {
4291
+ requireFact(Array.isArray(value), 'geometry attachment roster unavailable');
4292
+ return (value as unknown[]).map(a => {
4293
+ if (!isRecord(a) || typeof a.slot !== 'string' || typeof a.attachment !== 'string' ||
4294
+ !Array.isArray(a.vertices) || a.vertices.length % 2 !== 0 || !a.vertices.every(v => typeof v === 'number' && Number.isFinite(v)) ||
4295
+ !Array.isArray(a.color) || a.color.length !== 4 || !a.color.every(v => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 1)) throw new CoverageUnavailable('geometry attachment fields unavailable');
4296
+ return { slot: a.slot, attachment: a.attachment, vertices: a.vertices as number[], color: a.color as [number, number, number, number] };
4297
+ });
4298
+ };
4299
+ const prepare = (): Prepared => {
4300
+ if (prepared !== undefined) return prepared;
4301
+ // Node's module loader is called only here, never for a root-free reading.
4302
+ const loaded: unknown = officialRenderer();
4303
+ requireFact(isRecord(loaded) && ['loadCandidate', 'throughPoser', 'sampleSetupPose', 'renderFrame'].every(k => typeof loaded[k] === 'function'), 'official renderer exports unavailable');
4304
+ const api = loaded as Renderer;
4305
+ const skeleton = join(build, 'skeleton.json'), atlas = join(build, 'skeleton.atlas');
4306
+ const text = readFileSync(skeleton, 'utf8'), document: unknown = JSON.parse(text);
4307
+ const unsupported = (v: unknown): boolean => Array.isArray(v) ? v.some(unsupported) : isRecord(v) &&
4308
+ (v.type === 'clipping' || Object.keys(v).some(k => k === 'dark' || k === 'rgba2' || k === 'rgb2' || unsupported(v[k])));
4309
+ requireFact(!unsupported(document), 'clipping or dark-tint metadata is not replayable from this geometry');
4310
+ const candidate = api.loadCandidate({ skeletonText: text, atlasText: readFileSync(atlas, 'utf8'), atlasDir: build, label: 'root GAP composite' }, { skeleton, atlas }, undefined);
4311
+ const metadata = api.throughPoser(candidate.choice, p => api.sampleSetupPose(p, { geometry: true, bones: true })).value[0];
4312
+ requireFact(metadata !== undefined && metadata.attachments !== undefined && metadata.pieces.every(p => !('source' in p) && p.dark === undefined), 'unclipped packed metadata unavailable');
4313
+ prepared = { api, pages: candidate.pages, pieces: metadata.pieces, attachments: metadata.attachments ?? [] };
4314
+ return prepared;
4315
+ };
4316
+ return (pair, animation, hit, time) => {
4317
+ let result = rootGapBoxCoverage(hit, null);
4318
+ let alpha: number[] | null = null;
4319
+ let frameTime: number | null = null;
4320
+ const reason = 'official composite metadata or pixel replay unavailable';
4321
+ try {
4322
+ requireFact(Number.isInteger(hit.index) && hit.index >= 0 && typeof time === 'number' && Number.isFinite(time), 'actual raw frame time unavailable');
4323
+ const { api, pages, pieces, attachments: metadataAttachments } = prepare();
4324
+ const sidecar = read(join(rendered, 'frames.json'));
4325
+ requireFact(isRecord(sidecar) && Array.isArray(sidecar.sets) && isRecord(sidecar.viewport), 'render viewport unavailable');
4326
+ // requireFact deliberately does not narrow unknown values: each reader
4327
+ // checks again at its own boundary rather than using an unchecked cast.
4328
+ if (!isRecord(sidecar) || !Array.isArray(sidecar.sets) || !isRecord(sidecar.viewport)) throw new CoverageUnavailable(reason);
4329
+ const set = sidecar.sets.find(s => isRecord(s) && s.animation === animation);
4330
+ requireFact(isRecord(set) && typeof set.dir === 'string' && !isAbsolute(set.dir) && !set.dir.split(/[\\/]/).includes('..'), 'local animation directory unavailable');
4331
+ if (!isRecord(set) || typeof set.dir !== 'string') throw new CoverageUnavailable(reason);
4332
+ const v = sidecar.viewport;
4333
+ requireFact(['x', 'y', 'width', 'height', 'scale', 'pixelWidth', 'pixelHeight'].every(k => typeof v[k] === 'number' && Number.isFinite(v[k])) &&
4334
+ Number(v.scale) > 0 && Number.isSafeInteger(v.pixelWidth) && Number(v.pixelWidth) > 0 && Number.isSafeInteger(v.pixelHeight) && Number(v.pixelHeight) > 0, 'finite render viewport unavailable');
4335
+ const viewport: RootCoverageViewport = { minX: Number(v.x), minY: Number(v.y), maxX: Number(v.x) + Number(v.width), maxY: Number(v.y) + Number(v.height), scale: Number(v.scale), width: Number(v.pixelWidth), height: Number(v.pixelHeight) };
4336
+ requireFact(Array.isArray(sidecar.background) && sidecar.background.length === 4 && sidecar.background.every(x => typeof x === 'number' && Number.isInteger(x) && x >= 0 && x <= 255), 'render background unavailable');
4337
+ const background = sidecar.background as [number, number, number, number];
4338
+ let state = animations.get(animation);
4339
+ if (state === undefined) {
4340
+ const geometry = read(join(rendered, set.dir, GEOMETRY_FILE));
4341
+ requireFact(isRecord(geometry) && isRecord(geometry.setup) && Array.isArray(geometry.rest) && Array.isArray(geometry.frames) && geometry.animation === animation, 'same-animation geometry unavailable');
4342
+ if (!isRecord(geometry) || !isRecord(geometry.setup) || !Array.isArray(geometry.rest) || !Array.isArray(geometry.frames)) throw new CoverageUnavailable(reason);
4343
+ const setup = attachments(geometry.setup.attachments);
4344
+ requireFact(setup.length === pieces.length && new Set(setup.map(a => a.slot)).size === setup.length, 'setup draw roster unavailable');
4345
+ for (const p of pieces) {
4346
+ const a = setup.find(a => a.slot === p.slot);
4347
+ const rest = geometry.rest.find(r => isRecord(r) && r.slot === p.slot && r.attachment === a?.attachment);
4348
+ requireFact(a !== undefined && isRecord(rest) && rest.kind === p.kind && a.vertices.length === p.world.length && same(a.color, p.tint) &&
4349
+ (p.kind !== 'mesh' || same(rest.triangles, Array.from(p.triangles))), 'packed metadata topology or tint differs');
4350
+ }
4351
+ // The metadata poser supplies attachment identity, never world positions.
4352
+ // Match it explicitly to the captured setup, including default skin.
4353
+ requireFact(setup.every(a => metadataAttachments.some(b => a.slot === b.slot && a.attachment === b.attachment)), 'default attachment identity differs');
4354
+ let restMagnitude = 0;
4355
+ for (const r of geometry.rest) {
4356
+ if (!isRecord(r) || !Array.isArray(r.vertices) || !r.vertices.every(v => typeof v === 'number' && Number.isFinite(v))) throw new CoverageUnavailable('rest coordinate bound unavailable');
4357
+ for (const v of r.vertices as number[]) restMagnitude = Math.max(restMagnitude, Math.abs(v));
4358
+ }
4359
+ state = { restMagnitude, frames: new Map() };
4360
+ for (const f of geometry.frames) {
4361
+ if (!isRecord(f) || !Number.isInteger(f.index) || typeof f.time !== 'number' || !Number.isFinite(f.time)) throw new CoverageUnavailable('frame identity unavailable');
4362
+ const posed = attachments(f.attachments);
4363
+ requireFact(posed.length === pieces.length && new Set(posed.map(a => a.slot)).size === posed.length, 'frame draw roster differs');
4364
+ const drawn = posed.map(a => {
4365
+ const p = pieces.find(p => p.slot === a.slot), original = setup.find(p => p.slot === a.slot);
4366
+ if (p === undefined || original?.attachment !== a.attachment || p.world.length !== a.vertices.length) throw new CoverageUnavailable('frame attachment binding differs');
4367
+ return { ...p, world: a.vertices, tint: a.color };
4368
+ });
4369
+ requireFact(!state.frames.has(Number(f.index)), 'duplicate frame index');
4370
+ state.frames.set(Number(f.index), { frame: { index: Number(f.index), time: f.time, pieces: drawn }, alphaReplayExact: false });
4371
+ }
4372
+ animations.set(animation, state);
4373
+ }
4374
+ const captured = state.frames.get(hit.index);
4375
+ frameTime = captured?.frame.time ?? null;
4376
+ requireFact(captured !== undefined && captured.frame.time === time, 'raw and geometry frame time differ');
4377
+ if (captured === undefined) throw new CoverageUnavailable(reason);
4378
+ frameTime = captured.frame.time;
4379
+ if (!captured.alphaReplayExact) {
4380
+ const png = readPng(join(rendered, set.dir, 'f' + String(hit.index).padStart(4, '0') + '.png'));
4381
+ const replay = api.renderFrame(captured.frame, pages, viewport, background);
4382
+ requireFact(png.width === replay.width && png.height === replay.height && Buffer.from(png.data).equals(Buffer.from(replay.data)), 'official frame RGBA pixel replay differs');
4383
+ captured.alphaReplayExact = true;
4384
+ }
4385
+ const width = Math.round((hit.box[2] - hit.box[0]) / hit.cell), height = Math.round((hit.box[3] - hit.box[1]) / hit.cell);
4386
+ requireFact(Number.isSafeInteger(width * height) && width > 0 && height > 0 && Number.isFinite(hit.cell) && hit.cell > 0, 'world cell box unavailable');
4387
+ const grid = { minX: hit.box[0], minY: hit.box[1], maxX: hit.box[2], maxY: hit.box[3], width, height, scale: 1 / hit.cell };
4388
+ const composite = api.renderFrame(captured.frame, pages, grid, [0, 0, 0, 0]);
4389
+ alpha = Array.from({ length: width * height }, (_, i) => composite.data[i * 4 + 3]);
4390
+ let worldMagnitude = state.restMagnitude;
4391
+ for (const p of captured.frame.pieces) for (const v of p.world) worldMagnitude = Math.max(worldMagnitude, Math.abs(v));
4392
+ // All drawings' magnitude bounds either pair without selecting an owner.
4393
+ result = rootGapBoxCoverage(hit, alpha, 'world cell box grid unavailable', worldMagnitude);
4394
+ } catch (error) {
4395
+ // No guessed coverage and no absolute paths from an upstream exception.
4396
+ result = rootGapBoxCoverage(hit, null, error instanceof CoverageUnavailable ? error.message : reason);
4397
+ }
4398
+ const key = createHash('sha256').update(JSON.stringify([pair.pair, animation, hit.index])).digest('hex');
4399
+ const evidence = ROOT_COVERAGE_DIR + '/' + key + '.json';
4400
+ mkdirSync(join(out, ROOT_COVERAGE_DIR), { recursive: true });
4401
+ writeFileSync(join(out, evidence), JSON.stringify({ spec: 'rig-parts-root-gap-box/1', pair: pair.pair, animation,
4402
+ raw_time: typeof time === 'number' && Number.isFinite(time) ? time : null, frame_time: frameTime, raw: hit, ...result, alpha_threshold: ROOT_DRAWN_ALPHA,
4403
+ scope: 'whole world-cell box centres; not an exact GAP-cell mask',
4404
+ grid: { minX: hit.box[0], minY: hit.box[1], maxX: hit.box[2], maxY: hit.box[3], cell: hit.cell, rows: 'top to bottom' },
4405
+ alpha, exact_rgba_replay: alpha !== null, followup: 'rig-c/core#1556' }, null, 1) + '\n');
4406
+ return { ...result, evidence };
4407
+ };
4408
+ }
3665
4409
  export interface MotionSeamWorldKind {
3666
4410
  max_px: number;
3667
4411
  worst: MotionSeamHit | null;
@@ -3765,7 +4509,33 @@ type SeamHitRead = MotionSeamHit;
3765
4509
  * file that is missing, a file that is not the animation's or not at the rate
3766
4510
  * asked, a pair out of the flag's order, and a field of the wrong shape.
3767
4511
  */
3768
- export function readMotionSeams(dir: string, animations: readonly string[], fps: number, pairs: readonly MotionSeamPair[], plant: MotionSeamPlant = {}, worldRows?: MotionSeamWorldRow[]): MotionSeamRow[] {
4512
+ export function readMotionSeams(dir: string, animations: readonly string[], fps: number, pairs: readonly MotionSeamPair[], plant: MotionSeamPlant = {}, worldRows?: MotionSeamWorldRow[], coverageReader?: RootGapCoverageReader): MotionSeamRow[] {
4513
+ return readSeamRows(dir, animations, fps, pairs, plant, worldRows, false, coverageReader);
4514
+ }
4515
+
4516
+ /** The same stock seam reader, restricted to one canonical setup-only frame. */
4517
+ export function readMotionRootSetup(dir: string, fps: number, pairs: readonly MotionSeamPair[]): MotionRootSetupRow[] {
4518
+ const problems: Problem[] = [];
4519
+ const sidecar = readJson(join(dir, 'frames.json'), problems);
4520
+ const sets = sidecar !== null && Array.isArray(sidecar.sets) ? sidecar.sets.filter(isRecord) : [];
4521
+ const set = sets[0];
4522
+ if (sidecar?.spec !== 'rigc-frames/1' || sets.length !== 1 || set.animation !== null || set.fps !== fps ||
4523
+ set.sampled !== 1 || set.written !== 1 || set.stride !== 1 || set.duration !== 0 || typeof set.dir !== 'string' ||
4524
+ isAbsolute(set.dir) || set.dir.split(/[\\/]/).includes('..')) {
4525
+ problems.push({ code: 'FRAMES_SIDECAR', object: join(dir, 'frames.json'),
4526
+ detail: 'requires exactly one stock setup-only set: animation null, sampled/written/stride 1, duration 0, the requested fps and a local directory; unavailable is not zero overlap' });
4527
+ }
4528
+ refuseIfAny(problems);
4529
+ const rows = readSeamRows(dir, ['setup'], fps, pairs, {}, undefined, true);
4530
+ for (const row of rows) if (row.drawn !== 1 || (row.banded !== 0 && row.banded !== 1) || row.status !== (row.banded === 1 ? 'read' : 'skip')) {
4531
+ problems.push({ code: 'FRAMES_SIDECAR', object: row.pair,
4532
+ detail: 'setup seam requires both drawings on its one frame, banded 0/1 and matching skip/read; an absent drawing is not zero overlap' });
4533
+ }
4534
+ refuseIfAny(problems);
4535
+ return rows.map(({ pair, drawn, banded, status }) => ({ pair, drawn, banded, status }));
4536
+ }
4537
+
4538
+ function readSeamRows(dir: string, animations: readonly string[], fps: number, pairs: readonly MotionSeamPair[], plant: MotionSeamPlant = {}, worldRows?: MotionSeamWorldRow[], setup = false, coverageReader?: RootGapCoverageReader): MotionSeamRow[] {
3769
4539
  const problems: Problem[] = [];
3770
4540
  const bad = (object: string, detail: string): void => {
3771
4541
  problems.push({ code: 'FRAMES_SIDECAR', object, detail });
@@ -3777,7 +4547,8 @@ export function readMotionSeams(dir: string, animations: readonly string[], fps:
3777
4547
  const hitOf = (h: unknown): SeamHitRead | null =>
3778
4548
  isRecord(h) && typeof h.index === 'number' && typeof h.px === 'number' && typeof h.cell === 'number' && h.cell > 0 && nums(h.box) && h.box.length === 4 ? { index: h.index, px: h.px, cell: h.cell, box: [h.box[0], h.box[1], h.box[2], h.box[3]] } : null;
3779
4549
  for (const animation of animations) {
3780
- const set = sets.find((x) => x.animation === animation);
4550
+ const rawAnimation = setup ? null : animation;
4551
+ const set = sets.find((x) => x.animation === rawAnimation);
3781
4552
  if (set === undefined || typeof set.dir !== 'string') {
3782
4553
  bad(join(dir, 'frames.json'), `names no frame set for animation ${JSON.stringify(animation)}; \`rigc render --seam\` over the build writes one per animation`);
3783
4554
  continue;
@@ -3786,7 +4557,7 @@ export function readMotionSeams(dir: string, animations: readonly string[], fps:
3786
4557
  const file = readJson(path, problems);
3787
4558
  if (file === null) continue;
3788
4559
  if (file.spec !== SEAM_READING_SPEC) bad(path, `spec is ${JSON.stringify(file.spec)}; "${SEAM_READING_SPEC}" is required`);
3789
- if (file.animation !== animation) bad(path, `animation is ${JSON.stringify(file.animation)}; ${JSON.stringify(animation)} is required`);
4560
+ if (file.animation !== rawAnimation) bad(path, `animation is ${JSON.stringify(file.animation)}; ${JSON.stringify(rawAnimation)} is required`);
3790
4561
  if (file.fps !== fps) bad(path, `fps is ${JSON.stringify(file.fps)}; ${fps}, the rate asked for, is required`);
3791
4562
  const read = Array.isArray(file.pairs) ? file.pairs : [];
3792
4563
  if (read.length !== pairs.length) bad(path, `holds ${read.length} pair(s); the ${pairs.length} asked for, in the flag's order, are required`);
@@ -3802,6 +4573,11 @@ export function readMotionSeams(dir: string, animations: readonly string[], fps:
3802
4573
  return;
3803
4574
  }
3804
4575
  const over = new Map<number, number>();
4576
+ let rootWorst: MotionSeamRow['worst'];
4577
+ let rootGapFrames: number[] = [];
4578
+ let ghostFrames = 0;
4579
+ const coverage: RootGapCoverage[] = [];
4580
+ const exempt = new Set<number>();
3805
4581
  const kinds: Record<'gap' | 'ghost', MotionSeamWorldKind> = { gap: { max_px: 0, worst: null }, ghost: { max_px: 0, worst: null } };
3806
4582
  for (const kind of ['gap', 'ghost'] as const) {
3807
4583
  const k = p[kind];
@@ -3811,9 +4587,23 @@ export function readMotionSeams(dir: string, animations: readonly string[], fps:
3811
4587
  return;
3812
4588
  }
3813
4589
  const hits = frames as SeamHitRead[];
4590
+ if (kind === 'gap') rootGapFrames = hits.map(h => h.index);
4591
+ else ghostFrames = hits.length;
3814
4592
  const worst = hits.reduce<MotionSeamHit | null>((best, h) => best === null || h.px > best.px || (h.px === best.px && h.index < best.index) ? h : best, null);
3815
4593
  kinds[kind] = { max_px: worst?.px ?? 0, worst };
3816
- for (const h of hits) if (plant.noFloor === true || openingOverFloor(h)) over.set(h.index, Math.max(over.get(h.index) ?? 0, h.px));
4594
+ // rigc-seam/1 exposes aggregate ghost, not its drawing owner. A drawn
4595
+ // overlap band is not proof of a hole; only GAP gates roots until core#1555.
4596
+ for (const h of hits) if ((want.root === undefined || kind === 'gap') && (plant.noFloor === true || openingOverFloor(h))) {
4597
+ if (want.root !== undefined) {
4598
+ const raw = isRecord(k) && Array.isArray(k.frames) ? k.frames.find(v => isRecord(v) && v.index === h.index) : undefined;
4599
+ const time = isRecord(raw) && typeof raw.time === 'number' ? raw.time : undefined;
4600
+ const proof = coverageReader?.(want, animation, h, time) ?? rootGapBoxCoverage(h, null);
4601
+ coverage.push(proof);
4602
+ if (proof.status === 'exempt') { exempt.add(h.index); continue; }
4603
+ }
4604
+ over.set(h.index, Math.max(over.get(h.index) ?? 0, h.px));
4605
+ if (want.root !== undefined && (rootWorst === undefined || h.px > rootWorst.px || (h.px === rootWorst.px && h.index < rootWorst.index))) rootWorst = { ...h, kind: 'gap' };
4606
+ }
3817
4607
  }
3818
4608
  worldRows?.push({ pair: want.pair, animation, status: p.status, drawn: p.drawn, banded: p.banded, gap: kinds.gap, ghost: kinds.ghost });
3819
4609
  const opens = [...over.keys()].sort((x, y) => x - y);
@@ -3826,7 +4616,10 @@ export function readMotionSeams(dir: string, animations: readonly string[], fps:
3826
4616
  opens,
3827
4617
  px: opens.map((f) => over.get(f) ?? 0),
3828
4618
  max_px: opens.reduce((m, f) => Math.max(m, over.get(f) ?? 0), 0),
3829
- under_floor: p.opens.filter((f) => !over.has(f)),
4619
+ under_floor: (want.root === undefined ? p.opens : rootGapFrames).filter((f) => !over.has(f) && !exempt.has(f)),
4620
+ ...(rootWorst === undefined ? {} : { worst: rootWorst }),
4621
+ ...(coverage.length === 0 ? {} : { coverage }),
4622
+ ...(want.root === undefined ? {} : { ghost_info: { ...kinds.ghost, owner: 'unavailable' as const, frames: ghostFrames } }),
3830
4623
  });
3831
4624
  });
3832
4625
  }
@@ -3834,19 +4627,44 @@ export function readMotionSeams(dir: string, animations: readonly string[], fps:
3834
4627
  return rows;
3835
4628
  }
3836
4629
 
3837
- /** The line from its rows: WARN when a row has a frame over the floor, CLEAR when none has, SKIP when no row was read. */
3838
- export function motionSeamLine(pairs: MotionSeamPair[], animations: string[], fps: number, rows: MotionSeamRow[], reason?: string): MotionSeamLine {
3839
- const warnings = rows.filter((r) => r.opens.length > 0).length;
4630
+ /** Only active proven root GAP rows fail; mixed ghost is INFO. Existing warnings/floor are unchanged. */
4631
+ export function motionSeamLine(pairs: MotionSeamPair[], animations: string[], fps: number, rows: MotionSeamRow[], reason?: string, problems: Problem[] = [], unmeasuredRoots: readonly MotionUnmeasuredRoot[] = []): MotionSeamLine {
4632
+ const roots = pairs.filter(p => p.root !== undefined);
4633
+ const rootNames = new Set(roots.map(p => p.pair));
4634
+ const warnings = rows.filter((r) => !rootNames.has(r.pair) && r.opens.length > 0).length;
4635
+ const failed = rows.filter(r => rootNames.has(r.pair) && r.status === 'read' && r.banded > 0 && r.opens.length > 0);
4636
+ for (const row of failed) {
4637
+ const h = row.worst;
4638
+ const proof = row.coverage?.find(p => p.index === h?.index);
4639
+ problems.push({ code: 'CHECK_SEAM_OVER_MOTION', object: 'body-root seam "' + row.pair + '" in "' + row.animation + '"',
4640
+ detail: h === undefined
4641
+ ? 'opens on frames ' + frameRuns(row.opens) + ', max ' + row.max_px + ' cells; no above-floor root hit metadata was returned'
4642
+ : h.kind + ' at frame ' + h.index + ' (t = ' + h.index / fps + 's): ' + h.px + ' cells, cell ' + h.cell + ', world box [' + h.box.join(', ') + ']; at most ' + Math.round(Math.max(h.box[2] - h.box[0], h.box[3] - h.box[1]) / h.cell) + ' cells, the unchanged one-cell floor, is required' + (proof === undefined ? '' : '; ' + proof.status + ': ' + proof.reason + '; entire original GAP count retained') });
4643
+ }
4644
+ const missing = roots.flatMap(p => animations.length === 0 ? ['"' + p.pair + '": no animation'] : animations.flatMap(a => {
4645
+ const row = rows.find(r => r.pair === p.pair && r.animation === a);
4646
+ return row?.status === 'read' && row.banded > 0 ? [] : ['"' + p.pair + '" in "' + a + '": ' + (p.unread ?? (row === undefined ? 'no returned reading' : 'no band on any frame'))];
4647
+ }));
4648
+ const unmeasured = unmeasuredRoots.map(root => ({ ...root, candidates: [...root.candidates] }));
4649
+ const rootReasons = [...missing, ...unmeasured.map(root => 'root pair for ' + root.limb + ': ' + root.reason)];
4650
+ const rootGate: MotionSeamLine['roots'] = roots.length === 0 && unmeasured.length === 0 ? undefined : {
4651
+ status: failed.length > 0 ? 'FAIL' : rootReasons.length > 0 || reason !== undefined ? 'SKIP' : 'PASS',
4652
+ mode: 'gap-only', ghost_owner: 'unavailable', ghost_followup: 'rig-c/core#1555',
4653
+ pairs: roots.map(p => p.pair), failed: failed.length,
4654
+ ...(rootReasons.length === 0 && reason === undefined ? {} : { reason: unmeasured.length === 0 ? (reason ?? missing.join('; ')) : [reason, ...rootReasons].filter(r => r !== undefined).join('; ') }),
4655
+ ...(unmeasured.length === 0 ? {} : { unmeasured }),
4656
+ };
3840
4657
  const read = rows.some((r) => r.status === 'read');
3841
4658
  const skipWhy =
3842
4659
  reason ??
4660
+ (pairs.length === 0 && unmeasured.length > 0 ? rootGate?.reason : undefined) ??
3843
4661
  (read
3844
4662
  ? undefined
3845
4663
  : pairs.every((p) => p.unread !== undefined)
3846
4664
  ? `no declared pair is read: ${pairs.map((p) => `"${p.pair}" ${String(p.unread)}`).join('; ')}`
3847
4665
  : `rigc read no band on any frame of any declared pair in any animation — nothing measured, which is not a seam that held`);
3848
4666
  return {
3849
- status: skipWhy !== undefined ? 'SKIP' : warnings > 0 ? 'WARN' : 'CLEAR',
4667
+ status: rootGate?.status === 'FAIL' ? 'FAIL' : skipWhy !== undefined ? 'SKIP' : warnings > 0 ? 'WARN' : 'CLEAR',
3850
4668
  ...(skipWhy === undefined ? {} : { reason: skipWhy }),
3851
4669
  fps,
3852
4670
  floor: MOTION_SEAM_FLOOR,
@@ -3854,6 +4672,7 @@ export function motionSeamLine(pairs: MotionSeamPair[], animations: string[], fp
3854
4672
  animations,
3855
4673
  warnings,
3856
4674
  rows,
4675
+ ...(rootGate === undefined ? {} : { roots: rootGate }),
3857
4676
  };
3858
4677
  }
3859
4678
 
@@ -4192,7 +5011,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4192
5011
  const keptDir = join(out, STILL_DIR);
4193
5012
  const foldDir = join(out, FOLD_SCRATCH);
4194
5013
  const seamMotionDir = join(out, MOTION_SEAM_SCRATCH);
4195
- for (const d of [buildDir, idleDir, stillDir, isoDir, loopDir, seamDir, keptDir, foldDir, seamMotionDir]) rmSync(d, { recursive: true, force: true });
5014
+ for (const d of [buildDir, idleDir, stillDir, isoDir, loopDir, seamDir, keptDir, join(out, 'setup_still_auto'), foldDir, seamMotionDir, join(out, ROOT_COVERAGE_DIR)]) rmSync(d, { recursive: true, force: true });
4196
5015
  const written: string[] = [];
4197
5016
  const write = (name: string, data: string): void => {
4198
5017
  writeFileSync(join(out, name), data);
@@ -4534,13 +5353,50 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4534
5353
  }
4535
5354
  }
4536
5355
 
4537
- // 3e. every declared neighbour pair read in every animation by rigc's seam reading (issue #493): a warning, never a
4538
- // bar — the build as played, at the idle's rate; SKIP, named, with no pair declared or no animation to read
5356
+ // 3e. Existing neighbour pairs warn (issue #493); proven body-root tears alone gate (issue #686).
5357
+ // Read the build as played at the idle's rate; unavailable data is named SKIP.
4539
5358
  let motionSeam: MotionSeamLine;
5359
+ const motionRootProblems: Problem[] = [];
4540
5360
  {
4541
5361
  const fps = IDLE_FPS;
4542
5362
  const seamReqs = reqFile === null || seams === null ? [] : reqFile.requirements.flatMap((r) => (r.kind === 'seam' && seams?.has(r.name) === true ? [{ name: r.name, part: r.part, neighbour: r.neighbour }] : []));
4543
- const pairs = inp.parts === null ? [] : motionSeamPairs(inp.parts, seamReqs);
5363
+ const selection: MotionSeamSelection = inp.parts === null ? { pairs: [], unmeasuredRoots: [] } : motionSeamSelection(inp.parts, seamReqs, inp.rig, candidates => {
5364
+ // The stock reader's band is setup alpha overlap, not an inferred distance.
5365
+ // A static motion copy changes only animations; the accepted candidate and
5366
+ // authored motion remain intact. Root-free inputs never enter this path.
5367
+ const setupDir = join(out, '_seam_root_setup');
5368
+ rmSync(setupDir, { recursive: true, force: true });
5369
+ mkdirSync(setupDir, { recursive: true });
5370
+ try {
5371
+ let candidate = buildDir;
5372
+ if (isRecord(inp.motion.animations) && Object.keys(inp.motion.animations).length > 0) {
5373
+ const motion = join(setupDir, 'motion.json');
5374
+ writeFileSync(motion, JSON.stringify({ ...inp.motion, animations: {} }));
5375
+ candidate = join(setupDir, 'build');
5376
+ const compiled = rigc(['build', '--rig', inp.rigPath, '--motion', motion, '--out', candidate, ...packedBuildArgs(mode)]);
5377
+ if (compiled.status !== 0) refuseIfAny(rigcFailed('build (body-root setup observation)', compiled, buildGateLines(compiled.out)));
5378
+ const problems: Problem[] = [];
5379
+ const original = readJson(join(buildDir, 'skeleton.json'), problems);
5380
+ const setup = readJson(join(candidate, 'skeleton.json'), problems);
5381
+ const changed = ['bones', 'slots', 'skins', 'ik', 'transform', 'path', 'physics'].filter(key =>
5382
+ JSON.stringify(original?.[key]) !== JSON.stringify(setup?.[key]));
5383
+ const pages = parsePackLines(compiled.out.split('\n')).map(page => page.page);
5384
+ if (original === null || setup === null || !isRecord(setup.animations) || Object.keys(setup.animations).length > 0 || changed.length > 0 ||
5385
+ JSON.stringify(pages) !== JSON.stringify(pack.map(page => page.page)) ||
5386
+ pages.some(page => !existsSync(join(candidate, page)) || !readFileSync(join(buildDir, page)).equals(readFileSync(join(candidate, page))))) {
5387
+ problems.push({ code: 'CHECK_MOTION_SEAM_ROOT', object: 'stock setup observation',
5388
+ detail: 'requires unchanged default bones/slots/skins/constraints and atlas PNG bytes, with no animation; differing default fields: ' + changed.join(', ') });
5389
+ }
5390
+ refuseIfAny(problems);
5391
+ }
5392
+ const renderDir = join(setupDir, 'render');
5393
+ const list = candidates.map(pair => pair.a + ':' + pair.b).join(',');
5394
+ const rendered = rigc(['render', '--candidate', candidate, '--seam', list, '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--out', renderDir]);
5395
+ if (rendered.status !== 0) refuseIfAny(rigcFailed('render --seam (body-root setup observation)', rendered, rendered.out.split('\n').filter(line => line.includes('FAIL') || line.includes('rigc:'))));
5396
+ return readMotionRootSetup(renderDir, fps, candidates);
5397
+ } finally { rmSync(setupDir, { recursive: true, force: true }); }
5398
+ });
5399
+ const { pairs, unmeasuredRoots } = selection;
4544
5400
  const slotNames = new Set((Array.isArray(inp.rig.slots) ? inp.rig.slots : []).filter(isRecord).map((sl) => String(sl.name)));
4545
5401
  for (const p of pairs) {
4546
5402
  const missing = [p.a, p.b].filter((n) => !slotNames.has(n));
@@ -4548,19 +5404,22 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4548
5404
  }
4549
5405
  const read = pairs.filter((p) => p.unread === undefined);
4550
5406
  if (inp.parts === null) motionSeam = motionSeamLine([], animationNames, fps, [], inp.noParts ?? 'no parts.json');
4551
- else if (pairs.length === 0) motionSeam = motionSeamLine([], animationNames, fps, [], 'no neighbour pair is declared: parts.json holds no limb segment below a joint (config.limbs) and no --requirements seam names two parts');
4552
- else if (animationNames.length === 0) motionSeam = motionSeamLine(pairs, [], fps, [], 'motion.json holds no animation to read the declared pairs in');
4553
- else if (read.length === 0) motionSeam = motionSeamLine(pairs, animationNames, fps, []);
5407
+ else if (pairs.length === 0) motionSeam = motionSeamLine([], animationNames, fps, [], unmeasuredRoots.length === 0
5408
+ ? 'no neighbour pair is declared: parts.json holds no limb segment below a joint (config.limbs) and no --requirements seam names two parts'
5409
+ : undefined, motionRootProblems, unmeasuredRoots);
5410
+ else if (animationNames.length === 0) motionSeam = motionSeamLine(pairs, [], fps, [], 'motion.json holds no animation to read the declared pairs in', motionRootProblems, unmeasuredRoots);
5411
+ else if (read.length === 0) motionSeam = motionSeamLine(pairs, animationNames, fps, [], undefined, motionRootProblems, unmeasuredRoots);
4554
5412
  else {
4555
5413
  rmSync(seamMotionDir, { recursive: true, force: true });
4556
5414
  {
4557
5415
  const list = read.map((p) => `${p.a}:${p.b}`).join(',');
4558
5416
  const activeDest = stripped === null ? seamMotionDir : join(seamMotionDir, env === null ? 'default' : 'active');
4559
5417
  const renderedWorlds = new Set<'default' | 'still'>();
4560
- const r = measured(['render', '--candidate', buildDir, '--seam', list, '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--out', activeDest]);
5418
+ const hasRoots = read.some(p => p.root !== undefined);
5419
+ const r = measured(['render', '--candidate', buildDir, '--seam', list, '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), ...(hasRoots ? ['--geometry'] : []), '--out', activeDest]);
4561
5420
  if (r.status !== 0) refuseIfAny(rigcFailed(`render --seam ${list} --fps ${fps}`, r, r.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
4562
5421
  const activeWorldRows: MotionSeamWorldRow[] = [];
4563
- motionSeam = motionSeamLine(pairs, animationNames, fps, readMotionSeams(activeDest, animationNames, fps, read, {}, stripped !== null && env === null ? activeWorldRows : undefined));
5422
+ motionSeam = motionSeamLine(pairs, animationNames, fps, readMotionSeams(activeDest, animationNames, fps, read, {}, stripped !== null && env === null ? activeWorldRows : undefined, hasRoots ? motionRootCoverageReader(buildDir, activeDest, out) : undefined), undefined, motionRootProblems, unmeasuredRoots);
4564
5423
  if (stripped !== null) {
4565
5424
  const response = environmentResponse(readFileSync(join(buildDir, 'skeleton.json'), 'utf8'));
4566
5425
  motionSeam.worlds = motionSeamWorlds(true, response.wind.length > 0, world => {
@@ -4611,6 +5470,8 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4611
5470
  // 4. the setup pose as a one-key throwaway animation — the seam reads it against the parts, the source line against
4612
5471
  // the painting — and, beside it, the same pose with the eyes shut
4613
5472
  let seam: SeamFigures | null = null;
5473
+ let seamScope: SeamScope | undefined;
5474
+ const seamStacks = new SeamStacks();
4614
5475
  let seamPairs: SeamPairRow[] | null = null;
4615
5476
  let seamViewport: Viewport | null = null;
4616
5477
  let blink: JudgementLine = skip(lacking);
@@ -4646,48 +5507,88 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4646
5507
  if (sr.status !== 0) refuseIfAny(rigcFailed('render (the setup-pose still)', sr, sr.out.split('\n').filter((l) => l.includes('FAIL'))));
4647
5508
  const stillSet = readFrameSet(join(stillDir, 'render'));
4648
5509
  seamViewport = stillSet.viewport;
4649
- if (keepStills) cpSync(join(stillDir, 'render'), keptDir, { recursive: true });
5510
+ if (keepStills) cpSync(join(stillDir, 'render'), inp.parts === null ? keptDir : join(out, 'setup_still_auto'), { recursive: true });
4650
5511
  if (inp.parts !== null) {
5512
+ // Stage existing gated files, not decoded pages/poses. No second build or gate.
5513
+ const selectedAlts = set !== undefined || allSets
5514
+ ? (allSets ? (inp.parts.alternates ?? []) : (inp.parts.alternates ?? []).filter(a => a.name === set)) : [];
5515
+ const setStillAnimations: Record<string, unknown> = { still: animations.still };
5516
+ const setStillBase = { ...withoutSliders(inp.rig, setStillAnimations), images };
5517
+ const setsJsonPath = join(inp.rigDir, SETS_FILE);
5518
+ const setsJsonRaw = existsSync(setsJsonPath) ? readJson(setsJsonPath, []) : null;
5519
+ const setsMap = setsJsonRaw !== null && isRecord(setsJsonRaw.sets) ? setsJsonRaw.sets : null;
5520
+ const staged = selectedAlts.map(alt => {
5521
+ const entry = setsMap !== null && isRecord(setsMap[alt.name]) ? setsMap[alt.name] as Record<string, unknown> : null;
5522
+ const drawn = entry !== null && isRecord(entry.drawn)
5523
+ ? Object.fromEntries(Object.entries(entry.drawn).filter((e): e is [string, number] => typeof e[1] === 'number' && Number.isFinite(e[1]))) : alt.drawn;
5524
+ const dir = join(stillDir, 'set_' + alt.name);
5525
+ mkdirSync(dir, { recursive: true });
5526
+ writeFileSync(join(dir, 'rig.json'), JSON.stringify(stillRigForSet(setStillBase, alt, drawn)));
5527
+ writeFileSync(join(dir, 'motion.json'), JSON.stringify({ ...inp.motion, animations: setStillAnimations }));
5528
+ const built = rigc(['build', '--rig', join(dir, 'rig.json'), '--motion', join(dir, 'motion.json'), '--out', join(dir, 'build'), '--profile', 'spine']);
5529
+ if (built.status !== 0) refuseIfAny(rigcFailed(`build (the setup-pose still of set "${alt.name}")`, built, buildGateLines(built.out)));
5530
+ return { alt, dir };
5531
+ });
5532
+ const states: SeamStateBounds[] = [seamStateBounds(join(stillDir, 'build'), 'base')];
5533
+ for (const { alt, dir } of staged) states.push(seamStateBounds(join(dir, 'build'), alt.name));
5534
+ const union = seamUnionViewport(inp.stage, states);
5535
+ const domain = { viewport: union, authored: inp.stage, numerator: inp.parts.scene === undefined ? 'whole-union' as const : 'authored-scene-interior' as const, states };
5536
+ const canonical = (build: string, dir: string): FrameSet => {
5537
+ const cr = rigc(['render', '--candidate', build, '--animation', 'still', '--fps', String(STILL_FPS), '--max', String(Math.max(union.width, union.height)), '--viewport', [union.x, union.y, union.width, union.height].join(','), '--geometry', '--out', dir]);
5538
+ if (cr.status !== 0) refuseIfAny(rigcFailed('render (the source-grid setup seam)', cr, cr.out.split('\n').filter(l => l.includes('FAIL'))));
5539
+ const reading = readFrameSet(dir);
5540
+ seamCanonicalViewport(inp.stage, reading.viewport, JSON.parse(readFileSync(join(dir, 'frames.json'), 'utf8')) as unknown, union);
5541
+ return reading;
5542
+ };
5543
+ const canonicalSet = canonical(join(stillDir, 'build'), join(stillDir, 'seam'));
5544
+ seamViewport = canonicalSet.viewport;
5545
+ if (keepStills) cpSync(join(stillDir, 'seam'), keptDir, { recursive: true });
4651
5546
  const composite = flatComposite(inp.parts, inp.partsDir, stillSet.background);
4652
- seam = seamFigures(composite, stillSet.frames[0].image, inp.stage, stillSet.viewport, stillSet.background, undefined, inp.parts.scene !== undefined);
4653
- if (seamPairsAsked || seamFails(round3(seam.mean), seam.over40, round6(stillSet.viewport.scale))) {
4654
- const placed = inp.parts.parts.map((p) => ({ name: p.name, from: p.from, x: p.x, y: p.y, image: readPng(join(inp.partsDir, `${p.name}.png`)) }));
4655
- const split = seamPairRows(seam, placed, inp.parts.rig_size, stillSet.viewport);
5547
+ const autoSeam = seamFigures(composite, stillSet.frames[0].image, inp.stage, stillSet.viewport, stillSet.background, undefined, inp.parts.scene !== undefined);
5548
+ seam = seamFigures(composite, canonicalSet.frames[0].image, inp.stage, canonicalSet.viewport, canonicalSet.background, undefined, inp.parts.scene !== undefined, undefined, true);
5549
+ seamScope = { mode: 'source-grid/base', domain, denominator_px: canonicalDenominator(seam), auto_frame_raw: seamReading(autoSeam, stillSet.viewport), whole: seamReading(seam, canonicalSet.viewport) };
5550
+ const placed = inp.parts.parts.map(p => ({ name: p.name, from: p.from, x: p.x, y: p.y, image: readPng(join(inp.partsDir, `${p.name}.png`)) }));
5551
+ const baseRows = seamPairRows(seam, placed, inp.parts.rig_size, canonicalSet.viewport);
5552
+ seamScope.whole_pairs = baseRows.map(({ row: { picture: _picture, ...raw } }) => raw);
5553
+ if (seamPairsAsked || seamFails(round3(seam.mean), seam.over40, 1)) {
5554
+ const split = baseRows;
4656
5555
  mkdirSync(seamDir, { recursive: true });
4657
- for (const { row, pixels } of split) writePng(join(out, row.picture), seamPicture(stillSet.frames[0].image, row, pixels));
5556
+ for (const { row, pixels } of split) writePng(join(out, row.picture), seamPicture(canonicalSet.frames[0].image, row, pixels));
4658
5557
  seamPairs = split.map((x) => x.row);
4659
5558
  }
4660
5559
  if (set !== undefined || allSets) {
4661
- const alts = allSets ? (inp.parts.alternates ?? []) : (inp.parts.alternates ?? []).filter((a) => a.name === set);
4662
- const setStillAnimations: Record<string, unknown> = { still: animations.still };
4663
- const setStillBase = { ...withoutSliders(inp.rig, setStillAnimations), images };
4664
- const setsJsonPath = join(inp.rigDir, SETS_FILE);
4665
- const setsJsonRaw = existsSync(setsJsonPath) ? readJson(setsJsonPath, []) : null;
4666
- const setsMap = setsJsonRaw !== null && isRecord(setsJsonRaw.sets) ? setsJsonRaw.sets : null;
4667
- for (const alt of alts) {
4668
- const setEntry: Record<string, unknown> | null =
4669
- setsMap !== null && isRecord(setsMap[alt.name]) ? (setsMap[alt.name] as Record<string, unknown>) : null;
4670
- const setDrawn: Record<string, number> | undefined =
4671
- setEntry !== null && isRecord(setEntry.drawn)
4672
- ? Object.fromEntries(
4673
- Object.entries(setEntry.drawn).filter((entry): entry is [string, number] => typeof entry[1] === 'number' && Number.isFinite(entry[1])),
4674
- )
4675
- : alt.drawn;
4676
- const setDir = join(stillDir, `set_${alt.name}`);
4677
- mkdirSync(setDir, { recursive: true });
4678
- writeFileSync(join(setDir, 'rig.json'), JSON.stringify(stillRigForSet(setStillBase, alt, setDrawn)));
4679
- writeFileSync(join(setDir, 'motion.json'), JSON.stringify({ ...inp.motion, animations: setStillAnimations }));
4680
- const asb = rigc(['build', '--rig', join(setDir, 'rig.json'), '--motion', join(setDir, 'motion.json'), '--out', join(setDir, 'build'), '--profile', 'spine']);
4681
- if (asb.status !== 0) refuseIfAny(rigcFailed(`build (the setup-pose still of set "${alt.name}")`, asb, buildGateLines(asb.out)));
5560
+ const baseSupport = seamSupport(join(stillDir, 'build'), join(stillDir, 'rig.json'), canonicalSet, placed, seamStacks, inp.stage);
5561
+ for (const { alt, dir: setDir } of staged) {
4682
5562
  const asr = rigc(['render', '--candidate', join(setDir, 'build'), '--animation', 'still', '--fps', String(STILL_FPS), '--max', String(maxSide), '--out', join(setDir, 'render')]);
4683
5563
  if (asr.status !== 0) refuseIfAny(rigcFailed(`render (the setup-pose still of set "${alt.name}")`, asr, asr.out.split('\n').filter((l) => l.includes('FAIL'))));
4684
5564
  const altStillSet = readFrameSet(join(setDir, 'render'));
4685
- if (keepStills) cpSync(join(setDir, 'render'), join(keptDir, alt.name), { recursive: true });
5565
+ if (keepStills) cpSync(join(setDir, 'render'), join(out, 'setup_still_auto', alt.name), { recursive: true });
4686
5566
  const rigSlotOrder = (Array.isArray(inp.rig.slots) ? inp.rig.slots : []).filter(isRecord).map((sl) => String(sl.name));
4687
5567
  const altComposite = flatCompositeForSet(inp.parts, alt, inp.partsDir, altStillSet.background, rigSlotOrder);
4688
- const altSeam = seamFigures(altComposite, altStillSet.frames[0].image, inp.stage, altStillSet.viewport, altStillSet.background, undefined, alt.scene !== undefined);
5568
+ const altCanonical = canonical(join(setDir, 'build'), join(setDir, 'seam'));
5569
+ if (keepStills) cpSync(join(setDir, 'seam'), join(keptDir, alt.name), { recursive: true });
5570
+ const altPlaced = setPlacements(inp.parts, alt, rigSlotOrder).map(({ name, png, box }) => ({ name, from: box.from, x: box.x, y: box.y, image: readPng(join(inp.partsDir, `${png}.png`)) }));
5571
+ const altSupport = seamSupport(join(setDir, 'build'), join(setDir, 'rig.json'), altCanonical, altPlaced, seamStacks, inp.stage);
5572
+ const effects = seamEffectSelection(baseSupport, altSupport);
5573
+ const autoAltSeam = seamFigures(altComposite, altStillSet.frames[0].image, inp.stage, altStillSet.viewport, altStillSet.background, undefined, alt.scene !== undefined);
5574
+ const wholeAltSeam = seamFigures(altComposite, altCanonical.frames[0].image, inp.stage, altCanonical.viewport, altCanonical.background, undefined, inp.parts.scene !== undefined, undefined, true);
5575
+ const altSeam = seamFigures(altComposite, altCanonical.frames[0].image, inp.stage, altCanonical.viewport, altCanonical.background, undefined, inp.parts.scene !== undefined, effects.mask, true);
5576
+ const wholeRows = seamPairRows(wholeAltSeam, altPlaced, inp.parts.rig_size, altCanonical.viewport);
5577
+ const altScope: SeamScope = {
5578
+ mode: 'source-grid/affected-set', domain, denominator_px: canonicalDenominator(altSeam),
5579
+ auto_frame_raw: seamReading(autoAltSeam, altStillSet.viewport), whole: seamReading(wholeAltSeam, altCanonical.viewport), effects: effects.reasons, changes: effects.changes,
5580
+ ...((baseSupport.unavailable ?? altSupport.unavailable) === undefined ? {} : { unavailable: baseSupport.unavailable ?? altSupport.unavailable }),
5581
+ // Raw rows retain every original field except an unwritten picture.
5582
+ whole_pairs: wholeRows.map(({ row: { picture: _picture, ...raw } }) => raw),
5583
+ pairs: wholeRows.map(({ row, pixels }) => {
5584
+ const affected = pixels.filter(q => effects.mask[q] !== 0).length;
5585
+ const reasons: Partial<SeamEffects['reasons']> = {};
5586
+ for (const q of pixels) { const reason = SEAM_EFFECT_REASONS[effects.cellReasons[q]]; reasons[reason] = (reasons[reason] ?? 0) + 1; }
5587
+ return { parts: row.parts, whole_px_over_40: row.px_over_40, affected_px_over_40: affected, inherited_px_over_40: row.px_over_40 - affected, reasons };
5588
+ }),
5589
+ };
4689
5590
  const altMean = round3(altSeam.mean);
4690
- const altScale = round6(altStillSet.viewport.scale);
5591
+ const altScale = 1;
4691
5592
  const altFailed = seamFails(altMean, altSeam.over40, altScale);
4692
5593
  if (altFailed) {
4693
5594
  const hint = armSplitSetHint(inp.parts, alt);
@@ -4695,22 +5596,22 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4695
5596
  }
4696
5597
  let altPairs: SeamPairRow[] | null = null;
4697
5598
  if (seamPairsAsked || altFailed) {
4698
- const placed = setPlacements(inp.parts, alt, rigSlotOrder).map(({ name, png, box }) => ({ name, from: box.from, x: box.x, y: box.y, image: readPng(join(inp.partsDir, `${png}.png`)) }));
4699
- const split = seamPairRows(altSeam, placed, inp.parts.rig_size, altStillSet.viewport);
5599
+ const split = seamPairRows(altSeam, altPlaced, inp.parts.rig_size, altCanonical.viewport);
4700
5600
  const altSeamDir = join(seamDir, alt.name);
4701
5601
  mkdirSync(altSeamDir, { recursive: true });
4702
5602
  for (const { row, pixels } of split) {
4703
5603
  row.picture = `${SEAM_DIR}/${alt.name}/${basename(row.picture)}`;
4704
- writePng(join(out, row.picture), seamPicture(altStillSet.frames[0].image, row, pixels));
5604
+ writePng(join(out, row.picture), seamPicture(altCanonical.frames[0].image, row, pixels));
4705
5605
  }
4706
5606
  altPairs = split.map((x) => x.row);
4707
5607
  }
4708
5608
  setsFigures[alt.name] = {
4709
- render_px: `${altStillSet.viewport.pixelWidth}x${altStillSet.viewport.pixelHeight}`,
5609
+ render_px: `${altCanonical.viewport.pixelWidth}x${altCanonical.viewport.pixelHeight}`,
4710
5610
  seam_mean: altMean,
4711
5611
  seam_px_over_40: altSeam.over40,
4712
5612
  seam_px_over_80: altSeam.over80,
4713
5613
  seam_frame_scale: altScale,
5614
+ seam_scope: altScope,
4714
5615
  ...(altSeam.border === null ? {} : { seam_border: { frame_px_left_out: altSeam.border.framePx, px_over_40_left_out: altSeam.border.over40 } }),
4715
5616
  ...(altPairs === null ? {} : { seam_pairs: altPairs }),
4716
5617
  RECOMPOSITE_HOLES: altHolesLine(inp.parts, alt),
@@ -4773,6 +5674,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4773
5674
  seam_px_over_40: seam === null ? null : seam.over40,
4774
5675
  seam_px_over_80: seam === null ? null : seam.over80,
4775
5676
  seam_frame_scale: seam === null || seamViewport === null ? null : round6(seamViewport.scale),
5677
+ ...(seamScope === undefined ? {} : { seam_scope: seamScope }),
4776
5678
  ...(seam === null || seam.border === null ? {} : { seam_border: { frame_px_left_out: seam.border.framePx, px_over_40_left_out: seam.border.over40 } }),
4777
5679
  ...(seamPairs === null ? {} : { seam_pairs: seamPairs }),
4778
5680
  BREATH_VISIBLE: breath,
@@ -4786,7 +5688,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4786
5688
  ...(stress === null ? {} : { [STRESS_LINE]: stress }),
4787
5689
  ...(limbs === null ? {} : { [LIMB_LINE]: limbs }),
4788
5690
  ...(sweep === null ? {} : { [SWEEP_LINE]: sweep }),
4789
- ...(motionSeam.pairs.length === 0 ? {} : { [MOTION_SEAM_LINE]: motionSeam }),
5691
+ ...(motionSeam.pairs.length === 0 && motionSeam.roots === undefined ? {} : { [MOTION_SEAM_LINE]: motionSeam }),
4790
5692
  ...(stripped === null || idle === null ? {} : { [CLOTH_LINE]: cloth }),
4791
5693
  RECOMPOSITE_HOLES: inp.parts === null ? { status: 'SKIP', reason: inp.noParts ?? '' } : holesLine(inp.parts),
4792
5694
  ...(sourceRead === null ? {} : { [SOURCE_LINE]: sourceRead }),
@@ -4810,7 +5712,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4810
5712
  const worst = seamPairs === null || seamPairs.length === 0 ? null : seamPairs[0];
4811
5713
  barProblems.push({
4812
5714
  code: 'CHECK_SEAM_WITHIN_BAR',
4813
- object: 'the setup-pose render vs the flat composite of parts/',
5715
+ object: 'the source-grid setup-pose render vs the flat composite of parts/ (base, judged once)',
4814
5716
  detail:
4815
5717
  `mean |d| ${figures.seam_mean}/255 and ${figures.seam_px_over_40} frame px over ${SEAM_PX_LEVEL} (${figures.seam_px_over_80} over ${SEAM_PX_LEVEL_HIGH}) at frame scale ${figures.seam_frame_scale}, ${seamRigPxText(figures.seam_px_over_40, figures.seam_frame_scale)} rig px (the count / s²); mean <= ${SEAM_MEAN_BAR.toFixed(1)} and <= ${SEAM_PX_BAR} rig px over ${SEAM_PX_LEVEL} are required` +
4816
5718
  (worst === null
@@ -4823,7 +5725,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4823
5725
  const worst = setFig.seam_pairs === undefined || setFig.seam_pairs.length === 0 ? null : setFig.seam_pairs[0];
4824
5726
  barProblems.push({
4825
5727
  code: 'CHECK_SEAM_WITHIN_BAR',
4826
- object: `the setup-pose render of set "${setName}" vs the flat composite of parts/`,
5728
+ object: `the source-grid setup-pose render of set "${setName}" vs the flat composite of parts/ (affected cells only, base denominator retained)`,
4827
5729
  detail:
4828
5730
  `mean |d| ${setFig.seam_mean}/255 and ${setFig.seam_px_over_40} frame px over ${SEAM_PX_LEVEL} (${setFig.seam_px_over_80} over ${SEAM_PX_LEVEL_HIGH}) at frame scale ${setFig.seam_frame_scale}, ${seamRigPxText(setFig.seam_px_over_40, setFig.seam_frame_scale)} rig px (the count / s²); mean <= ${SEAM_MEAN_BAR.toFixed(1)} and <= ${SEAM_PX_BAR} rig px over ${SEAM_PX_LEVEL} are required` +
4829
5731
  (worst === null
@@ -4836,7 +5738,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4836
5738
  const rank = (q: Problem): number => JUDGEMENT_LINES.findIndex((n) => q.code === `CHECK_${n}`);
4837
5739
  problems.sort((a, b) => rank(a) - rank(b));
4838
5740
  problems.unshift(...barProblems);
4839
- problems.push(...foldProblems, ...levelProblems, ...stressProblems, ...limbProblems, ...sweepProblems, ...reqProblems);
5741
+ problems.push(...foldProblems, ...levelProblems, ...stressProblems, ...limbProblems, ...sweepProblems, ...motionRootProblems, ...reqProblems);
4840
5742
  figures.PASS = problems.length === 0;
4841
5743
  const publishCheck = (): void => write('check.json', `${JSON.stringify(figures, null, 1)}\n`);
4842
5744
  if (motionSeam.worlds === undefined) publishCheck();
@@ -4862,6 +5764,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4862
5764
  if (limbs !== null) tally(LIMB_LINE, null);
4863
5765
  // Issue #360: the range bar where it is written; a joint it cannot read fails, so it always measures.
4864
5766
  if (sweep !== null) tally(SWEEP_LINE, null);
5767
+ if (motionSeam.roots !== undefined) tally(MOTION_SEAM_LINE, motionSeam.roots.status === 'SKIP' ? (motionSeam.roots.reason ?? 'no body-root reading') : null);
4865
5768
  return {
4866
5769
  figures,
4867
5770
  gateHtml,