@12ui/design 0.2.48 → 0.2.50

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

@@ -1,14 +1,46 @@
 // 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.
+// Silent on: edges that are equal, further apart than NEAR (deliberate offsets), different kinds, or elements whose
+// before geometry declares vertical centering inside their immediate parent / containing control.
 export const name = 'align';
 export const maxShift = 6;
 
 export function browserFn() {
   return ({ metrics }) => {
+    // Population evidence (75 pages, 158 accepted align rule-parts; owner 2026-08-26): among the 14 vertical moves
+    // measurable inside declared buttons/circles/badges/chips, the centered cluster's inset imbalance is 0–1.024 px
+    // and the next observed value is 2.048 px. Keep the threshold between those clusters.
+    const CENTERED_INSET_TOLERANCE = 1.1;
+    const CENTERED_CONTAINER_SELECTOR = 'button, .button, .badge, .chip, .circle, [role="button"], [data-proto-action]';
     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 }; };
+    const verticalCenterContainer = (el) => {
+      const r = el.getBoundingClientRect();
+      const parent = el.parentElement;
+      if (!parent || !r.width || !r.height) return null;
+      const contains = (c) => c.left <= r.left + 0.25 && c.right >= r.right - 0.25
+        && c.top <= r.top + 0.25 && c.bottom >= r.bottom - 0.25;
+      // The relationship needs a declared control/container fact. A generic flex parent or painted surface is not
+      // enough: both occur around legitimate edge rows in the population and would turn this guard into suppression.
+      const ancestor = parent.closest(CENTERED_CONTAINER_SELECTOR);
+      const candidates = [...parent.children]
+        .filter((candidate) => candidate !== el && candidate.matches(CENTERED_CONTAINER_SELECTOR))
+        .map((candidate) => ({ el: candidate, rect: candidate.getBoundingClientRect() }))
+        .concat(ancestor ? [{ el: ancestor, rect: ancestor.getBoundingClientRect() }] : [])
+        .filter((candidate) => candidate.el !== el && contains(candidate.rect))
+        .sort((a, b) => a.rect.width * a.rect.height - b.rect.width * b.rect.height);
+      const container = candidates[0]?.el;
+      if (!container) return null;
+      const c = container.getBoundingClientRect();
+      if (!contains(c)) return null;
+      const topInset = r.top - c.top;
+      const bottomInset = c.bottom - r.bottom;
+      return topInset >= -0.5 && bottomInset >= -0.5
+        && Math.abs(topInset - bottomInset) <= CENTERED_INSET_TOLERANCE
+        ? container
+        : null;
+    };
     // 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();
@@ -41,6 +73,38 @@ export function browserFn() {
       }
       return false;
     };
+    // Unlike transform, positioned insets do not create a stacking context around a container's independently
+    // z-indexed descendants. Preserve the target's positioning mode and existing inset, and stay silent when a static
+    // target cannot be nudged without changing layout semantics.
+    const insetNudge = (el, horizontal, visualDelta) => {
+      const style = getComputedStyle(el);
+      if (style.position === 'static') return null;
+      const primary = horizontal ? 'left' : 'top';
+      const opposite = horizontal ? 'right' : 'bottom';
+      const dimension = horizontal ? 'width' : 'height';
+      const rect = el.getBoundingClientRect();
+      const layoutSpan = Number.parseFloat(style[dimension]);
+      const visualSpan = horizontal ? rect.width : rect.height;
+      const scale = layoutSpan > 0 && visualSpan > 0 ? visualSpan / layoutSpan : 1;
+      const d = visualDelta / scale;
+      const current = Number.parseFloat(style[primary]);
+      const anchored = Number.parseFloat(style[opposite]);
+      // With both insets resolved, moving only one inset resizes the box. Width preservation has an explicit
+      // zoom/constrained fixture. For vertical movement, shift both insets in opposite directions instead: that keeps
+      // the declared height relationship without publishing an unproven height:...!important lock.
+      const constrainedPosition = style.position === 'absolute' || style.position === 'fixed';
+      const doublyConstrained = constrainedPosition && Number.isFinite(current) && Number.isFinite(anchored) && Number.isFinite(layoutSpan);
+      const preserveSize = horizontal && doublyConstrained
+        ? { [dimension]: `${+layoutSpan.toFixed(2)}px` }
+        : {};
+      if (!horizontal && doublyConstrained) return {
+        [primary]: `${+(current + d).toFixed(2)}px`,
+        [opposite]: `${+(anchored - d).toFixed(2)}px`,
+      };
+      if (Number.isFinite(current)) return { ...preserveSize, [primary]: `${+(current + d).toFixed(2)}px` };
+      if (Number.isFinite(anchored)) return { ...preserveSize, [opposite]: `${+(anchored - d).toFixed(2)}px` };
+      return { [primary]: `${+d.toFixed(2)}px` };
+    };
     const out = [];
     for (const [key, g] of groups) {
       const axis = key.split('|')[1];
@@ -57,9 +121,15 @@ export function browserFn() {
           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 target = document.getElementById(id);
+            if (breaksColumn(target, 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 });
+            // Top/bottom/center edge repair cannot trade away a declared centre relationship. Aligning the containing
+            // control itself remains available; nudging only its centered child does not.
+            if (!horizontal && verticalCenterContainer(target)) continue;
+            const css = insetNudge(target, horizontal, d);
+            if (!css) continue;
+            out.push({ id, rule: 'align', reason: `${axis} ${v.toFixed(1)}→${anchor}`, dx: horizontal ? d : 0, dy: horizontal ? 0 : d, motion: 'inset', css });
           }
         }
         i = j + 1;

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

