@rig-c/parts 1.7.0 → 1.9.0

package/src/propose.ts

@@ -29,7 +29,10 @@
  *   midline, split at the eye axis — unless the blob is clasped hands (at the
  *   axis and at most half the shoulders' width), which ride `hip` as a region.
  * - `front hair` -> three fringe chains + one lock chain per strand that hangs
- *   0.3 face heights below the chin.
+ *   0.3 face heights below the chin. The fringe chains are the reference's
+ *   template turned into the head's frame (issue #249): columns along the
+ *   eye line's perpendicular ({@link headRollOf}), each rooted on the part's
+ *   own art, and a note saying they are a template, not the part's locks.
  * - `back hair` -> one `bun` bone if it ends above the shoulders, else two
  *   hanging chains.
  * - `headwear` / `earwear` -> the biggest layer of the tag gets a rigid bone
@@ -87,6 +90,18 @@
  * end of the trunk (issue #243), the trunk parts' fixed segments run along
  * neck -> hip, the line the chest is placed on, instead of down the screen
  * ({@link trunkLineOf}).
+ * One departure moves every published proposal, the reference's own two
+ * included (issue #249): the reference stood the fringe's three columns on
+ * the page and rooted them 13 px below the part's box, which on a tilted head
+ * put them on a hat above the hair and across the locks; here they stand in
+ * the head's frame and are rooted 13 px below the art on each column, and
+ * `lint` names a fringe link that does not lean with the head.
+ *
+ * The idle departs from the reference's too (issue #252): it is
+ * {@link IDLE_FRAMES} frames at 12 fps rather than 4 s, every period scaled
+ * with it, and the chest's breath travels {@link BREATH_FRACTION} of the torso
+ * part's height ({@link breathTrack}) rather than a fixed 1.3 px amplitude, so
+ * no tracked proposal is the reference's output any more in its `motion`.
  *
  * Issue #86 adds what the proposer and lint looked at, and changes nothing
  * they wrote: {@link proposeWithBasis} records, at each placement, what the
@@ -101,7 +116,8 @@ import { join } from 'node:path';
 import { drawText, GLYPH_H } from 'rig-c/tools/font5x7.ts';
 import { type BoneEntry, type ConfigConstraint, type MeshSpec, parseConfig, type Point, type Segment, type SkeletonSections } from './config.ts';
 import { PartsError, type Problem, refuseIfAny } from './errors.ts';
-import { OPAQUE_ALPHA_ABOVE } from './layers.ts';
+import { eyeLineDegrees, type FrameFeature, headAxes, type HeadAxes, headFrame, type HeadFrame } from './headframe.ts';
+import { type LayerSet, OPAQUE_ALPHA_ABOVE } from './layers.ts';
 import { PAINTING_RUN, type PartRecord, type PartsFile, readParts } from './parts.ts';
 import { connectedComponents } from './raster/components.ts';
 import { dilate, morphGradient } from './raster/morph.ts';
@@ -110,8 +126,11 @@ import { resize } from './raster/resize.ts';
 import { type Mask, newMask, newRaster, type Raster } from './raster/types.ts';
 import { npMean, npMedian, npPercentile, pyFixed, pyInt, pyIntList, pyRepr, pyRound, pyStrList } from './pyfmt.ts';
 import type { JointState, RigJoint, RigJoints } from './keypoints.ts';
+import { IDLE_FPS } from './motion.ts';
+import { pyRound as roundTo } from './round.ts';
 import { KEYPOINT_NAMES, type KeypointName } from './skeleton.ts';
 import { configRoles, type RoleOf } from './structure.ts';
+import { TURN_BONE, turnFractions, turnNearest, turnPivot, type TurnSpec } from './turn.ts';
 
 // ---------------------------------------------------------------------------
 // the output shape — config-shaped, key order as the reference writes it
@@ -149,6 +168,41 @@ export const EYE_GROUP_TAGS: readonly string[] = ['eyewhite-r', 'eyewhite-l'];
 /** The tags whose parts make the brow bones, the blink's `brows` group. */
 export const BROW_GROUP_TAGS: readonly string[] = ['eyebrow-r', 'eyebrow-l'];
 
+/**
+ * The drafted idle's length, in frames at {@link IDLE_FPS} (issue #252): 40
+ * frames, 40/12 s. The reference drafted a 4 s idle; HQ calibrated the breath
+ * over 40 frames at 12 fps, and a duration of a whole number of frames is what
+ * `check`'s loop compares frame 0 with (issue #244).
+ */
+export const IDLE_FRAMES = 40;
+/** {@link IDLE_FRAMES} in seconds: 3.3333333333333335 as a double, the time rigc's last frame is read at within `TIME_SLACK`. */
+export const IDLE_SECONDS = IDLE_FRAMES / IDLE_FPS;
+/**
+ * The idle the reference drafted, in seconds. Every drafted track's period is
+ * written against it (4 s: one cycle per idle; 2 s: two) and scaled by
+ * `IDLE_SECONDS / REFERENCE_IDLE_SECONDS` when the proposal is returned, so
+ * each keeps its number of cycles per idle — the loader refuses a period that
+ * does not divide the idle (`CONFIG_PERIOD_DIVIDES_DURATION`). The scale is
+ * 10/12 = 0.8333333333333334, and 4 and 2 times it are 40/12 and 20/12 to the
+ * last bit, since only a power of two multiplies it.
+ */
+export const REFERENCE_IDLE_SECONDS = 4;
+/**
+ * The breath's travel, peak to peak, as a fraction of the torso part's height
+ * (issue #252). The size is the height because the breath is a `translatey`:
+ * its travel is read along y, against the part's extent along y. HQ's
+ * calibration: about 2.5 %. On the trailer's seated character the torso part
+ * (`topwear`) is 267 px tall and the reference's fixed 2.6 px peak to peak
+ * (amplitude 1.3, the base 1.3 so the chest rises from its setup pose and
+ * returns) was 0.97 % of it, read by its owner as a still paper doll; the
+ * production scene rig that replaced it breathes 6.4 px, 2.4 %.
+ */
+export const BREATH_FRACTION = 0.025;
+/** The breath's amplitude the reference drafted on every figure, kept only where there is no torso part to scale by. */
+export const REFERENCE_BREATH_AMP = 1.3;
+/** The See-through tag of the torso part, whose height the breath is a fraction of. */
+export const BREATH_SIZE_TAG = 'topwear';
+
 export interface Proposal {
   bones: BoneEntry[];
   meshes: Record<string, MeshSpec>;
@@ -159,6 +213,8 @@ export interface Proposal {
     /** Absent when no part feeds the `eyes` group ({@link EYE_GROUP_TAGS}): a blink with nothing to blink is not written. */
     blink?: ProposedBlink;
   };
+  /** Only with `propose --full`/`--head` (issue #251, {@link draftTurn}); absent otherwise, so a proposal without them is the one written before it. */
+  turn?: TurnSpec;
   notes: string[];
 }
 
@@ -315,6 +371,7 @@ export function checkProposal(P: PartSet, p: Proposal): void {
     meshes: p.meshes,
     regions: p.regions,
     motion: p.motion,
+    ...(p.turn === undefined ? {} : { turn: p.turn }),
   });
 }
 
@@ -323,6 +380,98 @@ export function serializeProposal(p: Proposal): string {
   return `${JSON.stringify(p, null, 2)}\n`;
 }
 
+// ---------------------------------------------------------------------------
+// the turn control (issue #251)
+// ---------------------------------------------------------------------------
+
+/** The See-through runs `propose --full/--head` reads depths from, by run. */
+export type TurnRuns = Partial<Record<'full' | 'head', LayerSet>>;
+
+/**
+ * Draft `turn` (issue #251, `src/turn.ts`) from the parts and the See-through
+ * runs they came from: each part's depth is its layer's `depth_median` — the
+ * layer of its run named by its tag, a cut's piece its base's — and the pivot
+ * is {@link turnPivot} over the parts' `opaque_px`. A `painting:` patch has no
+ * layer and so no depth: it is not carried, and a note names it. What a depth
+ * cannot be read for is refused by name, every one at once:
+ *
+ * - `PROPOSE_TURN_RUN_GIVEN`: a part from a run whose layers were not given.
+ * - `PROPOSE_TURN_LAYER_PRESENT`: the run given holds no layer of the part's tag.
+ * - `PROPOSE_TURN_DEPTH_PRESENT`: the layer carries no depth (a PSD carries none).
+ *
+ * With no part to carry, or every carried part at one depth (nothing nearer
+ * than the pivot), no `turn` is drafted and a note says why. Otherwise one note
+ * states the pivot and its rule, the law, and every part's fraction with the
+ * depth it came from.
+ */
+export function draftTurn(P: PartSet, runs: TurnRuns): { turn: TurnSpec | null; notes: string[] } {
+  const problems: Problem[] = [];
+  const rows: Array<{ part: string; depth: number; area: number }> = [];
+  const patches: string[] = [];
+  const unread = new Map<string, string[]>();
+  for (const r of P.recs) {
+    const [run, tag] = splitFrom(r.from);
+    if (run === PAINTING_RUN) {
+      patches.push(r.name);
+      continue;
+    }
+    const set = run === 'full' || run === 'head' ? runs[run] : undefined;
+    if (set === undefined) {
+      unread.set(run, [...(unread.get(run) ?? []), r.name]);
+      continue;
+    }
+    const layer = set.layers.find((l) => l.name === tag);
+    if (layer === undefined) {
+      problems.push({ code: 'PROPOSE_TURN_LAYER_PRESENT', object: `part "${r.name}" (${r.from})`, detail: `came from the ${run} run's "${tag}" layer, and ${set.source} holds no layer of that name; the run its parts were assembled from is required` });
+      continue;
+    }
+    if (layer.depth === null) {
+      problems.push({ code: 'PROPOSE_TURN_DEPTH_PRESENT', object: `part "${r.name}" (${r.from})`, detail: `its layer in ${set.source} carries no depth_median (a ${set.form} input); the turn orders parts by See-through's per-layer depth, so a run that carries one is required` });
+      continue;
+    }
+    rows.push({ part: r.name, depth: layer.depth, area: r.opaque_px });
+  }
+  for (const [run, names] of unread) {
+    problems.push({ code: 'PROPOSE_TURN_RUN_GIVEN', object: `the ${run} run`, detail: `part(s) ${names.map((n) => `"${n}"`).join(', ')} came from it and its layers were not given; --${run} <dir | layers.json> is required to read their depth` });
+  }
+  refuseIfAny(problems);
+  const notes: string[] = [];
+  if (patches.length > 0) {
+    notes.push(`turn: painting patch(es) ${patches.map((n) => `"${n}"`).join(', ')} carry no See-through depth and are not carried — each moves only as its bone does, as the pivot depth does; a value in config.turn.depths carries one`);
+  }
+  const pivot = turnPivot(rows);
+  const depths = Object.create(null) as Record<string, number>;
+  for (const r of rows) depths[r.part] = r.depth;
+  const nearest = turnNearest(depths);
+  if (pivot === null || nearest === null) {
+    notes.push('turn: no part carries a See-through depth with any opaque pixel, so no turn control is drafted');
+    return { turn: null, notes };
+  }
+  if (!(pivot > nearest.depth)) {
+    notes.push(`turn: every carried part lies at depth ${nearest.depth}, so none is nearer than the pivot and no turn control is drafted`);
+    return { turn: null, notes };
+  }
+  const turn: TurnSpec = { pivot, depths };
+  const fr = turnFractions(turn, rows.map((r) => r.part));
+  notes.push(
+    `turn: control "${TURN_BONE}" under root, keyed by nothing — its x is the dial. Pivot depth ${pivot}: the mean of the ${rows.length} carried parts' See-through depth_median weighted by opaque_px, the one depth at which the painted pixels' centroid does not slide (correct it in turn.pivot). ` +
+      `Each part travels (pivot - depth) / (pivot - ${nearest.depth}) of the control's x, "${nearest.part}" (nearest) all of it: ${fr.map((f) => `${f.part} ${f.fraction} (depth ${f.depth})`).join(', ')}`,
+  );
+  notes.push(...TURN_DEPTH_CAVEAT);
+  return { turn, notes };
+}
+
+/** The notes beside every drafted turn (issue #251): what a See-through depth is, where it misleads, and that the two runs' axes are not reconciled. */
+export const TURN_DEPTH_CAVEAT: readonly string[] = [
+  "turn: depth is the See-through layer's median and each part takes its own run's axis; a seated or forward-reaching limb can read further back than it is (trailer legwear 0.770 sits behind the pivot)",
+  "turn: the two runs' depth axes are not reconciled (parts#271)",
+];
+
+/** The proposal with `turn` written after `motion` and `notes` extended; the proposal itself when `turn` is null. */
+export function withTurn(p: Proposal, draft: { turn: TurnSpec | null; notes: string[] }): Proposal {
+  return { bones: p.bones, meshes: p.meshes, regions: p.regions, motion: p.motion, ...(draft.turn === null ? {} : { turn: draft.turn }), notes: [...p.notes, ...draft.notes] };
+}
+
 // ---------------------------------------------------------------------------
 // the parts, as masks
 // ---------------------------------------------------------------------------
@@ -1072,6 +1221,9 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
       B('mouth', 'head', [cc.stats[best].cx, cc.stats[best].cy], placement('mask', `the centroid of the biggest 8-connected blob of ${mouth[0].name}`, { parts: [mouth[0].name] }));
     } else B('mouth', 'head', center(mouth[0]), placement('mask', `the centre of ${mouth[0].name}'s box`, { parts: [mouth[0].name], fallback: 'its mask has no opaque pixel, so no blob' }));
   }
