comp-spec snaps text and control regions to the largest ink mass in their grid span

A session's own note said its hero sat at 67 because the 10x10 grid boxes straddled two elements each, and it was right: every downstream measurement (cap height, line count, structure) inherited the slop. Text and control regions now snap to the dominant connected ink inside the span (page-ground threshold, dilated cells, masses touching the span's sides lose to inside masses), keep the span on the record for coverage, and can opt out with snap: false.

AI-assisted (Claude Code).

skill/reference/new-work.md

@@ -101,7 +101,7 @@ When an approved comp exists, it is a spatial contract, not a mood board: only t
 Then, in order, each closed by `node {{scripts_path}}/build-phase.mjs advance` (every script below lives under `{{scripts_path}}/` and runs with `node`; exit 2 means the gate failed and printed why; fix that and advance again; write nothing for a later phase while an earlier gate is open):
 
 0. **comps.** The comp round from [visualize.md](visualize.md): three compositional comps of the requested surface at its own viewport under `.impeccable/mocks/`, each with a prompt sidecar, put in front of the user; the chosen one's sidecar gets `"approved": true`. The gate counts them and reads the approval; a `start --comp` skips this phase because it already happened.
-1. **spec.** Measure the comp: `comp-spec.mjs --comp <comp> --grid` writes a coordinate grid over the comp; open it, name every salient region by grid span in a regions file (kind `plate` / `image` / `texture` for anything painted: every illustration, photograph, figure, product object, and material texture; `text` / `control` / `chrome` for what code draws; every region carries a `note` saying what the comp shows there, which the plate prompt and the gate messages read), and run `comp-spec.mjs --comp <comp> --regions <file>`. The spec carries each region's box, sampled palette, and medium; `comp-spec.mjs --print` is the build's reference from here on. Type is measured, not guessed: `font-match.mjs --measure <text region>` reads the comp's cap height, width class, and weight off the pixels, and `font-match.mjs --rank <region> --text "..."` takes its candidates from a fingerprint index of the Google Fonts catalog (the nearest faces to the crop's shape) plus any names you pass with `--candidates`, renders them at that cap height with the region's words, and ranks them by fingerprint distance (its `USE` line is the CSS; its proof sheet shows the comp over the top three); with no browser resolvable it records the catalog's nearest face and says the size is estimated, which is still the choice to build on. Do not install a browser to rank, and never write a `chosen` face into the spec by hand: the gate accepts only what font-match wrote. The spec gate refuses to close until the lead text region is measured and ranked. A region note that describes painted material (a diagram, drawing, photograph, texture) under a code kind is refused at the spec: reclassify it as a plate, or reword the note if code really draws it. The script refuses a regions file that leaves comp ink unnamed (callouts, a parts table, a notes block): what is never named can never be missing, so everything the comp shows gets a region. It also refuses a `text` / `control` / `chrome` region larger than a quarter of the comp: that is a column, not an element, and a column scored as one region hides the plates, tables, and notes inside it. Name each element inside it (`container: true` only when it truly is one undivided element). A plate region's box has to hold its whole artwork with a margin: the spec measures the artwork's contact with the box edges and refuses a box that cuts through it (`bleed: true` only when the page really crops it there), because a plate placed with `object-fit: cover` on such a box shows the artwork minus the side the box lost. Anything not in the spec does not exist on the page: no borders, rules, containers, or chrome the comp does not show. Only three concessions exist: fonts (the closest obtainable face), icon glyphs (close enough, exact if the user chose an icon library; this covers the pictogram only, never a control's chrome, so a chevron, an arrow, a dropdown's border and fill, a button's shape are the comp's), and genuine defects in the comp such as spelling errors. <!-- rule:skill-comp-spec -->
+1. **spec.** Measure the comp: `comp-spec.mjs --comp <comp> --grid` writes a coordinate grid over the comp; open it, name every salient region by grid span in a regions file (text and control regions snap to the largest ink mass inside their span, so a headline named B1:E4 measures as the headline and not the column beside it; `snap: false` keeps the span, and an explicit `box` is taken as drawn) (kind `plate` / `image` / `texture` for anything painted: every illustration, photograph, figure, product object, and material texture; `text` / `control` / `chrome` for what code draws; every region carries a `note` saying what the comp shows there, which the plate prompt and the gate messages read), and run `comp-spec.mjs --comp <comp> --regions <file>`. The spec carries each region's box, sampled palette, and medium; `comp-spec.mjs --print` is the build's reference from here on. Type is measured, not guessed: `font-match.mjs --measure <text region>` reads the comp's cap height, width class, and weight off the pixels, and `font-match.mjs --rank <region> --text "..."` takes its candidates from a fingerprint index of the Google Fonts catalog (the nearest faces to the crop's shape) plus any names you pass with `--candidates`, renders them at that cap height with the region's words, and ranks them by fingerprint distance (its `USE` line is the CSS; its proof sheet shows the comp over the top three); with no browser resolvable it records the catalog's nearest face and says the size is estimated, which is still the choice to build on. Do not install a browser to rank, and never write a `chosen` face into the spec by hand: the gate accepts only what font-match wrote. The spec gate refuses to close until the lead text region is measured and ranked. A region note that describes painted material (a diagram, drawing, photograph, texture) under a code kind is refused at the spec: reclassify it as a plate, or reword the note if code really draws it. The script refuses a regions file that leaves comp ink unnamed (callouts, a parts table, a notes block): what is never named can never be missing, so everything the comp shows gets a region. It also refuses a `text` / `control` / `chrome` region larger than a quarter of the comp: that is a column, not an element, and a column scored as one region hides the plates, tables, and notes inside it. Name each element inside it (`container: true` only when it truly is one undivided element). A plate region's box has to hold its whole artwork with a margin: the spec measures the artwork's contact with the box edges and refuses a box that cuts through it (`bleed: true` only when the page really crops it there), because a plate placed with `object-fit: cover` on such a box shows the artwork minus the side the box lost. Anything not in the spec does not exist on the page: no borders, rules, containers, or chrome the comp does not show. Only three concessions exist: fonts (the closest obtainable face), icon glyphs (close enough, exact if the user chose an icon library; this covers the pictogram only, never a control's chrome, so a chevron, an arrow, a dropdown's border and fill, a button's shape are the comp's), and genuine defects in the comp such as spelling errors. <!-- rule:skill-comp-spec -->
 2. **plates.** Every raster region ships as a plate: an illustration, photo, or figure regenerated at asset resolution from its comp crop, UI text removed, at its `plate` path (ink on flat ground is generated on a chroma key and keyed to alpha, so it sits on the page's own ground rather than a second paper); a texture (paper, cloth, grain) is a clean patch of the comp region mirror-tiled to size, generated only when no clean patch exists. `generate-image.mjs --plate <id>` does one region end to end and scores it against the crop; a harness-native image tool takes the crop (`comp-spec.mjs --crop <id>`) as its input image and `comp-spec.mjs --plate-prompt <id>` as its prompt, then `embed-prompt.mjs`. With parallel subagents, spawn the shipped asset producer (`impeccable-asset-producer`; `impeccable_asset_producer` in codex; `/impeccable-asset-producer` in Cursor; on GitHub Copilot say "Use the impeccable-asset-producer agent") with the spec path and let it produce them all; without subagents, produce them here. A crop of the comp is a reference, never a shipping pixel. The gate checks every plate exists, is at least 1.5x the region's size, and reads as the region. Page code waits for this gate: a page written before its plates exist is a page that draws its material in CSS. A single-file deliverable changes nothing here: the plate is produced the same way and inlined as a data URI. `--force` exists for one case only, the user downgrading the comp's authority in words you quote in `--reason`; the script refuses every other reason. <!-- rule:skill-plates-before-page -->
 3. **hero.** Build only the first viewport, at the comp's own dimensions, the comp's words copied verbatim (the user approved that comp with those words; rewording is a stated decision after the hero passes, never a silent one inside it), every text region sized from its measured cap height and set in its ranked face, plates first: place every plate at its spec box (`object-fit: cover`, an `<img>`, a background image, or an inlined data URI named for it) before any text or control, capture into `.impeccable/review/hero-repro.png`, run `build-phase.mjs record hero` once so you see the plate regions read as match before any text exists, then lay the semantic layer over the plates from the spec's palette and boxes and advance. The gate first refuses while any plate is unreferenced by the source, then runs `comp-diff.mjs`, writes `.impeccable/review/diff/hero/` (side-by-side, heatmap, one paired crop per region, `report.json`), and passes at 72% overall with no region missing and no reading outstanding: the gate also reads each text region's cap height, line count, weight, ink colour, and position against the comp, each chrome strip's height off its rule, and the frame for ink where the comp is calm (a kicker, an extra nav item, a divider), and says each miss as a number ("cap height 78px in the build, 103px in the comp"); those numbers are the edit. When it fails, open the region crops it lists, in order, before editing: a region scored `missing` needs its material, `contradicted` needs its structure re-derived from the spec box, `drift` is where size and spacing edits belong; the gate refuses a third attempt that only nudges values on the same region. This is where the run's ambition is won or lost, and a retry here costs minutes where a rebuild verdict at the finish costs the run. <!-- rule:skill-hero-gate -->
 4. **sections.** Build the rest of the surface inside the spec's system: the same corner language, line weights, and palette, and nothing the comp never shows. Where the comp does not cover a region, it inherits the recorded system.

skill/scripts/comp-spec.mjs

@@ -125,6 +125,76 @@ export function artworkTouchesEdges(img, { contact = EDGE_CONTACT_MIN, band = 2,
   return sides;
 }
 
+/**
+ * Shrink a normalized box to the ink inside it (pixels far from the page
+ * ground), padded by `pad` px, never grown. Returns null when the crop has no
+ * ink or the ink fills the box already.
+ */
+export function snapBoxToInk(comp, box, ground, { pad = 6, minShrink = 0.06 } = {}) {
+  const px = { x: Math.round(box.x * comp.width), y: Math.round(box.y * comp.height), w: Math.round(box.w * comp.width), h: Math.round(box.h * comp.height) };
+  if (px.w < 8 || px.h < 8) return null;
+  const c = crop(comp, px.x, px.y, px.w, px.h);
+  const W = c.width, H = c.height;
+  let x0 = W, y0 = H, x1 = -1, y1 = -1;
+  for (let y = 0; y < H; y++) for (let x = 0; x < W; x++) {
+    const i = (y * W + x) * 4;
+    const g = 0.299 * c.data[i] + 0.587 * c.data[i + 1] + 0.114 * c.data[i + 2];
+    if (Math.abs(g - ground) > 60) { if (x < x0) x0 = x; if (x > x1) x1 = x; if (y < y0) y0 = y; if (y > y1) y1 = y; }
+  }
+  if (x1 < 0) return null;
+  // The bounding box of all ink cannot shed a neighbour that shares the
+  // span (a spine at the left edge, the next column's text at the right).
+  // Take the largest connected ink mass instead: cells of `cell` px are
+  // inked when 4% of their pixels are; 8-connected components; the one
+  // with the most inked cells is the element the region names.
+  const cell = Math.max(6, Math.round(Math.min(W, H) / 40));
+  const cw = Math.ceil(W / cell), ch = Math.ceil(H / cell);
+  const on = new Uint8Array(cw * ch), cnt = new Uint16Array(cw * ch);
+  for (let y = 0; y < H; y++) for (let x = 0; x < W; x++) {
+    const i = (y * W + x) * 4;
+    const g = 0.299 * c.data[i] + 0.587 * c.data[i + 1] + 0.114 * c.data[i + 2];
+    if (Math.abs(g - ground) > 60) cnt[Math.floor(y / cell) * cw + Math.floor(x / cell)]++;
+  }
+  for (let i = 0; i < on.length; i++) on[i] = cnt[i] >= cell * cell * 0.04 ? 1 : 0;
+  // dilate by one cell so the letters of a word and the lines of a block
+  // join into one mass; a neighbouring column a few cells away stays apart
+  const grown = new Uint8Array(on.length);
+  for (let y = 0; y < ch; y++) for (let x = 0; x < cw; x++) {
+    if (!on[y * cw + x]) continue;
+    for (let dy = -1; dy <= 1; dy++) for (let dx = -1; dx <= 1; dx++) { const nx = x + dx, ny = y + dy; if (nx >= 0 && ny >= 0 && nx < cw && ny < ch) grown[ny * cw + nx] = 1; }
+  }
+  const mask = grown;
+  const label = new Int32Array(cw * ch).fill(-1);
+  let best = null;
+  for (let s0 = 0; s0 < on.length; s0++) {
+    if (!mask[s0] || label[s0] >= 0) continue;
+    const stack = [s0]; label[s0] = s0; let n = 0, bx0 = cw, by0 = ch, bx1 = -1, by1 = -1;
+    while (stack.length) {
+      const k = stack.pop();
+      const kx = k % cw, ky = (k / cw) | 0;
+      if (on[k]) { n += cnt[k]; if (kx < bx0) bx0 = kx; if (kx > bx1) bx1 = kx; if (ky < by0) by0 = ky; if (ky > by1) by1 = ky; }
+      for (let dy = -1; dy <= 1; dy++) for (let dx = -1; dx <= 1; dx++) {
+        const nx = kx + dx, ny = ky + dy; if (nx < 0 || ny < 0 || nx >= cw || ny >= ch) continue;
+        const nk = ny * cw + nx; if (mask[nk] && label[nk] < 0) { label[nk] = s0; stack.push(nk); }
+      }
+    }
+    // a mass touching the span's left or right edge continues past it (the
+    // spine, the next column); the element the region names sits inside.
+    // Prefer an inside mass unless the edge mass is far heavier.
+    const touchesSide = bx0 === 0 || bx1 === cw - 1;
+    const cand = { n, bx0, by0, bx1, by1, touchesSide };
+    if (!best) best = cand;
+    else if (best.touchesSide && !cand.touchesSide && cand.n * 3 >= best.n) best = cand;
+    else if (!best.touchesSide && cand.touchesSide && cand.n < best.n * 3) { /* keep inside */ }
+    else if (cand.n > best.n) best = cand;
+  }
+  if (best) { x0 = best.bx0 * cell; y0 = best.by0 * cell; x1 = Math.min(W - 1, (best.bx1 + 1) * cell - 1); y1 = Math.min(H - 1, (best.by1 + 1) * cell - 1); }
+  const nx0 = Math.max(0, x0 - pad), ny0 = Math.max(0, y0 - pad), nx1 = Math.min(W, x1 + 1 + pad), ny1 = Math.min(H, y1 + 1 + pad);
+  const shrink = 1 - ((nx1 - nx0) * (ny1 - ny0)) / (W * H);
+  if (shrink < minShrink) return null;
+  return { x: (px.x + nx0) / comp.width, y: (px.y + ny0) / comp.height, w: (nx1 - nx0) / comp.width, h: (ny1 - ny0) / comp.height };
+}
+
 function medianGray(img) {
   const sample = [];
   const step = Math.max(1, Math.floor((img.width * img.height) / 6000));
@@ -161,7 +231,7 @@ export function uncoveredInkCells(comp, regions) {
     const e = grid.cells[r * 10 + c];
     if (e < threshold) continue;
     const cx = (c + 0.5) / 10, cy = (r + 0.5) / 10;
-    const covered = regions.some((reg) => reg.kind !== 'texture' && reg.kind !== 'band' && cx >= reg.box.x && cx <= reg.box.x + reg.box.w && cy >= reg.box.y && cy <= reg.box.y + reg.box.h);
+    const covered = regions.some((reg) => { const b = reg.coverBox || reg.box; return reg.kind !== 'texture' && reg.kind !== 'band' && cx >= b.x && cx <= b.x + b.w && cy >= b.y && cy <= b.y + b.h; });
     if (!covered) cells.push(`${COLS[c]}${r}`);
   }
   return cells;
@@ -192,7 +262,20 @@ export function measureRegions(comp, regionsInput, compPath) {
     if (raw.note && !RASTER_KINDS.has(kind) && kind !== 'band' && PAINTED_NOTE.test(raw.note) && !raw.codeDrawn) {
       throw new Error(`region ${raw.id} is kind "${kind}" but its note describes painted material ("${raw.note}"). Anything drawn, photographed, or textured ships as a raster plate: set kind to plate (illustration, diagram, figure), image (photograph), or texture (ground). If the note is wrong and code really draws it (a table, a rule, a chrome bar), reword the note or set "codeDrawn": true on the region.`);
     }
-    const box = raw.box && typeof raw.box.x === 'number' ? raw.box : gridToBox(raw.grid);
+    let box = raw.box && typeof raw.box.x === 'number' ? raw.box : gridToBox(raw.grid);
+    // A grid span over-covers: a headline named B1:E4 carries the deck below
+    // it and a slice of the next column, and every measurement downstream
+    // (cap height, line count, structure) inherits that slop; a session
+    // wrote a note saying its hero sat at 67 because the boxes straddled
+    // elements, and it was right. Text and control regions snap to the ink
+    // inside their span (page ground as the reference, a small pad); plates,
+    // textures, chrome, and any region given an explicit box are left as
+    // drawn. The grid stays on the record.
+    let coverBox = null;
+    if (!raw.box && raw.grid && (kind === 'text' || kind === 'control') && raw.snap !== false) {
+      const snapped = snapBoxToInk(comp, box, pageGround);
+      if (snapped) { coverBox = box; box = snapped; }
+    }
     // A code region is one element the page draws: a headline, a table, a
     // button, a bar. A "chrome" region covering a third of the comp is a
     // column, and a column scored as one region hides everything inside it
@@ -220,6 +303,8 @@ export function measureRegions(comp, regionsInput, compPath) {
       id: raw.id,
       kind,
       note: raw.note || null,
+      grid: raw.grid || null,
+      coverBox: coverBox ? { x: r4(coverBox.x), y: r4(coverBox.y), w: r4(coverBox.w), h: r4(coverBox.h) } : undefined,
       box: { x: r4(box.x), y: r4(box.y), w: r4(box.w), h: r4(box.h) },
       px,
       aspect: r4(px.w / px.h),

tests/build-phase.test.mjs

@@ -74,6 +74,23 @@ describe('comp-spec', () => {
     assert.equal(plate.regions[0].medium, 'raster');
   });
 
+  it('snaps a text region to the largest ink mass in its grid span, keeping the span for coverage', () => {
+    // headline block at left, a thin dark spine on the span's left edge, a
+    // column of small text at its right: the span B1:E4 covers all three
+    const comp = createImage(1000, 1000, [235, 232, 220, 255]);
+    fillRect(comp, 100, 0, 12, 1000, [160, 40, 30, 255]);
+    drawText(comp, 'KEEP OLD', 160, 130, [20, 20, 20, 255], 8);
+    drawText(comp, 'IRON', 160, 220, [20, 20, 20, 255], 8);
+    for (let i = 0; i < 6; i++) drawText(comp, 'small column text', 430, 120 + i * 30, [20, 20, 20, 255], 2);
+    const spec = measureRegions(comp, { allowUncovered: true, regions: [{ id: 'headline', kind: 'text', grid: 'B1:E4', note: 'two-line block headline' }] }, 'c.png');
+    const r = spec.regions[0];
+    assert.equal(r.grid, 'B1:E4');
+    assert.ok(r.coverBox && r.coverBox.w === 0.4, 'the span stays on the record');
+    assert.ok(r.box.w < 0.3 && r.box.x >= 0.14 && r.box.x + r.box.w <= 0.42, `snapped to the headline: ${JSON.stringify(r.box)}`);
+    const plain = measureRegions(comp, { allowUncovered: true, regions: [{ id: 'headline', kind: 'text', grid: 'B1:E4', note: 'two-line block headline', snap: false }] }, 'c.png');
+    assert.equal(plain.regions[0].box.w, 0.4);
+  });
+
   it('warns when a plate box cuts through its own artwork', () => {
     // a black arch on paper, drawn wider than the region that names it
     const comp = createImage(1000, 1000, [235, 232, 220, 255]);