@rig-c/parts 1.66.0 → 1.68.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
@@ -85,6 +85,8 @@ import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep
85
85
  import { measureRecomposite, type RecompositeFigures, recompositeRecord, scenePhrase, sourceInRig } from './assemble.ts';
86
86
  import { type BoneTransform, computeExactFrameTransforms, cropToSpineY, normaliseDegrees, toBoneLocal } from './coords.ts';
87
87
  import { capBox, inDisc } from './limbs.ts';
88
+ import { motionSeamProblems } from './motionseams.ts';
89
+ import { seamPoseFrame, seamStaticRange, type SeamPoseAtWorst } from './motionseampose.ts';
88
90
  import { coreCompileGuideLine, PartsError, type Problem, refuseIfAny } from './errors.ts';
89
91
  import { framesInside, IDLE_FPS, TIME_SLACK } from './motion.ts';
90
92
  import {
@@ -4305,6 +4307,8 @@ export interface MotionSeamRow {
4305
4307
  worst?: MotionSeamHit & { kind: 'gap' | 'ghost' | 'gapOpen' | 'underGhost' | 'gapOpen+underGhost' };
4306
4308
  /** Exact stock partitions and the resolved UNDER owner, retained even below the floor. */
4307
4309
  cells?: MotionRootCells[];
4310
+ /** Same-render posed evidence on every played non-root WARN. */
4311
+ pose_at_worst?: SeamPoseAtWorst;
4308
4312
  }
4309
4313
 
4310
4314
  /** Existing pairs warn; new body roots alone can FAIL. Unavailable readings are named SKIP, never measured zero. */
@@ -4353,6 +4357,10 @@ export function motionSeamSelection(parts: PartsFile, seams: ReadonlyArray<{ nam
4353
4357
  }
4354
4358
  }
4355
4359
  for (const r of seams) add(r.part, r.neighbour, `requirement "${r.name}" (seam)`);
4360
+ if (parts.motion_seams !== undefined) {
4361
+ refuseIfAny(motionSeamProblems(parts.motion_seams, new Set(parts.parts.map(p => p.name)), 'parts.json motion_seams', 'CHECK_MOTION_SEAM_DECLARATION'));
4362
+ parts.motion_seams.forEach((r, i) => add(r.part, r.neighbour, `motion_seams[${i}]`));
4363
+ }
4356
4364
  const candidates = rig === undefined ? [] : motionRootCandidates(parts, rig);
4357
4365
  const selected: MotionSeamPair[] = [];
4358
4366
  if (candidates.length > 0) {
@@ -4750,6 +4758,7 @@ function readSeamRows(dir: string, animations: readonly string[], fps: number, p
4750
4758
  }
4751
4759
  const over = new Map<number, number>();
4752
4760
  let rootWorst: MotionSeamRow['worst'];
4761
+ let warnWorst: MotionSeamRow['worst'];
4753
4762
  const rootFrames = new Set<number>();
4754
4763
  const cells: MotionRootCells[] = [];
4755
4764
  const kinds: Record<'gap' | 'ghost', MotionSeamWorldKind> = { gap: { max_px: 0, worst: null }, ghost: { max_px: 0, worst: null } };
@@ -4767,6 +4776,7 @@ function readSeamRows(dir: string, animations: readonly string[], fps: number, p
4767
4776
  // Existing internal pairs retain their original maximum-kind warning and floor.
4768
4777
  for (const h of hits) if (want.root === undefined && (plant.noFloor === true || openingOverFloor(h))) {
4769
4778
  over.set(h.index, Math.max(over.get(h.index) ?? 0, h.px));
4779
+ if (warnWorst === undefined || h.px > warnWorst.px || (h.px === warnWorst.px && h.index < warnWorst.index)) warnWorst = { ...h, kind };
4770
4780
  }
4771
4781
  }
4772
4782
  if (want.root !== undefined && !setup) {
@@ -4842,6 +4852,7 @@ function readSeamRows(dir: string, animations: readonly string[], fps: number, p
4842
4852
  max_px: opens.reduce((m, f) => Math.max(m, over.get(f) ?? 0), 0),
4843
4853
  under_floor: (want.root === undefined ? p.opens : [...rootFrames].filter(f => cells.some(c => c.index === f && c.counted > 0))).filter((f) => !over.has(f)),
4844
4854
  ...(rootWorst === undefined ? {} : { worst: rootWorst }),
4855
+ ...(warnWorst === undefined || setup ? {} : { worst: warnWorst }),
4845
4856
  ...(want.root === undefined ? {} : { cells }),
4846
4857
  });
4847
4858
  });
@@ -4898,9 +4909,99 @@ export function motionSeamLine(pairs: MotionSeamPair[], animations: string[], fp
4898
4909
  };
4899
4910
  }
4900
4911
 