+  // Issue #250: the head's frame, read off the head run once, written as notes. The bar is the line through the eye
+  // bones' origins as written here: the one roll the rig turns the face bones to (src/headframe.ts).
+  notes.push(...headFrameNotes(P, bones));
   // An eye bone comes only from an eyewhite (EYE_GROUP_TAGS). An iris or a
   // lash on a side with none has no eye bone to ride, and writing its region
   // as `eye_<s>` anyway named a bone that does not exist — refused by the
@@ -1118,8 +1270,13 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
     if (Object.keys(still).length > 0) blink.still = still;
     if (browBonesProposed.length === 0) notes.push(`blink without brows: no eyebrow part (looked for: ${BROW_GROUP_TAGS.join(', ')}), so the blink has no brows group and no brow_drop`);
   }
+  // Issue #252: the breath's travel is BREATH_FRACTION of the torso part's height, not the reference's fixed 1.3 px
+  // amplitude. Its base stays its amplitude (the chest rises from the setup pose and returns). The other three tracks
+  // are an angle and a ratio and stay as drafted. A rig with no torso part keeps the reference's amplitude, and a note.
+  const breath = breathTrack(P);
+  notes.push(breath.note);
   tracks.push(
-    { bone: 'chest', prop: 'translatey', amp: 1.3, period: 4.0, phase: 0.0, base: 1.3 },
+    breath.track,
     { bone: 'chest', prop: 'scalex', amp: 0.004, period: 4.0, phase: 0.0, base: 1.004 },
     { bone: 'head', prop: 'rotate', amp: 0.9, period: 4.0, phase: 0.12 },
     { bone: 'neck', prop: 'rotate', amp: 0.35, period: 4.0, phase: 0.08 },
@@ -1170,43 +1327,78 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
   }
 
   // ---- front hair: fringe + locks
