@12ui/design 0.2.44 → 0.2.45

package/prototype-kit/polish/report.mjs

@@ -0,0 +1,76 @@
+// Durable, machine-readable outcome vocabulary for the opt-in polish stage.
+// A page/rule pair has exactly one terminal state:
+// - fired: at least one override from the rule survived every guard;
+// - silent: the rule proposed no change;
+// - reverted: the rule proposed a change but none survived, or the page was
+//   published unchanged after a rule/page error.
+
+const unique = (values) => [...new Set(values)];
+
+export function pageRuleRecords(page, ruleNames) {
+  const accepted = new Map((page.accepted || []).map((entry) => [entry.rule, entry]));
+  const rejected = new Map();
+  for (const entry of page.rejected || []) {
+    const reasons = rejected.get(entry.rule) || [];
+    reasons.push(...(entry.harm || []));
+    rejected.set(entry.rule, reasons);
+  }
+
+  return ruleNames.map((rule) => {
+    const measured = page.rules?.[rule] || {};
+    const proposed = Number.isFinite(measured.proposed) ? measured.proposed : 0;
+    const overCap = Number.isFinite(measured.overCap) ? measured.overCap : 0;
+    const kept = accepted.get(rule)?.overrides || 0;
+    const reasons = [
+      ...(rejected.get(rule) || []),
+      ...(overCap > 0 ? ['over-cap'] : []),
+      ...(page.error && measured.proposed === undefined ? ['page-error'] : []),
+    ];
+    const status = kept > 0
+      ? 'fired'
+      : proposed > 0 || reasons.length > 0
+        ? 'reverted'
+        : 'silent';
+    return {
+      rule,
+      status,
+      proposed,
+      accepted: kept,
+      overCap,
+      ...(reasons.length > 0 ? { reasons: unique(reasons) } : {}),
+    };
+  });
+}
+
+export function summarizePolishReport(report) {
+  const rules = report.rules.map((name) => ({
+    name,
+    fired: 0,
+    silent: 0,
+    reverted: 0,
+    proposed: 0,
+    accepted: 0,
+    overCap: 0,
+  }));
+  const byName = new Map(rules.map((rule) => [rule.name, rule]));
+  for (const page of report.pages) {
+    for (const record of page.ruleRecords || []) {
+      const rule = byName.get(record.rule);
+      if (!rule) continue;
+      rule[record.status] += 1;
+      rule.proposed += record.proposed;
+      rule.accepted += record.accepted;
+      rule.overCap += record.overCap;
+    }
+  }
+  return {
+    enabled: true,
+    policy: report.policy,
+    pageCount: report.pages.length,
+    pageErrors: report.pages.filter((page) => page.error).length,
+    fired: rules.reduce((count, rule) => count + rule.fired, 0),
+    silent: rules.reduce((count, rule) => count + rule.silent, 0),
+    reverted: rules.reduce((count, rule) => count + rule.reverted, 0),
+    rules,
+  };
+}

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