4912
+ /** Enrich active non-root WARNs only, using the SAME seam render and raw hit time. */
4913
+ export function enrichMotionSeamPoses(dir: string, rig: Record<string, unknown>, parts: PartsFile | null, pairs: readonly MotionSeamPair[], rows: MotionSeamRow[]): void {
4914
+ const wanted = rows.filter(row => row.opens.length > 0 && pairs.some(pair => pair.pair === row.pair && pair.root === undefined));
4915
+ if (wanted.length === 0) return;
4916
+ const problems: Problem[] = [];
4917
+ const sidecar = readJson(join(dir, 'frames.json'), problems);
4918
+ refuseIfAny(problems);
4919
+ const sets = Array.isArray(sidecar?.sets) ? sidecar.sets.filter(isRecord) : [];
4920
+ // Slots/weights already bind drawn stop links; resolve their ancestry in the same graph rig-c compiles.
4921
+ const expanded = Array.isArray(rig.stops) ? (expandStops(rig as unknown as RigcRigSpec, 'rig.json') as unknown as Record<string, unknown>) : rig;
4922
+ const bones = (Array.isArray(expanded.bones) ? expanded.bones : []).filter(isRecord);
4923
+ const skin = isRecord(rig.skins) && isRecord(rig.skins.default) ? rig.skins.default : {};
4924
+ const cache = new Map<string, { geometry: Record<string, unknown>; seam: Record<string, unknown>; cohort: FrameSet; parsed: IdleGeometry }>();
4925
+ for (const row of wanted) {
4926
+ const h = row.worst;
4927
+ if (h === undefined) geometryProblem(row.pair, 'above-floor WARN has no worst raw hit');
4928
+ const matches = sets.filter(set => set.animation === row.animation);
4929
+ const set = matches[0];
4930
+ if (matches.length !== 1 || typeof set.dir !== 'string' || isAbsolute(set.dir) || set.dir.split(/[\\/]/).includes('..')) geometryProblem(row.animation, 'one local same-animation frame set required for WARN pose');
4931
+ let data = cache.get(row.animation);
4932
+ if (data === undefined) {
4933
+ const geometry = readJson(join(dir, String(set.dir), GEOMETRY_FILE), problems);
4934
+ const seam = readJson(join(dir, String(set.dir), SEAM_READING_FILE), problems);
4935
+ refuseIfAny(problems);
4936
+ if (geometry === null || seam === null || !Array.isArray(geometry.frames) || geometry.frames.length !== set.written) geometryProblem(row.animation, 'stock seam geometry frame count differs from frames.json');
4937
+ const cohort = readFrameSet(join(dir, String(set.dir)));
4938
+ const parsed = readGeometry(join(dir, String(set.dir), GEOMETRY_FILE), cohort.written);
4939
+ if (parsed === null) geometryProblem(row.animation, 'same-render geometry is missing');
4940
+ data = { geometry, seam, cohort, parsed };
4941
+ cache.set(row.animation, data);
4942
+ }
4943
+ const rawPairs = Array.isArray(data.seam.pairs) ? data.seam.pairs.filter(isRecord) : [];
4944
+ const pair = pairs.find(p => p.pair === row.pair);
4945
+ const raw = rawPairs.find(p => p.a === pair?.a && p.b === pair?.b);
4946
+ const kind = raw?.[h.kind];
4947
+ const hits = isRecord(kind) && Array.isArray(kind.frames) ? kind.frames.filter(isRecord) : [];
4948
+ const hitsAt = hits.filter(hit => hit.index === h.index && hit.px === h.px && hit.cell === h.cell && JSON.stringify(hit.box) === JSON.stringify(h.box));
4949
+ const time = hitsAt[0]?.time;
4950
+ if (hitsAt.length !== 1 || typeof time !== 'number' || !Number.isFinite(time)) geometryProblem(row.pair, 'one matching worst raw hit with actual finite time required');
4951
+ const rawFrames = (data.geometry.frames as unknown[]).filter(isRecord);
4952
+ const frame = rawFrames.find(f => f.index === h.index);
4953
+ const shown = Array.isArray(frame?.attachments) ? frame.attachments.filter(isRecord) : [];
4954
+ const carriers = new Set<string>();
4955
+ for (const name of [pair?.a, pair?.b]) {
4956
+ const active = shown.filter(a => a.slot === name);
4957
+ const onValue = typeof name === 'string' ? skin[name] : undefined;
4958
+ const on = isRecord(onValue) ? onValue : {};
4959
+ const attachment = active.length === 1 && typeof active[0].attachment === 'string' ? on[active[0].attachment] : undefined;
4960
+ if (!isRecord(attachment)) geometryProblem(row.pair, `slot "${String(name)}": active default-skin drawing unavailable at worst frame`);
4961
+ if (Array.isArray(attachment.weights)) {
4962
+ const weights = attachment.weights.flatMap(v => Array.isArray(v) ? v.filter(isRecord) : []);
4963
+ for (const w of weights) if (typeof w.bone === 'string' && typeof w.weight === 'number' && w.weight > 0) carriers.add(w.bone);
4964
+ } else {
4965
+ const slot = (Array.isArray(rig.slots) ? rig.slots : []).filter(isRecord).find(sl => sl.name === name);
4966
+ if (typeof slot?.bone !== 'string') geometryProblem(row.pair, `slot "${String(name)}": no declared bone`);
4967
+ carriers.add(slot.bone);
4968
+ }
4969
+ }
4970
+ if (carriers.size === 0) geometryProblem(row.pair, 'no positive-weight or rigid carrier at worst frame');
4971
+ const ancestry = new Set<string>();
4972
+ for (const carrier of carriers) {
4973
+ const seen = new Set<string>();
4974
+ let next: string | undefined = carrier;
4975
+ while (next !== undefined) {
4976
+ if (seen.has(next)) geometryProblem(row.pair, `cycle in carrier path at "${next}"`);
4977
+ seen.add(next);
4978
+ ancestry.add(next);
4979
+ const named = bones.filter(b => b.name === next);
4980
+ if (named.length !== 1) geometryProblem(row.pair, `carrier "${next}": one declared bone required`);
4981
+ next = typeof named[0].parent === 'string' ? named[0].parent : undefined;
4982
+ }
4983
+ }
4984
+ const joints = bones.filter(b => typeof b.name === 'string' && ancestry.has(b.name)).map(b => {
4985
+ const ranges = parts?.parts.flatMap(p => {
4986
+ const limb = p.limb;
4987
+ return limb !== undefined && limb.bone === b.name && limb.range !== undefined ? [limb.range] : [];
4988
+ }) ?? [];
4989
+ return { bone: String(b.name), parent: typeof b.parent === 'string' ? b.parent : null,
4990
+ inherit: typeof b.inherit === 'string' ? b.inherit : 'normal', ...seamStaticRange(ranges) };
4991
+ });
4992
+ for (const joint of joints) {
4993
+ const track = boneTrackOf(data.parsed, join(dir, String(set.dir), GEOMETRY_FILE), data.cohort, joint.bone);
4994
+ if (typeof track === 'string') geometryProblem(row.pair, track);
4995
+ }
4996
+ row.pose_at_worst = seamPoseFrame(data.geometry, row.animation, h.index, time, data.cohort, joints);
4997
+ }
4998
+ }
4999
+
4901
5000
  /** One warning as the console prints it (issue #493's form, the floor's clause after it). */
