@rig-c/parts 1.9.1 → 1.10.0

package/src/check.ts

@@ -73,7 +73,7 @@
  */
 import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { basename, delimiter, dirname, join, resolve } from 'node:path';
-import { measureRecomposite, type RecompositeFigures, recompositeRecord, sourceInRig } from './assemble.ts';
+import { measureRecomposite, type RecompositeFigures, recompositeRecord, scenePhrase, sourceInRig } from './assemble.ts';
 import { cropToSpineY } from './coords.ts';
 import { PartsError, type Problem, refuseIfAny } from './errors.ts';
 import { framesInside, IDLE_FPS, TIME_SLACK } from './motion.ts';
@@ -200,6 +200,16 @@ export const BLINK_PATCH_LEVEL = SEAM_PX_LEVEL;
 /** The smallest lag the reading resolves, in cycles: phases are written to three places. */
 export const CHAIN_LAG_MIN_STEP = 0.001;
 export const TIP_RATIO_FLOOR = 1.4725;
+/**
+ * Issue #245: the bar a part the scene declares `rests` is held to — its tip
+ * half travels no further than its root half, tip / root <= 1, read at the
+ * line's precision (three places), and with a root that does not move, a tip
+ * that does not either. The declaration's own relation fixes it ("the tip's
+ * motion no greater than the root's"), a value the model fixes and not a
+ * margin: no example declares `rests`, so the floor-and-ceiling rule above
+ * has no figure to halve or double.
+ */
+export const TIP_REST_RATIO_CEILING = 1;
 /**
  * `TEXTURE_STRETCH`'s ceiling on max(ratio, 1/ratio) (issue #31): the worse
  * example's figure (demo, 1.388) squared. The ceiling rule is "twice the worse
@@ -1052,6 +1062,12 @@ export interface SeamFigures {
   mean: number;
   over40: number;
   over80: number;
+  /**
+   * Under a scene (issue #242), the frame pixels on the painting's border that the
+   * figures above leave out ({@link seamFigures}): how many there are, and how many
+   * of them were over {@link SEAM_PX_LEVEL}. Null when the painting is not a scene.
+   */
+  border: { framePx: number; over40: number } | null;
   /** The frame pixels {@link over40} counts, by index into the frame, ascending; each one's max-channel |d| is in {@link countedDiff}. */
   counted: number[];
   countedDiff: number[];