@@ -0,0 +1,70 @@
+// align: snap near-miss edges between same-kind siblings (≤ NEAR px apart) onto the group's modal edge.
+// Fires on: three cards whose tops are 0, 1.02 and 2.05 px → the two strays move to 0.
+// Silent on: edges that are equal, or further apart than NEAR (deliberate offsets), or different kinds.
+export const name = 'align';
+export const maxShift = 6;
+
+export function browserFn() {
+  return ({ metrics }) => {
+    const groups = new Map(); // parent|axis → [{id, value}]
+    const axisOf = { left: 'x', right: 'r', top: 'y', bottom: 'b', center: 'cy' };
+    const rectOf = (el) => { const r = el.getBoundingClientRect(); const s = el.closest('section[id^="viewport-"]') || document.body; const b = s.getBoundingClientRect(); return { x: r.left - b.left, y: r.top - b.top, r: r.right - b.left, b: r.bottom - b.top, cy: r.top - b.top + r.height / 2 }; };
+    // an element that already belongs to a left (top) column is left-aligned by design: never snap its RIGHT (bottom)
+    // edge — that is what moved the Lands "Proposals" nav item 5 px out of its icon column (owner, 2026-08-22)
+    const leftAligned = new Set(), topAligned = new Set();
+    for (const c of metrics.columns || []) { (c.axis === 'left' ? leftAligned : topAligned).add(c.a); (c.axis === 'left' ? leftAligned : topAligned).add(c.b); }
+    for (const pr of metrics.alignment) { if (pr.axis === 'left') { leftAligned.add(pr.a); leftAligned.add(pr.b); } if (pr.axis === 'top') { topAligned.add(pr.a); topAligned.add(pr.b); } }
+    for (const pair of metrics.alignment) {
+      const a = document.getElementById(pair.a), b = document.getElementById(pair.b);
+      if (!a || !b || a.parentElement !== b.parentElement) continue;
+      if (pair.axis === 'right' && (leftAligned.has(pair.a) || leftAligned.has(pair.b))) continue;
+      if (pair.axis === 'bottom' && (topAligned.has(pair.a) || topAligned.has(pair.b))) continue;
+      const key = `${a.parentElement.id || 'root'}|${pair.axis}`;
+      if (!groups.has(key)) groups.set(key, new Map());
+      const g = groups.get(key);
+      const k = axisOf[pair.axis];
+      if (!g.has(pair.a)) g.set(pair.a, rectOf(a)[k]);
+      if (!g.has(pair.b)) g.set(pair.b, rectOf(b)[k]);
+    }
+    // the eye aligns INK, not boxes: if an element's text/icon leaves already sit in an exact column with leaves
+    // outside it, moving the element would break that column (Lands nav rows are 1 px apart while their labels and
+    // icons line up perfectly) — leave it
+    const colPartners = new Map();
+    for (const c of metrics.columns || []) { if (!colPartners.has(c.a)) colPartners.set(c.a, []); colPartners.get(c.a).push(c.b); if (!colPartners.has(c.b)) colPartners.set(c.b, []); colPartners.get(c.b).push(c.a); }
+    const breaksColumn = (el, axis) => {
+      const leaves = [el, ...el.querySelectorAll('.text, .paragraph, .icon, h1, h2, h3, h4, h5, h6')].filter((l) => l.id);
+      const wantAxis = (axis === 'left' || axis === 'right') ? 'left' : 'top';
+      for (const l of leaves) for (const partner of colPartners.get(l.id) || []) {
+        const pe = document.getElementById(partner); if (!pe || el.contains(pe)) continue;
+        const c = (metrics.columns || []).find((x) => (x.a === l.id && x.b === partner) || (x.b === l.id && x.a === partner));
+        if (c && c.axis === wantAxis) return true;
+      }
+      return false;
+    };
+    const out = [];
+    for (const [key, g] of groups) {
+      const axis = key.split('|')[1];
+      // cluster values within NEAR; anchor = the value shared by most members (ties → smallest)
+      const entries = [...g.entries()].sort((p, q) => p[1] - q[1]);
+      let i = 0;
+      while (i < entries.length) {
+        let j = i; while (j + 1 < entries.length && entries[j + 1][1] - entries[i][1] <= 6) j++;
+        const cluster = entries.slice(i, j + 1);
+        if (cluster.length >= 2) {
+          const counts = new Map();
+          for (const [, v] of cluster) { const kv = Math.round(v * 4) / 4; counts.set(kv, (counts.get(kv) || 0) + 1); }
+          const anchor = [...counts.entries()].sort((p, q) => q[1] - p[1] || p[0] - q[0])[0][0];
+          for (const [id, v] of cluster) {
+            const d = anchor - v;
+            if (Math.abs(d) < 0.5 || Math.abs(d) > 6) continue;
+            if (breaksColumn(document.getElementById(id), axis)) continue;
+            const horizontal = axis === 'left' || axis === 'right';
+            out.push({ id, rule: 'align', reason: `${axis} ${v.toFixed(1)}→${anchor}`, dx: horizontal ? d : 0, dy: horizontal ? 0 : d });
+          }
+        }
+        i = j + 1;
+      }
+    }
+    return out;
+  };
+}

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