4902
5001
  export function motionSeamWarnText(r: MotionSeamRow): string {
4903
- return `WARN seam "${r.pair}" opens on ${r.opens.length} frame(s) ${frameRuns(r.opens)} max ${r.max_px} px in "${r.animation}" — over the one-cell floor${r.under_floor.length === 0 ? '' : `, ${r.under_floor.length} more frame(s) one cell thick not reported`}`;
5002
+ const pose = r.pose_at_worst;
5003
+ const evidence = pose === undefined ? '' : `; worst frame ${pose.index} (t = ${pose.time}s), ${pose.joints.map(j => `bone "${j.bone}" parent ${JSON.stringify(j.parent)} world ${j.world_x_axis_degrees === null ? 'unavailable' : round3(j.world_x_axis_degrees) + 'deg'}; relative setup axis ${j.parent_relative_setup_axis_delta_degrees_mod360 === null ? 'unavailable' : round3(j.parent_relative_setup_axis_delta_degrees_mod360) + 'deg modulo360'}, static range ${JSON.stringify(j.static_range)} (${j.comparison}${j.reason === undefined ? '' : ': ' + j.reason})`).join(' | ')}`;
5004
+ return `WARN seam "${r.pair}" opens on ${r.opens.length} frame(s) ${frameRuns(r.opens)} max ${r.max_px} px in "${r.animation}" — over the one-cell floor${r.under_floor.length === 0 ? '' : `, ${r.under_floor.length} more frame(s) one cell thick not reported`}${evidence}`;
4904
5005
  }
4905
5006
 
4906
5007
  // ---------------------------------------------------------------------------
@@ -6136,10 +6237,11 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
6136
6237
  const activeDest = stripped === null ? seamMotionDir : join(seamMotionDir, env === null ? 'default' : 'active');
6137
6238
  const renderedWorlds = new Set<'default' | 'still'>();
6138
6239
  const hasRoots = read.some(p => p.root !== undefined);
