@rig-c/parts 1.9.1 → 1.10.0

package/src/parts.ts

@@ -6,7 +6,9 @@
  * came from (`from` = `<run>:<tag>`, the See-through run and tag — the only
  * thing downstream stages classify a part by — or `painting:<name>` for an
  * `assemble.patches` entry, cut from the painting itself and named for the
- * part it made, which no tag classifies), where it sits in rig pixels
+ * part it made, which no tag classifies; a part from a layer the author made
+ * is `<run>:author:<label>`, issue #256, which no tag classifies either),
+ * where it sits in rig pixels
  * (`x`/`y`/`w`/`h`, y down, origin top-left: the PNG's own box), and what the
  * assembler did to its pixels, counted:
  *
@@ -73,7 +75,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { type Problem, refuseIfAny } from './errors.ts';
-import { readTag } from './tags.ts';
+import { readLayerTag } from './tags.ts';
 
 export interface PartRecord {
   name: string;
@@ -134,10 +136,26 @@ export interface PartsFile {
   ghost_px: Record<string, number>;
   /** Absent in a `parts.json` the reference wrote; `assemble` always writes it. */
   recomposite?: RecompositeRecord;
+  /** Written only under `config.scene` (issue #242): the recomposite was read inside this figure; absent otherwise. */
+  scene?: SceneRecord;
 }
 
-const TOP_KEYS = ['rig_size', 'scale_rig_per_source', 'parts', 'ghost_px', 'recomposite'] as const;
-const REQUIRED_TOP_KEYS = TOP_KEYS.filter((k) => k !== 'recomposite');
+/**
+ * `parts.json`'s `scene` block (issue #242): the painting is a scene, so the
+ * `recomposite` block beside it was measured inside the figure — the rig pixels
+ * where a full-run layer's alpha is above `figure_alpha_above` — and `check`
+ * reads `RECOMPOSITE_HOLES` and the seam that way. `figure_px` is the figure's
+ * size; `figure_mask` the image `assemble` wrote of it, beside the recomposite.
+ */
+export interface SceneRecord {
+  figure_alpha_above: number;
+  figure_px: number;
+  figure_mask: string;
+}
+
+const TOP_KEYS = ['rig_size', 'scale_rig_per_source', 'parts', 'ghost_px', 'recomposite', 'scene'] as const;
+const REQUIRED_TOP_KEYS = TOP_KEYS.filter((k) => k !== 'recomposite' && k !== 'scene');
+export const SCENE_KEYS = ['figure_alpha_above', 'figure_px', 'figure_mask'] as const;
 export const RECOMPOSITE_KEYS = ['mean_abs', 'within_limit', 'within_share', 'error_limit', 'error_px', 'covered_alpha', 'uncovered_error_px', 'hole_count', 'holes_listed', 'holes'] as const;
 const RECOMPOSITE_COUNTS = ['within_limit', 'error_limit', 'error_px', 'covered_alpha', 'uncovered_error_px', 'hole_count', 'holes_listed'] as const;
 export const HOLE_KEYS = ['px', 'x', 'y', 'w', 'h', 'borders'] as const;
@@ -170,22 +188,22 @@ const COUNT_KEYS = PART_KEYS.slice(2).filter((k) => k !== FRINGE_KEY && k !== CU
 export const VISIBILITY_KEYS = ['visible_px', 'occluded_px', 'visible_not_projected_px'] as const;
 const REQUIRED_KEYS = PART_KEYS.filter((k) => !(VISIBILITY_KEYS as readonly string[]).includes(k) && k !== FRINGE_KEY && k !== CUT_FROM_KEY);
 
-/** Where a part came from: a See-through run and a v3 tag, or the painting itself for a patch. */
+/** Where a part came from: a See-through run and a v3 tag or an author-made layer's `author:<label>` (issue #256), or the painting itself for a patch. */
 export type From = { run: 'full' | 'head'; tag: string } | { run: 'painting'; patch: string };
 
 /** The `from` a patch's record carries. */
 export const PAINTING_RUN = 'painting';
 
-/** `<run>:<tag>` with run `full` or `head` and a v3 tag, `painting:<patch name>`, or null. */
+/** `<run>:<tag>` with run `full` or `head` and a v3 tag or an `author:<label>` (`full:author:hand`), `painting:<patch name>`, or null. */
 export function readFrom(from: string): From | null {
   const p = /^painting:(.+)$/.exec(from);
   if (p !== null) return { run: 'painting', patch: p[1] };
   const m = /^(full|head):(.+)$/.exec(from);
-  if (m === null || readTag(m[2]) === null) return null;
+  if (m === null || readLayerTag(m[2]) === null) return null;
   return { run: m[1] as 'full' | 'head', tag: m[2] };
 }
 
-/** The See-through tag a part came from, or null for a `painting:` patch (or a `from` that is neither). */
+/** The tag a part came from — a See-through tag, or an author-made layer's `author:<label>`, which no role reader matches — or null for a `painting:` patch (or a `from` that is neither). */
 export function tagOf(from: string): string | null {
   const f = readFrom(from);
   return f === null || f.run === 'painting' ? null : f.tag;
@@ -207,6 +225,7 @@ export function serializeParts(file: PartsFile): string {
             holes: file.recomposite.holes.map((h) => ({ ...Object.fromEntries(HOLE_KEYS.filter((k) => k !== 'borders').map((k) => [k, h[k]])), borders: h.borders.map((b) => ({ part: b.part, px: b.px })) })),
           },
         }),
+    ...(file.scene === undefined ? {} : { scene: Object.fromEntries(SCENE_KEYS.map((k) => [k, (file.scene as SceneRecord)[k]])) }),
   };
   return `${JSON.stringify(ordered, null, 2)}\n`;
 }