@@ -0,0 +1,80 @@
+// contrast: text painted in (almost) the colour of what is under it is text the reader cannot see.
+// Mechanism (missing-text lane, 18 of 250 holding pages): build.mjs copies the heading colour of the base state's
+// largest text onto the holding block without checking the background the block actually lands on — a light
+// hero heading becomes rgb(247,248,248) on a white page (1.06:1). Real pages are clean (0 invisible leaves on
+// 249 pages once the paint-stack probe was fixed), so this rule mostly fires on holdings.
+// Fix (refined 2026-08-23, owner D1 forensics: the rule was flattening conversion-declared brand colours — Lanternfund's
+// #e68000 — to near-black): for a text leaf under MIN contrast, KEEP ITS HUE AND SATURATION and move its lightness
+// toward the background's opposite side until TARGET (4.5:1) is reached — or at least MIN (3:1) — within a lightness
+// floor/ceiling that keeps the colour a colour. Only when neither direction can reach MIN does it fall back to the
+// page's heading/body token or black/white, and the reason records 'hue unreachable'. Never touches image-backed text.
+export const name = 'contrast';
+export const maxShift = 0;
+export const phase = 'post'; // colour decisions need the geometry-polished DOM: evaluate after the geometry rules
+export const params = { MIN: 3, TARGET: 4.5, L_FLOOR: 0.16, L_CEIL: 0.88 };
+
+export function browserFn() {
+  return ({ params }) => {
+    const MIN = params.MIN || 3;
+    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); };
+    const contrast = (a, b) => { const l1 = lum(a), l2 = lum(b); return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05); };
+    const bgUnder = (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 === el || e.closest('.proto-notice, #proto-overlay-root, .proto-toast')) continue;
+        if (e.tagName === 'IMG' || e.tagName === 'svg' || e.tagName === 'CANVAS' || getComputedStyle(e).backgroundImage !== 'none') return null;
+        const c = parseRgb(getComputedStyle(e).backgroundColor); if (c && c.a > 0.5) return c;
+      }
+      return { r: 255, g: 255, b: 255, a: 1 };
+    };
+    let tokens = {};
+    try { tokens = JSON.parse(document.getElementById('proto-state').textContent).tokens || {}; } catch (e) { /* no state block */ }
+    const candidates = (bg) => [tokens.headingColor, tokens.bodyColor, lum(bg) > 0.4 ? 'rgb(20, 20, 20)' : 'rgb(245, 245, 245)'].filter(Boolean).map((c) => ({ css: c, rgb: parseRgb(c) })).filter((c) => c.rgb);
+    // ---- hue-preserving search
+    const rgb2hsl = ({ r, g, b }) => { r /= 255; g /= 255; b /= 255; const mx = Math.max(r, g, b), mn = Math.min(r, g, b); let h = 0, s = 0; const l = (mx + mn) / 2; if (mx !== mn) { const d = mx - mn; s = l > 0.5 ? d / (2 - mx - mn) : d / (mx + mn); h = mx === r ? ((g - b) / d + (g < b ? 6 : 0)) : mx === g ? ((b - r) / d + 2) : ((r - g) / d + 4); h /= 6; } return { h, s, l }; };
+    const hsl2rgb = ({ h, s, l }) => { const k = (n) => (n + h * 12) % 12; const a = s * Math.min(l, 1 - l); const f = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1))); return { r: Math.round(f(0) * 255), g: Math.round(f(8) * 255), b: Math.round(f(4) * 255), a: 1 }; };
+    const huePreserving = (fg, bg) => {
+      const hs = rgb2hsl(fg); const h = hs.h, s = hs.s < 0.08 ? 0 : hs.s; // a near-neutral stays neutral: no invented tint
+      const darkBg = lum(bg) <= 0.4;
+      // walk lightness away from the background in 1 % steps; first L that reaches TARGET wins, else the first that reaches MIN
+      const P_MIN = params.MIN || 3, P_TGT = params.TARGET || 4.5, FLOOR = params.L_FLOOR ?? 0.16, CEIL = params.L_CEIL ?? 0.88;
+      let best = null;
+      const start = rgb2hsl(fg).l;
+      const dir = darkBg ? +1 : -1;
+      for (let l = start; dir > 0 ? l <= CEIL : l >= FLOOR; l += dir * 0.01) {
+        const c = hsl2rgb({ h, s, l }); const k = contrast(c, bg);
+        if (k >= P_TGT) return { rgb: c, contrast: k, reached: 'target' };
+        if (k >= P_MIN && !best) best = { rgb: c, contrast: k, reached: 'min' };
+      }
+      return best; // null = hue unreachable within the lightness band
+    };
+    const out = [];
+    const seen = new Set();
+    const nodes = [...document.querySelectorAll('.text, .paragraph, h1, h2, h3, h4, h5, h6, .proto-holding-title, .proto-holding-sub, .proto-holding-note, .proto-holding-card-title')]
+      .filter((el) => !el.closest('#proto-overlay-root') && (el.textContent || '').trim() && !el.querySelector('.text'));
+    for (const el of nodes) {
+      const cs = getComputedStyle(el);
+      if (cs.display === 'none' || cs.visibility === 'hidden' || parseFloat(cs.opacity) === 0) continue;
+      const r = el.getBoundingClientRect(); if (!r.width || !r.height) continue;
+      const fg = parseRgb(cs.color); if (!fg || fg.a < 0.05) continue;
+      const bg = bgUnder(el); if (!bg) continue;
+      const c = contrast(fg, bg); if (c >= MIN) continue;
+      const target = el.id ? { id: el.id } : { sel: `${el.tagName.toLowerCase()}.${[...el.classList].join('.')}` };
+      const key = target.id || target.sel; if (seen.has(key)) continue; seen.add(key);
+      const hp = huePreserving(fg, bg);
+      if (hp) {
+        const css = `rgb(${hp.rgb.r}, ${hp.rgb.g}, ${hp.rgb.b})`;
+        const hue = Math.round(rgb2hsl(fg).h * 360);
+        out.push({ ...target, rule: 'contrast', reason: `${c.toFixed(2)}:1 → ${css} (hue ${hue}° kept, ${hp.contrast.toFixed(2)}:1${hp.reached === 'min' ? ', target 4.5 not reachable in hue' : ''})`, css: { color: css } });
+        continue;
+      }
+      const pick = candidates(bg).find((k) => contrast(k.rgb, bg) >= 4.5) || candidates(bg).sort((p, q) => contrast(q.rgb, bg) - contrast(p.rgb, bg))[0];
+      if (!pick) continue;
+      out.push({ ...target, rule: 'contrast', reason: `${c.toFixed(2)}:1 → ${pick.css} (hue unreachable: no lightness in [${(params.L_FLOOR ?? 0.16) * 100}%, ${(params.L_CEIL ?? 0.88) * 100}%] reaches ${params.MIN || 3}:1 on this background; fallback)`, css: { color: pick.css } });
+    }
+    return out;
+  };
+}

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

