@12ui/design 0.2.48 → 0.2.49

package/open-design.json

@@ -3,7 +3,7 @@
   "specVersion": "1.0.0",
   "name": "12ui-design",
   "title": "12UI Design",
-  "version": "0.2.48",
+  "version": "0.2.49",
   "description": "Explore corpus-grounded interface directions, choose one, and convert it into production-ready responsive or native artifacts with 12UI.",
   "author": {
     "name": "Just Every",
@@ -49,7 +49,7 @@
           "command": "npx",
           "args": [
             "-y",
-            "@12ui/design@0.2.48",
+            "@12ui/design@0.2.49",
             "mcp"
           ]
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12ui/design",
-  "version": "0.2.48",
+  "version": "0.2.49",
   "type": "module",
   "description": "The canonical 12ui CLI, SDK, MCP server, and visual interface design skills",
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
     "start": "node dist/cli.js",
     "test": "vitest",
     "test:run": "vitest run",
-    "test:prototype": "node prototype-kit/polish/tests/rules-check.mjs && node prototype-kit/polish/tests/harm-check.mjs && node prototype-kit/polish/tests/breathing-check.mjs && node prototype-kit/polish/tests/report-check.mjs && node prototype-kit/tests/rules-check.mjs && node prototype-kit/tests/offline-check.mjs && node prototype-kit/tests/shell-stitching-runtime.mjs && node prototype-kit/tests/adversarial-runtime.mjs --assert",
+    "test:prototype": "node prototype-kit/polish/tests/rules-check.mjs && node prototype-kit/polish/tests/harm-check.mjs && node prototype-kit/polish/tests/breathing-check.mjs && node prototype-kit/polish/tests/report-check.mjs && node prototype-kit/tests/rules-check.mjs && node prototype-kit/tests/offline-check.mjs && node prototype-kit/tests/shell-stitching-runtime.mjs && node prototype-kit/tests/shell-stitching-runtime.mjs --reintroduce-defect && node prototype-kit/tests/adversarial-runtime.mjs --assert",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.type-tests.json",
     "prepublishOnly": "npm run build"
   },

package/prototype-kit/build.mjs

@@ -4,7 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseHTML } from 'linkedom';
 import { resolveDropdownAction } from './lib/actions.mjs';
