@rig-c/parts 1.64.0 → 1.65.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
@@ -2628,6 +2628,8 @@ export interface CheckFigures {
2628
2628
  RECOMPOSITE_HOLES: ReportedLine;
2629
2629
  /** Written only under `--source` (issue #77): the setup pose against the painting, REPORTED. */
2630
2630
  SETUP_POSE_VS_SOURCE?: ReportedLine;
2631
+ /** Written only under `--wind-band` (issue #590): the steady-wind band each declared seam pair holds, REPORTED. */
2632
+ [WIND_BAND_LINE]?: WindBandLine;
2631
2633
  /**
2632
2634
  * Written only when the loop or the seam measured nothing (issue #77): the
2633
2635
  * reason for each, by the name its console line goes by. The judgement and
@@ -2941,6 +2943,8 @@ export interface CheckReport {
2941
2943
  motionSeam: MotionSeamLine;
2942
2944
  /** `CLOTH_SETTLES` (issue #501): a warning, never a bar — in `check.json` only when the rig declares a physics constraint and has an idle; its SKIP is printed either way. */
2943
2945
  cloth: ClothLine;
2946
+ /** `WIND_BAND` (issue #590): the steady-wind band each declared seam pair holds, written under `--wind-band` only. */
2947
+ windBand?: WindBandLine;
2944
2948
  /**
2945
2949
  * Issue #557: the contour step at each pose `SEAM_OVER_RANGE` read, by `<part> <degrees>` ({@link contourStep}) —
2946
2950
  * printed on every row; `check.json` carries it only for a joint whose cap is short ({@link SweepPose}).
@@ -2989,15 +2993,15 @@ export type CheckStatus = 'PASS' | 'FAIL' | 'SKIP' | 'WARN' | 'CLEAR' | 'REPORTE
2989
2993
  * never skipped); `loop` SKIP when `loop_max_diff` is null, `seam` SKIP when `seam_mean` is null, otherwise FAIL when
2990
2994
  * {@link barsNotMet} names it and PASS when it does not. Every other block carries its own `status` key and is copied:
2991
2995
  * the judgement lines, then {@link FOLD_LINE}, {@link LEVEL_LINE}, {@link STRESS_LINE}, {@link LIMB_LINE},
2992
- * {@link SWEEP_LINE}, {@link MOTION_SEAM_LINE}, {@link CLOTH_LINE}, the reported lines and {@link SOURCE_LINE}, each
2993
- * where the file writes it. The `requirements` block's lines are not bars and are not read here.
2996
+ * {@link SWEEP_LINE}, {@link MOTION_SEAM_LINE}, {@link CLOTH_LINE}, the reported lines, {@link SOURCE_LINE} and
2997
+ * {@link WIND_BAND_LINE}, each where the file writes it. The `requirements` block's lines are not bars and are not read here.
2994
2998
  */
2995
2999
  export function checkStatuses(fig: CheckFigures): Record<string, CheckStatus> {
2996
3000
  const notMet = barsNotMet(fig as unknown as Record<string, unknown>);
2997
3001
  const bar = (name: string, measured: boolean): CheckStatus => (!measured ? 'SKIP' : notMet.includes(name) ? 'FAIL' : 'PASS');
2998
3002
  const out: Record<string, CheckStatus> = { gate: bar('gate', true), loop: bar('loop', fig.loop_max_diff !== null), seam: bar('seam', fig.seam_mean !== null) };
2999
3003
  for (const n of JUDGEMENT_LINES) out[n] = fig[n].status;
3000
- for (const n of [FOLD_LINE, LEVEL_LINE, STRESS_LINE, LIMB_LINE, SWEEP_LINE, MOTION_SEAM_LINE, CLOTH_LINE, ...REPORTED_LINES, SOURCE_LINE] as const) {
3004
+ for (const n of [FOLD_LINE, LEVEL_LINE, STRESS_LINE, LIMB_LINE, SWEEP_LINE, MOTION_SEAM_LINE, CLOTH_LINE, ...REPORTED_LINES, SOURCE_LINE, WIND_BAND_LINE] as const) {
3001
3005
  const l = fig[n];
3002
3006
  if (l !== undefined) out[n] = l.status;
3003
3007
  }
@@ -3649,7 +3653,7 @@ export function stressPlan(rig: Record<string, unknown>, motion: Record<string,
3649
3653
  for (const p of parts) {
3650
3654
  // Issue #349: a limb segment is held to its one bone by LIMB_ONE_BONE, read off rig.json, so it turns rigidly by construction.
3651
3655
  if (p.limb !== undefined) {
3652
- notRead.push({ part: p.name, reason: `a limb segment (config.limbs.${p.limb.name}), held to its one bone "${p.limb.bone}" by ${LIMB_LINE}, so it turns rigidly by construction` });
3656
+ notRead.push({ part: p.name, reason: p.limb.band !== undefined ? `a hybrid joint band (config.limbs.${p.limb.name}), bound to its adjacent carriers by ${LIMB_LINE}; its declared range is read by ${SWEEP_LINE}, with no rigid-stretch promise` : `a limb segment (config.limbs.${p.limb.name}), held to its one bone "${p.limb.bone}" by ${LIMB_LINE}, so it turns rigidly by construction` });
3653
3657
  continue;
3654
3658
  }
3655
3659
  const onSlot = skin[p.name];
@@ -3794,7 +3798,8 @@ export function stressLine(plan: StressPlan, geometry: (animation: string) => Id
3794
3798
  * `LIMB_ONE_BONE` (issue #349): every part a `config.limbs` segment made —
3795
3799
  * `parts.json`'s records that carry `limb` — is bound in `rig.json` to its
3796
3800
  * limb bone alone, with weight 1: a region on a slot whose bone is that bone,
3797
- * or a mesh whose every weight names it. A bend is a rotation at the joint,
3801
+ * or a mesh whose every weight names it. An explicit hybrid band instead
3802
+ * requires both recorded adjacent carriers and no third bone (issue #399). A bend is a rotation at the joint,
3798
3803
  * never a deformed mesh, and a second bone is the pin (a puff held by the
3799
3804
  * chest) or the noodle (a forearm blended along a chain) the cut retires.
3800
3805
  * Under `config.turn` a part rides the leaf twin of its bone
@@ -3827,17 +3832,19 @@ export function limbLine(parts: PartsFile, rig: Record<string, unknown>, problem
3827
3832
  const slots = (Array.isArray(rig.slots) ? rig.slots : []).filter(isRecord);
3828
3833
  const rows: LimbRow[] = limbParts.map((p) => {
3829
3834
  const l = p.limb as NonNullable<PartRecord['limb']>;
3830
- const own = new Set([l.bone, turnTwin(p.name, l.bone)]);
3835
+ const own = new Set([l.bone, turnTwin(p.name, l.bone), ...(l.band === undefined ? [] : [l.band.upper, turnTwin(p.name, l.band.upper)])]);
3831
3836
  const slot = slots.find((sl) => sl.name === p.name);
3832
3837
  const bound = slot === undefined ? new Set<string>() : boundBones(rig, p.name);
3833
3838
  const others = [...bound].filter((b) => !own.has(b));
3834
- const fail = others.length > 0 || bound.size === 0;
3839
+ const fail = others.length > 0 || bound.size === 0 || (l.band !== undefined && (![l.bone, turnTwin(p.name, l.bone)].some((b) => bound.has(b)) || ![l.band.upper, turnTwin(p.name, l.band.upper)].some((b) => bound.has(b))));
3835
3840
  if (fail) {
3836
3841
  problems.push({
3837
3842
  code: `CHECK_${LIMB_LINE}`,
3838
3843
  object: `limb part "${p.name}" (config.limbs.${l.name} segment ${l.segment}, bone "${l.bone}")`,
3839
3844
  detail:
3840
- bound.size === 0
3845
+ l.band !== undefined
3846
+ ? `binds [${[...bound].join(', ')}]; the band requires both "${l.band.upper}" and "${l.bone}" and no other carrier — re-run rig with the recorded joint band`
3847
+ : bound.size === 0
3841
3848
  ? `is bound to no bone in rig.json (no slot of its name, or no attachment); its one bone "${l.bone}", with weight 1, is required`
3842
3849
  : `is weighted to ${others.map((b) => `"${b}"`).join(', ')} besides "${l.bone}"; a limb part rides its one bone with weight 1 — a bend is a rotation at the joint, never a deformed mesh — so a region on "${l.bone}" (config.regions.${p.name}), or a mesh whose segments name "${l.bone}" alone, is required`,
3843
3850
  });
@@ -3881,8 +3888,9 @@ export function sweepJoints(parts: PartsFile): SweepJoint[] {
3881
3888
  const out: SweepJoint[] = [];
3882
3889
  for (const p of parts.parts) {
3883
3890
  const l = p.limb;
3884
- if (l === undefined || l.range === undefined || l.cap === undefined || l.joint === undefined) continue;
3891
+ if (l === undefined || l.range === undefined || (l.cap === undefined && l.hybrid === undefined) || l.joint === undefined) continue;
3885
3892
  const up = parts.parts.find((q) => q.limb?.name === l.name && q.limb.segment === l.segment - 1)?.limb?.bone ?? null;
3893
+ const geometry = l.cap ?? l.hybrid as NonNullable<typeof l.hybrid>;
3886
3894
  out.push({
3887
3895
  part: p.name,
3888
3896
  limb: l.name,
@@ -3890,11 +3898,11 @@ export function sweepJoints(parts: PartsFile): SweepJoint[] {
3890
3898
  joint: l.joint,
3891
3899
  bone: l.bone,
3892
3900
  range: [l.range[0], l.range[1]],
3893
- at: [l.cap.at[0], l.cap.at[1]],
3894
- radius: l.cap.radius,
3895
- ...(l.cap.shape === undefined ? {} : { shape: l.cap.shape }),
3901
+ at: [...geometry.at],
3902
+ radius: geometry.radius,
3903
+ ...(l.cap?.shape === undefined ? {} : { shape: l.cap.shape }),
3896
3904
  upperBone: up,
3897
- ...(l.cap.short_px === undefined ? {} : { short: { left: l.cap.short_px.left, right: l.cap.short_px.right } }),
3905
+ ...(l.cap?.short_px === undefined ? {} : { short: { left: l.cap.short_px.left, right: l.cap.short_px.right } }),
3898
3906
  });
3899
3907
  }
3900
3908
  return out;
@@ -5123,6 +5131,471 @@ export function environmentLine(env: CheckEnvironment): string {
5123
5131
  return `environment: ${env.path}, ${ENVIRONMENT_SPEC}, ${env.steps} step(s), sha256 ${env.sha256.slice(0, 16)} — every render a bar or a warning reads with the physics on is posed under it; the physics-off, setup-pose and loop renders are not`;
5124
5132
  }
5125
5133
 
5134
+ // ---------------------------------------------------------------------------
5135
+ // the steady-wind seam band (issue #590)
5136
+ // ---------------------------------------------------------------------------
5137
+
5138
+ /** The spec id of a `--wind-band` file (issue #590). */
5139
+ export const WIND_BAND_SPEC = 'rig-parts-wind-band/1';
5140
+ /** The refusal rule of `--wind-band` (issue #590). */
5141
+ export const WIND_BAND_RULE = 'CHECK_WIND_BAND';
5142
+ /** The reported line `--wind-band` writes to `check.json` and the console (issue #590). */
5143
+ export const WIND_BAND_LINE = 'WIND_BAND';
5144
+ /** Maximum number of steps `(max - min) / step` a `--wind-band` sweep may take. */
5145
+ export const WIND_BAND_MAX_STEPS = 64;
5146
+
5147
+ const WIND_BAND_KEYS = ['spec', 'min', 'max', 'step', 'fps', 'max_gap', 'max_ghost', 'pairs'] as const;
5148
+ const WIND_BAND_SCRATCH = '_wind_band';
5149
+
5150
+ /** Parsed `--wind-band <spec.json>` specification (issue #590). Every field is required; nothing falls back. */
5151
+ export interface WindBandSpec {
5152
+ path: string;
5153
+ sha256: string;
5154
+ min: number;
5155
+ max: number;
5156
+ step: number;
5157
+ steps: number[];
5158
+ fps: number;
5159
+ max_gap: number;
5160
+ max_ghost: number;
5161
+ pairs: Array<{ pair: string; a: string; b: string }>;
5162
+ }
5163
+
5164
+ /** First step where a seam pair exceeds `max_gap` or `max_ghost` below or above its holding band. */
5165
+ export interface WindBandBreak {
5166
+ x: number;
5167
+ kind: 'gap' | 'ghost';
5168
+ px: number;
5169
+ bar: number;
5170
+ animation: string;
5171
+ frame: number;
5172
+ }
5173
+
5174
+ /** Per-step steady-wind seam reading for one pair across all animations. */
5175
+ export interface WindBandStepReading {
5176
+ x: number;
5177
+ holds: boolean;
5178
+ gap_max_px: number;
5179
+ ghost_max_px: number;
5180
+ }
5181
+
5182
+ /** One declared seam pair's steady-wind band and worst readings across the swept range. */
5183
+ export interface WindBandPairRow {
5184
+ pair: string;
5185
+ a: string;
5186
+ b: string;
5187
+ holds_all: boolean;
5188
+ holds_from: number | null;
5189
+ holds_to: number | null;
5190
+ first_break_below: WindBandBreak | null;
5191
+ first_break_above: WindBandBreak | null;
5192
+ worst_gap: { x: number; px: number; animation: string; frame: number | null };
5193
+ worst_ghost: { x: number; px: number; animation: string; frame: number | null };
5194
+ steps: WindBandStepReading[];
5195
+ }
5196
+
5197
+ /** `check.json`'s `WIND_BAND` block (issue #590): REPORTED, never a bar. */
5198
+ export interface WindBandLine {
5199
+ status: 'REPORTED';
5200
+ spec: typeof WIND_BAND_SPEC;
5201
+ path: string;
5202
+ sha256: string;
5203
+ steady_wind_only: true;
5204
+ gravity: [0, 1];
5205
+ min: number;
5206
+ max: number;
5207
+ step: number;
5208
+ steps: number[];
5209
+ fps: number;
5210
+ animations: string[];
5211
+ max_gap: number;
5212
+ max_ghost: number;
5213
+ holds_from: number | null;
5214
+ holds_to: number | null;
5215
+ pairs_holding_all: number;
5216
+ pairs: WindBandPairRow[];
5217
+ }
5218
+
5219
+ /** Planted mutants for negative controls on `WIND_BAND`. */
5220
+ export interface WindBandPlant {
5221
+ /** Mutant: ignore gap/ghost bar violations so every step is reported as holding. */
5222
+ ignoreBreaks?: boolean;
5223
+ /** Mutant: suppress per-pair breaking console lines. */
5224
+ silentPairs?: boolean;
5225
+ }
5226
+
5227
+ /**
5228
+ * Read and validate `--wind-band <spec.json>` before anything is built (issue #590).
5229
+ * Every field (`spec`, `min`, `max`, `step`, `fps`, `max_gap`, `max_ghost`, `pairs`) is
5230
+ * required; nothing falls back to `SEAM_OVER_MOTION`'s pairs, floor or fps.
5231
+ */
5232
+ export function readWindBand(given: string): WindBandSpec {
5233
+ const path = resolve(given);
5234
+ if (!existsSync(path) || !statSync(path).isFile()) {
5235
+ throw new PartsError([
5236
+ {
5237
+ code: WIND_BAND_RULE,
5238
+ object: given,
5239
+ detail: `--wind-band ${given}: nothing at ${path} — it takes a wind-band spec { "spec": "${WIND_BAND_SPEC}", ${WIND_BAND_KEYS.slice(1).map((k) => `"${k}"`).join(', ')} }`,
5240
+ },
5241
+ ]);
5242
+ }
5243
+ let bytes: Buffer;
5244
+ try {
5245
+ bytes = readFileSync(path);
5246
+ } catch (err) {
5247
+ throw new PartsError([{ code: WIND_BAND_RULE, object: given, detail: `--wind-band ${given}: not readable — ${(err as Error).message}` }]);
5248
+ }
5249
+ let raw: unknown;
5250
+ try {
5251
+ raw = JSON.parse(bytes.toString('utf8'));
5252
+ } catch (err) {
5253
+ throw new PartsError([{ code: WIND_BAND_RULE, object: given, detail: `does not parse as JSON — ${(err as Error).message}; a ${WIND_BAND_SPEC} object is required` }]);
5254
+ }
5255
+ if (!isRecord(raw)) {
5256
+ throw new PartsError([{ code: WIND_BAND_RULE, object: given, detail: `is ${Array.isArray(raw) ? 'an array' : typeof raw}; a ${WIND_BAND_SPEC} JSON object is required` }]);
5257
+ }
5258
+ const problems: Problem[] = [];
5259
+ const bad = (object: string, detail: string): void => {
5260
+ problems.push({ code: WIND_BAND_RULE, object, detail });
5261
+ };
5262
+ for (const k of Object.keys(raw)) {
5263
+ if (!(WIND_BAND_KEYS as readonly string[]).includes(k)) {
5264
+ bad(`${given} "${k}"`, `unknown key; ${WIND_BAND_SPEC} takes ${WIND_BAND_KEYS.join(', ')}`);
5265
+ }
5266
+ }
5267
+ for (const k of WIND_BAND_KEYS) {
5268
+ if (!Object.hasOwn(raw, k)) {
5269
+ bad(`${given} "${k}"`, `is missing; ${WIND_BAND_SPEC} requires every field (${WIND_BAND_KEYS.join(', ')}) and guesses none`);
5270
+ }
5271
+ }
5272
+ if (Object.hasOwn(raw, 'spec') && raw.spec !== WIND_BAND_SPEC) {
5273
+ bad(`${given} "spec"`, `is ${JSON.stringify(raw.spec)}; "${WIND_BAND_SPEC}" is required`);
5274
+ }
5275
+ const finite = (k: 'min' | 'max' | 'step'): number | null => {
5276
+ if (!Object.hasOwn(raw, k)) return null;
5277
+ const v = raw[k];
5278
+ if (typeof v !== 'number' || !Number.isFinite(v)) {
5279
+ bad(`${given} "${k}"`, `is ${JSON.stringify(v)}; a finite number is required`);
5280
+ return null;
5281
+ }
5282
+ return v;
5283
+ };
5284
+ const min = finite('min');
5285
+ const max = finite('max');
5286
+ const step = finite('step');
5287
+ const steps: number[] = [];
5288
+ if (min !== null && max !== null && min >= max) {
5289
+ bad(`${given} "min".."max"`, `min is ${min} and max is ${max}; min < max is required`);
5290
+ }
5291
+ if (step !== null && step <= 0) {
5292
+ bad(`${given} "step"`, `is ${step}; a positive number (> 0) is required`);
5293
+ }
5294
+ if (min !== null && max !== null && step !== null && min < max && step > 0) {
5295
+ const rawCount = (max - min) / step;
5296
+ const count = Math.round(rawCount);
5297
+ if (!Number.isFinite(rawCount) || Math.abs(rawCount - count) > 1e-6) {
5298
+ bad(`${given} "step"`, `(max - min) / step is ${rawCount}; an integer number of steps (within 1e-6) is required so the sweep lands on max ${max}`);
5299
+ } else if (count < 1 || count > WIND_BAND_MAX_STEPS) {
5300
+ bad(`${given} "step"`, `sweeps ${count} step(s) (${count + 1} wind points); between 1 and ${WIND_BAND_MAX_STEPS} steps is required`);
5301
+ } else {
5302
+ for (let k = 0; k <= count; k++) steps.push(k === count ? round6(max) : round6(min + k * step));
5303
+ }
5304
+ }
5305
+ if (Object.hasOwn(raw, 'fps')) {
5306
+ if (typeof raw.fps !== 'number' || !Number.isInteger(raw.fps) || raw.fps < 1) {
5307
+ bad(`${given} "fps"`, `is ${JSON.stringify(raw.fps)}; a positive integer (>= 1) is required`);
5308
+ }
5309
+ }
5310
+ for (const k of ['max_gap', 'max_ghost'] as const) {
5311
+ if (!Object.hasOwn(raw, k)) continue;
5312
+ const v = raw[k];
5313
+ if (typeof v !== 'number' || !Number.isInteger(v) || v < 0) {
5314
+ bad(`${given} "${k}"`, `is ${JSON.stringify(v)}; a non-negative integer (>= 0) is required`);
5315
+ }
5316
+ }
5317
+ const pairs: Array<{ pair: string; a: string; b: string }> = [];
5318
+ if (Object.hasOwn(raw, 'pairs')) {
5319
+ if (!Array.isArray(raw.pairs) || raw.pairs.length === 0) {
5320
+ bad(`${given} "pairs"`, `is ${JSON.stringify(raw.pairs)}; a non-empty array of "<a>|<b>" or "<a>:<b>" slot pairs is required`);
5321
+ } else {
5322
+ const seen = new Set<string>();
5323
+ raw.pairs.forEach((entry, i) => {
5324
+ const at = `${given} pairs[${i}]`;
5325
+ if (typeof entry !== 'string') {
5326
+ bad(at, `is ${JSON.stringify(entry)}; a string "<a>|<b>" or "<a>:<b>" naming two distinct slots is required`);
5327
+ return;
5328
+ }
5329
+ const m = /^([^|:]+)[|:]([^|:]+)$/.exec(entry);
5330
+ const a = m?.[1]?.trim() ?? '';
5331
+ const b = m?.[2]?.trim() ?? '';
5332
+ if (m === null || a === '' || b === '' || a !== m[1] || b !== m[2] || a === b) {
5333
+ bad(at, `is ${JSON.stringify(entry)}; "<a>|<b>" or "<a>:<b>" naming two distinct non-empty slots is required`);
5334
+ return;
5335
+ }
5336
+ const canon = a < b ? `${a}|${b}` : `${b}|${a}`;
5337
+ if (seen.has(canon)) {
5338
+ bad(at, `names "${a}|${b}", which duplicates an earlier pair in pairs`);
5339
+ return;
5340
+ }
5341
+ seen.add(canon);
5342
+ pairs.push({ pair: `${a}|${b}`, a, b });
5343
+ });
5344
+ }
5345
+ }
5346
+ refuseIfAny(problems);
5347
+ return {
5348
+ path: given,
5349
+ sha256: createHash('sha256').update(bytes).digest('hex'),
5350
+ min: min as number,
5351
+ max: max as number,
5352
+ step: step as number,
5353
+ steps,
5354
+ fps: raw.fps as number,
5355
+ max_gap: raw.max_gap as number,
5356
+ max_ghost: raw.max_ghost as number,
5357
+ pairs,
5358
+ };
5359
+ }
5360
+
5361
+ function rigAnswersWind(rig: Record<string, unknown>, motion: Record<string, unknown>): boolean {
5362
+ const constraints = Array.isArray(rig.constraints) ? rig.constraints.filter(isRecord) : [];
5363
+ for (const c of constraints) {
5364
+ if (c.type === 'physics' && typeof c.wind === 'number' && c.wind !== 0) return true;
5365
+ }
5366
+ if (isRecord(motion.physics)) {
5367
+ for (const e of Object.values(motion.physics)) {
5368
+ if (isRecord(e) && typeof e.wind === 'number' && e.wind !== 0) return true;
5369
+ }
5370
+ }
5371
+ if (isRecord(motion.animations)) {
5372
+ for (const a of Object.values(motion.animations)) {
5373
+ const tracks = isRecord(a) && Array.isArray(a.tracks) ? a.tracks.filter(isRecord) : [];
5374
+ for (const t of tracks) {
5375
+ if ('physics' in t && t.property === 'wind' && Array.isArray(t.keys) && t.keys.length > 0) return true;
5376
+ }
5377
+ }
5378
+ }
5379
+ return false;
5380
+ }
5381
+
5382
+ /**
5383
+ * Resolve every slot in `wb.pairs` against `rig.json`, check that `motion.json` holds at least one animation,
5384
+ * and check that the rig declares a wind-responsive physics constraint before `rigc build` runs (issue #590).
5385
+ */
5386
+ export function resolveWindBand(wb: WindBandSpec, inp: Pick<CheckInputs, 'rig' | 'rigPath' | 'motion' | 'motionPath'>): void {
5387
+ const problems: Problem[] = [];
5388
+ const slotList = (Array.isArray(inp.rig.slots) ? inp.rig.slots : []).filter(isRecord).map((s) => String(s.name));
5389
+ const slotSet = new Set(slotList);
5390
+ for (const p of wb.pairs) {
5391
+ const missing = [p.a, p.b].filter((n) => !slotSet.has(n));
5392
+ if (missing.length > 0) {
5393
+ problems.push({
5394
+ code: WIND_BAND_RULE,
5395
+ object: `${wb.path} pair "${p.pair}"`,
5396
+ detail: `names ${missing.map((n) => `slot "${n}"`).join(' and ')}, which ${inp.rigPath} does not have (slots: ${slotList.join(', ')})`,
5397
+ });
5398
+ }
5399
+ }
5400
+ if (!(isRecord(inp.motion.animations) && Object.keys(inp.motion.animations).length > 0)) {
5401
+ problems.push({
5402
+ code: WIND_BAND_RULE,
5403
+ object: wb.path,
5404
+ detail: `${inp.motionPath} holds no animation, so check renders no frame a wind-band sweep could pose`,
5405
+ });
5406
+ }
5407
+ if (withoutPhysics(inp.rig, inp.motion) === null) {
5408
+ problems.push({
5409
+ code: WIND_BAND_RULE,
5410
+ object: wb.path,
5411
+ detail: `${inp.rigPath} declares no physics constraint, so no wind moves anything in it`,
5412
+ });
5413
+ } else if (!rigAnswersWind(inp.rig, inp.motion)) {
5414
+ problems.push({
5415
+ code: WIND_BAND_RULE,
5416
+ object: wb.path,
5417
+ detail: `no physics constraint in ${inp.rigPath} or ${inp.motionPath} answers wind (every constraint has wind 0), so a wind sweep moves nothing in it`,
5418
+ });
5419
+ }
5420
+ refuseIfAny(problems);
5421
+ }
5422
+
5423
+ function holdingSpan(holdsAt: readonly boolean[], steps: readonly number[]): { start: number; end: number } | null {
5424
+ const runs: Array<{ start: number; end: number }> = [];
5425
+ let i = 0;
5426
+ while (i < holdsAt.length) {
5427
+ if (!holdsAt[i]) {
5428
+ i++;
5429
+ continue;
5430
+ }
5431
+ let j = i;
5432
+ while (j + 1 < holdsAt.length && holdsAt[j + 1]) j++;
5433
+ runs.push({ start: i, end: j });
5434
+ i = j + 1;
5435
+ }
5436
+ if (runs.length === 0) return null;
5437
+ const distToDefault = (r: { start: number; end: number }): number => {
5438
+ const lo = steps[r.start];
5439
+ const hi = steps[r.end];
5440
+ return 1 >= lo && 1 <= hi ? 0 : Math.min(Math.abs(1 - lo), Math.abs(1 - hi));
5441
+ };
5442
+ return [...runs].sort((a, b) => distToDefault(a) - distToDefault(b) || (b.end - b.start) - (a.end - a.start) || a.start - b.start)[0];
5443
+ }
5444
+
5445
+ /**
5446
+ * Sweep steady wind `wind: [x, 0], gravity: [0, 1]` at `t = 0` across `wb.steps` through `rigc render --seam`
5447
+ * (`--max 16`) and compute the holding band of each pair and of the rig overall (issue #590).
5448
+ */
5449
+ export function measureWindBand(
5450
+ wb: WindBandSpec,
5451
+ buildDir: string,
5452
+ scratchDir: string,
5453
+ animationNames: readonly string[],
5454
+ rigc: RigcRunner,
5455
+ plant: WindBandPlant = {},
5456
+ ): WindBandLine {
5457
+ rmSync(scratchDir, { recursive: true, force: true });
5458
+ mkdirSync(scratchDir, { recursive: true });
5459
+ const list = wb.pairs.map((p) => `${p.a}:${p.b}`).join(',');
5460
+ const seamPairs: MotionSeamPair[] = wb.pairs.map((p) => ({ ...p, declared: [wb.path] }));
5461
+ const stepRows: MotionSeamWorldRow[][] = [];
5462
+ for (let idx = 0; idx < wb.steps.length; idx++) {
5463
+ const x = wb.steps[idx];
5464
+ const schedulePath = join(scratchDir, `step_${idx}.json`);
5465
+ const renderDir = join(scratchDir, `render_${idx}`);
5466
+ writeFileSync(schedulePath, JSON.stringify({ spec: ENVIRONMENT_SPEC, steps: [{ t: 0, wind: [x, 0], gravity: [0, 1] }] }));
5467
+ const rendered = rigc(['render', '--candidate', buildDir, '--seam', list, '--fps', String(wb.fps), '--max', String(FOLD_RENDER_MAX), '--environment', schedulePath, '--out', renderDir]);
5468
+ if (rendered.status !== 0) {
5469
+ refuseIfAny(rigcFailed(`render --seam (wind-band x = ${x})`, rendered, rendered.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
5470
+ }
5471
+ const rows = readMotionSeamWorldRows(renderDir, animationNames, wb.fps, seamPairs);
5472
+ rmSync(renderDir, { recursive: true, force: true });
5473
+ if (idx === 0) {
5474
+ const unbandedProblems: Problem[] = [];
5475
+ for (const p of wb.pairs) {
5476
+ if (!rows.some((r) => r.pair === p.pair && r.status === 'read' && r.banded > 0)) {
5477
+ unbandedProblems.push({
5478
+ code: WIND_BAND_RULE,
5479
+ object: `${wb.path} pair "${p.pair}"`,
5480
+ detail: `rigc read no seam band on any frame of ${animationNames.join(', ')}; the two slots share no setup-pose alpha overlap band to measure`,
5481
+ });
5482
+ }
5483
+ }
5484
+ refuseIfAny(unbandedProblems);
5485
+ }
5486
+ stepRows.push(rows);
5487
+ }
5488
+
5489
+ const pairRows: WindBandPairRow[] = wb.pairs.map((p) => {
5490
+ const perStep = wb.steps.map((x, idx) => {
5491
+ const rows = stepRows[idx].filter((r) => r.pair === p.pair);
5492
+ let gapPx = 0;
5493
+ let gapAnim = animationNames[0] ?? 'idle';
5494
+ let gapFrame: number | null = null;
5495
+ let ghostPx = 0;
5496
+ let ghostAnim = animationNames[0] ?? 'idle';
5497
+ let ghostFrame: number | null = null;
5498
+ for (const r of rows) {
5499
+ if (r.gap.max_px > gapPx || (r.gap.max_px === gapPx && gapFrame === null && r.gap.worst !== null)) {
5500
+ gapPx = r.gap.max_px;
5501
+ gapAnim = r.animation;
5502
+ gapFrame = r.gap.worst?.index ?? null;
5503
+ }
5504
+ if (r.ghost.max_px > ghostPx || (r.ghost.max_px === ghostPx && ghostFrame === null && r.ghost.worst !== null)) {
5505
+ ghostPx = r.ghost.max_px;
5506
+ ghostAnim = r.animation;
5507
+ ghostFrame = r.ghost.worst?.index ?? null;
5508
+ }
5509
+ }
5510
+ const holds = plant.ignoreBreaks === true ? true : gapPx <= wb.max_gap && ghostPx <= wb.max_ghost;
5511
+ return { x, holds, gapPx, gapAnim, gapFrame, ghostPx, ghostAnim, ghostFrame };
5512
+ });
5513
+
5514
+ const breakAt = (idx: number): WindBandBreak => {
5515
+ const s = perStep[idx];
5516
+ const gapOver = s.gapPx - wb.max_gap;
5517
+ const ghostOver = s.ghostPx - wb.max_ghost;
5518
+ const kind: 'gap' | 'ghost' = s.gapPx > wb.max_gap && (s.ghostPx <= wb.max_ghost || gapOver >= ghostOver) ? 'gap' : 'ghost';
5519
+ return {
5520
+ x: s.x,
5521
+ kind,
5522
+ px: kind === 'gap' ? s.gapPx : s.ghostPx,
5523
+ bar: kind === 'gap' ? wb.max_gap : wb.max_ghost,
5524
+ animation: kind === 'gap' ? s.gapAnim : s.ghostAnim,
5525
+ frame: (kind === 'gap' ? s.gapFrame : s.ghostFrame) ?? 0,
5526
+ };
5527
+ };
5528
+
5529
+ const span = holdingSpan(perStep.map((s) => s.holds), wb.steps);
5530
+ const holdsAll = perStep.every((s) => s.holds);
5531
+ const worstGap = perStep.reduce((best, s) => (s.gapPx > best.gapPx ? s : best), perStep[0]);
5532
+ const worstGhost = perStep.reduce((best, s) => (s.ghostPx > best.ghostPx ? s : best), perStep[0]);
5533
+
5534
+ return {
5535
+ pair: p.pair,
5536
+ a: p.a,
5537
+ b: p.b,
5538
+ holds_all: holdsAll,
5539
+ holds_from: span === null ? null : wb.steps[span.start],
5540
+ holds_to: span === null ? null : wb.steps[span.end],
5541
+ first_break_below: span !== null && span.start > 0 ? breakAt(span.start - 1) : null,
5542
+ first_break_above: span === null ? breakAt(0) : span.end < wb.steps.length - 1 ? breakAt(span.end + 1) : null,
5543
+ worst_gap: { x: worstGap.x, px: worstGap.gapPx, animation: worstGap.gapAnim, frame: worstGap.gapFrame },
5544
+ worst_ghost: { x: worstGhost.x, px: worstGhost.ghostPx, animation: worstGhost.ghostAnim, frame: worstGhost.ghostFrame },
5545
+ steps: perStep.map((s) => ({ x: s.x, holds: s.holds, gap_max_px: s.gapPx, ghost_max_px: s.ghostPx })),
5546
+ };
5547
+ });
5548
+
5549
+ const allHoldAt = wb.steps.map((_, idx) => pairRows.every((p) => p.steps[idx].holds));
5550
+ const overallSpan = holdingSpan(allHoldAt, wb.steps);
5551
+
5552
+ return {
5553
+ status: 'REPORTED',
5554
+ spec: WIND_BAND_SPEC,
5555
+ path: wb.path,
5556
+ sha256: wb.sha256,
5557
+ steady_wind_only: true,
5558
+ gravity: [0, 1],
5559
+ min: wb.min,
5560
+ max: wb.max,
5561
+ step: wb.step,
5562
+ steps: wb.steps,
5563
+ fps: wb.fps,
5564
+ animations: [...animationNames],
5565
+ max_gap: wb.max_gap,
5566
+ max_ghost: wb.max_ghost,
5567
+ holds_from: overallSpan === null ? null : wb.steps[overallSpan.start],
5568
+ holds_to: overallSpan === null ? null : wb.steps[overallSpan.end],
5569
+ pairs_holding_all: pairRows.filter((p) => p.holds_all).length,
5570
+ pairs: pairRows,
5571
+ };
5572
+ }
5573
+
5574
+ /**
5575
+ * Console lines for `WIND_BAND` (issue #590): one summary line with the steady-wind band and the count of pairs that
5576
+ * hold throughout, plus one `WIND_BAND:` line per pair that breaks inside the swept range.
5577
+ */
5578
+ export function windBandLines(line: WindBandLine, plant: WindBandPlant = {}): string[] {
5579
+ const bandText =
5580
+ line.holds_from === null || line.holds_to === null
5581
+ ? `none of [${line.min}, ${line.max}]`
5582
+ : `[${line.holds_from}, ${line.holds_to}] of [${line.min}, ${line.max}]`;
5583
+ const summary =
5584
+ `${WIND_BAND_LINE}: ${line.status} — steady wind [x, 0], gravity [0, 1] at t = 0 over [${line.min}, ${line.max}] step ${line.step} (${line.steps.length} step(s) at ${line.fps} fps across ${line.animations.join(', ')}; bars gap <= ${line.max_gap}, ghost <= ${line.max_ghost}; steady wind only, does not measure gusts): ` +
5585
+ `band ${bandText}; ${line.pairs_holding_all}/${line.pairs.length} pair(s) hold throughout`;
5586
+ if (plant.silentPairs === true) return [summary];
5587
+ const breaking = line.pairs
5588
+ .filter((p) => !p.holds_all)
5589
+ .map((p) => {
5590
+ const pairBand = p.holds_from === null || p.holds_to === null ? 'holds nowhere' : `holds [${p.holds_from}, ${p.holds_to}]`;
5591
+ const fmtBreak = (dir: 'below' | 'above', b: WindBandBreak | null): string | null =>
5592
+ b === null ? null : `first break ${dir} at x = ${b.x} (${b.kind} ${b.px} > ${b.bar} in "${b.animation}" frame ${b.frame})`;
5593
+ const breaks = [fmtBreak('below', p.first_break_below), fmtBreak('above', p.first_break_above)].filter((s): s is string => s !== null).join('; ');
5594
+ return `${WIND_BAND_LINE}: pair "${p.pair}" — ${pairBand}; ${breaks}; worst gap ${p.worst_gap.px} at x = ${p.worst_gap.x}, worst ghost ${p.worst_ghost.px} at x = ${p.worst_ghost.x}`;
5595
+ });
5596
+ return [summary, ...breaking];
5597
+ }
5598
+
5126
5599
  /**
5127
5600
  * Run the whole check. Refuses (throws a PartsError) when the inputs are
5128
5601
  * unreadable or a rigc step that everything after it depends on is red — the
@@ -5149,7 +5622,7 @@ export function environmentLine(env: CheckEnvironment): string {
5149
5622
  * MEASURABLE is a problem. Without it nothing here reads, writes or prints
5150
5623
  * anything it did not before.
5151
5624
  */
5152
- export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, partsHome?: string, mode: PackMode = DEFAULT_PACK_MODE, source?: string, requirements?: string, seamPairsAsked = false, keepStills = false, set?: string, allSets = false, environment?: string, requirementsAs: string | undefined = requirements, config?: InputFileRecord): CheckReport {
5625
+ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, partsHome?: string, mode: PackMode = DEFAULT_PACK_MODE, source?: string, requirements?: string, seamPairsAsked = false, keepStills = false, set?: string, allSets = false, environment?: string, requirementsAs: string | undefined = requirements, config?: InputFileRecord, windBand?: string): CheckReport {
5153
5626
  let inp: CheckInputs;
5154
5627
  let reqFile: RequirementsFile | null = null;
5155
5628
  let reqRecord: RequirementsFileRecord | null = null;
@@ -5167,14 +5640,20 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
5167
5640
  };
5168
5641
  // Issue #538: the schedule is read once, first, by rigc's own reader; refused, nothing is built or written.
5169
5642
  const env = environment === undefined ? null : take(() => readCheckEnvironment(environment));
5643
+ // Issue #590: the steady-wind band spec is read and resolved before anything is built or written.
5644
+ const wb = windBand === undefined ? null : take(() => readWindBand(windBand));
5170
5645
  if (requirements === undefined) {
5171
5646
  const got = take(() => readCheckInputs(rigDir, partsHome, source, set, allSets));
5647
+ if (got !== null && wb !== null) take(() => resolveWindBand(wb, got));
5172
5648
  refuseIfAny(refused);
5173
5649
  inp = got as CheckInputs;
5174
5650
  } else {
5175
5651
  const got = take(() => readCheckInputs(rigDir, partsHome, source, set, allSets));
5176
5652
  reqFile = take(() => readRequirements(requirements));
5177
- refuseIfAny(refused);
5653
+ if (got === null || reqFile === null) {
5654
+ if (got !== null && wb !== null) take(() => resolveWindBand(wb, got));
5655
+ refuseIfAny(refused);
5656
+ }
5178
5657
  reqRecord = requirementsFileRecord(requirements, requirementsAs ?? requirements);
5179
5658
  inp = got as CheckInputs;
5180
5659
  const file = reqFile as RequirementsFile;
@@ -5189,6 +5668,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
5189
5668
  return placedArt(rec.x, rec.y, readPng(join(ready.partsDir, `${n}.png`)));
5190
5669
  }));
5191
5670
  }
5671
+ if (wb !== null) take(() => resolveWindBand(wb, ready));
5192
5672
  refuseIfAny(refused);
5193
5673
  }
5194
5674
  // Issue #538: a motion with no animation gives check no render a schedule could pose — every frame it reads would be
@@ -5215,6 +5695,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
5215
5695
  return call;
5216
5696
  };
5217
5697
  const out = resolve(outDir);
5698
+ const outExisted = existsSync(out);
5218
5699
  mkdirSync(out, { recursive: true });
5219
5700
  const buildDir = join(out, 'build');
5220
5701
  const idleDir = join(out, 'idle_frames');
@@ -5225,7 +5706,8 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
5225
5706
  const keptDir = join(out, STILL_DIR);
5226
5707
  const foldDir = join(out, FOLD_SCRATCH);
5227
5708
  const seamMotionDir = join(out, MOTION_SEAM_SCRATCH);
5228
- for (const d of [buildDir, idleDir, stillDir, isoDir, loopDir, seamDir, keptDir, join(out, 'setup_still_auto'), foldDir, seamMotionDir]) rmSync(d, { recursive: true, force: true });
5709
+ const windBandDir = join(out, WIND_BAND_SCRATCH);
5710
+ for (const d of [buildDir, idleDir, stillDir, isoDir, loopDir, seamDir, keptDir, join(out, 'setup_still_auto'), foldDir, seamMotionDir, windBandDir]) rmSync(d, { recursive: true, force: true });
5229
5711
  const written: string[] = [];
5230
5712
  const write = (name: string, data: string): void => {
5231
5713
  writeFileSync(join(out, name), data);
@@ -5275,6 +5757,22 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
5275
5757
  };
5276
5758
  const animationNames = isRecord(inp.motion.animations) ? Object.keys(inp.motion.animations) : [];
5277
5759
  const named = animationNames.filter((n) => n !== 'idle');
5760
+ // Issue #590: steady-wind seam band sweep, only under --wind-band; run before idle/still renders so a refusal
5761
+ // on an unbanded pair writes nothing.
5762
+ let windBandRead: WindBandLine | null = null;
5763
+ if (wb !== null) {
5764
+ try {
5765
+ windBandRead = measureWindBand(wb, buildDir, windBandDir, animationNames, rigc);
5766
+ } catch (err) {
5767
+ rmSync(windBandDir, { recursive: true, force: true });
5768
+ rmSync(join(out, 'gate_spine-html.txt'), { force: true });
5769
+ rmSync(buildDir, { recursive: true, force: true });
5770
+ if (!outExisted) rmSync(out, { recursive: true, force: true });
5771
+ throw err;
5772
+ } finally {
5773
+ rmSync(windBandDir, { recursive: true, force: true });
5774
+ }
5775
+ }
5278
5776
  let folds: FoldsLine | null = null;
5279
5777
  const foldProblems: Problem[] = [];
5280
5778
  // Issue #348: the feet the level line reads, off parts.json and rig.json; none, and nothing below moves.
@@ -5916,6 +6414,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
5916
6414
  ...(stripped === null || idle === null ? {} : { [CLOTH_LINE]: cloth }),
5917
6415
  RECOMPOSITE_HOLES: inp.parts === null ? { status: 'SKIP', reason: inp.noParts ?? '' } : holesLine(inp.parts),
5918
6416
  ...(sourceRead === null ? {} : { [SOURCE_LINE]: sourceRead }),
6417
+ ...(windBandRead === null ? {} : { [WIND_BAND_LINE]: windBandRead }),
5919
6418
  ...(Object.keys(skipped).length === 0 ? {} : { skipped }),
5920
6419
  ...(Object.keys(setsFigures).length === 0 ? {} : { sets: setsFigures }),
5921
6420
  ...(config === undefined ? {} : { config }),
@@ -6005,6 +6504,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
6005
6504
  motionSeam,
6006
6505
  cloth,
6007
6506
  ...(sweepSteps.size === 0 ? {} : { sweepSteps }),
6507
+ ...(windBandRead === null ? {} : { windBand: windBandRead }),
6008
6508
  };
6009
6509
  } finally {
6010
6510
  rmSync(seamMotionDir, { recursive: true, force: true });
@@ -6633,7 +7133,7 @@ function tipLine(inp: FullInputs, geometryPath: string, frames: number, problems
6633
7133
  }
6634
7134
  // Issue #349: a limb segment is rigid on its one bone and turns at its joint; it does not hang, so no tip trails a root.
6635
7135
  if (p.limb !== undefined) {
6636
- rows.push({ part: p.name, unmeasured: `a limb segment (config.limbs.${p.limb.name}), rigid on its one bone "${p.limb.bone}": it turns at its joint and does not hang, so it is not held to the bar` });
7136
+ rows.push({ part: p.name, unmeasured: p.limb.band !== undefined ? `a hybrid joint band (config.limbs.${p.limb.name}): it bends between adjacent carriers, does not hang, and is not held to a trailing-tip bar` : `a limb segment (config.limbs.${p.limb.name}), rigid on its one bone "${p.limb.bone}": it turns at its joint and does not hang, so it is not held to the bar` });
6637
7137
  continue;
6638
7138
  }
6639
7139
  const rises = excepted.rises.includes(p.name);