@@ -1135,6 +1151,16 @@ export function frameToRigMap(stage: StageBox, rigH: number, vp: Viewport): Scal
  *
  * `map` is for the controls alone (the `check` suite plants the map without
  * the centre term, issue #209); every caller in `src/` leaves it to the default.
+ *
+ * `scene` (issue #242; `parts.json`'s `scene` block): the painting is a scene,
+ * and a figure cut by its frame has an edge there that no part meets. A frame
+ * pixel whose bilinear sample of the composite reads the painting's outermost
+ * row or column, or past it — its two-by-two footprint, `floor(u)` and
+ * `floor(u) + 1` with `u = (x - tx) / sx`, reaching column 0 or `W - 1` or
+ * beyond, and the same for rows — is on the painting's border, and is not
+ * counted: not in the mean, not over either level. How many such pixels there
+ * were, and how many of them were over {@link SEAM_PX_LEVEL}, is returned
+ * (`border`) for the line to say.
  */
 export function seamFigures(
   composite: Raster,
@@ -1143,6 +1169,7 @@ export function seamFigures(
   vp: Viewport,
   background: readonly [number, number, number, number],
   map: ScaleTranslate = rigToFrameMap(stage, composite.height, vp),
+  scene = false,
 ): SeamFigures {
   const [W, H] = [composite.width, composite.height];
   const src = newFloatImage(W, H, 3);
@@ -1154,9 +1181,18 @@ export function seamFigures(
   let sum = 0;
   let over40 = 0;
   let over80 = 0;
+  let borderPx = 0;
+  let borderOver40 = 0;
   const counted: number[] = [];
   const countedDiff: number[] = [];
   const n = vp.pixelWidth * vp.pixelHeight;
+  // Issue #242: on a scene, the frame columns and rows whose composite sample reaches the painting's border.
+  const onEdge = (i: number, t: number, s: number, size: number): boolean => {
+    const k = Math.floor((i - t) / s);
+    return k <= 0 || k + 1 >= size - 1;
+  };
+  const edgeCol = scene ? Array.from({ length: vp.pixelWidth }, (_, x) => onEdge(x, map.tx, map.sx, W)) : null;
+  const edgeRow = scene ? Array.from({ length: vp.pixelHeight }, (_, y) => onEdge(y, map.ty, map.sy, H)) : null;
   for (let p = 0; p < n; p++) {
     let m = 0;
     for (let c = 0; c < 3; c++) {
@@ -1164,6 +1200,11 @@ export function seamFigures(
       const d = Math.abs(w - frame.data[p * 4 + c]);
       if (d > m) m = d;
     }
+    if (edgeCol !== null && edgeRow !== null && (edgeCol[p % vp.pixelWidth] || edgeRow[Math.floor(p / vp.pixelWidth)])) {
+      borderPx++;
+      if (m > SEAM_PX_LEVEL) borderOver40++;
+      continue;
+    }
     sum += m;
     if (m > SEAM_PX_LEVEL) {
       over40++;
@@ -1172,7 +1213,7 @@ export function seamFigures(
     }
     if (m > SEAM_PX_LEVEL_HIGH) over80++;
   }
-  return { mean: sum / n, over40, over80, counted, countedDiff, map };
+  return { mean: scene ? (n - borderPx === 0 ? 0 : sum / (n - borderPx)) : sum / n, over40, over80, border: scene ? { framePx: borderPx, over40: borderOver40 } : null, counted, countedDiff, map };
 }
 
 /**
@@ -1580,6 +1621,13 @@ export interface CheckFigures {
    * divided by its square ({@link seamRigPx}). Null with the other three.
    */
   seam_frame_scale: number | null;
+  /**
+   * Written only when `parts.json` declares a scene (issue #242): the frame pixels
+   * on the painting's border that the seam figures above leave out, and how many
+   * of them were over 40 ({@link seamFigures}). A painting that is not a scene
+   * writes the keys it always wrote.
+   */
+  seam_border?: { frame_px_left_out: number; px_over_40_left_out: number };
   /**
    * Written only when the seam bar fails, or when it was asked for (`check
    * --seam-pairs`), issue #202: the counted pixels split by the pair of parts
@@ -1887,7 +1935,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   if (full !== null) {
     try {
       breath = breathLine(full, isolated, problems, notPlanted);
-      if (idle !== null) tip = tipLine(full, join(idle.dir, GEOMETRY_FILE), idle.written, problems, reqFile === null ? NO_TIP_EXCEPTIONS : { path: reqFile.path, not_swinging: reqFile.not_swinging, rises: reqFile.rises });
+      if (idle !== null) tip = tipLine(full, join(idle.dir, GEOMETRY_FILE), idle.written, problems, reqFile === null ? NO_TIP_EXCEPTIONS : { path: reqFile.path, not_swinging: reqFile.not_swinging, rises: reqFile.rises, rests: reqFile.rests });
     } finally {
       rmSync(isoDir, { recursive: true, force: true });
     }
@@ -1896,7 +1944,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   let stretch: JudgementLine = skip(inp.noIdle ?? '');
   let still: JudgementLine = skip(lacking);
   if (idle !== null) {
-    chain = chainLine(inp, problems);
+    chain = chainLine(inp, problems, reqFile === null ? NO_CHAIN_RESTS : { path: reqFile.path, rests: reqFile.rests });
     // One reader for the one geometry file: the stretch reads its meshes, the still regions every slot and the head bone.
     const geometryPath = join(idle.dir, GEOMETRY_FILE);
     const geometry = readGeometry(geometryPath, idle.written);
@@ -1941,7 +1989,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
       if (keepStills) cpSync(join(stillDir, 'render'), keptDir, { recursive: true });
       if (inp.parts !== null) {
         const composite = flatComposite(inp.parts, inp.partsDir, stillSet.background);
-        seam = seamFigures(composite, stillSet.frames[0].image, inp.stage, stillSet.viewport, stillSet.background);
+        seam = seamFigures(composite, stillSet.frames[0].image, inp.stage, stillSet.viewport, stillSet.background, undefined, inp.parts.scene !== undefined);
         if (seamPairsAsked || seamFails(round3(seam.mean), seam.over40, round6(stillSet.viewport.scale))) {
           const placed = inp.parts.parts.map((p) => ({ name: p.name, from: p.from, x: p.x, y: p.y, image: readPng(join(inp.partsDir, `${p.name}.png`)) }));
           const split = seamPairRows(seam, placed, inp.parts.rig_size, stillSet.viewport);
@@ -2003,6 +2051,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     seam_px_over_40: seam === null ? null : seam.over40,
     seam_px_over_80: seam === null ? null : seam.over80,
     seam_frame_scale: seam === null || seamViewport === null ? null : round6(seamViewport.scale),
+    ...(seam === null || seam.border === null ? {} : { seam_border: { frame_px_left_out: seam.border.framePx, px_over_40_left_out: seam.border.over40 } }),
     ...(seamPairs === null ? {} : { seam_pairs: seamPairs }),
     BREATH_VISIBLE: breath,
     BLINK_NO_HOLE: blink,
@@ -2223,6 +2272,8 @@ export function holesLine(parts: PartsFile): ReportedLine {
   if (r === undefined) return { status: 'SKIP', reason: 'parts.json has no "recomposite" block (a parts.json the reference wrote has none); re-run assemble, which writes it' };
   return {
     status: 'REPORTED',
+    // Issue #242: a scene's figures were read inside the figure, and the line says so first.
+    ...(parts.scene === undefined ? {} : { declared_scene: scenePhrase(parts.scene, parts.rig_size[0] * parts.rig_size[1]) }),
     error_px: r.error_px,
     uncovered_error_px: r.uncovered_error_px,
     hole_count: r.hole_count,
@@ -2256,15 +2307,15 @@ type Isolate = (label: string, ps: readonly PartRecord[]) => FrameSet;
  * before anything is built: each name must be a part parts.json lists
  * (`REQUIREMENTS_RESOLVES`), and one the bar it relaxes reads — a `footwear`
  * part for `not_planted` (`REQUIREMENTS_NOT_PLANTED`), a `handwear` or
- * `bottomwear` part for `not_swinging` and `rises`
+ * `bottomwear` part for `not_swinging`, `rises` and `rests` (issue #245)
  * (`REQUIREMENTS_TIP_EXCEPTION`): an exception that excepts nothing is a miss,
  * refused by name. With no parts.json every name is refused. Whether a `rises`
  * part's chain does rise is read off the idle's geometry by `TIP_OVER_ROOT`.
  */
-export function exceptionProblems(file: Pick<RequirementsFile, 'not_planted' | 'not_swinging' | 'rises' | 'path'>, parts: PartsFile | null, noParts: string | null): Problem[] {
+export function exceptionProblems(file: Pick<RequirementsFile, 'not_planted' | 'not_swinging' | 'rises' | 'rests' | 'path'>, parts: PartsFile | null, noParts: string | null): Problem[] {
   const out: Problem[] = [];
-  // Issue #231: not_swinging and rises name swinging parts, the ones TIP_OVER_ROOT reads; whether a rises part's chain does rise is read off the idle's geometry, in the line.
-  for (const key of ['not_swinging', 'rises'] as const) {
+  // Issue #231: not_swinging and rises name swinging parts, the ones TIP_OVER_ROOT reads; whether a rises part's chain does rise is read off the idle's geometry, in the line. Issue #245: rests too.
+  for (const key of ['not_swinging', 'rises', 'rests'] as const) {
     file[key].forEach((name, i) => {
       const object = `${file.path} field "${key}"[${i}]`;
       if (parts === null) {
@@ -2369,14 +2420,15 @@ function breathLine(inp: FullInputs, isolated: Isolate, problems: Problem[], not
   };
 }
 
-/** The scene file's two exceptions to `TIP_OVER_ROOT` (issue #231), and the file they were read from, which a refusal names. */
+/** The scene file's exceptions to `TIP_OVER_ROOT` (issues #231, #245), and the file they were read from, which a refusal names. */
 export interface TipExceptions {
   path: string;
   not_swinging: readonly string[];
   rises: readonly string[];
+  rests: readonly string[];
 }
 
-const NO_TIP_EXCEPTIONS: TipExceptions = { path: '', not_swinging: [], rises: [] };
+const NO_TIP_EXCEPTIONS: TipExceptions = { path: '', not_swinging: [], rises: [], rests: [] };
 
 /**
  * What `TIP_OVER_ROOT` is measured with, written into its line (issue #118):
@@ -2402,6 +2454,12 @@ export const TIP_INSTRUMENT = 'geometry';
  * chain carrying each is measured to rise ({@link chainDirection}; refused by
  * name otherwise); both lists are the line's first figures. Without them the
  * line is the one written before.
+ *
+ * Issue #245: a part the scene declares `rests` — its tip at rest while its
+ * root moves — is measured with the same halves and held to the opposite
+ * relation: tip / root at most {@link TIP_REST_RATIO_CEILING}. Its row says
+ * so first (`declared: "rests"`), the list is the line's first figure after
+ * the other two, and the ceiling follows the floor.
  */
 function tipLine(inp: FullInputs, geometryPath: string, frames: number, problems: Problem[], excepted: TipExceptions = NO_TIP_EXCEPTIONS): JudgementLine {
   const swing = partsTagged(inp.parts, SWING_TAGS);
@@ -2435,21 +2493,30 @@ function tipLine(inp: FullInputs, geometryPath: string, frames: number, problems
       continue;
     }
     const rises = excepted.rises.includes(p.name);
+    const rests = excepted.rests.includes(p.name);
     const [rootHalf, tipHalf] = rises ? ['lower', 'upper'] : ['upper', 'lower'];
     const art = placedArt(p.x, p.y, readPng(join(inp.partsDir, `${p.name}.png`)));
     const shown = poses.map((f) => f.get(p.name) ?? null);
     const t = halfTravels(art, p, inp.stage, shown, rises ? 'up' : 'down');
     // A part not declared writes the row it wrote before issue #231; a declared one says which half is its tip's.
-    const said = rises ? { tip_half: tipHalf } : {};
+    const said = { ...(rests ? { declared: 'rests' } : {}), ...(rises ? { tip_half: tipHalf } : {}) };
     if (t.root === null || t.tip === null) {
       rows.push({ part: p.name, ...said, unmeasured: shown[0] === null ? 'its slot shows no attachment on idle frame 0' : `on idle frame 0 the ${t.root === null ? rootHalf : tipHalf} half of its box holds no art its attachment draws` });
       continue;
     }
     measured++;
     const ratio = t.root > 0 ? round3(t.tip / t.root) : null;
-    const ok = ratio === null ? t.tip > 0 : ratio >= TIP_RATIO_FLOOR;
+    // Issue #245: a resting tip is held to the opposite relation — no further than its root, at the line's precision.
+    const ok = rests ? (ratio === null ? round3(t.tip) === 0 : ratio <= TIP_REST_RATIO_CEILING) : ratio === null ? t.tip > 0 : ratio >= TIP_RATIO_FLOOR;
     rows.push({ part: p.name, ...said, root_rig_px: round3(t.root), tip_rig_px: round3(t.tip), ratio });
-    if (!ok) {
+    if (!ok && rests) {
+      failed = true;
+      problems.push({
+        code: 'CHECK_TIP_OVER_ROOT',
+        object: `part "${p.name}", box ${p.x},${p.y} ${p.w}x${p.h} rig px, posed by the idle's geometry, declared rests${rises ? ' and rises' : ''}`,
+        detail: `the art in its ${tipHalf} half travels ${round3(t.tip)} rig px and in its ${rootHalf} half ${round3(t.root)} rig px (ratio ${ratio ?? 'undefined: the root does not move'}); the scene file's rests declares its tip at rest, so a ratio <= ${TIP_REST_RATIO_CEILING} is required — the tip swings: the chain's amplitudes grow toward the tip, or the tip of the mesh is weighted to a bone the idle swings`,
+      });
+    } else if (!ok) {
       failed = true;
       // Issue #262: a root the breath carries is named with its carrier, not blamed on the chain.
       const carry = breathCarrier(inp.rig, inp.motion, p.name, geometryPath, frames, { art, box: p, stage: inp.stage, shown, toward: rises ? 'up' : 'down', root: t.root, tip: t.tip });
@@ -2468,9 +2535,10 @@ function tipLine(inp: FullInputs, geometryPath: string, frames: number, problems
   const declared = {
     ...(excepted.not_swinging.length === 0 ? {} : { declared_not_swinging: swing.filter((p) => excepted.not_swinging.includes(p.name)).map((p) => p.name) }),
     ...(excepted.rises.length === 0 ? {} : { declared_rises: swing.filter((p) => excepted.rises.includes(p.name)).map((p) => p.name) }),
+    ...(excepted.rests.length === 0 ? {} : { declared_rests: swing.filter((p) => excepted.rests.includes(p.name)).map((p) => p.name) }),
   };
   if (measured === 0) return { status: 'SKIP', reason: `none of ${quoteParts(swing)} could be measured: ${rows.map((r) => `${String(r.part)}: ${String(r.unmeasured)}`).join('; ')}` };
-  return { status: failed ? 'FAIL' : 'PASS', ...declared, instrument: TIP_INSTRUMENT, parts: rows, ratio_floor: TIP_RATIO_FLOOR };
+  return { status: failed ? 'FAIL' : 'PASS', ...declared, instrument: TIP_INSTRUMENT, parts: rows, ratio_floor: TIP_RATIO_FLOOR, ...(excepted.rests.length === 0 ? {} : { rest_ratio_ceiling: TIP_REST_RATIO_CEILING }) };
 }
 
 /**
@@ -2590,6 +2658,33 @@ function breathCarrier(
  * different ways.
  */
 export function chainDirection(rig: Record<string, unknown>, motion: Record<string, unknown>, part: string, origins: ReadonlyMap<string, { x: number; y: number }>): { toward: Toward; chains: string[] } | { none: string } {
+  const { found, bound } = chainsCarrying(rig, motion, part);
+  const boundText = [...bound].map((b) => `"${b}"`).join(', ') || 'no bone';
+  if (found.length === 0) return { none: `it rides no chain: none of the bones it is bound to (${boundText}) is under a chain of rotate-keyed links` };
+  const read = found.map((c) => {
+    const a = origins.get(c[0]);
+    const z = origins.get(c[c.length - 1]);
+    const label = c.join(' > ');
+    if (a === undefined || z === undefined) return { label, toward: null, text: `${label}: no setup-pose origin for ${a === undefined ? c[0] : c[c.length - 1]} in the idle's geometry` };
+    const dx = z.x - a.x;
+    const dy = z.y - a.y;
+    const toward = chainToward(dx, dy);
+    return { label, toward, text: `${label} ${toward ?? 'runs as far across as along'} (${round3(dx)}, ${round3(dy)} world px)` };
+  });
+  const ways = [...new Set(read.map((r) => r.toward))];
+  if (ways.length !== 1 || ways[0] === null) return { none: `its chains do not run one way: ${read.map((r) => r.text).join('; ')}` };
+  return { toward: ways[0], chains: read.map((r) => r.text) };
+}
+
+/**
+ * The chains that carry a part (issues #231, #245): the bones its attachments
+ * are bound to in the default skin ({@link boundBones}); the leaves among them
+ * — those with no other of them below — each walked up the bone tree to the
+ * first link of a chain `CHAIN_LAG` reads ({@link chainFigures}: two or more
+ * rotate-keyed links, each under the one before at one period). Each chain is
+ * its links' names from the root, once, in the order the leaves find them.
+ */
+export function chainsCarrying(rig: Record<string, unknown>, motion: Record<string, unknown>, part: string): { found: string[][]; bound: Set<string> } {
   const bones = (Array.isArray(rig.bones) ? rig.bones : []).filter(isRecord).filter((b) => typeof b.name === 'string');
   const parent = new Map(bones.map((b) => [String(b.name), typeof b.parent === 'string' ? b.parent : null]));
   const bound = boundBones(rig, part);
@@ -2617,21 +2712,7 @@ export function chainDirection(rig: Record<string, unknown>, motion: Record<stri
       }
     }
   }
-  const boundText = [...bound].map((b) => `"${b}"`).join(', ') || 'no bone';
-  if (found.length === 0) return { none: `it rides no chain: none of the bones it is bound to (${boundText}) is under a chain of rotate-keyed links` };
-  const read = found.map((c) => {
-    const a = origins.get(c[0]);
-    const z = origins.get(c[c.length - 1]);
-    const label = c.join(' > ');
-    if (a === undefined || z === undefined) return { label, toward: null, text: `${label}: no setup-pose origin for ${a === undefined ? c[0] : c[c.length - 1]} in the idle's geometry` };
-    const dx = z.x - a.x;
-    const dy = z.y - a.y;
-    const toward = chainToward(dx, dy);
-    return { label, toward, text: `${label} ${toward ?? 'runs as far across as along'} (${round3(dx)}, ${round3(dy)} world px)` };
-  });
-  const ways = [...new Set(read.map((r) => r.toward))];
-  if (ways.length !== 1 || ways[0] === null) return { none: `its chains do not run one way: ${read.map((r) => r.text).join('; ')}` };
-  return { toward: ways[0], chains: read.map((r) => r.text) };
+  return { found, bound };
 }
 
 /**
@@ -2945,10 +3026,34 @@ function fmt3(x: number): string {
   return x.toFixed(3);
 }
 
-/** (3) Down every chain the phase lags and the amplitude does not shrink, read off motion.json's rotate tracks. */
-export function chainLine(inp: Pick<CheckInputs, 'rig' | 'motion'>, problems: Problem[]): JudgementLine {
+/** The scene file's `rests` parts as `CHAIN_LAG` reads them (issue #245), and the file they were read from. */
+export interface ChainRests {
+  path: string;
+  rests: readonly string[];
+}
+
+const NO_CHAIN_RESTS: ChainRests = { path: '', rests: [] };
+
+/**
+ * (3) Down every chain the phase lags and the amplitude does not shrink, read off motion.json's rotate tracks.
+ *
+ * Issue #245: a chain that carries a part the scene file declares `rests` ({@link chainsCarrying}) is held to the
+ * opposite amplitude relation — non-increasing toward the tip, the tip moving no more than the root, as
+ * `TIP_OVER_ROOT` holds the part. The lag is not relaxed: the declaration says how far the tip moves, not when.
+ * The declared parts are the line's first figure (`declared_rests`), and the chains they hold, `resting_chains`,
+ * follow it; a declared part no chain carries is named in neither. Without the field the line is the one written
+ * before.
+ */
+export function chainLine(inp: Pick<CheckInputs, 'rig' | 'motion'>, problems: Problem[], declared: ChainRests = NO_CHAIN_RESTS): JudgementLine {
   const cf = chainFigures(inp.rig, inp.motion);
   const long = cf.chains.filter((c) => c.length >= 2);
+  // Issue #245: each resting chain by its first link, with the declared parts that ride it, in the file's order.
+  const resting = new Map<string, string[]>();
+  for (const part of declared.rests) {
+    for (const c of chainsCarrying(inp.rig, inp.motion, part).found) resting.set(c[0], [...(resting.get(c[0]) ?? []), part]);
+  }
+  const restingChains = long.filter((c) => resting.has(c[0].bone));
+  const said = declared.rests.length === 0 ? {} : { declared_rests: [...declared.rests], resting_chains: restingChains.map((c) => c.map((l) => l.bone).join(' > ')) };
   if (cf.edges.length === 0 && long.length === 0) {
     return skip(`no idle "rotate" track sits under another at the same period${cf.unread.length > 0 ? ` (unread, not sampled sines: ${cf.unread.join(', ')})` : ''}, so there is no chain to lag`);
   }
@@ -2961,9 +3066,21 @@ export function chainLine(inp: Pick<CheckInputs, 'rig' | 'motion'>, problems: Pr
     }
   }
   for (const c of long) {
+    const rests = resting.get(c[0].bone);
     for (let i = 1; i < c.length; i++) {
       const a = round3(c[i - 1].reading.amp);
       const b = round3(c[i].reading.amp);
+      if (rests !== undefined) {
+        if (b > a) {
+          violations.push(`"${c[i].bone}" swings ${fmt3(b)} over "${c[i - 1].bone}"'s ${fmt3(a)} in a chain declared resting`);
+          problems.push({
+            code: 'CHECK_CHAIN_LAG',
+            object: `bone "${c[i].bone}" in the chain from "${c[0].bone}", which carries ${rests.map((n) => `"${n}"`).join(', ')}, declared rests by ${declared.path}`,
+            detail: `amplitude ${fmt3(b)} above the link above's ${fmt3(a)}; non-increasing down the chain is required — the scene file's rests declares the tip at rest, so it moves no more than the root ("amps" shrink toward the tip)`,
+          });
+        }
+        continue;
+      }
       if (b < a) {
         violations.push(`"${c[i].bone}" swings ${fmt3(b)} under "${c[i - 1].bone}"'s ${fmt3(a)}`);
         problems.push({ code: 'CHECK_CHAIN_LAG', object: `bone "${c[i].bone}" in the chain from "${c[0].bone}"`, detail: `amplitude ${fmt3(b)} below the link above's ${fmt3(a)}; non-decreasing down the chain is required — "amps" grow toward the tip` });
@@ -2973,6 +3090,7 @@ export function chainLine(inp: Pick<CheckInputs, 'rig' | 'motion'>, problems: Pr
   const minStep = cf.edges.length === 0 ? null : round3(Math.min(...cf.edges.map((e) => e.step)));
   return {
     status: violations.length === 0 ? 'PASS' : 'FAIL',
+    ...said,
     chains: long.map((c) => `${c.map((l) => l.bone).join(' > ')}: period ${round3(c[0].reading.period)}s, phase ${c.map((l) => fmt3(l.reading.phase)).join(' ')}, amp ${c.map((l) => fmt3(l.reading.amp)).join(' ')}`),
     lags: cf.edges.map((e) => `${e.parent} > ${e.child} ${e.step >= 0 ? '+' : ''}${fmt3(e.step)}`),
     min_step: minStep,

package/src/config.ts

@@ -60,6 +60,17 @@
  * depth that stays put, both stated — `propose --full/--head` drafts them —
  * from which the rig stage derives every fraction ({@link checkTurn}).
  *
+ * 🖼️ **`scene` declares the painting a scene (issue #242).** An optional
+ * object, `{}` today: the painting holds the figure and its surroundings (a
+ * room, a ground), and See-through's full run holds only the figure. With it,
+ * `assemble` reads the recomposite inside the figure and writes the figure's
+ * mask, and `check` reads `RECOMPOSITE_HOLES` and the seam that way too, each
+ * line saying so first (`src/assemble.ts`, `sceneFigure`). It takes no field
+ * because nothing in it is the author's to choose: the figure is derived (the
+ * union of the full run's layers), and so is the threshold. A key in it that is
+ * not a record or an annotation is refused by name ({@link checkScene}); the
+ * object leaves room for a field a later issue gives it.
+ *
  * 🔗 **`motion.animations_from` is rig-c's too, verbatim (issue #183).** An
  * optional path, relative to the config file's directory, to a file in
  * rig-c's motion-spec shape whose `animations` are written into `motion.json`
@@ -79,7 +90,7 @@ import { RIG_SKIN_CONSTRAINT_KEYS, type RigConstraint, type RigSkinConstraintKey
 import { GRID, MAX_SIDE } from './contour.ts';
 import { type Problem, refuseIfAny } from './errors.ts';
 import { isSkeletonName, KEYPOINT_NAMES, type KeypointName, type PosePoints, SKELETON_NAMES, type SkeletonName } from './skeleton.ts';
-import { acceptedTagNames, readTag } from './tags.ts';
+import { acceptedTagNames, AUTHOR_LABEL_RULE, AUTHOR_PREFIX, readLayerTag } from './tags.ts';
 import { TURN_BONE, type TurnSpec, turnNearest } from './turn.ts';
 
 export type Point = [number, number];
@@ -301,6 +312,8 @@ export interface ContourSpec {
   margin: number;
   /** The background interior spacing, px, above 0. */
   spacing: number;
+  /** The longest outline edge, px (issue #265): a longer simplified edge is cut into equal pieces; absent cuts nothing. */
+  maxEdge?: number;
   /** The most vertices the mesh may have; absent is no budget. */
   budget?: number;
   /** The largest island, in art pixels, that may be left out of the mesh; absent leaves none out. */
@@ -612,8 +625,13 @@ export interface CharacterConfig {
   constraints?: ConfigConstraint[];
   /** The turn control (issue #251, `src/turn.ts`): absent, no control is added and no byte of any output moves. */
   turn?: TurnSpec;
+  /** The painting is a scene (issue #242): absent, no byte of any output moves. */
+  scene?: SceneSpec;
 }
 
+/** `config.scene` (issue #242): the declaration that the painting is a scene. It holds no field today. */
+export type SceneSpec = Readonly<Record<string, unknown>>;
+
 /** The fields of one constraint kind, as rig-c's interface for that kind declares them. */
 type ConstraintField<K extends RigSkinConstraintKey> = Exclude<keyof Extract<RigConstraint, { type: K }>, number | symbol>;
 
@@ -891,9 +909,10 @@ export interface AssembleConfig {
   key: string;
   seethrough: SeeThrough;
   assemble: Assemble;
+  scene?: SceneSpec;
 }
 
-const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'turn'] as const;
+const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'turn', 'scene'] as const;
 
 /**
  * The one partial entry point. It validates exactly what its door requires —
@@ -943,6 +962,7 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
   if (door === 'assemble') {
     if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
     if ('assemble' in t) checkAssemble(c, t.assemble, door);
+    if ('scene' in t) checkScene(c, t.scene);
   }
   const pose = base === null ? null : poseBeside(c, t.generation, base);
   refuseIfAny(c.problems);
@@ -1095,6 +1115,7 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   if ('motion' in t) checkMotion(c, t.motion, names.bones, names.chains, 'regions' in t ? t.regions : undefined);
   if ('constraints' in t) checkConstraints(c, t.constraints, names.bones, names.parents);
   if ('turn' in t) checkTurn(c, t.turn, attachedParts(t.meshes, t.regions), names.bones);
+  if ('scene' in t) checkScene(c, t.scene);
   const from = isPlainObject(t.motion) ? t.motion.animations_from : undefined;
   const animations = base !== null && typeof from === 'string' && from !== '' ? readAnimationsFrom(c, resolve(base, from)) : null;
   if (base !== null) poseBeside(c, t.generation, base);
@@ -1399,8 +1420,10 @@ function checkSeeThrough(c: Check, v: Json): void {
 
 function checkRunTag(c: Check, path: string, run: Json, tag: Json): void {
   if (run !== 'full' && run !== 'head') c.fail('CONFIG_FIELD_TYPE', `${path} run`, `is ${show(run)}; "full" or "head" is required`);
-  if (typeof tag !== 'string' || readTag(tag) === null) {
-    c.fail('CONFIG_TAG_KNOWN', `${path} tag`, `is ${show(tag)}; a See-through v3 tag is required — one of ${acceptedTagNames().join(', ')}`);
+  // Issue #256: an author-made layer's `author:<label>` is a tag the readers admit, with no role.
+  if (typeof tag !== 'string' || readLayerTag(tag) === null) {
+    const label = typeof tag === 'string' && tag.startsWith(AUTHOR_PREFIX) ? `; after "${AUTHOR_PREFIX}", ${AUTHOR_LABEL_RULE}` : '';
+    c.fail('CONFIG_TAG_KNOWN', `${path} tag`, `is ${show(tag)}; a See-through v3 tag is required — one of ${acceptedTagNames().join(', ')} — or "${AUTHOR_PREFIX}<label>" for a layer the author made${label}`);
   }
 }
 
@@ -1756,7 +1779,7 @@ function checkRibs(c: Check, at: string, m: Record<string, Json>, chains: Map<st
 
 /**
  * `meshes.<part>.contour` (issue #84). `tolerance`, `margin` and `spacing` are
- * required — nothing is defaulted; `budget`, `stray` and `regions` are
+ * required — nothing is defaulted; `maxEdge`, `budget`, `stray` and `regions` are
  * optional, and an absent one is "none", not a guessed value. What the outline
  * itself refuses (a band that folds a polygon, a spacing whose keep radius
  * snaps to nothing) is `src/contour.ts`'s, at the rig stage, in its words;
@@ -1764,13 +1787,14 @@ function checkRibs(c: Check, at: string, m: Record<string, Json>, chains: Map<st
  * the grid every region number must sit on.
  */
 function checkContour(c: Check, at: string, v: Json, bones: Set<string>): void {
-  const o = c.object(at, v, ['tolerance', 'margin', 'spacing'], ['budget', 'stray', 'regions']);
+  const o = c.object(at, v, ['tolerance', 'margin', 'spacing'], ['maxEdge', 'budget', 'stray', 'regions']);
   if (o === null) return;
   if ('tolerance' in o) c.number(`${at}.tolerance`, o.tolerance, 'non-negative');
   if ('margin' in o && c.number(`${at}.margin`, o.margin, 'non-negative') && (o.margin as number) > 0 && (o.margin as number) < 1) {
     c.fail('CONFIG_FIELD_TYPE', `${at}.margin`, `is ${o.margin as number}; 0, or 1 px or more, is required — the outline's silhouette grows by the pixels whose centre lies within the margin of an art pixel's centre, and none lies closer than 1 px, so a margin under 1 px would add nothing`);
   }
   if ('spacing' in o) c.number(`${at}.spacing`, o.spacing, 'positive');
+  if ('maxEdge' in o) c.number(`${at}.maxEdge`, o.maxEdge, 'positive');
   if ('budget' in o) c.int(`${at}.budget`, o.budget, 3);
   if ('stray' in o) c.int(`${at}.stray`, o.stray, 0);
   if (!('regions' in o) || !c.array(`${at}.regions`, o.regions, false)) return;
@@ -2318,6 +2342,28 @@ function attachedParts(meshes: Json, regions: Json): Set<string> {
  * - `CONFIG_TURN_BONE_FREE`: `bones` declares a bone named {@link TURN_BONE},
  *   the control the rig stage adds.
  */
+/**
+ * `config.scene` (issue #242): an object, and today one with no field — a key
+ * that is not a record (`x-…`) or an annotation (`note`, `…_note`) is
+ * `CONFIG_KEY_KNOWN`, naming the key and saying the object is the whole
+ * declaration. Not `true`: an object is what a later field can be added to
+ * without changing what an existing config means.
+ */
+function checkScene(c: Check, v: Json): void {
+  if (!isPlainObject(v)) {
+    c.fail('CONFIG_FIELD_TYPE', 'config.scene', `is ${show(v)}; an object is required — {} declares the painting a scene`);
+    return;
+  }
+  for (const key of Object.keys(v)) {
+    if (isRecordKey(key)) continue;
+    if (key === 'note' || key.endsWith('_note')) {
+      if (typeof v[key] !== 'string') c.fail('CONFIG_FIELD_TYPE', `config.scene.${key}`, `is ${show(v[key])}; an annotation is a string`);
+      continue;
+    }
+    c.fail('CONFIG_KEY_KNOWN', `config.scene.${key}`, `is not a field here; scene takes no field — {} is the whole declaration (the figure and its threshold are derived, not chosen) — ${DOORS}`);
+  }
+}
+
 function checkTurn(c: Check, v: Json, attached: Set<string>, bones: Set<string>): void {
   const at = 'config.turn';
   const o = c.object(at, v, ['pivot', 'depths'], []);

package/src/contour.ts

@@ -35,7 +35,9 @@
  *    pixels, so its trace cannot cross itself; a notch narrower than about
  *    twice the margin grows shut. A margin above 0 and below 1 px adds no
  *    pixel and is refused by name. This module does not raise a margin by
- *    itself: a margin that clips art is refused (`CONTOUR_COVERAGE`).
+ *    itself: a margin that clips art is refused (`CONTOUR_COVERAGE`). With
+ *    `maxEdge` declared (issue #265), every simplified edge longer than it is
+ *    then cut into equal pieces ({@link capOutlineEdges}); undeclared, nothing is.
  * 4. **Interior vertices are declared**, never inferred: see
  *    {@link interiorCandidates} for the candidates and {@link KEEP_FRACTION}
  *    for the one rule that keeps or drops each. Where the outline passes
@@ -141,6 +143,7 @@
  * automatic mode hands these triangles to rig-c as they are.
  */
 import { type Problem } from './errors.ts';
+import { edgeLength } from './length.ts';
 import { counterClockwiseInSpineWorld } from './mesh.ts';
 import { connectedComponents, fillHoles, type Mask } from './raster/index.ts';
 import {
@@ -224,6 +227,12 @@ export interface ContourParams {
   margin: number;
   /** The background interior spacing, px, above 0. */
   spacing: number;
+  /**
+   * The longest outline edge, px (issue #265): every edge of the simplified outline longer than this is cut into
+   * `ceil(length / maxEdge)` equal pieces ({@link capOutlineEdges}), before any region or rib touches the outline.
+   * Absent, nothing is cut and the mesh is byte for byte the one it was before the field existed; there is no default.
+   */
+  maxEdge?: number;
   /** Refuse a mesh with more vertices than this; absent is no budget. */
   budget?: number;
   /**
@@ -330,6 +339,8 @@ export interface ContourReport {
   grownHolePixels: number;
   /** Only when ribs were declared (issue #188): every rib, in placement order, with its vertices. Absent otherwise, so a mesh without ribs reports what it always reported. */
   ribs?: ContourRib[];
+  /** Only when `maxEdge` was declared (issue #265): the outline vertices the cap added. Absent otherwise, so a mesh without it reports what it always reported. */
+  outlineCut?: number;
 }
 
 export interface ContourMesh {
@@ -382,6 +393,10 @@ function parameterProblems(part: string, mask: AlphaMask, p: ContourParams): Pro
     else if (keepRadius(s) > MAX_RADIUS) bad(field, `is ${s}; its keep radius is ${keepRadius(s)} grid units, past the ${MAX_RADIUS} (${MAX_RADIUS / GRID} px) whose square is exact in a double`);
   };
   spacingOk('spacing', p.spacing);
+  // issue #265: a cut piece must be longer than one grid unit, so two cut points never snap onto one another.
+  if (p.maxEdge !== undefined && (!finite(p.maxEdge) || p.maxEdge * GRID < 2)) {
+    bad('maxEdge', `is ${p.maxEdge}; a number of px of at least 2/${GRID} is required — each edge is cut into pieces longer than half of it, and a piece must be longer than one 1/${GRID} px grid unit for its two ends to stay apart once snapped`);
+  }
   if (p.budget !== undefined && (!Number.isInteger(p.budget) || p.budget < 3)) bad('budget', `is ${p.budget}; a whole number of vertices, 3 or more, is required`);
   if (p.fitConnectivity !== undefined && p.fitConnectivity !== 4 && p.fitConnectivity !== 8) bad('fitConnectivity', `is ${JSON.stringify(p.fitConnectivity)}; 4 or 8 is required (how the background is flooded when overshoot is measured)`);
   if (p.stray !== undefined && (!Number.isInteger(p.stray) || p.stray < 0)) bad('stray', `is ${p.stray}; a whole number of art pixels, 0 or more, is required (the largest island that may be left out)`);
@@ -736,6 +751,26 @@ export function outlineInRegions(outline: ReadonlyArray<readonly [number, number
   return out;
 }
 
+/**
+ * An outline with every edge longer than `maxEdge` px cut into `n = ceil(length / maxEdge)` equal pieces (issue
+ * #265): between each edge's two ends, the points `a + (b − a)·k/n` for k = 1..n−1, each snapped to the {@link GRID}.
+ * Every vertex of the outline is kept, in the same cyclic order and position from index 0, and an edge at or under
+ * `maxEdge` gains nothing. The length is {@link edgeLength}'s. The snap moves a cut point off its edge by at most
+ * half a grid unit (1/512 px); the mesh's topology and coverage checks read the cut outline as they read any other.
+ * The measured reference is `capOutline` in `tools/outline_survey.ts` (issue #265, (G′)), which this states in `src/`.
+ */
+export function capOutlineEdges(outline: ReadonlyArray<readonly [number, number]>, maxEdge: number): Array<[number, number]> {
+  const out: Array<[number, number]> = [];
+  for (let i = 0; i < outline.length; i++) {
+    const [ax, ay] = outline[i];
+    const [bx, by] = outline[(i + 1) % outline.length];
+    out.push([ax, ay]);
+    const n = Math.ceil(edgeLength(bx - ax, by - ay) / maxEdge);
+    for (let k = 1; k < n; k++) out.push([snap(ax + ((bx - ax) * k) / n) / GRID, snap(ay + ((by - ay) * k) / n) / GRID]);
+  }
+  return out;
+}
+
 /**
  * The keep rule ({@link KEEP_FRACTION}) over the candidates in order, against
  * an outline in grid units. Exact: inside by the crossing rule on integers,
@@ -1767,7 +1802,9 @@ export function contourMesh(part: string, mask: AlphaMask, params: ContourParams
   const stage = contourOutline(part, filled, threshold, tolerance, margin);
   if (Array.isArray(stage)) return stage;
   const { grown } = stage;
-  let outline = outlineInRegions(stage.outline, params.regions);
+  // issue #265: the cap cuts the simplified outline's long edges first; undeclared, the outline is the stage's own.
+  const capped = params.maxEdge === undefined ? stage.outline : capOutlineEdges(stage.outline, params.maxEdge);
+  let outline = outlineInRegions(capped, params.regions);
   // issue #188: the ribs' ends join the outline, and their interior points come first among the interior vertices.
   // None declared, nothing here runs and every list below is the one it always was.
   let ribs: RibPlacement | null = null;
@@ -1854,6 +1891,7 @@ export function contourMesh(part: string, mask: AlphaMask, params: ContourParams
       pinchFilledPixels: grown.pinchFilledPixels,
       grownHolePixels: stage.grownHolePixels,
       ...(ribs === null ? {} : { ribs: ribs.ribs }),
+      ...(params.maxEdge === undefined ? {} : { outlineCut: capped.length - stage.outline.length }),
     },
   };
 }