@12ui/design 0.2.43 → 0.2.45

package/prototype-kit/polish/rules/left-rail.mjs

@@ -0,0 +1,77 @@
+// left-rail: a column of page sections (brand, title, results, filters, footer …) whose left edges are ALMOST one
+// rail snap to the dominant inset. Design-quality rule (owner, 2026-08-23: "we are no longer aiming for pixel perfect,
+// we are trying to improve on it") — the source may itself be ragged; that is the point.
+//
+// Facts, per viewport section:
+//   rows     the direct children of every top-level block (and of a shell host) that carry ink. A row's edge is the
+//            leftmost ink it contains — text / icon / image / button — or its own box edge when it is painted
+//            (border or opaque background): a filter panel aligns by its panel edge, a heading by its glyphs.
+//   rail     cluster the row edges within 4 px; the dominant cluster is the one spanning most top-level blocks
+//            (ties → most rows, then most ink);
+//            the rail is its median edge.
+//   snap     a row whose edge is 2–48 px off the rail moves onto it (translate; internal structure untouched).
+//   silent   full-bleed rows (edge ≤ 2 px or ≥ 95 % width), centered rows (left inset ≈ right inset, ±24 px),
+//            rows far from the rail (> 48 px: a second column, a grid), indented sub-items (a row ≥ 12 px right of its
+//            own block's edge while that block already sits on the rail), and pages with fewer than 3 ink rows.
+// maxShift 48 is the declared magnitude; the harm guard still rejects the rule on any page where a snap adds an
+// overlap, cut, escape, broken column or off-center fit. Horizontal gaps adjacent to a moved row are this rule's own
+// declared change (movesBlocks), not spacing harm.
+export const name = 'left-rail';
+export const maxShift = 48;
+export const movesBlocks = true;
+export const params = { SNAP_MAX: 48, SNAP_MIN: 2, CLUSTER: 4, INDENT: 12, CENTER_TOL: 24 };
+
+export function browserFn() {
+  return ({ params }) => {
+    const P = Object.assign({ SNAP_MAX: 48, SNAP_MIN: 2, CLUSTER: 4, INDENT: 12, CENTER_TOL: 24 }, params || {});
+    const out = [];
+    const visible = (el) => { const s = getComputedStyle(el); if (s.display === 'none' || s.visibility === 'hidden' || parseFloat(s.opacity) === 0) return false; const r = el.getBoundingClientRect(); return r.width > 0 && r.height > 0; };
+    const parseRgb = (s) => { const m = s && s.match(/rgba?\(([^)]+)\)/); if (!m) return null; const p = m[1].split(',').map(parseFloat); return { a: p[3] === undefined ? 1 : p[3] }; };
+    const painted = (el) => { const cs = getComputedStyle(el); const bg = parseRgb(cs.backgroundColor); return (bg && bg.a > 0.5) || parseFloat(cs.borderLeftWidth) > 0; };
+    const INK = '.text, .paragraph, h1, h2, h3, h4, h5, h6, .icon, img, .image, .badge, button, .button';
+    for (const sec of document.querySelectorAll('section[id^="viewport-"]')) {
+      const sb = sec.getBoundingClientRect();
+      const edgeOf = (el) => {
+        const r = el.getBoundingClientRect();
+        let left = painted(el) ? r.left : Infinity, right = painted(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) || !painted(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); } // a painted panel edge is visible ink
+        if (!Number.isFinite(left)) return null;
+        return { left: left - sb.left, right: right - sb.left };
+      };
+      // rows: direct children of top-level blocks (a block is a direct child of the section; a shell host counts)
+      const rows = [];
+      for (const block of sec.children) {
+        if (!block.id || !visible(block)) 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)); // thin wrapper
+        if (!kids.length) kids = [block];
+        for (const k of kids) {
+          const e = edgeOf(k); if (!e) continue;
+          const r = k.getBoundingClientRect();
+          if (e.left <= 2 || r.width >= 0.95 * sb.width && painted(k) && !k.querySelector(INK)) continue; // full-bleed band
+          const rightInset = sb.width - e.right;
+          if ((e.right - e.left) < 0.6 * sb.width && Math.abs(e.left - rightInset) <= P.CENTER_TOL) continue; // a centered block (narrow ink, equal insets); a full-width row with ink at both ends is not
+          rows.push({ el: k, block, edge: e.left, blockEdge: be.left, ink: k.querySelectorAll(INK).length + (k.matches(INK) ? 1 : 0) });
+        }
+      }
+      if (rows.length < 3) continue;
+      // dominant cluster
+      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 <= P.CLUSTER) c.push(r); else clusters.push([r]); }
+      // dominance = how many distinct top-level BLOCKS sit on the inset (a footer with five rows is still one block)
+      const blocksOf = (c) => new Set(c.map((r) => r.block)).size;
+      clusters.sort((a, b) => blocksOf(b) - blocksOf(a) || b.length - a.length || b.reduce((n, r) => n + r.ink, 0) - a.reduce((n, r) => n + r.ink, 0));
+      const dom = clusters[0]; const edges = dom.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 = rail - r.edge;
+        if (Math.abs(d) < P.SNAP_MIN || Math.abs(d) > P.SNAP_MAX) continue;
+        // an indented sub-item under a block that already sits on the rail is design
+        if (r.edge - r.blockEdge >= P.INDENT && Math.abs(r.blockEdge - rail) < P.SNAP_MIN) continue;
+        out.push({ id: r.el.id, rule: 'left-rail', reason: `edge ${r.edge.toFixed(1)} → rail ${rail.toFixed(1)}`, dx: +d.toFixed(2) });
+      }
+    }
+    return out;
+  };
+}

