@12ui/design 0.2.44 → 0.2.45

package/prototype-kit/polish/rules/section-breathing.mjs

@@ -0,0 +1,292 @@
+// section-breathing: add deliberate air at declared page and internal section boundaries while preserving the
+// boundary's proven solid ground. The rule remains page-atomic and the driver verifies its paint with real pixels.
+//
+// Declared facts, not page names, drive the r3 widening:
+//   - adjacent `section[id^=viewport-]` blocks remain the page-seam source;
+//   - a direct child `footer`, `*-faq` / `*-questions`, or full-width `*-partners` block is an internal semantic seam;
+//   - only explicit `.decoration` leaves whose bounds touch/cross a page seam travel with the section below it;
+//   - an explicit `dashboard` block stays silent (dense surfaces keep their deliberate compression).
+//
+// Solid page-seam paint uses an integer-offset shadow. Internal seams grow the section and its full-section solid
+// owner, then move the semantic block and later direct children. Gradient/image/texture grounds still abstain.
+export const name = 'section-breathing';
+export const maxShift = 192;
+export const movesBlocks = true;
+export const phase = 'post';
+export const verifyPaint = true;
+export const recordsCensus = true;
+export const params = {
+  FLOOR: 32,
+  CAP: 64,
+  MIN_TARGET: 48,
+  MAX_TARGET: 192,
+  COVER: 0.8,
+  TIGHT_GAP: 32,
+  SEMANTIC_MAX_GAP: 32,
+  SEMANTIC_WIDTH: 0.8,
+  PREVIOUS_BLOCK_WIDTH: 0.5,
+};
+
+export function browserFn() {
+  return ({ params }) => {
+    const P = Object.assign({
+      FLOOR: 32, CAP: 64, MIN_TARGET: 48, MAX_TARGET: 192, COVER: 0.8,
+      TIGHT_GAP: 32, SEMANTIC_MAX_GAP: 32, SEMANTIC_WIDTH: 0.8, PREVIOUS_BLOCK_WIDTH: 0.5,
+    }, 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 alphaOf = (color) => {
+      const m = color && color.match(/^rgba?\(([^)]+)\)$/);
+      if (!m) return color === 'transparent' ? 0 : 1;
+      const p = m[1].split(/[, /]+/).filter(Boolean).map(Number);
+      return p.length > 3 ? p[3] : 1;
+    };
+    const groundClass = (style, el) => {
+      if (['IMG', 'PICTURE', 'VIDEO'].includes(el.tagName)) return 'image';
+      const img = style.backgroundImage;
+      if (/repeating-(?:linear|radial|conic)-gradient\(/.test(img)) return 'texture';
+      if (/(?:linear|radial|conic)-gradient\(/.test(img)) return 'gradient';
+      if (img !== 'none') return style.backgroundRepeat === 'no-repeat' ? 'image' : 'texture';
+      return alphaOf(style.backgroundColor) > 0.01 ? 'solid' : 'transparent';
+    };
+    const INK = '.text, .paragraph, h1, h2, h3, h4, h5, h6, .icon, img, .image, button, .button';
+    const median = (v) => {
+      const s = [...v].sort((a, b) => a - b); const m = Math.floor(s.length / 2);
+      return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+    };
+    const ceil8 = (v) => Math.ceil(v / 8) * 8;
+    const sections = [...document.querySelectorAll('section[id^="viewport-"]')]
+      .filter((s) => /^viewport-\d+-[A-Za-z0-9]+$/.test(s.id) && visible(s))
+      .sort((a, b) => a.getBoundingClientRect().top - b.getBoundingClientRect().top);
+    if (!sections.length) return out;
+
+    const validSolidOwner = (o, section, edge = null) => {
+      if (!o) return { ok: false, reason: 'ground-owner-unproven' };
+      const sr = section.getBoundingClientRect();
+      if (o.gc !== 'solid') return { ok: false, reason: `${o.gc}-ground (experimental class, abstain)` };
+      if (Math.abs(o.rect.left - sr.left) > 0.75 || Math.abs(o.rect.right - sr.right) > 0.75) {
+        return { ok: false, reason: 'ground-does-not-own-full-seam' };
+      }
+      if (edge && (edge === 'bottom' ? Math.abs(o.rect.bottom - sr.bottom) : Math.abs(o.rect.top - sr.top)) > 0.75) {
+        return { ok: false, reason: 'ground-does-not-touch-edge' };
+      }
+      const cs = o.cs;
+      if (cs.boxShadow !== 'none' || cs.clipPath !== 'none' || cs.maskImage !== 'none') {
+        return { ok: false, reason: 'owner-has-shadow-clip-or-mask' };
+      }
+      if (/var\(/.test(cs.backgroundColor) || alphaOf(cs.backgroundColor) < 0.999) {
+        return { ok: false, reason: 'transparent-or-unresolved-solid' };
+      }
+      if (!o.el.id) return { ok: false, reason: 'owner-has-no-id' };
+      return { ok: true, owner: o.el, color: cs.backgroundColor };
+    };
+    const ownerAt = (section, edge) => {
+      const sr = section.getBoundingClientRect(); const y = edge === 'bottom' ? sr.bottom - 1 : sr.top + 1;
+      const cands = [section, ...section.querySelectorAll('*')].flatMap((el) => {
+        if (!visible(el)) return [];
+        const r = el.getBoundingClientRect();
+        if (!(r.top <= y && r.bottom >= y) || r.width < sr.width * P.COVER) return [];
+        const cs = getComputedStyle(el); const gc = groundClass(cs, el);
+        if (gc === 'transparent') return [];
+        const cls = typeof el.className === 'string' ? el.className : '';
+        if (['IMG', 'PICTURE', 'VIDEO'].includes(el.tagName) && /(?:^|\s)(?:decoration|icon|logo|badge|photo|image)(?:\s|$)/.test(cls)) return [];
+        return [{ el, rect: r, area: r.width * r.height, gc, cs }];
+      }).sort((a, b) => a.area - b.area || String(a.el.id).localeCompare(String(b.el.id)));
+      return cands[0] || null;
+    };
+    const fullSectionOwner = (section) => {
+      const sr = section.getBoundingClientRect();
+      const cands = [section, ...section.querySelectorAll('*')].flatMap((el) => {
+        if (!visible(el)) return [];
+        const r = el.getBoundingClientRect();
+        if (r.left > sr.left + 0.75 || r.right < sr.right - 0.75 || r.top > sr.top + 0.75 || r.bottom < sr.bottom - 0.75) return [];
+        const cs = getComputedStyle(el); const gc = groundClass(cs, el);
+        if (gc === 'transparent') return [];
+        return [{ el, rect: r, area: r.width * r.height, gc, cs }];
+      }).sort((a, b) => a.area - b.area || String(a.el.id).localeCompare(String(b.el.id)));
+      return validSolidOwner(cands[0] || null, section);
+    };
+    const inkEdge = (section, edge) => {
+      const sr = section.getBoundingClientRect();
+      const ink = [...section.querySelectorAll(INK)].filter(visible).map((el) => el.getBoundingClientRect());
+      if (!ink.length) return null;
+      return edge === 'bottom' ? Math.max(...ink.map((r) => r.bottom)) - sr.top : Math.min(...ink.map((r) => r.top)) - sr.top;
+    };
+    const directChildOf = (section, el) => {
+      let child = el;
+      while (child.parentElement && child.parentElement !== section) child = child.parentElement;
+      return child.parentElement === section ? child : null;
+    };
+    const attachmentsAt = (section, seamY) => {
+      const cands = [...section.querySelectorAll('.decoration[id]')].filter(visible).filter((el) => {
+        const r = el.getBoundingClientRect();
+        return r.top < seamY && r.bottom >= seamY - 0.75 && r.width < section.getBoundingClientRect().width * P.COVER;
+      });
+      return cands.filter((el) => !cands.some((other) => other !== el && el.contains(other))).map((el) => {
+        const r = el.getBoundingClientRect();
+        return { el, topOffset: +(r.top - seamY).toFixed(2), bottomOffset: +(r.bottom - seamY).toFixed(2) };
+      });
+    };
+
+    const viewportSeams = [];
+    for (let i = 1; i < sections.length; i++) {
+      const before = sections[i - 1], after = sections[i];
+      const br = before.getBoundingClientRect(), ar = after.getBoundingClientRect();
+      const lastInk = inkEdge(before, 'bottom'), firstInk = inkEdge(after, 'top');
+      if (lastInk == null || firstInk == null) continue;
+      const gap = (br.height - lastInk) + (ar.top - br.bottom) + firstInk;
+      if (gap < 0) continue;
+      viewportSeams.push({ kind: 'viewport', before, after, section: before, gap });
+    }
+    const target = viewportSeams.length === 1
+      ? viewportSeams[0].gap + P.FLOOR
+      : viewportSeams.length
+        ? Math.max(P.MIN_TARGET, Math.min(P.MAX_TARGET, ceil8(median(viewportSeams.map((s) => s.gap)) + P.FLOOR)))
+        : null;
+    const viewportPlans = viewportSeams.map((s) => {
+      const raw = Math.round(Math.min(P.CAP, Math.max(0, target - s.gap)));
+      const tightScaled = raw > 0 && raw < P.FLOOR && s.gap < P.TIGHT_GAP;
+      const addition = tightScaled ? P.FLOOR : raw;
+      if (addition < P.FLOOR) {
+        return { ...s, addition, declined: addition > 0 ? 'below the 32 px perceptibility floor' : 'already at the page rhythm target' };
+      }
+      const tryOwner = (section, edge) => {
+        const valid = validSolidOwner(ownerAt(section, edge), section, edge);
+        return valid.ok ? { ...valid, side: edge === 'bottom' ? 'outgoing' : 'incoming' } : valid;
+      };
+      const outgoing = tryOwner(s.before, 'bottom'); const ground = outgoing.ok ? outgoing : tryOwner(s.after, 'top');
+      const seamY = s.after.getBoundingClientRect().top;
+      return {
+        ...s, addition, tightScaled, ground,
+        diagnostics: outgoing.ok ? null : { outgoing: outgoing.reason, incoming: ground.reason },
+        attachments: attachmentsAt(s.before, seamY),
+      };
+    });
+
+    const semanticPlans = [];
+    for (const section of sections) {
+      const sr = section.getBoundingClientRect(); const children = [...section.children].filter(visible);
+      const ground = fullSectionOwner(section);
+      const semantic = children.flatMap((el) => {
+        const id = el.id.toLowerCase(); const r = el.getBoundingClientRect();
+        const fact = el.tagName === 'FOOTER' ? 'footer'
+          : /(?:^|[-_])(?:faq|questions)(?:[-_]|$)/.test(id) ? 'questions'
+            : /(?:^|[-_])partners(?:[-_]|$)/.test(id) ? 'partners' : null;
+        return fact && el.id && r.width >= sr.width * P.SEMANTIC_WIDTH ? [{ el, fact, rect: r }] : [];
+      }).sort((a, b) => a.rect.top - b.rect.top);
+      for (const candidate of semantic) {
+        const eligible = children.filter((el) => {
+          if (el === candidate.el || el === ground.owner || !el.id) return false;
+          const r = el.getBoundingClientRect();
+          const fullSection = r.top <= sr.top + 0.75 && r.bottom >= sr.bottom - 0.75;
+          return !fullSection && r.width >= sr.width * P.PREVIOUS_BLOCK_WIDTH && r.bottom <= candidate.rect.top + 0.75;
+        }).sort((a, b) => b.getBoundingClientRect().bottom - a.getBoundingClientRect().bottom);
+        const before = eligible[0]; if (!before) continue;
+        const br = before.getBoundingClientRect(); const gap = candidate.rect.top - br.bottom;
+        if (gap < 0) continue;
+        // Moving a full-width semantic block deliberately changes its vertical relation to every substantial direct
+        // block before it (including unequal-height columns). Declare that exact target relation; unrelated sibling
+        // gaps remain protected by the harm guard.
+        const beforePeers = children.filter((el) => {
+          if (el === candidate.el || el === ground.owner || !el.id) return false;
+          const r = el.getBoundingClientRect();
+          const fullSection = r.top <= sr.top + 0.75 && r.bottom >= sr.bottom - 0.75;
+          return !fullSection && r.bottom <= candidate.rect.top + 0.75;
+        }).map((el) => el.id);
+        const dense = [before.id, candidate.el.id].some((id) => /(?:^|[-_])dashboard(?:[-_]|$)/.test(id.toLowerCase()));
+        const addition = ground.ok && !dense && gap < P.SEMANTIC_MAX_GAP ? P.FLOOR : 0;
+        semanticPlans.push({
+          kind: 'semantic', section, before, beforePeers, after: candidate.el, fact: candidate.fact, gap,
+          addition, ground,
+          declined: !ground.ok ? ground.reason
+            : dense ? 'dense dashboard boundary stays tight'
+            : addition ? null : 'semantic boundary already has at least 32 px',
+        });
+      }
+    }
+
+    const censusRow = (p) => ({
+      kind: p.kind, section: p.section.id, before: p.before.id, after: p.after.id, fact: p.fact || null,
+      gap: +p.gap.toFixed(1), addition: p.addition, declined: p.declined || null,
+      tightScaled: p.tightScaled || false,
+      attachments: (p.attachments || []).map((a) => a.el.id),
+      ground: p.ground ? (p.ground.ok ? { side: p.ground.side || 'internal', color: p.ground.color, owner: p.ground.owner.id } : (p.diagnostics || { reason: p.ground.reason })) : null,
+    });
+    if (P.census) return [...viewportPlans, ...semanticPlans].map(censusRow);
+
+    const admittedViewport = viewportPlans.filter((p) => !p.declined);
+    const admittedSemantic = semanticPlans.filter((p) => !p.declined);
+    const admitted = [...admittedViewport, ...admittedSemantic];
+    if (!admitted.length || admitted.some((p) => !p.ground?.ok)) return out;
+
+    const sectionShift = new Map(sections.map((s) => [s.id, 0]));
+    const sectionGrowth = new Map(sections.map((s) => [s.id, 0]));
+    const childShift = new Map();
+    const sectionIndex = new Map(sections.map((s, i) => [s.id, i]));
+    for (const p of admittedSemantic) {
+      sectionGrowth.set(p.section.id, sectionGrowth.get(p.section.id) + p.addition);
+      const tr = p.after.getBoundingClientRect();
+      for (const child of [...p.section.children].filter(visible)) {
+        if (child.id && child.getBoundingClientRect().top >= tr.top - 0.75) childShift.set(child.id, (childShift.get(child.id) || 0) + p.addition);
+      }
+    }
+    for (const p of admittedViewport) {
+      for (let i = sectionIndex.get(p.after.id); i < sections.length; i++) sectionShift.set(sections[i].id, sectionShift.get(sections[i].id) + p.addition);
+    }
+
+    for (const p of admittedViewport) {
+      const dy = p.ground.side === 'outgoing' ? p.addition : -p.addition;
+      const br = p.before.getBoundingClientRect();
+      const attachments = p.attachments.map((a) => ({ id: a.el.id, topOffset: a.topOffset, bottomOffset: a.bottomOffset }));
+      out.push({
+        id: p.ground.owner.id, rule: 'section-breathing',
+        reason: `viewport seam ${p.before.id}→${p.after.id}: gap ${p.gap.toFixed(0)} + ${p.addition} px, solid ${p.ground.color} extended (${p.ground.side})`,
+        css: { 'box-shadow': `0 ${dy}px 0 0 ${p.ground.color}` },
+        meta: { seam: {
+          kind: p.kind, before: p.before.id, after: p.after.id, gap: +p.gap.toFixed(1), baseStripHeight: 0,
+          addition: p.addition, color: p.ground.color, side: p.ground.side, owner: p.ground.owner.id,
+          attachments, seamTop: br.bottom + window.scrollY + sectionShift.get(p.before.id) + sectionGrowth.get(p.before.id),
+        } },
+      });
+      for (const a of p.attachments) {
+        const direct = directChildOf(p.before, a.el); const inherited = direct ? (childShift.get(direct.id) || 0) : 0;
+        const travel = p.addition + sectionGrowth.get(p.before.id) - inherited;
+        if (travel) out.push({ id: a.el.id, rule: 'section-breathing', reason: `declared decoration travels ${travel} px with ${p.after.id}`, dy: travel });
+      }
+    }
+    for (const p of admittedSemantic) {
+      out.push({
+        id: p.after.id, rule: 'section-breathing',
+        reason: `${p.fact} seam ${p.before.id}→${p.after.id}: gap ${p.gap.toFixed(0)} + ${p.addition} px`, dy: p.addition,
+        meta: { seam: {
+          kind: p.kind, fact: p.fact, before: p.before.id, after: p.after.id, gap: +p.gap.toFixed(1),
+          baseStripHeight: +p.gap.toFixed(2), addition: p.addition, color: p.ground.color, side: 'internal',
+          owner: p.ground.owner.id, attachments: [], beforePeers: p.beforePeers,
+        } },
+      });
+    }
+    for (const [id, dy] of childShift) {
+      const targetOwnShift = admittedSemantic.filter((p) => p.after.id === id).reduce((n, p) => n + p.addition, 0);
+      const remainder = dy - targetOwnShift;
+      if (remainder) out.push({ id, rule: 'section-breathing', reason: `block follows ${remainder} px of semantic air above it`, dy: remainder });
+    }
+    for (const section of sections) {
+      const growth = sectionGrowth.get(section.id); if (!growth) continue;
+      const sr = section.getBoundingClientRect(); const owner = admittedSemantic.find((p) => p.section === section).ground.owner;
+      const or = owner.getBoundingClientRect();
+      out.push({ id: owner.id, rule: 'section-breathing', reason: `solid section ground grows ${growth} px`, h: or.height + growth });
+      out.push({ id: section.id, rule: 'section-breathing', reason: `section grows ${growth} px for semantic air`, h: sr.height + growth });
+    }
+    for (const [id, dy] of sectionShift) if (dy) out.push({ id, rule: 'section-breathing', reason: `section follows ${dy} px of added air above it`, dy });
+    const total = admitted.reduce((n, p) => n + p.addition, 0);
+    const canvas = document.querySelector('#page-flow') || document.querySelector('.ly-anchor-canvas');
+    const canvasH = canvas ? canvas.getBoundingClientRect().height : document.documentElement.scrollHeight;
+    out.push({ sel: '#page-flow, .ly-anchor-canvas', rule: 'section-breathing', reason: `canvas +${total} px`, css: { height: `${(canvasH + total).toFixed(2)}px` } });
+    return out;
+  };
+}

package/prototype-kit/polish/rules/shell-seam.mjs

@@ -0,0 +1,48 @@
+// shell-seam: transplanted shell children that do not fit the page's own host box.
+//
+// Mechanism (frontier lane C, 34 of 66 population runs): build.mjs transplants the canonical shell's CHILDREN into the
+// page's OWN host box; the children keep canonical geometry. On Lands the canonical rail is 258 px and the review page
+// hosts it in 221 px, so the "New study" button (214 px) crossed its own rail by 17 px.
+//
+// History, on the record: the first version of this rule grew the host to the canonical box (and, with no slack,
+// grew it into the content gutter). The owner rejected that — it squeezed the gutter 51 → 13 px and read worse, not
+// better ("I would reduce the button size"). build.mjs now fits the children to the host at build time
+// (`fitShellChildren`: width clamp with canonical insets, bottom re-anchoring), so this rule is a BACKSTOP that must
+// be content-conserving:
+//   * it only acts on a transplanted child that still spills past the host box (live geometry, ≥ 2 px);
+//   * it shrinks that child (`w`, keeping its left edge and its canonical right inset) or lifts it back above the
+//     host's bottom edge (`dy`); it never resizes the host, never moves page content, never touches the gutter;
+//   * with the upstream fit in place it is expected to stay silent (fixture `silent.html` pins exactly that).
+export const name = 'shell-seam';
+export const maxShift = 40; // a lifted footer may travel this far; width clamps move nothing
+
+export function browserFn() {
+  return () => {
+    const MIN = 2;
+    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; };
+    for (const host of document.querySelectorAll('[data-proto-shell]')) {
+      if (!visible(host)) continue;
+      const hr = host.getBoundingClientRect();
+      const handled = new Set();
+      // parents first so a child that travels with its parent is not handled twice
+      const kids = [...host.querySelectorAll('[id]')].filter(visible).sort((a, b) => a.id.length - b.id.length);
+      for (const k of kids) {
+        if ([...handled].some((id) => k.id.startsWith(id + '-'))) continue;
+        const r = k.getBoundingClientRect();
+        const overX = r.right - hr.right, overY = r.bottom - hr.bottom;
+        const isTextLeaf = k.classList.contains('text') || k.classList.contains('paragraph') || /^H[1-6]$/.test(k.tagName);
+        if (overX >= MIN && r.left < hr.right - 24 && !isTextLeaf) { // a nowrap label cannot shrink by width — fit-text's job
+          // shrink: keep the left edge, land the right edge at the host's right minus a small inset
+          const inset = Math.min(8, Math.max(0, hr.right - r.right + overX));
+          const w = hr.right - inset - r.left;
+          if (w >= 24 && w < r.width - 0.5) { out.push({ id: k.id, rule: 'shell-seam', reason: `child ${r.width.toFixed(1)}→${w.toFixed(1)} (spilled ${overX.toFixed(1)}px past the host)`, w }); handled.add(k.id); }
+        } else if (overY >= MIN) {
+          const dy = -(overY + Math.min(8, Math.max(0, hr.height - r.height)));
+          if (-dy <= 40) { out.push({ id: k.id, rule: 'shell-seam', reason: `child ${overY.toFixed(1)}px below the host → lift`, dy }); handled.add(k.id); }
+        }
+      }
+    }
+    return out;
+  };
+}

package/prototype-kit/polish/tests/breathing-check.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// section-breathing: floor + background-integrity pairs.
+//   floor    three solid sections, gaps ~42 / ~102 → target ceil8(median+32) = 104: seam 1 gets +62, seam 2 (+2) is DECLINED
+//   probe    on the fire fixture the pixel probe accepts the accepted seam (9/9 probes in the owner's colour, document
+//            grew by exactly the addition); with a deliberately wrong owner colour it must fail with 'coverage'
+import path from 'node:path';
+import { chromium } from '@playwright/test';
+import * as rule from '../rules/section-breathing.mjs';
+import { applyOverridesScript, overridesToCss, mergeOverrides } from '../overrides.mjs';
+import { probeSeams } from '../ground-probe.mjs';
+const here = path.dirname(new URL(import.meta.url).pathname);
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1536, height: 1024 } });
+let failures = 0;
+const check = (name, ok, detail) => { if (!ok) failures++; console.log(`${ok ? 'ok  ' : 'FAIL'} section-breathing/${name}: ${detail}`); };
+const seamMeta = (overrides) => overrides.filter((o) => o.meta?.seam).map((o) => o.meta.seam);
+// floor
+await page.goto('file://' + path.join(here, 'fixtures/section-breathing/floor.html'), { waitUntil: 'load' });
+const floor = await page.evaluate(rule.browserFn(), { metrics: {}, params: rule.params });
+const seams = seamMeta(floor);
+check('floor declines the 2 px seam, keeps the 62 px seam', seams.length === 1 && seams[0].addition === 62 && seams[0].before === 'viewport-1-a', JSON.stringify(seams));
+// tight-gap scale: a 30 px page seam whose rhythm delta is only 18 px still receives the perceptible 32 px floor
+await page.goto('file://' + path.join(here, 'fixtures/section-breathing/tight.html'), { waitUntil: 'load' });
+const tight = await page.evaluate(rule.browserFn(), { metrics: {}, params: { ...rule.params, census: true } });
+const tightPlan = tight.find((s) => s.before === 'viewport-3-a' && s.after === 'viewport-4-a');
+check('tight page seam scales to the 32 px perceptibility floor', tightPlan?.tightScaled && tightPlan.addition === 32, JSON.stringify(tightPlan));
+// probe: accepted seam on the fire fixture
+await page.goto('file://' + path.join(here, 'fixtures/section-breathing/fire.html'), { waitUntil: 'load' });
+const base = await page.evaluate(() => document.documentElement.scrollHeight);
+const fire = await page.evaluate(rule.browserFn(), { metrics: {}, params: rule.params });
+await page.evaluate(applyOverridesScript(), overridesToCss(mergeOverrides(fire)));
+const good = await probeSeams(page, seamMeta(fire), base);
+check('probe accepts a solid seam (9 probes, height +32)', good.ok && good.probes === 9 && good.documentHeight === base + 32, JSON.stringify({ ok: good.ok, probes: good.probes, h: [base, good.documentHeight], failures: good.failures.slice(0, 2) }));
+// probe: sabotage — claim a different colour than the one painted → coverage failure on every probe
+const bad = await probeSeams(page, seamMeta(fire).map((s) => ({ ...s, color: 'rgb(0, 90, 200)' })), base);
+check('probe rejects a seam whose pixels are not the declared ground', !bad.ok && bad.failures.every((f) => f.kind === 'coverage' || f.kind === 'floor-exposure') && bad.failures.length === 9, JSON.stringify({ ok: bad.ok, n: bad.failures.length, kinds: [...new Set(bad.failures.map((f) => f.kind))] }));
+
+// attachment pair: only a declared decoration touching the seam travels with the following section
+await page.goto('file://' + path.join(here, 'fixtures/section-breathing/attachment-fire.html'), { waitUntil: 'load' });
+const attachmentBase = await page.evaluate(() => document.documentElement.scrollHeight);
+const attachmentFire = await page.evaluate(rule.browserFn(), { metrics: {}, params: rule.params });
+const attachmentMove = attachmentFire.find((o) => o.id === 'viewport-1-a-fruit');
+await page.evaluate(applyOverridesScript(), overridesToCss(mergeOverrides(attachmentFire)));
+const attachmentProbe = await probeSeams(page, seamMeta(attachmentFire), attachmentBase);
+check('boundary-hugging decoration travels and keeps its seam attachment', attachmentMove?.dy === 32 && seamMeta(attachmentFire)[0]?.attachments?.[0]?.id === 'viewport-1-a-fruit' && attachmentProbe.ok, JSON.stringify({ move: attachmentMove, ground: attachmentProbe }));
+await page.goto('file://' + path.join(here, 'fixtures/section-breathing/attachment-silent.html'), { waitUntil: 'load' });
+const attachmentSilent = await page.evaluate(rule.browserFn(), { metrics: {}, params: rule.params });
+check('ordinary boundary image is not reclassified as decoration', !attachmentSilent.some((o) => o.id === 'viewport-1-a-product-image'), JSON.stringify(attachmentSilent.filter((o) => o.id === 'viewport-1-a-product-image')));
+
+// semantic pair: direct declared FAQ/footer boundaries breathe; a dense dashboard boundary stays silent
+await page.goto('file://' + path.join(here, 'fixtures/section-breathing/semantic-fire.html'), { waitUntil: 'load' });
+const semanticBase = await page.evaluate(() => document.documentElement.scrollHeight);
+const semantic = await page.evaluate(rule.browserFn(), { metrics: {}, params: rule.params });
+const semanticMerged = mergeOverrides(semantic);
+await page.evaluate(applyOverridesScript(), overridesToCss(semanticMerged));
+const semanticProbe = await probeSeams(page, seamMeta(semantic), semanticBase);
+const faq = semanticMerged.find((o) => o.id === 'viewport-1-a-faq');
+const footer = semanticMerged.find((o) => o.id === 'viewport-1-a-footer');
+const section = semanticMerged.find((o) => o.id === 'viewport-1-a');
+check('declared FAQ and footer boundaries each gain 32 px', faq?.dy === 32 && footer?.dy === 64 && section?.h === 1088 && faq?.meta?.seam?.beforePeers?.includes('viewport-1-a-comparison-aside') && semanticProbe.ok, JSON.stringify({ faq, footer, section, ground: semanticProbe }));
+await page.goto('file://' + path.join(here, 'fixtures/section-breathing/semantic-silent.html'), { waitUntil: 'load' });
+const semanticSilent = await page.evaluate(rule.browserFn(), { metrics: {}, params: rule.params });
+check('dense dashboard footer boundary stays tight', semanticSilent.length === 0, JSON.stringify(semanticSilent));
+
+// shadow-gradient pair: the measured neutral monotone fade is tolerated; a hard coloured band still fails
+for (const [fixture, expected] of [['shadow-fire.html', true], ['shadow-silent.html', false]]) {
+  await page.goto('file://' + path.join(here, 'fixtures/section-breathing', fixture), { waitUntil: 'load' });
+  const shadowBase = await page.evaluate(() => document.documentElement.scrollHeight);
+  const shadow = await page.evaluate(rule.browserFn(), { metrics: {}, params: rule.params });
+  await page.evaluate(applyOverridesScript(), overridesToCss(mergeOverrides(shadow)));
+  const verdict = await probeSeams(page, seamMeta(shadow), shadowBase);
+  const ok = expected ? verdict.ok && verdict.toleratedShadowGradients > 0 : !verdict.ok && verdict.failures.some((f) => f.kind === 'coverage');
+  check(expected ? 'neutral monotone shadow fade is tolerated' : 'hard coloured seam band stays rejected', ok, JSON.stringify(verdict));
+}
+await browser.close();
+if (failures) { console.log(`${failures} failure(s)`); process.exit(1); }
+console.log('section-breathing pairs green');

