@rig-c/parts 1.60.1 → 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,8 +78,10 @@
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
- import { basename, delimiter, dirname, isAbsolute, join, relative, resolve } from 'node:path';
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';
84
86
  import { type BoneTransform, computeExactFrameTransforms, cropToSpineY, normaliseDegrees, toBoneLocal } from './coords.ts';
85
87
  import { capBox, inDisc } from './limbs.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,
@@ -465,53 +468,64 @@ export function readRigcEntry(versionOut: string): RigcEntryRecord {
465
468
  throw new Error('unreachable');
466
469
  }
467
470
 
471
+ /** Executable names, in selection order. Bun's rigc.bunx is a companion, never a command. */
472
+ function rigcPaths(directory: string, platform: 'win32' | 'posix'): string[] {
473
+ return (platform === 'win32' ? ['rigc', 'rigc.exe'] : ['rigc']).map(name => join(directory, name));
474
+ }
475
+
468
476
  /**
469
- * This package's own rigc: `node_modules/.bin/rigc` under `root` and nowhere else — no directory above it and no
470
- * PATH, which {@link findRigc} walks (issue #337). The selftest's suites run rigc through it from the package root,
471
- * so a fixture in a temp directory, or a tree nested inside another checkout (a harness worktree under
472
- * `.claude/worktrees/`) whose own install is missing, cannot reach another tree's rigc. A miss is refused naming
473
- * the one path looked at.
477
+ * This package's own rigc under root/node_modules/.bin and nowhere else: no ancestor or PATH.
478
+ * Windows Bun supplies rigc.exe and rigc.bunx; the executable keeps its own launcher's runtime gates.
479
+ * The optional platform argument lets the same discovery controls plant both install shapes.
474
480
  */