@@ -257,7 +276,7 @@ function checkParts(raw: unknown, path: string): PartsFile {
     if (typeof g !== 'object' || g === null || Array.isArray(g)) fail('PARTS_FIELD_TYPE', `${path} field "ghost_px"`, `is ${show(g)}; an object of "<run>:<tag>" -> pixels is required`);
     else {
       for (const [k, v] of Object.entries(g as Record<string, unknown>)) {
-        if (tagOf(k) === null) fail('PARTS_FROM_KNOWN', `${path} ghost_px key "${k}"`, 'is not "<full|head>:<v3 tag>" (a patch has no See-through layer, so no ghost count)');
+        if (tagOf(k) === null) fail('PARTS_FROM_KNOWN', `${path} ghost_px key "${k}"`, 'is not "<full|head>:<v3 tag>" or "<full|head>:author:<label>" (a patch has no See-through layer, so no ghost count)');
         if (!(Number.isInteger(v) && (v as number) >= 0)) fail('PARTS_FIELD_TYPE', `${path} ghost_px "${k}"`, `is ${show(v)}; a pixel count is required`);
       }
     }
@@ -284,7 +303,7 @@ function checkParts(raw: unknown, path: string): PartsFile {
       } else if (seen.has(r.name)) fail('PARTS_NAME_UNIQUE', label, `appears at parts[${seen.get(r.name)}] and parts[${i}]`);
       else seen.set(r.name, i);
       const from = typeof r.from === 'string' ? readFrom(r.from) : null;
-      if (from === null) fail('PARTS_FROM_KNOWN', `${label} field "from"`, `is ${show(r.from)}; "<full|head>:<v3 tag>", or "painting:<the part's own name>" for a patch, is required`);
+      if (from === null) fail('PARTS_FROM_KNOWN', `${label} field "from"`, `is ${show(r.from)}; "<full|head>:<v3 tag>", "<full|head>:author:<label>" for a layer the author made, or "painting:<the part's own name>" for a patch, is required`);
       else if (from.run === 'painting' && from.patch !== r.name) {
         fail('PARTS_FROM_KNOWN', `${label} field "from"`, `is ${show(r.from)}; a patch's provenance names the patch itself, so "painting:${String(r.name)}" is required`);
       }
@@ -355,6 +374,18 @@ function checkParts(raw: unknown, path: string): PartsFile {
       else if (b.from !== r.from) fail('PARTS_CUT_FROM_KNOWN', object, `names "${base}", whose from is ${show(b.from)}; this piece's is ${show(r.from)}, and a piece shares its base's layer`);
     }
   }
