@rig-c/core 2.62.0 → 2.63.0

package/README.md

@@ -606,7 +606,7 @@ commands take it and what its default is.
 | `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. a skeleton that declares no stage is carried as declaring none, `--stage x,y,w,h` adds a box to one — and is refused, rather than ignored, beside one that declares a box — and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all |
 | `split --rig … --motion … --slot <name> --out <dir>` | the answer to a mesh refused because its triangles are **several pieces that share no vertex** — two legs after the triangles bridging them were deleted. It reads the two specs and writes them back into an absent or empty `--out` with one mesh per piece: piece 1 stays in the slot, piece k gets a new slot `<slot>_<k>` after it, each with the original's uvs and weights unchanged, its triangles renumbered outline first where the hull rule needs it, and every deform key re-sliced to the new indices — plus `split.json`, where every original vertex and triangle went. One piece is said so and nothing is written; what it cannot carry is refused by name ([AUTHORING §3.4.11](docs/AUTHORING.md)) |
 | `explain --rig … --motion …` | the compiled rig as a table — every bone with its resolved parent, the slots in draw order, every timeline key by key. Writes nothing. What to reach for when a rig compiles and still looks wrong |
-| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`, one directory per set: `<anim>@<fps>fps/` rather than `<anim>/` at any rate but the default — `--fps 24` writes `<anim>@24fps/`, and the default 12 writes `<anim>/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid. `--folds` adds a `folds.json` per set and prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count and which triangles, their world box and their setup-pose area. `--pass-through <cloth>:<leg>` adds a `pass-through.json` per set and prints the frames where a cloth drawn over a leg has its side inside the leg's drawn outline, with the depth and the world box — a reading, not a gate. `--seam <slot>:<slot>` adds a `seam.json` per set and prints, per pair, the frames where two slots that meet open background inside the joint (a gap) or show the overlap band of one past the other (a ghost), with the worst frame's cell count and world box — a reading, not a gate; the exit status never moves. `--angle-range <bone>:<relative-to>` prints how far one bone turns against another over each set: the lowest and highest angle and the frames they fall on — a reading, not a gate. `--viewport <x,y,w,h>` or `--viewport-from <frames.json>` draws over a given box instead of a fitted one, so two builds land on one pixel grid; a slot that reaches past it is named by set and frame, and `frames.json` records it. `--environment <schedule.json>` draws the rig under the wind and gravity its physics answers, in time — the same frames on the core and on spine-core; an inspection of the response the rig states, not a scene |
+| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`, one directory per set: `<anim>@<fps>fps/` rather than `<anim>/` at any rate but the default — `--fps 24` writes `<anim>@24fps/`, and the default 12 writes `<anim>/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid. `--folds` adds a `folds.json` per set and prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count and which triangles, their world box and their setup-pose area. `--pass-through <cloth>:<leg>` adds a `pass-through.json` per set and prints the frames where a cloth drawn over a leg has its side inside the leg's drawn outline, with the depth and the world box — a reading, not a gate. `--seam <slot>:<slot>` adds a `seam.json` per set and prints, per pair, the frames where two slots that meet open background inside the joint (a gap) or show the overlap band of one past the other (a ghost), with the worst frame's cell count and world box — a reading, not a gate; the exit status never moves. `--overlaps` adds an `overlaps.json` per set and prints one `OVERLAP "<under>" under "<over>"` line per pair of slots where the one drawn later covers the earlier one and the motion moves it — the frames, and the most pixels covered and the frame of them — with an outline plate per covered frame; the render reports what was drawn, and the draw-order key is the author's remedy — a reading, not a gate. `--angle-range <bone>:<relative-to>` prints how far one bone turns against another over each set: the lowest and highest angle and the frames they fall on — a reading, not a gate. `--viewport <x,y,w,h>` or `--viewport-from <frames.json>` draws over a given box instead of a fitted one, so two builds land on one pixel grid; a slot that reaches past it is named by set and frame, and `frames.json` records it. `--environment <schedule.json>` draws the rig under the wind and gravity its physics answers, in time — the same frames on the core and on spine-core; an inspection of the response the rig states, not a scene |
 | `preview --candidate <dir>` | one self-contained `.html` that plays it, headed by the line `validate <dir>` prints for it and the rigc version — a refused candidate is still previewed, and its header says so in the gate's words. Repeat `--candidate` for one page with a pane per candidate, in the order given; a green `build` ends by naming this command for its own `--out` |
 | `vote --candidate a --candidate b` | one `.html` that asks a human which; `vote --record <file>` checks the answer into `votes.jsonl` |
 | `pose --images <dir> --frame <png>` | reads part placements **out of** a picture |

package/docs/AUTHORING.md

@@ -261,6 +261,7 @@ What the flags mean:
 | `--folds` | `render` only: also read which mesh triangles **fold** — turn over against the setup pose — and write a `folds.json` into each frame directory: per mesh, the frames with a folded triangle, the worst frame's count and which triangles, by index, with their world box and setup-pose area. One printed line per mesh that folds; a triangle degenerate or inverted at the setup pose is said once and never counted. A reading, not a gate. Every other file is byte for byte what the render writes without it, `geometry.json` included. Refused with `--slot`/`--hide`, for `--geometry`'s reason — **§8.3** |
 | `--pass-through` | `render` only: `<cloth>:<leg>[,<cloth>:<leg>…]` — also read where each cloth slot **passes through** its leg slot, and write a `pass-through.json` into each frame directory: the frames where the cloth draws over the leg and its drawn side lies inside the leg's drawn outline by 2 steps or more, each with the depth and the world box. One printed line per pair, and one per frame that passes through. The first name must draw over the second for a frame to be read — the declared order, never both. A reading, not a gate. Every other file is byte for byte what the render writes without it. An unknown slot, a slot that draws on no frame, a malformed list and a pair named twice are refused by name, and so is `--slot`/`--hide` beside it — **§8.5** |
 | `--seam` | `render` only: `<slot>:<slot>[,<slot>:<slot>…]` — also read, for each pair, where the two drawings **stop meeting**, and write a `seam.json` into each frame directory: per pair, the frames with a **gap** (background inside the joint, where the two covered together at the setup pose) and the frames with a **ghost** (the overlap band of one showing where, from its partner's point of view, nothing was drawn), each with its cell count, area and world box, and as runs of frames with their times. One printed line per pair; a pair whose drawings share no cell at the setup pose is a **SKIP**. A reading, not a gate: the exit status never moves. Every other file is byte for byte what the render writes without it. An unknown slot, a slot with itself, a slot that draws on no frame, a malformed list and a pair named twice in either order are refused by name, and so is `--slot`/`--hide` beside it — **§8.8** |
+| `--overlaps` | `render` only: also read **which slot each frame drew over which**, and write an `overlaps.json` into each frame directory: per frame, every pair of slots where the slot drawn later covers pixels the earlier one drew (drawn at 128 of 255 or more, on the frames' own pixels), with the pixel count and the pixel box. One `OVERLAP` line per pair that covers anything — its frames as runs, how many of the set, and the most pixels and the frame of them — and one line counting the pairs that are layering the motion does not move. Each frame with a moving pair also gets an **outline plate**, `overlaps-f<NNNN>.png`: every slot in a moving pair as its contour in its own colour, dashed where a slot drawn later covers it, named at its top. The render reports what was drawn; who should be in front is the author's, and the draw-order key in the motion spec is the remedy. A reading, not a gate. Every other file is byte for byte what the render writes without it, and `frames.json` gains each set's `overlaps` record. Refused beside `--slot`/`--hide` — **§8.9** |
 | `--angle-range` | `render` only: `<bone>:<relative-to>[,<bone>:<relative-to>…]` — also read, for each pair, the range of the first bone's world direction against the second's over each set's frames, and print one line per pair per set: the lowest and the highest angle in degrees, the span, and the frame each was first reached on. A reading, not a gate: nothing is written, and every file is the bytes the render writes without it. An unknown bone (with the bones there are), a bone against itself, a malformed list and a pair named twice are refused by name, and so is a bone with no direction on a frame — **§8.7** |
 | `--viewport`, `--viewport-from` | `render`: give the box every frame is drawn over instead of fitting one — `--viewport <x,y,w,h>`, a world box, y up, `x,y` its bottom-left corner, at the pixel size `--max` gives; or `--viewport-from <frames.json \| dir>`, an earlier render's grid exactly (its box, scale and pixel size), so two candidates land on one pixel grid. A slot that reaches past the box is named by set and frame, and `frames.json` records the box was given under `pinned`. The two together are refused, and so is `--max` beside `--viewport-from` — **§8.6**. On `check` and `inspect`, `--viewport` pins the box those commands draw over instead |
 | `--environment` | `render` only: the wind and gravity the rig's physics constraints answer, in time — a schedule file `{ "spec": "rigc-environment/1", "steps": [{ "t": <seconds>, "wind"?: [x, y], "gravity"?: [x, y] }, …] }`, x right and **y down**, each step holding from its `t` until the next. Both posers set each change before the step that poses the first frame at or after its `t`, and draw the same frames, `geometry.json` and `frames.json` (`RE01`). `frames.json` and `geometry.json` record it, and the framing reads it. A malformed file, a half no physics constraint answers, two steps on one frame and a step after every set's last frame are refused by name, exit 2, nothing written; `check` refuses a frame set drawn under one as a reference. Without it every file is the bytes it always was. An inspection of the response the rig states, not a scene — **§8.4** |
@@ -1137,6 +1138,7 @@ bun cli.ts render   --candidate path/to/spine --geometry   # + geometry.json per
 bun cli.ts render   --candidate path/to/spine --folds      # + folds.json per set: which mesh triangles turn over, and when
 bun cli.ts render   --candidate path/to/spine --pass-through skirt:leg   # + pass-through.json: where a cloth goes through a leg
 bun cli.ts render   --candidate path/to/spine --seam thigh:shin   # + seam.json: where two slots that meet open a gap or show a ghost
+bun cli.ts render   --candidate path/to/spine --overlaps   # + overlaps.json and outline plates: which slot each frame drew over which
 bun cli.ts render   --candidate path/to/spine --angle-range tail:hip   # how far a bone turns against another, per animation
 bun cli.ts render   --candidate path/to/spine --viewport-from render/   # an earlier render's grid: two builds, one pixel grid
 bun cli.ts preview  --candidate path/to/spine [--candidate path/to/another …] [--animation …] [--out preview.html]
@@ -8879,6 +8881,107 @@ same file, and two runs write the same bytes (the selftest's `seam` suite).
 look at a frame it names, draw that set over the box it printed:
 `render --animation <name> --viewport <x,y,w,h> --max 400`.
 
+### 8.9 Which slot covers which — `render --overlaps`
+
+An arm the draw order puts behind the torso simply vanishes from the frames, on a
+build that passes every assertion and every check, and nothing in the frames names
+it. `--overlaps` reads it off the frames `render` draws: **who covers whom, on which
+frames, by how many pixels**. On the selftest's probe (`overlap_probe`,
+`fixtures/public.ts`: an opaque stage, a still body, and an arm drawn after the body
+slid along x across it and out the other side):
+
+```bash
+bun cli.ts render --candidate path/to/spine --animation cross --overlaps --max 160 [--skin …] [--fps 12]
+# rigc render
+#   ..    cross            25 frame(s), 2.000s + contact.png + overlaps.json (1 moving pair(s), 11 outline plate(s)) -> …/cross
+#   ..    overlap  "cross": 2 pair(s) cover on every frame by the same pixels, or with the slot in front drawn wholly on the one behind — layering the motion does not move; overlaps.json lists them
+#   ..    overlap  "cross": OVERLAP "body" under "arm": frames 7–17 (11 of 25), covered up to 135 px at frame 11
+```
+
+⭐ **The render reports what was drawn; who should be in front is the author's, and
+the draw-order key in the motion spec is the remedy** (§4.7, `drawOrder`). The same
+slide with a key that puts the arm before the body reads `OVERLAP "arm" under
+"body"` on the same frames and pixels (`OX02`). On `gallery/walk` at `--fps 20 --max
+288` the back arm reads `OVERLAP "arm_b" under "torso": frames 0–18 (19 of 19),
+covered up to 643 px at frame 15`; with `arm_b` moved after `torso` in the rig's
+slots, that line is gone and `OVERLAP "torso" under "arm_b"` reads the same 643 px at
+frame 15.
+
+**Which frames are read.** Every frame of every set drawn, in **that frame's own
+draw order** — the order its pieces are drawn in, so a draw-order key is honoured.
+
+**What covering means.** Every piece is rasterised in draw order on the render's own
+viewport, so a pixel here is a pixel of `f<NNNN>.png`. A pixel is drawn by a slot
+when the renderer paints it at half opacity or more (128 of 255) — the line every
+other reading draws outlines at. Each pixel keeps the slots that have drawn it so
+far; a slot drawing a pixel earlier slots already drew **covers** each of them there,
+one pixel to each (earlier, later) pair. `under` is the earlier-drawn slot, `over`
+the later-drawn one. Pairs are by slot name, so `a` under `b` and `b` under `a` —
+one draw-order key apart — are two pairs.
+
+**Layering the motion does not move.** A pair that covers on **every** frame, and on
+each either by the **same** pixel count or with the slot in front drawn **wholly on**
+the one behind (every pixel `over` draws is one `under` drew first), is static
+layering: a backdrop under a part that never leaves it, a face drawn over the head
+that carries it. It is counted on one line and listed in the file, never printed
+pair by pair. ⚠️ The pixel count alone was measured not to be enough: on
+`gallery/walk`, a part turning over the backdrop changes its pixel count from frame to
+frame by rasterisation alone, so none of its 35 pairs read as static and 14 backdrop lines (and the eyes over the head) buried the ones that mattered.
+Every other pair that covers anything prints one `OVERLAP` line; a pair that never
+covers prints nothing.
+
+**Blind spots, stated.** A fringe painted under half opacity covers nothing here
+although it tints the frame. A slot in front lying wholly on the one behind on every
+frame reads as layering however it moves across it — an arm swung over the torso
+without ever leaving it. A slot drawing more than one piece is one slot. And the
+counts are pixels at the render's `--max`: quote the size beside a figure.
+
+**The file.** `overlaps.json`, `rigc-overlaps/1`, beside each set's frames:
+`animation`, `skin` (absent when none was set), `fps`, `reading` (`drawnAlpha` 128,
+`unit` `"frame pixels"`, and `rule`, the definition above), `frames[]` — every
+frame, with `index`, `time` and `pairs[]` (`under`, `over`, `px`, and `box`
+`[x0, y0, x1, y1]`: frame pixels, x right, y down, both ends inclusive) — and
+`pairs[]`, one per pair that covers on any frame: `under`, `over`, `frames` (how
+many it covers on), `of` (the set's frames), `runs` (`[[first, last], …]`,
+inclusive), `most` (`{ index, px }`, the earliest on a tie), `inside` (the slot in
+front wholly on the one behind on every frame it covers on) and `varies` (`false`
+for static layering). Both lists are ordered by `under`, then `over`, by code unit.
+
+**The outline plate.** `overlaps-f<NNNN>.png`, numbered as the frames are, for each
+frame where a moving pair covers: a white plate of the frame's size; every slot in a
+moving pair drawn as its **contour** — a drawn pixel with an undrawn neighbour left,
+right, above or below — in its own colour, in draw order; a contour pixel some slot
+drawn later also drew is **dashed** (drawn where `(x + y) % 4 < 2`); and the slot's
+name, spelled as the lines spell it (`arm_b`, not `ARM_B`). Names are placed in draw
+order and no two touch: each takes the first free box, trying for every contour pixel
+in raster order (the first is the topmost, the leftmost on a tie) the box above it,
+below it, to its left and to its right; when none is free, the free spot nearest the
+topmost pixel, joined to it by a one-pixel leader line; every box clamped inside the
+plate. A plate with no free spot left prints the name at its first box anyway — the
+one case two names can meet. A slot keeps one colour across a set's plates (a fixed table of eight,
+by the slot's place among the set's moving slots in code-unit order); the colour
+means only "another slot" — the name says which.
+
+**`frames.json`.** Each set gains `overlaps`: `file`, `pairs` (how many cover on any
+frame), `static` (how many of those are layering), `plates`, and `moving[]` — each
+moving pair's `under`, `over`, `frames` and `most` — so a reader that cannot open a
+plate has the figures.
+
+**Refused, nothing written:** `--slot`/`--hide` beside the flag. A slot left out
+covers nothing, so the pairs it is in would vanish and the reading would describe a
+picture of part of the rig — run `render --overlaps` on the whole rig and the subset
+without it; both land on one grid.
+
+**Nothing else moves.** The PNGs, `contact.png` and every other file are byte for
+byte what the render writes without the flag, and `frames.json` differs only by
+each set's `overlaps` record (`OX05`); two runs and both posers write the same file
+and plates (`OX04`).
+
+**A reading, not a gate.** It never changes the exit status. Whether a covered arm
+is a defect is yours; when it is, the remedy is a `drawOrder` key in the motion
+spec (or the slot's place in the rig's `slots`), and the next render says whether
+the line moved.
+
 ---
 
 ## 9. Checking against the frames — `rigc check`
@@ -11706,6 +11809,7 @@ pixel (`IN09`).
 | Does this part's edge follow that bone? | `--show art,weights:<bone>,mesh --overlay-slot <part> --zoom slot:<part>` | the part's own triangles and the bone's weight over them alone, over the whole painting. Where slots stack — a neck under the face, the hair, a collar — every mesh crossing the box is drawn and the heat is the union of every slot the bone moves, so the part's edge has no pixel of its own until the others are left out. The legend's `meshes[]` gives the part's weight for the bone at every vertex, so "does the top row follow the head" is read as numbers as well as colour |
 | Is this rig's density where its motion is? | `--show art,density --dim` | each region and mesh filled by its **ratio** — its triangles per world unit² over the figure's — on one ramp, log-scaled and centred on 1×: grey is as dense as the figure, pink to magenta denser (4×, 16×), light to dark green sparser (1/4×, 1/16×), clamped past the end stops (the stops are in the legend). A part's area is its posed mesh's own, the sum of its triangles' areas at the pose drawn, not the image's box; a region is two triangles over its quad. Where parts overlap the pixel is the part drawn last, as in the art, so a part under others is read with `--overlay-slot <part>`. The figure's totals are always over every slot the pose shows — the filter picks what is drawn and listed, never what the figure is — and the legend's `density` gives each slot's attachment, kind, vertices, triangles, hull, area, triangles per area, ratio and the bones it is weighted to, in draw order. A measurement, not a verdict: no bar is drawn, and `A13_MESH_BUDGET` stays the one gate on counts |
 | Does a joint tear in this animation? | `render --seam <a>:<b> --animation <name>` (§8.8) | One line per pair: the frames where background opens inside the joint (gap) or the overlap band of one piece shows past its partner (ghost), with the worst frame's cell count and world box; `seam.json` carries every frame and its time, and the runs of frames. A pair whose drawings never overlap is a SKIP, said by name. A reading, not a verdict — the exit status never moves |
+| Which slot covers which in this animation? | `render --overlaps --animation <name>` (§8.9) | One `OVERLAP "<under>" under "<over>"` line per pair that moves: the frames it covers on, as runs, and the most pixels it covers and the frame of them; one line counting the layering the motion does not move. `overlaps.json` carries every frame's pairs with their pixel count and box, and `overlaps-f<NNNN>.png` draws each covered frame's contours, the covered part dashed. A reading, not a verdict — the draw-order key is the remedy |
 | Does anything fold in this animation? | `render --folds --animation <name>` (§8.3), then `inspect --show art,folds,mesh --animation <name> --at <the worst frame's time> --zoom folds` | `render --folds` prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count, which triangles, their world box at that frame and their setup-pose area. The view fills those triangles at the pose drawn — every pixel whose centre a folded triangle holds — in the colour the legend's `folds` states, and the legend's `folds[]` names, per mesh, the folded triangles by index with the same box and area, and the setup pose's degenerate and inverted ones, which are never counted. A fold is usually a sliver a few units across, invisible in a picture of the whole mesh: `--zoom folds` frames the picture to the folded triangles' box. A thin sliver still needs pixels — raise `--max` when the fill is a line. A reading, not a verdict |
 | How is this part triangulated? | `--show art,mesh,hull --zoom slot:<slot>` | each mesh's triangle edges, and over them its hull — vertex 0 to 1 to … to `hull − 1` and back. Regions are not drawn: a region is not a mesh. The legend lists every vertex in world units and in pixels |
 | Which is drawn over which? | `--show art,slots` | each slot that shows a region or mesh numbered by its place in the draw order **at the pose drawn** (0 is drawn first), on a white box at the centre of its attachment's box — so a `drawOrder` key (§4.7) shows from the first frame `render` draws it on |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.62.0",