475
- export function packageRigc(root: string): string {
476
- const bin = join(resolve(root), 'node_modules', '.bin', 'rigc');
477
- if (!existsSync(bin)) {
478
- refuseIfAny([
479
- {
480
- code: 'CHECK_RIGC_PACKAGE',
481
- object: bin,
482
- detail: `does not exist; this package's own rigc is required here and no other is looked for — not in a directory above ${resolve(root)}, not on PATH (\`bun install\` puts it there)`,
483
- },
484
- ]);
485
- }
486
- return bin;
481
+ export function packageRigc(root: string, platform: 'win32' | 'posix' = sep === '\\' ? 'win32' : 'posix'): string {
482
+ const paths = rigcPaths(join(resolve(root), 'node_modules', '.bin'), platform);
483
+ const bin = paths.find(path => existsSync(path));
484
+ if (bin !== undefined) return bin;
485
+ refuseIfAny([
486
+ {
487
+ code: 'CHECK_RIGC_PACKAGE',
488
+ object: paths[0],
489
+ detail: platform === 'win32'
490
+ ? "none of " + paths.join(", ") + " exists; rigc.bunx alone is not executable; this package's own rigc is required here and no ancestor or PATH is searched (bun install puts it there)"
491
+ : `does not exist; this package's own rigc is required here and no other is looked for — not in a directory above ${resolve(root)}, not on PATH (\`bun install\` puts it there)`,
492
+ },
493
+ ]);
494
+ return '';
487
495
  }
488
496
 
489
497
  /**
490
- * Where the `rigc` binary is: `node_modules/.bin/rigc` in `from` or any
491
- * directory above it (a clone has it beside the package; an install has it in
492
- * the consumer's `node_modules/.bin`), then every directory on `PATH`. A miss
493
- * is refused naming every place looked.
498
+ * Find rigc beside from or its ancestors, then on PATH. Windows also looks for rigc.exe;
499
+ * selecting it does not replace it with a compiler entry or another package's launcher.
494
500
  */
495
- export function findRigc(from: string, pathVar: string): string {
501
+ export function findRigc(from: string, pathVar: string, platform: 'win32' | 'posix' = sep === '\\' ? 'win32' : 'posix'): string {
496
502
  const looked: string[] = [];
503
+ let directories = 0;
497
504
  let dir = resolve(from);
498
505
  for (;;) {
499
- const bin = join(dir, 'node_modules', '.bin', 'rigc');
500
- looked.push(bin);
501
- if (existsSync(bin)) return bin;
506
+ directories++;
507
+ for (const bin of rigcPaths(join(dir, 'node_modules', '.bin'), platform)) {
508
+ looked.push(bin);
509
+ if (existsSync(bin)) return bin;
510
+ }
502
511
  const up = dirname(dir);
503
512
  if (up === dir) break;
504
513
  dir = up;
505
514
  }
506
- for (const p of pathVar.split(delimiter).filter((s) => s !== '')) {
507
- const bin = join(p, 'rigc');
508
- if (existsSync(bin)) return bin;
515
+ const onPath: string[] = [];
516
+ for (const p of pathVar.split(delimiter).filter(s => s !== '')) {
517
+ for (const bin of rigcPaths(p, platform)) {
518
+ onPath.push(bin);
519
+ if (existsSync(bin)) return bin;
520
+ }
509
521
  }
510
522
  refuseIfAny([
511
523
  {
512
524
  code: 'CHECK_RIGC_PRESENT',
513
525
  object: 'the rig-c CLI `rigc`',
514
- detail: `found at none of ${looked.length} node_modules/.bin/rigc path(s) from ${resolve(from)} up (nearest ${looked[0]}) nor on PATH; rig-c is this package's dependency — \`bun install\` puts it at node_modules/.bin/rigc`,
526
+ detail: platform === 'win32'
527
+ ? 'found at none of ' + looked.join(', ') + ' nor PATH candidates [' + onPath.join(', ') + ']; executable shapes rigc, rigc.exe were looked for; rigc.bunx alone is not executable; bun install supplies this dependency'
528
+ : `found at none of ${directories} node_modules/.bin/rigc path(s) from ${resolve(from)} up (nearest ${looked[0]}) nor on PATH; rig-c is this package's dependency — \`bun install\` puts it at node_modules/.bin/rigc`,
515
529
  },
516
530
  ]);
517
531
  return '';
@@ -1208,6 +1222,8 @@ export function motionHeat(frames: readonly Raster[]): Raster {
1208
1222
  }
1209
1223
 
1210
1224
  export interface SeamFigures {
1225
+ /** Authored support size for a canonical union; absent for the unchanged auto reading. */
1226
+ denominator?: number;
1211
1227
  mean: number;
1212
1228
  over40: number;
1213
1229
  over80: number;
@@ -1443,6 +1459,8 @@ export function seamFigures(
1443
1459
  background: readonly [number, number, number, number],
1444
1460
  map: ScaleTranslate = rigToFrameMap(stage, composite.height, vp),
1445
1461
  scene = false,
1462
+ effect?: Uint8Array,
1463
+ sourceGrid = false,
1446
1464
  ): SeamFigures {
1447
1465
  const [W, H] = [composite.width, composite.height];
1448
1466
  const src = newFloatImage(W, H, 3);
@@ -1459,11 +1477,23 @@ export function seamFigures(
1459
1477
  const counted: number[] = [];
1460
1478
  const countedDiff: number[] = [];
1461
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' }]);
1462
1481
  // Issue #242: on a scene, the frame columns and rows whose composite sample reaches the painting's border.
1463
1482
  const onEdge = (i: number, t: number, s: number, size: number): boolean => {
1464
1483
  const k = Math.floor((i - t) / s);
1465
1484
  return k <= 0 || k + 1 >= size - 1;
1466
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
+ }
1467
1497
  const edgeCol = scene ? Array.from({ length: vp.pixelWidth }, (_, x) => onEdge(x, map.tx, map.sx, W)) : null;
1468
1498
  const edgeRow = scene ? Array.from({ length: vp.pixelHeight }, (_, y) => onEdge(y, map.ty, map.sy, H)) : null;
1469
1499
  for (let p = 0; p < n; p++) {
@@ -1473,11 +1503,16 @@ export function seamFigures(
1473
1503
  const d = Math.abs(w - frame.data[p * 4 + c]);
1474
1504
  if (d > m) m = d;
1475
1505
  }
1476
- 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) {
1477
1511
  borderPx++;
1478
1512
  if (m > SEAM_PX_LEVEL) borderOver40++;
1479
1513
  continue;
1480
1514
  }
1515
+ if (effect !== undefined && effect[p] === 0) continue;
1481
1516
  sum += m;
1482
1517
  if (m > SEAM_PX_LEVEL) {
1483
1518
  over40++;
@@ -1486,13 +1521,357 @@ export function seamFigures(
1486
1521
  }
1487
1522
  if (m > SEAM_PX_LEVEL_HIGH) over80++;
1488
1523
  }
1489
- 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 };
1490
1869
  }
1491
1870
 
1492
1871
  /**
1493
1872
  * Where `check --keep-stills` leaves the setup-pose still under `--out`
1494
1873
  * (issue #209): rigc's own render directory as `render` wrote it —
1495
- * `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
1496
1875
  * background) and the set directory beside it — so a reader compares against
1497
1876
  * the frame the bars read rather than rebuilding it. Removed at the start of
1498
1877
  * every run, so it is on disk only after a run that asked for it.
@@ -1543,6 +1922,8 @@ export interface SeamPairRow {
1543
1922
  frame_box: [number, number, number, number];
1544
1923
  rig_box: [number, number, number, number];
1545
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;
1546
1927
  picture: string;
1547
1928
  }
1548
1929
 
@@ -1598,7 +1979,7 @@ export function seamPairRows(seam: SeamFigures, parts: readonly PlacedAlpha[], r
1598
1979
  const db = parts[b].image.data;
1599
1980
  return da[oa] !== db[ob] || da[oa + 1] !== db[ob + 1] || da[oa + 2] !== db[ob + 2];
1600
1981
  };
1601
- 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 }
1602
1983
  const byPair = new Map<string, Acc>();
1603
1984
  seam.counted.forEach((p, idx) => {
1604
1985
  const fx = p % vp.pixelWidth;
@@ -1641,11 +2022,12 @@ export function seamPairRows(seam: SeamFigures, parts: readonly PlacedAlpha[], r
1641
2022
  const key = `${a},${b}`;
1642
2023
  let acc = byPair.get(key);
1643
2024
  if (acc === undefined) {
1644
- 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 };
1645
2026
  byPair.set(key, acc);
1646
2027
  }
1647
2028
  if (a >= 0 && parts[a].from === parts[b].from && read.some(([u, v]) => differ(a, b, u, v))) acc.differing++;
1648
2029
  acc.over40++;
2030
+ if (u0 < 0 || v0 < 0 || u0 >= W || v0 >= H) acc.outside++;
1649
2031
  acc.pixels.push(p);
1650
2032
  if (seam.countedDiff[idx] > SEAM_PX_LEVEL_HIGH) acc.over80++;
1651
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)];
@@ -1659,7 +2041,8 @@ export function seamPairRows(seam: SeamFigures, parts: readonly PlacedAlpha[], r
1659
2041
  const pair: [string, string] = acc.a < 0 ? [name(acc.b), SEAM_NO_ART] : [name(acc.a), name(acc.b)];
1660
2042
  const file = `${String(i + 1).padStart(Math.max(2, width), '0')}_${pair.map((n) => (n === SEAM_NO_ART ? 'no-art' : n)).join('_')}.png`;
1661
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 } } : {};
1662
- 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 };
1663
2046
  });
1664
2047
  }
1665
2048
 
@@ -1900,6 +2283,8 @@ export interface CheckFigures {
1900
2283
  * divided by its square ({@link seamRigPx}). Null with the other three.
1901
2284
  */
1902
2285
  seam_frame_scale: number | null;
2286
+ /** Canonical acceptance scope and separately labelled diagnostic/raw readings (#705). */
2287
+ seam_scope?: SeamScope;
1903
2288
  /**
1904
2289
  * Written only when `parts.json` declares a scene (issue #242): the frame pixels
1905
2290
  * on the painting's border that the seam figures above leave out, and how many
@@ -1965,6 +2350,7 @@ export interface SetCheckFigures {
1965
2350
  seam_px_over_40: number;
1966
2351
  seam_px_over_80: number;
1967
2352
  seam_frame_scale: number;
2353
+ seam_scope?: SeamScope;
1968
2354
  seam_border?: { frame_px_left_out: number; px_over_40_left_out: number };
1969
2355
  seam_pairs?: SeamPairRow[];
1970
2356
  RECOMPOSITE_HOLES: ReportedLine;
@@ -2140,13 +2526,44 @@ export const STRESS_LINE = 'STRESS_OFF_CHAIN';
2140
2526
  /** The bars `PASS` reads, in the order the summary counts them: the gate, the reference's two, then the judgement lines. */
2141
2527
  export const BARS = ['gate', 'loop', 'seam', ...JUDGEMENT_LINES] as const;
2142
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
+
2143
2559
  /**
2144
2560
  * The bars a character's own check may have failed and `compose --accept`
2145
2561
  * still take (issue #203): every bar of {@link BARS} but the gate, which is
2146
2562
  * rig-c's and never accepted, {@link FOLD_LINE} (issue #320) and
2147
- * {@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).
2148
2565
  */
2149
- 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];
2150
2567
 
2151
2568
  /**
2152
2569
  * The bars a `check.json`, as `check` writes it, says were not met, in
@@ -2173,6 +2590,8 @@ export function barsNotMet(fig: Readonly<Record<string, unknown>>): string[] {
2173
2590
  const l = fig[n];
2174
2591
  if (typeof l === 'object' && l !== null && (l as { status?: unknown }).status === 'FAIL') out.push(n);
2175
2592
  }
2593
+ const motion = fig[MOTION_SEAM_LINE];
2594
+ if (isRecord(motion) && isRecord(motion.roots) && motion.roots.status === 'FAIL') out.push(MOTION_SEAM_LINE);
2176
2595
  return out;
2177
2596
  }
2178
2597
 
@@ -2197,7 +2616,7 @@ export interface CheckReport {
2197
2616
  idle: { frames: number; fps: number; duration: number; lastIndex: number; loopAt: { x: number; y: number } } | null;
2198
2617
  /** The physics line ({@link loopPhysicsLine}); null when the rig declares no physics constraint or has no idle. */
2199
2618
  loopPhysics: string | null;
2200
- /** 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. */
2201
2620
  seamViewport: Viewport | null;
2202
2621
  /** Every bar in {@link BARS} that measured, and every one that did not with its reason. */
2203
2622
  bars: { measured: string[]; skipped: Array<{ bar: string; reason: string }> };
@@ -2237,7 +2656,7 @@ export function barsSummary(r: Pick<CheckReport, 'bars'>): string {
2237
2656
 
2238
2657
  /** The summary's warning clause: each warning line that read something, named, with the warnings they printed together; empty when none read. */
2239
2658
  export function warningsClause(r: Pick<CheckReport, 'motionSeam' | 'cloth'>): string {
2240
- 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 }])];
2241
2660
  if (read.length === 0) return '';
2242
2661
  return `; ${read.reduce((a, x) => a + x.n, 0)} warning(s) (${read.map((x) => x.name).join(', ')}, not a bar)`;
2243
2662
  }
@@ -3502,36 +3921,7 @@ export function sweepLine(
3502
3921
  // the seam over every animation (issue #493; the line is {@link MOTION_SEAM_LINE}'s)
3503
3922
  // ---------------------------------------------------------------------------
3504
3923
 
3505
- /**
3506
- * `SEAM_OVER_MOTION` (issue #493): every declared neighbour pair read in every
3507
- * animation `motion.json` holds, the idle included, by rig-c's seam reading
3508
- * (`rigc render --seam`, rig-c 2.60.0) — a **warning, never a bar**. The
3509
- * owner's ruling (2026-10-18): a seam opening in motion may be intentional, so
3510
- * the line names the pair, the animation, the frames and the cells, and moves
3511
- * neither the exit status nor `check: PASS`; the summary counts it apart from
3512
- * the bars.
3513
- *
3514
- * The pairs are the ones the inputs declare and nothing else: each limb's
3515
- * consecutive segments in `parts.json` (`config.limbs`, the upper and the
3516
- * segment below each joint) and, under `--requirements`, each `seam`
3517
- * requirement's part and neighbour. None declared, the line is a SKIP naming
3518
- * why, never a pass, and `check.json` carries no key for it.
3519
- *
3520
- * **The floor** ({@link openingOverFloor}): a frame's gap or ghost is reported
3521
- * when it holds more cells than its box is long — when it is thicker than one
3522
- * cell. rigc counts a cell drawn when the renderer paints its centre at half
3523
- * opacity or more, so a boundary that moves by less than a cell flips the
3524
- * cells along it in or out: a line of cells one deep, scattered or joined,
3525
- * holds at most as many cells as its box's longer side. A hole of any area
3526
- * holds more. The rule types no number; it is read off rigc's own cell and
3527
- * box, and measured, not chosen: on `examples/wind`'s idle rigc names 43
3528
- * openings over its six limb pairs (28 and 15 frames of the two elbows, 1 to
3529
- * 5 cells, boxes up to 17 cells long) and every one is one cell thick; on
3530
- * rig-c's `gallery/walk` its 13 joint cracks of 1 to 3 cells are too; the
3531
- * ghost rig-c's own reading names on a skirt swung clear of a leg (1564 cells
3532
- * in a box 92 long) is far over it.
3533
- */
3534
- export const MOTION_SEAM_LINE = 'SEAM_OVER_MOTION';
3924
+
3535
3925
 
3536
3926
  /** The seam reading's scratch build and renders, under `--out`; removed before the stage returns. */
3537
3927
  const MOTION_SEAM_SCRATCH = '_seam_motion';
@@ -3553,6 +3943,31 @@ export interface MotionSeamPair {
3553
3943
  declared: string[];
3554
3944
  /** Why the pair is not read: a slot `rig.json` does not have. */
3555
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[];
3556
3971
  }
3557
3972
 
3558
3973
  /** One pair in one animation, as the floor reads rigc's file. */
@@ -3566,37 +3981,51 @@ export interface MotionSeamRow {
3566
3981
  banded: number;
3567
3982
  /** The frames over the floor, ascending: the warning's frames. */
3568
3983
  opens: number[];
3569
- /** 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. */
3570
3985
  px: number[];
3571
- /** 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. */
3572
3987
  max_px: number;
3573
3988
  /** The frames rigc names open whose every opening is one cell thick: under the floor, not reported. */
3574
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[];
3575
3996
  }
3576
3997
 
3577
- /** 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. */
3578
3999
  export interface MotionSeamLine {
3579
- status: 'WARN' | 'CLEAR' | 'SKIP';
4000
+ status: 'WARN' | 'CLEAR' | 'SKIP' | 'FAIL';
3580
4001
  reason?: string;
3581
4002
  fps: number;
3582
4003
  floor: string;
3583
4004
  pairs: MotionSeamPair[];
3584
4005
  animations: string[];
3585
- /** Rows with a frame over the floor: the WARN lines. */
4006
+ /** Existing non-root rows with a frame over the floor: the WARN lines. */
3586
4007
  warnings: number;
3587
4008
  rows: MotionSeamRow[];
3588
4009
  /** Physics-only reference worlds (issue #591); do not participate in warnings or bars. */
3589
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[] };
3590
4013
  }
3591
4014
 
3592
4015
  /**
3593
4016
  * The neighbour pairs the inputs declare, in their order: each limb's
3594
4017
  * consecutive segments (`parts.json`'s limb records, by segment), then each
3595
- * `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
3596
4019
  * order, is one pair with both declarations.
3597
4020
  */
3598
- 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 {
3599
4027
  const out: MotionSeamPair[] = [];
4028
+ const unmeasuredRoots: MotionUnmeasuredRoot[] = [];
3600
4029
  const add = (a: string, b: string, declared: string): void => {
3601
4030
  const hit = out.find((p) => (p.a === a && p.b === b) || (p.a === b && p.b === a));
3602
4031
  if (hit !== undefined) hit.declared.push(declared);
@@ -3612,6 +4041,142 @@ export function motionSeamPairs(parts: PartsFile, seams: ReadonlyArray<{ name: s
3612
4041
  }
3613
4042
  }
3614
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);
3615
4180
  return out;
3616
4181
  }
3617
4182
 
@@ -3644,13 +4209,203 @@ export interface MotionSeamPlant {
3644
4209
  }
3645
4210
 
3646
4211
 
3647
- /** 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. */
3648
4213
  export interface MotionSeamHit {
3649
4214
  index: number;
3650
4215
  px: number;
3651
4216
  cell: number;
3652
4217
  box: [number, number, number, number];
3653
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
+ }
3654
4409
  export interface MotionSeamWorldKind {
3655
4410
  max_px: number;
3656
4411
  worst: MotionSeamHit | null;
@@ -3754,7 +4509,33 @@ type SeamHitRead = MotionSeamHit;
3754
4509
  * file that is missing, a file that is not the animation's or not at the rate
3755
4510
  * asked, a pair out of the flag's order, and a field of the wrong shape.
3756
4511
  */
3757
- 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[] {
3758
4539
  const problems: Problem[] = [];
3759
4540
  const bad = (object: string, detail: string): void => {
3760
4541
  problems.push({ code: 'FRAMES_SIDECAR', object, detail });
@@ -3766,7 +4547,8 @@ export function readMotionSeams(dir: string, animations: readonly string[], fps:
3766
4547
  const hitOf = (h: unknown): SeamHitRead | null =>
3767
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;
3768
4549
  for (const animation of animations) {
3769
- const set = sets.find((x) => x.animation === animation);
4550
+ const rawAnimation = setup ? null : animation;
4551
+ const set = sets.find((x) => x.animation === rawAnimation);
3770
4552
  if (set === undefined || typeof set.dir !== 'string') {
3771
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`);
3772
4554
  continue;
@@ -3775,7 +4557,7 @@ export function readMotionSeams(dir: string, animations: readonly string[], fps:
3775
4557
  const file = readJson(path, problems);
3776
4558
  if (file === null) continue;
3777
4559
  if (file.spec !== SEAM_READING_SPEC) bad(path, `spec is ${JSON.stringify(file.spec)}; "${SEAM_READING_SPEC}" is required`);
3778
- 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`);
3779
4561
  if (file.fps !== fps) bad(path, `fps is ${JSON.stringify(file.fps)}; ${fps}, the rate asked for, is required`);
3780
4562
  const read = Array.isArray(file.pairs) ? file.pairs : [];
3781
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`);
@@ -3791,6 +4573,11 @@ export function readMotionSeams(dir: string, animations: readonly string[], fps:
3791
4573
  return;
3792
4574
  }
3793
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>();
3794
4581
  const kinds: Record<'gap' | 'ghost', MotionSeamWorldKind> = { gap: { max_px: 0, worst: null }, ghost: { max_px: 0, worst: null } };
3795
4582
  for (const kind of ['gap', 'ghost'] as const) {
3796
4583
  const k = p[kind];
@@ -3800,9 +4587,23 @@ export function readMotionSeams(dir: string, animations: readonly string[], fps:
3800
4587
  return;
3801
4588
  }
3802
4589
  const hits = frames as SeamHitRead[];
4590
+ if (kind === 'gap') rootGapFrames = hits.map(h => h.index);
4591
+ else ghostFrames = hits.length;
3803
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);
3804
4593
  kinds[kind] = { max_px: worst?.px ?? 0, worst };
3805
- 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
+ }
3806
4607
  }
3807
4608
  worldRows?.push({ pair: want.pair, animation, status: p.status, drawn: p.drawn, banded: p.banded, gap: kinds.gap, ghost: kinds.ghost });
3808
4609
  const opens = [...over.keys()].sort((x, y) => x - y);
@@ -3815,7 +4616,10 @@ export function readMotionSeams(dir: string, animations: readonly string[], fps:
3815
4616
  opens,
3816
4617
  px: opens.map((f) => over.get(f) ?? 0),
3817
4618
  max_px: opens.reduce((m, f) => Math.max(m, over.get(f) ?? 0), 0),
3818
- 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 } }),
3819
4623
  });
3820
4624
  });
3821
4625
  }
@@ -3823,19 +4627,44 @@ export function readMotionSeams(dir: string, animations: readonly string[], fps:
3823
4627
  return rows;
3824
4628
  }
3825
4629
 
3826
- /** 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. */
3827
- export function motionSeamLine(pairs: MotionSeamPair[], animations: string[], fps: number, rows: MotionSeamRow[], reason?: string): MotionSeamLine {
3828
- 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
+ };
3829
4657
  const read = rows.some((r) => r.status === 'read');
3830
4658
  const skipWhy =
3831
4659
  reason ??
4660
+ (pairs.length === 0 && unmeasured.length > 0 ? rootGate?.reason : undefined) ??
3832
4661
  (read
3833
4662
  ? undefined
3834
4663
  : pairs.every((p) => p.unread !== undefined)
3835
4664
  ? `no declared pair is read: ${pairs.map((p) => `"${p.pair}" ${String(p.unread)}`).join('; ')}`
3836
4665
  : `rigc read no band on any frame of any declared pair in any animation — nothing measured, which is not a seam that held`);
3837
4666
  return {
3838
- status: skipWhy !== undefined ? 'SKIP' : warnings > 0 ? 'WARN' : 'CLEAR',
4667
+ status: rootGate?.status === 'FAIL' ? 'FAIL' : skipWhy !== undefined ? 'SKIP' : warnings > 0 ? 'WARN' : 'CLEAR',
3839
4668
  ...(skipWhy === undefined ? {} : { reason: skipWhy }),
3840
4669
  fps,
3841
4670
  floor: MOTION_SEAM_FLOOR,
@@ -3843,6 +4672,7 @@ export function motionSeamLine(pairs: MotionSeamPair[], animations: string[], fp
3843
4672
  animations,
3844
4673
  warnings,
3845
4674
  rows,
4675
+ ...(rootGate === undefined ? {} : { roots: rootGate }),
3846
4676
  };
3847
4677
  }
3848
4678
 
@@ -4181,7 +5011,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4181
5011
  const keptDir = join(out, STILL_DIR);
4182
5012
  const foldDir = join(out, FOLD_SCRATCH);
4183
5013
  const seamMotionDir = join(out, MOTION_SEAM_SCRATCH);
4184
- 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 });
4185
5015
  const written: string[] = [];
4186
5016
  const write = (name: string, data: string): void => {
4187
5017
  writeFileSync(join(out, name), data);
@@ -4523,13 +5353,50 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4523
5353
  }
4524
5354
  }
4525
5355
 
4526
- // 3e. every declared neighbour pair read in every animation by rigc's seam reading (issue #493): a warning, never a
4527
- // 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.
4528
5358
  let motionSeam: MotionSeamLine;
5359
+ const motionRootProblems: Problem[] = [];
4529
5360
  {
4530
5361
  const fps = IDLE_FPS;
4531
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 }] : []));
4532
- 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;
4533
5400
  const slotNames = new Set((Array.isArray(inp.rig.slots) ? inp.rig.slots : []).filter(isRecord).map((sl) => String(sl.name)));
4534
5401
  for (const p of pairs) {
4535
5402
  const missing = [p.a, p.b].filter((n) => !slotNames.has(n));
@@ -4537,19 +5404,22 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4537
5404
  }
4538
5405
  const read = pairs.filter((p) => p.unread === undefined);
4539
5406
  if (inp.parts === null) motionSeam = motionSeamLine([], animationNames, fps, [], inp.noParts ?? 'no parts.json');
4540
- 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');
4541
- else if (animationNames.length === 0) motionSeam = motionSeamLine(pairs, [], fps, [], 'motion.json holds no animation to read the declared pairs in');
4542
- 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);
4543
5412
  else {
4544
5413
  rmSync(seamMotionDir, { recursive: true, force: true });
4545
5414
  {
4546
5415
  const list = read.map((p) => `${p.a}:${p.b}`).join(',');
4547
5416
  const activeDest = stripped === null ? seamMotionDir : join(seamMotionDir, env === null ? 'default' : 'active');
4548
5417
  const renderedWorlds = new Set<'default' | 'still'>();
4549
- 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]);
4550
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:'))));
4551
5421
  const activeWorldRows: MotionSeamWorldRow[] = [];
4552
- 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);
4553
5423
  if (stripped !== null) {
4554
5424
  const response = environmentResponse(readFileSync(join(buildDir, 'skeleton.json'), 'utf8'));
4555
5425
  motionSeam.worlds = motionSeamWorlds(true, response.wind.length > 0, world => {
@@ -4600,6 +5470,8 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4600
5470
  // 4. the setup pose as a one-key throwaway animation — the seam reads it against the parts, the source line against
4601
5471
  // the painting — and, beside it, the same pose with the eyes shut
4602
5472
  let seam: SeamFigures | null = null;
5473
+ let seamScope: SeamScope | undefined;
5474
+ const seamStacks = new SeamStacks();
4603
5475
  let seamPairs: SeamPairRow[] | null = null;
4604
5476
  let seamViewport: Viewport | null = null;
4605
5477
  let blink: JudgementLine = skip(lacking);
@@ -4635,48 +5507,88 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4635
5507
  if (sr.status !== 0) refuseIfAny(rigcFailed('render (the setup-pose still)', sr, sr.out.split('\n').filter((l) => l.includes('FAIL'))));
4636
5508
  const stillSet = readFrameSet(join(stillDir, 'render'));
4637
5509
  seamViewport = stillSet.viewport;
4638
- 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 });
4639
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 });
4640
5546
  const composite = flatComposite(inp.parts, inp.partsDir, stillSet.background);
4641
- seam = seamFigures(composite, stillSet.frames[0].image, inp.stage, stillSet.viewport, stillSet.background, undefined, inp.parts.scene !== undefined);
4642
- if (seamPairsAsked || seamFails(round3(seam.mean), seam.over40, round6(stillSet.viewport.scale))) {
4643
- 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`)) }));
4644
- 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;
4645
5555
  mkdirSync(seamDir, { recursive: true });
4646
- 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));
4647
5557
  seamPairs = split.map((x) => x.row);