+  if ('scene' in o) {
+    const sc = o.scene;
+    if (typeof sc !== 'object' || sc === null || Array.isArray(sc)) fail('PARTS_FIELD_TYPE', `${path} field "scene"`, `is ${show(sc)}; an object is required`);
+    else {
+      const r = sc as Record<string, unknown>;
+      for (const k of Object.keys(r)) if (!(SCENE_KEYS as readonly string[]).includes(k)) fail('PARTS_KEY_KNOWN', `${path} scene key "${k}"`, `is not a scene field; known: ${SCENE_KEYS.join(', ')}`);
+      for (const k of SCENE_KEYS) if (!(k in r)) fail('PARTS_FIELD_PRESENT', `${path} scene field "${k}"`, 'is absent and required');
+      for (const k of ['figure_alpha_above', 'figure_px'] as const) if (k in r && !(Number.isInteger(r[k]) && (r[k] as number) >= 0)) fail('PARTS_FIELD_TYPE', `${path} scene field "${k}"`, `is ${show(r[k])}; a non-negative integer is required`);
+      if ('figure_mask' in r && !(typeof r.figure_mask === 'string' && r.figure_mask !== '')) fail('PARTS_FIELD_TYPE', `${path} scene field "figure_mask"`, `is ${show(r.figure_mask)}; the mask's file name is required`);
+      if (!('recomposite' in o)) fail('PARTS_FIELD_PRESENT', `${path} field "recomposite"`, 'is absent; a scene block says how the recomposite block beside it was measured, so it is required with one');
+    }
+  }
   if ('recomposite' in o && sizeOk) {
     const names = Array.isArray(o.parts) ? new Set(o.parts.map((p) => (typeof p === 'object' && p !== null ? (p as Record<string, unknown>).name : undefined)).filter((n): n is string => typeof n === 'string')) : new Set<string>();
     checkRecomposite(o.recomposite, path, size as [number, number], names, fail);

package/src/propose.ts

@@ -43,7 +43,10 @@
  *   strand and what became of it — a strand left without a chain is never
  *   silent (issue #24).
  * - anything no rule claims rides its nearest trunk bone as a region —
- *   including every `painting:` patch (`assemble.patches`), which has no tag,
+ *   including every part from an author-made layer (`<run>:author:<label>`,
+ *   issue #256), which is no See-through tag and so has no role: no rule
+ *   reads it, and its note says the bone is the config's to name — and
+ *   every `painting:` patch (`assemble.patches`), which has no tag,
  *   so no rule above ever reads it: it is never a mesh or a chain, it moves
  *   no bone the rules place, and the note says the bone is the config's to
  *   name in `regions.<name>`. A cut's piece (`assemble.cuts`, recorded with
@@ -130,7 +133,8 @@ 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';
+import { AUTHOR_NO_ROLE, isAuthorTag } from './tags.ts';
+import { TURN_BONE, TURN_CARRIER_TAG, TURN_PLACES, TURN_RIDER_OFFSET, TURN_RIDER_TAGS, turnFractions, turnNearest, turnPivot, turnRiderDepth, type TurnSpec } from './turn.ts';
 import { edgeLength } from './length.ts';
 
 // ---------------------------------------------------------------------------
@@ -204,6 +208,46 @@ export const BREATH_FRACTION = 0.025;
 /** The breath's amplitude the reference drafted on every figure, kept only where the trunk has no length to scale by. */
 export const REFERENCE_BREATH_AMP = 1.3;
 
+/**
+ * How a drafted lattice's spacing (`meshes.<part>.grid`) is chosen (issue #265):
+ *
+ * - `figure`, the default: one spacing for the figure, `round(H / FIGURE_GRID_DIVISOR)` rig px, H the height of the
+ *   union of every part's box in parts.json ({@link figureGrid}); a part whose own spacing (the `part` rule) is
+ *   already coarser keeps its own. `r` is the `part` rule's either way, so the weights a vertex would take at a point
+ *   do not move, only where the vertices are.
+ * - `part`: the reference implementation's rule, a tenth of the part's own short side, clamped to 5..36. The
+ *   oracle examples (`reference-demo`, `reference-sample`) are proposed under it, because their `proposal.json` holds
+ *   this proposer to the reference's.
+ */
+export type GridRule = 'figure' | 'part';
+export const GRID_RULES: readonly GridRule[] = ['figure', 'part'];
+export const DEFAULT_GRID_RULE: GridRule = 'figure';
+
+/**
+ * The divisor of the figure's spacing: Stage A of issue #265 (docs/evidence/density-survey.md) built every lattice
+ * of demo, scarf and the public trailer at round(H / c) for c in {26, 37, 52}; 37 is the coarsest at which every
+ * `check` bar passed on all three (c 26 failed scarf's TIP_OVER_ROOT). Calibrated on those three figures only, all
+ * of similar size (H 1106, 1108 and 1185 rig px).
+ */
+export const FIGURE_GRID_DIVISOR = 37;
+
+/** The largest idle displacement Stage A measured at {@link FIGURE_GRID_DIVISOR} against each example's finer lattice, rig px (the trailer's hairpin), which no `check` bar reads. */
+export const FIGURE_GRID_IDLE_PX = 1.427;
+
+/** The figure's spacing: the union of every part's box in parts.json, its height H, and round(H / {@link FIGURE_GRID_DIVISOR}). */
+export function figureGrid(recs: readonly PartRecord[]): { top: number; bottom: number; height: number; grid: number } {
+  const top = Math.min(...recs.map((r) => r.y));
+  const bottom = Math.max(...recs.map((r) => r.y + r.h));
+  const height = bottom - top;
+  return { top, bottom, height, grid: pyInt(pyRound(height / FIGURE_GRID_DIVISOR)) };
+}
+
+/** The `part` rule's spacing and the weight falloff `r` both rules draft (the reference's). */
+export function partGrid(p: { w: number; h: number }): [number, number] {
+  const g = pyInt(Math.min(36, Math.max(5, pyRound(Math.min(p.w, p.h) / 10))));
+  return [g, Math.max(3, pyInt(pyRound(g * 0.42)))];
+}
+
 export interface Proposal {
   bones: BoneEntry[];
   meshes: Record<string, MeshSpec>;
@@ -390,48 +434,57 @@ 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:
+ * runs they came from: each carrier's depth is its layer's `depth_median` —
+ * the layer of the run its part was assembled from, 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).
  *
+ * A rider (issue #271, {@link TURN_RIDER_TAGS}: the eye group, nose, mouth)
+ * does not carry its own median: it takes the face part's, offset by
+ * {@link turnRiderDepth} by draw order. With no face part, or more than one,
+ * the riders keep their own medians and a note says so. Every other layer is
+ * its own carrier.
+ *
  * 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.
+ * depth it came from; one lists where each depth came from; and one line names
+ * each carrier the other run places more than {@link TURN_RUN_APART} of the
+ * span away.
  */
 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 read: Array<{ part: string; run: 'full' | 'head'; tag: string; base: string | null; own: number; area: number; order: number; piece: boolean }> = [];
   const patches: string[] = [];
   const unread = new Map<string, string[]>();
-  for (const r of P.recs) {
+  P.recs.forEach((r, order) => {
     const [run, tag] = splitFrom(r.from);
     if (run === PAINTING_RUN) {
       patches.push(r.name);
-      continue;
+      return;
     }
     const set = run === 'full' || run === 'head' ? runs[run] : undefined;
     if (set === undefined) {
       unread.set(run, [...(unread.get(run) ?? []), r.name]);
-      continue;
+      return;
     }
     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;
+      return;
     }
     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;
+      return;
     }
-    rows.push({ part: r.name, depth: layer.depth, area: r.opaque_px });
-  }
+    read.push({ part: r.name, run: run as 'full' | 'head', tag, base: 'base' in layer.tag ? layer.tag.base : null, own: layer.depth, area: r.opaque_px, order, piece: r.cut_from !== undefined });
+  });
   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` });
   }
@@ -440,6 +493,22 @@ export function draftTurn(P: PartSet, runs: TurnRuns): { turn: TurnSpec | null;
   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`);
   }
