@rig-c/parts 1.17.0 → 1.18.0

package/src/build.ts

@@ -43,7 +43,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { type AnimFrame, EncodeError, encodeApng, encodeIndexedApng, INDEXED_DEFAULTS } from './apng.ts';
-import { assemble, type AssembleResult, cutLines, driftLine, limbLines, FIGURE_MASK_FILE, figuresLine, holeLines, type ProjectRule, scenePhrase, type SeamRule, stageFields, uncoveredLine } from './assemble.ts';
+import { assemble, type AssembleResult, cutLines, hiddenLines, SINGLE_RUN_FACE_TAGS, driftLine, limbLines, FIGURE_MASK_FILE, figuresLine, holeLines, type ProjectRule, scenePhrase, type SeamRule, stageFields, uncoveredLine } from './assemble.ts';
 import { allocationClause, type Reducer, stageBClause, unboundedClause } from './automesh.ts';
 import { residualClause } from './autoenvelope.ts';
 import { type AutoMotionCase, failingRows, idleSchedule, localRow, motionClause, motionDeformation, motionDocument, motionInput, motionRowText, motionStimulus, motionVerdict, noStimulusProblem, type ReplayCandidate, runComparison, sourceSelfFailure, stimulusMotion, withStimulus } from './automotion.ts';
@@ -78,7 +78,7 @@ import { encodeGif } from './gif.ts';
 import { CONTROL_SUFFIX, withAnimations } from './motion.ts';
 import type { PaletteError } from './palette.ts';
 import { type LayerSet, readLayers } from './layers.ts';
-import { type PartRecord, readParts, tagOf, writeParts } from './parts.ts';
+import { type PartRecord, readParts, type SingleRunPad, tagOf, writeParts } from './parts.ts';
 import { encodePngBytes, readPng, writePng } from './raster/png.ts';
 import type { Raster } from './raster/types.ts';
 import { readRequirements, type RequirementLine, summaryText } from './requirements.ts';
@@ -106,8 +106,12 @@ export function readSource(path: string): Raster {
   }
 }
 