4648
5558
  }
4649
5559
  if (set !== undefined || allSets) {
4650
- const alts = allSets ? (inp.parts.alternates ?? []) : (inp.parts.alternates ?? []).filter((a) => a.name === set);
4651
- const setStillAnimations: Record<string, unknown> = { still: animations.still };
4652
- const setStillBase = { ...withoutSliders(inp.rig, setStillAnimations), images };
4653
- const setsJsonPath = join(inp.rigDir, SETS_FILE);
4654
- const setsJsonRaw = existsSync(setsJsonPath) ? readJson(setsJsonPath, []) : null;
4655
- const setsMap = setsJsonRaw !== null && isRecord(setsJsonRaw.sets) ? setsJsonRaw.sets : null;
4656
- for (const alt of alts) {
4657
- const setEntry: Record<string, unknown> | null =
4658
- setsMap !== null && isRecord(setsMap[alt.name]) ? (setsMap[alt.name] as Record<string, unknown>) : null;
4659
- const setDrawn: Record<string, number> | undefined =
4660
- setEntry !== null && isRecord(setEntry.drawn)
4661
- ? Object.fromEntries(
4662
- Object.entries(setEntry.drawn).filter((entry): entry is [string, number] => typeof entry[1] === 'number' && Number.isFinite(entry[1])),
4663
- )
4664
- : alt.drawn;
4665
- const setDir = join(stillDir, `set_${alt.name}`);
4666
- mkdirSync(setDir, { recursive: true });
4667
- writeFileSync(join(setDir, 'rig.json'), JSON.stringify(stillRigForSet(setStillBase, alt, setDrawn)));
4668
- writeFileSync(join(setDir, 'motion.json'), JSON.stringify({ ...inp.motion, animations: setStillAnimations }));
4669
- const asb = rigc(['build', '--rig', join(setDir, 'rig.json'), '--motion', join(setDir, 'motion.json'), '--out', join(setDir, 'build'), '--profile', 'spine']);
4670
- 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) {
4671
5562
  const asr = rigc(['render', '--candidate', join(setDir, 'build'), '--animation', 'still', '--fps', String(STILL_FPS), '--max', String(maxSide), '--out', join(setDir, 'render')]);
4672
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'))));
4673
5564
  const altStillSet = readFrameSet(join(setDir, 'render'));
4674
- 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 });
4675
5566
  const rigSlotOrder = (Array.isArray(inp.rig.slots) ? inp.rig.slots : []).filter(isRecord).map((sl) => String(sl.name));
