@rig-c/core 2.67.2 → 2.69.0

package/README.md

@@ -186,6 +186,16 @@ of them: it reads whatever frames you point it at, so it runs from the installed
 package on pictures of your own — which is what *Where to go next* below tells you
 to do with it, and it is the one instrument here that can see a wrong animation.
 
+Programmatic checked consumers can import `rig-c/render-shared`: the official
+candidate chooser (`loadCandidate`, `throughPoser`), setup and animation samplers
+(`sampleSetupPose`, `sampleAnimation`) and raster reads (`pageFor`, `projector`,
+`rasterisePiece`, `renderFrame`), with their argument/result types and named
+failures. It loads without the optional Spine runtime; a Spine input requires
+explicitly loading `rig-c/render`, whose eager runtime dependency is unchanged.
+The promised scope and planned first minor release are in
+[RELEASING.md, The import surface](https://github.com/rig-c/core/blob/main/RELEASING.md#the-import-surface);
+[AUTHORING §0.5](docs/AUTHORING.md#05-reading-a-build-from-code) shows the call chain.
+
 ### Install it into your agent
 
 The guides under [Documentation](#documentation) also ship as
@@ -606,7 +616,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. `--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 |
+| `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; `ghostA` and `ghostB` partition the same ghost by which named pair member drew it, each with its own frames, spans and worst; `gapOpen` and `gapCovered` partition `gap` by zero versus positive rendered alpha from the whole skeleton, including faint and clipped drawings ([AUTHORING §8.8](docs/AUTHORING.md#88-where-two-slots-stop-meeting--render---seam)) — 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

@@ -1617,6 +1617,68 @@ written`, followed by `rigc repack: nothing was written to <out>; the work direc
 
 ---
 
+### 0.5 Reading a build from code
+
+The named `rig-c/render-shared` entry promises the official renderer reads for
+checked consumers (issue #1561). It is planned for the next minor, 2.69.0; wait
+for the measured release before using `>=2.69.0 <3.0.0`. It requires Bun and the
+candidate's real files, but imports no optional Spine runtime. The existing
+`rig-c/render` entry still eagerly imports that runtime.
+
+```ts
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  loadCandidate, throughPoser, sampleSetupPose, sampleAnimation,
+  pageFor, projector, rasterisePiece, renderFrame,
+  type Viewport,
+} from 'rig-c/render-shared';
+
+const dir = 'build';
+const skeleton = join(dir, 'skeleton.json');
+const atlas = join(dir, 'skeleton.atlas');
+const candidate = loadCandidate({
+  skeletonText: readFileSync(skeleton, 'utf8'),
+  atlasText: readFileSync(atlas, 'utf8'),
+  atlasDir: dir, label: skeleton,
+}, { skeleton, atlas }, undefined);
+const read = throughPoser(candidate.choice, (poser, roster) => ({
+  setup: sampleSetupPose(poser, { bones: true, geometry: true })[0],
+  frames: sampleAnimation(poser, 'wave', 12),
+  skins: roster.skins,
+}));
+// The consumer supplies the world box and pixel grid it intends to measure.
+const viewport: Viewport = {
+  minX: 0, minY: 0, maxX: 256, maxY: 256,
+  scale: 1, width: 256, height: 256,
+};
+const project = projector(viewport);
+for (const piece of read.value.setup.pieces) {
+  rasterisePiece(pageFor(candidate.pages, piece), piece, project, viewport,
+    (x, y, r, g, b, a) => { /* read each covered sample */ });
+}
+const image = renderFrame(read.value.setup, candidate.pages, viewport, [0, 0, 0, 0]);
+```
+
+The animation name and viewport above belong to the consumer; the loader does
+not invent them. The chooser checks the model document beside the skeleton,
+its `spine.sha256`, atlas placement, page files and bone/slot/animation rosters.
+A /3 document can be loaded with `atlasText: null` when its atlas is absent.
+`throughPoser` returns `poser` and `note` with its value. Keep its callback free
+of writes: an explicitly registered runtime fallback can rerun it.
+
+The entry also exports the original `CandidateAtlasError` (missing required
+atlas), `CandidatePairError` (unloadable pair or missing page),
+`SpineRuntimeError` (input needs an unregistered or unusable Spine side),
+`PoserChoiceError` (a forced-core pose refusal), `SlotSubsetError` (invalid
+slot subset) and `CoreInputError` (core input/pose refusal). The chooser's
+mismatch reason remains in the refusal: no silent substitute is selected by
+this entry. Unknown animation and missing `pageFor` page are `Error`s naming
+the requested name and available names. A forced-core flag keeps the existing
+deferred choice check; it alone does not prove `candidate.choice.core` exists.
+To use a Spine export or `forced: 'spine'`, install the runtime and explicitly
+import `rig-c/render` first; importing `render-shared` never registers it.
+
 ## 1. The two files
 
 ### 1.1 A complete minimal rig spec
@@ -8933,7 +8995,8 @@ table's vertices, and the atlas alpha:
 - **Drawn** is the renderer painting a cell's centre at **128 of 255** or more —
   the half-opacity line `--pass-through` draws outlines at, the frame's tint
   included, the setup pose drawn at the same tint (so a slot faded out is not a
-  tear: it is faded in both). No other alpha enters.
+  tear: it is faded in both). This threshold defines the pair's band, gap and
+  ghost; the composite coverage partition below asks a different question.
 - **The band** is the cells both drawings draw at the setup pose — where the two
   were painted to overlap. It has **no width of its own**: it is the overlap the
   art states, dilated by nothing. A frame whose band is empty is not read; a pair
@@ -8949,8 +9012,30 @@ table's vertices, and the atlas alpha:
   the drawing piece, carrying it back, lands in the band, and which the other,
   carrying it back, finds neither drawing at at the setup pose: the overlap swung
   clear of its partner.
+- **ghostA**, **ghostB** — that same ghost partitioned by the piece drawing the
+  cell: `a` only or `b` only, respectively, in the flag's named pair order. On
+  each frame `ghost.px = ghostA.px + ghostB.px` (an absent hit contributes 0),
+  and each owner's box lies inside the union's. Reversing the pair exchanges
+  the complete owner readings and preserves `gap` and `ghost`.
+- **gapOpen**, **gapCovered** — the same gap cells partitioned by the actual
+  skeleton composite at their centres, on the same cell grid, over a transparent
+  background: alpha **0** is open; alpha **>0** is covered. Every skeleton drawing
+  enters, including the pair itself, with the frame's tint, UVs and clipping.
+  Alpha **1..127 covers too**: this is not the pair's half-opacity outline test.
+  The renderer's existing byte quantization remains in force: it emits rounded
+  alpha only when the sampled, tinted value exceeds 0.5 on the 0..255 scale;
+  a value that produces no rendered alpha byte is open. No display background
+  enters. Source-over cannot erase positive alpha, so the renderer's positive
+  emissions give exactly the nonzero alpha of its transparent composite.
+
+On every frame `gap.px = gapOpen.px + gapCovered.px` (missing hit means 0).
+Each partition's box lies in the union's. A gap in the pair can be covered by a
+third drawing and need not be a visible opening. Reversing the pair preserves
+both gap coverage readings.
 
 Draw order does not enter: a cell is covered or bare whichever piece is in front.
+An owner says which piece drew a ghost cell; it does not say which piece is over
+or under the other, or whether that exposure should fail a consumer's policy.
 
 **Its reach, stated.** A piece folded right back over its partner carries the band
 across the region it vacated, so a hull that wide reads the vacated cells its
@@ -8970,7 +9055,7 @@ block carries the definitions above in words.
 | `animation` | string or `null` | — | the set's animation; `null` for a skeleton with none (its one frame is the setup pose) |
 | `skin` | string | — | the skin asked for; **absent** when none was |
 | `fps` | number | frames per second | the rate the set was sampled at |
-| `reading` | object | — | `read`, `cell`, `drawn`, `band`, `carried`, `gap`, `ghost`, `box`, `status`: the definitions, in words |
+| `reading` | object | — | `read`, `cell`, `drawn`, `band`, `carried`, `gap`, `ghost`, `box`, `status`, `ghostA`, `ghostB`, `gapOpen`, `gapCovered`: the definitions, in words |
 | `pairs[]` | array | — | one per pair, in the flag's order |
 | `pairs[].a`, `pairs[].b` | string | — | the two slots, as the flag names them |
 | `pairs[].drawn` | integer | frames | frames on which both slots draw |
@@ -8979,6 +9064,8 @@ block carries the definitions above in words.
 | `pairs[].opens` | integer[] | frame indices | every frame with a gap or a ghost, ascending |
 | `pairs[].maxPx` | integer | px (cells) | the most cells of either kind on any frame; 0 when none opens |
 | `pairs[].gap`, `pairs[].ghost` | object | — | one per kind, each `{ frames, spans, worst }` |
+| `pairs[].ghostA`, `pairs[].ghostB` | object | — | the same `{ frames, spans, worst }` shape for ghost cells drawn by `a` only and `b` only; an empty owner has `frames: []`, `spans: []`, `worst: null` |
+| `pairs[].gapOpen`, `pairs[].gapCovered` | object | — | the same `{ frames, spans, worst }` shape for gap cells with zero or positive rendered skeleton-composite alpha, respectively; an empty kind has `frames: []`, `spans: []`, `worst: null` |
 | `<kind>.frames[]` | hit[] | — | only the frames with a cell of that kind, in frame order |
 | `<kind>.spans[]` | array | — | `<kind>.frames` as runs of consecutive indices: `{ frames: [first, last], times: [first, last], maxPx }` — frame indices, seconds, px |
 | `<kind>.worst` | hit or `null` | — | the frame with the most cells, the earliest on a tie; `null` when none |
@@ -8995,6 +9082,16 @@ span.times, maxPx: span.maxPx, kind }`, and one pair over one animation is
 `opens.length` frame(s) `[opens]`, max `maxPx` px — with `status: "skip"` the case
 to say SKIP for.
 
+The owner keys and their two legend entries are additive in `rigc-seam/1`.
+Removing just those four keys leaves the previous file's bytes after the same
+two-space JSON serialization and newline. The union, its spans and worst, and
+the printed summary retain their existing meanings; an owner may have different
+spans or a different worst frame from the union.
+Likewise `gapOpen`, `gapCovered` and their two legend entries are additive:
+removing only those entries leaves the previous file's bytes after the same
+serialization, including `gap`, `ghostA` and `ghostB`. The coverage partition may
+have different spans and worst frames from the union; it changes no seam policy.
+
 **Refused, nothing written:** a slot the skeleton does not have (with the slots it
 does), an entry without exactly one `:`, an empty entry or name, a slot paired with
 itself (a seam is between two drawings), a pair named twice in either order (the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.67.2",
+  "version": "2.69.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": {
@@ -11,6 +11,7 @@
     "./font5x7": "./tools/font5x7.ts",
     "./transform": "./src/transform.ts",
     "./render": "./src/render.ts",
+    "./render-shared": "./src/render_read.ts",
     "./png": "./src/png.ts",
     "./compile": "./src/compile.ts",
     "./rig": "./src/rig.ts",

package/src/render_read.ts

@@ -0,0 +1,55 @@
+/**
+ * The promised renderer reads for checked consumers (issue #1561).
+ *
+ * This entry registers no Spine side. Rigc builds use the official candidate
+ * chooser and core poser; inputs needing Spine are refused by SpineRuntimeError
+ * unless the consumer has explicitly loaded rig-c/render. That entry keeps its
+ * eager runtime import and registers the same implementation this seam uses.
+ * Only the agreed reads, their types and their existing failure classes belong
+ * here. The broader implementation module is not the public contract.
+ */
+export {
+  loadCandidate,
+  throughPoser,
+  sampleAnimation,
+  sampleSetupPose,
+  pageFor,
+  projector,
+  rasterisePiece,
+  renderFrame,
+  CandidateAtlasError,
+  CandidatePairError,
+  PoserChoiceError,
+  SlotSubsetError,
+} from './render_shared.ts';
+export { SpineRuntimeError } from './spine_side.ts';
+export { CoreInputError } from './core/index.ts';
+export type {
+  Candidate,
+  SkeletonFacts,
+  PoserChoice,
+  PoserName,
+  MakeCorePoser,
+  Poser,
+  Posed,
+  PoseSource,
+  PoseOptions,
+  DrawOptions,
+  SkinRoster,
+  SlotSubset,
+  Frame,
+  BoneSnapshot,
+  AttachmentPose,
+  AttachmentRest,
+  Piece,
+  PieceCommon,
+  PieceTexture,
+  UvWindow,
+  Quad,
+  Mesh,
+  ClipSource,
+  Viewport,
+  EmitPixel,
+} from './render_shared.ts';
+export type { Plate, RGBA } from '../tools/plate.ts';
+export type { EnvironmentStep, EnvironmentChange } from './environment.ts';

package/src/seam.ts

@@ -56,6 +56,10 @@
  *
  * Each frame's figures are the cell counts (`px`), the cell size, their area,
  * and the world box of the counted cells (each cell's whole square).
+ * The pair's gap is partitioned into gapOpen (the transparent skeleton frame
+ * has alpha 0 there) and gapCovered (positive rendered alpha from any piece,
+ * including a faint pair member). This does not change the half-opacity pair
+ * predicate: another drawing can cover what the pair no longer covers.
  *
  * Known reach, stated rather than discovered: a piece folded right back over its
  * partner carries the band across the region it vacated, so a hull that wide
@@ -71,13 +75,13 @@
 import type { Plate } from '../tools/plate.ts';
 import { indexRuns } from './folds.ts';
 import { DRAWN_ALPHA, drawnCells, drawsAt, sameVertices, texelSize } from './passthrough.ts';
-import type { AttachmentPose, AttachmentRest, Piece, Viewport } from './render_shared.ts';
+import { type AttachmentPose, type AttachmentRest, type Piece, projector, rasterisePiece, type Viewport } from './render_shared.ts';
 
 /** The reading's file name inside an animation's frame directory, and its format tag. */
 export const SEAM_FILE = 'seam.json';
 export const SEAM_SPEC = 'rigc-seam/1';
 
-/** One pair as the flag names it. The reading is symmetric: `a:b` and `b:a` are one pair. */
+/** One pair as the flag names it. Reversing it preserves the union and exchanges the ghost owners. */
 export interface SeamPair {
   a: string;
   b: string;
@@ -176,6 +180,14 @@ export interface SeamPairReading {
   maxPx: number;
   gap: SeamKindReading;
   ghost: SeamKindReading;
+  /** Ghost cells drawn by `a` only; together with ghostB, an exact partition of ghost. */
+  ghostA: SeamKindReading;
+  /** Ghost cells drawn by `b` only. Ownership is the flag's order, not draw order. */
+  ghostB: SeamKindReading;
+  /** Gap cells whose skeleton composite has no rendered alpha at the cell centre. */
+  gapOpen: SeamKindReading;
+  /** Gap cells whose skeleton composite has positive rendered alpha, even below half opacity. */
+  gapCovered: SeamKindReading;
 }
 
 /** `seam.json`: one frame set's reading, every pair the flag names, in the flag's order. */
@@ -186,12 +198,12 @@ export interface SeamFile {
   skin?: string;
   fps: number;
   /** What the numbers mean, stated in the file so a reader does not need this module. */
-  reading: { read: string; cell: string; drawn: string; band: string; carried: string; gap: string; ghost: string; box: string; status: string };
+  reading: { read: string; cell: string; drawn: string; band: string; carried: string; gap: string; ghost: string; box: string; status: string; ghostA: string; ghostB: string; gapOpen: string; gapCovered: string };
   pairs: SeamPairReading[];
 }
 
 /**
- * A planted defect, for the suite's mutants only (`SM` controls in
+ * A planted defect, for the suite's mutants only (`SE` controls in
  * `selftest.ts`). Production passes none.
  */
 export interface SeamPlant {
@@ -203,6 +215,10 @@ export interface SeamPlant {
   bothViews?: boolean;
   /** Count a ghost cell wherever a piece draws what its partner's view had none of, not only from the band. */
   ghostAnyArt?: boolean;
+  /** Attribute every ghost to a, regardless of which piece draws it. */
+  ghostOnlyA?: boolean;
+  /** Wrong composite readings: half opacity, only the pair, or every gap forced to one kind. */
+  gapCoverage?: 'half' | 'pair' | 'open' | 'covered';
   /** Report a pair with no band as read, rather than as a SKIP. */
   skipAsRead?: boolean;
   /** Count nothing. */
@@ -347,8 +363,28 @@ interface Cells {
 
 const restPiece = (side: Side): Piece => ({ ...side.piece, world: Array.from(side.rest) });
 
-/** One frame's two 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): { gap: Cells; ghost: Cells } | null {
+/**
+ * Positive alpha of the transparent skeleton composite, on the pair's cell grid.
+ * The renderer emits rounded alpha bytes through this same traversal, including
+ * tint, UV windows and already-clipped pieces. Source-over cannot erase positive
+ * alpha: OR of positive emissions is exactly composite alpha > 0. No background
+ * enters, and the pair's half-opacity outline is not this test.
+ */
+function frameAlphaCells(pieces: readonly Piece[], pages: ReadonlyMap<string, Plate>, viewport: Viewport, half: boolean): Uint8Array {
+  const cells = new Uint8Array(viewport.width * viewport.height);
+  const project = projector(viewport);
+  for (const piece of pieces) {
+    const page = pages.get(piece.page);
+    if (page === undefined) throw new SeamError(`slot "${piece.slot}" samples atlas page "${piece.page}", which is not among [${[...pages.keys()].join(', ')}]`);
+    rasterisePiece(page, piece, project, viewport, (x, y, _r, _g, _b, alpha) => {
+      if (half ? alpha >= DRAWN_ALPHA : alpha > 0) cells[y * viewport.width + x] = 1;
+    });
+  }
+  return cells;
+}
+
+/** 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>): { gap: Cells; ghost: Cells; ghostA: Cells; ghostB: Cells; gapOpen: Cells; gapCovered: Cells } | null {
   // One grid over both drawings at the setup pose and at the frame, on multiples of the cell from the world origin.
   let [x0, y0, x1, y1] = [Infinity, Infinity, -Infinity, -Infinity];
   for (const xy of [A.rest, B.rest, A.piece.world, B.piece.world]) {
@@ -401,6 +437,11 @@ function readFrame(A: Side, B: Side, cell: number, plant: SeamPlant): { gap: Cel
   const composite = (p: [number, number] | null): boolean => drawnAtRest(p, restA, A.page) || drawnAtRest(p, restB, B.page);
   const gap: Cells = { px: 0, box: null };
   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 };
+  let alphaCells: Uint8Array | null = null;
   const take = (into: Cells, qx: number, qy: number): void => {
     into.px++;
     const h = cell / 2;
@@ -410,7 +451,7 @@ function readFrame(A: Side, B: Side, cell: number, plant: SeamPlant): { gap: Cel
     into.box[2] = Math.max(into.box[2], qx + h);
     into.box[3] = Math.max(into.box[3], qy + h);
   };
-  if (plant.never) return { gap, ghost };
+  if (plant.never) return { gap, ghost, ghostA, ghostB, gapOpen, gapCovered };
   const inBand = (p: [number, number] | null): boolean => p !== null && p[0] >= bx0 - cell / 2 && p[0] <= bx1 + cell / 2 && p[1] >= by0 - cell / 2 && p[1] <= by1 + cell / 2;
   for (let py = 0; py < height; py++) {
     for (let px = 0; px < width; px++) {
@@ -423,7 +464,12 @@ function readFrame(A: Side, B: Side, cell: number, plant: SeamPlant): { gap: Cel
         if (!plant.noHull && !inHull(hull, qx, qy)) continue;
         const fromA = composite(back(A, posedIdsA, k, qx, qy));
         const fromB = composite(back(B, posedIdsB, k, qx, qy));
-        if (plant.bothViews ? fromA && fromB : fromA || fromB) take(gap, qx, qy);
+        if (plant.bothViews ? fromA && fromB : fromA || fromB) {
+          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);
+        }
         continue;
       }
       if (a && b) continue;
@@ -432,10 +478,13 @@ function readFrame(A: Side, B: Side, cell: number, plant: SeamPlant): { gap: Cel
       const otherRest = a ? restB : restA;
       const p = back(mine, myIds, k, qx, qy);
       if (!plant.ghostAnyArt && !(inBand(p) && drawnAtRest(p, myRest, mine.page) && drawnAtRest(p, otherRest, other.page))) continue;
-      if (!composite(back(other, otherIds, k, qx, qy))) take(ghost, qx, qy);
+      if (!composite(back(other, otherIds, k, qx, qy))) {
+        take(ghost, qx, qy);
+        take(a || plant.ghostOnlyA ? ghostA : ghostB, qx, qy);
+      }
     }
   }
-  return { gap, ghost };
+  return { gap, ghost, ghostA, ghostB, gapOpen, gapCovered };
 }
 
 const restKey = (slot: string, attachment: string): string => `${slot}\u0000${attachment}`;
@@ -494,6 +543,10 @@ export function seamsOf(
     let banded = 0;
     const gaps: SeamHit[] = [];
     const ghosts: SeamHit[] = [];
+    const ghostsA: SeamHit[] = [];
+    const ghostsB: SeamHit[] = [];
+    const openGaps: SeamHit[] = [];
+    const coveredGaps: SeamHit[] = [];
     for (const frame of frames) {
       const A = sideOf(frame, a);
       const B = sideOf(frame, b);
@@ -504,10 +557,10 @@ export function seamsOf(
       const flat = cellA === null ? a : cellB === null ? b : null;
       if (cellA === null || cellB === null) throw new SeamError(`frame ${frame.index}: slot "${flat}" draws no area at its setup pose, so it has no texel to grid the seam by`);
       const cell = Math.max(cellA, cellB);
-      const read = readFrame(A, B, cell, plant);
+      const read = readFrame(A, B, cell, plant, frame, pages);
       if (read === null) continue;
       banded++;
-      for (const [cells, into] of [[read.gap, gaps], [read.ghost, ghosts]] as const) {
+      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 });
       }
     }
@@ -516,7 +569,7 @@ export function seamsOf(
     const opens = [...new Set([...gaps, ...ghosts].map((f) => f.index))].sort((x, y) => x - y);
     const maxPx = Math.max(0, ...gaps.map((f) => f.px), ...ghosts.map((f) => f.px));
     const status = banded === 0 && !plant.skipAsRead ? 'skip' : 'read';
-    return { a, b, drawn, banded, status, opens, maxPx, gap, ghost };
+    return { a, b, drawn, banded, status, opens, maxPx, gap, ghost, ghostA: kindOf(ghostsA), ghostB: kindOf(ghostsB), gapOpen: kindOf(openGaps), gapCovered: kindOf(coveredGaps) };
   });
 }
 
@@ -532,6 +585,10 @@ export const SEAM_READING: SeamFile['reading'] = {
   ghost: "a ghost cell is drawn at the frame by one piece and not the other; the drawing piece, carrying it back, lands it in the band, and the other piece, carrying it back, finds neither drawing there at the setup pose",
   box: "a frame's box is [minX, minY, maxX, maxY] in world units (y up) over the whole squares of that kind's counted cells",
   status: 'a pair is skip when no frame is read — the two never draw together, or never share a cell at the setup pose — which is nothing measured, not a seam that held',
+  ghostA: 'the ghost cells drawn by a only, with the same frames, spans and worst shape as ghost; ghostA and ghostB partition ghost on every frame',
+  ghostB: 'the ghost cells drawn by b only; a and b are the named pair order, not which piece is in front — reversing the pair exchanges ghostA and ghostB',
+  gapOpen: 'the gap cells whose centre has alpha 0 in the transparent frame composite of every skeleton drawing, using the renderer on the same cell grid; gapOpen and gapCovered partition gap',
+  gapCovered: 'the gap cells whose centre has positive rendered alpha from any skeleton drawing, including the pair; alpha 1..127 covers too — this is not the pair\'s half-opacity test, and no presentation background enters',
 };
 
 /** The file for one frame set. */