@@ -0,0 +1,192 @@
+// escape: text that has left the opaque box it belongs to (card, pill, rail, header band).
+//
+// Mechanism this repairs (proven on the population): the same shell-transplant/measured-box mismatch as page-cut,
+// but bounded by a painted container rather than by the canvas. A search pill keeps the donor page's
+// `top:` inside a canonical header that is 58 px tall, so "⌘ K" is painted 17 px below the navy band; a footer
+// legal row sits 8 px under the footer's dark plate; a nav label is 2 px wider than its pill.
+//
+// Ladder: grow the container (only when its own parent has that slack and growing it disturbs nothing) →
+// translate the escaping block back inside (only when the container has room on the other side and the landing
+// spot is empty) → shrink the text by at most 6 % (only when fit-text is not already handling that string).
+// Elements that are ALSO cut by the canvas are left to page-cut, so the two rules never translate the same id twice.
+//
+// Fires on: "⌘ K" 17 px under its header band; a legal row 8 px below the footer plate; a 3 px-wide label bleed
+//           out of a card that has free space beside it.
+// Silent on: escapes under 2 px; a heading intentionally overhanging a photo panel with no slack anywhere;
+//           text already owned by page-cut.
+export const name = 'escape';
+export const maxShift = 64;
+export const params = { minEscape: 2, pad: 4, maxMove: 120, maxFontShrink: 0.06, cutOwnedAt: 4 };
+
+export function browserFn() {
+  return ({ metrics, params }) => {
+    const P = Object.assign({ minEscape: 2, pad: 4, maxMove: 120, maxFontShrink: 0.06, cutOwnedAt: 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 nLines = (el) => { const rs = [...rangeOf(el).getClientRects()].filter((r) => r.width > 0.5 && r.height > 0.5); return Math.max(1, rs.length); };
+    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'));
+    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;
+    };
+    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 ka = kindOf(A); if (ka === 'other') continue;
+        const ar = isText(A) ? trOf(A) : A.getBoundingClientRect();
+        for (const B of outside) {
+          const kb = kindOf(B); if (kb === 'other') continue;
+          if (ka === 'icon' && kb === 'icon') 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;
+    };
+    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 ownedByCut = new Set(metrics.overflow.filter((o) => o.kind === 'cut' && o.px >= P.cutOwnedAt).map((o) => o.id));
+    const bigSpill = new Set(metrics.overflow.filter((o) => o.kind === 'spill' && o.px >= 4).map((o) => o.id));
+    const out = [];
+    const done = new Set();
+    // 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: 'escape', id, why }, detail || {})); };
+
+    for (const f of metrics.overflow) {
+      if (f.kind !== 'escape' || f.px < P.minEscape) continue;
+      if (ownedByCut.has(f.id)) { skip(f.id, 'owned by page-cut (also off the canvas)', { px: f.px }); continue; }
+      const el = document.getElementById(f.id);
+      const C = f.container ? document.getElementById(f.container) : null;
+      if (!el || !C || !C.contains(el)) continue;
+      const tr = trOf(el), cr = C.getBoundingClientRect();
+      const over = { right: tr.right - cr.right, bottom: tr.bottom - cr.bottom, left: cr.left - tr.left, top: cr.top - tr.top };
+      const side = Object.keys(over).sort((a, b) => over[b] - over[a])[0];
+      const need = over[side];
+      if (need < P.minEscape) continue;
+      // the block that actually sticks out of C
+      let M = el, a = el.parentElement;
+      while (a && a !== C) {
+        const r = a.getBoundingClientRect();
+        const o = side === 'right' ? r.right - cr.right : side === 'bottom' ? r.bottom - cr.bottom : side === 'left' ? cr.left - r.left : cr.top - r.top;
+        if (o >= 1.5) M = a;
+        a = a.parentElement;
+      }
+      const key = M.id || f.id;
+      if (done.has(key)) continue;
+      let chosen = null;
+
+      // 1. grow the container, if its own parent leaves that room and nothing else moves
+      if (!chosen && (side === 'right' || side === 'bottom') && C.id && !C.hasAttribute('data-proto-shell') && C.parentElement) {
+        const dir = side === 'right' ? 'right' : 'down';
+        if (gapTo(C, C.parentElement, dir) >= need + P.pad) {
+          const prop = side === 'right' ? 'width' : 'height';
+          const v = Math.ceil((( side === 'right' ? cr.width : cr.height) + need + P.pad) * 100) / 100;
+          const r = trial(C, { [prop]: v + 'px' }, (c) => {
+            const q = c.getBoundingClientRect(), t = trOf(el);
+            return { ok: side === 'right' ? t.right <= q.right + 0.5 : t.bottom <= q.bottom + 0.5 };
+          });
+          if (r.ok && !disturbedOutside(C, r.now)) chosen = { id: C.id, [prop === 'width' ? 'w' : 'h']: v, reason: `grow ${C.id} ${prop} +${(need + P.pad).toFixed(1)}px so ${f.id} fits (free space in parent)` };
+        }
+      }
+      // 2. translate the escaping block back inside
+      if (!chosen && M.id) {
+        const dir = { right: 'left', bottom: 'up', left: 'right', top: 'down' }[side];
+        const mr = inkBounds(M);
+        const mNeed = side === 'right' ? mr.right - cr.right : side === 'bottom' ? mr.bottom - cr.bottom : side === 'left' ? cr.left - mr.left : cr.top - mr.top;
+        const room = gapTo(M, C, dir);
+        if (mNeed >= 1 && mNeed <= P.maxMove && room >= mNeed + 1) {
+          const pad = Math.min(P.pad, Math.max(0, room - mNeed));
+          const move = mNeed + pad;
+          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 = C.getBoundingClientRect();   // re-read: the page may have scrolled
+            const ok = side === 'right' ? q.right <= live.right + 0.5 : side === 'bottom' ? q.bottom <= live.bottom + 0.5
+              : side === 'left' ? q.left >= live.left - 0.5 : q.top >= live.top - 0.5;
+            return { ok, coll: collisions(m) };
+          });
+          if (r.ok && r.coll <= before && !disturbedOutside(M, r.now, true)) {
+            chosen = { id: M.id, dx, dy, reason: `${M === el ? 'text' : 'block'} ${mNeed.toFixed(1)}px outside ${C.id} → move ${move.toFixed(1)}px ${dir} (room ${room.toFixed(0)}px)` };
+          }
+        }
+      }
+      // 3. last resort: shrink the string's type, unless fit-text already owns it
+      if (!chosen && (side === 'right' || side === 'left') && !(bigSpill.has(f.id) && nLines(el) === 1)) {
+        const fs = parseFloat(getComputedStyle(el).fontSize) || 16;
+        for (let i = 1; i <= Math.round(P.maxFontShrink * 100); i++) {
+          const v = (fs * (1 - i / 100)).toFixed(2) + 'px';
+          const r = trial(el, { 'font-size': v }, () => {
+            const t = trOf(el), q = C.getBoundingClientRect();
+            return { ok: side === 'right' ? t.right <= q.right + 0.5 : t.left >= q.left - 0.5 };
+          });
+          if (r.ok && !disturbedOutside(el, r.now)) { chosen = { id: f.id, css: { 'font-size': v }, reason: `font -${i}% so ${f.id} stays inside ${C.id}` }; break; }
+        }
+      }
+      if (chosen) { done.add(key); out.push(Object.assign({ rule: 'escape' }, chosen)); }
+      else skip(f.id, 'no grow / move / shrink fits', { px: +need.toFixed(1), side, container: C.id, block: M.id });
+    }
+    return out;
+  };
+}