-import { restoreActionPointerReachability } from './lib/action-target.mjs';
+import { restoreActionPointerReachability, selectUniqueActionOwners } from './lib/action-target.mjs';
 import {
   HOLDING_SHELL_ATTRIBUTE,
   holdingBlockGeometry,
@@ -13,6 +13,7 @@ import {
   shellPlacementCss,
 } from './lib/holding-composition.mjs';
 import { injectReviewFraming } from './lib/review-framing.mjs';
+import { removeRemoteHeadLinks } from './lib/local-document.mjs';
 import {
   isolateTransplantedShell,
   rulesFor,
@@ -156,6 +157,7 @@ const report = {
   unbound: [],
   invalidDropdowns: [],
   actionDemotions: [],
+  duplicateActionOwners: [],
   shellSizeDelta: [],
   shellAmbiguities: model.shellAmbiguities || [],
   suppressedShellOverlaps: [],
@@ -234,7 +236,9 @@ function actionsFor(s) {
     if (a) acts.set(c.id, a);
     else report.counts.none++;
   }
-  return acts;
+  const normalized = selectUniqueActionOwners(loadDoc(s.file).document, acts);
+  report.duplicateActionOwners.push(...normalized.removed.map((removal) => ({ state: s.stateId, ...removal })));
+  return normalized.actions;
 }
 
 function bindAction(el, action) {
@@ -410,6 +414,7 @@ for (const u of units) {
   const cfg = { unit: u.id, states: u.states.map((s) => s.stateId), tokens: model.tokens, contentFile: `${u.id}.json`, activeNav: activeNav?.text || null };
   document.body.insertAdjacentHTML('beforeend', `<script id="proto-state" type="application/json">${JSON.stringify(cfg).replace(/</g, '\\u003c')}</script><script src="proto.js"></script>`);
   if (review) injectReviewFraming(document, review);
+  removeRemoteHeadLinks(document);
   fs.writeFileSync(path.join(outDir, outputFileOfUnit(u)), '<!doctype html>\n' + document.documentElement.outerHTML);
   fs.writeFileSync(path.join(outDir, 'content', u.id + '.json'), JSON.stringify(content, null, 1));
   report.units.push({
@@ -612,6 +617,7 @@ for (const u of units) {
     const cfg = { unit: hslug, holding: true, holdingBands: bandDeclarations, tokens: model.tokens, contentFile: null, activeNav: navMatch?.text || null };
     document.body.insertAdjacentHTML('beforeend', `<script id="proto-state" type="application/json">${JSON.stringify(cfg)}</script><script src="proto.js"></script>`);
     if (review) injectReviewFraming(document, review);
+    removeRemoteHeadLinks(document);
     fs.writeFileSync(path.join(outDir, outputFile), '<!doctype html>\n' + document.documentElement.outerHTML);
   }
   console.error(`holding pages: ${usedHoldings.size}`);
@@ -623,5 +629,5 @@ fs.writeFileSync(path.join(outDir, 'index.html'), `<!doctype html><meta http-equ
 const manifestHoldings = review
   ? [...usedHoldings.entries()].map(([holding, title]) => [holding.replace(/\.html$/, ''), title])
   : [...usedHoldings.entries()];
-fs.writeFileSync(path.join(outDir, 'proto-manifest.json'), JSON.stringify({ units: report.units, nav: navRows.map((n) => ({ text: n.text, target: n.target, holding: n.holding, rowId: n.rowId })), holdings: manifestHoldings, counts: report.counts, unbound: report.unbound, invalidDropdowns: report.invalidDropdowns, ...(report.actionDemotions.length > 0 ? { actionDemotions: report.actionDemotions } : {}), shellSizeDelta: report.shellSizeDelta, shellAmbiguities: report.shellAmbiguities, suppressedShellOverlaps: report.suppressedShellOverlaps, skippedShellTransplants: report.skippedShellTransplants, replacedShellActions: report.replacedShellActions, shellActionRemaps: report.shellActionRemaps, scriptDirections: states.map(({ stateId, scriptDirection, writingMode }) => ({ stateId, scriptDirection, writingMode })), canonicalShell: model.canonicalShell, canonicalShellPage: report.canonicalShellPage, shellConsistency: report.shellConsistency, ...(review ? { review } : {}) }, null, 1));
+fs.writeFileSync(path.join(outDir, 'proto-manifest.json'), JSON.stringify({ units: report.units, nav: navRows.map((n) => ({ text: n.text, target: n.target, holding: n.holding, rowId: n.rowId })), holdings: manifestHoldings, counts: report.counts, unbound: report.unbound, invalidDropdowns: report.invalidDropdowns, ...(report.actionDemotions.length > 0 ? { actionDemotions: report.actionDemotions } : {}), ...(report.duplicateActionOwners.length > 0 ? { duplicateActionOwners: report.duplicateActionOwners } : {}), shellSizeDelta: report.shellSizeDelta, shellAmbiguities: report.shellAmbiguities, suppressedShellOverlaps: report.suppressedShellOverlaps, skippedShellTransplants: report.skippedShellTransplants, replacedShellActions: report.replacedShellActions, shellActionRemaps: report.shellActionRemaps, scriptDirections: states.map(({ stateId, scriptDirection, writingMode }) => ({ stateId, scriptDirection, writingMode })), canonicalShell: model.canonicalShell, canonicalShellPage: report.canonicalShellPage, shellConsistency: report.shellConsistency, ...(review ? { review } : {}) }, null, 1));
 console.error('counts', JSON.stringify(report.counts), 'unbound', report.unbound.length);

package/prototype-kit/lib/action-target.mjs

@@ -8,3 +8,29 @@ export function restoreActionPointerReachability(element) {
   element.setAttribute('data-proto-pointer-restored', 'true');
   return true;
 }
+
+/**
+ * Give one semantic action to one rendered owner. A label response can name
+ * both a layout wrapper and one or more controls inside it. When descendants
+ * carry the same action kind, only the terminal-most elements are real action
+ * targets; retaining the wrapper adds a duplicate listener and an impossible
+ * hit-test identity. Different nested action kinds remain independent.
+ */
+export function selectUniqueActionOwners(document, actions) {
+  const selected = new Map(actions);
+  const removed = [];
+  for (const [wrapperId, wrapperAction] of actions) {
+    const wrapper = document.getElementById(wrapperId);
+    if (!wrapper) continue;
+    const descendants = [...wrapper.querySelectorAll('[id]')].filter((candidate) => (
+      actions.get(candidate.id)?.action === wrapperAction.action
+    ));
+    if (descendants.length === 0) continue;
+    const ownerIds = descendants.filter((candidate) => ![...candidate.querySelectorAll('[id]')].some((nested) => (
+      actions.get(nested.id)?.action === wrapperAction.action
+    ))).map((candidate) => candidate.id);
+    selected.delete(wrapperId);
+    removed.push({ wrapperId, ownerIds, action: wrapperAction.action });
+  }
+  return { actions: selected, removed };
+}

package/prototype-kit/lib/local-document.mjs

@@ -0,0 +1,16 @@
+const REMOTE_HREF = /^(?:https?:)?\/\//iu;
+
+/**
+ * Prototype files are owner-review artifacts that must open directly from
+ * disk. Remote head links turn an otherwise self-contained page into a noisy
+ * runtime failure when the review browser correctly blocks the network.
+ */
+export function removeRemoteHeadLinks(document) {
+  let removed = 0;
+  for (const link of document.querySelectorAll('head link[href]')) {
+    if (!REMOTE_HREF.test(link.getAttribute('href')?.trim() ?? '')) continue;
+    link.remove();
+    removed += 1;
+  }
+  return removed;
+}

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.