@ggui-ai/ui-gen 0.24.0 → 0.26.0

package/src/evaluation/criteria/edge-probe.ts

@@ -0,0 +1,286 @@
+/**
+ * `space.edge`'s measurement (#1663): the expression a capture evaluates in the page to produce {@link EdgeBlock}s for
+ * {@link judgeEdges}. It runs where the screenshot is taken, on the same DOM at the same width, so the rule reads what
+ * the judge's frame shows. It only reads layout; it never writes to the page.
+ *
+ * What it measures, under `#root`, in CSS px from the card's left edge:
+ *
+ * - **Text blocks.** Text is grouped by its nearest non-inline element. A block's edge is its first visible character
+ *   in ink: text in a transparent colour, private-use icon-font glyphs and formatting characters are not characters of
+ *   the block. Its extent is the union of its inked line boxes. A marker before the text (an icon or image that paints,
+ *   or a number or bullet on the same line) makes it a hanging marker: `edge` is the marker's, `textEdge` the text's.
+ * - **Control groups.** Native and ARIA controls, and bounded boxes the visitor clicks (a pointer cursor or a tab stop,
+ *   holding no control of their own), group by their parent and are measured at the first control: the border box
+ *   when bounded, else its text. A control's contents are never blocks of the enclosing column.
+ * - **Surfaces.** A non-inline box with a border on at least three sides, its own fill different from what it sits on,
+ *   or a shadow. A table is a surface measured at its rule and not descended into. A box with no text, control, image
+ *   or icon inside (a loading bar) is a `placeholder`, which is not a block.
+ * - **Roles.** A list item is `list-item` when its list follows a paragraph; text centred in a box wider than it, or
+ *   controls in a centring row, are `centred`.
+ * - **Rows, first, read by geometry.** Items set on one line, however the CSS lays them out: an item after another
+ *   measured item on its line that holds one block (a text, a control, or a box holding at most one text) belongs to
+ *   the row and is not measured. An item with a stack inside it is a column.
+ * - **Ornaments:** text with no letters or digits is not measured.
+ *
+ * Hidden elements (through any ancestor), zero-size ones and transparent text are skipped. What the rows and ornament
+ * rules set aside is counted. A frame with no text in ink is reported as placeholders only. The expression returns a
+ * JSON value; {@link parseEdgeProbe} is its typed read. *
+ * **Validated instrument (#1663, 2026-10-02):** this file as of `cec465319` (with `7bb4da13e`) passed a fresh sealed
+ * blind draw at the registered bar (27/30, κ 0.76), stricter than the design lead's reading on its disagreements. Any
+ * later change to what this file measures or decides is a new instrument until another fresh sealed draw.
+ */
+import type { EdgeBlock } from './edge.js';
+
+/** What the probe returns: the measured blocks, and whether the frame showed nothing to evaluate. */
+export interface EdgeProbe {
+  readonly blocks: readonly EdgeBlock[];
+  readonly placeholdersOnly: boolean;
+  /** What the probe saw and did not measure, by rule, so a dropped block is counted rather than silent. */
+  readonly skipped: { readonly rowItems: number; readonly ornaments: number };
+}
+
+// Plain ES2020 for the page: no imports, no template literals, no helpers a bundler might rename.
+export const EDGE_BLOCKS_EXPRESSION = String.raw`(() => {
+  const root = document.getElementById('root');
+  if (!root) return null;
+  const rootBox = root.getBoundingClientRect();
+  const x0 = rootBox.left;
+  const px = (v) => Math.round((v - x0) * 2) / 2;
+  const CONTROL = 'button,input,select,textarea,[role="button"],[role="tab"],[role="switch"],[role="checkbox"],[role="radio"],[role="option"],[role="link"],a[href]';
+  const ALNUM = /[\p{L}\p{N}]/u;
+  const css = (el) => getComputedStyle(el);
+  const clear = (c) => !c || c === 'transparent' || /rgba\([^)]*,\s*0(\.0+)?\)$/.test(c);
+  // Visible through every ancestor (an ancestor at opacity 0 or visibility hidden hides it), and not degenerate.
+  const shown = (el) => {
+    const s = css(el);
+    if (s.display === 'none' || s.visibility === 'hidden' || Number(s.opacity) === 0) return false;
+    if (typeof el.checkVisibility === 'function' && !el.checkVisibility({ opacityProperty: true, visibilityProperty: true })) return false;
+    const r = el.getBoundingClientRect();
+    return r.width > 1 && r.height > 1;
+  };
+  const inline = (s) => /^inline/.test(s.display) && s.display !== 'inline-block' && s.display !== 'inline-flex' && s.display !== 'inline-grid';
+  const groundOf = (el) => {
+    for (let p = el.parentElement; p; p = p.parentElement) { const b = css(p).backgroundColor; if (!clear(b)) return b; }
+    return 'rgb(255, 255, 255)';
+  };
+  const sides = (s) => ['Top', 'Right', 'Bottom', 'Left'].filter((k) => parseFloat(s['border' + k + 'Width']) > 0 && s['border' + k + 'Style'] !== 'none' && !clear(s['border' + k + 'Color'])).length;
+  const bounded = (el) => { const s = css(el); return sides(s) >= 1 || (!clear(s.backgroundColor) && s.backgroundColor !== groundOf(el)); };
+  // A control: a native or ARIA one, or a bounded box the visitor clicks (a pointer cursor or a tab stop) that holds no
+  // control of its own and is not the whole card. Its contents are not blocks of the column (decided 2026-10-02).
+  const isControl = (el) => {
+    const s = css(el);
+    if (inline(s)) return false;
+    if (el.matches(CONTROL)) return true;
+    if (el === root) return false;
+    const clickable = s.cursor === 'pointer' || (el.hasAttribute('tabindex') && el.tabIndex >= 0);
+    if (!clickable || !bounded(el) || el.querySelector(CONTROL)) return false;
+    const r = el.getBoundingClientRect();
+    return r.width * r.height < 0.6 * rootBox.width * rootBox.height;
+  };
+  const isTable = (el) => el.matches('table,[role="table"],[role="grid"]');
+  const isSurface = (el) => {
+    if (el === root || isControl(el)) return false;
+    const s = css(el);
+    if (/^inline/.test(s.display) || s.display === 'contents') return false;
+    if (isTable(el)) return true;
+    return sides(s) >= 3 || (!clear(s.backgroundColor) && s.backgroundColor !== groundOf(el)) || (s.boxShadow && s.boxShadow !== 'none');
+  };
+  const path = (el) => {
+    const parts = [];
+    for (let e = el; e && e !== root && parts.length < 4; e = e.parentElement) {
+      const i = e.parentElement ? Array.prototype.indexOf.call(e.parentElement.children, e) + 1 : 1;
+      parts.unshift(e.tagName.toLowerCase() + ':' + i);
+    }
+    return parts.join('>');
+  };
+  const label = (el) => { const t = (el.innerText || '').replace(/\s+/g, ' ').trim(); return path(el) + (t ? ' "' + t.slice(0, 24) + '"' : ''); };
+  const surfaces = [];
+  const surfaceOf = (el, self) => { for (let p = self ? el : el.parentElement; p && p !== root; p = p.parentElement) if (surfaces.indexOf(p) >= 0) return p; return null; };
+  const inTable = (el) => { for (let p = el.parentElement; p && p !== root; p = p.parentElement) if (isTable(p)) return true; return false; };
+  const inControl = (el) => { for (let p = el; p && p !== root; p = p.parentElement) if (isControl(p)) return p; return null; };
+  const all = Array.prototype.slice.call(root.querySelectorAll('*')).filter(shown);
+  for (const el of all) if (isSurface(el) && !inTable(el) && !inControl(el)) surfaces.push(el);
+  const ids = new Map();
+  const idOf = (el) => { if (!ids.has(el)) ids.set(el, label(el)); return ids.get(el); };
+  const blocks = [];
+  // Per block: the element it stands for and its first line's box, for rows.
+  const owners = [];
+  const lines = [];
+  // Per block: its raw line boxes and left, so a row reads the line two items share, not a wrapped item's widest line.
+  const rects = [];
+  const rawLeft = [];
+  const words = [];
+  const within = (el, self) => { const s = surfaceOf(el, self); return s ? { within: idOf(s) } : {}; };
+  for (const s of surfaces) {
+    const r = s.getBoundingClientRect();
+    owners.push(s); lines.push({ top: r.top, bottom: r.bottom }); rects.push([r]); rawLeft.push(r.left); words.push('');
+    // A placeholder: a box with no text, no control and no image or icon inside it (a loading bar). Not a block.
+    const holds = Array.prototype.some.call(s.querySelectorAll('*'), (el) => shown(el) && (el.matches(CONTROL) || el.tagName === 'IMG' || el.tagName.toLowerCase() === 'svg')) || ALNUM.test(s.innerText || '');
+    blocks.push(Object.assign({ id: idOf(s), kind: 'surface', edge: px(r.left), left: px(r.left), right: px(r.right), top: Math.round(r.top) }, within(s, false), isTable(s) ? { role: 'table' } : holds ? {} : { role: 'placeholder' }));
+  }
+  const blockOf = (node) => { for (let p = node.parentElement; p && p !== root; p = p.parentElement) if (!inline(css(p))) return p; return root; };
+  const groups = new Map();
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+    if (!/\S/.test(n.data) || !n.parentElement || n.parentElement.closest('style,script,noscript,template') || !shown(n.parentElement) || inControl(n.parentElement) || inTable(n.parentElement)) continue;
+    const b = blockOf(n);
+    if (!groups.has(b)) groups.set(b, []);
+    groups.get(b).push(n);
+  }
+  // Ink: text whose own colour is not transparent. The edge is the first visible character in ink (decided 2026-10-02):
+  // leading invisible text, private-use icon-font glyphs and formatting characters are not characters of the block,
+  // while a currency sign or a quotation mark is.
+  const inked = (n) => !clear(css(n.parentElement).color) && ALNUM.test(n.data);
+  const textRects = (nodes) => {
+    const rs = [];
+    for (const n of nodes) { if (!inked(n)) continue; const range = document.createRange(); range.selectNodeContents(n); for (const r of range.getClientRects()) if (r.width > 0 && r.height > 0) rs.push(r); }
+    return rs;
+  };
+  const glyphAt = (n, i) => { const range = document.createRange(); range.setStart(n, i); range.setEnd(n, i + 1); const r = range.getClientRects()[0]; return r || null; };
+  const firstGlyph = (nodes) => {
+    for (const n of nodes) { if (!inked(n)) continue; const i = n.data.search(/[^\s\p{Co}\p{Cf}]/u); if (i < 0) continue; const r = glyphAt(n, i); if (r) return r; }
+    return null;
+  };
+  // A marker paints: a loaded image, an SVG with a filled or stroked shape, or an element with its own fill, border
+  // or visible text. An element that paints nothing is not a marker.
+  const painted = (m) => {
+    if (!shown(m)) return false;
+    if (m.tagName === 'IMG') return m.complete && m.naturalWidth > 0;
+    if (m.tagName.toLowerCase() === 'svg' || m.closest('svg')) {
+      const shapes = m.querySelectorAll('path,circle,rect,line,polyline,polygon,ellipse,use,text');
+      return Array.prototype.some.call(shapes, (sh) => { const st = css(sh); return (st.fill !== 'none' && !clear(st.fill)) || (st.stroke !== 'none' && !clear(st.stroke)); });
+    }
+    const s = css(m);
+    if (!clear(s.backgroundColor) || sides(s) >= 1 || ((m.textContent || '').trim().length > 0 && !clear(s.color))) return true;
+    // A wrapper that paints nothing itself is a marker when an image or icon inside it paints.
+    return Array.prototype.some.call(m.querySelectorAll('svg,img'), (k) => painted(k));
+  };
+  const markerBefore = (b, textLeft, lineTop, lineBottom) => {
+    const cands = [];
+    const consider = (m) => { if (!painted(m)) return; const r = m.getBoundingClientRect(); if (r.left < textLeft - 2 && r.bottom > lineTop && r.top < lineBottom) cands.push(r.left); };
+    for (const m of b.querySelectorAll('svg,img,[aria-hidden="true"],i')) if ((m.textContent || '').trim().length <= 2) consider(m);
+    const p = b.parentElement;
+    if (p && p !== root && /flex/.test(css(p).display) && !/column/.test(css(p).flexDirection)) for (const sib of p.children) { if (sib === b) break; if (sib.matches('svg,img,i,[aria-hidden="true"]') || !(sib.textContent || '').trim()) consider(sib); }
+    return cands.length ? Math.min.apply(null, cands) : null;
+  };
+  let texts = 0;
+  let ornaments = 0;
+  for (const [b, nodes] of groups) {
+    if (!nodes.some((n) => ALNUM.test(n.data))) { ornaments += 1; continue; }
+    const rs = textRects(nodes);
+    const g = firstGlyph(nodes);
+    if (!rs.length || g === null) continue;
+    texts += 1;
+    const first = g.left;
+    const left = Math.min.apply(null, rs.map((r) => r.left));
+    const right = Math.max.apply(null, rs.map((r) => r.right));
+    const top = Math.min.apply(null, rs.map((r) => r.top));
+    const marker = markerBefore(b, first, g.top, g.bottom);
+    const s = css(b);
+    const box = b.getBoundingClientRect();
+    const parent = b.parentElement ? css(b.parentElement) : null;
+    const centredText = s.textAlign === 'center' && right - left < box.width * 0.9;
+    const centredBox = parent && /flex/.test(parent.display) && /column/.test(parent.flexDirection) && parent.alignItems === 'center';
+    const list = b.matches('li') || s.display === 'list-item' ? b.closest('ul,ol') : null;
+    const inProse = list && list.previousElementSibling && list.previousElementSibling.matches('p');
+    const block = { id: idOf(b), kind: 'text', edge: px(marker !== null ? marker : first), left: px(Math.min(left, marker !== null ? marker : left)), right: px(right), top: Math.round(top) };
+    if (marker !== null) block.textEdge = px(first);
+    if (centredText || centredBox) block.role = 'centred';
+    else if (inProse) block.role = 'list-item';
+    owners.push(b); lines.push({ top: g.top, bottom: g.bottom }); rects.push(rs); rawLeft.push(Math.min(left, marker !== null ? marker : left)); words.push(nodes.map((n) => n.data).join('').trim());
+    blocks.push(Object.assign(block, within(b, true)));
+  }
+  const ctlGroups = new Map();
+  for (const el of all) { if (!isControl(el) || inTable(el) || (el.parentElement && inControl(el.parentElement))) continue; const p = el.parentElement || root; if (!ctlGroups.has(p)) ctlGroups.set(p, []); ctlGroups.get(p).push(el); }
+  let controls = 0;
+  for (const [p, els] of ctlGroups) {
+    const rs = els.map((e) => e.getBoundingClientRect());
+    const topRow = Math.min.apply(null, rs.map((r) => r.top));
+    let firstEl = null; let firstR = null;
+    els.forEach((e, i) => { const r = rs[i]; if (r.top - topRow < r.height / 2 && (!firstR || r.left < firstR.left)) { firstEl = e; firstR = r; } });
+    let edge = firstR.left;
+    if (!bounded(firstEl)) { const tw = document.createTreeWalker(firstEl, NodeFilter.SHOW_TEXT); const ns = []; for (let n = tw.nextNode(); n; n = tw.nextNode()) ns.push(n); const g = firstGlyph(ns); if (g) edge = g.left; }
+    controls += 1;
+    const ps = css(p);
+    const centred = ps.justifyContent === 'center' || (ps.textAlign === 'center' && !/flex|grid/.test(ps.display));
+    const block = { id: idOf(p) + ' [controls]', kind: 'controls', edge: px(edge), left: px(Math.min.apply(null, rs.map((r) => r.left))), right: px(Math.max.apply(null, rs.map((r) => r.right))), top: Math.round(topRow) };
+    if (centred) block.role = 'centred';
+    owners.push(firstEl); lines.push({ top: firstR.top, bottom: firstR.bottom }); rects.push(rs); rawLeft.push(Math.min.apply(null, rs.map((r) => r.left))); words.push('');
+    blocks.push(Object.assign(block, within(firstEl, true)));
+  }
+  // Rows (decided 2026-10-01, read by geometry 2026-10-02): items set on one line, however the CSS sets them. An item
+  // after another measured item on its line that holds one block (a text, a control, or a box holding at most one
+  // text) belongs to the row and is not measured; an item with a stack inside it is a column.
+  const dropped = new Set();
+  const sameLine = (a, b) => Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top) > Math.min(a.bottom - a.top, b.bottom - b.top) / 2;
+  const contains = (o, el) => o === el || o.contains(el);
+  const innerTexts = (i) => owners.map((el, k) => k).filter((k) => k !== i && blocks[k].kind !== 'surface' && contains(owners[i], owners[k]));
+  const isPill = (i) => blocks[i].kind === 'surface' && innerTexts(i).length <= 1 && !owners.some((el, k) => k !== i && blocks[k].kind === 'surface' && contains(owners[i], el));
+  const itemOf = (el, other) => { let e = el; while (e.parentElement && e.parentElement !== root && !e.parentElement.contains(other)) e = e.parentElement; return e; };
+  for (let i = 0; i < blocks.length; i += 1) {
+    if (blocks[i].kind === 'surface' && !isPill(i)) continue;
+    const before = blocks.findIndex((bj, j) => j !== i && bj.within === blocks[i].within && !(bj.kind === 'surface' && !isPill(j)) && !contains(owners[j], owners[i]) && !contains(owners[i], owners[j]) && rects[j].some((r) => sameLine(r, lines[i]) && r.right <= rawLeft[i] + 1));
+    if (before < 0) continue;
+    // A number or bullet in front of a text on its line is a hanging marker, not a row: the pair is one block with two
+    // edges, the marker's and the text's.
+    if (blocks[i].kind === 'text' && blocks[before].kind === 'text' && /^[\p{N}\p{P}\p{S}]{1,3}$/u.test(words[before])) {
+      blocks[i] = Object.assign({}, blocks[i], { edge: blocks[before].edge, left: Math.min(blocks[i].left, blocks[before].left), textEdge: blocks[i].edge });
+      delete blocks[i].role;
+      dropped.add(before);
+      continue;
+    }
+    const item = itemOf(owners[i], owners[before]);
+    const inside = owners.map((el, k) => k).filter((k) => contains(item, owners[k]) && blocks[k].kind !== 'surface');
+    const boxes = owners.map((el, k) => k).filter((k) => contains(item, owners[k]) && blocks[k].kind === 'surface' && k !== i);
+    if (blocks[i].kind === 'surface') { if (boxes.length === 0) { dropped.add(i); for (const k of innerTexts(i)) dropped.add(k); } continue; }
+    if (inside.length === 1 && boxes.length === 0) dropped.add(i);
+  }
+  const kept = blocks.filter((_, i) => !dropped.has(i));
+  // Placeholders: a frame with no text in ink shows nothing to evaluate, whatever controls or boxes it draws.
+  return { blocks: kept, placeholdersOnly: texts === 0, skipped: { rowItems: dropped.size, ornaments } };
+})()`;
+
+const KINDS: readonly EdgeBlock['kind'][] = ['text', 'controls', 'surface'];
+const ROLES: readonly NonNullable<EdgeBlock['role']>[] = ['list-item', 'table', 'centred', 'placeholder'];
+const isKind = (v: unknown): v is EdgeBlock['kind'] => KINDS.some((k) => k === v);
+const isRole = (v: unknown): v is NonNullable<EdgeBlock['role']> => ROLES.some((r) => r === v);
+const num = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+const field = (o: object, key: string): unknown => Reflect.get(o, key);
+
+/**
+ * The probe's typed read: `null` when the page had no `#root` or returned something else, so a failed measurement is
+ * reported as unmeasured and never read as "no offsets". A malformed block fails the whole read for the same reason.
+ */
+export function parseEdgeProbe(value: unknown): EdgeProbe | null {
+  if (typeof value !== 'object' || value === null) return null;
+  const raw = field(value, 'blocks');
+  const placeholdersOnly = field(value, 'placeholdersOnly');
+  if (!Array.isArray(raw) || typeof placeholdersOnly !== 'boolean') return null;
+  const skippedRaw = field(value, 'skipped');
+  if (typeof skippedRaw !== 'object' || skippedRaw === null) return null;
+  const rowItems = field(skippedRaw, 'rowItems');
+  const ornaments = field(skippedRaw, 'ornaments');
+  if (!num(rowItems) || !num(ornaments)) return null;
+  const blocks: EdgeBlock[] = [];
+  for (const entry of raw) {
+    if (typeof entry !== 'object' || entry === null) return null;
+    const [id, kind, edge, left, right, top] = ['id', 'kind', 'edge', 'left', 'right', 'top'].map((k) => field(entry, k));
+    const [within, textEdge, role] = ['within', 'textEdge', 'role'].map((k) => field(entry, k));
+    if (typeof id !== 'string' || !isKind(kind) || !num(edge) || !num(left) || !num(right) || !num(top)) return null;
+    if (within !== undefined && typeof within !== 'string') return null;
+    if (textEdge !== undefined && !num(textEdge)) return null;
+    if (role !== undefined && !isRole(role)) return null;
+    blocks.push({
+      id,
+      kind,
+      edge,
+      left,
+      right,
+      top,
+      ...(within !== undefined ? { within } : {}),
+      ...(textEdge !== undefined ? { textEdge } : {}),
+      ...(role !== undefined ? { role } : {}),
+    });
+  }
+  return { blocks, placeholdersOnly, skipped: { rowItems, ornaments } };
+}