+  // Issue #271: the riders take the face's depth; everything else is its own carrier.
+  // An author-made layer (issue #256) has no tag, so it is neither a rider nor the carrier: it carries itself at its own depth.
+  const isRider = (x: { base: string | null }): boolean => x.base !== null && TURN_RIDER_TAGS.includes(x.base);
+  const faces = read.filter((x) => x.base === TURN_CARRIER_TAG && !x.piece);
+  const face = faces.length === 1 ? faces[0] : null;
+  const riders = read.filter(isRider);
+  if (riders.length > 0 && face === null) {
+    notes.push(
+      `turn: rider(s) ${riders.map((x) => `"${x.part}"`).join(', ')} keep their own See-through depth_median: ${faces.length === 0 ? `no part comes from a "${TURN_CARRIER_TAG}" layer` : `${faces.length} parts (${faces.map((x) => `"${x.part}"`).join(', ')}) come from a "${TURN_CARRIER_TAG}" layer, and which one carries them cannot be read off the parts`} — a value in config.turn.depths sets one`,
+    );
+  }
+  const rows = read.map((x) => {
+    if (face === null || !isRider(x)) return { ...x, depth: x.own, source: `own, ${x.run}:${x.tag}` };
+    const above = x.order > face.order;
+    return { ...x, depth: turnRiderDepth(face.own, above), source: `"${face.part}" ${above ? '-' : '+'} ${TURN_RIDER_OFFSET}, drawn ${above ? 'above' : 'under'} it; own ${x.run}:${x.tag} ${x.own}` };
+  });
   const pivot = turnPivot(rows);
   const depths = Object.create(null) as Record<string, number>;
   for (const r of rows) depths[r.part] = r.depth;
@@ -455,17 +524,36 @@ export function draftTurn(P: PartSet, runs: TurnRuns): { turn: TurnSpec | null;
   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). ` +
+    `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' depths 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: where each depth came from — ${rows.map((r) => `${r.part} ${r.depth} (${r.source})`).join('; ')}`);
+  // Issue #271: a carrier the other run places elsewhere is named; the run read stays the part's own.
+  const span = pivot - nearest.depth;
+  for (const r of rows) {
+    if (isRider(r) && face !== null) continue;
+    const other = r.run === 'full' ? 'head' : 'full';
+    const there = runs[other]?.layers.find((l) => l.name === r.tag);
+    if (there === undefined || there.depth === null || there.opaquePx === 0 || !(there.depth < 1)) continue;
+    if (Math.abs(there.depth - r.own) > TURN_RUN_APART * span) {
+      notes.push(`turn: "${r.part}" reads ${r.own} in the ${r.run} run and ${there.depth} in the ${other} run, more than ${TURN_RUN_APART * 100} % of the span ${roundTo(span, TURN_PLACES)} apart; the ${r.run} run it was assembled from is read`);
+    }
+  }
   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. */
+/**
+ * The share of the span (`pivot − nearest`) past which a carrier's two runs
+ * are said to disagree: issue #271's judgment line, set before it was measured
+ * (from #251's record). It only writes a note; the run read does not change.
+ */
+export const TURN_RUN_APART = 0.1;
+
+/** The notes beside every drafted turn (issues #251, #271): 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)",
+  "turn: depth is the See-through layer's median, a carrier's read from the run its part was assembled from and a rider's (eye group, nose, mouth) taken from the face; 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 — a linear map cannot reconcile them, since the runs order the shared layers differently (parts#271)",
 ];
 
 /** The proposal with `turn` written after `motion` and `notes` extended; the proposal itself when `turn` is null. */