-/** Read both runs, collecting the refusals of both before throwing. */
-export function readRuns(full: string, head: string): { full: LayerSet; head: LayerSet } {
+/**
+ * Read both runs, collecting the refusals of both before throwing. With no
+ * head run (`head` null, issue #359) the full run is read once and stands for
+ * both, and `single` says so: the stage then holds it to `checkSingleRun`.
+ */
+export function readRuns(full: string, head: string | null): { full: LayerSet; head: LayerSet; single: boolean } {
   const problems: Problem[] = [];
   const one = (path: string): LayerSet | null => {
     try {
@@ -121,15 +125,16 @@ export function readRuns(full: string, head: string): { full: LayerSet; head: La
     }
   };
   const f = one(full);
-  const h = one(head);
+  const h = head === null ? f : one(head);
   if (problems.length > 0) throw new PartsError(problems);
-  return { full: f as LayerSet, head: h as LayerSet };
+  return { full: f as LayerSet, head: h as LayerSet, single: head === null };
 }
 
 export interface AssembleStageInput {
   source: string;
   full: string;
-  head: string;
+  /** The head run, or null for one run that holds the face (issue #359). */
+  head: string | null;
   config: string;
   seam: SeamRule;
   project: ProjectRule;
@@ -236,7 +241,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   const runs = readRuns(input.full, input.head);
   // The early door: assemble runs before propose has drafted bones, meshes,
   // regions and motion, so it requires only what it reads (issue #20).
-  const fields = stageFields(loadEarlyConfig(input.config, 'assemble'));
+  const fields = stageFields(loadEarlyConfig(input.config, 'assemble'), runs.single ? { w: src.width, h: src.height } : null);
   const under = readUnders(input.config, fields.cuts);
   const caps = fields.limbs === undefined ? undefined : readCaps(input.config, fields.limbs);
   const result = assemble({ source: src, full: runs.full, head: runs.head, ...fields, under, ...(caps === undefined ? {} : { caps }), seamRule: input.seam, projectRule: input.project });
@@ -254,6 +259,11 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   if (figurePath !== null) writePng(figurePath, result.figure as Raster);
   const [W, H] = result.parts.rig_size;
   log(`rig-parts assemble: ${result.images.length} part(s) on a ${W}x${H} rig (${result.parts.scale_rig_per_source} rig px per source px), seam rule ${result.seamRule}, projection rule ${result.projectRule}`);
+  // Issue #359: one run, said, so a reader of the lines knows no head run was placed.
+  if (runs.single) log(`  one run: ${input.full} holds the face (${SINGLE_RUN_FACE_TAGS.join(', ')}), so no head run is read; every part comes from the full run`);
+  // Issue #366: a file that is not the resolution square was padded to it; said, with where parts.json records it. None for a square file.
+  const pad = result.parts.single_run_pad;
+  if (pad !== undefined) log(singleRunPadLine(input.full, pad));
   for (const p of result.parts.parts) {
     log(
       `  ${p.name.padEnd(11)} ${p.from.padEnd(16)} ${`${p.w}x${p.h}`.padEnd(9)} @${String(p.x).padStart(4)},${String(p.y).padStart(4)} ` +
@@ -268,6 +278,8 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   // Issue #349: one line per part a limb took, and one per joint with its cap's pixels. None without limbs.
   for (const l of limbLines(result.limbs)) log(l);
   for (const l of fringeLines(result.parts.parts)) log(l);
+  // Issue #359: one line per hidden-art layer and what read it. None without one.
+  for (const l of hiddenLines(result.hidden)) log(l);
   const total = (k: 'opaque_px' | 'visible_px' | 'occluded_px' | 'source_px_taken' | 'visible_not_projected_px'): number => result.parts.parts.reduce((a, p) => a + (p[k] ?? 0), 0);
   const [op, vis, occ, taken, unproj] = (['opaque_px', 'visible_px', 'occluded_px', 'source_px_taken', 'visible_not_projected_px'] as const).map(total);
   const pct = (n: number): string => `${((100 * n) / op).toFixed(1)}%`;
@@ -286,6 +298,16 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   return result;
 }
 
+/**
+ * The line `assemble` prints under `one run:` when the file was padded (issue
+ * #366): its size, the square and the four margins, and that `parts.json`'s
+ * `single_run_pad` records them.
+ */
+export function singleRunPadLine(file: string, pad: SingleRunPad): string {
+  const [w, h] = pad.file_size;
+  return `  padded: ${file} is ${w}x${h}, centred on the ${pad.side}x${pad.side} run square (left ${pad.left}, right ${pad.side - w - pad.left}, top ${pad.top}, bottom ${pad.side - h - pad.top}); parts.json single_run_pad records it, and every part's box is in the file's pixels times scale_rig_per_source`;
+}
+
 /**
  * The scale the per-part line prints `drift=` with (issue #314): `refused_drift_px` counts the part's projection
  * candidates (`projected_core_px`, the `src=` column's second figure) refused because See-through's colour sits more
@@ -1421,7 +1443,8 @@ export interface BuildInput {
   config: string;
   source: string;
   full: string;
-  head: string;
+  /** The head run, or null for one run that holds the face (issue #359). */
+  head: string | null;
   out: string;
   seam: SeamRule;
   project: ProjectRule;

package/src/inputs.ts

@@ -59,7 +59,17 @@ export interface SquarePad {
  * At most one of the two margins is non-zero.
  */
 export function squarePad(w: number, h: number): SquarePad {
-  const side = Math.max(w, h);
+  return padToSquare(w, h, Math.max(w, h));
+}
+
+/**
+ * The same centring on a square of a given `side` (issue #366): a single run's
+ * file padded to the `seethrough.resolution` square. Each margin floors, so an
+ * odd remainder goes to the right or the bottom, exactly as {@link squarePad};
+ * both margins are non-zero when both sides are below `side`. The caller has
+ * refused a side above `side` — padding cannot shrink a canvas.
+ */
+export function padToSquare(w: number, h: number, side: number): SquarePad {
   return { side, left: Math.floor((side - w) / 2), top: Math.floor((side - h) / 2) };
 }
 

package/src/layers.ts

@@ -31,13 +31,13 @@
  * (`src/tags.ts`, `AUTHOR_PREFIX`): read with `group` "author", it has no
  * role, and its place in the draw order is read like any other layer's.
  */
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
-import { initializeCanvas, type Layer as PsdLayer, readPsd } from 'ag-psd';
+import { initializeCanvas, type Layer as PsdLayer, readPsd, writePsd } from 'ag-psd';
 import { type Problem, refuseIfAny } from './errors.ts';
-import { decodePngBytes } from './raster/png.ts';
+import { decodePngBytes, encodePngBytes } from './raster/png.ts';
 import type { Raster } from './raster/types.ts';
-import { type LayerTagReading, layerTagRequirement, readLayerTag } from './tags.ts';
+import { BODY_TAGS, HEAD_TAGS, HIDDEN_NAME_RULE, type LayerTagReading, layerTagRequirement, readHiddenTag, readLayerTag, SPLIT_TAGS } from './tags.ts';
 
 /** Alpha strictly above this counts as painted. The reference uses the same cut for its ghost clean-up and its sheets. */
 export const OPAQUE_ALPHA_ABOVE = 8;
@@ -69,6 +69,26 @@ export interface Layer {
   opaquePx: number;
 }
 
+/**
+ * A hidden-art layer (issue #359, `HIDDEN_SUFFIX` in `src/tags.ts`): the art
+ * of the layer `of` where something covers it. Never drawn and never a part,
+ * so it carries no tag reading, no depth and no draw order.
+ */
+export interface HiddenLayer {
+  /** `<of>:hidden`. */
+  name: string;
+  /** The drawn layer of the same input it belongs to. */
+  of: string;
+  /** The file the pixels came from, or null for a PSD layer. */
+  file: string | null;
+  pixels: Raster;
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+  opaquePx: number;
+}
+
 export interface LayerSet {
   form: 'wrapper' | 'psd';
   /** The manifest or PSD that was read. */
@@ -76,6 +96,8 @@ export interface LayerSet {
   canvas: { w: number; h: number };
   /** In draw order, back to front. */
   layers: Layer[];
+  /** The hidden-art layers (issue #359), in the order the input lists them; empty when it holds none. */
+  hidden: HiddenLayer[];
 }
 
 function opaque(r: Raster): number {
@@ -101,6 +123,15 @@ const MANIFEST_REQUIRED = ['layers', 'width', 'height'] as const;
 const LAYER_KEYS = ['name', 'filename', 'left', 'top', 'right', 'bottom', 'depth_median', 'depth_filename'] as const;
 const LAYER_REQUIRED = ['name', 'filename', 'left', 'top', 'right', 'bottom', 'depth_median'] as const;
 
+/**
+ * What the wrapper form's `depth_median` may be, as a refusal quotes it. A
+ * See-through run writes a number; an input with no depth — a PSD exported by
+ * `layers --export` (issue #359) — writes `null` for every drawn layer, and
+ * its draw order is then the manifest's order, back to front, exactly as a
+ * PSD's is its stacking order. A depth is never invented for it.
+ */
+const DEPTH_RULE = 'a finite number (See-through\'s depth, larger = further back), or null on every drawn layer of an input that carries no depth (the manifest\'s order is then the draw order, back to front)';
+
 /**
  * Read the wrapper form from a directory holding `layers.json`, or from the
  * manifest path itself.
@@ -166,6 +197,7 @@ export function readWrapperLayers(path: string): LayerSet {
   if (entries.length === 0) refuse('LAYERS_FIELD_PRESENT', `${manifestPath} field "layers"`, 'is empty; at least one layer is required');
 
   const read: Array<Omit<Layer, 'drawOrder'> & { index: number }> = [];
+  const hidden: HiddenLayer[] = [];
   const seen = new Map<string, number>();
   entries.forEach((entry, index) => {
     const at = `${basename(manifestPath)} layers[${index}]`;
@@ -202,8 +234,9 @@ export function readWrapperLayers(path: string): LayerSet {
       return;
     }
     const name = e.name;
-    const tag = readLayerTag(name);
-    if (tag === null) {
+    const hiddenOf = readHiddenTag(name);
+    const tag = hiddenOf === null ? readLayerTag(name) : null;
+    if (tag === null && hiddenOf === null) {
       refuse('LAYERS_TAG_KNOWN', `layer "${name}"`, layerTagRequirement(name));
       ok = false;
     }
@@ -213,15 +246,20 @@ export function readWrapperLayers(path: string): LayerSet {
         ok = false;
       }
     }
-    if (typeof e.depth_median !== 'number' || !Number.isFinite(e.depth_median)) {
-      refuse('LAYERS_FIELD_PRESENT', `layer "${name}" field "depth_median"`, `is ${describe(e.depth_median)}; a finite number is required`);
+    if (hiddenOf !== null) {
+      if (e.depth_median !== null) {
+        refuse('LAYERS_HIDDEN_NO_DEPTH', `layer "${name}" field "depth_median"`, `is ${describe(e.depth_median)}; a hidden-art layer is never drawn, so it has no depth and null is required`);
+        ok = false;
+      }
+    } else if (e.depth_median !== null && (typeof e.depth_median !== 'number' || !Number.isFinite(e.depth_median))) {
+      refuse('LAYERS_FIELD_PRESENT', `layer "${name}" field "depth_median"`, `is ${describe(e.depth_median)}; ${DEPTH_RULE} is required`);
       ok = false;
     }
     if (typeof e.filename !== 'string' || e.filename === '') {
       refuse('LAYERS_FIELD_PRESENT', `layer "${name}" field "filename"`, `is ${describe(e.filename)}; a file name is required`);
       ok = false;
     }
-    if (!ok || tag === null) return;
+    if (!ok || (tag === null && hiddenOf === null)) return;
     const left = e.left as number;
     const top = e.top as number;
     const right = e.right as number;
@@ -261,31 +299,53 @@ export function readWrapperLayers(path: string): LayerSet {
       );
       return;
     }
+    if (hiddenOf !== null) {
+      hidden.push({ name, of: hiddenOf.of, file: present[0], pixels, left, top, right, bottom, opaquePx: opaque(pixels) });
+      return;
+    }
     read.push({
       name,
-      tag,
+      tag: tag as LayerTagReading,
       file: present[0],
       pixels,
       left,
       top,
       right,
       bottom,
-      depth: e.depth_median as number,
+      depth: e.depth_median as number | null,
       opaquePx: opaque(pixels),
       index,
     });
   });
+  // Issue #359: depth on every drawn layer, or on none — a mix has no one order to draw by.
+  const withDepth = read.filter((l) => l.depth !== null);
+  if (withDepth.length > 0 && withDepth.length < read.length) {
+    const none = read.filter((l) => l.depth === null).map((l) => `"${l.name}"`);
+    refuse('LAYERS_DEPTH_ALL_OR_NONE', manifestPath, `${withDepth.length} drawn layer(s) carry a depth_median and ${none.length} carry null (${none.join(', ')}); a number on every drawn layer, or null on every one, is required — a mix has no one draw order`);
+  }
+  checkHiddenOf(hidden, read.map((l) => l.name), (l) => `layer "${l}"`, refuse);
   refuseIfAny(problems);
-  // Stable: Array.prototype.sort is stable, so equal depths keep manifest order.
-  const ordered = [...read].sort((a, b) => (b.depth as number) - (a.depth as number));
+  // Stable: Array.prototype.sort is stable, so equal depths keep manifest order — and with no depth at all (every
+  // depth null), the manifest's own order is the draw order.
+  const ordered = withDepth.length === 0 ? read : [...read].sort((a, b) => (b.depth as number) - (a.depth as number));
   return {
     form: 'wrapper',
     source: manifestPath,
     canvas: { w: W, h: H },
     layers: ordered.map(({ index: _index, ...rest }, drawOrder) => ({ ...rest, drawOrder })),
+    hidden,
   };
 }
 
+/** Every hidden-art layer must belong to a drawn layer the same input holds (issue #359): `LAYERS_HIDDEN_OF_PRESENT`. */
+function checkHiddenOf(hidden: readonly HiddenLayer[], drawn: readonly string[], label: (name: string) => string, refuse: (code: string, object: string, detail: string) => void): void {
+  for (const h of hidden) {
+    if (!drawn.includes(h.of)) {
+      refuse('LAYERS_HIDDEN_OF_PRESENT', label(h.name), `is the hidden art of "${h.of}", and the input holds no drawn layer of that name — it holds ${drawn.length === 0 ? 'none' : drawn.map((n) => `"${n}"`).join(', ')}; ${HIDDEN_NAME_RULE} is required`);
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // the PSD form
 // ---------------------------------------------------------------------------
@@ -349,7 +409,9 @@ export function readPsdLayers(path: string): LayerSet {
   const walk = (children: PsdLayer[] | undefined, trail: string): void => {
     for (const layer of children ?? []) {
       const where = `${trail}${layer.name ?? '(unnamed)'}`;
-      if (layer.hidden) refuse('PSD_LAYER_PLAIN', `PSD layer "${where}"`, 'is hidden; every layer of a decomposition is drawn');
+      // A hidden-art layer (issue #359) is never drawn, so it may be switched off in the file; every other layer is drawn.
+      const art = layer.children === undefined && readHiddenTag(layer.name ?? '') !== null;
+      if (layer.hidden && !art) refuse('PSD_LAYER_PLAIN', `PSD layer "${where}"`, 'is hidden; every layer of a decomposition is drawn (only a hidden-art layer, "<layer>:hidden", may be switched off)');
       if (layer.opacity !== undefined && layer.opacity !== 1) {
         refuse('PSD_LAYER_PLAIN', `PSD layer "${where}"`, `has opacity ${layer.opacity}; 1 is required`);
       }
@@ -372,10 +434,12 @@ export function readPsdLayers(path: string): LayerSet {
   if (leaves.length === 0) refuse('PSD_HAS_LAYERS', path, 'holds no pixel layer; one per See-through tag is required');
   const seen = new Set<string>();
   const layers: Layer[] = [];
+  const hidden: HiddenLayer[] = [];
   leaves.forEach((layer) => {
     const name = layer.name ?? '';
-    const tag = readLayerTag(name);
-    if (tag === null) {
+    const hiddenOf = readHiddenTag(name);
+    const tag = hiddenOf === null ? readLayerTag(name) : null;
+    if (tag === null && hiddenOf === null) {
       refuse('LAYERS_TAG_KNOWN', `PSD layer "${name}"`, layerTagRequirement(name));
       return;
     }
@@ -406,9 +470,13 @@ export function readPsdLayers(path: string): LayerSet {
       return;
     }
     const pixels: Raster = { width: img.width, height: img.height, data: new Uint8ClampedArray(img.data) };
+    if (hiddenOf !== null) {
+      hidden.push({ name, of: hiddenOf.of, file: null, pixels, left, top, right, bottom, opaquePx: opaque(pixels) });
+      return;
+    }
     layers.push({
       name,
-      tag,
+      tag: tag as LayerTagReading,
       file: null,
       pixels,
       left,
@@ -420,8 +488,9 @@ export function readPsdLayers(path: string): LayerSet {
       opaquePx: opaque(pixels),
     });
   });
+  checkHiddenOf(hidden, layers.map((l) => l.name), (l) => `PSD layer "${l}"`, refuse);
   refuseIfAny(problems);
-  return { form: 'psd', source: path, canvas: { w: W, h: H }, layers };
+  return { form: 'psd', source: path, canvas: { w: W, h: H }, layers, hidden };
 }
 
 /** Read whichever form `path` is: a `.psd` file, or a wrapper directory / `layers.json`. */
@@ -440,6 +509,135 @@ export function readLayers(path: string): LayerSet {
   throw new Error('unreachable');
 }
 
+// ---------------------------------------------------------------------------
+// the export and the template (issue #359)
+// ---------------------------------------------------------------------------
+
+/**
+ * The file a layer is exported to: its index in the manifest, zero-padded to
+ * the width of the last index (at least two digits), then its name with every
+ * character other than a letter, a digit, `-` and `_` written `_`. The index
+ * makes the name unique (`author:a b` and `author:a_b` would otherwise meet),
+ * and the manifest, not the file name, says which layer a file is.
+ */
+export function exportFileName(index: number, count: number, name: string): string {
+  const width = Math.max(2, String(Math.max(0, count - 1)).length);
+  return `${String(index).padStart(width, '0')}_${name.replace(/[^A-Za-z0-9_-]/g, '_')}.png`;
+}
+
+/** The wrapper manifest `exportLayers` writes, as text: fixed key order, two-space indent, a trailing newline. */
+export function exportManifestText(set: LayerSet): string {
+  const all: Array<{ name: string; left: number; top: number; right: number; bottom: number; depth: number | null }> = [
+    ...set.layers.map((l) => ({ name: l.name, left: l.left, top: l.top, right: l.right, bottom: l.bottom, depth: l.depth })),
+    ...set.hidden.map((h) => ({ name: h.name, left: h.left, top: h.top, right: h.right, bottom: h.bottom, depth: null })),
+  ];
+  const manifest = {
+    width: set.canvas.w,
+    height: set.canvas.h,
+    layers: all.map((l, i) => ({ name: l.name, filename: exportFileName(i, all.length, l.name), left: l.left, top: l.top, right: l.right, bottom: l.bottom, depth_median: l.depth })),
+  };
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+/**
+ * `layers --export <dir> <input>` (issue #359): write a set as the wrapper
+ * form — `layers.json` beside one RGBA PNG per layer — so an agent can correct
+ * the parse with ordinary file operations and hand the directory back to any
+ * command that reads layers. Drawn layers are listed in draw order, back to
+ * front, then the hidden-art layers in their own order; `depth_median` is the
+ * input's own, so a PSD's is `null` on every layer and the manifest's order is
+ * its draw order ({@link readWrapperLayers}). Reading the directory back gives
+ * the same layers, boxes, pixels and order as the input's reading (selftest
+ * `LW` round trip).
+ *
+ * Refuses a `dir` that exists and is not an empty directory
+ * (`LAYERS_EXPORT_DIR_EMPTY`): a file left there by an earlier export — a
+ * `parts/<name>.png` the reader also looks for — could be read in place of
+ * the one written now. Writes nothing until that has passed.
+ */
+export function exportLayers(set: LayerSet, dir: string): { manifest: string; files: string[] } {
+  if (existsSync(dir) && (!statSync(dir).isDirectory() || readdirSync(dir).length > 0)) {
+    refuseIfAny([
+      {
+        code: 'LAYERS_EXPORT_DIR_EMPTY',
+        object: dir,
+        detail: statSync(dir).isDirectory() ? `holds ${readdirSync(dir).length} entr${readdirSync(dir).length === 1 ? 'y' : 'ies'}; a directory that does not exist yet, or an empty one, is required — a file left there could be read in place of the one written now` : 'is a file; a directory that does not exist yet, or an empty one, is required',
+      },
+    ]);
+  }
+  const text = exportManifestText(set);
+  const entries = (JSON.parse(text) as { layers: Array<{ filename: string }> }).layers;
+  const pixels = [...set.layers.map((l) => l.pixels), ...set.hidden.map((h) => h.pixels)];
+  mkdirSync(dir, { recursive: true });
+  const files = entries.map((e, i) => {
+    const path = join(dir, e.filename);
+    writeFileSync(path, encodePngBytes(pixels[i]));
+    return path;
+  });
+  const manifest = join(dir, 'layers.json');
+  writeFileSync(manifest, text);
+  return { manifest, files };
+}
+
+/**
+ * Where two readings of one decomposition differ, or null when they are the
+ * same: the canvas, then each drawn layer in draw order — name, box, depth,
+ * pixels byte for byte — then each hidden-art layer. The first difference is
+ * named. What the export's round trip is held to (issue #359); the source
+ * path, the form and each layer's file are where it was read from, not what
+ * it holds, and are not compared.
+ */
+export function layerSetDiff(a: LayerSet, b: LayerSet): string | null {
+  if (a.canvas.w !== b.canvas.w || a.canvas.h !== b.canvas.h) return `canvas ${a.canvas.w}x${a.canvas.h} against ${b.canvas.w}x${b.canvas.h}`;
+  const box = (l: { left: number; top: number; right: number; bottom: number }): string => `${l.left},${l.top},${l.right},${l.bottom}`;
+  const same = (x: Raster, y: Raster): boolean => x.width === y.width && x.height === y.height && Buffer.from(x.data).equals(Buffer.from(y.data));
+  if (a.layers.length !== b.layers.length) return `${a.layers.length} drawn layer(s) against ${b.layers.length}`;
+  for (let i = 0; i < a.layers.length; i++) {
+    const x = a.layers[i];
+    const y = b.layers[i];
+    if (x.name !== y.name) return `draw order ${i} is "${x.name}" against "${y.name}"`;
+    if (box(x) !== box(y)) return `layer "${x.name}" box ${box(x)} against ${box(y)}`;
+    if (x.depth !== y.depth) return `layer "${x.name}" depth ${String(x.depth)} against ${String(y.depth)}`;
+    if (!same(x.pixels, y.pixels)) return `layer "${x.name}" pixels differ`;
+  }
+  if (a.hidden.length !== b.hidden.length) return `${a.hidden.length} hidden-art layer(s) against ${b.hidden.length}`;
+  for (let i = 0; i < a.hidden.length; i++) {
+    const x = a.hidden[i];
+    const y = b.hidden[i];
+    if (x.name !== y.name || box(x) !== box(y) || !same(x.pixels, y.pixels)) return `hidden-art layer ${i} "${x.name}" against "${y.name}" (name, box or pixels)`;
+  }
+  return null;
+}
+
+/**
+ * The layer names `layers --template` writes, bottom first (issue #359): every
+ * v3 tag (`src/tags.ts`, 24) less `head` — upstream never emits it as a layer
+ * and no stage reads a role from it — with each of the six split tags written
+ * as its `-r` and `-l` halves, because the rig reads the halves (the eye bones
+ * come from `eyewhite-r` and `eyewhite-l`): 24 − 1 − 6 + 12 = 29 names. The
+ * order is a starting stack — back hair, the body, the face, front hair — and
+ * not a rule: the file's own order is the draw order.
+ */
+export function templateLayerNames(): string[] {
+  const expand = (t: string): string[] => ((SPLIT_TAGS as readonly string[]).includes(t) ? [`${t}-r`, `${t}-l`] : [t]);
+  const body = (BODY_TAGS as readonly string[]).filter((t) => t !== 'head' && t !== 'back hair' && t !== 'front hair');
+  return ['back hair', ...body.flatMap(expand), ...(HEAD_TAGS as readonly string[]).flatMap(expand), 'front hair'];
+}
+
+/**
+ * `layers --template <out.psd> --canvas <W>x<H>`: a PSD of {@link templateLayerNames}'s
+ * layers, each empty, on a `W x H` canvas, written by the same library the
+ * reader uses. The same canvas writes the same bytes. The reader refuses an
+ * empty layer (`PSD_LAYER_HAS_PIXELS`), so the template read back as it is
+ * names every layer once: an artist paints into the layers the figure has and
+ * deletes the rest.
+ */
+export function templatePsdBytes(w: number, h: number): Uint8Array {
+  stubCanvas();
+  const doc = { width: w, height: h, children: templateLayerNames().map((name) => ({ name })) };
+  return new Uint8Array(writePsd(doc, { noBackground: true }));
+}
+
 // ---------------------------------------------------------------------------
 // plausibility: three figures per layer, and the rules `--propose-plan` drops by
 // ---------------------------------------------------------------------------
@@ -601,3 +799,18 @@ export function ruleSummary(rule: PlausibilityRule): string {
   }
   return `at most ${PLAUSIBLE_AREA_RATIO_MAX}x the rest of the figure`;
 }
+
+/** The `layers` line for a hidden-art layer (issue #359): whose art it is, its box and pixels, and that it is never drawn. */
+export function hiddenLayerLine(h: HiddenLayer): string {
+  return `hidden art: layer "${h.name}" — "${h.of}"'s art where it is covered, box ${h.left},${h.top} to ${h.right},${h.bottom}, ${h.opaquePx} opaque px; never drawn and never a part: assemble reads it as the under of a cut and the cap of a limb segment that take "${h.of}"'s part`;
+}
+
+/**
+ * The line `layers` prints for an input with no depth (issue #359): a PSD, or
+ * a wrapper export of one. The one reading of depth in this package is the
+ * turn draft (`propose --full/--head`), and it SKIPs such a run — naming it —
+ * rather than drafting a turn from depths nobody measured.
+ */
+export function depthSkipLine(set: LayerSet): string {
+  return `SKIP  depth: ${set.source} carries no depth_median (${set.form === 'psd' ? 'a PSD carries none' : 'null on every layer'}); the draw order is the file's own, and the turn draft (propose --full/--head) skips this run`;
+}