package/src/evaluation/criteria/edge.ts

@@ -0,0 +1,202 @@
+/**
+ * `space.edge` as an instrument (#1663): the alignment rule applied to measured blocks, never to a model's estimate.
+ *
+ * The rule (docs/design/direction/visual-criteria.md, "The edge rule, measurable"): in each column of a card, the things
+ * that stack start on one edge. A block may start in only two other places — inside a box, on the box's inner edge,
+ * which everything inside the box then shares; or next to a box or a band, on the box's own outer edge or on the edge
+ * of the text inside it. Same edge means within 2 px. A card fails if any captured width fails; this function judges one
+ * width.
+ *
+ * Levels that are allowed: a hanging marker (a block with two edges, the marker's and its text's); a list inside
+ * running text (list items share an edge of their own); a table (measured at its rule, its cells not re-checked);
+ * columns side by side (each with its own edge); a centred group (one centre axis). A frame that shows only loading
+ * placeholders is not evaluated.
+ *
+ * Input is the measured block list (a DOM probe at capture produces it); output is the verdict plus every offset in
+ * px, so a near miss reads apart from a split. This module measures nothing itself. *
+ * **Validated instrument (#1663, 2026-10-02):** this file as of `cec465319` (with `7bb4da13e`) passed a fresh sealed
+ * blind draw at the registered bar (27/30, κ 0.76), stricter than the design lead's reading on its disagreements. Any
+ * later change to what this file measures or decides is a new instrument until another fresh sealed draw.
+ */
+
+/** The rule's tolerance: two edges within this many px are the same edge. */
+export const EDGE_TOLERANCE_PX = 2;
+
+/** One block of a captured card, at one canvas width. All x in CSS px from the card's left. */
+export interface EdgeBlock {
+  /** A stable label for evidence (a DOM path in production, a name in tests). */
+  readonly id: string;
+  /** A text block, a control group (measured at its first control), or a surface (a box: border or its own fill). */
+  readonly kind: 'text' | 'controls' | 'surface';
+  /**
+   * The block's edge: a text's first-character origin, a bounded control's or a surface's border box, an unbounded
+   * control's text. For a hanging marker, the marker's edge.
+   */
+  readonly edge: number;
+  /** Horizontal extent, for telling side-by-side columns apart. */
+  readonly left: number;
+  readonly right: number;
+  /** Vertical position, for finding a surface's first text. */
+  readonly top: number;
+  /** The surface this block sits inside, by id; absent at the card's own level. */
+  readonly within?: string;
+  /** A hanging marker's text edge: what stacks with the block may line up with this or with `edge`. */
+  readonly textEdge?: number;
+  /** Structure the DOM names: a list item, a table (measured at its rule), a member of a centred group. */
+  readonly role?: 'list-item' | 'table' | 'centred' | 'placeholder';
+}
+
+export interface EdgeOffset {
+  /** The container checked: the card, or a surface's id. */
+  readonly container: string;
+  /** The block that sits off every allowed edge. */
+  readonly block: string;
+  /** Its edge, and the nearest edge the rule allowed it, in px. */
+  readonly at: number;
+  readonly nearest: number;
+  readonly offPx: number;
+  /** Why the block is off when it is not plain distance (a centred block among edge-aligned ones). */
+  readonly reason?: string;
+}
+
+export interface EdgeVerdict {
+  readonly verdict: 'pass' | 'fail' | 'n/a';
+  /** Every block that sits off the allowed edges, with its offset; empty on a pass. */
+  readonly offsets: readonly EdgeOffset[];
+  readonly evidence: string;
+}
+
+const CARD = 'card';
+const same = (a: number, b: number): boolean => Math.abs(a - b) <= EDGE_TOLERANCE_PX;
+const overlaps = (a: EdgeBlock, b: EdgeBlock): boolean => a.left < b.right && b.left < a.right;
+const axis = (b: EdgeBlock): number => (b.left + b.right) / 2;
+
+/** A surface's content edge: where its first text starts (its topmost text block's edge), or undefined if it has none. */
+function contentEdge(surface: EdgeBlock, blocks: readonly EdgeBlock[]): number | undefined {
+  const texts = blocks.filter((b) => b.within === surface.id && b.kind !== 'surface' && b.role !== 'centred');
+  if (texts.length === 0) return undefined;
+  const first = texts.reduce((a, b) => (b.top < a.top ? b : a));
+  return first.textEdge ?? first.edge;
+}
+
+/** Columns among a container's direct blocks: non-surface blocks that overlap horizontally, transitively. */
+function columns(direct: readonly EdgeBlock[]): EdgeBlock[][] {
+  const all = direct.filter((b) => b.kind !== 'surface');
+  // A block that spans two columns side by side (it overlaps two blocks that do not overlap each other) belongs to
+  // their parent column, never to either (decided 2026-10-02): it must not chain them into one.
+  const bridges = (b: EdgeBlock): boolean => {
+    const under = all.filter((x) => x !== b && overlaps(x, b));
+    return under.some((x, i) => under.slice(i + 1).some((y) => !overlaps(x, y)));
+  };
+  const flow = all.filter((b) => !bridges(b));
+  const parentPool: EdgeBlock[] = all.filter((b) => bridges(b));
+  const parent = flow.map((_, i) => i);
+  const find = (i: number): number => (parent[i] === i ? i : (parent[i] = find(parent[i]!)));
+  for (let i = 0; i < flow.length; i += 1) for (let j = i + 1; j < flow.length; j += 1) if (overlaps(flow[i]!, flow[j]!)) parent[find(i)] = find(j);
+  const groups = new Map<number, EdgeBlock[]>();
+  flow.forEach((b, i) => groups.set(find(i), [...(groups.get(find(i)) ?? []), b]));
+  const cols = [...groups.values()];
+  // A surface joins the one column whose text or controls it overlaps. One that overlaps two or more columns spans
+  // them and goes to their parent, like a spanning text block; one that overlaps none stands with the other
+  // unclaimed blocks. Only flow blocks decide, so a surface never chains another surface into a column.
+  for (const s of direct.filter((b) => b.kind === 'surface')) {
+    const hit = cols.filter((c) => c.some((b) => b.kind !== 'surface' && overlaps(b, s)));
+    if (hit.length === 1) hit[0]!.push(s);
+    else parentPool.push(s);
+  }
+  // The parent's blocks and the unclaimed surfaces form columns among themselves: blocks that overlap stack.
+  const lp = parentPool.map((_, i) => i);
+  const lfind = (i: number): number => (lp[i] === i ? i : (lp[i] = lfind(lp[i]!)));
+  for (let i = 0; i < parentPool.length; i += 1) for (let j = i + 1; j < parentPool.length; j += 1) if (overlaps(parentPool[i]!, parentPool[j]!)) lp[lfind(i)] = lfind(j);
+  const lgroups = new Map<number, EdgeBlock[]>();
+  parentPool.forEach((b, i) => lgroups.set(lfind(i), [...(lgroups.get(lfind(i)) ?? []), b]));
+  cols.push(...lgroups.values());
+  return cols;
+}
+
+/** One column's check: one edge, or a stacked surface's content edge (the surface is then a ground). */
+function checkColumn(container: string, col: readonly EdgeBlock[], blocks: readonly EdgeBlock[]): EdgeOffset[] {
+  const surfaces = col.filter((b) => b.kind === 'surface');
+  const grounds = surfaces.flatMap((s) => {
+    const c = s.role === 'table' ? undefined : contentEdge(s, blocks);
+    return c === undefined ? [] : [c];
+  });
+  const flow = col.filter((b) => b.kind !== 'surface' && b.role !== 'centred' && b.role !== 'list-item');
+  const listItems = col.filter((b) => b.role === 'list-item');
+  // Every edge a flow block or a surface offers; the common edge E must sit on one of them.
+  const candidates = [...flow.flatMap((b) => [b.edge, ...(b.textEdge !== undefined ? [b.textEdge] : [])]), ...surfaces.flatMap((s) => [s.edge]), ...grounds];
+  const blockEdges = (b: EdgeBlock): number[] => [b.edge, ...(b.textEdge !== undefined ? [b.textEdge] : [])];
+  // The end edges another block of the column offers: its boxes' and its other control sets'.
+  const endEdgesBesides = (b: EdgeBlock): number[] => [...surfaces.map((s) => s.right), ...flow.filter((x) => x !== b && x.kind === 'controls').map((x) => x.right)];
+  // A column of only list items or only a centred group has no common edge to find; their own checks below still run.
+  let best: EdgeOffset[] | null = candidates.length === 0 ? [] : null;
+  for (const E of candidates) {
+    const allowed = [E, ...grounds];
+    const off: EdgeOffset[] = [];
+    for (const b of flow) {
+      if (blockEdges(b).some((x) => allowed.some((a) => same(x, a)))) continue;
+      // A control set alone on its line may END on the end edge its column's boxes or other controls share.
+      if (b.kind === 'controls' && endEdgesBesides(b).some((r) => same(b.right, r))) continue;
+      const nearest = allowed.reduce((n, a) => (Math.abs(a - b.edge) < Math.abs(n - b.edge) ? a : n));
+      off.push({ container, block: b.id, at: b.edge, nearest, offPx: Math.abs(b.edge - nearest) });
+    }
+    for (const s of surfaces) {
+      const c = s.role === 'table' ? undefined : contentEdge(s, blocks);
+      if (same(s.edge, E) || (c !== undefined && same(c, E))) continue;
+      const nearest = c !== undefined && Math.abs(c - E) < Math.abs(s.edge - E) ? c : s.edge;
+      off.push({ container, block: s.id, at: nearest, nearest: E, offPx: Math.abs(nearest - E) });
+    }
+    if (best === null || off.length < best.length || (off.length === best.length && sum(off) < sum(best))) best = off;
+    if (best.length === 0) break;
+  }
+  const offsets = best ?? [];
+  // A list inside running text: its items share an edge of their own.
+  if (listItems.length > 1) {
+    const e0 = listItems[0]!.edge;
+    for (const li of listItems.slice(1)) if (!same(li.edge, e0)) offsets.push({ container, block: li.id, at: li.edge, nearest: e0, offPx: Math.abs(li.edge - e0) });
+  }
+  // A centred group: its members share one centre axis, and it must be the whole content of its column. A column is
+  // edge-aligned or centred, never both (decided 2026-10-02).
+  const centred = col.filter((b) => b.role === 'centred');
+  // A centred group of two or more may follow a label or heading when nothing edge-aligned follows it (an empty state
+  // under its section label). One centred block among edge-aligned ones, or a column that returns to an edge after
+  // the group, fails (decided 2026-10-02).
+  const edgeAligned = col.filter((b) => b.role !== 'centred');
+  const groupTop = centred.length > 0 ? Math.min(...centred.map((c) => c.top)) : 0;
+  const groupEndsColumn = centred.length > 1 && edgeAligned.every((b) => b.top < groupTop);
+  if (centred.length > 0 && edgeAligned.some((b) => b.kind !== 'surface') && !groupEndsColumn) {
+    const E = flow[0]?.edge ?? edgeAligned[0]!.edge;
+    for (const c of centred) offsets.push({ container, block: c.id, at: c.edge, nearest: E, offPx: Math.abs(c.edge - E), reason: 'a centred block in an edge-aligned column' });
+  } else if (centred.length > 1) {
+    const a0 = axis(centred[0]!);
+    for (const c of centred.slice(1)) if (!same(axis(c), a0)) offsets.push({ container, block: c.id, at: axis(c), nearest: a0, offPx: Math.abs(axis(c) - a0) });
+  }
+  return offsets;
+}
+const sum = (o: readonly EdgeOffset[]): number => o.reduce((s, x) => s + x.offPx, 0);
+
+/**
+ * Judge one captured width. `placeholdersOnly`: the frame shows only loading placeholders, so the row is not evaluated.
+ */
+export function judgeEdges(measured: readonly EdgeBlock[], opts: { readonly placeholdersOnly?: boolean } = {}): EdgeVerdict {
+  if (opts.placeholdersOnly === true) return { verdict: 'n/a', offsets: [], evidence: 'only loading placeholders are shown; not evaluated' };
+  let blocks = measured;
+  // A placeholder (a box with nothing in it, shown while content loads) is not a block, and the rule needs two blocks to
+  // compare: with fewer than two once placeholders are set aside, the frame is not evaluated (decided 2026-10-02).
+  // The two blocks are content, text or controls: a box holds them and is not one of them for this count.
+  const kept = blocks.filter((b) => b.role !== 'placeholder');
+  const content = kept.filter((b) => b.kind !== 'surface').length;
+  if (content < 2) return { verdict: 'n/a', offsets: [], evidence: kept.length === 0 ? 'no blocks were measured' : 'fewer than two blocks once placeholders are set aside; not evaluated' };
+  blocks = kept;
+  const offsets: EdgeOffset[] = [];
+  const containers = [CARD, ...blocks.filter((b) => b.kind === 'surface' && b.role !== 'table').map((b) => b.id)];
+  for (const container of containers) {
+    const direct = blocks.filter((b) => (b.within ?? CARD) === container);
+    for (const col of columns(direct)) offsets.push(...checkColumn(container, col, blocks));
+  }
+  if (offsets.length === 0) return { verdict: 'pass', offsets, evidence: 'every column shares its edge, or sits on a stacked surface’s content edge, within 2 px' };
+  const worst = offsets.reduce((a, b) => (b.offPx > a.offPx ? b : a));
+  const lines = offsets.map((o) => `${o.block} at x${round(o.at)} is ${round(o.offPx)} px from x${round(o.nearest)} (in ${o.container}${o.reason !== undefined ? `; ${o.reason}` : ''})`);
+  return { verdict: 'fail', offsets, evidence: `${offsets.length} block(s) off the allowed edges, largest ${round(worst.offPx)} px: ${lines.join('; ')}` };
+}
+const round = (n: number): string => (Math.round(n * 10) / 10).toString();