+  "version": "2.63.0",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/cli/core_commands.ts

@@ -38,6 +38,8 @@ import { FOLDS_FILE, foldLine, foldsFileOf, foldsOf, foldsText, setupFaultLine }
 import { AngleRangeError, angleRangeLine, type AngleRangeReading, angleRangesOf, type BonePair, readBonePairs } from '../anglerange.ts';
 import { outsideLine, outsideViewport, pinnedRecord, readViewportBox, viewportOfFramesFile, ViewportError } from '../viewportpin.ts';
 import { PASS_THROUGH_FILE, passFrameLine, type PassPair, passSummaryLine, passThroughFileOf, passThroughOf, passThroughText, PassThroughError, readPassPairs } from '../passthrough.ts';
+import type { Plate } from '../../tools/plate.ts';
+import { OVERLAPS_FILE, OverlapError, overlapLine, overlapPlate, overlapsFileOf, overlapsOf, overlapsPlateFile, overlapsText, plateParticipants, staticLine } from '../overlaps.ts';
 import { readSeamPairs, SEAM_FILE, seamFileOf, seamLine, SeamError, type SeamPair, seamsOf, seamText } from '../seam.ts';
 import { environmentCollisions, environmentFrame, EnvironmentError, environmentResponse, readEnvironmentSchedule, type EnvironmentStep } from '../environment.ts';
 import { estimatePose, poseLines, type PoseOptions } from '../pose.ts';