+  // Issue #249: the fringe's columns stand in the head's frame — the roll read once, off the eye bones as written
+  // (headRollOf, the one derivation) — and each column's root sits on the part's own art. With no eye pair the
+  // frame is the page's, said in a note.
+  const roll = headRollOf(bones, P.H);
+  const ax = headAxes('none' in roll ? 0 : roll.degrees, P.H);
+  const eyeMid: [number, number] = [axis, eyeY];
+  const turned = 'none' in roll ? 'on the page' : `along the head's down axis (the eye line's perpendicular, roll ${pyFixed(roll.degrees, 3)} degrees)`;
+  const rollBones = 'none' in roll ? [] : ['eye_r', 'eye_l'];
   for (const p of P.headFirst('front hair')) {
     const [g, r] = gridR(p);
     const mask = P.alpha(p);
     const top = p.y;
     const segs: Segment[] = [['head', rnd(head), rnd([axis, top])]];
-    const browY = eyeY - 0.18 * fh;
+    // Depths along the face's down axis from the eye line (through the eye midpoint): the brow line and the tip's.
+    const browD = -0.18 * fh;
+    const tipD = browD + 19;
+    const columns: string[] = [];
     for (const [tag, f, dx] of [
-      ['bang_r', 0.25, -10],
+      ['bang_r', 0.25, -FRINGE_STEP_PX],
       ['bang_c', 0.5, 0],
-      ['bang_l', 0.75, 10],
+      ['bang_l', 0.75, FRINGE_STEP_PX],
     ] as const) {
-      const x0 = fx0 + f * fw;
+      const foot = ax.at(eyeMid, fx0 + f * fw - axis, 0);
+      // The root is 13 px into a run of the column's art and above the brow line: the lowest run that holds such a
+      // point. A strand's end under the fringe (demo's centre column has one, 7 px below it) or a lock that starts
+      // at the brow line is not where the fringe's lock starts.
+      const runs = columnRuns(mask, p, ax, foot);
+      const held = runs.filter(([s0, s1]) => s0 + 13 < browD && s0 + 13 <= s1);
+      const artD = held.length === 0 ? null : held[held.length - 1][0];
+      const d0 = (artD ?? boxEntry(p, ax, foot)) + 13;
+      const d1 = (d0 + browD) / 2 + 6;
+      const rootWhy = placement(
+        'mask',
+        `link 0: on the column at ${f} of the face box's width from its left, ${turned}, 13 px below where ${p.name}'s art starts on that column — the lowest run of its art there that holds a point 13 px in and above the brow line (0.18 face heights above the eye line)`,
+        {
+          parts: [p.name],
+          bones: rollBones,
+          frame: ['face_box', 'eye_axis', 'eye_line'],
+          constants: [konst('of_face_width', f), konst('px_below_art_start', 13)],
+          fallback: artD === null ? `no run of ${p.name}'s art on the column holds a point 13 px in above the brow line: 13 px below the top of its box along the column` : null,
+        },
+      );
       C(
         tag,
         'head',
+        [ax.at(foot, 0, d0), ax.at(foot, dx, d1)],
+        ax.at(foot, dx * 1.8, tipD),
         [
-          [x0, top + 13],
-          [x0 + dx, (top + 13 + browY) / 2 + 6],
-        ],
-        [x0 + dx * 1.8, browY + 19],
-        [
-          placement('ratio', `link 0: ${f} of the face box's width from its left, 13 px below the top of ${p.name}`, { parts: [p.name], frame: ['face_box'], constants: [konst('of_face_width', f), konst('px_below_part_top', 13)] }),
-          placement('ratio', `link 1: ${dx} px across from link 0, 6 px below half way from link 0's row to the brow line (0.18 face heights above the eye line)`, {
+          rootWhy,
+          placement('ratio', `link 1: ${dx} px across the column from link 0, 6 px below half way from link 0 to the brow line (0.18 face heights above the eye line), ${turned}`, {
             parts: [p.name],
+            bones: rollBones,
             frame: ['face_box', 'eye_line'],
             constants: [konst('px_across', dx), konst('px_below_half_way', 6), konst('brow_line_face_heights_above_eye_line', 0.18)],
           }),
         ],
-        placement('ratio', `${dx * 1.8} px across from link 0 (1.8 times link 1's offset), 19 px below the brow line (0.18 face heights above the eye line)`, {
+        placement('ratio', `${dx * 1.8} px across the column (1.8 times link 1's step), 19 px below the brow line (0.18 face heights above the eye line), ${turned}`, {
+          bones: rollBones,
           frame: ['face_box', 'eye_line'],
           constants: [konst('times_link_1_offset', 1.8), konst('px_below_brow_line', 19), konst('brow_line_face_heights_above_eye_line', 0.18)],
         }),
       );
       segs.push(tag);
+      columns.push(tag);
       const a = tag === 'bang_c' ? 0.8 : 1.0;
       tracks.push({ chain: tag, amps: [a, Number((a * 2.2).toFixed(4))], period: 4.0, phase: 0.18, lag: 0.1 });
     }
+    notes.push(
+      `${p.name} (${p.from}): ${columns.join(', ')} are a template, not its locks — columns at 0.25, 0.5 and 0.75 of the face box's width, ${turned}, each rooted on the part's art; ` +
+        `the opaque shape does not separate the locks painted inside one mass of hair, so a lock that runs elsewhere is not followed — move the chains onto the locks` +
+        ('none' in roll ? `; no head frame to turn the columns to: ${roll.none}` : ''),
+    );
     const below = newMask(P.W, P.H);
     below.data.set(mask.data);
     const [c0, c1] = pySlice(0, pyInt(chin) + 4, P.H);
@@ -1666,6 +1858,20 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
         ['hip', rnd(along(waist, trunk.v, s0 + 0.09 * (s1 - s0))), rnd(along(waist, trunk.v, s0 + 0.91 * (s1 - s0)))],
       ];
     }
+    // Issue #262: a skirt whose art starts below the chest bone hangs from the waist. Its root is the hip line's,
+    // and the chest segment goes: with it the breath carries the waistband (a vertex near the chest segment's
+    // lower end takes chest weight), so the root travels with the breath while the hem, on the skirt's chains,
+    // does not. A bottomwear reaching up past the chest (the long robe the hip rule above reads the waist for) has
+    // art on the chest and keeps the segment. Read along the trunk where there is one, down the screen otherwise.
+    const down: readonly [number, number] = trunk === null ? [0, 1] : trunk.u;
+    const artTop = artExtent(mask, p, hip, down)[0];
+    const chestAt = (chest[0] - hip[0]) * down[0] + (chest[1] - hip[1]) * down[1];
+    if (artTop >= chestAt) {
+      segs = segs.filter((s) => typeof s === 'string' || s[0] !== 'chest');
+      notes.push(
+        `${p.name} (${p.from}): its art starts ${pyFixed(artTop - chestAt, 1)} px below chest's origin, so it hangs from the waist — its mesh takes the hip line and its skirt chains, no chest segment, and the breath does not carry its root`,
+      );
+    }
     for (const [tag, f, ph] of [
       ['skirt_r', 0.3, 0.3],
       ['skirt_c', 0.5, 0.34],
@@ -1764,7 +1970,40 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
       }),
     );
   }
-  return { proposal: { bones, meshes, regions, motion: blink === undefined ? { duration: 4.0, tracks } : { duration: 4.0, tracks, blink }, notes }, basis: { frame, bones: records } };
+  // Issue #252: the idle is IDLE_FRAMES long, and every period drafted against the reference's 4 s idle keeps its
+  // cycles per idle (REFERENCE_IDLE_SECONDS).
+  const scale = IDLE_SECONDS / REFERENCE_IDLE_SECONDS;
+  const idleTracks = tracks.map((tr) => ({ ...tr, period: tr.period * scale }));
+  return { proposal: { bones, meshes, regions, motion: blink === undefined ? { duration: IDLE_SECONDS, tracks: idleTracks } : { duration: IDLE_SECONDS, tracks: idleTracks, blink }, notes }, basis: { frame, bones: records } };
+}
+
+/**
+ * The drafted breath (issue #252): `chest` `translatey`, its travel peak to
+ * peak {@link BREATH_FRACTION} of the height of the {@link BREATH_SIZE_TAG}
+ * layer — the box around every part from it, cut pieces included, since a cut
+ * does not shorten the torso — amplitude half of it to two decimals, and the
+ * base the amplitude. With no such part there is no height to take a fraction
+ * of, and inventing one is not done: the track keeps the reference's
+ * amplitude, {@link REFERENCE_BREATH_AMP}, and the note says so.
+ */
+export function breathTrack(P: PartSet): { track: ProposedSingleTrack; note: string } {
+  const parts = P.byTag(BREATH_SIZE_TAG, undefined, true);
+  if (parts.length === 0) {
+    const a = REFERENCE_BREATH_AMP;
+    return {
+      track: { bone: 'chest', prop: 'translatey', amp: a, period: REFERENCE_IDLE_SECONDS, phase: 0.0, base: a },
+      note: `breath: no ${BREATH_SIZE_TAG} part, so no torso height to take a fraction of: chest translatey keeps the reference's amplitude ${a} (${pyFixed(2 * a, 2)} px peak to peak), not ${pyFixed(BREATH_FRACTION * 100, 1)} % of a torso — scale it to the figure`,
+    };
+  }
+  const top = Math.min(...parts.map((p) => p.y));
+  const bottom = Math.max(...parts.map((p) => p.y + p.h));
+  const height = bottom - top;
+  const amp = roundTo((BREATH_FRACTION * height) / 2, 2);
+  const layers = [...new Set(parts.map((p) => p.from))].join(', ');
+  return {
+    track: { bone: 'chest', prop: 'translatey', amp, period: REFERENCE_IDLE_SECONDS, phase: 0.0, base: amp },
+    note: `breath: chest translatey ${pyFixed(2 * amp, 2)} px peak to peak (amp ${pyFixed(amp, 2)}, base ${pyFixed(amp, 2)}) = ${pyFixed(BREATH_FRACTION * 100, 1)} % of the torso's height, ${height} px (layer ${layers}, y ${top}..${bottom}), once per ${IDLE_FRAMES}-frame idle at ${IDLE_FPS} fps`,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -2211,6 +2450,178 @@ function pct(v: number): string {
   return `${Math.round(v * 100)} %`;
 }
 
+/**
+ * The frontal reference the pitch proportions are written beside (issue #250):
+ * each figure's range, `[min, max]`, over three drawn faces that face front —
+ * `demo` and `scarf` as built here, and the seated character of
+ * https://github.com/rig-c/trailer (its `inputs/`, assembled by this port at
+ * the same plan) — read by {@link headFrame} with a `nose` part added to each
+ * plan, which `assemble --propose-plan` never proposes (the reference's rule):
+ * where the nose sits along eye midpoint -> mouth, demo 0.474, scarf 0.564,
+ * trailer 0.630; the stem against the bar, demo 0.629, scarf 0.675, trailer
+ * 0.510 (each on the eye bones `propose` writes). A drawn face does not carry a human face's ratios (the eyes are
+ * larger and lower, the nose a dot), so no published human model's are used.
+ *
+ * The turn is not written (issue #250): on a face painted three-quarter
+ * toward image left, the stem via the nose (skew −45.9 degrees, frontal
+ * −8.2 to 0.8) and via the mouth (−11.1, frontal −5.3 to 3.6) and the face's
+ * halves (image-left over image-right 0.681, frontal 0.839 to 1.032) all read
+ * it beyond the frontal range on the turned side, but the eyewhites' widths
+ * (0.913) read it inside the frontal range (0.898 to 1.000) — the trailer
+ * character, facing front, reads more turned by that figure than the turned
+ * face. Three readings that do not agree in order are not reported as one.
+ */
+export const FRONTAL_REFERENCE = {
+  faces: ['demo', 'scarf', 'the rig-c/trailer character'],
+  noseAlongStem: [0.474, 0.63],
+  stemOverBar: [0.51, 0.675],
+} as const;
+
+/** The centroid of a part's biggest 8-connected blob — the mouth bone's rule — or why it has none. */
+function blobPoint(P: PartSet, tag: string): FrameFeature {
+  const ps = P.headFirst(tag);
+  if (ps.length === 0) return { missing: `no part tagged ${tag}` };
+  const cc = connectedComponents(P.alpha(ps[0]), 8);
+  if (cc.count < 2) return { missing: `${ps[0].name} (${tag}) has no opaque pixel` };
+  let best = 1;
+  for (let i = 2; i < cc.count; i++) if (cc.stats[i].area > cc.stats[best].area) best = i;
+  return { part: ps[0].name, at: [cc.stats[best].cx, cc.stats[best].cy] };
+}
+
+/**
+ * The head's roll as the hair chains and their lint read it (issue #249):
+ * {@link eyeLineDegrees} on the origins of the single bones `eye_r` and
+ * `eye_l` as `bones` writes them — the one derivation of the roll, the one
+ * {@link headFrameNotes} prints and the rig turns the face bones to. With no
+ * such pair, or a pair in one column, why there is none.
+ */
+export function headRollOf(bones: readonly BoneEntry[], H: number): { degrees: number; eyes: [Point, Point] } | { none: string } {
+  const at = (n: string): Point | null => {
+    const e = bones.find((b) => 'name' in b && b.name === n);
+    return e === undefined || 'chain' in e ? null : e.at;
+  };
+  const r = at('eye_r');
+  const l = at('eye_l');
+  if (r === null || l === null) return { none: `no single bone ${[r === null ? 'eye_r' : null, l === null ? 'eye_l' : null].filter((n) => n !== null).join(' or ')}, so there is no eye line to turn to` };
+  if (r[0] === l[0]) return { none: `eye_r ${fmtAt(r)} and eye_l ${fmtAt(l)} share the column x = ${r[0]}, so the eye line has no left-to-right direction` };
+  return { degrees: eyeLineDegrees(r, l, H), eyes: [r, l] };
+}
+
+/**
+ * The px a fringe link of the template steps across its column, image-outward
+ * (issue #249 keeps it; the reference's `dx`): `bang_r`'s first link 10 px
+ * toward image-left, `bang_l`'s toward image-right, each tip 1.8 times that
+ * from its root. It is the widest step across the column the fringe rule
+ * writes in one link (the second steps 0.8 of it), so the off-lock LINT
+ * ({@link lint}) allows a link this much drift across the head's down axis.
+ */
+export const FRINGE_STEP_PX = 10;
+
+/**
+ * The runs of `mask`'s art along a column of the head's frame (issue #249):
+ * the column is the line through `foot` along the face's down axis, and the
+ * pixels it reads are those inside the part's box whose centre lies within
+ * half a pixel of that line. Ordered by the depth of their centre along the
+ * down axis, two pixels whose centres are within sqrt(2) px in depth
+ * (8-connected neighbours at most) are one run. Each run is `[start, end]`:
+ * its first centre's depth less half a pixel and its last's plus half a
+ * pixel — on the page's axes, exactly the top edge of its first row and the
+ * bottom edge of its last. Shallowest first.
+ */
+function columnRuns(mask: Mask, box: PartRecord, ax: HeadAxes, foot: readonly [number, number]): Array<[number, number]> {
+  const ds: number[] = [];
+  for (let y = box.y; y < box.y + box.h; y++) {
+    for (let x = box.x; x < box.x + box.w; x++) {
+      if (mask.data[y * mask.width + x] !== 1) continue;
+      const [a, d] = ax.of(foot, [x + 0.5, y + 0.5]);
+      if (Math.abs(a) <= 0.5) ds.push(d);
+    }
+  }
+  ds.sort((p, q) => p - q);
+  const runs: Array<[number, number]> = [];
+  for (let i = 0; i < ds.length; i++) {
+    if (i === 0 || ds[i] - ds[i - 1] > Math.SQRT2) runs.push([ds[i] - 0.5, ds[i] + 0.5]);
+    else runs[runs.length - 1][1] = ds[i] + 0.5;
+  }
+  return runs;
+}
+
+/**
+ * The depth along the face's down axis at which the column through `foot`
+ * enters the part's box (issue #249): on the page's axes, the box's top row
+ * less the foot's y, which is where the reference rooted the fringe. A column
+ * that misses the box enters it nowhere, and its corners' least depth stands
+ * in.
+ */
+function boxEntry(box: PartRecord, ax: HeadAxes, foot: readonly [number, number]): number {
+  const o = ax.at(foot, 0, 0);
+  const one = ax.at(foot, 0, 1);
+  const n: [number, number] = [one[0] - o[0], one[1] - o[1]];
+  const corners = (): number => Math.min(...[[box.x, box.y], [box.x + box.w, box.y], [box.x, box.y + box.h], [box.x + box.w, box.y + box.h]].map((c) => ax.of(foot, [c[0], c[1]])[1]));
+  let lo = -Infinity;
+  let hi = Infinity;
+  for (const [k, a, b] of [
+    [0, box.x, box.x + box.w],
+    [1, box.y, box.y + box.h],
+  ] as const) {
+    if (n[k] === 0) {
+      if (o[k] < a || o[k] > b) return corners();
+      continue;
+    }
+    const t0 = (a - o[k]) / n[k];
+    const t1 = (b - o[k]) / n[k];
+    lo = Math.max(lo, Math.min(t0, t1));
+    hi = Math.min(hi, Math.max(t0, t1));
+  }
+  return lo <= hi ? lo : corners();
+}
+
+/** `[min, max]` as `a..b` at 3 places. */
+function refRange(r: readonly [number, number] | readonly number[]): string {
+  return `${pyFixed(r[0], 3)}..${pyFixed(r[1], 3)}`;
+}
+
+/**
+ * The head frame's notes (issue #250): the bar through the eye bones'
+ * origins as `bones` writes them, its roll, the eye midpoint and the
+ * inter-eye distance; then the pitch proportions beside their frontal
+ * reference ({@link FRONTAL_REFERENCE}). The turn is read by
+ * {@link headFrame} but not written (the reference says why). A figure whose
+ * part is missing is named, never estimated.
+ * With no pair of eye bones there is no bar, and one note says why.
+ */
+export function headFrameNotes(P: PartSet, bones: readonly BoneEntry[]): string[] {
+  const at = (n: string): Point | null => {
+    const e = bones.find((b) => 'name' in b && b.name === n);
+    return e === undefined || 'chain' in e ? null : e.at;
+  };
+  const r = at('eye_r');
+  const l = at('eye_l');
+  if (r === null || l === null) {
+    const missing = [r === null ? 'eye_r' : null, l === null ? 'eye_l' : null].filter((n) => n !== null).join(' and ');
+    return [`head frame: not read — no ${missing} bone (an eye bone comes only from an eyewhite), so there is no bar to read the roll, the turn or the pitch against`];
+  }
+  if (r[0] === l[0]) return [`head frame: not read — eye_r ${fmtAt(r)} and eye_l ${fmtAt(l)} share the column x = ${r[0]}, so the bar has no left-to-right direction`];
+  const ew = (['eyewhite-r', 'eyewhite-l'] as const).map((t, i) => {
+    const p = P.byTag(t)[0];
+    return { part: p.name, mask: P.alpha(p), eye: i === 0 ? r : l };
+  });
+  const facePart = P.headFirst('face')[0];
+  const hf: HeadFrame = headFrame([r, l], P.H, { nose: blobPoint(P, 'nose'), mouth: blobPoint(P, 'mouth') }, ew, facePart === undefined ? { missing: 'no part tagged face' } : { part: facePart.name, mask: P.alpha(facePart) });
+  const f3 = (v: number): string => pyFixed(v, 3);
+  const [el, er] = hf.eyes;
+  const bar =
+    `head frame: the bar runs through ${el === l ? 'eye_l' : 'eye_r'} ${fmtAt(el)} and ${er === l ? 'eye_l' : 'eye_r'} ${fmtAt(er)}, the eye bones' origins, ${f3(hf.bar)} px; ` +
+    `roll ${f3(hf.roll)} degrees (Spine's, counter-clockwise) — the line the rig turns the face bones to and declares as invariants.axes; eye midpoint ${fmtAt(hf.mid)}`;
+  const ref = FRONTAL_REFERENCE;
+  const nose = hf.nose;
+  const mouth = hf.mouth;
+  const pitch =
+    `head pitch: the nose sits ${hf.noseAlongStem === null ? `— (not read: ${'missing' in nose ? nose.missing : 'missing' in mouth ? mouth.missing : 'the mouth sits on the bar'})` : f3(hf.noseAlongStem)} of the way from the eye midpoint to the mouth (frontal ${refRange(ref.noseAlongStem)}); ` +
+    `the stem, eye midpoint -> mouth, is ${'missing' in mouth ? `— (not read: ${mouth.missing})` : `${f3(mouth.down)} of the bar`} (frontal ${refRange(ref.stemOverBar)}); frontal ranges read on ${ref.faces.join(', ')}; the turn is not reported (src/propose.ts FRONTAL_REFERENCE says why)`;
+  return [bar, pitch];
+}
+
 /**
  * The blink squashes each eye's parts about the eye bone, so anything painted
  * into the eyelash layer above the lid — a double-eyelid crease — is squashed
@@ -2299,6 +2710,26 @@ export interface OffArtFinding {
   at: [number, number];
 }
 
+/**
+ * A link of a lock the head carries whose line leaves the lock's run (issue
+ * #249): it drifts across the head's down axis by more than the fringe
+ * template's widest step, {@link FRINGE_STEP_PX}, plus a pixel's rounding at
+ * each end. `degrees` is the link's angle off that axis and `limit` the angle
+ * that drift allows over the link's reach down the axis; a link that does not
+ * reach down the axis at all has no limit (`null`) and is named whatever its
+ * angle.
+ */
+export interface OffLockFinding {
+  kind: 'off-lock';
+  bone: string;
+  mesh: string;
+  from: [number, number];
+  to: [number, number];
+  degrees: number;
+  limit: number | null;
+  roll: number;
+}
+
 /** The hip at or above the chest: breathing and every skirt chain hang from the wrong end of the torso. */
 export interface HipAboveChestFinding {
   kind: 'hip-not-below-chest';
@@ -2358,7 +2789,7 @@ export interface ChainNotAdvancingFinding {
   toJoint: KeypointName;
 }
 
-export type LintFinding = OffArtFinding | HipAboveChestFinding | HipTooHighFinding | ChestNotBetweenFinding | HipNotPastChestFinding | HipNearerNeckFinding | ChainNotAdvancingFinding;
+export type LintFinding = OffArtFinding | OffLockFinding | HipAboveChestFinding | HipTooHighFinding | ChestNotBetweenFinding | HipNotPastChestFinding | HipNearerNeckFinding | ChainNotAdvancingFinding;
 
 /** Which rule set read the torso and the sleeve chains, under `--keypoints`. */
 export interface LintBasis {
@@ -2372,6 +2803,8 @@ export interface LintResult {
   findings: LintFinding[];
   /** Meshes naming no part in parts.json: nothing to lint them against. */
   unknownMeshes: string[];
+  /** Why the off-lock check (issue #249) read nothing though a head-run front hair mesh names a chain hung from head: no head frame, or no face box to find the chin by. Empty when it ran or had nothing to read. */
+  lockUnread: string[];
   /** Single bones the torso checks read (`hip`, `chest`) that the bones do not hold: those checks did not run. */
   missingTorsoBones: string[];
   /** Present only under `--keypoints`: the rule set that read the torso and the chains. */
@@ -2416,6 +2849,17 @@ export function coverageOutcome(c: BoneCoverage): CoverageOutcome {
  * the links `<segment><digits>`, so a single bone named as a segment has none,
  * and an explicit `[bone, from, to]` segment is a line, not an origin.
  *
+ * Then the fringe (issue #249): every chain hung from `head` that a head-run
+ * `front hair` part's mesh names, its tip no lower than the chin (the face
+ * box's bottom centre) along the head's down axis — the eye line's
+ * perpendicular, read by {@link headRollOf} — is a lock the head carries,
+ * and a link of it that drifts across that axis by more than
+ * {@link FRINGE_STEP_PX} plus sqrt(2) px (the template's widest step, and
+ * each end rounded to whole px) is named, with its angle and the angle its
+ * reach allows. A strand that hangs past the chin hangs with its weight and
+ * is not held to the head. With no head frame or no face box, `lockUnread`
+ * says why nothing was read.
+ *
  * Then the torso, which the reference did not lint: a single bone `hip` that
  * is not below a single bone `chest` (larger y), and a `hip` above
  * `HIP_MIN_FRACTION` of the figure's height (every part's union, top row to
@@ -2474,6 +2918,52 @@ export function lint(
       if (!isOn(mask, x, y)) findings.push({ kind: 'off-art', bone: n, mesh: mname, at: [x, y] });
     }
   }
+  // Issue #249: a lock the head carries runs along the head's down axis. The links read are those of every chain
+  // hung from head that a head-run front hair part's mesh names, when the chain's tip lies no lower along that axis
+  // than the chin (the face box's bottom centre): a strand that hangs past the chin hangs with its weight, not with
+  // the head, and is not held to the head's axis. The roll is headRollOf's, the one derivation.
+  const lockUnread: string[] = [];
+  const lockMeshes = Object.entries(spec.meshes).filter(([mname]) => {
+    const part = parts.get(mname);
+    return part !== undefined && splitFrom(part.from)[0] === 'head' && splitFrom(part.from)[1] === 'front hair';
+  });
+  const lockChains = lockMeshes.flatMap(([mname, m]) =>
+    m.segments.flatMap((sp) => {
+      if (typeof sp !== 'string') return [];
+      const e = spec.bones.find((b) => 'chain' in b && b.chain === sp);
+      return e !== undefined && 'chain' in e && e.parent === 'head' ? [{ mesh: mname, entry: e }] : [];
+    }),
+  );
+  if (lockChains.length > 0) {
+    const roll = headRollOf(spec.bones, P.H);
+    let chin: [number, number] | null = null;
+    try {
+      const [fx0, fy0, fw, fh] = faceBoxOf(P).box;
+      chin = [fx0 + fw / 2, fy0 + fh];
+    } catch (err) {
+      if (!(err instanceof PartsError)) throw err;
+      lockUnread.push(`no face box to find the chin by (${err.message.split('\n')[0]}), so no chain was read as a lock the head carries`);
+    }
+    if ('none' in roll) lockUnread.push(`${roll.none}, so no chain was read against the head's down axis`);
+    else if (chin !== null) {
+      const ax = headAxes(roll.degrees, P.H);
+      const mid: [number, number] = [(roll.eyes[0][0] + roll.eyes[1][0]) / 2, (roll.eyes[0][1] + roll.eyes[1][1]) / 2];
+      const chinD = ax.of(mid, chin)[1];
+      for (const { mesh, entry } of lockChains) {
+        if (ax.of(mid, entry.tip)[1] > chinD) continue;
+        const pts = [...entry.points, entry.tip];
+        entry.points.forEach((q, i) => {
+          const bone = `${entry.chain}${i}`;
+          readBy(bone, `off-lock on mesh ${pyRepr(mesh)}`);
+          const [across, down] = ax.of(q, pts[i + 1]);
+          const degrees = (Math.atan2(Math.abs(across), down) * 180) / Math.PI;
+          // A drift of FRINGE_STEP_PX across, and each end within sqrt(2)/2 px of the point it was rounded from.
+          const limit = down > 0 ? (Math.atan2(FRINGE_STEP_PX + Math.SQRT2, down) * 180) / Math.PI : null;
+          if (limit === null || degrees > limit) findings.push({ kind: 'off-lock', bone, mesh, from: [q[0], q[1]], to: [pts[i + 1][0], pts[i + 1][1]], degrees, limit, roll: roll.degrees });
+        });
+      }
+    }
+  }
   const single = (n: string): [number, number] | null => {
     const e = spec.bones.find((b) => 'name' in b && b.name === n);
     return e !== undefined && 'name' in e ? [e.at[0], e.at[1]] : null;
@@ -2525,13 +3015,14 @@ export function lint(
     }
   }
   const coverage = lintCoverage(spec, byName, read, findings, unknownMeshes, basis);
-  return basis === undefined ? { findings, unknownMeshes, missingTorsoBones, coverage } : { findings, unknownMeshes, missingTorsoBones, basis, coverage };
+  return basis === undefined ? { findings, unknownMeshes, lockUnread, missingTorsoBones, coverage } : { findings, unknownMeshes, lockUnread, missingTorsoBones, basis, coverage };
 }
 
 /** The bones a finding names: the off-art link; hip and chest for a relation between them; a chain's last link for its tip. */
 function findingBones(f: LintFinding, bones: readonly BoneEntry[]): string[] {
   switch (f.kind) {
     case 'off-art':
+    case 'off-lock':
       return [f.bone];
     case 'hip-not-below-chest':
     case 'hip-not-past-chest':
@@ -2688,6 +3179,14 @@ export function lintLine(f: LintFinding): string {
   switch (f.kind) {
     case 'off-art':
       return `LINT ${f.bone} at ${pyIntList(f.at)} is off the art of mesh ${pyRepr(f.mesh)}`;
+    case 'off-lock':
+      return (
+        `LINT ${f.bone} at ${pyIntList(f.from)} runs to ${pyIntList(f.to)} ${pyFixed(f.degrees, 1)} degrees off the head's down axis (the eye line's perpendicular, roll ${pyFixed(f.roll, 1)}), ` +
+        (f.limit === null
+          ? 'and does not reach down it at all'
+          : `more than the ${pyFixed(f.limit, 1)} its reach allows (a drift of ${FRINGE_STEP_PX} px across, the fringe template's widest step, and a pixel's rounding at each end)`) +
+        `: a lock of mesh ${pyRepr(f.mesh)} the head carries runs along the head, and this link leaves it`
+      );
     case 'hip-not-below-chest':
       return `LINT hip at ${pyIntList(f.hip)} is not below chest at ${pyIntList(f.chest)}: the hip must have the larger y, or breathing and the skirt hang from the shoulders`;
     case 'hip-too-high':