@12ui/design 0.2.47 → 0.2.49

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

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

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

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

package/prototype-kit/runtime/proto.js

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

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

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

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

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

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

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

package/prototype-kit/tests/offline-check.mjs

@@ -4,13 +4,29 @@ import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { parseHTML } from 'linkedom';
 import { reviewFramingMarkup } from '../lib/review-framing.mjs';
+import { removeRemoteHeadLinks } from '../lib/local-document.mjs';
 import { buildPrototype } from './lib/run-process.mjs';
 
 const testsDir = path.dirname(new URL(import.meta.url).pathname);
 const kitDir = path.resolve(testsDir, '..');
 const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'proto-kit-offline-'));
 
+const localDocument = parseHTML([
+  '<html><head>',
+  '<link rel="preconnect" href="https://fonts.example">',
+  '<link rel="stylesheet" href="//cdn.example/font.css">',
+  '<link rel="stylesheet" href="proto.css">',
+  '</head></html>',
+].join('')).document;
+assert.equal(removeRemoteHeadLinks(localDocument), 2, 'must fire: direct-file prototypes remove remote head links');
+assert.deepEqual(
+  [...localDocument.querySelectorAll('head link')].map((link) => link.getAttribute('href')),
+  ['proto.css'],
+  'must stay silent: prototype-local stylesheets survive offline sanitization',
+);
+
 function buildFixture(name) {
   const runDir = path.join(testsDir, 'fixtures', name);
   return buildPrototype({ kitDir, run: { runDir }, runWorkDir: path.join(scratch, name) });
@@ -44,7 +60,7 @@ const outputDigest = (directory) => {
 };
 assert.equal(
   outputDigest(threeShell.protoDir),
-  '0c2147df5bc6552016cc278faec7abaabecbc7f5945cad7e1ac9b1df6e554403',
+  '0a24a0c220106a1592598f1ad11685081337cb60d3044953e56e11e239dbc8bd',
   'must stay silent: review support leaves the accepted shell/navigation complete output byte-identical',
 );
 const threeShellModel = JSON.parse(fs.readFileSync(threeShell.modelFile, 'utf8'));

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

@@ -2,11 +2,13 @@
 import assert from 'node:assert/strict';
 import { parseHTML } from 'linkedom';
 import { resolveDropdownAction, suppressDeterministicAction, usableDropdownOptions } from '../lib/actions.mjs';
-import { restoreActionPointerReachability } from '../lib/action-target.mjs';
+import { restoreActionPointerReachability, selectUniqueActionOwners } from '../lib/action-target.mjs';
+import { checkAlignRule } from './align-rule-check.mjs';
 import { declaredActiveMarkers, linkedNavForUnit, markerOverlapsNav } from '../lib/nav-active-state.mjs';
 import { matchPlannedPage } from '../lib/navigation.mjs';
 import { needsCanonicalShell, selectCanonicalShellPage } from '../lib/shell-consistency.mjs';
 import { isolateTransplantedShell, shellElementsForSourceId } from '../lib/shell-identity.mjs';
+import { compareCanonicalShellSamples, SHELL_RUNTIME_GEOMETRY_EPSILON_PX } from '../lib/shell-runtime-equivalence.mjs';
 import { stitchUnitShells } from '../lib/shell-stitching.mjs';
 import { compareCanonicalShells, isWithinShell, qualifiesShellCandidate, selectOneShellPerRegion, shouldSuppressDroppedShell, shouldTransplantShell } from '../lib/shells.mjs';
 import { slugText } from '../lib/text.mjs';
@@ -69,6 +71,68 @@ const reachableBefore = reachableDropdown.outerHTML;
 assert.equal(restoreActionPointerReachability(reachableDropdown), false, 'must stay silent: an already reachable dropdown target is unchanged');
 assert.equal(reachableDropdown.outerHTML, reachableBefore);
 
+const repeatedDropdown = { action: 'dropdown', options: ['All opportunities', 'High intent', 'Low intent'] };
+const distinctDropdown = { action: 'dropdown', options: ['All countries', 'Australia', 'Canada'] };
+const landsFilterDocument = parseHTML(`<div id="filters"><button id="filter-1"></button><button id="filter-2"></button><button id="filter-3"></button><button id="filter-4"></button><button id="filter-5"></button><button id="filter-6"></button></div>`).document;
+const landsFilterActions = new Map([
+  ['filters', repeatedDropdown],
+  ['filter-1', repeatedDropdown],
+  ['filter-2', distinctDropdown],
+  ['filter-3', distinctDropdown],
+  ['filter-4', distinctDropdown],
+  ['filter-5', distinctDropdown],
+  ['filter-6', distinctDropdown],
+]);
+const uniqueLandsFilters = selectUniqueActionOwners(landsFilterDocument, landsFilterActions);
+assert.deepEqual(uniqueLandsFilters.removed, [{ wrapperId: 'filters', ownerIds: ['filter-1', 'filter-2', 'filter-3', 'filter-4', 'filter-5', 'filter-6'], action: 'dropdown' }], 'must fire: the six-child Ghost Sitemap filter shape gives the wrapper action to its terminal controls');
+assert.deepEqual([...uniqueLandsFilters.actions.keys()], ['filter-1', 'filter-2', 'filter-3', 'filter-4', 'filter-5', 'filter-6'], 'must stay silent: every native filter control remains independently actionable');
+const landsModalDocument = parseHTML('<div id="submit"><button id="submit-button"></button></div>').document;
+const landsModalActions = new Map([
+  ['submit', { action: 'modal', modal: { title: 'Analyze my site?', confirm: 'Analyze my site' } }],
+  ['submit-button', { action: 'modal', modal: { title: 'Analyze my site?', confirm: 'Analyze my site' } }],
+]);
+const uniqueLandsModal = selectUniqueActionOwners(landsModalDocument, landsModalActions);
+assert.deepEqual(uniqueLandsModal.removed, [{ wrapperId: 'submit', ownerIds: ['submit-button'], action: 'modal' }], 'must fire: the One Question modal wrapper yields to its terminal button');
+assert.deepEqual([...uniqueLandsModal.actions.keys()], ['submit-button']);
+const territoryFilterDocument = parseHTML('<aside id="filter-bar"><button id="filter-a"></button><button id="filter-b"></button><button id="filter-c"></button><button id="filter-d"></button></aside>').document;
+const territoryFilterActions = new Map([
+  ['filter-bar', { action: 'dropdown', options: ['All', 'Open', 'Closed'] }],
+  ['filter-a', { action: 'dropdown', options: ['All territories', 'East', 'West'] }],
+  ['filter-b', { action: 'dropdown', options: ['All visits', 'High', 'Low'] }],
+  ['filter-c', { action: 'dropdown', options: ['All claims', 'Claimed', 'Open'] }],
+  ['filter-d', { action: 'dropdown', options: ['Sort', 'Visits', 'Fit'] }],
+]);
+const uniqueTerritoryFilters = selectUniqueActionOwners(territoryFilterDocument, territoryFilterActions);
+assert.deepEqual(uniqueTerritoryFilters.removed, [{ wrapperId: 'filter-bar', ownerIds: ['filter-a', 'filter-b', 'filter-c', 'filter-d'], action: 'dropdown' }], 'must fire: the Territory Map four-button aside yields to every terminal dropdown even when their option payloads differ');
+assert.deepEqual([...uniqueTerritoryFilters.actions.keys()], ['filter-a', 'filter-b', 'filter-c', 'filter-d']);
+const distinctNestedDocument = parseHTML('<div id="parent"><button id="child"></button></div>').document;
+const distinctNestedActions = new Map([
+  ['parent', { action: 'dropdown', options: ['One', 'Two', 'Three'] }],
+  ['child', { action: 'modal', modal: { title: 'Child' } }],
+]);
+const uniqueDistinctNested = selectUniqueActionOwners(distinctNestedDocument, distinctNestedActions);
+assert.deepEqual([...uniqueDistinctNested.actions.keys()], ['parent', 'child'], 'must stay silent: distinct nested actions retain the runtime child-wins contract');
+
+const shellSample = ({ visualOffset = 0, shellOffset = 0, appearanceSignature = 'same' } = {}) => ({
+  appearanceSignature,
+  visualGeometry: [[0, 0, 390, 72], [20 + visualOffset, 20, 100, 28]],
+  shellGeometry: [shellOffset, 0, 390, 72],
+});
+assert.equal(SHELL_RUNTIME_GEOMETRY_EPSILON_PX, 0.5, 'fixture contract: canonical shell geometry tolerance is half a CSS pixel');
+const subpixelShellComparison = compareCanonicalShellSamples(shellSample(), shellSample({ visualOffset: 0.4 }));
+assert.equal(subpixelShellComparison.equivalent, true, 'must stay silent: a sub-half-pixel glyph measurement drift is visually equivalent');
+assert.ok(Math.abs(subpixelShellComparison.maxGeometryDelta - 0.4) < 1e-9, 'fixture contract: the comparator reports the measured subpixel drift');
+assert.deepEqual(compareCanonicalShellSamples(shellSample(), shellSample({ visualOffset: 24 })), {
+  equivalent: false,
+  reason: 'geometry',
+  maxGeometryDelta: 24,
+}, 'must fire: the b13-class displaced header descendant remains a canonical-shell mismatch');
+assert.deepEqual(compareCanonicalShellSamples(shellSample(), shellSample({ appearanceSignature: 'changed' })), {
+  equivalent: false,
+  reason: 'appearance',
+  maxGeometryDelta: null,
+}, 'must fire: geometry tolerance never conceals structural or style differences');
+
 const headerNav = { containerId: 'nav', region: 'header', semantic: true, items: 8, share: 0.8, box: [0, 40, 1536, 76] };
 const announcement = { containerId: 'announcement', region: 'header', semantic: false, items: 3, share: 1, box: [0, 0, 1536, 40] };
 const footer = { containerId: 'footer', region: 'footer', semantic: true, items: 5, share: 0.8, box: [0, 900, 1536, 124] };
@@ -205,4 +269,6 @@ assert.equal(fireResult.bands[0].regions[0].active.navText, 'Menu');
 assert.equal(fireResult.bands[0].regions[0].shellId, isolatedHeader.id);
 assert.equal(fireResult.bands[0].regions[0].active.markerId, isolatedMarker.id);
 
+checkAlignRule();
+
 process.stdout.write('rules: ok\n');

package/prototype-kit/tests/shell-stitching-runtime.mjs

@@ -8,9 +8,9 @@ import { checkRuntime } from '../lib/runtime-check.mjs';
 import { startStaticServer } from '../lib/static-server.mjs';
 import { buildPrototype } from './lib/run-process.mjs';
 
-const expectFailure = process.argv.includes('--expect-failure');
-const unexpectedArgs = process.argv.slice(2).filter((arg) => arg !== '--expect-failure');
-if (unexpectedArgs.length > 0) throw new Error(`usage: shell-stitching-runtime.mjs [--expect-failure]`);
+const reintroduceDefect = process.argv.includes('--reintroduce-defect');
+const unexpectedArgs = process.argv.slice(2).filter((arg) => arg !== '--reintroduce-defect');
+if (unexpectedArgs.length > 0) throw new Error(`usage: shell-stitching-runtime.mjs [--reintroduce-defect]`);
 
 const testsDir = path.dirname(new URL(import.meta.url).pathname);
 const kitDir = path.resolve(testsDir, '..');
@@ -49,6 +49,13 @@ try {
     bandHeight(inventory, 'p2-canvas-control', 'mobile-390'),
   ], [900, 1400], 'fixture contract: the portrait control has a substantially taller canvas');
 