@@ -704,6 +706,22 @@ export function cmdRender(flags: Record<string, string>): void {
     }
   }
 
+  // The overlap reading (issue #1480) is its own flag for --folds' reason, and refused beside a subset for
+  // --pass-through's: who covers whom is a fact of every slot the rig draws, and a subset drops some of them — a slot
+  // left out covers nothing, so the pairs it is in would vanish and the reading would describe a picture of part of the rig.
+  const overlaps = flags.overlaps !== undefined;
+  if (overlaps) {
+    for (const flag of ['slot', 'hide'] as const) {
+      if (flags[flag] !== undefined) {
+        throw new UsageError(
+          `--overlaps takes no --${flag}: it reads which slot covers which as the whole rig draws them, and a subset of the ` +
+            `drawn slots would drop the pairs the slots left out are in. Run \`rigc render --overlaps\` on the whole rig for the reading, and --${flag} ${flags[flag]} ` +
+            'without --overlaps for the pictures — both land on the same grid',
+        );
+      }
+    }
+  }
+
   // The seam reading (issue #1456) is its own flag for --folds' reason, and refused beside a subset for --pass-through's:
   // it reads the two slots as the whole rig draws them.
   const seam = flags.seam;
@@ -913,9 +931,30 @@ export function cmdRender(flags: Record<string, string>): void {
         }
       }
     }
-    return { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings };
+    // The overlap reading, off the very pieces the frames are drawn from, in their draw order, on the frames' own
+    // viewport — one per set — and its outline plates, drawn here so a refusal leaves nothing written.
+    const overlapReadings = new Map<string, { file: ReturnType<typeof overlapsFileOf>; plates: Map<number, Plate> }>();
+    if (overlaps) {
+      for (const [name, frames] of sampled) {
+        const animation = name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name;
+        try {
+          const reading = overlapsOf(frames, pages, viewport);
+          const participants = plateParticipants(reading.pairs);
+          const plates = new Map<number, Plate>();
+          for (const index of reading.plated.keys()) {
+            const plate = overlapPlate(reading, index, participants, viewport);
+            if (plate !== null) plates.set(index, plate);
+          }
+          overlapReadings.set(name, { file: overlapsFileOf(animation, fps, skin, reading), plates });
+        } catch (err) {
+          if (err instanceof OverlapError) throw new UsageError(`--overlaps, ${JSON.stringify(name)}: ${err.message}`);
+          throw err;
+        }
+      }
+    }
+    return { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings, overlapReadings };
   });