package/prototype-kit/polish/rules/overlap.mjs

@@ -0,0 +1,122 @@
+// overlap: nudge apart two pieces of ink from DIFFERENT parents that have been assembled into each other.
+//
+// Mechanism: the builder composes a page from parts that were laid out independently, so a part can land a few px
+// into another part — a transplanted nav's "Log in" sitting on the page's own hero heading (Northshore), a topbar
+// icon 4 px into an incident header, a comparison-table value under its own check icon.
+//
+// What the pixels changed. measure.mjs measures text with a Range rect, which is the LINE box: it includes the
+// font's ascent/descent, so it is routinely 6-8 px taller than the element's declared box. On this population that
+// makes 80 of 106 "overlaps" pure typography — a "15" stacked over "min" with a real 3 px gap reads as a 3.5 px
+// overlap, and a transplanted brand line 2 px above a hero heading reads as 6.6 px. Nudging those apart would open
+// gaps the design never had. So this rule works on the TIGHT rect — the element's box intersected with its line box
+// — and fires only when the tight rects really cross. 26 of the 106 findings survive that test, 18 across parents.
+//
+// Fix: for a small tight overlap (≤ SMALL px on the axis we move), translate the LATER piece — the one further down
+// (or right), tie-broken by document order — clear by the overlap + 2 px, but only when it has slack:
+//   * nothing else may sit in the region the piece sweeps through,
+//   * it must stay inside its nearest painted ancestor (the card it belongs to) and inside its section,
+//   * a piece inside a transplanted shell is never moved: the shell is the fixed frame, the page's content yields.
+// Two heading LINES under one parent are the design's leading, not a collision, and are left alone; so are larger
+// overlaps, which need a layout decision rather than a nudge. Both are recorded in window.__protoRuleNotes.
+export const name = 'overlap';
+export const maxShift = 16;
+
+export function browserFn() {
+  return ({ metrics }) => {
+    const SMALL = 14, CLEAR = 2;
+    const out = [];
+    const notes = [];
+    const claimed = new Set();
+    const cs = (el) => getComputedStyle(el);
+    const visible = (el) => {
+      const s = cs(el);
+      if (s.display === 'none' || s.visibility === 'hidden' || parseFloat(s.opacity) === 0) return false;
+      const r = el.getBoundingClientRect();
+      return r.width > 0 && r.height > 0;
+    };
+    const isText = (el) => el.classList.contains('text') || /^H[1-6]$/.test(el.tagName);
+    // tight rect: the declared box ∩ the rendered line box. Neither alone is the ink — the box can be smaller than
+    // the type that overflows it, the line box is taller than the glyphs by the font's leading.
+    const tightRect = (el) => {
+      const b = el.getBoundingClientRect();
+      if (!isText(el)) return { left: b.left, right: b.right, top: b.top, bottom: b.bottom };
+      const range = document.createRange(); range.selectNodeContents(el);
+      const t = range.getBoundingClientRect();
+      if (!(t.width > 0)) return { left: b.left, right: b.right, top: b.top, bottom: b.bottom };
+      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 cross = (u, v) => ({ ix: Math.min(u.right, v.right) - Math.max(u.left, v.left), iy: Math.min(u.bottom, v.bottom) - Math.max(u.top, v.top) });
+    const parseRgb = (s) => { const m = s && s.match(/rgba?\(([^)]+)\)/); if (!m) return null; const p = m[1].split(',').map(parseFloat); return { a: p[3] === undefined ? 1 : p[3] }; };
+    // the nearest ancestor that actually paints a box — the card the ink lives in
+    const frameOf = (el) => {
+      const sec = el.closest('section[id^="viewport-"]') || document.body;
+      let a = el.parentElement;
+      while (a && a !== sec) {
+        const s = cs(a), bg = parseRgb(s.backgroundColor);
+        if ((bg && bg.a > 0.5) || parseFloat(s.borderTopWidth) > 0) return a.getBoundingClientRect();
+        a = a.parentElement;
+      }
+      return sec.getBoundingClientRect();
+    };
+    const allInk = [...document.querySelectorAll('.text, h1, h2, h3, h4, h5, h6, .icon, img, .image, .badge')]
+      .filter((el) => visible(el) && !el.closest('#proto-overlay-root') && !el.querySelector('.text'))
+      .map((el) => ({ el, r: tightRect(el) }));
+
+    for (const f of metrics.overlap || []) {
+      const a = document.getElementById(f.a), b = document.getElementById(f.b);
+      if (!a || !b || !visible(a) || !visible(b)) continue;
+      const note = (why, extra = {}) => notes.push({ rule: 'overlap', a: f.a, b: f.b, why, ...extra });
+      if (a.parentElement === b.parentElement) { note('same parent (leading / pill) — design, left alone'); continue; }
+
+      const ar = tightRect(a), br = tightRect(b);
+      const { ix, iy } = cross(ar, br);
+      if (!(ix > 1 && iy > 1)) { note('line-box overlap only, declared boxes are clear', { ix: +ix.toFixed(1), iy: +iy.toFixed(1) }); continue; }
+
+      const shellA = !!a.closest('[data-proto-shell]'), shellB = !!b.closest('[data-proto-shell]');
+      const vertical = iy <= ix;
+      // which piece yields: never the shell; otherwise the lower/righter one, tie-broken by document order
+      let mover, other;
+      if (shellA !== shellB) { mover = shellA ? b : a; other = shellA ? a : b; }
+      else {
+        const online = Math.abs((ar.top + ar.bottom) / 2 - (br.top + br.bottom) / 2) <= 4;
+        const byX = online || !vertical;
+        const later = (byX ? (br.left - ar.left) : (br.top - ar.top)) > 0.5 ? b
+          : (byX ? (ar.left - br.left) : (ar.top - br.top)) > 0.5 ? a
+          : (a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING) ? b : a;
+        mover = later; other = later === a ? b : a;
+      }
+      if (mover.closest('[data-proto-shell]')) { note('only a shell piece could move — left alone', { ix: +ix.toFixed(1), iy: +iy.toFixed(1) }); continue; }
+      const mr = mover === a ? ar : br, or_ = mover === a ? br : ar;
+
+      // Two pieces whose centres sit on the same line are ON one line — a label and its trailing check icon, an
+      // eyebrow icon and its kicker. Pulling those apart vertically drops the label off its row (proved on the
+      // Harborlight pricing table, where "Basic visibility" fell onto the row rule while its neighbouring column
+      // stayed put). Same-line collisions are separated horizontally or not at all.
+      const sameLine = Math.abs((mr.top + mr.bottom) / 2 - (or_.top + or_.bottom) / 2) <= 4;
+      // only ever move away from the other piece, and only along an axis whose overlap is small enough to nudge
+      const canY = !sameLine && mr.top >= or_.top - 0.5 && iy <= SMALL;
+      const canX = mr.left >= or_.left - 0.5 && ix <= SMALL;
+      const axis = canY && canX ? (iy <= ix ? 'y' : 'x') : canY ? 'y' : canX ? 'x' : null;
+      if (!axis) { note('overlap needs a layout decision, not a nudge', { ix: +ix.toFixed(1), iy: +iy.toFixed(1) }); continue; }
+      const shift = +((axis === 'y' ? iy : ix) + CLEAR).toFixed(2);
+      if (!mover.id || claimed.has(mover.id)) { note('mover already nudged by another pair', { mover: mover.id }); continue; }
+
+      // swept region: the mover's rect from where it is to where it lands — nothing else may be in it
+      const swept = {
+        left: mr.left, right: mr.right + (axis === 'x' ? shift : 0),
+        top: mr.top, bottom: mr.bottom + (axis === 'y' ? shift : 0),
+      };
+      const frame = frameOf(mover), sec = (mover.closest('section[id^="viewport-"]') || document.body).getBoundingClientRect();
+      if (swept.bottom > frame.bottom - 0.5 || swept.right > frame.right - 0.5 || swept.bottom > sec.bottom - 0.5 || swept.right > sec.right - 0.5) { note('no slack: would leave its card or the section', { axis, shift }); continue; }
+      const blocked = allInk.filter(({ el, r }) => el !== mover && el !== other && !mover.contains(el) && !el.contains(mover)
+        && Math.min(r.right, swept.right) - Math.max(r.left, swept.left) > 0.5
+        && Math.min(r.bottom, swept.bottom) - Math.max(r.top, swept.top) > 0.5);
+      if (blocked.length) { note('no slack: ink in the way', { axis, shift, blocked: blocked.slice(0, 3).map((x) => x.el.id) }); continue; }
+
+      claimed.add(mover.id);
+      out.push({ id: mover.id, rule: 'overlap', reason: `clear ${(shift - CLEAR).toFixed(1)}px of #${other.id}`, dx: axis === 'x' ? shift : 0, dy: axis === 'y' ? shift : 0 });
+    }
+    window.__protoRuleNotes = (window.__protoRuleNotes || []).concat(notes);
+    return out;
+  };
+}

