@rig-c/parts 1.16.0 → 1.18.0

package/src/autoamplitude.ts

@@ -22,7 +22,7 @@
  *   undeclared, which would leave both rows `not-measurable` (§8: "a pair no
  *   track declares makes both rows not-measurable"). A track moves bone `b`
  *   when a bone it keys is `b` or an ancestor of `b`: Spine bones inherit
- *   their parent's rotation and scale (the rig writes no inherit mode), so a
+ *   their parent's rotation and scale (where the rig writes no inherit mode), so a
  *   pair the track moves together — both under one keyed bone — or not at all
  *   keeps its relative linear part, θ 0 (§8: "a bone that does not move is
  *   declared with θ 0"); a pair it moves on one side only gets the track's θ.
@@ -57,6 +57,11 @@
  *   the author left it out — rig-c 2.29.0 then measures `MQ_DEFORM_LOAD`, which
  *   never read G, and reads `MQ_ALLOCATION_CONTRAST` `not-measurable` naming
  *   the gradation. No value is derived or defaulted here.
+ * - **A declared inherit mode** (issue #348): a bone between a keyed bone and
+ *   a bound one — the bound bone itself included — whose `inherit` is not
+ *   `normal` takes less than the key's rotation or scale, by its mode, so the
+ *   track's θ for that pair is not composed here: the term stops, naming the
+ *   bone and its mode, and the amplitude is not sent.
  * - **Constraints** move bones by what they solve, not by a key: a rig with
  *   any constraint is refused by name, because no declared amplitude bounds
  *   what a constraint does.
@@ -73,7 +78,7 @@ import type { MotionKey, MotionSpec } from './motion.ts';
  * — `rig.json`'s bones, `motion.json`, the config's constraints — so both build the one input `reductionKey` matches.
  */
 export interface AmplitudeBasis {
-  bones: ReadonlyArray<{ name: string; parent?: string }>;
+  bones: ReadonlyArray<{ name: string; parent?: string; inherit?: string }>;
   motion: MotionSpec;
   constraints: number;
 }
@@ -133,7 +138,7 @@ export type AmplitudeDerivation = { amplitude: MotionAmplitude } | { stops: Ampl
  * reason to stop (rig-c 2.29.0 admits null).
  */
 export function deriveMotionAmplitude(args: {
-  bones: ReadonlyArray<{ name: string; parent?: string }>;
+  bones: ReadonlyArray<{ name: string; parent?: string; inherit?: string }>;
   motion: MotionSpec;
   constraints: number;
   bound: readonly string[];
@@ -142,6 +147,13 @@ export function deriveMotionAmplitude(args: {
 }): AmplitudeDerivation {
   const stops: AmplitudeStop[] = [];
   const parent = new Map(args.bones.map((b) => [b.name, b.parent ?? null]));
+  const mode = new Map(args.bones.filter((b) => b.inherit !== undefined && b.inherit !== 'normal').map((b) => [b.name, b.inherit as string]));
+  /** The bones from `bone` up to `k`, `k` left out, that declare an inherit mode other than normal (issue #348). */
+  const declared = (bone: string, k: string): string[] => {
+    const out: string[] = [];
+    for (let b: string | null = bone; b !== null && b !== k; b = parent.get(b) ?? null) if (mode.has(b)) out.push(b);
+    return out;
+  };
   const under = (bone: string, k: string): boolean => {
     for (let b: string | null = bone; b !== null; b = parent.get(b) ?? null) if (b === k) return true;
     return false;
@@ -159,6 +171,14 @@ export function deriveMotionAmplitude(args: {
     const name = `${t.bone ?? t.group ?? '?'}.${t.property}#${i}`;
     const moverOf = (b: string): string[] => keyed.filter((k) => under(b, k));
     if (!bound.some((b) => moverOf(b).length > 0)) return;
+    const through = [...new Set(bound.flatMap((b) => moverOf(b).flatMap((k) => declared(b, k))))];
+    if (through.length > 0) {
+      stops.push({
+        term: `tracks[${name}].pairs[].theta`,
+        detail: `the track keys [${keyed.join(', ')}], and ${through.map((b) => `"${b}" declares inherit "${mode.get(b)}"`).join(', ')} below it, so what the key does to the bones under it is not the key's own rotation or scale; θ is composed here only through bones that inherit normally, and none is invented`,
+      });
+      return;
+    }
     const th = trackTheta(t.property, t.keys);
     if ('refused' in th) {
       stops.push({ term: `tracks[${name}].pairs[].theta`, detail: th.refused });

package/src/autoenvelope.ts

@@ -58,7 +58,10 @@
  *   setup by; an unkeyed property is [0, 0], [1, 1] or 0. `pivot` is the
  *   bone's setup joint in the part's drawing frame (crop px less the part's
  *   padded origin, y down). `setup` is the rig's as written: this package
- *   writes no bone scale, shear or inherit mode, so `{ 1, 1, 0, 0, 'normal' }`.
+ *   writes no bone scale or shear, so `{ 1, 1, 0, 0, 'normal' }` — with the
+ *   bone's own `inherit` where config.bones declares one (issue #348), handed
+ *   to rig-c as written, which refuses any mode but `normal` by name
+ *   (`SKINNING_RANGE_UNSUPPORTED`): the residual is then not measurable.
  *   A shear key has no field in `BoneMotionRange`, so a bone keyed by one
  *   makes the residual not measurable (`ENVELOPE_SHEAR_KEYED`); a property
  *   the idle writes and none of the above names is refused the same way.
@@ -86,7 +89,7 @@ import { edgeLength } from './length.ts';
 
 /** What the derivation reads off the rig besides the part: the bones (name, parent), each bone's setup joint in crop px, the idle as written, the constraints. */
 export interface EnvelopeBasis {
-  bones: ReadonlyArray<{ name: string; parent?: string }>;
+  bones: ReadonlyArray<{ name: string; parent?: string; inherit?: string }>;
   joints: ReadonlyMap<string, readonly [number, number]>;
   motion: MotionSpec;
   constraints: readonly ConfigConstraint[];
@@ -105,8 +108,11 @@ export type EnvelopeDerivation = { envelope: SkinningEnvelope } | { stops: Envel
 /** Where a range comes from: the bone's keys, or the kind of the constraint that drives it — which rig-c refuses by name. */
 type RangeSource = 'keys' | 'ik' | 'transform' | 'path' | 'physics';
 
-/** A `BoneMotionRange` whose `source` may name a constraint kind: rig-c reads `source` at run time and certifies `'keys'` alone. */
-type DeclaredRange = Omit<BoneMotionRange, 'source'> & { source: RangeSource };
+/**
+ * A `BoneMotionRange` whose `source` may name a constraint kind, and whose `setup.inherit` may name a declared mode
+ * (issue #348): rig-c reads both at run time and certifies `'keys'` and `'normal'` alone.
+ */
+type DeclaredRange = Omit<BoneMotionRange, 'source' | 'setup'> & { source: RangeSource; setup: Omit<BoneMotionRange['setup'], 'inherit'> & { inherit: string } };
 
 /**
  * rig-c's helper over ranges whose `source` may be a constraint kind. rig-c's type admits only the one value it
@@ -136,6 +142,12 @@ function trackValues(keys: readonly MotionKey[]): number[] {
 
 const SETUP: BoneMotionRange['setup'] = { scaleX: 1, scaleY: 1, shearX: 0, shearY: 0, inherit: 'normal' };
 
+/** The bone's declared inherit mode as the rig writes it (issue #348), or nothing, so {@link SETUP}'s `normal` stands. */
+function inheritOf(basis: EnvelopeBasis, bone: string): { inherit: string } | Record<string, never> {
+  const mode = basis.bones.find((b) => b.name === bone)?.inherit;
+  return mode === undefined ? {} : { inherit: mode };
+}
+
 /** One bone's declared range off the idle, or the stop that names why it has none. */
 export function boneRange(basis: EnvelopeBasis, bone: string, origin: readonly [number, number], driven: ReadonlyMap<string, RangeSource>): DeclaredRange | EnvelopeStop {
   const joint = basis.joints.get(bone);
@@ -170,7 +182,7 @@ export function boneRange(basis: EnvelopeBasis, bone: string, origin: readonly [
     scaleX,
     scaleY,
     translate: edgeLength(tx, ty),
-    setup: { ...SETUP },
+    setup: { ...SETUP, ...inheritOf(basis, bone) },
   };
 }
 

package/src/build.ts

@@ -43,7 +43,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { type AnimFrame, EncodeError, encodeApng, encodeIndexedApng, INDEXED_DEFAULTS } from './apng.ts';
-import { assemble, type AssembleResult, cutLines, driftLine, FIGURE_MASK_FILE, figuresLine, holeLines, type ProjectRule, scenePhrase, type SeamRule, stageFields, uncoveredLine } from './assemble.ts';
+import { assemble, type AssembleResult, cutLines, hiddenLines, SINGLE_RUN_FACE_TAGS, driftLine, limbLines, FIGURE_MASK_FILE, figuresLine, holeLines, type ProjectRule, scenePhrase, type SeamRule, stageFields, uncoveredLine } from './assemble.ts';
 import { allocationClause, type Reducer, stageBClause, unboundedClause } from './automesh.ts';
 import { residualClause } from './autoenvelope.ts';
 import { type AutoMotionCase, failingRows, idleSchedule, localRow, motionClause, motionDeformation, motionDocument, motionInput, motionRowText, motionStimulus, motionVerdict, noStimulusProblem, type ReplayCandidate, runComparison, sourceSelfFailure, stimulusMotion, withStimulus } from './automotion.ts';
@@ -70,15 +70,15 @@ import {
   splitSchedule,
   untestedIntervals,
 } from './autoreplay.ts';
-import { besideIdleLine, FOLD_LINE, type FoldsLine, buildGateLines, causeLines, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, type PageEdges, readFrameSet, rigcFailed, rigcIdentity, rigcRanClause, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR } from './check.ts';
-import { type Cut, loadConfig, loadConfigAndAnimations, loadEarlyConfig } from './config.ts';
+import { besideIdleLine, FOLD_LINE, type FoldsLine, LEVEL_LINE, type LevelLine, LIMB_LINE, type LimbLine, STRESS_LINE, buildGateLines, causeLines, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, type PageEdges, readFrameSet, rigcFailed, rigcIdentity, rigcRanClause, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR } from './check.ts';
+import { type Cut, type Limb, loadConfig, loadConfigAndAnimations, loadEarlyConfig } from './config.ts';
 import { failLine, PartsError, type Problem, refuseIfAny } from './errors.ts';
 import type { MeshQualityReport, MotionSchedule } from 'rig-c/mesh';
 import { encodeGif } from './gif.ts';
 import { CONTROL_SUFFIX, withAnimations } from './motion.ts';
 import type { PaletteError } from './palette.ts';
 import { type LayerSet, readLayers } from './layers.ts';
-import { type PartRecord, readParts, tagOf, writeParts } from './parts.ts';
+import { type PartRecord, readParts, type SingleRunPad, tagOf, writeParts } from './parts.ts';
 import { encodePngBytes, readPng, writePng } from './raster/png.ts';
 import type { Raster } from './raster/types.ts';
 import { readRequirements, type RequirementLine, summaryText } from './requirements.ts';
@@ -106,8 +106,12 @@ export function readSource(path: string): Raster {
   }
 }
 
-/** Read both runs, collecting the refusals of both before throwing. */
-export function readRuns(full: string, head: string): { full: LayerSet; head: LayerSet } {
+/**
+ * Read both runs, collecting the refusals of both before throwing. With no
+ * head run (`head` null, issue #359) the full run is read once and stands for
+ * both, and `single` says so: the stage then holds it to `checkSingleRun`.
+ */
+export function readRuns(full: string, head: string | null): { full: LayerSet; head: LayerSet; single: boolean } {
   const problems: Problem[] = [];
   const one = (path: string): LayerSet | null => {
     try {
@@ -121,15 +125,16 @@ export function readRuns(full: string, head: string): { full: LayerSet; head: La
     }
   };
   const f = one(full);
-  const h = one(head);
+  const h = head === null ? f : one(head);
   if (problems.length > 0) throw new PartsError(problems);
-  return { full: f as LayerSet, head: h as LayerSet };
+  return { full: f as LayerSet, head: h as LayerSet, single: head === null };
 }
 
 export interface AssembleStageInput {
   source: string;
   full: string;
-  head: string;
+  /** The head run, or null for one run that holds the face (issue #359). */
+  head: string | null;
   config: string;
   seam: SeamRule;
   project: ProjectRule;
@@ -200,15 +205,46 @@ export function readUnders(configPath: string, cuts: readonly Cut[]): Array<Rast
   return out;
 }
 
+/**
+ * Each limb segment's `cap` image (issue #349), read from its path relative to
+ * the config's directory and keyed `<limb>/<segment index>`. Every one is read
+ * before one refusal names them all: no such file
+ * (`ASSEMBLE_LIMB_CAP_PRESENT`), or a file that does not decode as a PNG
+ * (`ASSEMBLE_LIMB_CAP_DECODES`). The stage holds the image to the cap's box.
+ */
+export function readCaps(configPath: string, limbs: Readonly<Record<string, Limb>>): Map<string, Raster> {
+  const problems: Problem[] = [];
+  const out = new Map<string, Raster>();
+  for (const [l, limb] of Object.entries(limbs)) {
+    limb.segments.forEach((sg, k) => {
+      if (sg.cap === undefined) return;
+      const file = resolve(dirname(resolve(configPath)), sg.cap);
+      const object = `config.limbs.${l}.segments[${k}].cap (part "${sg.part}")`;
+      if (!existsSync(file) || !statSync(file).isFile()) {
+        problems.push({ code: 'ASSEMBLE_LIMB_CAP_PRESENT', object, detail: `names ${file}, which is no such file; a PNG of the cap, its path relative to the config's directory, is required` });
+        return;
+      }
+      try {
+        out.set(`${l}/${k}`, readPng(file));
+      } catch (err) {
+        problems.push({ code: 'ASSEMBLE_LIMB_CAP_DECODES', object, detail: `${file}: ${(err as Error).message.split('\n')[0]}; a PNG is required` });
+      }
+    });
+  }
+  refuseIfAny(problems);
+  return out;
+}
+
 /** Read, assemble, and write only after every refusal has had its chance. Throws a PartsError on a refusal, having written nothing. */
 export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs, log: Log): AssembleResult {
   const src = readSource(input.source);
   const runs = readRuns(input.full, input.head);
   // The early door: assemble runs before propose has drafted bones, meshes,
   // regions and motion, so it requires only what it reads (issue #20).
-  const fields = stageFields(loadEarlyConfig(input.config, 'assemble'));
+  const fields = stageFields(loadEarlyConfig(input.config, 'assemble'), runs.single ? { w: src.width, h: src.height } : null);
   const under = readUnders(input.config, fields.cuts);
-  const result = assemble({ source: src, full: runs.full, head: runs.head, ...fields, under, seamRule: input.seam, projectRule: input.project });
+  const caps = fields.limbs === undefined ? undefined : readCaps(input.config, fields.limbs);
+  const result = assemble({ source: src, full: runs.full, head: runs.head, ...fields, under, ...(caps === undefined ? {} : { caps }), seamRule: input.seam, projectRule: input.project });
   // Emit only after green: every refusal above has already thrown.
   mkdirSync(outs.partsDir, { recursive: true });
   mkdirSync(dirname(outs.partsJson), { recursive: true });
@@ -223,6 +259,11 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   if (figurePath !== null) writePng(figurePath, result.figure as Raster);
   const [W, H] = result.parts.rig_size;
   log(`rig-parts assemble: ${result.images.length} part(s) on a ${W}x${H} rig (${result.parts.scale_rig_per_source} rig px per source px), seam rule ${result.seamRule}, projection rule ${result.projectRule}`);
+  // Issue #359: one run, said, so a reader of the lines knows no head run was placed.
+  if (runs.single) log(`  one run: ${input.full} holds the face (${SINGLE_RUN_FACE_TAGS.join(', ')}), so no head run is read; every part comes from the full run`);
+  // Issue #366: a file that is not the resolution square was padded to it; said, with where parts.json records it. None for a square file.
+  const pad = result.parts.single_run_pad;
+  if (pad !== undefined) log(singleRunPadLine(input.full, pad));
   for (const p of result.parts.parts) {
     log(
       `  ${p.name.padEnd(11)} ${p.from.padEnd(16)} ${`${p.w}x${p.h}`.padEnd(9)} @${String(p.x).padStart(4)},${String(p.y).padStart(4)} ` +
@@ -234,7 +275,11 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   for (const l of authorPartLines(result.parts.parts)) log(l);
   // One line per plan part an assemble.cuts entry cut, before the fringe lines: the cut is made first. None without cuts.
   for (const l of cutLines(result.cuts)) log(l);
+  // Issue #349: one line per part a limb took, and one per joint with its cap's pixels. None without limbs.
+  for (const l of limbLines(result.limbs)) log(l);
   for (const l of fringeLines(result.parts.parts)) log(l);
+  // Issue #359: one line per hidden-art layer and what read it. None without one.
+  for (const l of hiddenLines(result.hidden)) log(l);
   const total = (k: 'opaque_px' | 'visible_px' | 'occluded_px' | 'source_px_taken' | 'visible_not_projected_px'): number => result.parts.parts.reduce((a, p) => a + (p[k] ?? 0), 0);
   const [op, vis, occ, taken, unproj] = (['opaque_px', 'visible_px', 'occluded_px', 'source_px_taken', 'visible_not_projected_px'] as const).map(total);
   const pct = (n: number): string => `${((100 * n) / op).toFixed(1)}%`;
@@ -253,6 +298,16 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   return result;
 }
 
+/**
+ * The line `assemble` prints under `one run:` when the file was padded (issue
+ * #366): its size, the square and the four margins, and that `parts.json`'s
+ * `single_run_pad` records them.
+ */
+export function singleRunPadLine(file: string, pad: SingleRunPad): string {
+  const [w, h] = pad.file_size;
+  return `  padded: ${file} is ${w}x${h}, centred on the ${pad.side}x${pad.side} run square (left ${pad.left}, right ${pad.side - w - pad.left}, top ${pad.top}, bottom ${pad.side - h - pad.top}); parts.json single_run_pad records it, and every part's box is in the file's pixels times scale_rig_per_source`;
+}
+
 /**
  * The scale the per-part line prints `drift=` with (issue #314): `refused_drift_px` counts the part's projection
  * candidates (`projected_core_px`, the `src=` column's second figure) refused because See-through's colour sits more
@@ -1046,6 +1101,40 @@ export function foldsLines(line: FoldsLine): string[] {
   return [head, ...line.folding.map((r) => `  folds  ${r.line}${r.declared === null ? '' : ` — declared in may_fold: ${r.declared}`}`)];
 }
 
+/**
+ * The feet-level line (issue #348) as the console prints it: the status, what was read, the bar and whose it is, then
+ * each foot on a line of its own — its bone, what that hangs from, how many frames posed it, and the worst turn with
+ * the bone that was turned and the bones it came through. A SKIP prints its reason.
+ */
+export function levelLines(line: LevelLine): string[] {
+  const physics = line.physics_left_out === 0 ? '' : `, its ${line.physics_left_out} physics constraint(s) left out`;
+  const read = `${line.animations.length} animation(s) read by rigc render --folds --geometry at ${line.fps} fps${physics} (${line.animations.join(', ')})`;
+  const head =
+    line.status === 'SKIP'
+      ? `${LEVEL_LINE}: SKIP — ${String(line.reason)}; ${read}`
+      : `${LEVEL_LINE}: ${line.status} — ${read}: each foot's drawing within ±${line.bar_degrees} degrees of its setup pose while a bone above it is turned, ${line.bar}`;
+  return [
+    head,
+    ...line.feet.map((f) => {
+      const at = `foot  "${f.part}" on "${f.bone}" (hangs from "${f.hangs_from}"): ${f.status}, ${f.frames_posed} posed frame(s)`;
+      if (f.worst === null) return `${at}, so nothing was measured`;
+      const w = f.worst;
+      return `${at}; worst ${w.degrees} degrees in "${w.animation}" frame ${w.frame} (t = ${w.time}s), "${w.turned}" turned ${w.turned_degrees}, through ${w.through.map((x) => `${x.bone} (inherit ${x.inherit})`).join(', ')}`;
+    }),
+  ];
+}
+
+/**
+ * The limb line (issue #349) as the console prints it: the status and the bar, then each limb part on a line of its
+ * own — its limb, its bone, and on a FAIL every other bone it is bound to.
+ */
+export function limbCheckLines(line: LimbLine): string[] {
+  return [
+    `${LIMB_LINE}: ${line.status} — ${line.parts.length} limb part(s), each bound in rig.json to its one bone with weight 1 (a region on it, or a mesh weighted to it alone)`,
+    ...line.parts.map((r) => `limb  "${r.part}" (${r.limb}) on "${r.bone}": ${r.status}${r.others.length === 0 ? '' : `, also weighted to ${r.others.map((b) => `"${b}"`).join(', ')}`}`),
+  ];
+}
+
 /** A requirement's line as the console prints it: its name and status, the reason first when NOT MEASURABLE, then its figures as check.json holds them. */
 export function requirementText(name: string, line: RequirementLine): string {
   const rest = Object.entries(line).filter(([k]) => k !== 'status' && k !== 'reason');
@@ -1072,7 +1161,7 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   if (r.idle === null) log(`  loop: SKIP — ${fig.skipped?.loop ?? ''}`);
   else log(`  ${loopCheckLine(r.idle, fig.loop_max_diff, fig.loop_physics?.length ?? 0)}`);
   if (r.loopPhysics !== null) log(`  ${r.loopPhysics}`);
-  const beside = besideIdleLine(r.besideIdle);
+  const beside = besideIdleLine(r.besideIdle, r.figures[LEVEL_LINE] !== undefined);
   if (beside !== null) log(`  ${beside}`);
   if (r.seamViewport === null || fig.seam_mean === null) log(`  seam: SKIP — ${fig.skipped?.seam ?? ''}`);
   else {
@@ -1086,6 +1175,12 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   for (const name of JUDGEMENT_LINES) log(`  ${judgementLine(name, fig[name])}`);
   const folds = fig[FOLD_LINE];
   if (folds !== undefined) for (const l of foldsLines(folds)) log(`  ${l}`);
+  const level = fig[LEVEL_LINE];
+  if (level !== undefined) for (const [i, l] of levelLines(level).entries()) log(`  ${i === 0 ? '' : '  '}${l}`);
+  const stress = fig[STRESS_LINE];
+  if (stress !== undefined) log(`  ${judgementLine(STRESS_LINE, stress)}`);
+  const limbs = fig[LIMB_LINE];
+  if (limbs !== undefined) for (const [i, l] of limbCheckLines(limbs).entries()) log(`  ${i === 0 ? '' : '  '}${l}`);
   for (const name of REPORTED_LINES) log(`  ${judgementLine(name, fig[name])}`);
   const vsSource = fig[SOURCE_LINE];
   if (vsSource !== undefined) log(`  ${judgementLine(SOURCE_LINE, vsSource)}`);
@@ -1348,7 +1443,8 @@ export interface BuildInput {
   config: string;
   source: string;
   full: string;
-  head: string;
+  /** The head run, or null for one run that holds the face (issue #359). */
+  head: string | null;
   out: string;
   seam: SeamRule;
   project: ProjectRule;