spine-rigc 3.3.0 → 3.4.0

package/docs/AUTHORING.md

@@ -378,11 +378,12 @@ What the flags mean:
 | `--max` | `render` and `inspect`: the longest side of the frame in pixels (default `256`, finite and at least `16`). On `render`, refused with `--viewport-from`, which already fixes the pixel size — **§8.6**, **§13** |
 | `--show`, `--dim`, `--at`, `--zoom` | `inspect` only — what it draws, whether the art is faded, which times of `--animation` it poses and the bone, slot or folds it frames to; §13 says each, with the refusals |
 | `--geometry` | `render` only: also write a `geometry.json` into each frame directory — per frame, every bone's world transform and every slot's region or mesh vertices in world units after skinning, plus each attachment's rest geometry and topology, on the frames' own grid and viewport. Every other file is byte for byte what the render writes without it. Refused with `--slot`/`--hide`, because the geometry is the whole pose whatever is drawn — **§8.2** |
-| `--extremes-only` | `render` only: imply `--extremes`, but write only `extremes.json` and readable `extremes.png` with the same bytes. Pose the same grid; rasterize only the setup/min/max pictures used by the plate. No ordinary frame PNGs, contact sheet or `frames.json`. Takes no `--sheet`, `--sheet-format`, `--page-edges`, `--geometry`, `--folds`, `--pass-through`, `--seam`, `--overlaps` or `--angle-range`; drop the named flag or use `--extremes` instead — **§8.11** |
+| `--extremes-only` | `render` only: imply `--extremes`, but write only `extremes.json` and readable `extremes.png` with the same bytes. Pose the same grid; rasterize only the setup/min/max pictures used by the plate. No ordinary frame PNGs, contact sheet or `frames.json`. Takes no `--sheet`, `--sheet-format`, `--page-edges`, `--geometry`, `--folds`, `--pass-through`, `--seam`, `--seam-cells`, `--overlaps` or `--angle-range`; drop the named flag or use `--extremes` instead — **§8.11** |
 | `--parallax` | `render` only: a named slider dial, through the core poser. Write `parallax.json` and a readable `parallax.png` into `--out` on a fixed 9-value grid. This is a separate dial render mode, with `--skin`, `--max`, `--candidate`, `--atlas` and `--poser core`; it takes no animation, fps, subset, other diagnostic, sheet, environment or viewport flag. A missing dial is refused by name; unavailable fits report SKIP, never a pass — **§8.12** |
 | `--extremes` | `render` only: add `extremes.json` and an `EXTREMES` line per set; a moving set with comparable geometry and readable images also gets a native six-panel `extremes.png`: setup, geometry-pair min/max and three premultiplied RGBA diffs with a legend. Per-channel extrema are independent of that geometry pair; valid channels survive geometry/image SKIPs, and channel refusals are named separately. Still or uncomparable geometry is a named SKIP, with no invented pair or PNG; observation failures do not change a successful render's exit status. Supports `--slot`/`--hide` on both posers, on the whole rig's viewport. Without the flag, no extremes observations are added — **§8.11** |
 | `--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-cells` | `render` only, with `--seam`: add exact `cells` lists to `gapOpen`/`gapCovered` hits (including `worst`), with setup-pose top and underlying slot names at the same world cell. Without `--seam` it is refused before output. No effect on the counts — **§8.8** |
 | `--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 visible overlap band of one showing where, from its partner's point of view, nothing was drawn), plus `exposureA`/`exposureB` for each named slot’s positive-alpha drawing on otherwise empty skeleton background, 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** |
@@ -9396,6 +9397,33 @@ block carries the definitions above in words.
 | hit `area` | number | world units² | `px × cell²` |
 | hit `box` | `[minX, minY, maxX, maxY]` | world units, y up | the counted cells' whole squares, in Spine world |
 
+**Exact cells, opt-in.** Add `--seam-cells` beside `--seam` to retain the
+cells counted by the existing gap classifier. Only `gapOpen` and `gapCovered`
+hits gain `cells`; `gap`, `ghost` and exposure hits keep their old shape. Each
+entry is `{ x, y, setupTop, setupUnder }`: `x,y` are the cell **centre** in world
+units, y up; the hit's `cell` gives the square's side. Lists are in descending
+`y`, then ascending `x` order (top row first, left to right), with no duplicates.
+Every nonempty hit has `cells.length === px`; absent hits still mean zero and
+SKIP pairs remain unmeasured. `worst` carries the same list as its frame hit.
+
+`setupTop` is the topmost slot whose setup drawing emits positive rendered alpha
+at that **same world cell**, and `setupUnder` is the next distinct covering slot
+beneath it in setup draw order. Each is a slot name or `null` if absent. All
+slots participate, including third slots, faint alpha, texture holes and clipped
+fragments; multiple fragments of one slot count as one layer. These are setup
+layers, not the current frame's cover, not spatial neighbors, and not a cell
+carried back by the seam's inverse attachment maps. A currently open cell can
+therefore name setup art; a cell beyond all setup art has two null names.
+
+This is an additive opt-in extension of **`rigc-seam/1`**: readers ignoring
+unknown hit keys retain every existing number and meaning. Exact-object readers
+must opt into the new shape. With the flag absent no setup attribution is sampled
+or rasterized and the sidecar bytes remain unchanged. With it present, setup is
+sampled lazily once per recipe/skin and its rendered-alpha layers are cached per
+distinct seam cell side across pairs and animation sets; only listed cells query
+the cache. Determinism controls compare two complete flagged renders, not just
+list lengths.
+
 A downstream warning is a projection of this file and needs nothing re-measured:
 one span of one kind is `{ pair: "<a>|<b>", frames: span.frames, times:
 span.times, maxPx: span.maxPx, kind }`, and one pair over one animation is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "3.3.0",
+  "version": "3.4.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

@@ -45,7 +45,7 @@ import { PASS_THROUGH_FILE, passFrameLine, type PassPair, passSummaryLine, passT
 import type { Plate } from '../../tools/plate.ts';
 import { OVERLAPS_FILE, OverlapError, overlapLine, overlapPlate, overlapsFileOf, overlapsOf, overlapsPlateFile, overlapsText, plateParticipants, staticLine } from '../overlaps.ts';
 import { buildSheetSet, SHEET_MANIFEST_FILE, type SheetSetPack, SheetUsageError, sheetRigNameOf, sheetSidecarRecord, sheetSourceOf } from '../sheet.ts';
-import { readSeamPairs, SEAM_FILE, seamFileOf, seamLine, SeamError, type SeamPair, seamsOf, seamText } from '../seam.ts';
+import { readSeamPairs, SEAM_FILE, seamFileOf, seamLine, SeamError, type SeamPair, seamsOf, seamText, setupCellReader } from '../seam.ts';
 import { environmentCollisions, environmentFrame, EnvironmentError, environmentResponse, readEnvironmentSchedule, type EnvironmentStep } from '../environment.ts';
 import { estimatePose, poseLines, type PoseOptions } from '../pose.ts';
 import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, frameSetDir, type FrameSet, type FramesSidecar, framingViewport, GEOMETRY_FILE, geometryFileOf, geometryText, loadCandidate, POSER_NAMES, type PoserName, prerollStart, prerollWarmPoints, PROTOCOL_FPS, refuseUnchosen, renderFrame, sampleAll, sampleAnimation, sampleSetupPose, SETUP_POSE_DIR, SHEET_FILE, SHEET_TILE, sidecarViewport, type SkeletonFacts, type SlotSubset, SlotSubsetError, throughPoser, type Viewport, viewportFor } from '../render_shared.ts';
@@ -737,7 +737,7 @@ export function cmdRender(flags: Record<string, string>): void {
   const given = readGivenViewport(flags);
   const extremesOnly = flags['extremes-only'] !== undefined;
   if (extremesOnly) {
-    for (const flag of ['sheet', 'sheet-format', 'page-edges', 'geometry', 'folds', 'pass-through', 'seam', 'overlaps', 'angle-range', 'boundary-from']) {
+    for (const flag of ['sheet', 'sheet-format', 'page-edges', 'geometry', 'folds', 'pass-through', 'seam', 'seam-cells', 'overlaps', 'angle-range', 'boundary-from']) {
       if (flags[flag] !== undefined) {
         throw new UsageError(`--extremes-only takes no --${flag}: it writes only extremes.json and, when readable, extremes.png. Drop --${flag}, or use --extremes for ordinary frames and additional outputs`);
       }
@@ -827,6 +827,8 @@ export function cmdRender(flags: Record<string, string>): void {
   // 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;
+  const seamCells = flags['seam-cells'] !== undefined;
+  if (seamCells && seam === undefined) throw new UsageError('--seam-cells needs --seam <slot>:<slot>[,…]; no pair was supplied');
   if (seam !== undefined) {
     for (const flag of ['slot', 'hide'] as const) {
       if (flags[flag] !== undefined) {
@@ -854,7 +856,7 @@ export function cmdRender(flags: Record<string, string>): void {
     posersAsked(flags),
   );
   if (flags.parallax !== undefined) {
-    for (const flag of ['animation', 'fps', 'slot', 'hide', 'geometry', 'folds', 'extremes', 'extremes-only', 'pass-through', 'seam', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'preroll', 'physics', 'boundary-from', 'viewport', 'viewport-from']) {
+    for (const flag of ['animation', 'fps', 'slot', 'hide', 'geometry', 'folds', 'extremes', 'extremes-only', 'pass-through', 'seam', 'seam-cells', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'preroll', 'physics', 'boundary-from', 'viewport', 'viewport-from']) {
       if (flags[flag] !== undefined) throw new UsageError(`--parallax takes no --${flag}: it samples one named dial on its own 9-value grid; drop --${flag} or run ordinary render separately`);
     }
     if (flags.poser !== undefined && flags.poser !== 'core') throw new UsageError('--parallax requires --poser core: it reads only a rigc compiled model');
@@ -1070,6 +1072,7 @@ export function cmdRender(flags: Record<string, string>): void {
     // whose slot draws on no frame of any set drawn is refused, as --pass-through refuses it, rather than read as a SKIP.
     const seamReadings = new Map<string, ReturnType<typeof seamFileOf>>();
     if (seamPairs !== undefined) {
+      const cells = seamCells ? setupCellReader(() => sampleSetupPose(poser, { skin })[0].pieces, pages) : undefined;
       const draws = new Set<string>();
       for (const frames of sampled.values()) for (const frame of frames) for (const piece of frame.pieces) draws.add(piece.slot);
       for (const pair of seamPairs) {
@@ -1087,7 +1090,7 @@ export function cmdRender(flags: Record<string, string>): void {
         const shown = frames.map((frame) => frame.attachments ?? []);
         const read = frames.map((frame) => ({ index: frame.index, time: frame.time, pieces: frame.pieces, attachments: frame.attachments ?? [] }));
         try {
-          seamReadings.set(name, seamFileOf(animation, fps, skin, seamsOf(seamPairs, poser.rest(skin, shown), read, pages)));
+          seamReadings.set(name, seamFileOf(animation, fps, skin, seamsOf(seamPairs, poser.rest(skin, shown), read, pages, {}, { cells })));
         } catch (err) {
           if (err instanceof SeamError) throw new UsageError(`--seam, ${JSON.stringify(name)}: ${err.message}`);
           throw err;

package/src/cli/shared.ts

@@ -151,7 +151,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', 'extremes', 'extremes-only', 'overlaps', 'sheet', 'accept-skeleton-differences', 'keep-pages', 'dim']);
+const BOOLEAN_FLAGS = new Set(['all', 'all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'seam-cells', 'folds', 'extremes', 'extremes-only', 'overlaps', 'sheet', 'accept-skeleton-differences', 'keep-pages', 'dim']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -1072,8 +1072,9 @@ const FLAG_MEANINGS: Record<string, string> = {
     '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",
   parallax: 'read one named slider dial through the core poser on 9 evenly spaced values: parallax.json plus setup/extreme/diff/affine-residual heat-map parallax.png; geometry only, no assertion or pass threshold. A separate dial render mode; takes no animation, fps, other diagnostics, sheet, subset, environment, preroll or viewport flags',
-  'extremes-only': 'write only extremes.json and readable extremes.png per set, with the same posed grid and bytes as --extremes; no ordinary frame PNGs, contact.png or frames.json. Implies --extremes; takes no --sheet, --sheet-format, --page-edges, --geometry, --folds, --pass-through, --seam, --overlaps or --angle-range',
+  'extremes-only': 'write only extremes.json and readable extremes.png per set, with the same posed grid and bytes as --extremes; no ordinary frame PNGs, contact.png or frames.json. Implies --extremes; takes no --sheet, --sheet-format, --page-edges, --geometry, --folds, --pass-through, --seam, --seam-cells, --overlaps or --angle-range',
   extremes: 'also write extremes.json and a native six-panel extremes.png per set: setup, geometry-pair min/max and premultiplied RGBA diffs, with a legend. Per-channel extrema are recorded separately and valid channels survive geometry/image SKIPs; channel refusals are named separately. Still geometry reports SKIP; a reading, not a gate. Attachment identity/count changes record a named SKIP without changing render exit; supports --slot/--hide on both posers',
+  'seam-cells': 'with --seam, include exact world-grid cells on gapOpen/gapCovered hits, with setupTop/setupUnder slots; absent by default',
   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 carried overlap hull and a local sweep of the same setup band cell through both drawings — ' +
@@ -1789,7 +1790,7 @@ export const COMMANDS: CommandDoc[] = [
       'rigc render … --viewport <x,y,w,h> | --viewport-from <frames.json>   (a box given, not fitted: two renders on one pixel grid)',
       'rigc render … --sheet [--sheet-format json-hash] [--page-edges pot|free]   (deterministic sprite sheets + JSON hash table + sheet-manifest.json per set)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'extremes', 'extremes-only', 'parallax', 'pass-through', 'seam', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'preroll', 'physics', 'boundary-from', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'extremes', 'extremes-only', 'parallax', 'pass-through', 'seam', 'seam-cells', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'preroll', 'physics', 'boundary-from', 'poser', 'out'],
     overrides: {
       'page-edges': {
         meaning:

package/src/seam.ts

@@ -133,6 +133,69 @@ export interface SeamFrame {
 /** A world box `[minX, minY, maxX, maxY]`, world units, y up. */
 export type SeamBox = [number, number, number, number];
 
+/** One counted gap cell: centre in world units, y up. */
+export interface SeamCell {
+  x: number;
+  y: number;
+  setupTop: string | null;
+  setupUnder: string | null;
+}
+
+/** Optional detail; absent preserves the existing sidecar bytes. */
+export interface SeamOptions {
+  cells?: SeamCellReader;
+}
+
+/** Fills setup attribution for counted cells; reusable across pairs and frame sets. */
+export type SeamCellReader = (cells: SeamCell[], side: number) => void;
+
+/**
+ * Lazy setup raster, once per distinct cell side. Slot occupancy uses the same
+ * positive rendered-alpha traversal as gap coverage, without source-over hiding
+ * the layer below. Repeated fragments of one slot are one layer.
+ */
+export function setupCellReader(setup: () => readonly Piece[], pages: ReadonlyMap<string, Plate>): SeamCellReader {
+  const cache = new Map<number, { viewport: Viewport; names: string[]; top: Int32Array; under: Int32Array } | null>();
+  let pieces: readonly Piece[] | undefined;
+  return (cells, side) => {
+    if (cells.length === 0) return;
+    if (!cache.has(side)) {
+      pieces ??= setup();
+      if (pieces.length === 0) cache.set(side, null);
+      else {
+        const { viewport } = gridOf([], side, pieces);
+        const top = new Int32Array(viewport.width * viewport.height).fill(-1);
+        const under = new Int32Array(top.length).fill(-1);
+        const names = [...new Set(pieces.map(p => p.slot))];
+        const ids = new Map(names.map((name, i) => [name, i]));
+        const project = projector(viewport);
+        for (const piece of pieces) {
+          const page = pages.get(piece.page);
+          if (page === undefined) throw new SeamError(`setup slot "${piece.slot}" samples missing atlas page "${piece.page}"; available [${[...pages.keys()].join(', ')}]`);
+          const id = ids.get(piece.slot)!;
+          rasterisePiece(page, piece, project, viewport, (x, y, _r, _g, _b, alpha) => {
+            const k = y * viewport.width + x;
+            if (alpha > 0 && top[k] !== id) { under[k] = top[k]; top[k] = id; }
+          });
+        }
+        cache.set(side, { viewport, names, top, under });
+      }
+    }
+    const read = cache.get(side);
+    for (const cell of cells) {
+      cell.setupTop = null; cell.setupUnder = null;
+      if (read == null) continue;
+      const { viewport, names, top, under } = read;
+      const x = Math.round((cell.x - viewport.minX) / side - 0.5);
+      const y = Math.round((viewport.maxY - cell.y) / side - 0.5);
+      if (x < 0 || y < 0 || x >= viewport.width || y >= viewport.height) continue;
+      const k = y * viewport.width + x;
+      cell.setupTop = names[top[k]] ?? null;
+      cell.setupUnder = names[under[k]] ?? null;
+    }
+  };
+}
+
 /** What one frame reads of one kind. */
 export interface SeamHit {
   index: number;
@@ -146,6 +209,8 @@ export interface SeamHit {
   area: number;
   /** The counted cells' whole squares, world units, y up. */
   box: SeamBox;
+  /** Opt-in on gapOpen/gapCovered only; descending y, then ascending x. */
+  cells?: SeamCell[];
 }
 
 /** A run of consecutive frames of one kind — first and last frame, their times, the most cells on any of them. */
@@ -385,6 +450,7 @@ interface Side {
 interface Cells {
   px: number;
   box: SeamBox | null;
+  cells?: SeamCell[];
 }
 
 const restPiece = (side: Side): Piece => ({ ...side.piece, world: Array.from(side.rest) });
@@ -530,7 +596,7 @@ function contactOf(restA: Uint8Array, restB: Uint8Array, drawnA: Uint8Array, dra
 }
 
 /** One frame's counts, or `null` when the two drawings share no cell at the setup pose. See the module comment. */
-function readFrame(A: Side, B: Side, cell: number, plant: SeamPlant, frame: SeamFrame, pages: ReadonlyMap<string, Plate>, grid: Grid, visibility: readonly Uint8Array[]): { gap: Cells; ghost: Cells; ghostA: Cells; ghostB: Cells; gapOpen: Cells; gapCovered: Cells; contact: Contact } | null {
+function readFrame(A: Side, B: Side, cell: number, plant: SeamPlant, frame: SeamFrame, pages: ReadonlyMap<string, Plate>, grid: Grid, visibility: readonly Uint8Array[], options: SeamOptions): { gap: Cells; ghost: Cells; ghostA: Cells; ghostB: Cells; gapOpen: Cells; gapCovered: Cells; contact: Contact } | null {
   const { width, height } = grid.viewport;
   const restA = restPiece(A);
   const restB = restPiece(B);
@@ -589,8 +655,8 @@ function readFrame(A: Side, B: Side, cell: number, plant: SeamPlant, frame: Seam
   const ghost: Cells = { px: 0, box: null };
   const ghostA: Cells = { px: 0, box: null };
   const ghostB: Cells = { px: 0, box: null };
-  const gapOpen: Cells = { px: 0, box: null };
-  const gapCovered: Cells = { px: 0, box: null };
+  const gapOpen: Cells = { px: 0, box: null, ...(options.cells ? { cells: [] } : {}) };
+  const gapCovered: Cells = { px: 0, box: null, ...(options.cells ? { cells: [] } : {}) };
   let alphaCells: Uint8Array | null = null;
   const take = (into: Cells, qx: number, qy: number): void => takeCell(into, qx, qy, cell);
   if (plant.never) return { gap, ghost, ghostA, ghostB, gapOpen, gapCovered, contact };
@@ -610,7 +676,9 @@ function readFrame(A: Side, B: Side, cell: number, plant: SeamPlant, frame: Seam
           take(gap, qx, qy);
           const covered = plant.gapCoverage === 'covered' || (plant.gapCoverage !== 'open' &&
             (alphaCells ??= frameAlphaCells(plant.gapCoverage === 'pair' ? [A.piece, B.piece] : frame.pieces, pages, grid.viewport, plant.gapCoverage === 'half'))[k] !== 0);
-          take(covered ? gapCovered : gapOpen, qx, qy);
+          const into = covered ? gapCovered : gapOpen;
+          take(into, qx, qy);
+          into.cells?.push({ x: qx, y: qy, setupTop: null, setupUnder: null });
         }
         continue;
       }
@@ -665,6 +733,7 @@ export function seamsOf(
   frames: readonly SeamFrame[],
   pages: ReadonlyMap<string, Plate>,
   plant: SeamPlant = {},
+  options: SeamOptions = {},
 ): SeamPairReading[] {
   const restOf = new Map(rest.map((r) => [restKey(r.slot, r.attachment), r]));
   const sideOf = (frame: SeamFrame, slot: string): Side | null => {
@@ -711,13 +780,17 @@ export function seamsOf(
       if (A === null || B === null) continue;
       drawn++;
       const cell = exposureCell;
-      const read = readFrame(A, B, cell, plant, frame, pages, exposureGrid, exposure.map((m) => m.visible));
+      const read = readFrame(A, B, cell, plant, frame, pages, exposureGrid, exposure.map((m) => m.visible), options);
       if (read === null) { contact(unavailableContact('no shared half-opacity cell at the setup pose; no band to identify a joint')); continue; }
       const fragmented = [a, b].some(slot => frame.pieces.filter(p => p.slot === slot).length !== 1);
       contact(fragmented ? unavailableContact('each named slot must draw exactly one fragment for material contact') : read.contact);
       banded++;
+      if (options.cells) {
+        options.cells(read.gapOpen.cells!, cell);
+        options.cells(read.gapCovered.cells!, cell);
+      }
       for (const [cells, into] of [[read.gap, gaps], [read.ghost, ghosts], [read.ghostA, ghostsA], [read.ghostB, ghostsB], [read.gapOpen, openGaps], [read.gapCovered, coveredGaps]] as const) {
-        if (cells.px > 0 && cells.box !== null) into.push({ index: frame.index, time: frame.time, px: cells.px, cell, area: cells.px * cell * cell, box: cells.box });
+        if (cells.px > 0 && cells.box !== null) into.push({ index: frame.index, time: frame.time, px: cells.px, cell, area: cells.px * cell * cell, box: cells.box, ...(cells.cells === undefined ? {} : { cells: cells.cells }) });
       }
     }
     const gap = kindOf(gaps);