@12ui/design 0.2.47 → 0.2.49

package/prototype-kit/lib/shell-runtime-equivalence.mjs

@@ -0,0 +1,41 @@
+export const SHELL_RUNTIME_GEOMETRY_EPSILON_PX = 0.5;
+
+function geometryDelta(reference, candidate) {
+  if (!Array.isArray(reference) || !Array.isArray(candidate) || reference.length !== candidate.length) {
+    return Number.POSITIVE_INFINITY;
+  }
+  let maximum = 0;
+  for (let index = 0; index < reference.length; index++) {
+    const left = reference[index];
+    const right = candidate[index];
+    if (Array.isArray(left) || Array.isArray(right)) {
+      const nested = geometryDelta(left, right);
+      if (!Number.isFinite(nested)) return nested;
+      maximum = Math.max(maximum, nested);
+      continue;
+    }
+    if (!Number.isFinite(left) || !Number.isFinite(right)) return Number.POSITIVE_INFINITY;
+    maximum = Math.max(maximum, Math.abs(left - right));
+  }
+  return maximum;
+}
+
+/**
+ * Canonical shells must retain identical visible structure and styles. Browser
+ * layout geometry may differ by at most half a CSS pixel per node; that absorbs
+ * subpixel glyph measurement noise while remaining far below displaced-shell
+ * defects.
+ */
+export function compareCanonicalShellSamples(reference, candidate, epsilon = SHELL_RUNTIME_GEOMETRY_EPSILON_PX) {
+  if (reference.appearanceSignature !== candidate.appearanceSignature) {
+    return { equivalent: false, reason: 'appearance', maxGeometryDelta: null };
+  }
+  const visualDelta = geometryDelta(reference.visualGeometry, candidate.visualGeometry);
+  const shellDelta = geometryDelta(reference.shellGeometry, candidate.shellGeometry);
+  const maxGeometryDelta = Math.max(visualDelta, shellDelta);
+  return {
+    equivalent: maxGeometryDelta <= epsilon,
+    reason: maxGeometryDelta <= epsilon ? 'equivalent' : 'geometry',
+    maxGeometryDelta,
+  };
+}

package/prototype-kit/polish/harm.mjs

@@ -1,12 +1,17 @@
-// Structure the harm guard protects, computed from two measurements of the same page (before / after a rule set):
+// Structure and interaction state the harm guard protects, computed from two measurements of the same page
+// (before / after a rule set):
 //   misaligned — a same-kind sibling pair whose left (top) edges were exactly aligned before and are not after
 //                (an icon nudged out of its column, a nav label pulled off its list edge);
 //   spacing    — a consecutive sibling gap that changed by more than GAP_TOL px, unless one side was itself cut or
 //                escaped before (a stranded footer coming home is allowed to change its gap).
+//   containment  — an element newly leaves (or moves farther beyond) its direct parent;
+//   actions      — a semantic action that was pointer-reachable before is no longer reachable after.
 // Owner rule (2026-08-22): a repair that moves an icon out of its column or changes sibling spacing is harm.
+// Owner rule (2026-08-25): no moving rule is guard-exempt, and reachable actions may never be traded away.
 export const GAP_TOL = 6;
+export const CONTAINMENT_TOL = 0.5;
 