package/prototype-kit/polish/rules/fit-text.mjs

@@ -0,0 +1,158 @@
+// fit-text: make a text leaf fit the box the design measured for it.
+//
+// Mechanism this repairs (proven on the population): every element carries a px width/height copied from the
+// design measurement, and every text leaf renders with `white-space:pre`. When the runtime font is a hair wider
+// than the design font the line box is wider than the declared box ("spill"). The box is what the rest of the
+// layout is aligned to, so the label drifts out of its column / card / pill.
+//
+// Ladder, in order, first one that provably works wins (every step is TRIED in the live DOM and reverted):
+//   1. free space on the overflow side (parent content edge, and the nearest sibling that vertically overlaps)
+//      >= spill + sidePad → LEAVE IT. The label renders into empty canvas; nothing is clipped, covered or
+//      collided with, so there is nothing to repair. (Widening `w` to swallow the spill was tried and dropped:
+//      measured on two real pages, 17 widen overrides changed 0 pixels — `white-space:pre` text is painted from
+//      the start edge whatever the declared width — while moving the box centre enough that measure.mjs's
+//      `shift` metric tripped the driver's harm guard and threw away the real repairs on 113 of 249 pages.)
+//   2. tighten letter-spacing, down to -0.02em.
+//   3. reduce font-size, by at most 6 %.
+//   4. both at their caps.
+//   5. give up — the string itself is too long; that is the text lane's job, not geometry's.
+// Multi-line text that is CLIPPED vertically: grow the clipping ancestor's height, but only when doing so
+// moves nothing else (i.e. it has real slack below).
+//
+// Fires on: a 6 px spill fixable by tracking; a 9 px spill needing a 4 % font trim; a clipped wrapped
+//           paragraph inside a card with slack below it.
+// Silent on: spill under 4 px; a label spilling into 450 px of open space beside it; a display heading
+//           deliberately bleeding out of its column on BOTH sides (over an image); a badge whose text fills it
+//           exactly; anything wrapping (no white-space changes).
+export const name = 'fit-text';
+export const maxShift = 2; // this rule never translates; the cap covers sub-pixel reflow only
+export const params = { minSpill: 4, maxLetterSpacingEm: 0.02, maxFontShrink: 0.06, sidePad: 4, bleedBothSides: 2 };
+
+export function browserFn() {
+  return ({ metrics, params }) => {
+    const P = Object.assign({ minSpill: 4, maxLetterSpacingEm: 0.02, maxFontShrink: 0.06, sidePad: 4, bleedBothSides: 2 }, 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 nLines = (el) => { const rs = [...rangeOf(el).getClientRects()].filter((r) => r.width > 0.5 && r.height > 0.5); return Math.max(1, rs.length); };
+    const spillOf = (el) => { const er = el.getBoundingClientRect(), tr = trOf(el); return Math.max(tr.right - er.right, er.left - tr.left); };
+
+    // --- movement probe: every id'd element's rect, so a trial that disturbs the page can be rejected outright
+    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 disturbed = (el) => {
+      const now = snap();
+      for (let i = 0; i < probes.length; i++) {
+        const p = probes[i]; if (p === el || el.contains(p)) 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;
+    };
+    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.moved = disturbed(el);
+      if (prev === null) el.removeAttribute('style'); else el.setAttribute('style', prev);
+      void document.body.offsetHeight;
+      return out;
+    };
+
+    const freeOn = (el, side) => {
+      const er = el.getBoundingClientRect(), p = el.parentElement;
+      if (!p) return 0;
+      const pr = p.getBoundingClientRect(), pcs = getComputedStyle(p);
+      let limit = side === 'right'
+        ? pr.right - (parseFloat(pcs.paddingRight) || 0) - (parseFloat(pcs.borderRightWidth) || 0)
+        : pr.left + (parseFloat(pcs.paddingLeft) || 0) + (parseFloat(pcs.borderLeftWidth) || 0);
+      for (const sib of p.children) {
+        if (sib === el) continue;
+        const sr = sib.getBoundingClientRect();
+        if (sr.width < 0.5 || sr.height < 0.5) continue;
+        if (Math.min(er.bottom, sr.bottom) - Math.max(er.top, sr.top) <= 1) continue;
+        if (side === 'right' && sr.left >= er.right - 0.5) limit = Math.min(limit, sr.left);
+        if (side === 'left' && sr.right <= er.left + 0.5) limit = Math.max(limit, sr.right);
+      }
+      return side === 'right' ? limit - er.right : er.left - limit;
+    };
+
+    const out = [];
+    const seen = new Set();
+
+    // ---------- horizontal spill on single-line text
+    for (const f of metrics.overflow) {
+      if (f.kind !== 'spill' || f.px < P.minSpill || seen.has(f.id)) continue;
+      const el = document.getElementById(f.id);
+      if (!el) continue;
+      const need = spillOf(el);
+      if (need < P.minSpill) continue;                       // stale finding
+      if (nLines(el) !== 1) continue;                        // wrapped/multi-line: never touched here
+      const er = el.getBoundingClientRect(), tr = trOf(el);
+      const overRight = tr.right - er.right, overLeft = er.left - tr.left;
+      if (overRight > P.bleedBothSides && overLeft > P.bleedBothSides) continue; // deliberate two-sided bleed
+      const side = overRight >= overLeft ? 'right' : 'left';
+      const cs = getComputedStyle(el);
+      const fs = parseFloat(cs.fontSize) || 16;
+      const ls0 = parseFloat(cs.letterSpacing) || 0;
+      const ok = (el2) => ({ ok: spillOf(el2) < 1.5 });
+      let chosen = null;
+
+      // 1. the text spills into open canvas: not clipped, not covered, hits nothing — leave the type alone
+      if (freeOn(el, side) >= need + P.sidePad) continue;
+      // 2. letter-spacing
+      if (!chosen) {
+        for (const em of [0.004, 0.008, 0.012, 0.016, P.maxLetterSpacingEm]) {
+          const v = (ls0 - em * fs).toFixed(3) + 'px';
+          const r = trial(el, { 'letter-spacing': v }, ok);
+          if (r.ok && !r.moved) { chosen = { css: { 'letter-spacing': v }, reason: `tracking -${em}em (spill ${need.toFixed(1)}px)` }; break; }
+        }
+      }
+      // 3. font-size
+      if (!chosen) {
+        for (let i = 1; i <= 6; i++) {
+          const sc = 1 - i / 100;
+          if (1 - sc > P.maxFontShrink + 1e-6) break;
+          const v = (fs * sc).toFixed(2) + 'px';
+          const r = trial(el, { 'font-size': v }, ok);
+          if (r.ok && !r.moved) { chosen = { css: { 'font-size': v }, reason: `font -${i}% (spill ${need.toFixed(1)}px)` }; break; }
+        }
+      }
+      // 4. both at their caps
+      if (!chosen) {
+        const styles = { 'letter-spacing': (ls0 - P.maxLetterSpacingEm * fs).toFixed(3) + 'px', 'font-size': (fs * (1 - P.maxFontShrink)).toFixed(2) + 'px' };
+        const r = trial(el, styles, ok);
+        if (r.ok && !r.moved) chosen = { css: styles, reason: `tracking+font at cap (spill ${need.toFixed(1)}px)` };
+      }
+      // 5. else: the string is too long for the box — text lane's problem, not geometry's.
+      if (chosen) { seen.add(f.id); out.push(Object.assign({ id: f.id, rule: 'fit-text' }, chosen)); }
+    }
+
+    // ---------- vertical clipping of wrapped text: give the clipping ancestor its missing height
+    for (const f of metrics.overflow) {
+      if (f.kind !== 'clipped') continue;
+      const el = document.getElementById(f.id);
+      if (!el) continue;
+      const sec = secOf(el);
+      let a = el.parentElement, clip = null;
+      while (a && a !== sec) { if (getComputedStyle(a).overflow !== 'visible') { clip = a; break; } a = a.parentElement; }
+      if (!clip || seen.has(clip.id) || !clip.id) continue;
+      // measure.mjs scrolls clipped ancestors while sampling background colour (scrollIntoView); undo that so
+      // we read the geometry the page actually loads with.
+      if (clip.scrollTop || clip.scrollLeft) { clip.scrollTop = 0; clip.scrollLeft = 0; void document.body.offsetHeight; }
+      const tr = trOf(el), cr = clip.getBoundingClientRect();
+      const need = tr.bottom - cr.bottom;
+      if (need < 1.5) continue;                              // horizontal clipping is the spill branch's job
+      const h = Math.ceil((cr.height + need + 2) * 100) / 100;
+      const r = trial(clip, { height: h + 'px' }, (c) => ({ ok: trOf(el).bottom <= c.getBoundingClientRect().bottom + 0.5 }));
+      if (r.ok && !r.moved) { seen.add(clip.id); out.push({ id: clip.id, rule: 'fit-text', h, reason: `unclip ${el.id}: +${need.toFixed(1)}px height (slack below)` }); }
+    }
+
+    return out;
+  };
+}

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

@@ -0,0 +1,61 @@
+// Rule registry and the single owner of production polish policy. A rule module
+// exports { name, maxShift, params?, browserFn }. browserFn() returns a function
+// evaluated in the page with ({ metrics, params }) and emits deterministic CSS
+// overrides (see ../overrides.mjs).
+//
+// Keep this list explicit: adding a file must never silently enable an unstudied
+// rule. These eleven rules are the population-retained set from the canonical
+// prototype-polish study through owner-feedback round 8.
+import * as align from './align.mjs';
+import * as contrast from './contrast.mjs';
+import * as escape from './escape.mjs';
+import * as fitText from './fit-text.mjs';
+import * as leftRail from './left-rail.mjs';
+import * as overlap from './overlap.mjs';
+import * as pageCut from './page-cut.mjs';
+import * as photoCorners from './photo-corners.mjs';
+import * as rhythm from './rhythm.mjs';
+import * as sectionBreathing from './section-breathing.mjs';
+import * as shellSeam from './shell-seam.mjs';
+
+export const RETAINED_RULES = Object.freeze([
+  'align',
+  'contrast',
+  'escape',
+  'fit-text',
+  'left-rail',
+  'overlap',
+  'page-cut',
+  'photo-corners',
+  'rhythm',
+  'section-breathing',
+  'shell-seam',
+]);
+
+export const ALL = RETAINED_RULES;
+
+const MODULES = new Map([
+  ['align', align],
+  ['contrast', contrast],
+  ['escape', escape],
+  ['fit-text', fitText],
+  ['left-rail', leftRail],
+  ['overlap', overlap],
+  ['page-cut', pageCut],
+  ['photo-corners', photoCorners],
+  ['rhythm', rhythm],
+  ['section-breathing', sectionBreathing],
+  ['shell-seam', shellSeam],
+]);
+
+export async function loadRules(names = []) {
+  const wanted = names.length ? names : ALL;
+  const rules = [];
+  for (const n of wanted) {
+    if (!ALL.includes(n)) throw new Error(`unknown polish rule: ${n} (have ${ALL.join(', ')})`);
+    const mod = MODULES.get(n);
+    if (!mod.name || typeof mod.browserFn !== 'function') throw new Error(`rule ${n} must export name + browserFn()`);
+    rules.push(mod);
+  }
+  return rules;
+}