@12ui/design 0.2.48 → 0.2.50

package/prototype-kit/lib/runtime-check.mjs

@@ -1,6 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import {
+  compareCanonicalShellSamples,
+  SHELL_RUNTIME_GEOMETRY_EPSILON_PX,
+} from './shell-runtime-equivalence.mjs';
+
 function errorText(error) {
   return error instanceof Error ? error.message : String(error);
 }
@@ -21,7 +26,23 @@ function configuredWidths(protoDir, file) {
 async function smokeInteraction(page, selector, assertion) {
   const locator = page.locator(selector).first();
   if (!await locator.count()) return { present: false, ok: true };
+  let reviewClearanceAdded = false;
   try {
+    reviewClearanceAdded = await locator.evaluate((element) => {
+      const framing = document.getElementById('proto-review-framing');
+      if (!framing) return false;
+      const box = framing.getBoundingClientRect();
+      const target = element.getBoundingClientRect();
+      const overlaps = Math.min(box.right, target.right) - Math.max(box.left, target.left) > 0
+        && Math.min(box.bottom, target.bottom) - Math.max(box.top, target.top) > 0;
+      if (!overlaps) return false;
+      const clearance = document.createElement('div');
+      clearance.setAttribute('data-proto-runtime-clearance', 'true');
+      clearance.setAttribute('aria-hidden', 'true');
+      clearance.style.cssText = `display:block;position:relative;flex:none;width:1px;height:${box.height + 36}px;pointer-events:none`;
+      document.body.appendChild(clearance);
+      return true;
+    });
     await locator.scrollIntoViewIfNeeded();
     // Playwright considers an element "in view" even when a fixed review
     // panel covers every point in its box. Center it before hit-testing so
@@ -55,6 +76,10 @@ async function smokeInteraction(page, selector, assertion) {
     return { present: true, ok, point, opened };
   } catch (error) {
     return { present: true, ok: false, error: errorText(error) };
+  } finally {
+    if (reviewClearanceAdded) {
+      await page.locator('[data-proto-runtime-clearance="true"]').evaluateAll((nodes) => nodes.forEach((node) => node.remove())).catch(() => null);
+    }
   }
 }
 
@@ -286,7 +311,12 @@ export async function checkRuntime({ browser, baseUrl, relativeProtoPath, protoD
           const host = screen?.querySelector('.ly-anchor-canvas') || screen;
           const hostZoom = host ? parseFloat(getComputedStyle(host).zoom) || 1 : 1;
           const round = (value) => Math.round(value * 10) / 10;
-          const visualSignature = async (shell, declaration) => {
+          const digestJson = async (value) => {
+            const bytes = new TextEncoder().encode(JSON.stringify(value));
+            const digest = await crypto.subtle.digest('SHA-256', bytes);
+            return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+          };
+          const visualSample = async (shell, declaration) => {
             const rootBox = shell.getBoundingClientRect();
             const markerIds = new Set(declaration.activeMarkerIds || []);
             const visualNodes = [shell, ...shell.querySelectorAll('*')]
@@ -306,10 +336,10 @@ export async function checkRuntime({ browser, baseUrl, relativeProtoPath, protoD
                   label: node.getAttribute('alt') || node.getAttribute('aria-label') || '',
                   source: node.getAttribute('src') || '',
                   box: [
-                    round((box.left - rootBox.left) / hostZoom),
-                    round((box.top - rootBox.top) / hostZoom),
-                    round(box.width / hostZoom),
-                    round(box.height / hostZoom),
+                    (box.left - rootBox.left) / hostZoom,
+                    (box.top - rootBox.top) / hostZoom,
+                    box.width / hostZoom,
+                    box.height / hostZoom,
                   ],
                   style: [
                     style.display, node === shell ? 'shell-root' : style.position,
@@ -319,9 +349,13 @@ export async function checkRuntime({ browser, baseUrl, relativeProtoPath, protoD
                   ],
                 };
               }).filter((node) => node.box[2] > 0 && node.box[3] > 0);
-            const bytes = new TextEncoder().encode(JSON.stringify({ region: declaration.region, visualNodes }));
-            const digest = await crypto.subtle.digest('SHA-256', bytes);
-            return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+            const appearanceNodes = visualNodes.map(({ box, ...appearance }) => appearance);
+            const diagnosticNodes = visualNodes.map((node) => ({ ...node, box: node.box.map(round) }));
+            return {
+              appearanceSignature: await digestJson({ region: declaration.region, visualNodes: appearanceNodes }),
+              diagnosticSignature: await digestJson({ region: declaration.region, visualNodes: diagnosticNodes }),
+              geometry: visualNodes.map((node) => node.box),
+            };
           };
           for (const declaration of declared.regions || []) {
             const shell = document.getElementById(declaration.shellId);
@@ -329,15 +363,16 @@ export async function checkRuntime({ browser, baseUrl, relativeProtoPath, protoD
               failures.push({ kind: 'shell-consistency', region: declaration.region, reason: 'missing-declared-shell' });
               continue;
             }
-            const actualSignature = await visualSignature(shell, declaration);
+            const sample = await visualSample(shell, declaration);
             const shellBox = shell.getBoundingClientRect();
             const hostBox = host?.getBoundingClientRect() || { left: 0, top: 0 };
-            const actualGeometry = [
-              round((shellBox.left - hostBox.left) / hostZoom),
-              round((shellBox.top - hostBox.top) / hostZoom),
-              round(shellBox.width / hostZoom),
-              round(shellBox.height / hostZoom),
+            const comparisonGeometry = [
+              (shellBox.left - hostBox.left) / hostZoom,
+              (shellBox.top - hostBox.top) / hostZoom,
+              shellBox.width / hostZoom,
+              shellBox.height / hostZoom,
             ];
+            const actualGeometry = comparisonGeometry.map(round);
             let activeMatches = true;
             if (declaration.active?.status === 'linked') {
               const marker = document.getElementById(declaration.active.markerId);
@@ -364,8 +399,11 @@ export async function checkRuntime({ browser, baseUrl, relativeProtoPath, protoD
             regions.push({
               region: declaration.region,
               shellId: declaration.shellId,
-              actualSignature,
+              actualSignature: sample.diagnosticSignature,
               actualGeometry,
+              appearanceSignature: sample.appearanceSignature,
+              visualGeometry: sample.geometry,
+              comparisonGeometry,
               inventorySampleSignature: declaration.canonicalSignature,
               consistencyStatus: declaration.consistencyStatus || 'canonical',
               activeStatus: declaration.active?.status || 'silent',
@@ -427,23 +465,48 @@ export async function checkRuntime({ browser, baseUrl, relativeProtoPath, protoD
       .map((failure) => ({ file: page.file, width: viewport.width, ...failure })) || []
   )));
   const shellRuntimeGroups = new Map();
+  const shellConsistencyTolerances = [];
   for (const page of pages) for (const viewport of page.viewports) {
     if (!unitByFile.has(page.file)) continue;
     for (const region of viewport.shellState?.regions || []) {
       if (region.consistencyStatus !== 'canonical') continue;
       const key = `${viewport.width}:${viewport.shellState.activeBand}:${region.region}`;
       if (!shellRuntimeGroups.has(key)) shellRuntimeGroups.set(key, []);
-      shellRuntimeGroups.get(key).push({ file: page.file, signature: region.actualSignature, geometry: region.actualGeometry });
+      shellRuntimeGroups.get(key).push({
+        file: page.file,
+        signature: region.actualSignature,
+        geometry: region.actualGeometry,
+        appearanceSignature: region.appearanceSignature,
+        visualGeometry: region.visualGeometry,
+        shellGeometry: region.comparisonGeometry,
+      });
     }
   }
   for (const [key, entries] of shellRuntimeGroups) {
-    const fingerprints = new Set(entries.map((entry) => JSON.stringify([entry.signature, entry.geometry])));
-    if (fingerprints.size > 1) shellConsistencyFailures.push({
+    const reference = entries[0];
+    const comparisons = entries.slice(1).map((entry) => compareCanonicalShellSamples(reference, entry));
+    const equivalent = comparisons.every((comparison) => comparison.equivalent);
+    const pagesInGroup = entries.map(({ file, signature, geometry }) => ({ file, signature, geometry }));
+    if (!equivalent) shellConsistencyFailures.push({
       kind: 'shell-consistency',
       reason: 'prototype-shell-signature-mismatch',
       group: key,
-      pages: entries,
+      pages: pagesInGroup,
     });
+    else {
+      const diagnosticFingerprints = new Set(entries.map((entry) => JSON.stringify([entry.signature, entry.geometry])));
+      if (diagnosticFingerprints.size > 1) shellConsistencyTolerances.push({
+        group: key,
+        epsilonPx: SHELL_RUNTIME_GEOMETRY_EPSILON_PX,
+        maxGeometryDelta: Math.max(0, ...comparisons.map((comparison) => comparison.maxGeometryDelta || 0)),
+        pages: pagesInGroup,
+      });
+    }
+  }
+  for (const page of pages) for (const viewport of page.viewports) for (const region of viewport.shellState?.regions || []) {
+    delete region.appearanceSignature;
+    delete region.visualGeometry;
+    delete region.comparisonGeometry;
   }
   const activeNavigationFailures = pages.flatMap((page) => page.viewports.flatMap((viewport) => (
     viewport.shellState?.failures?.filter((failure) => failure.kind === 'active-navigation')
@@ -458,6 +521,7 @@ export async function checkRuntime({ browser, baseUrl, relativeProtoPath, protoD
     interactionFailures: pages.filter((page) => page.dropdown?.ok === false || page.modal?.ok === false).map((page) => page.file),
     compositionFailures,
     shellConsistencyFailures,
+    shellConsistencyTolerances,
     activeNavigationFailures,
     deepLinkBack,
   };

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) {