@12ui/design 0.2.43 → 0.2.45

package/prototype-kit/polish/measure.mjs

@@ -0,0 +1,333 @@
+// Polish metrics: deterministic, geometry-only, computed in the browser on a rendered page.
+// One page → { overflow, overlap, alignment, whitespace, missingText, shift } with per-finding detail.
+// Used before AND after the polish stage; the numbers are instruments, the findings are the evidence.
+
+export const NEAR = 6;      // px: an edge this close (but not equal) to another is a near-miss
+export const EXACT = 0.75;  // px: closer than this counts as aligned
+
+// Runs inside the page. `opts.sourceItems` = inventory items of the source state(s) (id → {x,y,w,h,text}).
+export function pageMetricsScript() {
+  return ({ NEAR, EXACT, sourceItems, sectionSelector }) => {
+    const sections = [...document.querySelectorAll(sectionSelector || 'section[id^="viewport-"]')];
+    const section = sections[0] || document.body;
+    const sb = section.getBoundingClientRect();
+    const secOf = (el) => el.closest('section[id^="viewport-"]') || section;
+    const relTo = (r, s) => { const b = s.getBoundingClientRect(); return { x: r.left - b.left, y: r.top - b.top, w: r.width, h: r.height, r: r.right - b.left, b: r.bottom - b.top }; };
+    const rel = (r, el) => relTo(r, el ? secOf(el) : section);
+    const textRect = (el) => { const range = document.createRange(); range.selectNodeContents(el); const rr = range.getBoundingClientRect(); return rr.width > 0 ? rr : el.getBoundingClientRect(); };
+    // The Range rect is the LINE box (ascent+descent), 6–8 px taller than the declared box: two leaves with a real
+    // 3 px gap read as a 3.5 px overlap. Collision tests use box ∩ line box (rhythm lane, 80 of 106 findings were leading).
+    const tightRect = (el) => { const b = el.getBoundingClientRect(); const t = textRect(el); return { left: Math.max(b.left, t.left), right: Math.min(b.right, t.right), top: Math.max(b.top, t.top), bottom: Math.min(b.bottom, t.bottom) }; };
+    const clipRectOf = (el) => { // intersection of all overflow-clipping ancestors up to the section
+      let a = el.parentElement; let c = null; const s = secOf(el);
+      while (a && a !== s) { const o = getComputedStyle(a).overflow; if (o !== 'visible') { const r = a.getBoundingClientRect(); c = c ? { left: Math.max(c.left, r.left), top: Math.max(c.top, r.top), right: Math.min(c.right, r.right), bottom: Math.min(c.bottom, r.bottom) } : { left: r.left, top: r.top, right: r.right, bottom: r.bottom }; } a = a.parentElement; }
+      return c;
+    };
+    const kindOf = (el) => isText(el) ? 'text' : (el.tagName === 'BUTTON' || el.classList.contains('button')) ? 'button' : el.classList.contains('icon') ? 'icon' : (el.tagName === 'IMG' || el.classList.contains('image')) ? 'image' : el.classList.contains('badge') ? 'badge' : el.classList.contains('divider') ? 'divider' : 'box';
+    const sameKind = (A, B) => { const ka = kindOf(A.el), kb = kindOf(B.el); if (ka !== kb) return false; if (ka === 'text') return Math.abs(parseFloat(getComputedStyle(A.el).fontSize) - parseFloat(getComputedStyle(B.el).fontSize)) < 1 && Math.abs(A.r.h - B.r.h) < 3; if (ka === 'box') return Math.abs(A.r.h - B.r.h) <= 4 || Math.abs(A.r.w - B.r.w) <= 4; return Math.abs(A.r.h - B.r.h) < 3; };
+    const imageBacked = (el, r) => { let a = el.parentElement; while (a) { if (getComputedStyle(a).backgroundImage !== 'none') return true; a = a.parentElement; } const s = secOf(el); for (const im of s.querySelectorAll('img, .image, .decoration, .chart, svg, canvas, video')) { const ir = im.getBoundingClientRect(); if (ir.width && ir.height && Math.min(ir.right, r.right) - Math.max(ir.left, r.left) > 0 && Math.min(ir.bottom, r.bottom) - Math.max(ir.top, r.top) > 0) return true; } return false; };
+    const visible = (el) => {
+      const cs = getComputedStyle(el);
+      if (cs.display === 'none' || cs.visibility === 'hidden' || parseFloat(cs.opacity) === 0) return false;
+      const r = el.getBoundingClientRect();
+      return r.width > 0 && r.height > 0;
+    };
+    const isText = (el) => el.classList.contains('text') || el.classList.contains('paragraph') || /^H[1-6]$/.test(el.tagName);
+    const isLeaf = (el) => isText(el) || el.classList.contains('icon') || el.tagName === 'IMG' || el.classList.contains('image') || el.classList.contains('badge') || el.classList.contains('divider');
+    const inShell = (el) => !!el.closest('[data-proto-shell], aside, header, footer, [id*="sidebar"], [id*="-nav"]');
+    const scope = sections.length ? sections : [section];
+    const qsa = (sel) => scope.flatMap((s) => [...s.querySelectorAll(sel)]);
+    const leaves = qsa('.text, .paragraph, h1, h2, h3, h4, h5, h6, .icon, img, .image, .badge, .divider, button, .button')
+      .filter((el) => visible(el) && !el.closest('#proto-overlay-root') && !el.querySelector('.text, .paragraph') && !(el.matches('button, .button') && el.closest('.proto-notice, .proto-holding-block')));
+    const containers = qsa('div[id], button[id], aside[id], header[id], footer[id], nav[id], article[id], form[id], main[id]')
+      .filter((el) => visible(el) && !el.closest('#proto-overlay-root'));
+    const parseRgb = (s) => { const m = s && s.match(/rgba?\(([^)]+)\)/); if (!m) return null; const p = m[1].split(',').map(parseFloat); return { r: p[0], g: p[1], b: p[2], a: p[3] === undefined ? 1 : p[3] }; };
+    const lum = (c) => { const f = (v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4; }; return 0.2126 * f(c.r) + 0.7152 * f(c.g) + 0.0722 * f(c.b); };
+    // what is actually painted under the text: walk the hit-test stack at the text centre
+    const effectiveBg = (el) => {
+      el.scrollIntoView({ block: 'center', inline: 'nearest' });
+      const r = el.getBoundingClientRect();
+      const stack = document.elementsFromPoint(Math.min(window.innerWidth - 1, r.left + r.width / 2), Math.min(window.innerHeight - 1, r.top + Math.min(r.height / 2, 8)));
+      for (const e of stack) {
+        if (e.closest('.proto-notice, #proto-overlay-root, .proto-toast')) continue; // prototype chrome floats above the page; it is not the background
+        if (e === el || e.contains(el)) { const c0 = parseRgb(getComputedStyle(e).backgroundColor); if (e !== el && c0 && c0.a > 0.5) return c0; continue; }
+        if (e.tagName === 'IMG' || e.tagName === 'svg' || e.tagName === 'CANVAS' || e.tagName === 'VIDEO' || getComputedStyle(e).backgroundImage !== 'none') return null; // image-backed
+        const c = parseRgb(getComputedStyle(e).backgroundColor); if (c && c.a > 0.5) return c;
+      }
+      return { r: 255, g: 255, b: 255, a: 1 };
+    };
+    const out = { overflow: [], overlap: [], alignment: [], whitespace: [], missingText: [], shift: [], counts: {} };
+
+    // ---- overflow / clipping / escape
+    for (const el of leaves) {
+      if (!isText(el)) continue;
+      const sec = secOf(el); const secB = sec.getBoundingClientRect();
+      const er = el.getBoundingClientRect(); const tr = textRect(el);
+      const r = rel(er, el); const t = relTo(tr, sec);
+      const box = { id: el.id, text: (el.textContent || '').trim().slice(0, 80), x: +r.x.toFixed(1), y: +r.y.toFixed(1), w: +r.w.toFixed(1), h: +r.h.toFixed(1) };
+      // spill: the text's real line boxes extend beyond the element's own box (a nowrap label longer than its slot)
+      const spillX = Math.max(tr.right - er.right, er.left - tr.left);
+      if (spillX > 1.5) out.overflow.push({ kind: 'spill', px: +spillX.toFixed(1), ...box });
+      // clipped: an overflow-hiding ancestor cuts the text
+      const clip = clipRectOf(el);
+      if (clip) { const cp = Math.max(tr.right - clip.right, clip.left - tr.left, tr.bottom - clip.bottom, clip.top - tr.top); if (cp > 1.5) out.overflow.push({ kind: 'clipped', px: +cp.toFixed(1), ...box }); }
+      // escape: text box leaves an opaque ancestor (card) or the section itself
+      let a = el.parentElement, esc = null;
+      while (a && a !== sec) {
+        const cs2 = getComputedStyle(a); const bg = parseRgb(cs2.backgroundColor);
+        if ((bg && bg.a > 0.5) || parseFloat(cs2.borderTopWidth) > 0) {
+          const ar = rel(a.getBoundingClientRect(), el);
+          const over = Math.max(t.r - ar.r, ar.x - t.x, t.b - ar.b, ar.y - t.y);
+          if (over > 1.5) esc = { kind: 'escape', px: +over.toFixed(1), container: a.id, ...box };
+          break;
+        }
+        a = a.parentElement;
+      }
+      if (esc) out.overflow.push(esc);
+      const cut = Math.max(t.r - secB.width, t.b - secB.height, -t.x, -t.y);
+      if (cut > 1.5) out.overflow.push({ kind: 'cut', px: +cut.toFixed(1), ...box });
+    }
+
+    // ---- overlap between unrelated leaves
+    const L = leaves.map((el) => ({ el, r: rel(isText(el) ? tightRect(el) : el.getBoundingClientRect(), el) }));
+    for (let i = 0; i < L.length; i++) for (let j = i + 1; j < L.length; j++) {
+      const A = L[i], B = L[j];
+      if (A.el.contains(B.el) || B.el.contains(A.el) || secOf(A.el) !== secOf(B.el)) continue;
+      const ix = Math.min(A.r.r, B.r.r) - Math.max(A.r.x, B.r.x), iy = Math.min(A.r.b, B.r.b) - Math.max(A.r.y, B.r.y);
+      if (ix > 1 && iy > 3 && ix * iy > 24) {
+        // decorations/images behind text are design (hero text over image); only text×text, text×icon, icon×icon count
+        const kA = kindOf(A.el), kB = kindOf(B.el);
+        const textText = kA === 'text' && kB === 'text';
+        const textIcon = (kA === 'text' && kB === 'icon') || (kA === 'icon' && kB === 'text');
+        // a control (button) landing on text from another parent — a wrapped "Sign in" over a hero eyebrow (owner r4)
+        const textButton = (kA === 'text' && kB === 'button') || (kA === 'button' && kB === 'text');
+        if (!(textText || textIcon || textButton)) continue;
+        if (textIcon && A.el.parentElement === B.el.parentElement) continue; // icon + label inside one pill is design
+        if (textButton && (A.el.contains(B.el) || B.el.contains(A.el) || A.el.parentElement === B.el.parentElement)) continue;
+        out.overlap.push({ a: A.el.id, b: B.el.id, area: +(ix * iy).toFixed(0), ix: +ix.toFixed(1), iy: +iy.toFixed(1), ta: (A.el.textContent || '').trim().slice(0, 40), tb: (B.el.textContent || '').trim().slice(0, 40) });
+      }
+    }
+
+    // ---- alignment near-misses: siblings under the same parent, and "peer" containers in a row
+    const byParent = new Map();
+    for (const el of [...leaves, ...containers]) {
+      const p = el.parentElement; if (!p) continue;
+      if (!byParent.has(p)) byParent.set(p, []);
+      byParent.get(p).push(el);
+    }
+    const pushAlign = (axis, a, b, d) => out.alignment.push({ axis, a: a.id, b: b.id, delta: +d.toFixed(2) });
+    for (const [, kids] of byParent) {
+      const ks = kids.filter((k) => !k.classList.contains('decoration')).map((k) => ({ el: k, r: rel(k.getBoundingClientRect(), k) }));
+      if (ks.length < 2) continue;
+      for (let i = 0; i < ks.length; i++) for (let j = i + 1; j < ks.length; j++) {
+        const A = ks[i], B = ks[j];
+        if (!sameKind(A, B)) continue;
+        // vertical stack → compare left edges; horizontal row → compare tops
+        const stacked = A.r.b <= B.r.y + 1 || B.r.b <= A.r.y + 1;
+        const sideBySide = A.r.r <= B.r.x + 1 || B.r.r <= A.r.x + 1;
+        if (stacked && !sideBySide) {
+          const dl = Math.abs(A.r.x - B.r.x), dr = Math.abs(A.r.r - B.r.r);
+          if (dl > EXACT && dl <= NEAR) pushAlign('left', A.el, B.el, dl);
+          else if (dr > EXACT && dr <= NEAR && dl > NEAR) pushAlign('right', A.el, B.el, dr);
+        } else if (sideBySide && !stacked) {
+          const dt = Math.abs(A.r.y - B.r.y), db = Math.abs(A.r.b - B.r.b);
+          const cy = Math.abs((A.r.y + A.r.h / 2) - (B.r.y + B.r.h / 2));
+          if (dt > EXACT && dt <= NEAR) pushAlign('top', A.el, B.el, dt);
+          else if (db > EXACT && db <= NEAR && dt > NEAR) pushAlign('bottom', A.el, B.el, db);
+          else if (cy > EXACT && cy <= NEAR && dt > NEAR && db > NEAR && Math.abs(A.r.h - B.r.h) < 2 * NEAR) pushAlign('center', A.el, B.el, cy);
+        }
+      }
+    }
+
+    // ---- whitespace: gaps between consecutive stacked siblings; "almost the same" gaps are noise
+    for (const [p, kids] of byParent) {
+      const ks = kids.filter((k) => !k.classList.contains('decoration')).map((k) => ({ el: k, r: rel(k.getBoundingClientRect(), k) })).sort((a, b) => a.r.y - b.r.y);
+      const gaps = [];
+      for (let i = 1; i < ks.length; i++) {
+        const prev = ks[i - 1], cur = ks[i];
+        if (!sameKind(prev, cur)) continue;
+        const stacked = prev.r.b <= cur.r.y + 1 && Math.min(prev.r.r, cur.r.r) - Math.max(prev.r.x, cur.r.x) > 0;
+        if (stacked) gaps.push({ a: prev.el.id, b: cur.el.id, gap: +(cur.r.y - prev.r.b).toFixed(2) });
+      }
+      if (gaps.length < 2) continue;
+      // cluster gaps: two gaps in the same stack within NEAR of each other but not equal → inconsistent rhythm
+      for (let i = 0; i < gaps.length; i++) for (let j = i + 1; j < gaps.length; j++) {
+        const d = Math.abs(gaps[i].gap - gaps[j].gap);
+        if (d > EXACT && d <= NEAR) out.whitespace.push({ parent: p.id, g1: gaps[i], g2: gaps[j], delta: +d.toFixed(2) });
+      }
+    }
+
+    // ---- structure the harm guard protects: exactly-aligned same-kind sibling pairs ("columns": an icon column, a
+    // label column, a card row's top edge) and every consecutive sibling gap (any kind — the rail/content gutter is a
+    // gap between two siblings). A repair that breaks a column or changes a gap by more than a hair is harm.
+    out.columns = []; out.gaps = [];
+    const columnPairs = (ks) => {
+      for (let i = 0; i < ks.length; i++) for (let j = i + 1; j < ks.length; j++) {
+        const A = ks[i], B = ks[j];
+        if (!sameKind(A, B)) continue;
+        const stacked = A.r.b <= B.r.y + 1 || B.r.b <= A.r.y + 1;
+        const sideBySide = A.r.r <= B.r.x + 1 || B.r.r <= A.r.x + 1;
+        if (stacked && !sideBySide && Math.abs(A.r.x - B.r.x) <= EXACT) out.columns.push({ axis: 'left', a: A.el.id, b: B.el.id });
+        else if (sideBySide && !stacked && Math.abs(A.r.y - B.r.y) <= EXACT) out.columns.push({ axis: 'top', a: A.el.id, b: B.el.id });
+      }
+    };
+    // cousins too: the icons of a nav list each live in their own row — the column is across the rows' parent
+    const byGrand = new Map();
+    for (const el of leaves) { const g = el.parentElement?.parentElement; if (!g || !el.id) continue; if (!byGrand.has(g)) byGrand.set(g, []); byGrand.get(g).push(el); }
+    for (const [, cousins] of byGrand) {
+      const ks = cousins.filter((k) => !k.classList.contains('decoration')).map((k) => ({ el: k, r: rel(k.getBoundingClientRect(), k) }));
+      const parents = new Set(ks.map((k) => k.el.parentElement)); if (parents.size < 2) continue;
+      columnPairs(ks.filter((k) => kindOf(k.el) === 'icon' || kindOf(k.el) === 'text'));
+    }
+    for (const [p, kids] of byParent) {
+      const ks = kids.filter((k) => !k.classList.contains('decoration')).map((k) => ({ el: k, r: rel(k.getBoundingClientRect(), k) }));
+      columnPairs(ks);
+      const byY = [...ks].sort((a, b) => a.r.y - b.r.y);
+      for (let i = 1; i < byY.length; i++) { const P = byY[i - 1], C = byY[i]; if (P.r.b <= C.r.y + 1 && Math.min(P.r.r, C.r.r) - Math.max(P.r.x, C.r.x) > 0) out.gaps.push({ axis: 'v', a: P.el.id, b: C.el.id, gap: +(C.r.y - P.r.b).toFixed(2) }); }
+      const byX = [...ks].sort((a, b) => a.r.x - b.r.x);
+      const fitHost = p.closest ? p.closest('[data-proto-fit]') : null; const fh = fitHost ? fitHost.id : null;
+      for (let i = 1; i < byX.length; i++) { const P = byX[i - 1], C = byX[i]; if (P.r.r <= C.r.x + 1 && Math.min(P.r.b, C.r.b) - Math.max(P.r.y, C.r.y) > 0) out.gaps.push({ axis: 'h', a: P.el.id, b: C.el.id, gap: +(C.r.x - P.r.r).toFixed(2), fit: fh }); }
+    }
+
+    // ---- fitted shell children: does the inner ink still honour the donor's alignment relation? (build.mjs marks
+    // every clamped container with data-proto-fit = centered | left | right). Measured live on the painted ink:
+    //   centered → |leftInset − rightInset| ≤ 8 px   right → right inset ≤ 12 px   left → left inset ≤ 12 px or a
+    //   flanking sibling box touches the ink (an avatar beside a name). Anything else is an off-center finding.
+    out.offcenter = [];
+    for (const host of qsa('[data-proto-fit]')) {
+      if (!visible(host)) continue;
+      const rel = host.getAttribute('data-proto-fit');
+      const hr = host.getBoundingClientRect();
+      const ink = [...host.querySelectorAll('.text, .paragraph, .icon, h1, h2, h3, h4, h5, h6, button > span')].filter((el) => visible(el) && (el.classList.contains('icon') || (el.textContent || '').trim()));
+      if (!ink.length) continue;
+      const boxes = host.querySelectorAll('[id]');
+      const rects = ink.map((el) => (el.tagName === 'SPAN' && !el.classList.contains('icon')) ? textRect(el) : el.getBoundingClientRect());
+      // contiguous groups along x (gap ≤ 16), the same notion the build used
+      const sorted = rects.map((r, i) => ({ r, el: ink[i] })).sort((a, b) => a.r.left - b.r.left);
+      const groups = []; for (const it of sorted) { const g = groups[groups.length - 1]; if (g && it.r.left - Math.max(...g.map((x) => x.r.right)) <= 16) g.push(it); else groups.push([it]); }
+      for (const g of groups) {
+        const left = Math.min(...g.map((x) => x.r.left)), right = Math.max(...g.map((x) => x.r.right));
+        const top = Math.min(...g.map((x) => x.r.top)), bottom = Math.max(...g.map((x) => x.r.bottom));
+        // flanking sibling boxes (badges, avatars) in the same band move the anchor, as in the build
+        let la = hr.left, ra = hr.right;
+        for (const b of boxes) { if (b === host || g.some((x) => b === x.el || b.contains(x.el))) continue; const br = b.getBoundingClientRect(); if (!br.width || br.top >= bottom || br.bottom <= top) continue; if (br.right <= left + 1) la = Math.max(la, br.right); if (br.left >= right - 1) ra = Math.min(ra, br.left); }
+        const li = left - la, ri = ra - right;
+        const expL = parseFloat(host.getAttribute('data-proto-fit-left')), expR = parseFloat(host.getAttribute('data-proto-fit-right'));
+        let bad = false;
+        const partial = host.hasAttribute('data-proto-fit-partial');
+        // a partial re-centre (ink stopped at the box edge) is judged as 'no worse than the donor', not as centred
+        if (rel === 'centered') bad = groups.length === 1 && (partial ? (Number.isFinite(expL) && Number.isFinite(expR) && Math.abs(li - ri) > Math.abs(expL - expR) + 2) : Math.abs(li - ri) > 8);
+        else if (rel === 'right') bad = g === groups[groups.length - 1] && (Number.isFinite(expR) ? Math.abs(ri - expR) > 6 : ri > 12); // the donor's right inset, kept
+        else if (rel === 'left') bad = g === groups[0] && (Number.isFinite(expL) ? li - expL > 6 : (li > 12 && la === hr.left && ri < li)); // the donor's left inset, kept
+        if (bad) out.offcenter.push({ id: host.id, relation: rel, leftInset: +li.toFixed(1), rightInset: +ri.toFixed(1), ink: g.map((x) => x.el.id || x.el.tagName).slice(0, 3) });
+      }
+    }
+
+    // ---- rail raggedness: rows of the page's top-level blocks whose left edge is 2–48 px off the dominant left inset
+    // (design-quality metric; the left-rail rule drives it down; a rise is harm)
+    out.rail = [];
+    {
+      const INK = '.text, .paragraph, h1, h2, h3, h4, h5, h6, .icon, img, .image, .badge, button, .button';
+      const paintedBox = (el) => { const cs = getComputedStyle(el); const bg = parseRgb(cs.backgroundColor); return (bg && bg.a > 0.5) || parseFloat(cs.borderLeftWidth) > 0; };
+      for (const sec of scope) {
+        const sb = sec.getBoundingClientRect();
+        const edgeOf = (el) => { const r = el.getBoundingClientRect(); let left = paintedBox(el) ? r.left : Infinity, right = paintedBox(el) ? r.right : -Infinity; for (const k of [...(el.matches(INK) ? [el] : []), ...el.querySelectorAll(INK)]) { if (!visible(k)) continue; const kr = k.getBoundingClientRect(); if (kr.left - sb.left <= 2) continue; left = Math.min(left, kr.left); right = Math.max(right, kr.right); } for (const k of el.querySelectorAll('[id]:not(.text):not(.icon):not(img):not(button)')) { if (!visible(k) || !paintedBox(k)) continue; const kr = k.getBoundingClientRect(); if (kr.left - sb.left <= 2 || kr.width < 40) continue; left = Math.min(left, kr.left); right = Math.max(right, kr.right); } return Number.isFinite(left) ? { left: left - sb.left, right: right - sb.left } : null; };
+        const rows = [];
+        for (const block of sec.children) {
+          if (!block.id || !visible(block) || block.closest('#proto-overlay-root')) continue;
+          const be = edgeOf(block); if (!be) continue;
+          let kids = [...block.children].filter((k) => k.id && visible(k));
+          if (kids.length === 1 && kids[0].children.length > 1) kids = [...kids[0].children].filter((k) => k.id && visible(k));
+          if (!kids.length) kids = [block];
+          for (const k of kids) { const e = edgeOf(k); if (!e) continue; if (e.left <= 2) continue; if ((e.right - e.left) < 0.6 * sb.width && Math.abs(e.left - (sb.width - e.right)) <= 24) continue; rows.push({ id: k.id, edge: e.left, blockEdge: be.left, block: block.id }); }
+        }
+        if (rows.length < 3) continue;
+        const sorted = [...rows].sort((a, b) => a.edge - b.edge); const clusters = [];
+        for (const r of sorted) { const c = clusters[clusters.length - 1]; if (c && r.edge - c[0].edge <= 4) c.push(r); else clusters.push([r]); }
+        clusters.sort((a, b) => new Set(b.map((r) => r.block)).size - new Set(a.map((r) => r.block)).size || b.length - a.length);
+        const edges = clusters[0].map((r) => r.edge).sort((a, b) => a - b); const rail = edges[Math.floor((edges.length - 1) / 2)];
+        for (const r of rows) { const d = Math.abs(rail - r.edge); if (d >= 2 && d <= 48 && !(r.edge - r.blockEdge >= 12 && Math.abs(r.blockEdge - rail) < 2)) out.rail.push({ id: r.id, edge: +r.edge.toFixed(1), rail: +rail.toFixed(1) }); }
+      }
+    }
+
+    // ---- explicit plan seams (stacked pages): ink gap across each adjacent pair of viewport sections
+    out.seams = [];
+    {
+      const INK = '.text, .paragraph, h1, h2, h3, h4, h5, h6, .icon, img, .image, button, .button';
+      const secs = [...scope].filter((s) => visible(s)).sort((a, b) => a.getBoundingClientRect().top - b.getBoundingClientRect().top);
+      for (let i = 1; i < secs.length; i++) {
+        const A = secs[i - 1], B = secs[i]; const ar = A.getBoundingClientRect(), br = B.getBoundingClientRect();
+        const aInk = [...A.querySelectorAll(INK)].filter(visible).map((e) => e.getBoundingClientRect().bottom), bInk = [...B.querySelectorAll(INK)].filter(visible).map((e) => e.getBoundingClientRect().top);
+        if (!aInk.length || !bInk.length) continue;
+        out.seams.push({ before: A.id, after: B.id, gap: +(Math.min(...bInk) - Math.max(...aInk)).toFixed(1), dom: +(br.top - ar.bottom).toFixed(1) });
+      }
+    }
+
+    // ---- missing / invisible text vs source
+    const builtText = new Map();
+    for (const el of qsa('.text, .paragraph, h1, h2, h3, h4, h5, h6')) if (el.id) builtText.set(el.id, el);
+    const replacedShell = new Set([...document.querySelectorAll('[data-proto-shell]')].map((el) => el.id));
+    if (sourceItems) {
+      for (const [id, src] of Object.entries(sourceItems)) {
+        if (!src.text) continue;
+        if ((src.chain || []).some((c) => replacedShell.has(c))) continue; // the canonical shell replaced this page's own shell copy
+        const el = builtText.get(id) || document.getElementById(id);
+        if (!el) { out.missingText.push({ id, kind: 'absent', src: src.text.slice(0, 60) }); continue; }
+        const txt = (el.textContent || '').trim();
+        if (!txt) { out.missingText.push({ id, kind: 'empty', src: src.text.slice(0, 60) }); continue; }
+        if (!visible(el)) { out.missingText.push({ id, kind: 'hidden', src: src.text.slice(0, 60) }); continue; }
+        const cs = getComputedStyle(el); const fg = parseRgb(cs.color); const bg = effectiveBg(el);
+        if (fg && bg && !imageBacked(el, el.getBoundingClientRect())) {
+          const l1 = lum(fg), l2 = lum(bg); const contrast = (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+          if (contrast < 1.25 && fg.a > 0.05) out.missingText.push({ id, kind: 'invisible', contrast: +contrast.toFixed(2), src: src.text.slice(0, 60) });
+        }
+        const r = rel(el.getBoundingClientRect(), el);
+        // top-left corner, not the centre: a width-only repair (fit-text) is not content moving
+        const dx = r.x - src.x, dy = r.y - src.y;
+        const d = Math.hypot(dx, dy);
+        if (d > 1) out.shift.push({ id, dx: +dx.toFixed(1), dy: +dy.toFixed(1), d: +d.toFixed(1) });
+      }
+    }
+    // standalone invisible-text check (no source needed)
+    for (const [id, el] of builtText) {
+      if (sourceItems && sourceItems[id]) continue;
+      if (!visible(el) || !(el.textContent || '').trim()) continue;
+      const fg = parseRgb(getComputedStyle(el).color); if (!fg) continue;
+      if (imageBacked(el, el.getBoundingClientRect())) continue;
+      const bg = effectiveBg(el); if (!bg) continue; const l1 = lum(fg), l2 = lum(bg);
+      const contrast = (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+      if (contrast < 1.25 && fg.a > 0.05) out.missingText.push({ id, kind: 'invisible', contrast: +contrast.toFixed(2), src: el.textContent.trim().slice(0, 60) });
+    }
+
+    window.scrollTo(0, 0); // effectiveBg scrolled probes into view; leave the page as found
+    out.counts = {
+      leaves: leaves.length, textLeaves: leaves.filter(isText).length, containers: containers.length,
+      overflow: out.overflow.length, overlap: out.overlap.length, alignment: out.alignment.length, whitespace: out.whitespace.length,
+      columns: out.columns.length, gaps: out.gaps.length, seams: out.seams.length, narrowSeams: out.seams.filter((x) => x.gap < 48).length, documentHeight: document.documentElement.scrollHeight, offcenter: out.offcenter.length, rail: out.rail.length, missingText: out.missingText.length, shifted: out.shift.length, maxShift: out.shift.reduce((m, s) => Math.max(m, s.d), 0),
+      sectionW: sb.width, sectionH: sb.height,
+    };
+    return out;
+  };
+}
+
+// Source geometry for a state from inventory.json: id → {x,y,w,h,text}
+export function sourceItemsFor(inventory, stateIds) {
+  const map = {};
+  for (const page of inventory.pages) for (const sec of page.sections) {
+    if (!stateIds.includes(sec.sectionId)) continue;
+    for (const it of sec.items) if (it.id && (it.cls.includes('text') || /^h[1-6]$/.test(it.tag))) map[it.id] = { x: it.x, y: it.y, w: it.w, h: it.h, text: it.text, chain: it.chain };
+  }
+  return map;
+}
+
+// Wait until webfonts have actually swapped in (document.fonts.ready resolves before late swaps on some pages —
+// 4/249 pages measured differently run-to-run until this settle was added).
+export async function settleFonts(page, ms = 250) {
+  await page.evaluate(() => document.fonts.ready);
+  await page.waitForFunction(() => document.fonts.status === 'loaded' && [...document.fonts].every((f) => f.status !== 'loading'));
+  await page.waitForTimeout(ms);
+}
+
+export async function measurePage(page, { sourceItems = null, sectionSelector = null } = {}) {
+  return page.evaluate(pageMetricsScript(), { NEAR, EXACT, sourceItems, sectionSelector });
+}

package/prototype-kit/polish/overrides.mjs

@@ -0,0 +1,55 @@
+// Override model shared by every polish rule and the driver.
+// An override is { id | sel, rule, reason, dx?, dy?, w?, h?, css?: {prop: value} }.
+//   id     → targets #id; sel → targets an arbitrary selector (holding pages have class-only nodes)
+//   dx/dy  → translate (does not disturb siblings; sums across rules)
+//   w/h    → width/height in px (last rule wins)
+//   css    → any other declarations (last rule wins per property)
+
+export function mergeOverrides(list) {
+  const byId = new Map();
+  for (const o of list) {
+    if (!o || !(o.id || o.sel)) continue;
+    const key = o.sel || o.id;
+    const cur = byId.get(key) || { id: o.id, sel: o.sel, dx: 0, dy: 0, css: {}, rules: [] };
+    cur.dx += o.dx || 0;
+    cur.dy += o.dy || 0;
+    if (o.w != null) cur.w = o.w;
+    if (o.h != null) cur.h = o.h;
+    Object.assign(cur.css, o.css || {});
+    cur.rules.push(o.rule + (o.reason ? `: ${o.reason}` : ''));
+    if (o.meta && !cur.meta) cur.meta = o.meta;
+    byId.set(key, cur);
+  }
+  return [...byId.values()];
+}
+
+const esc = (id) => id.replace(/([^\w-])/g, '\\$1');
+
+export function overridesToCss(merged) {
+  const lines = ['/* proto polish: deterministic per-id overrides; every line names the rule that produced it */'];
+  for (const o of merged) {
+    const decl = [];
+    if (Math.abs(o.dx) > 0.01 || Math.abs(o.dy) > 0.01) decl.push(`transform:translate(${round(o.dx)}px,${round(o.dy)}px)`);
+    if (o.w != null) decl.push(`width:${round(o.w)}px`);
+    if (o.h != null) decl.push(`height:${round(o.h)}px`);
+    for (const [k, v] of Object.entries(o.css)) decl.push(`${k}:${v}`);
+    if (!decl.length) continue;
+    lines.push(`/* ${o.rules.join(' | ')} */`);
+    lines.push(`${o.sel || '#' + esc(o.id)}{${decl.map((d) => d + '!important').join(';')}}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+function round(n) { return Math.round(n * 100) / 100; }
+
+// In-browser: (re)place a <style id="proto-polish"> with the given css text.
+export function applyOverridesScript() {
+  return (css) => {
+    let style = document.getElementById('proto-polish');
+    if (!style) { style = document.createElement('style'); style.id = 'proto-polish'; document.head.appendChild(style); }
+    style.textContent = css;
+    // force layout
+    void document.body.offsetHeight;
+    return true;
+  };
+}

package/prototype-kit/polish/polish.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+// Polish stage: deterministic visual repair of a built prototype, one page at a time (pages are independent → parallel).
+// Usage: node polish/polish.mjs <protoDir> --out <outDir> [--inventory inventory.json --model model.json] [--rules a,b] [--concurrency 4] [--report polish-report.json]
+//
+// For every real page: measure → run rules (in-browser, geometry-only) → apply overrides live → re-measure →
+// harm guard (reject any rule that adds overlap/clipping/cut or moves content beyond its declared cap) →
+// write polish/<unit>.css + <link> into the page copy. Nothing is redrawn; only per-id CSS overrides are emitted.
+import fs from 'node:fs';
+import path from 'node:path';
+import { chromium } from '@playwright/test';
+import { startStaticServer } from '../lib/static-server.mjs';
+import { measurePage, sourceItemsFor, settleFonts } from './measure.mjs';
+import { loadRules } from './rules/index.mjs';
+import { applyOverridesScript, overridesToCss, mergeOverrides } from './overrides.mjs';
+import { structureHarm } from './harm.mjs';
+import { probeSeams } from './ground-probe.mjs';
+import { pageRuleRecords, summarizePolishReport } from './report.mjs';
+
+const HARM = { newOverlap: 0, newEscape: 0, newCut: 0, newClipped: 0 };
+
+export async function polishPrototype({
+  protoDir,
+  outDir,
+  inventoryFile = path.join(protoDir, '..', 'inventory.json'),
+  modelFile = path.join(protoDir, '..', 'model.json'),
+  reportFile = path.join(outDir, 'polish-report.json'),
+  ruleNames = [],
+  concurrency = 4,
+  log = () => {},
+}) {
+  protoDir = path.resolve(protoDir);
+  outDir = path.resolve(outDir);
+  inventoryFile = path.resolve(inventoryFile);
+  modelFile = path.resolve(modelFile);
+  reportFile = path.resolve(reportFile);
+  if (protoDir === outDir) {
+    throw new Error('Polish source and output directories must be different.');
+  }
+  fs.rmSync(outDir, { recursive: true, force: true });
+  fs.cpSync(protoDir, outDir, { recursive: true });
+  fs.mkdirSync(path.join(outDir, 'polish'), { recursive: true });
+  const manifest = JSON.parse(fs.readFileSync(path.join(outDir, 'proto-manifest.json'), 'utf8'));
+  const inventory = fs.existsSync(inventoryFile) ? JSON.parse(fs.readFileSync(inventoryFile, 'utf8')) : null;
+  const model = fs.existsSync(modelFile) ? JSON.parse(fs.readFileSync(modelFile, 'utf8')) : null;
+  const rules = await loadRules(ruleNames);
+  const server = await startStaticServer(path.dirname(outDir));
+  const base = `${server.baseUrl}/${path.basename(outDir)}`;
+  const browser = await chromium.launch();
+  const report = {
+    version: 1,
+    policy: 'retained-v1',
+    rules: rules.map((rule) => rule.name),
+    pages: [],
+  };
+
+  async function polishPage(unit) {
+    const page = await browser.newPage({ viewport: { width: 1536, height: 1024 } });
+    const row = { unit: unit.id, rules: {}, accepted: [], rejected: [], overrides: 0 };
+    try {
+      const sectionIds = model ? unit.states.map((s) => model.states.find((st) => st.stateId === s)?.sectionId).filter(Boolean) : [];
+      const sourceItems = inventory && sectionIds.length ? sourceItemsFor(inventory, sectionIds) : null;
+      await page.goto(`${base}/${unit.id}.html`, { waitUntil: 'networkidle', timeout: 30_000 });
+      await settleFonts(page);
+      const before = await measurePage(page, { sourceItems });
+      row.before = before.counts;
+      // phase 1: geometry rules propose against the pristine page; phase 2 ('post') rules — colour — run against the
+      // geometry-polished DOM, because where a block ENDS UP decides what is painted under it (a legal row lifted back
+      // into a navy footer must not have been darkened for the white it used to sit on).
+      const harmed = (after, ruleSet) => {
+        const newOf = (kind) => (after.overflow.filter((o) => o.kind === kind).length) - (before.overflow.filter((o) => o.kind === kind).length);
+        const cap = Math.max(0, ...ruleSet.map((p) => p.rule.maxShift || 0));
+        // rules that declare block moves (left-rail) change the horizontal gaps beside the rows they move by design
+        const exempt = new Set(ruleSet.filter((p) => p.rule.movesBlocks).flatMap((p) => p.overrides.map((o) => o.id)));
+        // A spacing rule may change only the exact before->after gaps it declares in seam metadata. Every other
+        // vertical sibling gap remains protected by the ordinary harm guard.
+        const exemptGaps = new Set(ruleSet.flatMap((p) => p.overrides.map((o) => o.meta?.seam).filter(Boolean).flatMap((s) => (s.beforePeers || [s.before]).map((beforeId) => `${beforeId}|${s.after}`))));
+        const st = structureHarm(before, after, exempt, exemptGaps);
+        return {
+          misaligned: st.misaligned.length > 0,
+          spacing: st.spacing.length > 0,
+          overlap: after.counts.overlap - before.counts.overlap > HARM.newOverlap,
+          escape: newOf('escape') > HARM.newEscape,
+          cut: newOf('cut') > HARM.newCut,
+          clipped: newOf('clipped') > HARM.newClipped,
+          invisible: after.counts.missingText > before.counts.missingText,
+          offcenter: (after.counts.offcenter || 0) > (before.counts.offcenter || 0),
+          rail: (after.counts.rail || 0) > (before.counts.rail || 0),
+          shift: after.counts.maxShift - before.counts.maxShift > cap + 0.5,
+        };
+      };
+      const propose = async (ruleSet, metrics) => {
+        const proposals = [];
+        for (const rule of ruleSet) {
+          const proposed = await page.evaluate(rule.browserFn(), { metrics, params: rule.params || {} });
+          const cap = rule.maxShift ?? 0; // each override is held to ITS rule's declared cap
+          const found = proposed.filter((o) => Math.abs(o.dx || 0) <= cap + 0.01 && Math.abs(o.dy || 0) <= cap + 0.01);
+          row.rules[rule.name] = { proposed: proposed.length, overCap: proposed.length - found.length };
+          if (rule.recordsCensus) {
+            row.rules[rule.name].census = await page.evaluate(rule.browserFn(), {
+              metrics,
+              params: { ...(rule.params || {}), census: true },
+            });
+          }
+          if (found.length) proposals.push({ rule, overrides: found });
+        }
+        return proposals;
+      };
+      const evaluate = async (set) => {
+        const merged = mergeOverrides(set.flatMap((p) => p.overrides));
+        await page.evaluate(applyOverridesScript(), overridesToCss(merged));
+        const after = await measurePage(page, { sourceItems });
+        return { merged, after };
+      };
+      // greedy acceptance with harm guard: apply all, then drop the rule whose removal helps most until clean
+      const accept = async (active) => {
+        let result = active.length ? await evaluate(active) : null;
+        let guard = result ? harmed(result.after, active) : null;
+        while (result && Object.values(guard).some(Boolean) && active.length) {
+          let best = null;
+          for (let i = 0; i < active.length; i++) {
+            const trial = active.filter((_, j) => j !== i);
+            const r = trial.length ? await evaluate(trial) : { merged: [], after: before };
+            const g = trial.length ? harmed(r.after, trial) : {};
+            const score = Object.values(g).filter(Boolean).length;
+            if (!best || score < best.score) best = { i, score, r, g };
+          }
+          row.rejected.push({ rule: active[best.i].rule.name, harm: Object.keys(guard).filter((k) => guard[k]) });
+          active = active.filter((_, j) => j !== best.i);
+          result = active.length ? best.r : null;
+          guard = active.length ? best.g : null;
+        }
+        return { active, result };
+      };
+      const geometry = rules.filter((r) => r.phase !== 'post');
+      const post = rules.filter((r) => r.phase === 'post');
+      let active = await propose(geometry, before);
+      let { active: kept, result } = await accept(active);
+      active = kept;
+      if (post.length) {
+        if (result) await page.evaluate(applyOverridesScript(), overridesToCss(result.merged)); // polished DOM in place
+        const mid = result ? result.after : before;
+        const postProposals = await propose(post, mid);
+        if (postProposals.length) {
+          const r2 = await accept([...active, ...postProposals]);
+          active = r2.active; result = r2.result;
+        }
+      }
+      // background-integrity: a rule that extends a ground (section-breathing) must prove, on real pixels, that every
+      // accepted seam is painted in the owner's colour (coverage) and the page floor never shows (floor exposure), and
+      // that the document grew by exactly the accepted additions. Any failure rejects that rule on this page.
+      for (const rule of rules.filter((r) => r.verifyPaint)) {
+        const p = active.find((a) => a.rule === rule); if (!p) continue;
+        // baseline height = everything else applied, without this rule (page-cut may legitimately have grown the canvas)
+        await page.evaluate(applyOverridesScript(), overridesToCss(mergeOverrides(active.filter((a) => a !== p).flatMap((a) => a.overrides))));
+        const baseHeight = await page.evaluate(() => document.documentElement.scrollHeight);
+        await page.evaluate(applyOverridesScript(), overridesToCss(mergeOverrides(active.flatMap((a) => a.overrides))));
+        const seams = p.overrides.map((o) => o.meta?.seam).filter(Boolean);
+        const verdict = await probeSeams(page, seams, baseHeight);
+        row.ground = verdict;
+        if (!verdict.ok) {
+          row.rejected.push({ rule: rule.name, harm: verdict.failures.map((f) => 'ground-' + f.kind) });
+          active = active.filter((a) => a !== p);
+          result = active.length ? await evaluate(active) : null;
+        }
+      }
+      if (result) {
+        // make sure the live DOM reflects the final accepted set
+        result = await evaluate(active);
+        row.accepted = active.map((p) => ({ rule: p.rule.name, overrides: p.overrides.length }));
+        row.after = result.after.counts;
+        row.overrides = result.merged.length;
+        const css = overridesToCss(result.merged);
+        fs.writeFileSync(path.join(outDir, 'polish', `${unit.id}.css`), css);
+        const htmlFile = path.join(outDir, `${unit.id}.html`);
+        let html = fs.readFileSync(htmlFile, 'utf8');
+        if (!html.includes(`polish/${unit.id}.css`)) html = html.replace('</head>', `<link rel="stylesheet" href="polish/${unit.id}.css" data-proto-polish>\n</head>`);
+        fs.writeFileSync(htmlFile, html);
+        fs.writeFileSync(path.join(outDir, 'polish', `${unit.id}.json`), JSON.stringify({ unit: unit.id, accepted: row.accepted, rejected: row.rejected, overrides: result.merged }, null, 1));
+      } else {
+        row.after = row.before;
+      }
+    } catch (error) {
+      row.error = error.message;
+      row.accepted = [];
+      row.overrides = 0;
+      row.after = row.before;
+      fs.rmSync(path.join(outDir, 'polish', `${unit.id}.css`), { force: true });
+      fs.rmSync(path.join(outDir, 'polish', `${unit.id}.json`), { force: true });
+      fs.copyFileSync(
+        path.join(protoDir, `${unit.id}.html`),
+        path.join(outDir, `${unit.id}.html`),
+      );
+    } finally {
+      row.ruleRecords = pageRuleRecords(row, report.rules);
+      await page.close();
+    }
+    const reverted = row.ruleRecords
+      .filter((record) => record.status === 'reverted')
+      .map((record) => `${record.rule}:${(record.reasons || []).join('+') || 'guard'}`);
+    log(`${unit.id}: ${row.overrides} overrides, fired=[${row.ruleRecords.filter((record) => record.status === 'fired').map((record) => record.rule).join(',')}] reverted=[${reverted.join(',')}]${row.error ? ` ERROR ${row.error}` : ''}`);
+    return row;
+  }
+
+  // worker pool over independent pages
+  // real pages + holding pages (holdings have no source state; rules that need one simply find nothing)
+  const queue = [...manifest.units, ...(manifest.holdings || []).map(([slug, title]) => ({ id: slug, states: [], holding: true, title }))];
+  const workers = Array.from({ length: Math.max(1, concurrency) }, async () => {
+    while (queue.length) {
+      const unit = queue.shift();
+      report.pages.push(await polishPage(unit));
+    }
+  });
+  await Promise.all(workers);
+  report.pages.sort((a, b) => a.unit.localeCompare(b.unit));
+  await browser.close();
+  await server.close();
+  report.summary = summarizePolishReport(report);
+  fs.writeFileSync(reportFile, `${JSON.stringify(report, null, 2)}\n`);
+  return report;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === new URL(import.meta.url).pathname) {
+  const argv = process.argv.slice(2);
+  if (!argv[0]) throw new Error('usage: polish.mjs <protoDir> --out <outDir> [--rules a,b] [--concurrency n]');
+  const value = (flag, fallback) => (
+    argv.includes(flag) ? argv[argv.indexOf(flag) + 1] : fallback
+  );
+  const protoDir = path.resolve(argv[0]);
+  const outDir = path.resolve(value('--out', `${protoDir}-polished`));
+  const reportFile = path.resolve(value('--report', path.join(outDir, 'polish-report.json')));
+  const ruleNames = value('--rules', '').split(',').filter(Boolean);
+  const concurrency = Number(value('--concurrency', 4));
+  const report = await polishPrototype({
+    protoDir,
+    outDir,
+    inventoryFile: value('--inventory', path.join(protoDir, '..', 'inventory.json')),
+    modelFile: value('--model', path.join(protoDir, '..', 'model.json')),
+    reportFile,
+    ruleNames,
+    concurrency,
+    log: (message) => process.stderr.write(`${message}\n`),
+  });
+  const sum = (k) => report.pages.reduce((n, p) => n + (p[k === 'before' ? 'before' : 'after']?.overflow || 0), 0);
+  console.log(JSON.stringify({
+    pages: report.pages.length,
+    overrides: report.pages.reduce((n, page) => n + page.overrides, 0),
+    rejected: report.summary.reverted,
+    pageErrors: report.summary.pageErrors,
+    overflowBefore: sum('before'),
+    overflowAfter: sum('after'),
+  }));
+}