package/prototype-kit/polish/tests/fixtures/align/expect.json

@@ -0,0 +1 @@
+[{"id":"viewport-1-a-cards-card-2","dy":-1.02},{"id":"viewport-1-a-cards-card-3","dy":-2.05}]

package/prototype-kit/polish/tests/fixtures/align/fire.html

@@ -0,0 +1,14 @@
+<!doctype html><meta charset="utf-8"><style>
+*{margin:0;padding:0;box-sizing:border-box} body{font-family:system-ui}
+section{position:relative;width:1536px;height:1024px;background:#fff}
+.row{position:relative;display:flex;gap:24px;margin:100px 0 0 100px}
+.card{position:relative;width:300px;height:200px;background:#f3f3f3;border:1px solid #ddd;border-radius:12px}
+.text{position:relative;display:block;font-size:16px;line-height:20px;margin:20px 0 0 20px}
+</style>
+<section id="viewport-1-a">
+  <div id="viewport-1-a-cards" class="row">
+    <div id="viewport-1-a-cards-card-1" class="card"><span id="viewport-1-a-cards-card-1-text" class="text">Alpha</span></div>
+    <div id="viewport-1-a-cards-card-2" class="card" style="margin-top:1.02px"><span id="viewport-1-a-cards-card-2-text" class="text">Beta</span></div>
+    <div id="viewport-1-a-cards-card-3" class="card" style="margin-top:2.05px"><span id="viewport-1-a-cards-card-3-text" class="text">Gamma</span></div>
+  </div>
+</section>

package/prototype-kit/polish/tests/fixtures/align/silent.html

@@ -0,0 +1,28 @@
+<!doctype html><meta charset="utf-8"><style>
+*{margin:0;padding:0;box-sizing:border-box} body{font-family:system-ui}
+section{position:relative;width:1536px;height:1024px;background:#fff}
+.row{position:relative;display:flex;gap:24px;margin:100px 0 0 100px}
+.card{position:relative;width:300px;height:200px;background:#f3f3f3;border:1px solid #ddd;border-radius:12px}
+.text{position:relative;display:block;font-size:16px;line-height:20px;margin:20px 0 0 20px}
+.big{font-size:28px;line-height:34px}
+</style>
+<section id="viewport-1-a">
+  <!-- equal tops: nothing to snap; a deliberate 24px step and a different-kind pair must stay untouched -->
+  <div id="viewport-1-a-cards" class="row">
+    <div id="viewport-1-a-cards-card-1" class="card"><span id="viewport-1-a-cards-card-1-text" class="text">Alpha</span><span id="viewport-1-a-cards-card-1-value" class="text big" style="margin-top:3px">42</span></div>
+    <div id="viewport-1-a-cards-card-2" class="card"><span id="viewport-1-a-cards-card-2-text" class="text">Beta</span></div>
+    <div id="viewport-1-a-cards-card-3" class="card" style="margin-top:24px"><span id="viewport-1-a-cards-card-3-text" class="text">Gamma</span></div>
+  </div>
+  <!-- left-aligned nav list: right edges 5 px apart are a near-miss, but the items belong to a left column → no snap -->
+  <div id="viewport-1-a-nav" style="position:absolute;left:0;top:400px;width:240px;height:200px">
+    <div id="viewport-1-a-nav-item-1" class="text" style="position:absolute;left:30px;top:0;width:99px;height:18px;margin:0">Overview</div>
+    <div id="viewport-1-a-nav-item-2" class="text" style="position:absolute;left:30px;top:40px;width:104px;height:18px;margin:0">Proposals</div>
+    <div id="viewport-1-a-nav-item-3" class="text" style="position:absolute;left:30px;top:80px;width:100px;height:18px;margin:0">Streams</div>
+  </div>
+  <!-- rows 1 px apart whose labels + icons already form exact columns: snapping the ROW boxes would break the ink → no snap -->
+  <div id="viewport-1-a-list" style="position:absolute;left:400px;top:400px;width:300px;height:200px">
+    <div id="viewport-1-a-list-row-1" style="position:absolute;left:10px;top:0;width:200px;height:24px"><span id="viewport-1-a-list-row-1-icon" class="icon" style="position:absolute;left:0;top:4px;width:16px;height:16px;background:#888"></span><span id="viewport-1-a-list-row-1-text" class="text" style="position:absolute;left:28px;top:2px;margin:0;width:100px">Alpha</span></div>
+    <div id="viewport-1-a-list-row-2" style="position:absolute;left:11.1px;top:40px;width:200px;height:24px"><span id="viewport-1-a-list-row-2-icon" class="icon" style="position:absolute;left:-1.1px;top:4px;width:16px;height:16px;background:#888"></span><span id="viewport-1-a-list-row-2-text" class="text" style="position:absolute;left:26.9px;top:2px;margin:0;width:100px">Beta</span></div>
+    <div id="viewport-1-a-list-row-3" style="position:absolute;left:10px;top:80px;width:200px;height:24px"><span id="viewport-1-a-list-row-3-icon" class="icon" style="position:absolute;left:0;top:4px;width:16px;height:16px;background:#888"></span><span id="viewport-1-a-list-row-3-text" class="text" style="position:absolute;left:28px;top:2px;margin:0;width:100px">Gamma</span></div>
+  </div>
+</section>

package/prototype-kit/polish/tests/fixtures/contrast/expect.json

@@ -0,0 +1 @@
+[]

package/prototype-kit/polish/tests/fixtures/contrast/fallback.html

@@ -0,0 +1,7 @@
+<!doctype html><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}body{font-family:system-ui}section{position:relative;width:1536px;height:1024px;background:#959595}.text{position:relative;display:block;margin:40px;font-size:20px}</style>
+<script id="proto-state" type="application/json">{"tokens":{"headingColor":"rgb(30, 30, 29)"}}</script>
+<section id="viewport-1-a">
+  <!-- unreachable: a saturated yellow on MID GREY — neither darkening to the floor nor lightening to the ceiling reaches 3:1
+       within its hue, so the rule falls back and says so -->
+  <p id="viewport-1-a-orange-grey" class="text" style="color:#ffe600">Yellow on mid grey</p>
+</section>

package/prototype-kit/polish/tests/fixtures/contrast/fire.html

@@ -0,0 +1,9 @@
+<!doctype html><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}body{font-family:system-ui}section{position:relative;width:1536px;height:1024px;background:#fbf6ee}.text{position:relative;display:block;margin:40px;font-size:20px}</style>
+<script id="proto-state" type="application/json">{"tokens":{"headingColor":"rgb(30, 30, 29)","bodyColor":"rgb(60, 60, 60)"}}</script>
+<section id="viewport-1-a">
+  <!-- fire: a declared brand orange on cream (≈2.5:1) darkens WITHIN its hue to a readable orange — not to black -->
+  <p id="viewport-1-a-orange" class="text" style="color:#e68000">Give your time. Strengthen our city.</p>
+  <!-- fire: a holding title painted near-white on a light page (1.06:1): a neutral keeps its (zero) saturation → grey -->
+  <h1 class="proto-holding-title text" style="color:rgb(247,248,248)">Changelog</h1>
+  <span id="viewport-1-a-fine" class="text" style="color:rgb(30,30,30)">Readable copy</span>
+</section>

package/prototype-kit/polish/tests/fixtures/contrast/silent.html

@@ -0,0 +1,9 @@
+<!doctype html><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}body{font-family:system-ui}section{position:relative;width:1536px;height:1024px;background:#fbf6ee}.text{position:relative;display:block;margin:40px;font-size:20px}.hero{position:absolute;left:0;top:0;width:800px;height:400px;background-image:linear-gradient(#234,#123)}</style>
+<script id="proto-state" type="application/json">{"tokens":{"headingColor":"rgb(30, 30, 29)"}}</script>
+<section id="viewport-1-a">
+  <div id="viewport-1-a-hero" class="hero"></div>
+  <!-- light text over an image-backed hero is design; an already-readable declared brand colour (#a05600, 4.6:1) is untouched -->
+  <h1 id="viewport-1-a-hero-heading" class="text" style="position:absolute;left:40px;top:40px;color:rgb(250,250,250)">Over the photo</h1>
+  <span id="viewport-1-a-brand" class="text" style="margin-top:500px;color:#a05600">Already readable orange</span>
+  <span id="viewport-1-a-body" class="text" style="color:rgb(40,40,40)">Readable copy</span>
+</section>

package/prototype-kit/polish/tests/fixtures/escape/expect.json

@@ -0,0 +1,2 @@
+[{"id":"viewport-1-a-header-search","dy":-26},
+ {"id":"viewport-1-a-card","w":222}]

package/prototype-kit/polish/tests/fixtures/escape/fire.html

@@ -0,0 +1,23 @@
+<!doctype html><meta charset="utf-8"><style>
+*{margin:0;padding:0;box-sizing:border-box} body{font-family:Arial,Helvetica,sans-serif}
+section{position:relative;width:1536px;height:800px;background:#fff}
+.text,h1,h2,h3{position:relative;display:block;white-space:pre;margin:0}
+.card{position:absolute;background:#ffffff;border:1px solid #dfe3e8;border-radius:12px}
+.icon{position:absolute;background:#9aa7b4;border-radius:3px}
+</style>
+<section id="viewport-1-a">
+
+  <!-- 1. canonical header band is 60px tall; the transplanted search pill keeps the donor page's y=52 -->
+  <header id="viewport-1-a-header" data-proto-shell style="position:absolute;left:0;top:0;width:1536px;height:60px;background:#0a1928">
+    <p id="viewport-1-a-header-brand" class="text" style="position:absolute;left:32px;top:22px;width:120px;height:16px;font-size:14px;line-height:16px;color:#e6edf4">Kestrel</p>
+    <div id="viewport-1-a-header-search" style="position:absolute;left:600px;top:52px;width:280px;height:30px">
+      <p id="viewport-1-a-header-search-text" class="text" style="position:absolute;left:240px;top:10px;width:30px;height:10px;font-size:10px;line-height:10px;color:#8ea3b8">⌘ K</p>
+    </div>
+  </header>
+
+  <!-- 2. a card whose label is wider than the card, with open space to its right → grow the card -->
+  <div id="viewport-1-a-card" class="card" style="left:200px;top:200px;width:200px;height:120px">
+    <p id="viewport-1-a-card-text" class="text" style="position:absolute;left:16px;top:20px;width:200px;height:19px;font-size:16px;line-height:19px;color:#1b2530">Deployment health overview</p>
+  </div>
+
+</section>

package/prototype-kit/polish/tests/fixtures/escape/silent.html

@@ -0,0 +1,29 @@
+<!doctype html><meta charset="utf-8"><style>
+*{margin:0;padding:0;box-sizing:border-box} body{font-family:Arial,Helvetica,sans-serif}
+section{position:relative;width:1536px;height:600px;background:#fff}
+.text,h1,h2,h3{position:relative;display:block;white-space:pre;margin:0}
+.card{position:absolute;background:#ffffff;border:1px solid #dfe3e8;border-radius:12px}
+.panel{position:absolute;background:#12212f}
+</style>
+<section id="viewport-1-a">
+
+  <!-- near threshold: the label sits ~1.8px proud of its pill; that is glyph bearing, not a defect -->
+  <div id="viewport-1-a-pill" class="card" style="left:80px;top:60px;width:72px;height:24px">
+    <p id="viewport-1-a-pill-text" class="text" style="position:absolute;left:8px;top:5px;width:60px;height:14px;font-size:12px;line-height:14px;color:#1b2530">In review 24</p>
+  </div>
+
+  <!-- a display line deliberately overhanging its photo panel, with a neighbour right beside it and no slack
+       inside: nothing can be grown, moved or shrunk by 6% → leave it exactly as designed -->
+  <div id="viewport-1-a-photo" class="panel" style="left:100px;top:200px;width:200px;height:160px">
+    <h2 id="viewport-1-a-photo-heading" style="position:absolute;left:0;top:50px;width:200px;height:44px;font-size:36px;line-height:44px;color:#fff">Night market</h2>
+  </div>
+  <div id="viewport-1-a-photo-next" class="panel" style="left:310px;top:200px;width:200px;height:160px"></div>
+
+  <!-- already owned by page-cut: this row is off the canvas as well as out of its footer plate -->
+  <footer id="viewport-1-a-footer" data-proto-shell class="panel" style="left:0;top:480px;width:1536px;height:120px">
+    <div id="viewport-1-a-footer-legal" style="position:absolute;left:80px;top:132px;width:900px;height:14px">
+      <p id="viewport-1-a-footer-legal-text" class="text" style="position:absolute;left:0;top:0;width:420px;height:14px;font-size:12px;line-height:14px;color:#8ea3b8">© 2024 Kestrel Systems. All rights reserved.</p>
+    </div>
+  </footer>
+
+</section>

package/prototype-kit/polish/tests/fixtures/fit-text/expect.json

@@ -0,0 +1,3 @@
+[{"id":"viewport-1-a-metric-text","css":{"letter-spacing":"-0.192px"}},
+ {"id":"viewport-1-a-title-heading","css":{"font-size":"30.72px"}},
+ {"id":"viewport-1-a-note","h":53}]

package/prototype-kit/polish/tests/fixtures/fit-text/fire.html

@@ -0,0 +1,26 @@
+<!doctype html><meta charset="utf-8"><style>
+*{margin:0;padding:0;box-sizing:border-box} body{font-family:Arial,Helvetica,sans-serif}
+section{position:relative;width:1536px;height:1024px;background:#fff}
+.fx-col{display:flex;flex-direction:column;align-items:flex-start}
+.fx-abs{position:relative}
+.text,h1,h2,h3{position:relative;display:block;white-space:pre;margin:0}
+.card{position:relative;background:#f6f7f9;border:1px solid #e3e6ea;border-radius:12px}
+</style>
+<section id="viewport-1-a">
+
+  <!-- A: label a few px wider than its slot, parent exactly as wide (no free space) → tighten tracking -->
+  <div id="viewport-1-a-metric" class="fx-col" style="position:absolute;left:80px;top:260px;width:180px;height:60px">
+    <p id="viewport-1-a-metric-text" class="text" style="width:180px;height:19px;font-size:16px;line-height:19px">Monthly recurring revenue</p>
+  </div>
+
+  <!-- B: too wide for tracking alone, inside 6% → trim the font -->
+  <div id="viewport-1-a-title" class="fx-col" style="position:absolute;left:80px;top:400px;width:199px;height:60px">
+    <h2 id="viewport-1-a-title-heading" style="width:199px;height:40px;font-size:32px;line-height:40px">DASHBOARD</h2>
+  </div>
+
+  <!-- C: wrapped paragraph clipped by a card that is the last thing in its column (real slack below) -->
+  <div id="viewport-1-a-note" class="card" style="position:absolute;left:80px;top:560px;width:360px;height:44px;overflow:hidden;padding:12px">
+    <p id="viewport-1-a-note-text" class="text" style="width:336px;height:auto;font-size:15px;line-height:20px;white-space:normal">Wellness exam completed. Mild gingivitis noted and discussed a dental cleaning at the next visit.</p>
+  </div>
+
+</section>