@@ -1013,8 +1101,8 @@ const SIDES = [
  * which rule stood in; without it every value and note is the one this
  * function wrote before the parameter existed.
  */
-export function propose(P: PartSet, joints?: RigJoints, wristSnap: number | null = null): Proposal {
-  return proposeWithBasis(P, joints, wristSnap).proposal;
+export function propose(P: PartSet, joints?: RigJoints, wristSnap: number | null = null, gridRule: GridRule = DEFAULT_GRID_RULE): Proposal {
+  return proposeWithBasis(P, joints, wristSnap, gridRule).proposal;
 }
 
 /**
@@ -1027,7 +1115,7 @@ export function propose(P: PartSet, joints?: RigJoints, wristSnap: number | null
  * `joints`: see {@link armsFromJoints}. `null` is the built-in tolerance
  * alone, and every value and note is the one written before it existed.
  */
-export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: number | null = null): { proposal: Proposal; basis: ProposalBasis } {
+export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: number | null = null, gridRule: GridRule = DEFAULT_GRID_RULE): { proposal: Proposal; basis: ProposalBasis } {
   // Issue #230: a piece is not given its base's rule a second time, which
   // needs to know which part is the piece. A file that cannot say is refused
   // here, and only here: every other reader of parts.json still takes it.
@@ -1285,9 +1373,13 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
     { bone: 'neck', prop: 'rotate', amp: 0.35, period: 4.0, phase: 0.08 },
   );
 
+  // Issue #265: the figure's spacing unless the reference's rule is asked for; r is the part rule's either way.
+  const fig = figureGrid(P.recs);
+  const ownGrid = new Map<string, number>();
   const gridR = (p: PartRecord): [number, number] => {
-    const g = pyInt(Math.min(36, Math.max(5, pyRound(Math.min(p.w, p.h) / 10))));
-    return [g, Math.max(3, pyInt(pyRound(g * 0.42)))];
+    const [g, r] = partGrid(p);
+    ownGrid.set(p.name, g);
+    return [gridRule === 'part' ? g : Math.max(g, fig.grid), r];
   };
 
   // ---- back hair
@@ -1940,6 +2032,9 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
       regions[p.name] = cy < neckY ? 'head' : cy < hip[1] ? 'chest' : 'hip';
       if (splitFrom(p.from)[0] === PAINTING_RUN) {
         notes.push(`${p.name} (${p.from}): a painting patch has no tag, so no rule -> region on ${regions[p.name]}, the nearest trunk bone; config.regions.${p.name} is the bone it rides`);
+      } else if (isAuthorTag(splitFrom(p.from)[1])) {
+        // Issue #256: no rule reads an author-made layer, and none is guessed for it.
+        notes.push(`${p.name} (${p.from}): ${AUTHOR_NO_ROLE}; no rule reads it -> region on ${regions[p.name]}, the nearest trunk bone, until config.regions.${p.name} names the bone it rides`);
       } else if (p.cut_from !== undefined) {
         notes.push(
           `${p.name} (${p.from}): a piece an assemble.cuts entry took from ${p.cut_from}, so not given that layer's rule a second time (it would name ${p.cut_from}'s bones and chains again) -> region on ${regions[p.name]}, the nearest trunk bone; config.regions.${p.name} is the bone it rides, and a mesh in config.meshes is the author's to give it`,
@@ -1955,6 +2050,10 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
       );
     }
   }