+  if (reintroduceDefect) {
+    const collisionFile = path.join(built.protoDir, 'id-collision.html');
+    const collisionHtml = fs.readFileSync(collisionFile, 'utf8');
+    const displaced = '<style id="reintroduced-b13-defect">@media(max-width:600px){[data-proto-shell-source-id="mobile-390-header-brand"]{transform:translateX(24px)!important}}</style>';
+    fs.writeFileSync(collisionFile, collisionHtml.replace('</head>', `${displaced}</head>`));
+  }
+
   server = await startStaticServer(runWorkDir);
   browser = await chromium.launch();
   const audit = await checkRuntime({
@@ -77,11 +84,11 @@ try {
   assert.equal(collision1536.actualSignature, donor1536.actualSignature, 'must stay silent: distinct native identities render the same canonical header');
 
   const groups = audit.shellConsistencyFailures.map((failure) => failure.group);
-  if (expectFailure) {
-    assert.deepEqual(groups, ['390:mobile-390:header'], 'pre-fix evidence must isolate one canonical collision to the mobile header');
-    assert.notEqual(collision390.actualSignature, donor390.actualSignature, 'must fire before the fix: recipient offsets alter transplanted donor descendants');
+  if (reintroduceDefect) {
+    assert.deepEqual(groups, ['390:mobile-390:header'], 'reintroduced b13 evidence must isolate one canonical collision to the mobile header');
+    assert.notEqual(collision390.actualSignature, donor390.actualSignature, 'must fire with the defect present: a 24px recipient displacement alters transplanted donor descendants');
     const failure = audit.shellConsistencyFailures[0];
-    assert.equal(failure.reason, 'prototype-shell-signature-mismatch', 'pre-fix evidence is the rendered canonical-shell mismatch');
+    assert.equal(failure.reason, 'prototype-shell-signature-mismatch', 'reintroduced evidence is the rendered canonical-shell mismatch');
     assert.deepEqual(failure.pages, [
       { file: 'donor.html', signature: donor390.actualSignature, geometry: donor390.actualGeometry },
       { file: 'id-collision.html', signature: collision390.actualSignature, geometry: collision390.actualGeometry },
@@ -92,7 +99,7 @@ try {
   }
 
   process.stdout.write(JSON.stringify({
-    expectation: expectFailure ? 'pre-fix-failure' : 'post-fix-pass',
+    expectation: reintroduceDefect ? 'reintroduced-defect-failure' : 'post-fix-pass',
     groups,
     mobile: {
       donor: donor390.actualSignature,