package/prototype-kit/polish/rules/page-cut.mjs

@@ -0,0 +1,203 @@
+// page-cut: content that has fallen off the state's own canvas (kind 'cut' — text past the section box).
+//
+// Mechanism this repairs (proven on the population): a canonical shell (`[data-proto-shell]`: sidebar, header,
+// footer) is transplanted into a page whose canvas is a different size, but the shell's CHILDREN keep the donor
+// page's absolute `top:` / flow margins. A sidebar footer with `margin-top:88px` inside a 947 px sidebar lands at
+// y=1035 — "Kestrel v2.14.0" floats on white 88 px below the navy rail. A footer legal row with `top:222px`
+// inside a 212 px footer hangs 23 px below the page.
+//
+// Two repairs, chosen by where the culprit lives:
+//   * inside a shell / footer / header / aside / nav → TRANSLATE the whole overhanging block back up (or left)
+//     until its bottom sits at the section bottom minus a small pad, capped by the free space above it, and only
+//     if that lands it on nothing (live overlap check + the driver's harm guard).
+//   * otherwise (a stacked, in-flow marketing page) → EXTEND the section's own height so nothing is cut. The
+//     canvas follows: body/html are sized by the sections, so growing one grows the page (measured, see REPORT).
+// Right/left/top edges are handled the same way by translation when there is slack on the opposite side.
+//
+// Findings under `minCut` (default 4 px) are deliberately left alone: at 1.6–3 px they are line-box overshoot
+// (ascender/descender beyond the declared box) with no visible ink outside the canvas.
+//
+// Fires on: a shell sidebar footer 88 px below the rail; a footer legal row 23 px below a stacked page.
+// Silent on: 2 px line-box overshoot; a hero band that intentionally runs to the canvas edge; anything whose
+//           lift would land on another element.
+export const name = 'page-cut';
+export const maxShift = 128; // honest: this rule moves a stranded footer row / sidebar block by up to ~100 px
+export const params = { minCut: 4, pad: 8, maxLift: 200, minGroupForExtend: 1, roomTolerance: 4 };
+
+export function browserFn() {
+  return ({ metrics, params }) => {
+    const P = Object.assign({ minCut: 4, pad: 8, maxLift: 200, minGroupForExtend: 1, roomTolerance: 4 }, params || {});
+    const secOf = (el) => el.closest('section[id^="viewport-"]') || document.body;
+    const rangeOf = (el) => { const r = document.createRange(); r.selectNodeContents(el); return r; };
+    const trOf = (el) => { const b = rangeOf(el).getBoundingClientRect(); return b.width > 0 ? b : el.getBoundingClientRect(); };
+    const vis = (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') || /^H[1-6]$/.test(el.tagName);
+    const kindOf = (el) => isText(el) ? 'text' : el.classList.contains('icon') ? 'icon' : 'other';
+    const leaves = [...document.querySelectorAll('.text, h1, h2, h3, h4, h5, h6, .icon, img, .image, .badge, .divider')]
+      .filter((el) => vis(el) && !el.closest('#proto-overlay-root') && !el.querySelector('.text'));
+    // count text×text / text×icon collisions between M's subtree and everything else in its section
+    const collisions = (M) => {
+      const sec = secOf(M);
+      const inside = leaves.filter((e) => M.contains(e));
+      const outside = leaves.filter((e) => !M.contains(e) && secOf(e) === sec);
+      let n = 0;
+      for (const A of inside) {
+        const ar = (isText(A) ? trOf(A) : A.getBoundingClientRect());
+        const ka = kindOf(A); if (ka === 'other') continue;
+        for (const B of outside) {
+          const kb = kindOf(B); if (kb === 'other') continue;
+          if (!(ka === 'text' && kb === 'text') && !((ka === 'text') !== (kb === 'text'))) continue;
+          const br = (isText(B) ? trOf(B) : B.getBoundingClientRect());
+          const ix = Math.min(ar.right, br.right) - Math.max(ar.left, br.left);
+          const iy = Math.min(ar.bottom, br.bottom) - Math.max(ar.top, br.top);
+          if (ix > 1 && iy > 3 && ix * iy > 24) n++;
+        }
+      }
+      return n;
+    };
+    const probes = [...document.body.querySelectorAll('[id]')].filter((e) => !e.closest('#proto-overlay-root'));
+    // document coordinates, not viewport: measure.mjs scrolls the page while sampling backgrounds, and
+    // removing an overhang changes the scroll clamp — viewport coords would report the whole page as moved.
+    const snap = () => probes.map((e) => { const r = e.getBoundingClientRect(); return [r.left + window.scrollX, r.top + window.scrollY, r.width, r.height]; });
+    const base = snap();
+    const trial = (el, styles, probe) => {
+      const prev = el.getAttribute('style');
+      for (const k of Object.keys(styles)) el.style.setProperty(k, styles[k], 'important');
+      void document.body.offsetHeight;
+      const out = probe(el);
+      out.now = snap();
+      if (prev === null) el.removeAttribute('style'); else el.setAttribute('style', prev);
+      void document.body.offsetHeight;
+      return out;
+    };
+    // `ignoreAncestors`: a pure transform never reflows anything, but it does change the page's scroll extent,
+    // so the wrappers ABOVE the moved block legitimately shrink. Only translate trials pass this.
+    const disturbedOutside = (el, now, ignoreAncestors) => {
+      for (let i = 0; i < probes.length; i++) {
+        const p = probes[i]; if (p === el || el.contains(p) || (ignoreAncestors && p.contains(el))) continue;
+        const a = base[i], b = now[i];
+        if (!a[2] && !a[3] && !b[2] && !b[3]) continue;  // never-rendered node: its rect is all zeros, ignore
+        if (Math.abs(a[0] - b[0]) > 0.5 || Math.abs(a[1] - b[1]) > 0.5 || Math.abs(a[2] - b[2]) > 0.5 || Math.abs(a[3] - b[3]) > 0.5) return p.id || p.tagName;
+      }
+      return null;
+    };
+    // the real painted extent of a block: its own box unioned with the text rects of the text leaves inside it
+    const inkBounds = (M) => {
+      const r = M.getBoundingClientRect();
+      let o = { left: r.left, top: r.top, right: r.right, bottom: r.bottom };
+      for (const t of leaves) {
+        if (!isText(t) || !M.contains(t)) continue;
+        const q = trOf(t);
+        o = { left: Math.min(o.left, q.left), top: Math.min(o.top, q.top), right: Math.max(o.right, q.right), bottom: Math.max(o.bottom, q.bottom) };
+      }
+      return o;
+    };
+    // free travel for M in one direction inside `stop`: to the nearest blocking edge
+    const gapTo = (M, stop, dir) => {
+      const mr = M.getBoundingClientRect(), sr = stop.getBoundingClientRect(), cs = getComputedStyle(stop);
+      const pad = (k) => parseFloat(cs[k]) || 0;
+      let lim = dir === 'up' ? sr.top + pad('paddingTop') : dir === 'down' ? sr.bottom - pad('paddingBottom')
+        : dir === 'left' ? sr.left + pad('paddingLeft') : sr.right - pad('paddingRight');
+      for (const e of stop.querySelectorAll('*')) {
+        if (e === M || M.contains(e) || e.contains(M) || !vis(e)) continue;
+        const r = e.getBoundingClientRect();
+        if (dir === 'up' || dir === 'down') {
+          if (Math.min(mr.right, r.right) - Math.max(mr.left, r.left) <= 1) continue;
+          if (dir === 'up' && r.bottom <= mr.top + 0.5) lim = Math.max(lim, r.bottom);
+          if (dir === 'down' && r.top >= mr.bottom - 0.5) lim = Math.min(lim, r.top);
+        } else {
+          if (Math.min(mr.bottom, r.bottom) - Math.max(mr.top, r.top) <= 1) continue;
+          if (dir === 'left' && r.right <= mr.left + 0.5) lim = Math.max(lim, r.right);
+          if (dir === 'right' && r.left >= mr.right - 0.5) lim = Math.min(lim, r.left);
+        }
+      }
+      return dir === 'up' ? mr.top - lim : dir === 'down' ? lim - mr.bottom : dir === 'left' ? mr.left - lim : lim - mr.right;
+    };
+
+    const out = [];
+    const done = new Set();
+    const extendBySection = new Map();
+    // every declined finding is recorded on the page so a probe can read WHY (the driver ignores this).
+    const skip = (id, why, detail) => { (window.__polishSkips = window.__polishSkips || []).push(Object.assign({ rule: 'page-cut', id, why }, detail || {})); };
+
+    for (const f of metrics.overflow) {
+      if (f.kind !== 'cut' || f.px < P.minCut) continue;
+      const el = document.getElementById(f.id);
+      if (!el) continue;
+      const sec = secOf(el), sb = sec.getBoundingClientRect(), tr = trOf(el);
+      const over = { bottom: tr.bottom - sb.bottom, right: tr.right - sb.right, top: sb.top - tr.top, left: sb.left - tr.left };
+      const side = Object.keys(over).sort((a, b) => over[b] - over[a])[0];
+      if (over[side] < P.minCut) { skip(f.id, 'recomputes under the threshold (line-box overshoot, no ink outside)', { px: f.px, live: +over[side].toFixed(1), side }); continue; }
+      // the block that actually hangs out: outermost ancestor (still inside the section) over the same edge
+      let M = el, a = el.parentElement;
+      while (a && a !== sec) {
+        const r = a.getBoundingClientRect();
+        const o = side === 'bottom' ? r.bottom - sb.bottom : side === 'right' ? r.right - sb.right : side === 'top' ? sb.top - r.top : sb.left - r.left;
+        if (o >= 1.5) M = a;
+        a = a.parentElement;
+      }
+      if (!M.id) { skip(f.id, 'nothing addressable to move (no id on the overhanging block)', { side }); continue; }
+      if (done.has(M.id)) continue;
+      const shell = M.closest('[data-proto-shell]') || M.closest('footer, header, aside, nav');
+      const stop = shell && shell !== M ? shell : sec;
+
+      if (shell) {
+        // --- translate the stranded block back onto the canvas
+        const mr = inkBounds(M);
+        const overhang = side === 'bottom' ? mr.bottom - sb.bottom : side === 'right' ? mr.right - sb.right
+          : side === 'top' ? sb.top - mr.top : sb.left - mr.left;
+        if (overhang < 1.5 || overhang > P.maxLift) { skip(M.id, 'overhang out of range', { overhang: +overhang.toFixed(1), maxLift: P.maxLift }); continue; }
+        const dir = { bottom: 'up', right: 'left', top: 'down', left: 'right' }[side];
+        const room = gapTo(M, stop, dir);
+        // `room` is a cheap pre-filter; the real guards are the ink-collision count and the disturbance check
+        // below, so allow the block to close the last couple of px of a gap that is exactly its own overhang.
+        if (room < overhang - P.roomTolerance) { skip(M.id, 'no room to move it', { overhang: +overhang.toFixed(1), room: +room.toFixed(1), side, stop: stop.id }); continue; }
+        const pad = Math.min(P.pad, Math.max(0, room - overhang));
+        const move = overhang + pad;                             // always positive, along `dir`
+        const dx = dir === 'left' ? -move : dir === 'right' ? move : 0;
+        const dy = dir === 'up' ? -move : dir === 'down' ? move : 0;
+        const before = collisions(M);
+        const r = trial(M, { transform: `translate(${dx}px,${dy}px)` }, (m) => {
+          const q = inkBounds(m), live = sec.getBoundingClientRect();   // re-read: the page may have scrolled
+          const fixed = side === 'bottom' ? q.bottom <= live.bottom + 0.5 : side === 'right' ? q.right <= live.right + 0.5
+            : side === 'top' ? q.top >= live.top - 0.5 : q.left >= live.left - 0.5;
+          return { fixed, coll: collisions(m) };
+        });
+        r.disturbed = disturbedOutside(M, r.now, true);
+        if (!r.fixed || r.coll > before || r.disturbed) { skip(M.id, 'move would harm', { fixed: r.fixed, collisions: `${before}→${r.coll}`, disturbed: r.disturbed, move: +move.toFixed(1), dir }); continue; }
+        done.add(M.id);
+        out.push({
+          id: M.id, rule: 'page-cut', dx, dy,
+          reason: `${M === el ? 'text' : 'block'} ${overhang.toFixed(1)}px past section ${side} inside ${shell.id || shell.tagName.toLowerCase()} → move ${move.toFixed(1)}px ${dir} (room ${room.toFixed(0)}px)`,
+        });
+      } else if (side === 'bottom') {
+        // --- in-flow page: grow the canvas instead of moving the content
+        const cur = extendBySection.get(sec.id) || { sec, need: 0, ids: [] };
+        cur.need = Math.max(cur.need, over[side]);
+        cur.ids.push(f.id);
+        extendBySection.set(sec.id, cur);
+      }
+    }
+
+    for (const [id, g] of extendBySection) {
+      if (!id || g.ids.length < P.minGroupForExtend) continue;
+      const sb = g.sec.getBoundingClientRect();
+      const h = Math.ceil((sb.height + g.need + P.pad) * 100) / 100;
+      const r = trial(g.sec, { height: h + 'px' }, (s) => ({ ok: s.getBoundingClientRect().height >= h - 0.5 }));
+      // everything inside the section must stay put; sections after it may only translate down by the delta
+      const delta = h - sb.height;
+      let bad = null;
+      for (let i = 0; i < probes.length; i++) {
+        const p = probes[i]; if (p === g.sec || g.sec.contains(p)) continue;
+        const a = base[i], b = r.now[i];
+        const dy = b[1] - a[1];
+        if (Math.abs(b[0] - a[0]) > 0.5 || Math.abs(b[2] - a[2]) > 0.5 || Math.abs(b[3] - a[3]) > 0.5) { bad = p.id; break; }
+        if (Math.abs(dy) > 0.5 && Math.abs(dy - delta) > 0.5) { bad = p.id; break; }
+      }
+      if (!r.ok || bad) { skip(id, 'canvas extend would reflow the page', { ok: r.ok, disturbed: bad, delta: +delta.toFixed(1) }); continue; }
+      out.push({ id, rule: 'page-cut', h, reason: `extend canvas +${delta.toFixed(1)}px so ${g.ids.length} cut item(s) fit (${g.ids[0]})` });
+    }
+
+    return out;
+  };
+}

package/prototype-kit/polish/rules/photo-corners.mjs

@@ -0,0 +1,38 @@
+// photo-corners: a photo that sits flush in the corners of a rounded card paints square pixels over the card's radius.
+// Mechanism (owner r4, Verdant Row product cards): every card declares the same border-radius, the photo child is
+// placed flush at the card's top with radius 0 and the card does not clip — whether the corner LOOKS rounded then
+// depends on pixels baked into each photo raster (4 of 6 rounded, 2 square: a conversion-side inconsistency, routed
+// upstream). The HTML defect is the card whose declared radius its flush child ignores. Fix: give the photo the card's
+// radius on exactly the corners it touches. No pixel is patched; nothing moves.
+export const name = 'photo-corners';
+export const maxShift = 0;
+
+export function browserFn() {
+  return () => {
+    const out = [];
+    const seen = new Set();
+    const visible = (el) => { const s = getComputedStyle(el); if (s.display === 'none' || s.visibility === 'hidden') return false; const r = el.getBoundingClientRect(); return r.width > 0 && r.height > 0; };
+    for (const img of document.querySelectorAll('img, .image, [id$="-photo"]')) {
+      if (!img.id || seen.has(img.id) || !visible(img) || img.closest('#proto-overlay-root, .proto-holding-block')) continue;
+      const ir = img.getBoundingClientRect();
+      const ics = getComputedStyle(img);
+      if (parseFloat(ics.borderTopLeftRadius) > 1 || parseFloat(ics.borderTopRightRadius) > 1) continue; // already rounded
+      // nearest ancestor with a declared radius and no clip
+      let card = img.parentElement;
+      while (card && !(parseFloat(getComputedStyle(card).borderTopLeftRadius) >= 4)) card = card.parentElement;
+      if (!card || !card.id) continue;
+      const ccs = getComputedStyle(card);
+      if (ccs.overflow !== 'visible') continue; // the card clips already
+      const r = parseFloat(ccs.borderTopLeftRadius);
+      const cr = card.getBoundingClientRect();
+      const near = (a, b) => Math.abs(a - b) <= 1.5;
+      const tl = near(ir.left, cr.left) && near(ir.top, cr.top), tr = near(ir.right, cr.right) && near(ir.top, cr.top);
+      const bl = near(ir.left, cr.left) && near(ir.bottom, cr.bottom), br = near(ir.right, cr.right) && near(ir.bottom, cr.bottom);
+      if (!(tl || tr || bl || br)) continue; // an inset, framed photo: design
+      const radius = `${tl ? r : 0}px ${tr ? r : 0}px ${br ? r : 0}px ${bl ? r : 0}px`;
+      seen.add(img.id);
+      out.push({ id: img.id, rule: 'photo-corners', reason: `flush in ${[tl && 'TL', tr && 'TR', br && 'BR', bl && 'BL'].filter(Boolean).join('+')} of #${card.id} (radius ${r}px)`, css: { 'border-radius': radius } });
+    }
+    return out;
+  };
+}

package/prototype-kit/polish/rules/rhythm.mjs

@@ -0,0 +1,148 @@
+// rhythm: make the whitespace inside a parent regular.
+//
+// Mechanism the population showed: a transplanted/assembled parent ends up with stacked same-kind children whose
+// gaps differ by a hair — sidebar nav items at 40.47 / 41.97 px, alert rows at 29.7 / 25.6. Nothing is broken, the
+// page just reads "hand-placed". measure.mjs flags every PAIR of gaps under one parent that differ by 0.75..6 px,
+// so a parent with n gaps produces up to n*(n-1)/2 findings — the fix has to make ALL of a parent's gaps equal,
+// not just the ones inside one contiguous run.
+//
+// Rule: per parent, collect the gaps between consecutive same-kind stacked (or side-by-side) children. If there are
+// ≥2 gaps and every gap is within ±6 px of the parent's median gap, snap them all to that median: each contiguous
+// run gets cumulative dy (dx) translates, the run's first child never moves, and a run is skipped if its last child
+// would move more than 6 px or would leave the parent's content box. A gap further than +6 px from the median is a
+// deliberate step (a section break), and its presence makes the whole parent ineligible — we never flatten design.
+//
+// Plus card grids: a run of ≥3 same-kind sibling BOXES whose widths (vertical run) or heights (horizontal run)
+// differ by ≤4 px is snapped to the widest/tallest of the cluster. Growing, never shrinking: shrinking a card can
+// re-wrap its text and invent new spill, growing cannot. The axis is chosen so the size change cannot disturb the
+// flow of the siblings (width in a column, height in a row), and the grown strip must be empty.
+export const name = 'rhythm';
+export const maxShift = 6;
+
+export function browserFn() {
+  return () => {
+    const NEAR = 6, EXACT = 0.75, CARD_SPREAD = 4;
+    const out = [];
+    const cs = (el) => getComputedStyle(el);
+    const visible = (el) => {
+      const s = cs(el);
+      if (s.display === 'none' || s.visibility === 'hidden' || parseFloat(s.opacity) === 0) return false;
+      const r = el.getBoundingClientRect();
+      return r.width > 0 && r.height > 0;
+    };
+    const isText = (el) => el.classList.contains('text') || /^H[1-6]$/.test(el.tagName);
+    const kindOf = (el) => isText(el) ? 'text'
+      : el.classList.contains('icon') ? 'icon'
+      : (el.tagName === 'IMG' || el.classList.contains('image')) ? 'image'
+      : el.classList.contains('badge') ? 'badge'
+      : el.classList.contains('divider') ? 'divider' : 'box';
+    // measure.mjs's notion of "same kind": same kind tag, and for text the same font size + line height,
+    // for boxes a matching width or height, otherwise a matching height.
+    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(cs(A.el).fontSize) - parseFloat(cs(B.el).fontSize)) < 1 && Math.abs(A.r.height - B.r.height) < 3;
+      if (ka === 'box') return Math.abs(A.r.height - B.r.height) <= 4 || Math.abs(A.r.width - B.r.width) <= 4;
+      return Math.abs(A.r.height - B.r.height) < 3;
+    };
+    const LEAF = '.text, h1, h2, h3, h4, h5, h6, .icon, img, .image, .badge, .divider';
+    const CONTAINER = 'div[id], button[id], aside[id], header[id], footer[id], nav[id], article[id], form[id], main[id]';
+    const candidate = (el) => el.id && !el.classList.contains('decoration') && !el.closest('#proto-overlay-root')
+      && ((el.matches(LEAF) && !el.querySelector('.text')) || el.matches(CONTAINER)) && visible(el);
+    const median = (xs) => [...xs].sort((a, b) => a - b)[Math.floor((xs.length - 1) / 2)];
+    const contentBox = (p) => {
+      const r = p.getBoundingClientRect(), s = cs(p);
+      return {
+        left: r.left + parseFloat(s.paddingLeft) + parseFloat(s.borderLeftWidth),
+        right: r.right - parseFloat(s.paddingRight) - parseFloat(s.borderRightWidth),
+        top: r.top + parseFloat(s.paddingTop) + parseFloat(s.borderTopWidth),
+        bottom: r.bottom - parseFloat(s.paddingBottom) - parseFloat(s.borderBottomWidth),
+      };
+    };
+    const allBoxes = [...document.querySelectorAll('*')].filter((el) => !el.closest('#proto-overlay-root') && visible(el)).map((el) => ({ el, r: el.getBoundingClientRect() }));
+
+    const parents = new Set();
+    for (const el of document.querySelectorAll(`${LEAF}, ${CONTAINER}`)) if (candidate(el) && el.parentElement) parents.add(el.parentElement);
+
+    for (const p of parents) {
+      const kids = [...p.children].filter(candidate).map((el) => ({ el, r: el.getBoundingClientRect() }));
+      if (kids.length < 3) continue;
+      for (const axis of ['y', 'x']) {
+        const ks = [...kids].sort((a, b) => axis === 'y' ? a.r.top - b.r.top : a.r.left - b.r.left);
+        // gaps between consecutive same-kind children that really are stacked / side by side (they must overlap
+        // on the cross axis, or they are not part of one column/row).
+        const gaps = [];
+        for (let i = 1; i < ks.length; i++) {
+          const prev = ks[i - 1], cur = ks[i];
+          if (!sameKind(prev, cur)) { gaps.push(null); continue; }
+          const inLine = axis === 'y'
+            ? prev.r.bottom <= cur.r.top + 1 && Math.min(prev.r.right, cur.r.right) - Math.max(prev.r.left, cur.r.left) > 0
+            : prev.r.right <= cur.r.left + 1 && Math.min(prev.r.bottom, cur.r.bottom) - Math.max(prev.r.top, cur.r.top) > 0;
+          gaps.push(inLine ? (axis === 'y' ? cur.r.top - prev.r.bottom : cur.r.left - prev.r.right) : null);
+        }
+        const real = gaps.filter((g) => g != null);
+        if (real.length < 2) continue;
+        const target = median(real);
+        //  a gap further than NEAR from the median is a deliberate step (a section break) → never flatten it;
+        //  a parent whose gaps are already equal has nothing to snap. Card equalisation is independent of both.
+        const snappable = !real.some((g) => Math.abs(g - target) > NEAR) && real.some((g) => Math.abs(g - target) > EXACT);
+
+        // contiguous runs of linked children; first child of each run is the anchor and never moves
+        let i = 0;
+        while (i < gaps.length) {
+          if (gaps[i] == null) { i++; continue; }
+          let j = i; while (j < gaps.length && gaps[j] != null) j++;       // run covers ks[i .. j]
+          const moves = [];
+          let acc = 0;
+          for (let k = i; k < j; k++) { acc += target - gaps[k]; moves.push({ node: ks[k + 1], d: acc }); }
+          const maxMove = Math.max(...moves.map((m) => Math.abs(m.d)));
+          const box = contentBox(p);
+          const last = moves[moves.length - 1];
+          const lastEdge = axis === 'y' ? last.node.r.bottom + last.d : last.node.r.right + last.d;
+          const limit = axis === 'y' ? box.bottom : box.right;
+          if (snappable && maxMove <= NEAR && lastEdge <= limit + 0.5) {
+            for (const m of moves) {
+              if (Math.abs(m.d) < 0.25) continue;
+              out.push({
+                id: m.node.el.id, rule: 'rhythm',
+                reason: `${axis === 'y' ? 'gap' : 'hgap'} →${target.toFixed(2)} in #${p.id || p.tagName.toLowerCase()}`,
+                dx: axis === 'x' ? +m.d.toFixed(2) : 0, dy: axis === 'y' ? +m.d.toFixed(2) : 0,
+              });
+            }
+          }
+          // card grid: equalise the cross-axis size of a run of ≥3 same-kind boxes (grow only)
+          const run = ks.slice(i, j + 1);
+          // measure.mjs compares edges between ANY two same-kind children of a parent, not just the ones in one
+          // run. Equalising part of a row therefore invents a new edge near-miss against a same-kind child the run
+          // left out (review-invoice: a narrow "More" tab is same-kind-by-width with "Home" but same-kind-by-height
+          // with nothing). So: equalise the whole family or none of it.
+          const outsiders = kids.filter((k) => !run.includes(k) && run.some((n) => sameKind(n, k)));
+          if (run.length >= 3 && !outsiders.length && run.every((n) => kindOf(n.el) === 'box')) {
+            const prop = axis === 'y' ? 'width' : 'height';
+            const sizes = run.map((n) => n.r[prop]);
+            const lo = Math.min(...sizes), hi = Math.max(...sizes);
+            if (hi - lo > EXACT && hi - lo <= CARD_SPREAD) {
+              for (const n of run) {
+                const grow = hi - n.r[prop];
+                if (grow < 0.25) continue;
+                // the grown strip must be empty and must stay inside the parent's content box
+                const box2 = contentBox(p);
+                const strip = axis === 'y'
+                  ? { left: n.r.right, right: n.r.right + grow, top: n.r.top, bottom: n.r.bottom }
+                  : { left: n.r.left, right: n.r.right, top: n.r.bottom, bottom: n.r.bottom + grow };
+                if (axis === 'y' ? strip.right > box2.right + 0.5 : strip.bottom > box2.bottom + 0.5) continue;
+                const blocked = allBoxes.some(({ el, r }) => el !== n.el && !n.el.contains(el) && !el.contains(n.el)
+                  && Math.min(r.right, strip.right) - Math.max(r.left, strip.left) > 0.5
+                  && Math.min(r.bottom, strip.bottom) - Math.max(r.top, strip.top) > 0.5);
+                if (blocked) continue;
+                out.push({ id: n.el.id, rule: 'rhythm', reason: `card ${prop} ${n.r[prop].toFixed(2)}→${hi.toFixed(2)}`, [axis === 'y' ? 'w' : 'h']: +hi.toFixed(2) });
+              }
+            }
+          }
+          i = j + 1;
+        }
+      }
+    }
+    return out;
+  };
+}