+  if (gridRule === 'figure') {
+    const latt = Object.keys(meshes).filter((m) => 'grid' in meshes[m] && ownGrid.has(m));
+    if (latt.length > 0) notes.push(gridNote(fig, latt.map((m) => [m, ownGrid.get(m) as number])));
+  }
   if (joints !== undefined) {
     notes.push(
       ...jointNotes(joints, {
@@ -1980,6 +2079,19 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
   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 note the `figure` grid rule writes (issue #265): the spacing and where it came from, per lattice part its own
+ * spacing and the one drafted, what it costs and what it was calibrated on.
+ */
+export function gridNote(fig: { top: number; bottom: number; height: number; grid: number }, parts: ReadonlyArray<readonly [string, number]>): string {
+  const took = parts.filter(([, g]) => g < fig.grid).map(([m, g]) => `${m} ${g} -> ${fig.grid}`);
+  const kept = parts.filter(([, g]) => g >= fig.grid).map(([m, g]) => `${m} ${g}`);
+  return (
+    `mesh spacing: grid ${fig.grid} = round(H / ${FIGURE_GRID_DIVISOR}), H ${fig.height} rig px the height of every part's box together (rows ${fig.top} to ${fig.bottom}), in place of a tenth of each part's short side (${took.length > 0 ? took.join(', ') : 'none'}; kept, already as coarse: ${kept.length > 0 ? kept.join(', ') : 'none'}); r is the part's own. ` +
+    `Calibrated on three figures of similar size (H 1106-1185 rig px, issue #265 Stage A), where every check bar passed at this divisor and the idle moved by up to ${FIGURE_GRID_IDLE_PX} rig px against the finer lattice — no bar reads that. propose --grid-rule part drafts the part's own spacing`
+  );
+}
+
 /**
  * The drafted breath (issues #252, #270): `chest` `translatey`, its travel peak
  * to peak {@link BREATH_FRACTION} of the torso's length — the distance from the

package/src/requirements.ts

@@ -170,6 +170,15 @@ export interface RequirementsFile {
    * and names each in its line. Empty when not declared: every part hangs.
    */
   rises: string[];
+  /**
+   * Issue #245: the swinging parts whose tip is at rest — a hand lying on the
+   * bed while the shoulder moves with the breath — by name. `TIP_OVER_ROOT`
+   * holds each to the opposite relation, its tip half travelling no further
+   * than its root half, and `CHAIN_LAG` holds the chain carrying each to
+   * amplitudes that do not grow toward the tip; each line names them first.
+   * Empty when not declared: every swinging part's tip swings.
+   */
+  rests: string[];
 }
 
 /** What `check --requirements` and `build --requirements` name, said once for the help and the refusals. */
@@ -205,8 +214,8 @@ const KIND_FIELDS: Record<RequirementKind, readonly string[]> = {
 
 const NAME = /^[A-Za-z][A-Za-z0-9_]*$/;
 
-/** The three lists of parts a scene excepts from a bar that assumes a standing figure (issue #231), in the order they are read. */
-export const EXCEPTION_LISTS = ['not_planted', 'not_swinging', 'rises'] as const;
+/** The lists of parts a scene excepts from a bar that assumes a standing figure (issues #231, #245), in the order they are read. */
+export const EXCEPTION_LISTS = ['not_planted', 'not_swinging', 'rises', 'rests'] as const;
 type ExceptionList = (typeof EXCEPTION_LISTS)[number];
 
 /** What each list's absence declares. */
@@ -214,14 +223,16 @@ const EXCEPTION_ABSENT: Record<ExceptionList, string> = {
   not_planted: 'every footwear part a planted foot',
   not_swinging: 'every handwear and bottomwear part one that swings',
   rises: 'every swinging part one that hangs',
+  rests: 'every swinging part one whose tip swings further than its root',
 };
 
 /**
  * Read and shape-check a requirements file. Every problem is collected before
  * one refusal: the file, `spec`, `fps` (required, a positive number: no
  * default), `targets` (optional), `requirements` (required, possibly empty)
- * and `not_planted`, `not_swinging` and `rises` (each optional, issue #231: a
- * non-empty list of distinct part names, no part in both of the last two;
+ * and `not_planted`, `not_swinging`, `rises` and `rests` (each optional,
+ * issues #231 and #245: a non-empty list of distinct part names, no part both
+ * in `not_swinging` and in `rises` or `rests`;
  * which parts they are is read against parts.json and the rig by `check`),
  * each entry's every field and bar by name, a key the format does not read,
  * and a name used twice. Resolving the names against the rig is
@@ -246,7 +257,7 @@ export function readRequirements(path: string): RequirementsFile {
     problems.push({ code: 'REQUIREMENTS_FIELD', object, detail });
   };
   if (raw.spec !== REQUIREMENTS_SPEC) field(`${at} field "spec"`, `is ${JSON.stringify(raw.spec)}; ${JSON.stringify(REQUIREMENTS_SPEC)} is required`);
-  for (const k of Object.keys(raw)) if (!['spec', 'fps', 'targets', 'requirements', ...EXCEPTION_LISTS].includes(k) && !freeKey(k, raw[k])) field(`${at} field "${k}"`, 'is not a field this format reads (spec, fps, targets, requirements, not_planted, not_swinging, rises; note or *_note as a string; x-<name> as a record)');
+  for (const k of Object.keys(raw)) if (!['spec', 'fps', 'targets', 'requirements', ...EXCEPTION_LISTS].includes(k) && !freeKey(k, raw[k])) field(`${at} field "${k}"`, 'is not a field this format reads (spec, fps, targets, requirements, not_planted, not_swinging, rises, rests; note or *_note as a string; x-<name> as a record)');
   let fps = NaN;
   if (!(finite(raw.fps) && raw.fps > 0)) field(`${at} field "fps"`, `is ${JSON.stringify(raw.fps)}; a positive number of frames per second is required — every named animation is sampled at it, and there is no default`);
   else fps = raw.fps;
@@ -392,8 +403,12 @@ export function readRequirements(path: string): RequirementsFile {
   lists.rises.forEach((n, i) => {
     if (lists.not_swinging.includes(n)) field(`${at} field "rises"[${i}]`, `names "${n}", which "not_swinging" names too; a part that does not swing has no tip to read up or down`);
   });
+  // Issue #245: rests is a reading (the tip no further than the root) and not_swinging is none, so a part cannot be both.
+  lists.rests.forEach((n, i) => {
+    if (lists.not_swinging.includes(n)) field(`${at} field "rests"[${i}]`, `names "${n}", which "not_swinging" names too; a part declared not swinging is not measured, so there is no tip to hold at rest — leave it in one list`);
+  });
   refuseIfAny(problems);
-  return { path: at, fps, targets, requirements, not_planted: lists.not_planted, not_swinging: lists.not_swinging, rises: lists.rises };
+  return { path: at, fps, targets, requirements, not_planted: lists.not_planted, not_swinging: lists.not_swinging, rises: lists.rises, rests: lists.rests };
 }
 
 // ---------------------------------------------------------------------------

package/src/rig.ts

@@ -638,7 +638,8 @@ export interface ContourMeshReport {
   exponent?: number;
   /** Only when the mesh declared ribs (issue #188): what it declared and what was placed. Absent otherwise, so a mesh without ribs writes the row it always wrote. */
   ribs?: RibsRow;
-  params: { tolerance: number; margin: number; spacing: number; budget: number | null; stray: number | null };
+  /** `maxEdge` only when the mesh declared it (issue #265), so a mesh without it writes the row it always wrote. */
+  params: { tolerance: number; margin: number; spacing: number; maxEdge?: number; budget: number | null; stray: number | null };
   contour: ContourReport;
   regions: Array<{ name: string; bone: string; reached: number; whole: number }>;
   /** Only under `rule: "heat"` (issue #161), as the lattice row's. */
@@ -1335,7 +1336,7 @@ export function buildRig(
         : { name: rg.name, shape: 'polygon', points: rg.points.map(([x, y]) => [x - ox, y - oy] as [number, number]), spacing: rg.spacing, band: rg.band },
     );
     const ribs = chainRibs(ribSpec.segments, ribSpec.ribs, ox, oy);
-    const cm = contourMesh(p.name, { width: w, height: h, alpha }, { threshold: ART_ALPHA, tolerance: spec.tolerance, margin: spec.margin, spacing: spec.spacing, budget: spec.budget, stray: spec.stray, regions: inPart, ...(ribs.length === 0 ? {} : { ribs }) });
+    const cm = contourMesh(p.name, { width: w, height: h, alpha }, { threshold: ART_ALPHA, tolerance: spec.tolerance, margin: spec.margin, spacing: spec.spacing, ...(spec.maxEdge === undefined ? {} : { maxEdge: spec.maxEdge }), budget: spec.budget, stray: spec.stray, regions: inPart, ...(ribs.length === 0 ? {} : { ribs }) });
     if (Array.isArray(cm)) {
       out.push(...cm);
       return null;
@@ -1401,7 +1402,7 @@ export function buildRig(
         mode: 'contour',
         ...(exponent === undefined ? {} : { exponent }),
         ...(ribSpec.ribs === undefined ? {} : { ribs: ribsRow(ribSpec.ribs, cm.ribs ?? []) }),
-        params: { tolerance: spec.tolerance, margin: spec.margin, spacing: spec.spacing, budget: spec.budget ?? null, stray: spec.stray ?? null },
+        params: { tolerance: spec.tolerance, margin: spec.margin, spacing: spec.spacing, ...(spec.maxEdge === undefined ? {} : { maxEdge: spec.maxEdge }), budget: spec.budget ?? null, stray: spec.stray ?? null },
         contour: rep,
         regions: regions.map((rg, k) => ({ name: rg.name, bone: rg.bone, reached: reached[k], whole: whole[k] })),
         ...(heat === null ? {} : { heat: heatRow(heat) }),

package/src/tags.ts

@@ -26,6 +26,22 @@
  * Nothing downstream classifies a part by its NAME. The role of a part — what
  * a proposer may do with it — is read from the tag it came from, which is why
  * `parts.json` records `from` for every part.
+ *
+ * ⭐ **An author-made layer** (issue #256) is a layer the author split or
+ * painted by hand outside the tool — a hand laid over a hip taken out of
+ * `handwear`, a loop of hair over a shoulder taken out of `back hair` — and
+ * added to a run. It is named `author:<label>` ({@link AUTHOR_PREFIX}), the
+ * label the author's own. It is not a See-through tag and carries no role:
+ * {@link readTag} never reads it, so no rule that reads roles from tags ever
+ * sees it, and every reader that admits a layer reads it through
+ * {@link readLayerTag}, which says `group: "author"`. Why a prefix and this
+ * one: a single reserved name would let a run hold one such layer (a tag
+ * names one layer, `LAYERS_NAME_UNIQUE`, and one layer makes one part); no
+ * v3 tag holds a colon, so the prefix cannot be read as a See-through tag or
+ * as one of its `-r`/`-l` halves; and `<origin>:<name>` is already how
+ * `parts.json` says "not a See-through layer" for a patch (`painting:<name>`).
+ * Every reader of a part's `from` splits at the first colon, so
+ * `full:author:hand` is the full run's layer `author:hand`.
  */
 
 export const BODY_TAGS = [
@@ -119,3 +135,73 @@ export function pairOf(name: string): string | null {
   if (t === null || t.side === null) return null;
   return `${t.base}-${t.side === 'r' ? 'l' : 'r'}`;
 }
+
+/** The prefix of an author-made layer's name (issue #256): `author:<label>`. */
+export const AUTHOR_PREFIX = 'author:';
+
+/** An author-made layer's name read: the label after {@link AUTHOR_PREFIX}, and no tag, so no role. */
+export interface AuthorTagReading {
+  /** The name as the layer carries it: `author:hand`. */
+  name: string;
+  /** What follows the prefix: the author's own word, read by nothing as a role. */
+  label: string;
+  group: 'author';
+}
+
+/** What a layer name reads as: a See-through v3 tag, or an author-made layer's name. */
+export type LayerTagReading = TagReading | AuthorTagReading;
+
+/** What an author-made layer's label must be, as a refusal quotes it. */
+export const AUTHOR_LABEL_RULE = 'a label that is not empty, does not start with "." or whitespace, does not end with whitespace, and holds no slash, backslash or colon';
+
+/**
+ * Whether `label` may follow {@link AUTHOR_PREFIX}. It becomes part of a part
+ * name the plan proposes and of a file name the wrapper form may look for
+ * (`parts/<name>.png`), so it is held to what a part name may be, and it holds
+ * no colon, so the name keeps exactly one.
+ */
+export function authorLabelOk(label: string): boolean {
+  return label !== '' && !label.startsWith('.') && label.trim() === label && !/[\\/:]/.test(label);
+}
+
+/** Read a layer name as an author-made layer's, or `null` when it is not one (no prefix, or a label {@link authorLabelOk} refuses). */
+export function readAuthorTag(name: string): AuthorTagReading | null {
+  if (!name.startsWith(AUTHOR_PREFIX)) return null;
+  const label = name.slice(AUTHOR_PREFIX.length);
+  return authorLabelOk(label) ? { name, label, group: 'author' } : null;
+}
+
+/** Read a layer name as a v3 tag or an author-made layer's name, or `null` when it is neither. */
+export function readLayerTag(name: string): LayerTagReading | null {
+  return readTag(name) ?? readAuthorTag(name);
+}
+
+/** Whether a tag string names an author-made layer. */
+export function isAuthorTag(name: string): boolean {
+  return readAuthorTag(name) !== null;
+}
+
+/**
+ * Why `name` is no layer tag, as the detail of a `*_TAG_KNOWN` refusal: an
+ * `author:` name whose label is refused says what the label must be; any
+ * other names the accepted v3 tags and the author form.
+ */
+export function layerTagRequirement(name: string): string {
+  if (name.startsWith(AUTHOR_PREFIX)) {
+    return `is an author-made layer's name with the label ${JSON.stringify(name.slice(AUTHOR_PREFIX.length))}; ${AUTHOR_LABEL_RULE} is required after "${AUTHOR_PREFIX}"`;
+  }
+  return `is not a See-through v3 tag; one of ${acceptedTagNames().join(', ')} is required, or "${AUTHOR_PREFIX}<label>" for a layer the author made`;
+}
+
+/**
+ * What every stage says of an author-made layer (issue #256), so it never
+ * reads as a See-through layer: `layers` prints it per layer, `assemble` per
+ * part, and `--propose-plan` and `propose` carry it in their notes.
+ */
+export const AUTHOR_NO_ROLE =
+  'an author-made layer, not a See-through one: no tag, so no role — it rides the bone the config gives it (config.regions.<part>, or a mesh in config.meshes), and its draw position is its place in config.assemble.plan';
+
+/** The `layers` line for an author-made layer. */
+export function authorLayerLine(name: string): string {
+  return `author-made: layer "${name}" — ${AUTHOR_NO_ROLE}`;
+}

package/src/turn.ts

@@ -30,6 +30,37 @@
  */
 import { pyRound } from './round.ts';
 
+/**
+ * The layers that ride on the face (issue #271): See-through makes no depth
+ * of their own for them, so `propose` does not read theirs. The eye group —
+ * eyewhite, irides, eyelash, eyebrow — is cut from one depth map predicted for
+ * the combined eyes layer (`compose_list` in See-through's
+ * `common/utils/inference_utils.py`, commit df019de), which is why
+ * `eyewhite-r` and `eyewhite-l` read the same median in every run measured
+ * for #251; nose and mouth are clamped by See-through to the face's median
+ * minus {@link TURN_RIDER_OFFSET} when they read behind it (the same file,
+ * lines 528-531). Their own medians disagreed across the two runs by up to
+ * 0.474 (demo `eyebrow-r`, #251's table), and the disagreement swapped their
+ * order against the face. Matched on the layer's base tag, either side.
+ */
+export const TURN_RIDER_TAGS: readonly string[] = ['eyewhite', 'irides', 'eyelash', 'eyebrow', 'nose', 'mouth'];
+
+/** The tag of the part the riders take their depth from. */
+export const TURN_CARRIER_TAG = 'face';
+
+/** See-through's own offset between a clamped face feature and the face (`face − 0.001`, the file named at {@link TURN_RIDER_TAGS}). */
+export const TURN_RIDER_OFFSET = 0.001;
+
+/**
+ * A rider's depth: its carrier's, {@link TURN_RIDER_OFFSET} nearer when the
+ * rider is drawn after the carrier (above it) and as much further when it is
+ * drawn before (under it), so the draw order the depths imply is the one
+ * parts.json holds.
+ */
+export function turnRiderDepth(carrier: number, above: boolean): number {
+  return above ? carrier - TURN_RIDER_OFFSET : carrier + TURN_RIDER_OFFSET;
+}
+
 /** The control bone the rig stage adds under `root` when the config has `turn`: nothing keys it, and its local x is the dial. */
 export const TURN_BONE = 'turn';