-  const { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings } = posed.value;
+  const { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings, overlapReadings } = posed.value;
   console.log(`  ..    poser    ${posed.note}`);
   if (environment !== undefined) {
     const response = environmentResponse(skeletonText);
@@ -969,6 +1008,11 @@ export function cmdRender(flags: Record<string, string>): void {
     if (passReading !== undefined) writeFileSync(join(dir, PASS_THROUGH_FILE), passThroughText(passReading));
     const seamReading = seamReadings.get(name);
     if (seamReading !== undefined) writeFileSync(join(dir, SEAM_FILE), seamText(seamReading));
+    const overlapReading = overlapReadings.get(name);
+    if (overlapReading !== undefined) {
+      writeFileSync(join(dir, OVERLAPS_FILE), overlapsText(overlapReading.file));
+      for (const [index, plate] of overlapReading.plates) plate.writePng(join(dir, overlapsPlateFile(index)));
+    }
     const duration = frames[frames.length - 1].time;
     const physics = physicsDeclared.length === 0 ? undefined : physicsSteppedOf(frames, fps);
     sets.push({
@@ -980,6 +1024,7 @@ export function cmdRender(flags: Record<string, string>): void {
       stride: 1,
       duration,
       ...(physics === undefined ? {} : { physics: { stepped: physics.stepped.length, fps } }),
+      ...(overlapReading === undefined ? {} : { overlaps: overlapsRecord(overlapReading.file, overlapReading.plates.size) }),
     });
     const how = frames.length === 1 ? 'a single pose' : `${duration.toFixed(3)}s`;
     const folding = foldReading?.meshes.filter((m) => m.worst !== null).length ?? 0;
@@ -988,7 +1033,11 @@ export function cmdRender(flags: Record<string, string>): void {
     const passNote = passReading === undefined ? '' : ` + ${PASS_THROUGH_FILE} (${passing} of ${passReading.pairs.length} pair(s) pass through)`;
     const opening = seamReading?.pairs.filter((p) => p.opens.length > 0).length ?? 0;
     const seamNote = seamReading === undefined ? '' : ` + ${SEAM_FILE} (${opening} of ${seamReading.pairs.length} pair(s) open)`;
-    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}${passNote}${seamNote}`;
+    const overlapNote =
+      overlapReading === undefined
+        ? ''
+        : ` + ${OVERLAPS_FILE} (${overlapReading.file.pairs.filter((p) => p.varies).length} moving pair(s), ${overlapReading.plates.size} outline plate(s))`;
+    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}${passNote}${seamNote}${overlapNote}`;
     console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${extras} -> ${dir}`);
     if (physics !== undefined) console.log(`  ..    ${physicsLine(physics.stepped, physicsDeclared, fps, frames.length)}`);
     for (const mesh of foldReading?.meshes ?? []) {
@@ -1004,6 +1053,11 @@ export function cmdRender(flags: Record<string, string>): void {
       for (const frame of pair.frames) console.log(`  ..    pass     ${passFrameLine(passReading?.animation ?? null, pair, frame)}`);
     }
     for (const pair of seamReading?.pairs ?? []) console.log(`  ..    seam     ${seamLine(seamReading?.animation ?? null, fps, pair)}`);
+    if (overlapReading !== undefined) {
+      const still = staticLine(overlapReading.file.animation, overlapReading.file.pairs);
+      if (still !== null) console.log(`  ..    overlap  ${still}`);
+      for (const pair of overlapReading.file.pairs) if (pair.varies) console.log(`  ..    overlap  ${overlapLine(overlapReading.file.animation, pair)}`);
+    }
     for (const reading of angleReadings.get(name) ?? []) {
       console.log(`  ..    angle    ${angleRangeLine(name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name, fps, reading)}`);
     }
@@ -1036,6 +1090,21 @@ export function cmdRender(flags: Record<string, string>): void {
   console.log(`rigc: wrote ${join(outRoot, FRAMES_SIDECAR)}`);
 }
 
+/**
+ * `frames.json`'s record of one set's overlap reading (issue #1480), so a reader that cannot open a plate still has
+ * the figures: the file, how many pairs cover anything, how many of them are static layering, how many plates were
+ * drawn, and every pair that moves with its frame count and its most pixels — the figures its line prints.
+ */
+export function overlapsRecord(file: ReturnType<typeof overlapsFileOf>, plates: number): NonNullable<FrameSet['overlaps']> {
+  return {
+    file: OVERLAPS_FILE,
+    pairs: file.pairs.length,
+    static: file.pairs.filter((p) => !p.varies).length,
+    plates,
+    moving: file.pairs.filter((p) => p.varies).map((p) => ({ under: p.under, over: p.over, frames: p.frames, most: p.most })),
+  };
+}
+
 /** `render`'s line for a rig that declares no physics constraint (issue #1467): nothing was stepped because nothing could be. */
 export const PHYSICS_NONE_LINE = 'physics: none in this rig — it declares no physics constraint, so no frame steps one';
 

package/src/cli/shared.ts

@@ -40,6 +40,7 @@ import { depthStepLevels, type FoldLimit, type TurnCeiling } from '../depth.ts';
 import { FOLDS_FILE } from '../folds.ts';
 import { DRAWN_ALPHA, PASS_THROUGH_FILE, PASS_THROUGH_RUN } from '../passthrough.ts';
 import { SEAM_FILE } from '../seam.ts';
+import { OVERLAPS_FILE } from '../overlaps.ts';
 import { readViewportBox, ViewportError } from '../viewportpin.ts';
 import { parseJsonWithPosition } from '../json-position.ts';
 import { RUNG_IDS } from '../ladder.ts';
@@ -146,7 +147,7 @@ export { PACKAGE_ROOT, readPackageMeta, readVersion };
  * needs a value` (issue #328). `CLI10`/`CLI11` in `selftest.ts` now hold the two
  * halves together by reading `--help` rather than by naming a flag.
  */
-const BOOLEAN_FLAGS = new Set(['all', 'all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'folds', 'accept-skeleton-differences', 'keep-pages', 'dim']);
+const BOOLEAN_FLAGS = new Set(['all', 'all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'folds', 'overlaps', 'accept-skeleton-differences', 'keep-pages', 'dim']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -1052,6 +1053,14 @@ const FLAG_MEANINGS: Record<string, string> = {
     'world units, one texel of the coarser drawing to a step — each with the depth and the world box. One line per pair, and one per frame that passes through. ' +
     'The order is the declaration: the first name must draw over the second for a frame to be read. A reading, not a gate. ' +
     'An unknown slot, a slot that draws on no frame, a malformed list and a pair named twice are refused by name. Not with --slot/--hide',
+  overlaps:
+    `also read which slot each frame drew over which, and write ${OVERLAPS_FILE} into each frame directory: per frame, every pair ` +
+    `of slots where the slot drawn later covers pixels the earlier one drew (drawn at ${DRAWN_ALPHA} of 255 or more, on the frames' own ` +
+    'pixels), with the pixel count and the pixel box. One OVERLAP line per pair that covers anything — the frames, and the most pixels ' +
+    'and the frame of them — and one line counting the pairs that cover the same pixels on every frame (layering the motion does not move). ' +
+    'Each frame with a moving pair also gets an outline plate, overlaps-f<NNNN>.png: every slot in a moving pair as its contour in its own ' +
+    'colour, dashed where a slot drawn later covers it, named at its top. The render reports what was drawn; who should be in front is the ' +
+    "author's, and the draw-order key in the motion spec is the remedy. A reading, not a gate. Not with --slot/--hide",
   seam:
     `also read, for each <slot>:<slot> pair, where the two drawings stop meeting, and write ${SEAM_FILE} into each frame directory: ` +
     'per pair, the frames with a gap — background inside the hull of the band the two drawings share at the setup pose, carried to the frame by both — ' +
@@ -1733,10 +1742,11 @@ export const COMMANDS: CommandDoc[] = [
       'rigc render … --environment <schedule.json>   (the wind and gravity the physics answers, in time)',
       'rigc render … --pass-through <cloth>:<leg>[,…]   (the frames where a cloth drawn over a leg passes through it)',
       'rigc render … --seam <slot>:<slot>[,…]   (the frames where two slots that meet open a gap or show a ghost)',
+      'rigc render … --overlaps   (which slot each frame drew over which, by name, with an outline plate)',
       'rigc render … --angle-range <bone>:<relative-to>[,…]   (how far a bone turns against another, per animation)',
       'rigc render … --viewport <x,y,w,h> | --viewport-from <frames.json>   (a box given, not fitted: two renders on one pixel grid)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'pass-through', 'seam', 'angle-range', 'environment', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'pass-through', 'seam', 'overlaps', 'angle-range', 'environment', 'poser', 'out'],
     overrides: {
       out: { value: '<dir>', meaning: 'directory to write the frame series into (default `render/`)' },
       fps: {

package/src/overlaps.ts

@@ -0,0 +1,545 @@
+/**
+ * Which slot a frame drew over which — the reading behind `rigc render --overlaps`
+ * (issue #1480).
+ *
+ * ⭐ **A reading, not a gate**, as `--folds` and `--pass-through` are. An agent
+ * authoring a motion cannot see its frames: an arm the draw order puts behind
+ * the torso simply vanishes from them, on a build that passes everything, and
+ * nothing names it. This names it — **who covers whom, on which frames, by how
+ * many pixels** — and decides nothing. Who *should* be in front is the author's,
+ * stated in the motion's draw-order keys; the render says what was drawn.
+ *
+ * ## What "covers" means here
+ *
+ * Per frame, every piece is rasterised **in the frame's own draw order** (the
+ * order `Frame.pieces` lists them in, which both posers return in applied draw
+ * order, so a draw-order key is honoured) on the render's own viewport, so a
+ * pixel here is a pixel of `f<NNNN>.png`. A pixel is **drawn** by a piece when
+ * the renderer's own traversal (`rasterisePiece`) paints it at `DRAWN_ALPHA` of
+ * 255 or more — the half-opacity line every other reading draws outlines at; no
+ * other threshold enters.
+ *
+ * Each pixel keeps the slots that have drawn it so far, in draw order. When a
+ * slot draws a pixel that earlier slots already drew, it **covers** each of them
+ * there: pair (earlier, later) gains one pixel, and its box grows to hold it.
+ * `under` is the earlier-drawn slot, `over` the later-drawn one — the slot drawn
+ * later covers the earlier one, whatever either looks like. Pairs are keyed by
+ * slot name, so `a` under `b` and `b` under `a` — one draw-order key apart —
+ * are two pairs, never one.
+ *
+ * ## Layering the motion does not move
+ *
+ * A pair that covers on **every** frame of the set, and on each either by the
+ * **same** pixel count or with the slot in front drawn **wholly on** the one
+ * behind (every pixel `over` draws is one `under` drew first — `inside`), is
+ * **static layering** (`varies: false`): a backdrop under a part that never
+ * leaves it, a face drawn over the head that carries it. It is counted, listed
+ * in the file and not printed pair by pair. Every other pair that covers
+ * anything is printed (`varies: true`).
+ *
+ * ⚠️ The pixel count alone was the first rule, and it was measured not to hold
+ * its own examples (issue #1480): on `gallery/walk`, a part turning over the
+ * backdrop changes its pixel count from frame to frame by rasterisation alone,
+ * so no pair of its 35 read as static, and 14 backdrop lines
+ * buried the one that mattered. Containment is what "layering" means there.
+ *
+ * Known blind spots, stated rather than discovered: a pixel is drawn or not at
+ * the half-opacity line, so a fringe painted fainter than that covers nothing
+ * here although it tints the frame; a slot that draws more than one piece on a
+ * frame is one slot, entered at a pixel by the first of its pieces to draw there;
+ * and the count is of pixels at the
+ * render's `--max`, so the same motion at another size reads other numbers —
+ * quote the size beside a figure. A slot in front that lies wholly on the one
+ * behind on every frame is layering, however it moves across it — an arm swung
+ * over the torso without ever leaving it reads as static.
+ *
+ * Pure: no clock, no randomness, no runtime. The pieces and pages are handed in
+ * by whichever poser drew the frames.
+ */
+
+import { GLYPH_H, textWidth } from '../tools/font5x7.ts';
+import { Plate, type RGBA } from '../tools/plate.ts';
+import { DRAWN_ALPHA } from './passthrough.ts';
+import { type Piece, projector, rasterisePiece, type Viewport } from './render_shared.ts';
+
+/** The reading's file name inside a set's frame directory, and its format tag. */
+export const OVERLAPS_FILE = 'overlaps.json';
+export const OVERLAPS_SPEC = 'rigc-overlaps/1';
+
+/** An outline plate's file name for frame `index`: `overlaps-f0007.png`, zero-padded as the frames are. */
+export function overlapsPlateFile(index: number): string {
+  return `overlaps-f${String(index).padStart(4, '0')}.png`;
+}
+
+/** A covered area's pixel box `[x0, y0, x1, y1]`: frame pixels, x right, y down, both ends inclusive. */
+export type OverlapBox = [number, number, number, number];
+
+/** One sampled frame: its index, its time and the pieces it draws, in draw order. */
+export interface OverlapFrame {
+  index: number;
+  time: number;
+  pieces: readonly Piece[];
+}
+
+/** One pair's figures on one frame. */
+export interface FramePair {
+  under: string;
+  over: string;
+  /** Pixels `over` drew where `under` had already drawn. */
+  px: number;
+  box: OverlapBox;
+}
+
+/** One pair's figures over a set. */
+export interface PairTotal {
+  under: string;
+  over: string;
+  /** Frames on which `over` covers `under` by one pixel or more. */
+  frames: number;
+  /** Frames in the set. */
+  of: number;
+  /** Those frames as inclusive runs of indices, ascending. */
+  runs: Array<[number, number]>;
+  /** The frame it covers the most pixels on — the earliest on a tie. */
+  most: { index: number; px: number };
+  /** Whether, on every frame it covers on, every pixel `over` draws is a pixel `under` drew first: the slot in front lies wholly on the one behind. */
+  inside: boolean;
+  /**
+   * `false` for layering the motion does not move: it covers on every frame of
+   * the set, and either by one pixel count on each or with `inside` true.
+   */
+  varies: boolean;
+}
+
+/** `overlaps.json`: one frame set's reading. */
+export interface OverlapsFile {
+  spec: typeof OVERLAPS_SPEC;
+  /** The animation, or `null` for a skeleton with none (its one frame is the setup pose). */
+  animation: string | null;
+  skin?: string;
+  fps: number;
+  /** What the numbers mean, stated in the file so a reader does not need this module. */
+  reading: { drawnAlpha: number; unit: 'frame pixels'; rule: string };
+  frames: Array<{ index: number; time: number; pairs: FramePair[] }>;
+  pairs: PairTotal[];
+}
+
+/** A page a piece samples that is not among the pages — said by name. */
+export class OverlapError extends Error {}
+
+/**
+ * A planted defect, for the suite's mutants only (`OX` controls in
+ * `selftest.ts`). Production passes none.
+ */
+export interface OverlapPlant {
+  /** Rasterise the pieces in reverse draw order, so the earlier-drawn slot reads as the one in front. */
+  reverse?: boolean;
+  /** Count a pixel drawn at any painted alpha rather than at `DRAWN_ALPHA`. */
+  anyAlpha?: boolean;
+  /** Read every pair as varying, so static layering prints pair by pair. */
+  noStatic?: boolean;
+}
+
+/** One frame's per-pixel lists of the slots that drew there, in draw order — what both the counts and the plate read. */
+export interface FrameDraw {
+  /** Slot names, in the order they first drew on this frame. */
+  slots: string[];
+  /** Per pixel, row major, the indices into `slots` that drew it, in draw order; `null` where nothing did. */
+  lists: Array<number[] | null>;
+}
+
+/** Code-unit order, so one build orders one way on every machine and locale. */
+const byCodeUnit = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+/** Pairs in one order everywhere: by `under`, then by `over`, in code-unit order. */
+const pairOrder = (a: { under: string; over: string }, b: { under: string; over: string }): number => byCodeUnit(a.under, b.under) || byCodeUnit(a.over, b.over);
+
+function drawFrame(frame: OverlapFrame, pages: ReadonlyMap<string, Plate>, viewport: Viewport, plant: OverlapPlant): FrameDraw {
+  const slots: string[] = [];
+  const lists: Array<number[] | null> = new Array<number[] | null>(viewport.width * viewport.height).fill(null);
+  const project = projector(viewport);
+  const need = plant.anyAlpha ? 1 : DRAWN_ALPHA;
+  const pieces = plant.reverse ? [...frame.pieces].reverse() : frame.pieces;
+  for (const piece of pieces) {
+    const page = pages.get(piece.page);
+    if (page === undefined) throw new OverlapError(`frame ${frame.index}: slot "${piece.slot}" samples atlas page "${piece.page}", which is not among [${[...pages.keys()].join(', ')}]`);
+    let id = slots.indexOf(piece.slot);
+    if (id < 0) id = slots.push(piece.slot) - 1;
+    rasterisePiece(page, piece, project, viewport, (px, py, _r, _g, _b, a) => {
+      if (a < need) return;
+      const at = py * viewport.width + px;
+      const list = lists[at];
+      if (list === null) lists[at] = [id];
+      else if (!list.includes(id)) list.push(id);
+    });
+  }
+  return { slots, lists };
+}
+
+/** Every slot's drawn pixel count on one frame, by name. */
+function drawnPx(draw: FrameDraw): Map<string, number> {
+  const counts = new Array<number>(draw.slots.length).fill(0);
+  for (const list of draw.lists) if (list !== null) for (const id of list) counts[id]++;
+  return new Map(draw.slots.map((name, id) => [name, counts[id]]));
+}
+
+/** One frame's pairs, off its per-pixel lists: each slot covers every slot listed before it at a pixel. */
+function framePairs(draw: FrameDraw, width: number): FramePair[] {
+  const found = new Map<string, FramePair>();
+  for (let at = 0; at < draw.lists.length; at++) {
+    const list = draw.lists[at];
+    if (list === null || list.length < 2) continue;
+    const x = at % width;
+    const y = (at - x) / width;
+    for (let j = 1; j < list.length; j++) {
+      for (let i = 0; i < j; i++) {
+        const under = draw.slots[list[i]];
+        const over = draw.slots[list[j]];
+        const key = `${under}\u0000${over}`;
+        const pair = found.get(key);
+        if (pair === undefined) found.set(key, { under, over, px: 1, box: [x, y, x, y] });
+        else {
+          pair.px++;
+          pair.box = [Math.min(pair.box[0], x), Math.min(pair.box[1], y), Math.max(pair.box[2], x), Math.max(pair.box[3], y)];
+        }
+      }
+    }
+  }
+  return [...found.values()].sort(pairOrder);
+}
+
+/** Ascending indices as inclusive runs: `[3, 4, 5, 9]` → `[[3, 5], [9, 9]]`. */
+function runsOf(indices: readonly number[]): Array<[number, number]> {
+  const runs: Array<[number, number]> = [];
+  for (const i of indices) {
+    const last = runs[runs.length - 1];
+    if (last !== undefined && i === last[1] + 1) last[1] = i;
+    else runs.push([i, i]);
+  }
+  return runs;
+}
+
+/** What `overlaps.json` states its numbers mean — the one wording the file and the docs share. */
+export const OVERLAPS_RULE =
+  "the slot drawn later covers the earlier one: per frame every piece is rasterised in that frame's draw order on the render's own viewport, and a pixel a slot draws where earlier slots already drew counts one for each (earlier, later) pair; under is the earlier-drawn slot, over the later";
+
+/** One set's reading, plus what the plates need: the frames' per-pixel lists, kept only for frames a plate is drawn of. */
+export interface OverlapReading {
+  frames: OverlapsFile['frames'];
+  pairs: PairTotal[];
+  /** Per plated frame index, its draw — the frames with a varying pair covering. */
+  plated: Map<number, FrameDraw>;
+}
+
+/**
+ * One set's reading: `frames` as the sampler returned them (pieces in draw
+ * order), `pages` the atlas pages the pieces sample, `viewport` the render's.
+ */
+export function overlapsOf(frames: readonly OverlapFrame[], pages: ReadonlyMap<string, Plate>, viewport: Viewport, plant: OverlapPlant = {}): OverlapReading {
+  const draws: FrameDraw[] = [];
+  const perFrame: OverlapsFile['frames'] = [];
+  const seen = new Map<string, { under: string; over: string; on: Array<{ index: number; px: number; inside: boolean }> }>();
+  for (const frame of frames) {
+    const draw = drawFrame(frame, pages, viewport, plant);
+    draws.push(draw);
+    const pairs = framePairs(draw, viewport.width);
+    perFrame.push({ index: frame.index, time: frame.time, pairs });
+    const drawn = drawnPx(draw);
+    for (const p of pairs) {
+      const key = `${p.under}\u0000${p.over}`;
+      const entry = seen.get(key) ?? { under: p.under, over: p.over, on: [] };
+      entry.on.push({ index: frame.index, px: p.px, inside: p.px === drawn.get(p.over) });
+      seen.set(key, entry);
+    }
+  }
+  const pairs: PairTotal[] = [...seen.values()]
+    .map(({ under, over, on }) => {
+      let most = on[0];
+      for (const o of on) if (o.px > most.px) most = o;
+      const inside = on.every((o) => o.inside);
+      const still = on.length === frames.length && (inside || on.every((o) => o.px === on[0].px));
+      return {
+        under,
+        over,
+        frames: on.length,
+        of: frames.length,
+        runs: runsOf(on.map((o) => o.index)),
+        most: { index: most.index, px: most.px },
+        inside,
+        varies: plant.noStatic === true || !still,
+      };
+    })
+    .sort(pairOrder);
+  const moving = new Set(pairs.filter((p) => p.varies).map((p) => `${p.under}\u0000${p.over}`));
+  const plated = new Map<number, FrameDraw>();
+  perFrame.forEach((f, i) => {
+    if (f.pairs.some((p) => moving.has(`${p.under}\u0000${p.over}`))) plated.set(f.index, draws[i]);
+  });
+  return { frames: perFrame, pairs, plated };
+}
+
+/** The file for one frame set. */
+export function overlapsFileOf(animation: string | null, fps: number, skin: string | undefined, reading: OverlapReading): OverlapsFile {
+  return {
+    spec: OVERLAPS_SPEC,
+    animation,
+    ...(skin === undefined ? {} : { skin }),
+    fps,
+    reading: { drawnAlpha: DRAWN_ALPHA, unit: 'frame pixels', rule: OVERLAPS_RULE },
+    frames: reading.frames,
+    pairs: reading.pairs,
+  };
+}
+
+/** The file's text: two-space JSON and a newline, so one build and one request are one byte sequence. */
+export function overlapsText(file: OverlapsFile): string {
+  return `${JSON.stringify(file, null, 2)}\n`;
+}
+
+/** `n` with a comma between thousands, written out rather than asked of a locale: `1840` → `1,840`. */
+export function groupedPx(n: number): string {
+  const digits = String(n);
+  let out = '';
+  for (let i = 0; i < digits.length; i++) {
+    if (i > 0 && (digits.length - i) % 3 === 0) out += ',';
+    out += digits[i];
+  }
+  return out;
+}
+
+/** Inclusive runs as the line prints them: `12–41, 50`. */
+function runsText(runs: ReadonlyArray<[number, number]>): string {
+  return runs.map(([a, b]) => (a === b ? String(a) : `${a}–${b}`)).join(', ');
+}
+
+/** Where a line is: the animation, or the setup pose for a skeleton with none. */
+const whereOf = (animation: string | null): string => (animation === null ? 'the setup pose' : JSON.stringify(animation));
+
+/** The line for one varying pair: `OVERLAP "<under>" under "<over>": frames 12–41 (30 of 224), covered up to 1,840 px at frame 27`. */
+export function overlapLine(animation: string | null, pair: PairTotal): string {
+  return (
+    `${whereOf(animation)}: OVERLAP "${pair.under}" under "${pair.over}": frames ${runsText(pair.runs)} (${pair.frames} of ${pair.of}), ` +
+    `covered up to ${groupedPx(pair.most.px)} px at frame ${pair.most.index}`
+  );
+}
+
+/** The one line for a set's static layering, or `null` when it has none. */
+export function staticLine(animation: string | null, pairs: readonly PairTotal[]): string | null {
+  const k = pairs.filter((p) => !p.varies).length;
+  if (k === 0) return null;
+  return (
+    `${whereOf(animation)}: ${k} pair(s) cover on every frame by the same pixels, or with the slot in front drawn wholly on the one behind — ` +
+    `layering the motion does not move; ${OVERLAPS_FILE} lists them`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// the outline plate
+// ---------------------------------------------------------------------------
+
+/** The plate's background: plain white, so every contour colour reads against it. */
+export const PLATE_BACKGROUND: RGBA = [255, 255, 255, 255];
+
+/**
+ * The contour colours, by a slot's place in its set's participants (every slot
+ * in a varying pair, in code-unit order), modulo the table's length — so one
+ * slot keeps one colour across a set's plates. Eight saturated hues far apart
+ * on the wheel and none near the white background; the table means nothing
+ * beyond "a different slot", and the name at each contour says which.
+ */
+export const PLATE_COLOURS: readonly RGBA[] = [
+  [214, 39, 40, 255],
+  [31, 119, 180, 255],
+  [44, 160, 44, 255],
+  [148, 103, 189, 255],
+  [255, 127, 14, 255],
+  [23, 190, 207, 255],
+  [140, 86, 75, 255],
+  [227, 119, 194, 255],
+];
+
+/**
+ * A covered contour pixel is drawn when `(x + y) % 4 < 2`: on two, off two,
+ * along the diagonals — a dash the eye and a pixel count both tell from a solid
+ * line. An uncovered contour pixel is always drawn.
+ */
+export const dashOn = (x: number, y: number): boolean => (x + y) % 4 < 2;
+
+/** Whether two label boxes `[x, y, w, h]` touch or sit within one pixel. */
+const crowds = (a: [number, number, number, number], b: [number, number, number, number]): boolean =>
+  a[0] < b[0] + b[2] + 1 && b[0] < a[0] + a[2] + 1 && a[1] < b[1] + b[3] + 1 && b[1] < a[1] + a[3] + 1;
+
+/** One label the plate drew: the slot's name as printed, its box, the contour pixel it names, and whether a leader line joins them. */
+export interface PlateLabel {
+  /** The slot's name, exactly as the lines print it. */
+  name: string;
+  /** The label's ink box `[x0, y0, x1, y1]`, frame pixels, both ends inclusive — the text's full 5x7 cells. */
+  box: OverlapBox;
+  /** The contour pixel the label names: the slot's topmost boundary pixel, the leftmost on a tie. */
+  anchor: [number, number];
+  /** Whether no candidate along the contour was free and the label sits at the nearest free spot, joined by a line. */
+  leader: boolean;
+  /** Whether no free spot was left on the plate at all, so the label sits at its first candidate and may crowd another — stated, never silent. */
+  crowded: boolean;
+}
+
+/**
+ * A planted defect of the plate, for the suite's mutants only (`OX07`, `OX08`
+ * in `selftest.ts`). Production passes none.
+ */
+export interface OverlapPlatePlant {
+  /** Every label at its first candidate, above the contour's top, whatever it crowds — placement off. */
+  atTop?: boolean;
+  /** Labels drawn in capitals, as the font once drew every name. */
+  upper?: boolean;
+}
+
+/** An outline plate and the labels on it, as the writer placed them. */
+export interface LabelledPlate {
+  plate: Plate;
+  /** In draw order, one per participant drawn on the frame. */
+  labels: PlateLabel[];
+}
+
+/** A one-pixel line from (x0, y0) to (x1, y1), integer steps along the longer axis — no antialiasing, one pixel set per step. */
+function leaderLine(plate: Plate, x0: number, y0: number, x1: number, y1: number, colour: RGBA): void {
+  const n = Math.max(Math.abs(x1 - x0), Math.abs(y1 - y0));
+  for (let s = 0; s <= n; s++) {
+    const x = n === 0 ? x0 : x0 + Math.round(((x1 - x0) * s) / n);
+    const y = n === 0 ? y0 : y0 + Math.round(((y1 - y0) * s) / n);
+    if (x >= 0 && y >= 0 && x < plate.width && y < plate.height) plate.set(x, y, colour);
+  }
+}
+
+/**
+ * The outline plate of one frame: on `PLATE_BACKGROUND`, every slot of
+ * `participants` that draws on the frame as its mask boundary — a drawn pixel
+ * with an undrawn 4-neighbour, or on the plate's edge — in its colour, in the
+ * frame's draw order; a boundary pixel some slot drawn later also drew is
+ * covered, and drawn dashed (`dashOn`). Each slot's name is printed as the
+ * lines print it, in the case it has.
+ *
+ * ## Where a label goes (issue #1484)
+ *
+ * Labels are placed one at a time in the frame's draw order; a label is a box
+ * of `textWidth(name)` by `GLYPH_H` pixels, and a box is **free** when it does
+ * not touch or sit within one pixel of any box placed before it (`crowds`).
+ * Every candidate box is clamped into the plate before it is tried, so no label
+ * leaves the plate (a name wider than the plate is the one exception: it starts
+ * at x 0 and runs off the right edge). The candidates, in this fixed order:
+ *
+ * 1. for every boundary pixel of the slot's contour in raster order (top row
+ *    first, left to right — so the first is the contour's topmost pixel, the
+ *    leftmost on a tie, which is the label's anchor), the box above it
+ *    (`GLYPH_H + 1` up, left edge on the pixel), then below it (2 down), then to
+ *    its left (`2 +` the label's width), then to its right (2 across), the last
+ *    two centred on the pixel's row;
+ * 2. none free: every in-plate position in raster order, and the one whose box
+ *    centre is nearest the anchor (squared distance, the first in raster order
+ *    on a tie) wins, joined to the anchor by a one-pixel leader line drawn from
+ *    the anchor to the nearest pixel of the box, in the slot's colour;
+ * 3. no position free at all: the first candidate of step 1, marked `crowded`.
+ *
+ * The first free candidate wins. No randomness and no search order that
+ * depends on anything but the frame: one frame, one plate, on every machine.
+ */
+export function overlapPlateLabelled(reading: OverlapReading, index: number, participants: readonly string[], viewport: Viewport, plant: OverlapPlatePlant = {}): LabelledPlate | null {
+  const draw = reading.plated.get(index);
+  if (draw === undefined) return null;
+  const { width, height } = viewport;
+  const plate = new Plate(width, height);
+  for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) plate.set(x, y, PLATE_BACKGROUND);
+  const contours: Array<{ name: string; colour: RGBA; boundary: Array<[number, number]> }> = [];
+  for (let id = 0; id < draw.slots.length; id++) {
+    const name = draw.slots[id];
+    const place = participants.indexOf(name);
+    if (place < 0) continue;
+    const colour = PLATE_COLOURS[place % PLATE_COLOURS.length];
+    const has = (x: number, y: number): boolean => x >= 0 && y >= 0 && x < width && y < height && (draw.lists[y * width + x]?.includes(id) ?? false);
+    const boundary: Array<[number, number]> = [];
+    for (let y = 0; y < height; y++) {
+      for (let x = 0; x < width; x++) {
+        const list = draw.lists[y * width + x];
+        if (list === null) continue;
+        const k = list.indexOf(id);
+        if (k < 0) continue;
+        if (has(x - 1, y) && has(x + 1, y) && has(x, y - 1) && has(x, y + 1)) continue;
+        boundary.push([x, y]);
+        const covered = k < list.length - 1;
+        if (!covered || dashOn(x, y)) plate.set(x, y, colour);
+      }
+    }
+    if (boundary.length > 0) contours.push({ name, colour, boundary });
+  }
+  const taken: Array<[number, number, number, number]> = [];
+  const labels: PlateLabel[] = [];
+  const h = GLYPH_H;
+  for (const { name, colour, boundary } of contours) {
+    const text = plant.upper ? name.toUpperCase() : name;
+    const w = textWidth(text, 1);
+    const clamp = (x: number, y: number): [number, number, number, number] => [Math.max(0, Math.min(width - w, x)), Math.max(0, Math.min(height - h, y)), w, h];
+    const free = (box: [number, number, number, number]): boolean => !taken.some((t) => crowds(t, box));
+    const anchor = boundary[0];
+    const first = clamp(anchor[0], anchor[1] - h - 1);
+    let box: [number, number, number, number] | null = null;
+    let leader = false;
+    let crowded = false;
+    if (plant.atTop) box = first;
+    for (let i = 0; box === null && i < boundary.length; i++) {
+      const [cx, cy] = boundary[i];
+      const mid = cy - Math.floor(h / 2);
+      for (const c of [clamp(cx, cy - h - 1), clamp(cx, cy + 2), clamp(cx - w - 2, mid), clamp(cx + 2, mid)]) {
+        if (free(c)) {
+          box = c;
+          break;
+        }
+      }
+    }
+    if (box === null) {
+      let best: [number, number, number, number] | null = null;
+      let bestD = Number.POSITIVE_INFINITY;
+      for (let y = 0; y + h <= height; y++) {
+        for (let x = 0; x + w <= width; x++) {
+          const c: [number, number, number, number] = [x, y, w, h];
+          const dx = 2 * x + w - 1 - 2 * anchor[0];
+          const dy = 2 * y + h - 1 - 2 * anchor[1];
+          const d = dx * dx + dy * dy;
+          if (d < bestD && free(c)) {
+            best = c;
+            bestD = d;
+          }
+        }
+      }
+      if (best !== null) {
+        box = best;
+        leader = true;
+        const lx = Math.max(best[0], Math.min(best[0] + w - 1, anchor[0]));
+        const ly = Math.max(best[1], Math.min(best[1] + h - 1, anchor[1]));
+        leaderLine(plate, anchor[0], anchor[1], lx, ly, colour);
+      } else {
+        box = first;
+        crowded = true;
+      }
+    }
+    taken.push(box);
+    plate.text(text, box[0], box[1], 1, colour);
+    labels.push({ name: text, box: [box[0], box[1], box[0] + w - 1, box[1] + h - 1], anchor: [anchor[0], anchor[1]], leader, crowded });
+  }
+  return { plate, labels };
+}
+
+/** The outline plate of one frame, without its label list — `overlapPlateLabelled`'s picture. */
+export function overlapPlate(reading: OverlapReading, index: number, participants: readonly string[], viewport: Viewport): Plate | null {
+  return overlapPlateLabelled(reading, index, participants, viewport)?.plate ?? null;
+}
+
+/** A set's participants: every slot in a varying pair, in code-unit order — what the plate colours index. */
+export function plateParticipants(pairs: readonly PairTotal[]): string[] {
+  const names = new Set<string>();
+  for (const p of pairs) {
+    if (!p.varies) continue;
+    names.add(p.under);
+    names.add(p.over);
+  }
+  return [...names].sort(byCodeUnit);
+}

package/src/render_shared.ts

@@ -204,6 +204,23 @@ export interface FrameSet {
    * taken without.
    */
   physics?: { stepped: number; fps: number };
+  /**
+   * The overlap reading, when `render --overlaps` asked for it (issue #1480):
+   * the file it wrote, how many slot pairs cover anything on any frame, how
+   * many of those are static layering (the same pixels on every frame), how
+   * many outline plates were drawn, and every pair that moves — under, over,
+   * the frames it covers on and the frame it covers the most pixels on.
+   *
+   * ⭐ Absent unless asked for, for `skin`'s reason in `FramesSidecar`: a render
+   * without the flag stays the bytes it always was.
+   */
+  overlaps?: {
+    file: string;
+    pairs: number;
+    static: number;
+    plates: number;
+    moving: Array<{ under: string; over: string; frames: number; most: { index: number; px: number } }>;
+  };
 }
 
 export interface FramesSidecar {

package/tools/font5x7.ts

@@ -1,5 +1,5 @@
 /**
- * A 5x7 bitmap font, uppercase + digits + a little punctuation.
+ * A 5x7 bitmap font: uppercase, lowercase, digits and a little punctuation.
  *
  * It exists so a generated plate can burn its own name into its own pixels with
  * no font file, no canvas and no dependency. That matters more than it sounds:
@@ -7,7 +7,9 @@
  * for real art, and the strongest form of that is the word PLACEHOLDER sitting
  * in the image itself.
  *
- * Each glyph is 7 rows of 5 bits, MSB = leftmost column.
+ * Each glyph is 7 rows of 5 bits, MSB = leftmost column. Lowercase sits in the
+ * same 5x7 cell, x-height from row 2, a descender (g j p q y) ending on row 6 —
+ * the cell has no eighth row (issue #1484: a slot named `arm_b` reads `arm_b`).
  */
 const GLYPHS: Record<string, number[]> = {
   A: [0x0e, 0x11, 0x11, 0x1f, 0x11, 0x11, 0x11],
@@ -36,6 +38,32 @@ const GLYPHS: Record<string, number[]> = {
   X: [0x11, 0x11, 0x0a, 0x04, 0x0a, 0x11, 0x11],
   Y: [0x11, 0x11, 0x0a, 0x04, 0x04, 0x04, 0x04],
   Z: [0x1f, 0x01, 0x02, 0x04, 0x08, 0x10, 0x1f],
+  a: [0x00, 0x00, 0x0e, 0x01, 0x0f, 0x11, 0x0f],
+  b: [0x10, 0x10, 0x16, 0x19, 0x11, 0x11, 0x1e],
+  c: [0x00, 0x00, 0x0e, 0x10, 0x10, 0x11, 0x0e],
+  d: [0x01, 0x01, 0x0d, 0x13, 0x11, 0x11, 0x0f],
+  e: [0x00, 0x00, 0x0e, 0x11, 0x1f, 0x10, 0x0e],
+  f: [0x06, 0x09, 0x08, 0x1c, 0x08, 0x08, 0x08],
+  g: [0x00, 0x0f, 0x11, 0x11, 0x0f, 0x01, 0x0e],
+  h: [0x10, 0x10, 0x16, 0x19, 0x11, 0x11, 0x11],
+  i: [0x04, 0x00, 0x0c, 0x04, 0x04, 0x04, 0x0e],
+  j: [0x02, 0x00, 0x06, 0x02, 0x02, 0x12, 0x0c],
+  k: [0x10, 0x10, 0x12, 0x14, 0x18, 0x14, 0x12],
+  l: [0x0c, 0x04, 0x04, 0x04, 0x04, 0x04, 0x0e],
+  m: [0x00, 0x00, 0x1a, 0x15, 0x15, 0x11, 0x11],
+  n: [0x00, 0x00, 0x16, 0x19, 0x11, 0x11, 0x11],
+  o: [0x00, 0x00, 0x0e, 0x11, 0x11, 0x11, 0x0e],
+  p: [0x00, 0x00, 0x1e, 0x11, 0x1e, 0x10, 0x10],
+  q: [0x00, 0x00, 0x0d, 0x13, 0x0f, 0x01, 0x01],
+  r: [0x00, 0x00, 0x16, 0x19, 0x10, 0x10, 0x10],
+  s: [0x00, 0x00, 0x0e, 0x10, 0x0e, 0x01, 0x1e],
+  t: [0x08, 0x08, 0x1c, 0x08, 0x08, 0x09, 0x06],
+  u: [0x00, 0x00, 0x11, 0x11, 0x11, 0x13, 0x0d],
+  v: [0x00, 0x00, 0x11, 0x11, 0x11, 0x0a, 0x04],
+  w: [0x00, 0x00, 0x11, 0x11, 0x15, 0x15, 0x0a],
+  x: [0x00, 0x00, 0x11, 0x0a, 0x04, 0x0a, 0x11],
+  y: [0x00, 0x00, 0x11, 0x11, 0x0f, 0x01, 0x0e],
+  z: [0x00, 0x00, 0x1f, 0x02, 0x04, 0x08, 0x1f],
   '0': [0x0e, 0x11, 0x13, 0x15, 0x19, 0x11, 0x0e],
   '1': [0x04, 0x0c, 0x04, 0x04, 0x04, 0x04, 0x0e],
   '2': [0x0e, 0x11, 0x01, 0x02, 0x04, 0x08, 0x1f],
@@ -73,8 +101,10 @@ export function textWidth(text: string, scale: number): number {
 
 /**
  * Rasterise `text` by calling `plot(x, y)` for every lit pixel, with the top
- * left of the first glyph at (x0, y0). Unknown characters draw as a full block
- * so a typo is loud rather than invisible.
+ * left of the first glyph at (x0, y0). Text is drawn in the case it is given —
+ * the font once upper-cased everything, so a lowercase name printed in capitals
+ * (issue #1484). Unknown characters draw as a full block so a typo is loud
+ * rather than invisible.
  */
 export function drawText(
   text: string,
@@ -84,7 +114,7 @@ export function drawText(
   plot: (x: number, y: number) => void,
 ): void {
   let cursor = x0;
-  for (const ch of text.toUpperCase()) {
+  for (const ch of text) {
     const glyph = GLYPHS[ch] ?? [0x1f, 0x1f, 0x1f, 0x1f, 0x1f, 0x1f, 0x1f];
     for (let row = 0; row < GLYPH_H; row++) {
       for (let col = 0; col < GLYPH_W; col++) {