6139
- const r = measured(['render', '--candidate', buildDir, '--seam', list, '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), ...(hasRoots ? ['--geometry'] : []), '--out', activeDest]);
6240
+ const r = measured(['render', '--candidate', buildDir, '--seam', list, '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--geometry', '--out', activeDest]);
6140
6241
  if (r.status !== 0) refuseIfAny(rigcFailed(`render --seam ${list} --fps ${fps}`, r, r.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
6141
6242
  const activeWorldRows: MotionSeamWorldRow[] = [];
6142
6243
  motionSeam = motionSeamLine(pairs, animationNames, fps, readMotionSeams(activeDest, animationNames, fps, read, {}, stripped !== null && env === null ? activeWorldRows : undefined, hasRoots ? motionRootDrawOrderReader(activeDest) : undefined), undefined, motionRootProblems, unmeasuredRoots);
6244
+ enrichMotionSeamPoses(activeDest, inp.rig, inp.parts, pairs, motionSeam.rows);
6143
6245
  if (stripped !== null) {
6144
6246
  const response = environmentResponse(readFileSync(join(buildDir, 'skeleton.json'), 'utf8'));
6145
6247
  motionSeam.worlds = motionSeamWorlds(true, response.wind.length > 0, world => {
@@ -31,6 +31,7 @@ import { basename, dirname, join } from 'node:path';
31
31
  import { refuseIfAny } from '../errors.ts';
32
32
  import { checkGraph, fillSeeThrough, type SeeThroughParams } from '../graphs.ts';
33
33
  import { readWrapperLayers } from '../layers.ts';
34
+ import type { DepthBinding } from '../depthsheets.ts';
34
35
  import { decodePngBytes } from '../raster/png.ts';
35
36
  import { ComfyClient, historyImages, refuse } from './client.ts';
36
37
 
@@ -50,6 +51,8 @@ export interface SeeThroughRun {
50
51
  quant: 'none' | 'nf4';
51
52
  wait: number;
52
53
  timeout: number;
54
+ /** Explicit config/run context; absent means legacy art-only capture. */
55
+ depth?: DepthBinding;
53
56
  }
54
57
 
55
58
  export interface SeeThroughResult {
@@ -73,6 +76,7 @@ function safeName(name: string): boolean {
73
76
  }
74
77
 
75
78
  export async function runSeeThrough(client: ComfyClient, run: SeeThroughRun, say: (line: string) => void): Promise<SeeThroughResult> {
79
+ const depth = run.depth?.config === undefined ? undefined : run.depth;
76
80
  if (!existsSync(run.image)) refuse('COMFY_IMAGE_PRESENT', run.image, 'no such file; the PNG See-through is to decompose is required');
77
81
  const bytes = new Uint8Array(readFileSync(run.image));
78
82
  const img = decodePngBytes(bytes, run.image);
@@ -122,7 +126,7 @@ export async function runSeeThrough(client: ComfyClient, run: SeeThroughRun, say
122
126
  }
123
127
  const layers = Array.isArray(manifest.layers) ? (manifest.layers as Array<Record<string, unknown>>) : [];
124
128
  if (layers.length === 0) refuse('COMFY_MANIFEST_NAMED', `output/${infoLog}`, 'lists no layers; a See-through run writes one per tag');
125
- const bad = layers.filter((l) => typeof l.name !== 'string' || !safeName(l.name) || typeof l.filename !== 'string' || !safeName(l.filename));
129
+ const bad = layers.filter((l) => typeof l.name !== 'string' || !safeName(l.name) || typeof l.filename !== 'string' || !safeName(l.filename) || (depth !== undefined && 'depth_filename' in l && (typeof l.depth_filename !== 'string' || !safeName(l.depth_filename))));
126
130
  if (bad.length > 0) {
127
131
  refuse('COMFY_LAYER_NAME', `output/${infoLog}`, `names ${bad.length} layer(s) whose name or filename is not a plain file name (first ${JSON.stringify(bad[0]).slice(0, 200)}); each becomes parts/<name>.png`);
128
132
  }
@@ -135,8 +139,9 @@ export async function runSeeThrough(client: ComfyClient, run: SeeThroughRun, say
135
139
  try {
136
140
  for (const p of previews) writeFileSync(join(stage, 'previews', basename(p.filename)), await client.view(p.filename, p.subfolder, p.type));
137
141
  for (const l of layers) writeFileSync(join(stage, 'parts', `${l.name as string}.png`), await client.view(l.filename as string));
142
+ if (depth !== undefined) for (const l of layers) if ('depth_filename' in l) writeFileSync(join(stage, 'parts', `${l.name as string}_depth.png`), await client.view(l.depth_filename as string));
138
143
  writeFileSync(join(stage, 'layers.json'), manifestBytes);
139
- const set = readWrapperLayers(stage);
144
+ const set = readWrapperLayers(stage, depth);
140
145
  const meta = {
141
146
  prompt_id: id,
142
147
  image: run.image,
package/src/config.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import type { DepthConfig } from './depthsheets.ts';
1
2
  /**
2
3
  * The character config: everything character-specific the CPU stages read,
3
4
  * plus the optional blocks for the two GPU stages.
@@ -88,6 +89,7 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
88
89
  import { dirname, resolve } from 'node:path';
89
90
  import { RIG_BONE_INHERIT, RIG_SKIN_CONSTRAINT_KEYS, type RigBoneInherit, type RigConstraint, type RigSkinConstraintKey, type RigStop } from 'rig-c/src/rig.ts';
90
91
  import { pyRound } from './round.ts';
92
+ import { motionSeamProblems, type MotionSeamDeclaration } from './motionseams.ts';
91
93
  import { REQUIREMENTS_SPEC } from './requirements.ts';
92
94
  import { CLOTH_TARGETS, type ClothRecipes, RECIPE_STRENGTH, RIGC_DEFAULT_DAMPING, springStable } from './cloth.ts';
93
95
  import { GRID, MAX_SIDE } from './contour.ts';
@@ -96,7 +98,7 @@ import { edgeLength } from './length.ts';
96
98
  import { setFocusProblems } from './setfocus.ts';
97
99
  import { isSkeletonName, KEYPOINT_NAMES, type KeypointName, type PosePoints, scaledPoints, SKELETON_NAMES, type SkeletonName } from './skeleton.ts';
98
100
  import { acceptedTagNames, AUTHOR_LABEL_RULE, AUTHOR_PREFIX, readLayerTag } from './tags.ts';
99
- import { EAR_DEPTH_RANGE, FACE_DEFORM_FRACTIONS, FACE_DEFORM_RANGES, type FaceDeformKey, FACE_RATED_PITCH_BAND, FACE_RATED_YAW_BAND, TURN_BONE, type TurnSpec, turnNearest } from './turn.ts';
101
+ import { EAR_DEPTH_RANGE, FACE_DEFORM_FRACTIONS, FACE_DEFORM_RANGES, type FaceDeformKey, FACE_RATED_PITCH_BAND, FACE_RATED_YAW_BAND, FACESHIFT_BONE, REAR_SHIFT_BONE, TURN_BONE, TURN_ROLES, type TurnSpec, turnNearest, turnSurfaceBone } from './turn.ts';
100
102
  import { FLOOR_FORMS, type FloorForm, type MeshInfluences } from './weights.ts';
101
103
 
102
104
  export type Point = [number, number];
@@ -1038,6 +1040,7 @@ export type LimbLayout = { parts?: string[] } & (
1038
1040
  );
1039
1041
 
1040
1042
  export interface CharacterConfig {
1043
+ depth?: DepthConfig;
1041
1044
  key: string;
1042
1045
  note?: string;
1043
1046
  generation?: Generation;
@@ -1069,6 +1072,8 @@ export interface CharacterConfig {
1069
1072
  * is read and no byte of any output moves.
1070
1073
  */
1071
1074
  requirements?: string;
1075
+ /** Explicit motion observations, propagated to parts.json; absent means no added pair. */
1076
+ motion_seams?: MotionSeamDeclaration[];
1072
1077
  }
1073
1078
 
1074
1079
  /** `config.scene` (issue #242): the declaration that the painting is a scene. It holds no field today. */
@@ -1375,6 +1380,7 @@ export interface PaintConfig {
1375
1380
  * bones, meshes, regions and motion that are written only after them.
1376
1381
  */
1377
1382
  export interface EarlyConfig {
1383
+ depth?: DepthConfig;
1378
1384
  key: string;
1379
1385
  seethrough: SeeThrough;
1380
1386
  assemble: { rig_scale: number; head_face_underfill?: boolean };
@@ -1382,6 +1388,7 @@ export interface EarlyConfig {
1382
1388
 
1383
1389
  /** What plain `assemble` reads: the early config plus the plan `--propose-plan` printed. */
1384
1390
  export interface AssembleConfig {
1391
+ depth?: DepthConfig;
1385
1392
  key: string;
1386
1393
  seethrough: SeeThrough;
1387
1394
  assemble: Assemble;
@@ -1389,11 +1396,12 @@ export interface AssembleConfig {
1389
1396
  /** Issue #349: read with `bones` (the joints are the bones' origins) when present. */
1390
1397
  limbs?: Record<string, Limb>;
1391
1398
  bones?: BoneEntry[];
1399
+ motion_seams?: MotionSeamDeclaration[];
1392
1400
  /** Issue #354: the `rig_scale` `propose` drafted the rig sections at, held equal to `assemble.rig_scale` when present. */
1393
1401
  proposed_rig_scale?: number;
1394
1402
  }
1395
1403
 
1396
- const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'limbs', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'stops', 'turn', 'scene', 'cloth', 'proposed_rig_scale', 'requirements'] as const;
1404
+ const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'limbs', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'stops', 'turn', 'scene', 'cloth', 'proposed_rig_scale', 'requirements', 'motion_seams', 'depth'] as const;
1397
1405
 
1398
1406
  /**
1399
1407
  * The one partial entry point. It validates exactly what its door requires —
@@ -1424,6 +1432,7 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
1424
1432
  const top = c.object('config', raw, required, TOP_KEYS.filter((k) => !required.includes(k)));
1425
1433
  if (top === null) refuseIfAny(c.problems);
1426
1434
  const t = top as Record<string, Json>;
1435
+ if ('depth' in t) checkDepthConfig(c, t.depth);
1427
1436
  if ('key' in t) c.string('config.key', t.key);
1428
1437
  if ('generation' in t) checkGeneration(c, t.generation);
1429
1438
  else if (needed.includes('generation')) {
@@ -1464,6 +1473,10 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
1464
1473
  if (isPlainObject(t.assemble) && 'alternates' in t.assemble) {
1465
1474
  checkAlternates(c, t.assemble.alternates, made, limbs, names?.bones ?? null, names?.chains ?? null, t.regions, t.meshes);
1466
1475
  }
1476
+ if ('motion_seams' in t) {
1477
+ const output = new Set([...made.parts.filter(n => !limbs?.consumed.has(n)), ...made.patches, ...made.cuts, ...(limbs?.parts.keys() ?? [])]);
1478
+ c.problems.push(...motionSeamProblems(t.motion_seams, output, 'config.motion_seams', 'CONFIG_MOTION_SEAM'));
1479
+ }
1467
1480
  }
1468
1481
  if ('cloth' in t) checkCloth(c, t.cloth);
1469
1482
  const pose = base === null ? null : poseBeside(c, t.generation, base);
@@ -1643,6 +1656,7 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
1643
1656
  const top = c.object('config', raw, required, TOP_KEYS.filter((k) => !required.includes(k)));
1644
1657
  if (top === null) refuseIfAny(c.problems);
1645
1658
  const t = top as Record<string, Json>;
1659
+ if ('depth' in t) checkDepthConfig(c, t.depth);
1646
1660
  if ('key' in t) c.string('config.key', t.key);
1647
1661
  if ('generation' in t) checkGeneration(c, t.generation);
1648
1662
  if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
@@ -1660,8 +1674,9 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
1660
1674
  if ('constraints' in t) checkConstraints(c, t.constraints, names.bones, names.parents);
1661
1675
  if ('stops' in t) checkStops(c, t.stops, names.bones, names.chains);
1662
1676
  const attached = attachedParts(t.meshes, t.regions);
1677
+ if ('motion_seams' in t) c.problems.push(...motionSeamProblems(t.motion_seams, attached, 'config.motion_seams', 'CONFIG_MOTION_SEAM'));
1663
1678
  const hasAltFace = hasAlternateFaceSet(t.assemble, [...parts, ...cuts]);
1664
- if ('turn' in t) checkTurn(c, t.turn, attached, names.bones, hasAltFace);
1679
+ if ('turn' in t) checkTurn(c, t.turn, attached, names.bones, hasAltFace, parts);
1665
1680
  if ('scene' in t) checkScene(c, t.scene);
1666
1681
  if ('cloth' in t) checkCloth(c, t.cloth);
1667
1682
  if ('requirements' in t && c.string('config.requirements', t.requirements) && base !== null) checkRequirementsFile(c, resolve(base, t.requirements));
@@ -1890,9 +1905,9 @@ export interface SkeletonSections {
1890
1905
  * both before writing (`checkProposal`). A key the loader would not take is
1891
1906
  * refused by name, as in a config. Refusals name the fields `proposal.…`.
1892
1907
  */
1893
- export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[]; proposed_rig_scale?: number } {
1908
+ export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[]; proposed_rig_scale?: number; motion_seams?: MotionSeamDeclaration[] } {
1894
1909
  const c = new Check();
1895
- const top = c.object('config', raw, ['bones', 'meshes', 'regions', 'motion'], ['notes', 'limbs', 'constraints', 'stops', 'proposed_rig_scale']);
1910
+ const top = c.object('config', raw, ['bones', 'meshes', 'regions', 'motion'], ['notes', 'limbs', 'constraints', 'stops', 'proposed_rig_scale', 'motion_seams']);
1896
1911
  if (top !== null) {
1897
1912
  const names = 'bones' in top ? checkBones(c, top.bones) : { bones: new Set<string>([ROOT_BONE]), chains: new Map<string, number>(), parents: new Map<string, string>() };
1898
1913
  if ('limbs' in top) {
@@ -1903,6 +1918,7 @@ export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: R
1903
1918
  }
1904
1919
  if ('meshes' in top) checkMeshes(c, top.meshes, names.bones, names.chains, top.stops);
1905
1920
  if ('regions' in top) checkRegions(c, top.regions, names.bones);
1921
+ if ('motion_seams' in top) c.problems.push(...motionSeamProblems(top.motion_seams, attachedParts(top.meshes, top.regions), 'config.motion_seams', 'CONFIG_MOTION_SEAM'));
1906
1922
  if ('motion' in top) checkMotion(c, top.motion, names.bones, names.chains, 'regions' in top ? top.regions : undefined);
1907
1923
  if ('constraints' in top) checkConstraints(c, top.constraints, names.bones, names.parents);
1908
1924
  if ('stops' in top) checkStops(c, top.stops, names.bones, names.chains);
@@ -1910,7 +1926,7 @@ export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: R
1910
1926
  if ('notes' in top && c.array('config.notes', top.notes, false)) (top.notes as Json[]).forEach((n, i) => c.string(`config.notes[${i}]`, n, false));
1911
1927
  }
1912
1928
  refuseIfAny(c.problems.map((p) => ({ ...p, object: p.object.replace(/^config\b/, 'proposal') })));
1913
- return raw as SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[]; proposed_rig_scale?: number };
1929
+ return raw as SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[]; proposed_rig_scale?: number; motion_seams?: MotionSeamDeclaration[] };
1914
1930
  }
1915
1931
 
1916
1932
  /**
@@ -4115,6 +4131,7 @@ export function loadClothConfig(path: string): { key: string; cloth: ClothRecipe
4115
4131
  const top = c.object('config', raw, required, TOP_KEYS.filter((k) => !required.includes(k)));
4116
4132
  if (top === null) refuseIfAny(c.problems);
4117
4133
  const t = top as Record<string, Json>;
4134
+ if ('depth' in t) checkDepthConfig(c, t.depth);
4118
4135
  if ('key' in t) c.string('config.key', t.key);
4119
4136
  if ('cloth' in t) checkCloth(c, t.cloth);
4120
4137
  refuseIfAny(c.problems);
@@ -4179,7 +4196,7 @@ function checkFaceAnimationBand(c: Check, animations: AnimationsFrom, hasAltFace
4179
4196
  'config.turn',
4180
4197
  "is absent and required when motion.animations_from carries a turn or tilt slider animation with derive keys; copy the turn block propose drafted into config.turn so the head pivot and each head part's depth are declared",
4181
4198
  );
4182
- } else if (isPlainObject(turn) && isPlainObject(turn.depths) && attached !== undefined) {
4199
+ } else if (isPlainObject(turn) && isPlainObject(turn.depths) && !isPlainObject(turn.roles) && attached !== undefined) {
4183
4200
  for (const reqPart of ['face', 'hair_front', 'hair_back'] as const) {
4184
4201
  if (attached.has(reqPart) && !(reqPart in turn.depths)) {
4185
4202
  c.fail(
@@ -4343,11 +4360,98 @@ function checkAnimationSetKeys(
4343
4360
  }
4344
4361
  }
4345
4362
 
4346
- function checkTurn(c: Check, v: Json, attached: Set<string>, bones: Set<string>, hasAltFace: boolean): void {
4363
+ function checkTurn(c: Check, v: Json, attached: Set<string>, bones: Set<string>, hasAltFace: boolean, parts: readonly string[] = []): void {
4347
4364
  const at = 'config.turn';
4348
- const o = c.object(at, v, ['pivot', 'depths'], ['head', 'deform', 'band', 'radius', 'surface']);
4365
+ const hasRoles = isPlainObject(v) && 'roles' in v;
4366
+ const o = hasRoles
4367
+ ? c.object(at, v, ['roles'], ['pivot', 'depths', 'counter', 'grid', 'unitDepths', 'head', 'deform', 'band', 'radius', 'surface'])
4368
+ : c.object(at, v, ['pivot', 'depths'], ['roles', 'counter', 'grid', 'unitDepths', 'head', 'deform', 'band', 'radius', 'surface']);
4349
4369
  if (o === null) return;
4350
4370
  const pivot = 'pivot' in o && c.number(`${at}.pivot`, o.pivot) ? (o.pivot as number) : null;
4371
+ if ('counter' in o && c.number(`${at}.counter`, o.counter)) {
4372
+ const cnt = o.counter as number;
4373
+ if (cnt < 0 || cnt > 1) {
4374
+ c.fail('CONFIG_TURN_COUNTER_RANGE', `${at}.counter`, `is ${cnt}; a rear counter fraction in [0, 1] is required`);
4375
+ }
4376
+ }
4377
+ if ('grid' in o) {
4378
+ const checkGridPair = (gAt: string, gv: Json): void => {
4379
+ if (!Array.isArray(gv) || gv.length !== 2 || !gv.every((n) => typeof n === 'number' && Number.isInteger(n) && n >= 2)) {
4380
+ c.fail('CONFIG_FIELD_TYPE', gAt, `is ${show(gv)}; a [cols, rows] pair of integers >= 2 is required`);
4381
+ }
4382
+ };
4383
+ if (Array.isArray(o.grid)) {
4384
+ checkGridPair(`${at}.grid`, o.grid);
4385
+ } else if (isPlainObject(o.grid)) {
4386
+ for (const [part, gv] of Object.entries(o.grid)) {
4387
+ if (isRecordKey(part)) continue;
4388
+ if (!attached.has(part)) {
4389
+ c.fail('CONFIG_NAME_RESOLVES', `${at}.grid.${part}`, `names "${part}", which neither config.meshes nor config.regions attaches`);
4390
+ }
4391
+ checkGridPair(`${at}.grid.${part}`, gv);
4392
+ }
4393
+ } else {
4394
+ c.fail('CONFIG_FIELD_TYPE', `${at}.grid`, `is ${show(o.grid)}; a [cols, rows] pair or object of part -> [cols, rows] is required`);
4395
+ }
4396
+ }
4397
+ if ('unitDepths' in o) {
4398
+ if (!isPlainObject(o.unitDepths)) {
4399
+ c.fail('CONFIG_FIELD_TYPE', `${at}.unitDepths`, `is ${show(o.unitDepths)}; an object of part or bone name -> scalar depth is required`);
4400
+ } else {
4401
+ for (const [k, dv] of Object.entries(o.unitDepths)) {
4402
+ if (isRecordKey(k)) continue;
4403
+ if (!attached.has(k) && !bones.has(k)) {
4404
+ c.fail('CONFIG_NAME_RESOLVES', `${at}.unitDepths.${k}`, `names "${k}", which is neither an attached part nor a declared bone`);
4405
+ }
4406
+ c.number(`${at}.unitDepths.${k}`, dv);
4407
+ }
4408
+ }
4409
+ }
4410
+ if ('roles' in o) {
4411
+ const r = o.roles;
4412
+ if (!isPlainObject(r) || Object.keys(r).length === 0) {
4413
+ c.fail('CONFIG_FIELD_TYPE', `${at}.roles`, `is ${show(r)}; a non-empty object of part name -> ("surface" | "unit" | "rear") is required`);
4414
+ } else {
4415
+ const surfaceParts: string[] = [];
4416
+ const earParts: string[] = [];
4417
+ for (const [part, role] of Object.entries(r)) {
4418
+ if (isRecordKey(part)) continue;
4419
+ if (!attached.has(part)) {
4420
+ c.fail('CONFIG_NAME_RESOLVES', `${at}.roles.${part}`, `names "${part}", which neither config.meshes nor config.regions attaches; a part the rig draws is required`);
4421
+ }
4422
+ if (typeof role !== 'string' || !(TURN_ROLES as readonly string[]).includes(role)) {
4423
+ c.fail('CONFIG_TURN_ROLE_UNKNOWN', `${at}.roles.${part}`, `is ${show(role)}; expected one of ${TURN_ROLES.map((x) => `"${x}"`).join(', ')}`);
4424
+ } else {
4425
+ if (role === 'surface') surfaceParts.push(part);
4426
+ if (role === 'unit' && (part === 'ear_r' || part === 'ear_l')) earParts.push(part);
4427
+ }
4428
+ }
4429
+ if (surfaceParts.length === 0) {
4430
+ c.fail('CONFIG_TURN_SURFACE_REQUIRED', `${at}.roles`, 'declares no part with role "surface"; at least one surface part (such as "face") is required for 2.5D head turn');
4431
+ }
4432
+ for (const ear of earParts) {
4433
+ const earIdx = parts.indexOf(ear);
4434
+ for (const surf of surfaceParts) {
4435
+ const surfIdx = parts.indexOf(surf);
4436
+ if (earIdx !== -1 && surfIdx !== -1 && earIdx > surfIdx) {
4437
+ c.fail(
4438
+ 'CONFIG_TURN_EAR_DRAW_ORDER',
4439
+ `${at}.roles.${ear}`,
4440
+ `draws "${ear}" (plan index ${earIdx}) after surface part "${surf}" (plan index ${surfIdx}); place "${ear}" before "${surf}" in config.assemble.plan so the ear is occluded behind the face`,
4441
+ );
4442
+ }
4443
+ }
4444
+ }
4445
+ if (!bones.has('head')) {
4446
+ c.fail('CONFIG_TURN_HEAD_BONE', `${at}.roles`, 'requires a declared "head" bone in config.bones to parent the 2.5D turn carriers');
4447
+ }
4448
+ for (const reserved of [FACESHIFT_BONE, REAR_SHIFT_BONE, ...surfaceParts.map(turnSurfaceBone)]) {
4449
+ if (bones.has(reserved)) {
4450
+ c.fail('CONFIG_TURN_BONE_FREE', `bone "${reserved}"`, `is a carrier bone the rig stage adds under head for config.turn.roles, and config.bones already declares a bone of that name; rename it`);
4451
+ }
4452
+ }
4453
+ }
4454
+ }
4351
4455
  if ('radius' in o) c.number(`${at}.radius`, o.radius, 'positive');
4352
4456
  if ('surface' in o) {
4353
4457
  const so = c.object(`${at}.surface`, o.surface, [], ['radius']);
@@ -4443,7 +4547,7 @@ function checkTurn(c: Check, v: Json, attached: Set<string>, bones: Set<string>,
4443
4547
  }
4444
4548
  }
4445
4549
  }
4446
- if (pivot !== null && depthsOk) {
4550
+ if (!hasRoles && pivot !== null && depthsOk) {
4447
4551
  const nearest = turnNearest(depths);
4448
4552
  if (nearest !== null && !(pivot > nearest.depth)) {
4449
4553
  c.fail(
@@ -4453,7 +4557,7 @@ function checkTurn(c: Check, v: Json, attached: Set<string>, bones: Set<string>,
4453
4557
  );
4454
4558
  }
4455
4559
  }
4456
- if (headPivot !== null && depthsOk) {
4560
+ if (!hasRoles && headPivot !== null && depthsOk) {
4457
4561
  const nearest = turnNearest(depths);
4458
4562
  if (nearest !== null && !(headPivot > nearest.depth)) {
4459
4563
  c.fail(
@@ -4463,7 +4567,34 @@ function checkTurn(c: Check, v: Json, attached: Set<string>, bones: Set<string>,
4463
4567
  );
4464
4568
  }
4465
4569
  }
4466
- if (bones.has(TURN_BONE)) {
4570
+ if (!hasRoles && bones.has(TURN_BONE)) {
4467
4571
  c.fail('CONFIG_TURN_BONE_FREE', `bone "${TURN_BONE}"`, `is the control the rig stage adds under root for config.turn, and config.bones already declares a bone of that name; rename it`);
4468
4572
  }
4469
4573
  }
4574
+
4575
+ /** #773: all scalar units and user polarity are authored, never inferred. */
4576
+ function checkDepthConfig(c: Check, raw: Json): void {
4577
+ const d = c.object('config.depth', raw, [], ['zScale', 'full', 'head']);
4578
+ if (d === null) return;
4579
+ const scale = (path: string, v: Json | undefined): void => {
4580
+ if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0) c.fail('DEPTH_ZSCALE_REQUIRED', path, `is ${show(v)}; positive finite authored world units are required`);
4581
+ };
4582
+ if ('zScale' in d) scale('config.depth.zScale', d.zScale);
4583
+ const sheet = (path: string, value: Json): void => {
4584
+ const q = c.object(path, value, ['image'], ['near', 'zScale']);
4585
+ if (q === null) return;
4586
+ if ('image' in q) c.string(`${path}.image`, q.image);
4587
+ if (q.near !== 'black' && q.near !== 'white') c.fail('DEPTH_NEAR_REQUIRED', `${path}.near`, `is ${show(q.near)}; a user sheet must declare black or white, with no guessed convention`);
4588
+ scale(`${path}.zScale`, q.zScale);
4589
+ };
4590
+ for (const run of ['full', 'head']) if (run in d) {
4591
+ const path = `config.depth.${run}`, q = c.object(path, d[run], [], ['layers', 'atlas']);
4592
+ if (q === null) continue;
4593
+ if ('atlas' in q) sheet(`${path}.atlas`, q.atlas);
4594
+ if ('layers' in q) {
4595
+ if (!isPlainObject(q.layers)) c.fail('CONFIG_FIELD_TYPE', `${path}.layers`, 'requires an object keyed by exact source layer name');
4596
+ else for (const [layer, value] of Object.entries(q.layers)) sheet(`${path}.layers.${layer}`, value);
4597
+ }
4598
+ if ('atlas' in q && isPlainObject(q.layers) && Object.keys(q.layers).length > 0) c.fail('DEPTH_SOURCE_AMBIGUOUS', path, 'declares canvas and per-layer sheets together; choose one fallback explicitly');
4599
+ }
4600
+ }