-export function structureHarm(before, after, exempt = new Set(), exemptGaps = new Set()) {
+export function structureHarm(before, after, declaredGaps = new Set()) {
   const colKey = (c) => `${c.axis}|${c.a}|${c.b}`;
   const beforeCols = new Set((before.columns || []).map(colKey));
   const afterCols = new Set((after.columns || []).map(colKey));
@@ -16,8 +21,25 @@ export function structureHarm(before, after, exempt = new Set(), exemptGaps = ne
   const spacing = (after.gaps || []).filter((g) => {
     const b = beforeGaps.get(`${g.axis}|${g.a}|${g.b}`);
     // a horizontal gap inside a fitted shell child is the fit's own declared change (name … chevron), not harm
-    const declaredGap = exemptGaps.has(`${g.a}|${g.b}`) || exemptGaps.has(`${g.b}|${g.a}`);
-    return b != null && Math.abs(g.gap - b) > GAP_TOL && !broken.has(g.a) && !broken.has(g.b) && !g.fit && !declaredGap && !(g.axis === 'h' && (exempt.has(g.a) || exempt.has(g.b)));
+    const declaredGap = declaredGaps.has(`${g.a}|${g.b}`) || declaredGaps.has(`${g.b}|${g.a}`);
+    return b != null && Math.abs(g.gap - b) > GAP_TOL && !broken.has(g.a) && !broken.has(g.b) && !g.fit && !declaredGap;
   }).map((g) => ({ ...g, before: beforeGaps.get(`${g.axis}|${g.a}|${g.b}`) }));
-  return { misaligned, spacing };
+  const beforeContainment = new Map((before.containment || []).map((finding) => [`${finding.parent}|${finding.id}`, finding]));
+  const containment = (after.containment || []).filter((finding) => {
+    const baseline = beforeContainment.get(`${finding.parent}|${finding.id}`);
+    return Object.entries(finding.sides || {}).some(([side, px]) => px > (baseline?.sides?.[side] || 0) + CONTAINMENT_TOL);
+  }).map((finding) => ({
+    ...finding,
+    before: beforeContainment.get(`${finding.parent}|${finding.id}`)?.sides || {},
+  }));
+  const afterActions = new Map((after.actions || []).map((action) => [action.key, action]));
+  const unreachableActions = (before.actions || []).filter((action) => (
+    action.reachable && afterActions.get(action.key)?.reachable !== true
+  )).map((action) => ({
+    key: action.key,
+    id: action.id,
+    kind: action.kind,
+    after: afterActions.get(action.key) || null,
+  }));
+  return { misaligned, spacing, containment, unreachableActions };
 }

package/prototype-kit/polish/measure.mjs

@@ -1,5 +1,6 @@
-// Polish metrics: deterministic, geometry-only, computed in the browser on a rendered page.
-// One page → { overflow, overlap, alignment, whitespace, missingText, shift } with per-finding detail.
+// Polish metrics: deterministic geometry + hit-test evidence, computed in the browser on a rendered page.
+// One page → { overflow, containment, actions, overlap, alignment, whitespace, missingText, shift }
+// with per-finding detail.
 // Used before AND after the polish stage; the numbers are instruments, the findings are the evidence.
 
 export const NEAR = 6;      // px: an edge this close (but not equal) to another is a near-miss
@@ -37,6 +38,18 @@ export function pageMetricsScript() {
     const inShell = (el) => !!el.closest('[data-proto-shell], aside, header, footer, [id*="sidebar"], [id*="-nav"]');
     const scope = sections.length ? sections : [section];
     const qsa = (sel) => scope.flatMap((s) => [...s.querySelectorAll(sel)]);
+    const domKey = (el) => {
+      if (el.id) return el.id;
+      const parts = [];
+      let node = el;
+      while (node?.parentElement) {
+        const parent = node.parentElement;
+        parts.unshift(`${node.tagName.toLowerCase()}:nth-child(${[...parent.children].indexOf(node) + 1})`);
+        if (parent.id) return `${parent.id}>${parts.join('>')}`;
+        node = parent;
+      }
+      return parts.join('>');
+    };
     const leaves = qsa('.text, .paragraph, h1, h2, h3, h4, h5, h6, .icon, img, .image, .badge, .divider, button, .button')
       .filter((el) => visible(el) && !el.closest('#proto-overlay-root') && !el.querySelector('.text, .paragraph') && !(el.matches('button, .button') && el.closest('.proto-notice, .proto-holding-block')));
     const containers = qsa('div[id], button[id], aside[id], header[id], footer[id], nav[id], article[id], form[id], main[id]')
@@ -56,7 +69,7 @@ export function pageMetricsScript() {
       }
       return { r: 255, g: 255, b: 255, a: 1 };
     };
-    const out = { overflow: [], overlap: [], alignment: [], whitespace: [], missingText: [], shift: [], counts: {} };
+    const out = { overflow: [], containment: [], actions: [], overlap: [], alignment: [], whitespace: [], missingText: [], shift: [], counts: {} };
 
     // ---- overflow / clipping / escape
     for (const el of leaves) {
@@ -88,6 +101,29 @@ export function pageMetricsScript() {
       if (cut > 1.5) out.overflow.push({ kind: 'cut', px: +cut.toFixed(1), ...box });
     }
 
+    // ---- direct parent containment for every positioned block/leaf. Text overflow alone cannot see a full-width
+    // card moved beyond its owning stack. Record existing overhangs as baseline evidence; the harm guard rejects only
+    // newly introduced or enlarged overhangs, so intentional source geometry remains untouched.
+    for (const el of qsa('[id]')) {
+      const parent = el.parentElement;
+      if (!parent || !visible(el) || !visible(parent) || parent.closest('#proto-overlay-root')) continue;
+      const r = el.getBoundingClientRect(); const p = parent.getBoundingClientRect();
+      const sides = {
+        left: Math.max(0, p.left - r.left),
+        top: Math.max(0, p.top - r.top),
+        right: Math.max(0, r.right - p.right),
+        bottom: Math.max(0, r.bottom - p.bottom),
+      };
+      const px = Math.max(sides.left, sides.top, sides.right, sides.bottom);
+      if (px > 1.5) out.containment.push({
+        id: el.id,
+        parent: domKey(parent),
+        parentId: parent.id || null,
+        px: +px.toFixed(2),
+        sides: Object.fromEntries(Object.entries(sides).filter(([, value]) => value > 1.5).map(([side, value]) => [side, +value.toFixed(2)])),
+      });
+    }
+
     // ---- overlap between unrelated leaves
     const L = leaves.map((el) => ({ el, r: rel(isText(el) ? tightRect(el) : el.getBoundingClientRect(), el) }));
     for (let i = 0; i < L.length; i++) for (let j = i + 1; j < L.length; j++) {
@@ -299,10 +335,70 @@ export function pageMetricsScript() {
       if (contrast < 1.25 && fg.a > 0.05) out.missingText.push({ id, kind: 'invisible', contrast: +contrast.toFixed(2), src: el.textContent.trim().slice(0, 60) });
     }
 
-    window.scrollTo(0, 0); // effectiveBg scrolled probes into view; leave the page as found
+    // ---- semantic action reachability. CSS-only polish must not change which declared controls a real pointer can
+    // reach. Probe every action/field at its own scrolled-into-view action points, not merely the first dropdown or
+    // modal that the runtime smoke test happens to exercise.
+    {
+      const DECLARED_ACTION = '[data-proto-action], [data-proto-field], [data-proto-submit-for]';
+      const NATIVE_ACTION = 'a[href], button, input:not([type="hidden"]), select, textarea, [role="button"], [role="link"], [tabindex]:not([tabindex="-1"])';
+      const ACTION = `${DECLARED_ACTION}, ${NATIVE_ACTION}`;
+      const targets = qsa(ACTION).filter((el) => (
+        visible(el)
+        && !el.closest('#proto-overlay-root')
+        && !el.hasAttribute('disabled')
+        && el.getAttribute('aria-disabled') !== 'true'
+        && !el.closest('[inert]')
+        && !el.hasAttribute('data-proto-suppressed')
+        // A plain native child is the pointer surface of its declared wrapper, not a competing action. A nested
+        // DECLARED action remains distinct and correctly owns its own hit points.
+        && (el.matches(DECLARED_ACTION) || !el.closest(DECLARED_ACTION))
+      ));
+      for (let index = 0; index < targets.length; index++) {
+        const el = targets[index];
+        const kind = el.getAttribute('data-proto-action')
+          || (el.hasAttribute('data-proto-field') ? 'field' : null)
+          || (el.hasAttribute('data-proto-submit-for') ? 'submit' : null)
+          || el.getAttribute('role')
+          || el.tagName.toLowerCase();
+        el.scrollIntoView({ block: 'center', inline: 'nearest', behavior: 'instant' });
+        const rects = [...el.getClientRects()].filter((r) => r.width > 0 && r.height > 0);
+        let point = null; let receiver = null;
+        for (const rect of rects) {
+          const insetX = Math.min(8, rect.width / 4), insetY = Math.min(8, rect.height / 4);
+          const points = [
+            [rect.left + rect.width / 2, rect.top + rect.height / 2],
+            [rect.left + insetX, rect.top + insetY],
+            [rect.right - insetX, rect.top + insetY],
+            [rect.left + insetX, rect.bottom - insetY],
+            [rect.right - insetX, rect.bottom - insetY],
+          ];
+          for (const [x, y] of points) {
+            if (x < 0 || y < 0 || x >= window.innerWidth || y >= window.innerHeight) continue;
+            const hit = document.elementFromPoint(x, y);
+            const owner = hit?.closest(DECLARED_ACTION) || hit?.closest(NATIVE_ACTION);
+            if (owner === el) { point = { x: +x.toFixed(2), y: +y.toFixed(2) }; receiver = hit; break; }
+            if (!receiver && hit) receiver = hit;
+          }
+          if (point) break;
+        }
+        out.actions.push({
+          key: el.id || `${kind}:${index}`,
+          id: el.id || null,
+          kind,
+          reachable: Boolean(point),
+          ...(point ? { point } : {}),
+          ...(!point && receiver ? { interceptedBy: receiver.id || receiver.tagName.toLowerCase() } : {}),
+        });
+      }
+    }
+
+    window.scrollTo(0, 0); // effectiveBg and action probes scroll; leave the page as found
     out.counts = {
       leaves: leaves.length, textLeaves: leaves.filter(isText).length, containers: containers.length,
-      overflow: out.overflow.length, overlap: out.overlap.length, alignment: out.alignment.length, whitespace: out.whitespace.length,
+      overflow: out.overflow.length, containment: out.containment.length,
+      actions: out.actions.length, reachableActions: out.actions.filter((action) => action.reachable).length,
+      unreachableActions: out.actions.filter((action) => !action.reachable).length,
+      overlap: out.overlap.length, alignment: out.alignment.length, whitespace: out.whitespace.length,
       columns: out.columns.length, gaps: out.gaps.length, seams: out.seams.length, narrowSeams: out.seams.filter((x) => x.gap < 48).length, documentHeight: document.documentElement.scrollHeight, offcenter: out.offcenter.length, rail: out.rail.length, missingText: out.missingText.length, shifted: out.shift.length, maxShift: out.shift.reduce((m, s) => Math.max(m, s.d), 0),
       sectionW: sb.width, sectionH: sb.height,
     };

package/prototype-kit/polish/overrides.mjs

@@ -1,7 +1,9 @@
 // Override model shared by every polish rule and the driver.
-// An override is { id | sel, rule, reason, dx?, dy?, w?, h?, css?: {prop: value} }.
+// An override is { id | sel, rule, reason, dx?, dy?, motion?, w?, h?, css?: {prop: value} }.
 //   id     → targets #id; sel → targets an arbitrary selector (holding pages have class-only nodes)
 //   dx/dy  → translate (does not disturb siblings; sums across rules)
+//   motion → `inset` means dx/dy describe the cap/evidence only; css left/top performs the nudge without a
+//            stacking-context-producing transform
 //   w/h    → width/height in px (last rule wins)
 //   css    → any other declarations (last rule wins per property)
 
@@ -11,8 +13,10 @@ export function mergeOverrides(list) {
     if (!o || !(o.id || o.sel)) continue;
     const key = o.sel || o.id;
     const cur = byId.get(key) || { id: o.id, sel: o.sel, dx: 0, dy: 0, css: {}, rules: [] };
-    cur.dx += o.dx || 0;
-    cur.dy += o.dy || 0;
+    if (o.motion !== 'inset') {
+      cur.dx += o.dx || 0;
+      cur.dy += o.dy || 0;
+    }
     if (o.w != null) cur.w = o.w;
     if (o.h != null) cur.h = o.h;
     Object.assign(cur.css, o.css || {});
@@ -40,6 +44,31 @@ export function overridesToCss(merged) {
   return lines.join('\n') + '\n';
 }
 
+// Canonical shell regions are a cross-page contract. A page-local rule cannot safely mutate a shell descendant, the
+// shell root, or one of its ancestors: any of those changes can make one page's shell signature diverge from peers.
+// Partition in the browser because selectors and ancestry are facts of the rendered page.
+export function partitionProtectedShellOverridesScript() {
+  return ({ overrides, shellIds }) => {
+    const shells = (shellIds || []).map((id) => document.getElementById(id)).filter(Boolean);
+    if (!shells.length) return { allowed: overrides, protected: [] };
+    const allowed = []; const protectedOverrides = [];
+    for (const override of overrides) {
+      let targets = [];
+      try {
+        targets = override.id ? [document.getElementById(override.id)].filter(Boolean) : [...document.querySelectorAll(override.sel)];
+      } catch {
+        protectedOverrides.push(override);
+        continue;
+      }
+      const touchesShell = targets.some((target) => shells.some((shell) => (
+        target === shell || target.contains(shell) || shell.contains(target)
+      )));
+      (touchesShell ? protectedOverrides : allowed).push(override);
+    }
+    return { allowed, protected: protectedOverrides };
+  };
+}
+
 function round(n) { return Math.round(n * 100) / 100; }
 
 // In-browser: (re)place a <style id="proto-polish"> with the given css text.

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}