@12ui/design 0.2.48 → 0.2.49

package/prototype-kit/polish/polish.mjs

@@ -2,8 +2,8 @@
 // Polish stage: deterministic visual repair of a built prototype, one page at a time (pages are independent → parallel).
 // Usage: node polish/polish.mjs <protoDir> --out <outDir> [--inventory inventory.json --model model.json] [--rules a,b] [--concurrency 4] [--report polish-report.json]
 //
-// For every real page: measure → run rules (in-browser, geometry-only) → apply overrides live → re-measure →
-// harm guard (reject any rule that adds overlap/clipping/cut or moves content beyond its declared cap) →
+// For every real page: measure → run rules in-browser → apply overrides live → re-measure →
+// harm guard (reject any rule that adds geometry/containment harm, loses a reachable action, or exceeds its cap) →
 // write polish/<unit>.css + <link> into the page copy. Nothing is redrawn; only per-id CSS overrides are emitted.
 import fs from 'node:fs';
 import path from 'node:path';
@@ -11,7 +11,7 @@ import { chromium } from '@playwright/test';
 import { startStaticServer } from '../lib/static-server.mjs';
 import { measurePage, sourceItemsFor, settleFonts } from './measure.mjs';
 import { loadRules } from './rules/index.mjs';
-import { applyOverridesScript, overridesToCss, mergeOverrides } from './overrides.mjs';
+import { applyOverridesScript, overridesToCss, mergeOverrides, partitionProtectedShellOverridesScript } from './overrides.mjs';
 import { structureHarm } from './harm.mjs';
 import { probeSeams } from './ground-probe.mjs';
 import { pageRuleRecords, summarizePolishReport } from './report.mjs';
@@ -59,6 +59,9 @@ export async function polishPrototype({
     try {
       const sectionIds = model ? unit.states.map((s) => model.states.find((st) => st.stateId === s)?.sectionId).filter(Boolean) : [];
       const sourceItems = inventory && sectionIds.length ? sourceItemsFor(inventory, sectionIds) : null;
+      const protectedShellIds = [...new Set((unit.shellBands || []).flatMap((band) => (
+        (band.regions || []).filter((region) => (region.consistencyStatus || 'canonical') === 'canonical').map((region) => region.shellId)
+      )).filter(Boolean))];
       await page.goto(`${base}/${unit.id}.html`, { waitUntil: 'networkidle', timeout: 30_000 });
       await settleFonts(page);
       const before = await measurePage(page, { sourceItems });
@@ -69,15 +72,15 @@ export async function polishPrototype({
       const harmed = (after, ruleSet) => {
         const newOf = (kind) => (after.overflow.filter((o) => o.kind === kind).length) - (before.overflow.filter((o) => o.kind === kind).length);
         const cap = Math.max(0, ...ruleSet.map((p) => p.rule.maxShift || 0));
-        // rules that declare block moves (left-rail) change the horizontal gaps beside the rows they move by design
-        const exempt = new Set(ruleSet.filter((p) => p.rule.movesBlocks).flatMap((p) => p.overrides.map((o) => o.id)));
         // A spacing rule may change only the exact before->after gaps it declares in seam metadata. Every other
         // vertical sibling gap remains protected by the ordinary harm guard.
-        const exemptGaps = new Set(ruleSet.flatMap((p) => p.overrides.map((o) => o.meta?.seam).filter(Boolean).flatMap((s) => (s.beforePeers || [s.before]).map((beforeId) => `${beforeId}|${s.after}`))));
-        const st = structureHarm(before, after, exempt, exemptGaps);
+        const declaredGaps = new Set(ruleSet.filter((p) => p.rule.name === 'section-breathing').flatMap((p) => p.overrides.map((o) => o.meta?.seam).filter(Boolean).flatMap((s) => (s.beforePeers || [s.before]).map((beforeId) => `${beforeId}|${s.after}`))));
+        const st = structureHarm(before, after, declaredGaps);
         return {
           misaligned: st.misaligned.length > 0,
           spacing: st.spacing.length > 0,
+          containment: st.containment.length > 0,
+          'reachable-actions': st.unreachableActions.length > 0,
           overlap: after.counts.overlap - before.counts.overlap > HARM.newOverlap,
           escape: newOf('escape') > HARM.newEscape,
           cut: newOf('cut') > HARM.newCut,
@@ -92,9 +95,17 @@ export async function polishPrototype({
         const proposals = [];
         for (const rule of ruleSet) {
           const proposed = await page.evaluate(rule.browserFn(), { metrics, params: rule.params || {} });
+          const partition = protectedShellIds.length
+            ? await page.evaluate(partitionProtectedShellOverridesScript(), { overrides: proposed, shellIds: protectedShellIds })
+            : { allowed: proposed, protected: [] };
           const cap = rule.maxShift ?? 0; // each override is held to ITS rule's declared cap
-          const found = proposed.filter((o) => Math.abs(o.dx || 0) <= cap + 0.01 && Math.abs(o.dy || 0) <= cap + 0.01);
-          row.rules[rule.name] = { proposed: proposed.length, overCap: proposed.length - found.length };
+          const found = partition.allowed.filter((o) => Math.abs(o.dx || 0) <= cap + 0.01 && Math.abs(o.dy || 0) <= cap + 0.01);
+          row.rules[rule.name] = {
+            proposed: proposed.length,
+            overCap: partition.allowed.length - found.length,
+            ...(partition.protected.length ? { protectedShell: partition.protected.length } : {}),
+          };
+          if (partition.protected.length) row.rejected.push({ rule: rule.name, harm: ['canonical-shell'] });
           if (rule.recordsCensus) {
             row.rules[rule.name].census = await page.evaluate(rule.browserFn(), {
               metrics,
@@ -159,8 +170,9 @@ export async function polishPrototype({
         row.ground = verdict;
         if (!verdict.ok) {
           row.rejected.push({ rule: rule.name, harm: verdict.failures.map((f) => 'ground-' + f.kind) });
-          active = active.filter((a) => a !== p);
-          result = active.length ? await evaluate(active) : null;
+          const final = await accept(active.filter((a) => a !== p));
+          active = final.active;
+          result = final.result;
         }
       }
       if (result) {

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');