@@ -14,11 +14,10 @@
 //            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.
+// overlap, cut, escape, parent-containment breach, broken column, changed sibling gap, or off-center fit. No moving
+// rule is exempt from the shared guard.
 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() {

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

@@ -11,7 +11,6 @@
 // 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;

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

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

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

@@ -4,11 +4,14 @@ 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}
+.action{position:absolute;right:16px;bottom:16px;z-index:100;width:96px;height:32px}
+.canvas-sibling{position:absolute;left:100px;top:100px;z-index:50;width:948px;height:204px;background:rgba(255,255,255,.001)}
 </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-2" class="card" style="margin-top:1.02px"><span id="viewport-1-a-cards-card-2-text" class="text">Beta</span><button id="viewport-1-a-cards-card-2-action" class="action" data-proto-action="modal">Open</button></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>
+  <div class="canvas-sibling"></div>
 </section>

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

@@ -25,4 +25,12 @@ section{position:relative;width:1536px;height:1024px;background:#fff}
     <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>
+  <!-- Owner-found must-stay-silent pair: the icons' top edges differ by 2 px, but each icon is vertically centered
+       inside its containing button. Align must preserve that stronger relation instead of snapping their top edges. -->
+  <div id="viewport-1-a-centered-controls" style="position:absolute;left:760px;top:400px;width:116px;height:44px">
+    <button id="viewport-1-a-centered-controls-button-1" class="button" style="position:absolute;left:0;top:0;width:40px;height:40px;border:0;border-radius:20px;background:#dfeacc"></button>
+    <span id="viewport-1-a-centered-controls-icon-1" class="icon" style="position:absolute;left:12px;top:12px;width:16px;height:16px;background:#56714a"></span>
+    <div id="viewport-1-a-centered-controls-circle-2" class="circle" style="position:absolute;left:72px;top:0;width:44px;height:44px;border-radius:22px;background:#dfeacc"></div>
+    <span id="viewport-1-a-centered-controls-icon-2" class="icon" style="position:absolute;left:86px;top:14px;width:16px;height:16px;background:#56714a"></span>
+  </div>
 </section>

package/prototype-kit/polish/tests/fixtures/align/zoom-constrained.html

@@ -0,0 +1,17 @@
+<!doctype html><meta charset="utf-8"><style>
+*{margin:0;padding:0;box-sizing:border-box}body{font-family:system-ui}.zoom{zoom:.75}.card,.box{background:#f3f3f3;border:1px solid #ddd}.text{position:absolute;left:12px;top:12px}.row{position:relative;display:flex;gap:20px;margin:80px}.card{position:relative;width:240px;height:100px}.stack{position:relative;width:1536px;height:500px}.box{position:absolute;right:100px;height:60px}
+</style>
+<div class="zoom"><section id="viewport-1-a" style="position:relative;width:1536px;height:300px"><div id="viewport-1-a-row" class="row">
+  <div id="viewport-1-a-card-1" class="card"><span id="viewport-1-a-card-1-text" class="text">One</span></div>
+  <div id="viewport-1-a-card-2" class="card" style="margin-top:2px"><span id="viewport-1-a-card-2-text" class="text">Two</span></div>
+  <div id="viewport-1-a-card-3" class="card" style="margin-top:4px"><span id="viewport-1-a-card-3-text" class="text">Three</span></div>
+</div></section></div>
+<section id="viewport-2-a" class="stack">
+  <div id="viewport-2-a-box-1" class="box" style="left:100px;top:80px"><span id="viewport-2-a-box-1-text" class="text">One</span></div>
+  <div id="viewport-2-a-box-2" class="box" style="left:102px;top:180px"><span id="viewport-2-a-box-2-text" class="text">Two</span></div>
+  <div id="viewport-2-a-box-3" class="box" style="left:104px;top:280px"><span id="viewport-2-a-box-3-text" class="text">Three</span></div>
+</section>
+<section id="viewport-3-a" style="position:relative;width:600px;height:120px">
+  <div id="viewport-3-a-box-1" class="box" style="position:absolute;left:80px;top:20px;bottom:20px;width:100px;height:auto"><span id="viewport-3-a-box-1-text" class="text">Anchor</span></div>
+  <div id="viewport-3-a-box-2" class="box" style="position:absolute;left:220px;top:22px;bottom:18px;width:100px;height:auto"><span id="viewport-3-a-box-2-text" class="text">Stray</span></div>
+</section>

package/prototype-kit/polish/tests/fixtures/harm/left-rail-contained.html

@@ -0,0 +1,16 @@
+<!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}.reference,.inbox{position:absolute;left:0;width:1536px}.text{position:absolute;white-space:nowrap}.inbox{left:64px;width:440px;height:490px}.inbox .text{left:0;width:400px;height:44px;padding:12px;background:#f5f5f2;border:1px solid #ddd}
+</style><section id="viewport-1-a">
+  <div id="viewport-1-a-reference-1" class="reference" style="top:20px;height:40px"><p id="viewport-1-a-reference-1-text" class="text" style="left:80px;top:0">Inbox</p></div>
+  <div id="viewport-1-a-reference-2" class="reference" style="top:70px;height:40px"><p id="viewport-1-a-reference-2-text" class="text" style="left:80px;top:0">Assigned</p></div>
+  <div id="viewport-1-a-reference-3" class="reference" style="top:120px;height:40px"><p id="viewport-1-a-reference-3-text" class="text" style="left:80px;top:0">Resolved</p></div>
+  <div id="viewport-1-a-inbox" class="inbox" style="top:190px">
+    <button id="viewport-1-a-inbox-row-1" class="text" data-proto-action="navigate" style="top:0">Action one</button>
+    <button id="viewport-1-a-inbox-row-2" class="text" data-proto-action="navigate" style="top:60px">Action two</button>
+    <button id="viewport-1-a-inbox-row-3" class="text" data-proto-action="navigate" style="top:120px">Action three</button>
+    <button id="viewport-1-a-inbox-row-4" class="text" data-proto-action="navigate" style="top:180px">Action four</button>
+    <button id="viewport-1-a-inbox-row-5" class="text" data-proto-action="navigate" style="top:240px">Action five</button>
+    <button id="viewport-1-a-inbox-row-6" class="text" data-proto-action="navigate" style="top:300px">Action six</button>
+    <button id="viewport-1-a-inbox-row-7" class="text" data-proto-action="navigate" style="top:360px">Action seven</button>
+  </div>
+</section>

package/prototype-kit/polish/tests/fixtures/harm/left-rail-overflow.html

@@ -0,0 +1,16 @@
+<!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}.reference,.inbox{position:absolute;left:0;width:1536px}.text{position:absolute;white-space:nowrap}.inbox{left:64px;width:400px;height:490px}.inbox .text{left:0;width:400px;height:44px;padding:12px;background:#f5f5f2;border:1px solid #ddd}
+</style><section id="viewport-1-a">
+  <div id="viewport-1-a-reference-1" class="reference" style="top:20px;height:40px"><p id="viewport-1-a-reference-1-text" class="text" style="left:80px;top:0">Inbox</p></div>
+  <div id="viewport-1-a-reference-2" class="reference" style="top:70px;height:40px"><p id="viewport-1-a-reference-2-text" class="text" style="left:80px;top:0">Assigned</p></div>
+  <div id="viewport-1-a-reference-3" class="reference" style="top:120px;height:40px"><p id="viewport-1-a-reference-3-text" class="text" style="left:80px;top:0">Resolved</p></div>
+  <div id="viewport-1-a-inbox" class="inbox" style="top:190px">
+    <button id="viewport-1-a-inbox-row-1" class="text" data-proto-action="navigate" style="top:0">Action one</button>
+    <button id="viewport-1-a-inbox-row-2" class="text" data-proto-action="navigate" style="top:60px">Action two</button>
+    <button id="viewport-1-a-inbox-row-3" class="text" data-proto-action="navigate" style="top:120px">Action three</button>
+    <button id="viewport-1-a-inbox-row-4" class="text" data-proto-action="navigate" style="top:180px">Action four</button>
+    <button id="viewport-1-a-inbox-row-5" class="text" data-proto-action="navigate" style="top:240px">Action five</button>
+    <button id="viewport-1-a-inbox-row-6" class="text" data-proto-action="navigate" style="top:300px">Action six</button>
+    <button id="viewport-1-a-inbox-row-7" class="text" data-proto-action="navigate" style="top:360px">Action seven</button>
+  </div>
+</section>

package/prototype-kit/polish/tests/fixtures/harm/nested-actions.html

@@ -0,0 +1,6 @@
+<!doctype html><meta charset="utf-8"><style>
+*{box-sizing:border-box}section{position:relative;width:1536px;height:1024px}#viewport-1-a-outer,#viewport-1-a-stacked{position:absolute;left:100px;width:240px;height:80px;background:#ddd}#viewport-1-a-outer{top:100px}#viewport-1-a-inner{position:absolute;inset:0;width:100%;height:100%;z-index:2}#viewport-1-a-stacked{top:220px}#viewport-1-a-stacked-button{width:100%;height:100%}
+</style><section id="viewport-1-a">
+  <div id="viewport-1-a-outer" role="button" data-proto-action="modal" tabindex="0"><button id="viewport-1-a-inner" data-proto-action="dropdown">Inner action</button></div>
+  <div id="viewport-1-a-stacked" data-proto-action="modal"><button id="viewport-1-a-stacked-button">Plain pointer surface</button></div>
+</section>

package/prototype-kit/polish/tests/fixtures/harm/unidentified-parent.html

@@ -0,0 +1,3 @@
+<!doctype html><meta charset="utf-8"><style>
+*{margin:0;padding:0;box-sizing:border-box}section{position:relative;width:1536px;height:1024px}.wrapper{position:absolute;left:100px;top:100px;width:400px;height:100px}.row{position:absolute;left:0;top:0;width:400px;height:60px;background:#eee}
+</style><section id="viewport-1-a"><div class="wrapper"><div id="viewport-1-a-row" class="row">Row</div></div></section>

package/prototype-kit/polish/tests/fixtures/shell-seam/fire.html

@@ -3,7 +3,7 @@
 section{position:relative;width:1536px;height:1024px;background:#fff}
 .rail{position:absolute;left:0;top:0;width:220px;height:1024px;background:#f6f4f0;padding:24px 0 0 16px}
 .btn{position:relative;width:214px;height:43px;background:#245;border-radius:8px;margin-top:40px}
-.btn .text{position:absolute;left:0;top:12px;width:214px;text-align:center;color:#fff;font-size:15px}
+.btn .text{position:absolute;left:0;top:12px;width:100%;text-align:center;color:#fff;font-size:15px}
 .nav{position:relative;margin-top:24px;font-size:15px;width:99px;height:18px}
 .foot{position:absolute;left:16px;top:1040px;width:120px;height:14px;font-size:11px;color:#666}
 .content{position:absolute;left:270px;top:40px;width:1200px;height:900px;background:#fff;border:1px solid #ddd}

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

@@ -2,10 +2,15 @@
 // Paired cases for the structure harm guard (harm.mjs): a synthetic override that breaks an icon column or collapses
 // the rail/content gutter MUST be flagged; a rhythm-sized nudge (≤ 6 px) on a gap MUST NOT.
 import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
 import { chromium } from '@playwright/test';
 import { measurePage } from '../measure.mjs';
-import { applyOverridesScript } from '../overrides.mjs';
+import { applyOverridesScript, mergeOverrides, overridesToCss, partitionProtectedShellOverridesScript } from '../overrides.mjs';
 import { structureHarm } from '../harm.mjs';
+import * as align from '../rules/align.mjs';
+import * as leftRail from '../rules/left-rail.mjs';
+import { polishPrototype } from '../polish.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 } });
@@ -29,7 +34,7 @@ const gapBefore = await measurePage(page, {});
 await page.evaluate(applyOverridesScript(), '#viewport-1-a-footer{transform:translate(0,32px)!important}');
 const gapAfter = await measurePage(page, {});
 const undeclaredGap = structureHarm(gapBefore, gapAfter);
-const declaredGap = structureHarm(gapBefore, gapAfter, new Set(), new Set(['viewport-1-a-content|viewport-1-a-footer']));
+const declaredGap = structureHarm(gapBefore, gapAfter, new Set(['viewport-1-a-content|viewport-1-a-footer']));
 const okDeclaredGap = undeclaredGap.spacing.length > 0 && declaredGap.spacing.length === 0;
 if (!okDeclaredGap) failures++;
 console.log(`${okDeclaredGap ? 'ok  ' : 'FAIL'} harm/declared-gap: undeclared=${undeclaredGap.spacing.length} declared=${declaredGap.spacing.length}`);
@@ -47,6 +52,130 @@ const pairs = mo.overlap.map((o) => [o.a, o.b].sort().join('|'));
 const okBtn = pairs.length === 1 && pairs[0] === 'viewport-1-a-hero-eyebrow|viewport-1-a-hero-stray';
 if (!okBtn) failures++;
 console.log(`${okBtn ? 'ok  ' : 'FAIL'} overlap/button-over-text: ${JSON.stringify(pairs)} (expected eyebrow|stray only)`);
+// The page-gallery failure class: a positioned card is not a stacking context until align adds transform. Its high-z
+// action can initially paint over a canvas sibling, then becomes trapped underneath it. The hit-test guard must catch
+// that legacy emission; align's current inset emission must preserve reachability and contain no transform.
+await page.goto('file://' + path.join(here, 'fixtures/align/fire.html'), { waitUntil: 'load' });
+const alignBefore = await measurePage(page, {});
+const alignOverrides = await page.evaluate(align.browserFn(), { metrics: alignBefore, params: align.params });
+const protectedAlign = await page.evaluate(partitionProtectedShellOverridesScript(), {
+  overrides: alignOverrides,
+  shellIds: ['viewport-1-a-cards'],
+});
+const legacyAlignCss = alignOverrides.map((o) => `#${o.id}{transform:translate(${o.dx || 0}px,${o.dy || 0}px)!important}`).join('\n');
+await page.evaluate(applyOverridesScript(), legacyAlignCss);
+const alignLegacyAfter = await measurePage(page, {});
+const legacyAlignHarm = structureHarm(alignBefore, alignLegacyAfter);
+const fixedAlignCss = overridesToCss(mergeOverrides(alignOverrides));
+await page.evaluate(applyOverridesScript(), fixedAlignCss);
+const alignFixedAfter = await measurePage(page, {});
+const fixedAlignHarm = structureHarm(alignBefore, alignFixedAfter);
+const okAlignHit = alignBefore.counts.reachableActions === 1
+  && alignLegacyAfter.counts.reachableActions === 0
+  && legacyAlignHarm.unreachableActions.length === 1
+  && alignFixedAfter.counts.reachableActions === 1
+  && fixedAlignHarm.unreachableActions.length === 0
+  && !fixedAlignCss.includes('transform:')
+  && !fixedAlignCss.includes('height:')
+  && protectedAlign.allowed.length === 0
+  && protectedAlign.protected.length === 2;
+if (!okAlignHit) failures++;
+console.log(`${okAlignHit ? 'ok  ' : 'FAIL'} harm/align-hit-test: legacy reachable ${alignBefore.counts.reachableActions}→${alignLegacyAfter.counts.reachableActions}, fixed ${alignBefore.counts.reachableActions}→${alignFixedAfter.counts.reachableActions}, fixed transform=${fixedAlignCss.includes('transform:')}, canonical-shell blocked=${protectedAlign.protected.length}`);
+// Insets use layout coordinates, while alignment findings use visual coordinates. Under CSS zoom the emitted inset
+// must divide by the visual scale, and a left+right constrained target must retain its used width.
+await page.goto('file://' + path.join(here, 'fixtures/align/zoom-constrained.html'), { waitUntil: 'load' });
+const scaledBefore = await measurePage(page, {});
+const scaledWidthsBefore = await page.evaluate(() => ['viewport-2-a-box-2', 'viewport-2-a-box-3'].map((id) => document.getElementById(id).getBoundingClientRect().width));
+const verticalHeightsBefore = await page.evaluate(() => ['viewport-3-a-box-1', 'viewport-3-a-box-2'].map((id) => document.getElementById(id).getBoundingClientRect().height));
+const scaledOverrides = await page.evaluate(align.browserFn(), { metrics: scaledBefore, params: align.params });
+const scaledCss = overridesToCss(mergeOverrides(scaledOverrides));
+await page.evaluate(applyOverridesScript(), scaledCss);
+const scaledAfter = await measurePage(page, {});
+const scaledWidthsAfter = await page.evaluate(() => ['viewport-2-a-box-2', 'viewport-2-a-box-3'].map((id) => document.getElementById(id).getBoundingClientRect().width));
+const verticalHeightsAfter = await page.evaluate(() => ['viewport-3-a-box-1', 'viewport-3-a-box-2'].map((id) => document.getElementById(id).getBoundingClientRect().height));
+const verticalTop = await page.evaluate(() => ['viewport-3-a-box-1', 'viewport-3-a-box-2'].map((id) => document.getElementById(id).getBoundingClientRect().top));
+const zoomTop = await page.evaluate(() => ['viewport-1-a-card-1', 'viewport-1-a-card-2', 'viewport-1-a-card-3'].map((id) => document.getElementById(id).getBoundingClientRect().top));
+const constrained = scaledOverrides.filter((override) => override.id?.startsWith('viewport-2-a-box-') && override.id !== 'viewport-2-a-box-1');
+const verticalConstrained = scaledOverrides.find((override) => override.id === 'viewport-3-a-box-2');
+const okScaledAlign = Math.max(...zoomTop) - Math.min(...zoomTop) < 0.2
+  && scaledWidthsAfter.every((width, index) => Math.abs(width - scaledWidthsBefore[index]) < 0.2)
+  && constrained.length === 2
+  && constrained.every((override) => override.css.width)
+  && verticalConstrained?.css.top === '20px'
+  && verticalConstrained?.css.bottom === '20px'
+  && verticalConstrained?.css.height == null
+  && !scaledCss.includes('height:')
+  && Math.max(...verticalTop) - Math.min(...verticalTop) < 0.2
+  && verticalHeightsAfter.every((height, index) => Math.abs(height - verticalHeightsBefore[index]) < 0.2)
+  && structureHarm(scaledBefore, scaledAfter).unreachableActions.length === 0;
+if (!okScaledAlign) failures++;
+console.log(`${okScaledAlign ? 'ok  ' : 'FAIL'} align/zoom-constrained: zoom top spread=${(Math.max(...zoomTop) - Math.min(...zoomTop)).toFixed(2)} width deltas=${scaledWidthsAfter.map((width, index) => (width - scaledWidthsBefore[index]).toFixed(2)).join(',')} vertical top spread=${(Math.max(...verticalTop) - Math.min(...verticalTop)).toFixed(2)} height lock=${scaledCss.includes('height:')}`);
+// Owner-found centering pair: measurement must expose the tempting 2 px top-edge near miss, while align stays silent
+// because each icon is vertically centered in its containing circle button.
+await page.goto('file://' + path.join(here, 'fixtures/align/silent.html'), { waitUntil: 'load' });
+const centeredBefore = await measurePage(page, {});
+const centeredIds = new Set(['viewport-1-a-centered-controls-icon-1', 'viewport-1-a-centered-controls-icon-2']);
+const centeredNearMiss = centeredBefore.alignment.some((pair) => pair.axis === 'top' && centeredIds.has(pair.a) && centeredIds.has(pair.b));
+const centeredOverrides = await page.evaluate(align.browserFn(), { metrics: centeredBefore, params: align.params });
+const centeredTouched = centeredOverrides.filter((override) => centeredIds.has(override.id));
+const okCenteredAlign = centeredNearMiss && centeredTouched.length === 0;
+if (!okCenteredAlign) failures++;
+console.log(`${okCenteredAlign ? 'ok  ' : 'FAIL'} align/centered-control-silent: near-miss=${centeredNearMiss} overrides=${centeredTouched.length}`);
+// The autopilot-inbox failure shape: the actual left-rail rule moves seven full-width rows beyond their direct parent.
+// A wider parent is the paired healthy case: the same seven proposals remain contained and the guard stays silent.
+for (const [fixture, expectedHarm] of [['left-rail-overflow.html', 7], ['left-rail-contained.html', 0]]) {
+  await page.goto('file://' + path.join(here, 'fixtures/harm', fixture), { waitUntil: 'load' });
+  const railBefore = await measurePage(page, {});
+  const railOverrides = await page.evaluate(leftRail.browserFn(), { metrics: railBefore, params: leftRail.params });
+  await page.evaluate(applyOverridesScript(), overridesToCss(mergeOverrides(railOverrides)));
+  const railAfter = await measurePage(page, {});
+  const railHarm = structureHarm(railBefore, railAfter);
+  const okRail = railOverrides.length === 7 && railHarm.containment.length === expectedHarm;
+  if (!okRail) failures++;
+  console.log(`${okRail ? 'ok  ' : 'FAIL'} harm/${fixture.replace('.html', '')}: proposals=${railOverrides.length} containment=${railHarm.containment.length}`);
+}
+// Exercise the production acceptance loop as well as the pure comparator: the overflow case must publish unchanged
+// with left-rail reverted, while the contained twin accepts all seven moves.
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), '12ui-polish-harm-'));
+  try {
+    for (const [fixture, status, accepted] of [['left-rail-overflow.html', 'reverted', 0], ['left-rail-contained.html', 'fired', 7]]) {
+      const stem = fixture.replace('.html', '');
+      const source = path.join(root, `${stem}-source`); const out = path.join(root, `${stem}-out`);
+      fs.mkdirSync(source);
+      fs.copyFileSync(path.join(here, 'fixtures/harm', fixture), path.join(source, `${stem}.html`));
+      fs.writeFileSync(path.join(source, 'proto-manifest.json'), JSON.stringify({ units: [{ id: stem, states: [] }], holdings: [] }));
+      const report = await polishPrototype({ protoDir: source, outDir: out, ruleNames: ['left-rail'], concurrency: 1 });
+      const record = report.pages[0].ruleRecords.find((entry) => entry.rule === 'left-rail');
+      const okAcceptance = record?.status === status && record.accepted === accepted
+        && (status !== 'reverted' || record.reasons?.includes('containment'));
+      if (!okAcceptance) failures++;
+      console.log(`${okAcceptance ? 'ok  ' : 'FAIL'} harm/${stem}-acceptance: status=${record?.status} accepted=${record?.accepted} reasons=${record?.reasons?.join(',') || 'none'}`);
+    }
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+// Interaction identity is the nearest interactive ancestor, not merely DOM containment. An outer action completely
+// covered by a nested action is unreachable even though element.contains(elementFromPoint(...)) would be true.
+await page.goto('file://' + path.join(here, 'fixtures/harm/nested-actions.html'), { waitUntil: 'load' });
+const nestedActions = await measurePage(page, {});
+const nestedById = new Map(nestedActions.actions.map((action) => [action.id, action.reachable]));
+const okNested = nestedById.get('viewport-1-a-outer') === false
+  && nestedById.get('viewport-1-a-inner') === true
+  && nestedById.get('viewport-1-a-stacked') === true
+  && !nestedById.has('viewport-1-a-stacked-button');
+if (!okNested) failures++;
+console.log(`${okNested ? 'ok  ' : 'FAIL'} harm/nested-action-identity: outer=${nestedById.get('viewport-1-a-outer')} inner=${nestedById.get('viewport-1-a-inner')} wrapper-over-native=${nestedById.get('viewport-1-a-stacked')}`);
+// An ordinary un-IDed layout wrapper still owns containment and cannot be a blind spot.
+await page.goto('file://' + path.join(here, 'fixtures/harm/unidentified-parent.html'), { waitUntil: 'load' });
+const anonymousBefore = await measurePage(page, {});
+await page.evaluate(applyOverridesScript(), '#viewport-1-a-row{transform:translate(20px,0)!important}');
+const anonymousAfter = await measurePage(page, {});
+const anonymousHarm = structureHarm(anonymousBefore, anonymousAfter);
+const okAnonymous = anonymousHarm.containment.length === 1 && anonymousHarm.containment[0].id === 'viewport-1-a-row';
+if (!okAnonymous) failures++;
+console.log(`${okAnonymous ? 'ok  ' : 'FAIL'} harm/unidentified-parent: containment=${anonymousHarm.containment.length}`);
 // contrast refinement: declared brand colour keeps its hue (orange → readable orange, not black); readable declared
 // colour untouched; a hue that cannot reach the threshold falls back and records the fact
 {

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

@@ -5,6 +5,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { chromium } from '@playwright/test';
 import { measurePage } from '../measure.mjs';
+import { structureHarm } from '../harm.mjs';
 import { loadRules, ALL } from '../rules/index.mjs';
 import { applyOverridesScript, overridesToCss, mergeOverrides } from '../overrides.mjs';
 
@@ -31,8 +32,12 @@ for (const rule of rules) {
       const merged = mergeOverrides(found);
       await page.evaluate(applyOverridesScript(), overridesToCss(merged));
       const after = await measurePage(page, {});
-      harm = after.counts.overlap > before.counts.overlap || after.overflow.filter((o) => o.kind !== 'spill').length > before.overflow.filter((o) => o.kind !== 'spill').length;
-      detail += `; overlap ${before.counts.overlap}→${after.counts.overlap}, overflow ${before.counts.overflow}→${after.counts.overflow}, align ${before.counts.alignment}→${after.counts.alignment}, ws ${before.counts.whitespace}→${after.counts.whitespace}`;
+      const structural = structureHarm(before, after);
+      harm = after.counts.overlap > before.counts.overlap
+        || after.overflow.filter((o) => o.kind !== 'spill').length > before.overflow.filter((o) => o.kind !== 'spill').length
+        || structural.containment.length > 0
+        || structural.unreachableActions.length > 0;
+      detail += `; overlap ${before.counts.overlap}→${after.counts.overlap}, overflow ${before.counts.overflow}→${after.counts.overflow}, containment ${before.counts.containment}→${after.counts.containment} (new ${structural.containment.length}), reachable ${before.counts.reachableActions}→${after.counts.reachableActions} (lost ${structural.unreachableActions.length}), align ${before.counts.alignment}→${after.counts.alignment}, ws ${before.counts.whitespace}→${after.counts.whitespace}`;
       const expectFile = path.join(dir, 'expect.json');
       if (fs.existsSync(expectFile)) {
         const expect = JSON.parse(fs.readFileSync(expectFile, 'utf8'));

package/prototype-kit/runtime/proto.js

@@ -10,7 +10,10 @@
 
   // ---- content layer: replace text nodes from content/<state>.json (or content-<set>/)
   async function hydrate() {
-    if (!cfg.contentFile) return;
+    // Direct-file review already carries the same baked-in copy. Browsers do
+    // not permit fetch(file://...), and attempting it emits a console error
+    // even when the rejected promise is caught.
+    if (!cfg.contentFile || location.protocol === 'file:') return;
     const dir = contentSet ? `content-${contentSet}` : 'content';
     try {
       const res = await fetch(`${dir}/${cfg.contentFile}`, { cache: 'no-store' });

package/prototype-kit/tests/adversarial-runtime.mjs

@@ -130,6 +130,7 @@ const interactionPage = (file) => interactionRuntime.pages.find((page) => page.f
 const interactionReachability = {
   occludedExactFailure: interactionPage('occluded-saved-journeys.html')?.dropdown,
   ordinaryControl: interactionPage('ordinary-dropdown.html')?.dropdown,
+  reviewBottomControl: interactionPage('review-bottom-action.html')?.modal,
 };
 
 const blockingScratch = fs.mkdtempSync(path.join(os.tmpdir(), 'prototype-blocking-runtime-'));
@@ -194,6 +195,8 @@ if (process.argv.includes('--assert')) {
   assert.equal(interactionReachability.occludedExactFailure?.ok, true, 'must fire: the exact Saved Journeys dropdown is scrolled clear of the fixed review framing before pointer hit-testing');
   assert.ok(interactionReachability.occludedExactFailure?.point?.y < 700, 'must fire: the exact initially occluded target is measured outside the review panel');
   assert.equal(interactionReachability.ordinaryControl?.ok, true, 'must stay silent: an ordinary already-visible dropdown remains pointer reachable');
+  assert.equal(interactionReachability.reviewBottomControl?.ok, true, 'must fire: a bottom-edge action receives temporary scroll clearance from fixed review chrome before hit-testing');
+  assert.ok(interactionReachability.reviewBottomControl?.point?.y < 800, 'must fire: the bottom-edge action is measured above the review panel');
   assert.notEqual(blockingVerification.status, 0, 'must fire: a claimed dropdown with broken pointer wiring still refuses publication');
   assert.match(blockingVerification.stderr, /Prototype runtime gate failed: 1 page\(s\) with broken dropdown\/modal interaction/, 'must fire: the refusal names the genuinely blocking interaction gate');
   assert.deepEqual(blockingAudit.interactionFailures, ['broken-interaction.html'], 'must stay silent: the blocking fixture identifies only the broken page');

package/prototype-kit/tests/align-rule-check.mjs

@@ -0,0 +1,105 @@
+import assert from 'node:assert/strict';
+import * as align from '../polish/rules/align.mjs';
+
+const rect = (left, top, width, height) => ({ left, top, width, height, right: left + width, bottom: top + height });
+
+export function checkAlignRule() {
+  const previousDocument = globalThis.document;
+  const previousGetComputedStyle = globalThis.getComputedStyle;
+  const elements = new Map();
+  const section = { getBoundingClientRect: () => rect(0, 0, 1536, 1024) };
+  const defaultStyle = {
+    position: 'static', left: 'auto', right: 'auto', top: 'auto', bottom: 'auto', width: 'auto', height: 'auto',
+    backgroundColor: 'rgba(0, 0, 0, 0)', backgroundImage: 'none',
+    borderTopWidth: '0px', borderRightWidth: '0px', borderBottomWidth: '0px', borderLeftWidth: '0px',
+  };
+  const element = (id, box, style = {}, { tagName = 'DIV', classes = [] } = {}) => {
+    const classSet = new Set(classes);
+    const el = {
+      id, tagName, parentElement: null, children: [], box, style: { ...defaultStyle, ...style },
+      classList: { contains: (name) => classSet.has(name) },
+      getBoundingClientRect: () => el.box,
+      closest: (selector) => selector.startsWith('section') ? section : null,
+      querySelectorAll: () => [],
+      contains: (candidate) => candidate === el,
+      matches: (selector) => (tagName === 'BUTTON' && selector.includes('button'))
+        || (classSet.has('button') && selector.includes('.button'))
+        || (classSet.has('badge') && selector.includes('.badge'))
+        || (classSet.has('chip') && selector.includes('.chip'))
+        || (classSet.has('circle') && selector.includes('.circle')),
+    };
+    elements.set(id, el);
+    return el;
+  };
+  const parent = (id, box, children) => {
+    const el = element(id, box);
+    el.children = children;
+    for (const child of children) child.parentElement = el;
+    return el;
+  };
+  const run = (alignment) => align.browserFn()({ metrics: { alignment, columns: [] } });
+
+  globalThis.document = { getElementById: (id) => elements.get(id) || null, body: section };
+  globalThis.getComputedStyle = (el) => el.style;
+  try {
+    const card1 = element('card-1', rect(0, 0, 100, 80), { position: 'relative', top: '0px', height: '80px' });
+    const card2 = element('card-2', rect(120, 1.02, 100, 80), { position: 'relative', top: '1.02px', height: '80px' });
+    const card3 = element('card-3', rect(240, 2.05, 100, 80), { position: 'relative', top: '2.05px', height: '80px' });
+    parent('stray-row', rect(0, 0, 400, 180), [card1, card2, card3]);
+    const fire = run([
+      { axis: 'top', a: 'card-1', b: 'card-2', delta: 1.02 },
+      { axis: 'top', a: 'card-1', b: 'card-3', delta: 2.05 },
+    ]);
+    assert.deepEqual(fire.map((override) => override.id), ['card-2', 'card-3'], 'must fire: genuine strays in an edge row still snap');
+
+    elements.clear();
+    const button1 = element('centered-button-1', rect(0, 0, 40, 40), { backgroundColor: 'rgb(220, 230, 210)' }, { tagName: 'BUTTON', classes: ['button'] });
+    const icon1 = element('centered-icon-1', rect(12, 12, 16, 16), { position: 'absolute', top: '12px', height: '16px' }, { classes: ['icon'] });
+    const button2 = element('centered-circle-2', rect(72, 0, 44, 44), { backgroundColor: 'rgb(220, 230, 210)' }, { classes: ['circle'] });
+    const icon2 = element('centered-icon-2', rect(86, 14, 16, 16), { position: 'absolute', top: '14px', height: '16px' }, { classes: ['icon'] });
+    parent('centered-controls', rect(0, 0, 116, 44), [button1, icon1, button2, icon2]);
+    const silent = run([{ axis: 'top', a: 'centered-icon-1', b: 'centered-icon-2', delta: 2 }]);
+    assert.deepEqual(silent, [], 'must stay silent: a centered icon keeps its button/circle relationship');
+
+    elements.clear();
+    const anchorButton = element('anchor-button', rect(0, 0, 40, 40), {}, { tagName: 'BUTTON', classes: ['button'] });
+    const centeredAnchor = element('centered-anchor-icon', rect(12, 12, 16, 16), { position: 'absolute', top: '12px', height: '16px' }, { classes: ['icon'] });
+    const ordinaryStray = element('ordinary-stray-icon', rect(80, 14, 16, 16), { position: 'absolute', top: '14px', height: '16px' }, { classes: ['icon'] });
+    parent('mixed-controls', rect(0, 0, 116, 44), [anchorButton, centeredAnchor, ordinaryStray]);
+    assert.deepEqual(
+      run([{ axis: 'top', a: 'centered-anchor-icon', b: 'ordinary-stray-icon', delta: 2 }]).map((override) => override.id),
+      ['ordinary-stray-icon'],
+      'must fire: an uncontained stray still snaps to a centered anchor',
+    );
+
+    elements.clear();
+    const boundaryAnchor = element('boundary-anchor-icon', rect(12, 12, 16, 16), { position: 'absolute', top: '12px', height: '16px' }, { classes: ['icon'] });
+    const boundaryTarget = element('boundary-target-icon', rect(86, 14, 16, 16), { position: 'absolute', top: '14px', height: '16px' }, { classes: ['icon'] });
+    const boundaryButton = element('boundary-button', rect(72, 0, 44, 45.024), {}, { tagName: 'BUTTON', classes: ['button'] });
+    parent('boundary-controls', rect(0, 0, 116, 46), [boundaryAnchor, boundaryButton, boundaryTarget]);
+    assert.deepEqual(
+      run([{ axis: 'top', a: 'boundary-anchor-icon', b: 'boundary-target-icon', delta: 2 }]),
+      [],
+      'must stay silent: 1.024px inset imbalance is inside the measured centered cluster',
+    );
+
+    boundaryButton.box = rect(72, 0, 44, 46.048);
+    const outsideBoundary = run([{ axis: 'top', a: 'boundary-anchor-icon', b: 'boundary-target-icon', delta: 2 }]);
+    assert.deepEqual(
+      outsideBoundary.map((override) => override.id),
+      ['boundary-target-icon'],
+      'must fire: 2.048px inset imbalance is outside the measured centered cluster',
+    );
+
+    elements.clear();
+    const box1 = element('constrained-box-1', rect(80, 20, 100, 80), { position: 'absolute', top: '20px', bottom: '20px', width: '100px', height: '80px' });
+    const box2 = element('constrained-box-2', rect(220, 22, 100, 80), { position: 'absolute', top: '22px', bottom: '18px', width: '100px', height: '80px' });
+    parent('constrained-row', rect(0, 0, 600, 120), [box1, box2]);
+    const constrained = run([{ axis: 'top', a: 'constrained-box-1', b: 'constrained-box-2', delta: 2 }]);
+    assert.equal(constrained.length, 1, 'must fire: a genuine constrained vertical stray still snaps');
+    assert.deepEqual(constrained[0].css, { top: '20px', bottom: '20px' }, 'must stay silent: align shifts paired insets and does not freeze height');
+  } finally {
+    globalThis.document = previousDocument;
+    globalThis.getComputedStyle = previousGetComputedStyle;
+  }
+}

package/prototype-kit/tests/fixtures/interaction-runtime/review-bottom-action.html

@@ -0,0 +1,8 @@
+<!doctype html><html><head><meta charset="utf-8"><link rel="stylesheet" href="../../../runtime/proto.css"><style>
+html,body{margin:0;width:1536px;height:1024px}.page{position:relative;width:1536px;height:1024px}.proto-review-framing{position:fixed;right:18px;bottom:18px;z-index:2147483646;width:430px;height:170px;background:#14161a}.control{position:absolute;left:1246px;top:921px;width:215px;height:59px}
+</style></head><body>
+<aside id="proto-review-framing" class="proto-review-framing">Prototype review</aside>
+<main class="page"><button id="review-bottom-modal" class="control" data-proto-action="modal" data-proto-modal='{"title":"Analyze my site?","body":"Confirm analysis.","confirm":"Analyze my site"}'>Analyze my site</button></main>
+<script id="proto-state" type="application/json">{"unit":"review-bottom-action","tokens":{},"contentFile":null}</script>
+<script src="../../../runtime/proto.js"></script>
+</body></html>