4676
5567
  const altComposite = flatCompositeForSet(inp.parts, alt, inp.partsDir, altStillSet.background, rigSlotOrder);
4677
- 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
+ };
4678
5590
  const altMean = round3(altSeam.mean);
4679
- const altScale = round6(altStillSet.viewport.scale);
5591
+ const altScale = 1;
4680
5592
  const altFailed = seamFails(altMean, altSeam.over40, altScale);
4681
5593
  if (altFailed) {
4682
5594
  const hint = armSplitSetHint(inp.parts, alt);
@@ -4684,22 +5596,22 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4684
5596
  }
4685
5597
  let altPairs: SeamPairRow[] | null = null;
4686
5598
  if (seamPairsAsked || altFailed) {
4687
- 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`)) }));
4688
- const split = seamPairRows(altSeam, placed, inp.parts.rig_size, altStillSet.viewport);
5599
+ const split = seamPairRows(altSeam, altPlaced, inp.parts.rig_size, altCanonical.viewport);
4689
5600
  const altSeamDir = join(seamDir, alt.name);
4690
5601
  mkdirSync(altSeamDir, { recursive: true });
4691
5602
  for (const { row, pixels } of split) {
4692
5603
  row.picture = `${SEAM_DIR}/${alt.name}/${basename(row.picture)}`;
4693
- 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));
4694
5605
  }
4695
5606
  altPairs = split.map((x) => x.row);
4696
5607
  }
4697
5608
  setsFigures[alt.name] = {
4698
- render_px: `${altStillSet.viewport.pixelWidth}x${altStillSet.viewport.pixelHeight}`,
5609
+ render_px: `${altCanonical.viewport.pixelWidth}x${altCanonical.viewport.pixelHeight}`,
4699
5610
  seam_mean: altMean,
4700
5611
  seam_px_over_40: altSeam.over40,
4701
5612
  seam_px_over_80: altSeam.over80,
4702
5613
  seam_frame_scale: altScale,
5614
+ seam_scope: altScope,
4703
5615
  ...(altSeam.border === null ? {} : { seam_border: { frame_px_left_out: altSeam.border.framePx, px_over_40_left_out: altSeam.border.over40 } }),
4704
5616
  ...(altPairs === null ? {} : { seam_pairs: altPairs }),
4705
5617
  RECOMPOSITE_HOLES: altHolesLine(inp.parts, alt),
@@ -4762,6 +5674,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4762
5674
  seam_px_over_40: seam === null ? null : seam.over40,
4763
5675
  seam_px_over_80: seam === null ? null : seam.over80,
4764
5676
  seam_frame_scale: seam === null || seamViewport === null ? null : round6(seamViewport.scale),
5677
+ ...(seamScope === undefined ? {} : { seam_scope: seamScope }),
4765
5678
  ...(seam === null || seam.border === null ? {} : { seam_border: { frame_px_left_out: seam.border.framePx, px_over_40_left_out: seam.border.over40 } }),
4766
5679
  ...(seamPairs === null ? {} : { seam_pairs: seamPairs }),
4767
5680
  BREATH_VISIBLE: breath,
@@ -4775,7 +5688,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4775
5688
  ...(stress === null ? {} : { [STRESS_LINE]: stress }),
4776
5689
  ...(limbs === null ? {} : { [LIMB_LINE]: limbs }),
4777
5690
  ...(sweep === null ? {} : { [SWEEP_LINE]: sweep }),
4778
- ...(motionSeam.pairs.length === 0 ? {} : { [MOTION_SEAM_LINE]: motionSeam }),
5691
+ ...(motionSeam.pairs.length === 0 && motionSeam.roots === undefined ? {} : { [MOTION_SEAM_LINE]: motionSeam }),
4779
5692
  ...(stripped === null || idle === null ? {} : { [CLOTH_LINE]: cloth }),
4780
5693
  RECOMPOSITE_HOLES: inp.parts === null ? { status: 'SKIP', reason: inp.noParts ?? '' } : holesLine(inp.parts),
4781
5694
  ...(sourceRead === null ? {} : { [SOURCE_LINE]: sourceRead }),
@@ -4799,7 +5712,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4799
5712
  const worst = seamPairs === null || seamPairs.length === 0 ? null : seamPairs[0];
4800
5713
  barProblems.push({
4801
5714
  code: 'CHECK_SEAM_WITHIN_BAR',
4802
- 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)',
4803
5716
  detail:
4804
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` +
4805
5718
  (worst === null
@@ -4812,7 +5725,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4812
5725
  const worst = setFig.seam_pairs === undefined || setFig.seam_pairs.length === 0 ? null : setFig.seam_pairs[0];
4813
5726
  barProblems.push({
4814
5727
  code: 'CHECK_SEAM_WITHIN_BAR',
4815
- 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)`,
4816
5729
  detail:
4817
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` +
4818
5731
  (worst === null
@@ -4825,7 +5738,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4825
5738
  const rank = (q: Problem): number => JUDGEMENT_LINES.findIndex((n) => q.code === `CHECK_${n}`);
4826
5739
  problems.sort((a, b) => rank(a) - rank(b));
4827
5740
  problems.unshift(...barProblems);
4828
- problems.push(...foldProblems, ...levelProblems, ...stressProblems, ...limbProblems, ...sweepProblems, ...reqProblems);
5741
+ problems.push(...foldProblems, ...levelProblems, ...stressProblems, ...limbProblems, ...sweepProblems, ...motionRootProblems, ...reqProblems);
4829
5742
  figures.PASS = problems.length === 0;
4830
5743
  const publishCheck = (): void => write('check.json', `${JSON.stringify(figures, null, 1)}\n`);
4831
5744
  if (motionSeam.worlds === undefined) publishCheck();
@@ -4851,6 +5764,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4851
5764
  if (limbs !== null) tally(LIMB_LINE, null);
4852
5765
  // Issue #360: the range bar where it is written; a joint it cannot read fails, so it always measures.
4853
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);
4854
5768
  return {
4855
5769
  figures,
4856
5770
  gateHtml,