@12ui/design 0.2.43 → 0.2.45

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

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+
+import { pageRuleRecords, summarizePolishReport } from '../report.mjs';
+
+const page = {
+  rules: {
+    align: { proposed: 2, overCap: 0 },
+    contrast: { proposed: 0, overCap: 0 },
+    rhythm: { proposed: 1, overCap: 1 },
+  },
+  accepted: [{ rule: 'align', overrides: 2 }],
+  rejected: [{ rule: 'rhythm', harm: ['spacing'] }],
+};
+page.ruleRecords = pageRuleRecords(page, ['align', 'contrast', 'rhythm']);
+assert.deepEqual(page.ruleRecords.map(({ rule, status }) => ({ rule, status })), [
+  { rule: 'align', status: 'fired' },
+  { rule: 'contrast', status: 'silent' },
+  { rule: 'rhythm', status: 'reverted' },
+]);
+
+const summary = summarizePolishReport({
+  policy: 'retained-v1',
+  rules: ['align', 'contrast', 'rhythm'],
+  pages: [page],
+});
+assert.equal(summary.fired, 1);
+assert.equal(summary.silent, 1);
+assert.equal(summary.reverted, 1);
+assert.equal(summary.rules.find(({ name }) => name === 'rhythm').overCap, 1);
+console.log('polish report outcomes green');

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

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// Paired cases for every polish rule: fixtures/<rule>/fire.html must produce ≥1 override,
+// fixtures/<rule>/silent.html must produce 0. Optional fixtures/<rule>/expect.json pins exact ids/deltas.
+import fs from 'node:fs';
+import path from 'node:path';
+import { chromium } from '@playwright/test';
+import { measurePage } from '../measure.mjs';
+import { loadRules, ALL } from '../rules/index.mjs';
+import { applyOverridesScript, overridesToCss, mergeOverrides } from '../overrides.mjs';
+
+const here = path.dirname(new URL(import.meta.url).pathname);
+const only = process.argv[2] ? process.argv[2].split(',') : ALL;
+const rules = await loadRules(only);
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1536, height: 1024 } });
+let failures = 0;
+const near = (a, b, tol = 0.6) => Math.abs(a - b) <= tol;
+for (const rule of rules) {
+  const dir = path.join(here, 'fixtures', rule.name);
+  for (const kind of ['fire', 'silent']) {
+    const file = path.join(dir, `${kind}.html`);
+    if (!fs.existsSync(file)) { console.log(`FAIL ${rule.name}/${kind}: fixture missing`); failures++; continue; }
+    await page.goto('file://' + file, { waitUntil: 'load' });
+    await page.evaluate(() => document.fonts.ready);
+    const before = await measurePage(page, {});
+    const found = await page.evaluate(rule.browserFn(), { metrics: before, params: rule.params || {} });
+    const ok = kind === 'fire' ? found.length > 0 : found.length === 0;
+    let detail = `${found.length} override(s)`;
+    let harm = false;
+    if (kind === 'fire' && found.length) {
+      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 expectFile = path.join(dir, 'expect.json');
+      if (fs.existsSync(expectFile)) {
+        const expect = JSON.parse(fs.readFileSync(expectFile, 'utf8'));
+        for (const e of expect) {
+          const m = merged.find((o) => o.id === e.id);
+          const good = m && (e.dx == null || near(m.dx, e.dx)) && (e.dy == null || near(m.dy, e.dy)) && (e.w == null || near(m.w, e.w, 1)) && (e.h == null || near(m.h, e.h, 1)) && (!e.css || Object.entries(e.css).every(([k, v]) => m.css[k] === v));
+          if (!good) { detail += `; expected ${JSON.stringify(e)} got ${JSON.stringify(m || null)}`; failures++; }
+        }
+      }
+    }
+    if (!ok || harm) failures++;
+    console.log(`${ok && !harm ? 'ok  ' : 'FAIL'} ${rule.name}/${kind}: ${detail}${harm ? ' HARM' : ''}`);
+  }
+}
+await browser.close();
+if (failures) { console.log(`${failures} failure(s)`); process.exit(1); }
+console.log('all polish rule pairs green');

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

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { chromium } from '@playwright/test';
 import { checkRuntime } from '../lib/runtime-check.mjs';
@@ -130,9 +132,19 @@ const interactionReachability = {
   ordinaryControl: interactionPage('ordinary-dropdown.html')?.dropdown,
 };
 
+const blockingScratch = fs.mkdtempSync(path.join(os.tmpdir(), 'prototype-blocking-runtime-'));
+const blockingAuditFile = path.join(blockingScratch, 'runtime-audit.json');
+const blockingVerification = spawnSync(process.execPath, [
+  path.join(kitDir, 'verify-runtime.mjs'),
+  path.join(kitDir, 'tests', 'fixtures', 'blocking-runtime'),
+  blockingAuditFile,
+], { cwd: kitDir, encoding: 'utf8', timeout: 30_000 });
+const blockingAudit = JSON.parse(fs.readFileSync(blockingAuditFile, 'utf8'));
+fs.rmSync(blockingScratch, { recursive: true, force: true });
+
 await browser.close();
 await server.close();
-const result = { doubleBinding, nestedBinding, dropdownGuard, hoverStacking, deepLinkBack, accessibleBack, pageBack, holdingComposition, shellNavigation, interactionReachability };
+const result = { doubleBinding, nestedBinding, dropdownGuard, hoverStacking, deepLinkBack, accessibleBack, pageBack, holdingComposition, shellNavigation, interactionReachability, blockingInteraction: { status: blockingVerification.status, failures: blockingAudit.interactionFailures } };
 if (process.argv.includes('--assert')) {
   assert.deepEqual(doubleBinding, { overlayRoots: 1, modals: 1 }, 'runtime must bind exactly once when injected twice');
   assert.deepEqual(nestedBinding, { modals: 1, menus: 0 }, 'the innermost action must stop a parent binding from also firing');
@@ -182,6 +194,9 @@ 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.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');
 }
 const json = JSON.stringify(result, null, 2) + '\n';
 if (outFile) fs.writeFileSync(outFile, json);

package/prototype-kit/tests/fixtures/blocking-runtime/broken-interaction.html

@@ -0,0 +1,7 @@
+<!doctype html><html><head><meta charset="utf-8"><style>
+html,body{margin:0;width:1536px;height:1024px}.control{position:absolute;left:120px;top:120px;width:220px;height:44px}.interceptor{position:fixed;inset:0;z-index:20;background:rgba(255,255,255,.01)}
+</style></head><body>
+<button id="broken-dropdown" class="control" data-proto-action="dropdown" data-proto-options='["One","Two","Three"]'>Menu</button>
+<div class="interceptor" aria-hidden="true"></div>
+<script id="proto-state" type="application/json">{"unit":"broken-interaction","tokens":{},"contentFile":null}</script>
+</body></html>

package/prototype-kit/tests/fixtures/four-dropdown/branch.plan.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "scope": "site",
+  "concept": "Observed four-candidate dropdown degradation shape",
+  "pages": [
+    {
+      "index": 0,
+      "id": "p2-stream-proposals",
+      "title": "Stream proposals",
+      "surfaceType": "web_app",
+      "purpose": "Review proposed streams.",
+      "startsFromWinner": true,
+      "slots": ["b"]
+    },
+    {
+      "index": 1,
+      "id": "p4-live-stream-results",
+      "title": "Live stream results",
+      "surfaceType": "web_app",
+      "purpose": "Review live stream performance.",
+      "startsFromWinner": false,
+      "slots": ["e"]
+    }
+  ],
+  "screens": [
+    { "slot": "b", "pageIndex": 0, "content": "Stream proposal filters", "dependsOnSlot": null },
+    { "slot": "e", "pageIndex": 1, "content": "Live stream date filter", "dependsOnSlot": null }
+  ]
+}

package/prototype-kit/tests/fixtures/four-dropdown/pages/p2-stream-proposals.html

@@ -0,0 +1,10 @@
+<!doctype html>
+<html><head><meta charset="utf-8"><style>
+html,body,#page-flow,#viewport-1-b{margin:0;width:1536px;height:1024px;font-family:Arial,sans-serif}
+.filter{position:absolute;display:flex;align-items:center;justify-content:space-between;width:280px;height:44px}.text{font-size:16px}.icon{width:16px;height:16px}
+#viewport-1-b-filters{left:80px;top:180px}#viewport-1-b-sort{left:80px;top:260px}#viewport-1-b-table-footer{left:80px;top:340px}
+</style></head><body><main id="page-flow"><section id="viewport-1-b">
+<button class="filter" id="viewport-1-b-filters"><span class="text" id="viewport-1-b-filters-device-button">All countries</span><span class="icon" id="viewport-1-b-filters-language-icon-2" aria-label="Chevron down">⌄</span></button>
+<button class="filter" id="viewport-1-b-sort"><span class="text" id="viewport-1-b-sort-text">Sort by</span><span class="icon" id="viewport-1-b-sort-icon" aria-label="Chevron down">⌄</span></button>
+<button class="filter" id="viewport-1-b-table-footer"><span class="text" id="viewport-1-b-table-footer-text-2">Compare</span><span class="icon" id="viewport-1-b-table-footer-icon" aria-label="Chevron down">⌄</span></button>
+</section></main></body></html>

package/prototype-kit/tests/fixtures/four-dropdown/pages/p4-live-stream-results.html

@@ -0,0 +1,7 @@
+<!doctype html>
+<html><head><meta charset="utf-8"><style>
+html,body,#page-flow,#viewport-1-e{margin:0;width:1536px;height:1024px;font-family:Arial,sans-serif}
+.filter{position:absolute;left:80px;top:180px;display:flex;align-items:center;justify-content:space-between;width:460px;height:44px}.text{font-size:16px}.icon{width:16px;height:16px}
+</style></head><body><main id="page-flow"><section id="viewport-1-e">
+<button class="filter" id="viewport-1-e-main-date-filter"><span class="text" id="viewport-1-e-main-date-filter-text">compared to Apr 6 – May 5, 2025</span><span class="icon" id="viewport-1-e-main-date-filter-icon-3" aria-label="Chevron down">⌄</span></button>
+</section></main></body></html>

package/prototype-kit/tests/fixtures/shell-stitching-runtime/PROVENANCE.md

@@ -0,0 +1,22 @@
+# Responsive shell-stitching runtime fixture
+
+This reduced three-page branch preserves the deterministic mechanism found by
+the 2026-08-25 b13 header-signature refusal study. The full artifact's canonical
+Central Station Departures and stitched Network Map pages had byte-identical
+`#mobile-390-header` DOM and identical outer geometry `[0, 0, 390, 72.5]`, but
+their runtime signatures differed:
+
+- donor: `47b710c2aee9240892128ad7271eb0451792db7d8b1c1650c36bc076770ca088`;
+- recipient: `5f1aae89d7c2083b27edc7c50e265bb844ed2760722b8dccea91a8c07ab4fbf9`.
+
+The recipient stylesheet still addressed the reused `mobile-390-header-*` ids.
+Its `left` and `top` declarations therefore survived the later, property-partial
+donor rules and displaced donor descendants. The fixture keeps that exact
+boundary: the donor omits `left`/`top`, while the recipient declares them on the
+same responsive ids. Native shell identities stay distinct so the failure is
+isolated to the 390px band.
+
+The third page is the paired silent control. It renders the donor shell but has
+different product content and a substantially taller portrait canvas. Its shell
+signature must remain equal to the donor's because canvas and body variation are
+outside the declared shell subtree.

package/prototype-kit/tests/fixtures/shell-stitching-runtime/branch.plan.json

@@ -0,0 +1,40 @@
+{
+  "version": 1,
+  "scope": "site",
+  "concept": "Canonical responsive shell CSS isolation fixture",
+  "sitePurpose": "Exercise one donor shell, one colliding recipient, and one canvas-only control.",
+  "pages": [
+    {
+      "index": 0,
+      "id": "p0-donor",
+      "title": "Departures",
+      "surfaceType": "web_app",
+      "purpose": "Provide the canonical responsive header.",
+      "startsFromWinner": true,
+      "slots": ["a"]
+    },
+    {
+      "index": 1,
+      "id": "p1-id-collision",
+      "title": "Network map",
+      "surfaceType": "web_app",
+      "purpose": "Reuse responsive header ids under recipient-specific offsets.",
+      "startsFromWinner": false,
+      "slots": ["b"]
+    },
+    {
+      "index": 2,
+      "id": "p2-canvas-control",
+      "title": "Service notes",
+      "surfaceType": "web_app",
+      "purpose": "Keep the canonical header while changing content and canvas height.",
+      "startsFromWinner": false,
+      "slots": ["c"]
+    }
+  ],
+  "screens": [
+    { "slot": "a", "pageIndex": 0, "content": "Departures content", "dependsOnSlot": null },
+    { "slot": "b", "pageIndex": 1, "content": "Network map content", "dependsOnSlot": null },
+    { "slot": "c", "pageIndex": 2, "content": "Long service notes content", "dependsOnSlot": null }
+  ]
+}

package/prototype-kit/tests/fixtures/shell-stitching-runtime/pages/p0-donor.html

@@ -0,0 +1,38 @@
+<!doctype html>
+<html><head><meta charset="utf-8"><style>
+html,body,#page-flow{margin:0;width:100%;min-height:100%;font-family:Arial,sans-serif;background:#eef2f4}.ly-band{display:none}.generated-screen,.ly-anchor-canvas{position:relative}.generated-screen{width:100%}.text{margin:0}.fixture-shell{box-sizing:border-box;color:#f7fafc;background:#071923}
+@media(max-width:959px){.ly-band[data-ly-band="mobile-390"]{display:block}}
+@media(min-width:960px){.ly-band[data-ly-band="native"]{display:block}}
+#donor-mobile-canvas{width:390px;height:900px;background:#dce7eb}
+#mobile-390-header{position:relative;display:flex;align-items:flex-start;margin:0;width:390px;height:72px;background:#071923}
+#mobile-390-header-brand{position:relative;margin:20px 0 0 20px;width:100px;height:28px}
+#mobile-390-header-time{position:relative;margin:20px 0 0 90px;width:80px;height:32px}
+#mobile-390-header-menu{position:relative;margin:24px 0 0 25px;width:24px;height:24px}
+#mobile-390-header-divider{position:absolute;left:0;bottom:0;width:390px;height:2px;background:#3e5e6d}
+#mobile-390-header-brand-text{font-size:16px;line-height:28px;font-weight:700}
+#mobile-390-header-time-text{font-size:14px;line-height:16px;font-weight:600}
+#mobile-390-header-time-live{font-size:11px;line-height:16px;color:#b6f437}
+#mobile-390-header-menu-icon{display:block;width:24px;height:24px;font-size:20px;line-height:24px;text-align:center}
+#donor-mobile-content{padding:44px 24px;color:#17252c}
+#viewport-1-a{position:relative;width:1536px;height:1024px;background:#eef2f4}
+#viewport-1-a-header{position:absolute;left:0;top:0;display:flex;align-items:center;width:1536px;height:72px}
+#viewport-1-a-header-brand{margin-left:32px;font-size:16px;line-height:24px;font-weight:700}
+#viewport-1-a-header-status{margin-left:1200px;font-size:14px;line-height:24px}
+#viewport-1-a-content{position:absolute;left:80px;top:150px;width:800px;height:400px;color:#17252c}
+</style></head><body><main id="page-flow">
+<div class="ly-band" data-ly-band="mobile-390"><div class="generated-screen"><div id="donor-mobile-canvas" class="ly-anchor-canvas">
+  <header id="mobile-390-header" class="fixture-shell">
+    <div id="mobile-390-header-brand"><p id="mobile-390-header-brand-text" class="text">Kinetic</p></div>
+    <div id="mobile-390-header-time"><p id="mobile-390-header-time-text" class="text">09:42</p><p id="mobile-390-header-time-live" class="text">Live</p></div>
+    <nav id="mobile-390-header-menu"><span id="mobile-390-header-menu-icon" class="icon" role="img" aria-label="Menu">≡</span></nav>
+    <div id="mobile-390-header-divider" class="divider"></div>
+  </header>
+  <article id="donor-mobile-content"><h1>Central departures</h1><p>Two platforms are boarding.</p></article>
+</div></div></div>
+<div class="ly-band" data-ly-band="native"><div class="generated-screen"><div class="ly-anchor-canvas">
+  <section id="viewport-1-a">
+    <header id="viewport-1-a-header" class="fixture-shell"><p id="viewport-1-a-header-brand" class="text">Kinetic</p><p id="viewport-1-a-header-status" class="text">Live service</p></header>
+    <div id="viewport-1-a-content"><h1 id="viewport-1-a-content-title">Central departures</h1><p id="viewport-1-a-content-copy">Two platforms are boarding.</p></div>
+  </section>
+</div></div></div>
+</main></body></html>

package/prototype-kit/tests/fixtures/shell-stitching-runtime/pages/p1-id-collision.html

@@ -0,0 +1,38 @@
+<!doctype html>
+<html><head><meta charset="utf-8"><style>
+html,body,#page-flow{margin:0;width:100%;min-height:100%;font-family:Arial,sans-serif;background:#eef2f4}.ly-band{display:none}.generated-screen,.ly-anchor-canvas{position:relative}.generated-screen{width:100%}.text{margin:0}.fixture-shell{box-sizing:border-box;color:#f7fafc;background:#071923}
+@media(max-width:959px){.ly-band[data-ly-band="mobile-390"]{display:block}}
+@media(min-width:960px){.ly-band[data-ly-band="native"]{display:block}}
+#collision-mobile-canvas{width:390px;height:900px;background:#d9e4e8}
+#mobile-390-header{position:relative;margin:0;width:390px;height:72px;background:#0a202b}
+#mobile-390-header-brand{position:absolute;left:25px;top:22px;width:104px;height:30px}
+#mobile-390-header-time{position:absolute;left:215px;top:19px;width:82px;height:34px}
+#mobile-390-header-menu{position:absolute;left:340px;top:23px;width:26px;height:26px}
+#mobile-390-header-divider{position:absolute;left:0;top:68px;width:390px;height:2px;background:#476b7a}
+#mobile-390-header-brand-text{font-size:16px;line-height:28px;font-weight:700}
+#mobile-390-header-time-text{font-size:14px;line-height:16px;font-weight:600}
+#mobile-390-header-time-live{font-size:11px;line-height:16px;color:#b6f437}
+#mobile-390-header-menu-icon{display:block;width:24px;height:24px;font-size:20px;line-height:24px;text-align:center}
+#collision-mobile-content{padding:70px 36px;color:#17252c}
+#viewport-1-b{position:relative;width:1536px;height:1024px;background:#eef2f4}
+#viewport-1-b-header{position:absolute;left:0;top:0;display:flex;align-items:center;width:1536px;height:72px}
+#viewport-1-b-header-brand{margin-left:32px;font-size:16px;line-height:24px;font-weight:700}
+#viewport-1-b-header-status{margin-left:1200px;font-size:14px;line-height:24px}
+#viewport-1-b-content{position:absolute;left:110px;top:180px;width:900px;height:420px;color:#17252c}
+</style></head><body><main id="page-flow">
+<div class="ly-band" data-ly-band="mobile-390"><div class="generated-screen"><div id="collision-mobile-canvas" class="ly-anchor-canvas">
+  <header id="mobile-390-header" class="fixture-shell">
+    <div id="mobile-390-header-brand"><p id="mobile-390-header-brand-text" class="text">Kinetic</p></div>
+    <div id="mobile-390-header-time"><p id="mobile-390-header-time-text" class="text">09:42</p><p id="mobile-390-header-time-live" class="text">Live</p></div>
+    <nav id="mobile-390-header-menu"><span id="mobile-390-header-menu-icon" class="icon" role="img" aria-label="Menu">≡</span></nav>
+    <div id="mobile-390-header-divider" class="divider"></div>
+  </header>
+  <article id="collision-mobile-content"><h1>Network map</h1><p>Choose a station to inspect its connections.</p></article>
+</div></div></div>
+<div class="ly-band" data-ly-band="native"><div class="generated-screen"><div class="ly-anchor-canvas">
+  <section id="viewport-1-b">
+    <header id="viewport-1-b-header" class="fixture-shell"><p id="viewport-1-b-header-brand" class="text">Kinetic</p><p id="viewport-1-b-header-status" class="text">Live service</p></header>
+    <div id="viewport-1-b-content"><h1 id="viewport-1-b-content-title">Network map</h1><p id="viewport-1-b-content-copy">Choose a station to inspect its connections.</p></div>
+  </section>
+</div></div></div>
+</main></body></html>

package/prototype-kit/tests/fixtures/shell-stitching-runtime/pages/p2-canvas-control.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html><head><meta charset="utf-8"><style>
+html,body,#page-flow{margin:0;width:100%;min-height:100%;font-family:Arial,sans-serif;background:#f3eee6}.ly-band{display:none}.generated-screen,.ly-anchor-canvas{position:relative}.generated-screen{width:100%}.text{margin:0}.fixture-shell{box-sizing:border-box;color:#f7fafc;background:#071923}
+@media(max-width:959px){.ly-band[data-ly-band="mobile-390"]{display:block}}
+@media(min-width:960px){.ly-band[data-ly-band="native"]{display:block}}
+#control-mobile-canvas{width:390px;height:1400px;background:#f3eee6}
+#mobile-390-header{position:relative;display:flex;align-items:flex-start;margin:0;width:390px;height:72px;background:#071923}
+#mobile-390-header-brand{position:relative;margin:20px 0 0 20px;width:100px;height:28px}
+#mobile-390-header-time{position:relative;margin:20px 0 0 90px;width:80px;height:32px}
+#mobile-390-header-menu{position:relative;margin:24px 0 0 25px;width:24px;height:24px}
+#mobile-390-header-divider{position:absolute;left:0;bottom:0;width:390px;height:2px;background:#3e5e6d}
+#mobile-390-header-brand-text{font-size:16px;line-height:28px;font-weight:700}
+#mobile-390-header-time-text{font-size:14px;line-height:16px;font-weight:600}
+#mobile-390-header-time-live{font-size:11px;line-height:16px;color:#b6f437}
+#mobile-390-header-menu-icon{display:block;width:24px;height:24px;font-size:20px;line-height:24px;text-align:center}
+#control-mobile-content{padding:96px 28px;color:#30271f}
+#control-mobile-content section{margin-top:180px;padding:28px;background:#fff;border-radius:16px}
+#viewport-1-c{position:relative;width:1536px;height:1400px;background:#f3eee6}
+#viewport-1-c-header{position:absolute;left:0;top:0;display:flex;align-items:center;width:1536px;height:72px}
+#viewport-1-c-header-brand{margin-left:32px;font-size:16px;line-height:24px;font-weight:700}
+#viewport-1-c-header-status{margin-left:1200px;font-size:14px;line-height:24px}
+#viewport-1-c-content{position:absolute;left:140px;top:220px;width:1000px;height:900px;color:#30271f}
+</style></head><body><main id="page-flow">
+<div class="ly-band" data-ly-band="mobile-390"><div class="generated-screen"><div id="control-mobile-canvas" class="ly-anchor-canvas">
+  <header id="mobile-390-header" class="fixture-shell">
+    <div id="mobile-390-header-brand"><p id="mobile-390-header-brand-text" class="text">Kinetic</p></div>
+    <div id="mobile-390-header-time"><p id="mobile-390-header-time-text" class="text">09:42</p><p id="mobile-390-header-time-live" class="text">Live</p></div>
+    <nav id="mobile-390-header-menu"><span id="mobile-390-header-menu-icon" class="icon" role="img" aria-label="Menu">≡</span></nav>
+    <div id="mobile-390-header-divider" class="divider"></div>
+  </header>
+  <article id="control-mobile-content"><h1>Service notes</h1><p>This deliberately taller route has unrelated portrait content.</p><section><h2>Maintenance archive</h2><p>Older notices continue far below the shared shell.</p></section></article>
+</div></div></div>
+<div class="ly-band" data-ly-band="native"><div class="generated-screen"><div class="ly-anchor-canvas">
+  <section id="viewport-1-c">
+    <header id="viewport-1-c-header" class="fixture-shell"><p id="viewport-1-c-header-brand" class="text">Kinetic</p><p id="viewport-1-c-header-status" class="text">Live service</p></header>
+    <div id="viewport-1-c-content"><h1 id="viewport-1-c-content-title">Service notes</h1><p id="viewport-1-c-content-copy">This route has substantially more content and a taller canvas.</p></div>
+  </section>
+</div></div></div>
+</main></body></html>

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

@@ -44,7 +44,7 @@ const outputDigest = (directory) => {
 };
 assert.equal(
   outputDigest(threeShell.protoDir),
-  '5168cc6926988d3bee32d5e890792e989417d9ca78376282f988ebf7875a57bc',
+  '0c2147df5bc6552016cc278faec7abaabecbc7f5945cad7e1ac9b1df6e554403',
   '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

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import assert from 'node:assert/strict';
 import { parseHTML } from 'linkedom';
-import { suppressDeterministicAction, usableDropdownOptions } from '../lib/actions.mjs';
+import { resolveDropdownAction, suppressDeterministicAction, usableDropdownOptions } from '../lib/actions.mjs';
 import { restoreActionPointerReachability } from '../lib/action-target.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 { stitchUnitShells } from '../lib/shell-stitching.mjs';
 import { compareCanonicalShells, isWithinShell, qualifiesShellCandidate, selectOneShellPerRegion, shouldSuppressDroppedShell, shouldTransplantShell } from '../lib/shells.mjs';
 import { slugText } from '../lib/text.mjs';
@@ -27,6 +28,37 @@ assert.equal(usableDropdownOptions(['Only choice']), null, 'must fire: a one-opt
 assert.deepEqual(usableDropdownOptions(['All', 'Open', 'Closed']), ['All', 'Open', 'Closed'], 'must stay silent: a real three-option dropdown remains bindable');
 assert.equal(suppressDeterministicAction({ action: 'none' }), true, 'must fire: a recovered explicit none suppresses an unsafe deterministic dropdown');
 assert.equal(suppressDeterministicAction({ action: 'dropdown', options: ['All', 'Open', 'Closed'] }), false, 'must stay silent: a valid labeled dropdown remains bindable');
+assert.deepEqual(resolveDropdownAction({
+  deterministic: { action: 'dropdown' },
+  label: { action: 'none' },
+  labelId: 'filter-label',
+}), {
+  disposition: 'static',
+  degradation: {
+    code: 'label_none_overrode_deterministic_dropdown',
+    reason: 'explicit-label-none',
+    fromAction: 'dropdown',
+    toAction: 'none',
+    options: [],
+  },
+}, 'must fire: normalized none becomes one recorded static dropdown policy outcome');
+assert.deepEqual(resolveDropdownAction({
+  deterministic: { action: 'dropdown' },
+  label: { action: 'dropdown', options: ['All', 'Open', 'Closed'] },
+  labelId: 'filter-label',
+}), {
+  disposition: 'dropdown',
+  action: { action: 'dropdown', labelId: 'filter-label', options: ['All', 'Open', 'Closed'] },
+}, 'must stay silent: a proven three-option dropdown remains actionable');
+assert.equal(
+  resolveDropdownAction({
+    deterministic: { action: 'dropdown' },
+    label: { action: 'modal', options: null },
+    labelId: 'filter-label',
+  }).degradation.code,
+  'dropdown_options_incomplete',
+  'must fire: a deterministic dropdown with no usable label options is recorded and kept static',
+);
 
 const unreachableDropdown = parseHTML('<span id="viewport-1-c-journeys-harbourfront-source-row-1-icon" style="width:29.696px;height:11.264px;pointer-events:none">...</span>').document.querySelector('span');
 assert.equal(restoreActionPointerReachability(unreachableDropdown), true, 'must fire: the exact failed Saved Journeys dropdown target becomes pointer reachable');
@@ -106,6 +138,34 @@ assert.equal(linkedNavForUnit({ navRows: [{ region: 'header', text: 'Journal', t
 
 const rulesForFixture = () => '';
 const styleTextFixture = () => '';
+const identityRecipient = parseHTML('<html><body><div id="donor-shell"><span id="donor-shell-label"></span></div></body></html>').document;
+const identityDonor = parseHTML('<html><body><section id="donor-shell" aria-labelledby="donor-shell-label"><label id="donor-shell-label" for="donor-shell-field">Name</label><input id="donor-shell-field"><svg id="donor-shell-icon" aria-labelledby="donor-shell-label"><use id="donor-shell-icon-use" href="#donor-shell-icon"></use></svg></section></body></html>').document;
+const isolatedIdentity = isolateTransplantedShell({
+  document: identityRecipient,
+  sourceElement: identityDonor.getElementById('donor-shell'),
+  css: '#donor-shell{display:block}#donor-shell-label{color:red}#donor-shell-icon-use{fill:url(#donor-shell-icon)}',
+  namespaceParts: ['mobile-390', 'header'],
+});
+const isolatedIdentityDocument = parseHTML(`<html><body>${isolatedIdentity.html}</body></html>`).document;
+const isolatedIdentityRoot = isolatedIdentityDocument.getElementById(isolatedIdentity.rootId);
+const isolatedIdentityLabel = shellElementsForSourceId(isolatedIdentityRoot, 'donor-shell-label')[0];
+const isolatedIdentityField = shellElementsForSourceId(isolatedIdentityRoot, 'donor-shell-field')[0];
+const isolatedIdentityIcon = shellElementsForSourceId(isolatedIdentityRoot, 'donor-shell-icon')[0];
+assert.notEqual(isolatedIdentity.rootId, 'donor-shell', 'must fire: the physical donor root cannot reuse a recipient identity');
+assert.equal(isolatedIdentityRoot.getAttribute('aria-labelledby'), isolatedIdentityLabel.id, 'must fire: ARIA id references follow isolated identities');
+assert.equal(isolatedIdentityLabel.getAttribute('for'), isolatedIdentityField.id, 'must fire: form id references follow isolated identities');
+assert.equal(isolatedIdentityRoot.querySelector('use').getAttribute('href'), `#${isolatedIdentityIcon.id}`, 'must fire: fragment references follow isolated identities');
+assert.ok(isolatedIdentity.css.includes(`#${isolatedIdentityLabel.id}{color:red}`), 'must fire: exact donor CSS selectors follow isolated identities');
+assert.ok(isolatedIdentity.css.includes(`url(#${isolatedIdentityIcon.id})`), 'must fire: CSS fragment references follow isolated identities');
+assert.equal(isolatedIdentity.css.includes('#donor-shell'), false, 'must stay silent: no donor id selector remains available to recipient CSS');
+const duplicateDonor = parseHTML('<html><body><section id="duplicate-shell"><span id="duplicate-child"></span><span id="duplicate-child"></span></section></body></html>').document;
+assert.throws(() => isolateTransplantedShell({
+  document: identityRecipient,
+  sourceElement: duplicateDonor.getElementById('duplicate-shell'),
+  css: '',
+  namespaceParts: ['native', 'header'],
+}), /duplicate donor id duplicate-child/, 'must fire: invalid donor identity cannot be ambiguously namespaced');
+
 const noWriteDocument = parseHTML('<html><head></head><body><header id="detail-header"><span id="detail-home">Home</span><img id="detail-ink" alt="Home navigation underline"></header></body></html>').document;
 const noWriteBefore = noWriteDocument.documentElement.outerHTML;
 const noWriteResult = stitchUnitShells({
@@ -135,8 +195,14 @@ const fireResult = stitchUnitShells({
   styleText: styleTextFixture,
 });
 assert.equal(fireResult.changes, 1, 'must fire: a measured incompatible fingerprint commits the declared donor shell');
-assert.ok(fireDocument.getElementById('journal-header'), 'must fire: the canonical donor outer shell replaces the recipient shell');
-assert.ok(fireDocument.getElementById('menu-ink'), 'must fire: the page-declared Menu underline is retained and moved into the donor shell');
+const isolatedHeader = shellElementsForSourceId(fireDocument, 'journal-header')[0];
+const isolatedMarker = shellElementsForSourceId(fireDocument, 'menu-ink')[0];
+assert.ok(isolatedHeader, 'must fire: the canonical donor outer shell replaces the recipient shell');
+assert.notEqual(isolatedHeader.id, 'journal-header', 'must fire: transplanted donor identity is physically isolated from recipient CSS');
+assert.ok(isolatedMarker && isolatedHeader.contains(isolatedMarker), 'must fire: the page-declared Menu underline is retained and moved into the isolated donor shell');
+assert.equal(fireDocument.getElementById('menu-header')?.getAttribute('data-proto-shell-space'), 'header', 'must stay silent: the recipient shell remains an invisible flow spacer under its own identity');
 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);
 
 process.stdout.write('rules: ok\n');

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

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { chromium } from '@playwright/test';
+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 testsDir = path.dirname(new URL(import.meta.url).pathname);
+const kitDir = path.resolve(testsDir, '..');
+const fixtureDir = path.join(testsDir, 'fixtures', 'shell-stitching-runtime');
+const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'proto-shell-stitching-'));
+const runWorkDir = path.join(scratch, 'build');
+let browser = null;
+let server = null;
+
+const regionAt = (audit, file, width) => audit.pages
+  .find((page) => page.file === file)?.viewports
+  .find((viewport) => viewport.width === width)?.shellState?.regions
+  .find((region) => region.region === 'header') || null;
+const bandHeight = (inventory, pageId, key) => inventory.pages
+  .find((page) => page.pageId === pageId)?.bands
+  .find((band) => band.key === key)?.height;
+const decisionFor = (manifest, unitId) => manifest.units
+  .find((unit) => unit.id === unitId)?.shellDecisions
+  .find((decision) => decision.region === 'header') || null;
+
+try {
+  const built = buildPrototype({
+    kitDir,
+    run: { runDir: fixtureDir },
+    runWorkDir,
+  });
+  assert.equal(built.ok, true, `fixture pipeline must build: ${built.failedStage || 'unknown stage'} ${built.stages?.[built.failedStage]?.error || ''}`);
+
+  const inventory = JSON.parse(fs.readFileSync(built.inventoryFile, 'utf8'));
+  const manifest = JSON.parse(fs.readFileSync(path.join(built.protoDir, 'proto-manifest.json'), 'utf8'));
+  assert.equal(manifest.canonicalShellPage?.pageId, 'p0-donor', 'fixture contract: the approved donor is the one canonical shell page');
+  assert.deepEqual(decisionFor(manifest, 'id-collision'), { region: 'header', commit: true, reason: 'compatible' }, 'fixture contract: differing compatible bands request one atomic transplant');
+  assert.deepEqual(decisionFor(manifest, 'canvas-control'), { region: 'header', commit: false, reason: 'compatible' }, 'must stay silent: the already canonical control does not request a write');
+  assert.deepEqual([
+    bandHeight(inventory, 'p0-donor', 'mobile-390'),
+    bandHeight(inventory, 'p2-canvas-control', 'mobile-390'),
+  ], [900, 1400], 'fixture contract: the portrait control has a substantially taller canvas');
+
+  server = await startStaticServer(runWorkDir);
+  browser = await chromium.launch();
+  const audit = await checkRuntime({
+    browser,
+    baseUrl: server.baseUrl,
+    relativeProtoPath: 'proto',
+    protoDir: built.protoDir,
+  });
+
+  assert.equal(audit.pageErrors, 0, 'fixture pages must load without page errors');
+  assert.equal(audit.consoleErrors, 0, 'fixture pages must not emit console errors');
+  assert.equal(audit.duplicateIds, 0, 'shell replacement must not leave duplicate ids');
+
+  const donor390 = regionAt(audit, 'donor.html', 390);
+  const collision390 = regionAt(audit, 'id-collision.html', 390);
+  const control390 = regionAt(audit, 'canvas-control.html', 390);
+  const donor1536 = regionAt(audit, 'donor.html', 1536);
+  const collision1536 = regionAt(audit, 'id-collision.html', 1536);
+  assert.ok(donor390 && collision390 && control390 && donor1536 && collision1536, 'fixture contract: all audited header regions are present');
+  assert.deepEqual(donor390.actualGeometry, [0, 0, 390, 72], 'fixture contract: donor mobile shell geometry is fixed');
+  assert.deepEqual(collision390.actualGeometry, donor390.actualGeometry, 'outer shell geometry alone cannot conceal descendant displacement');
+  assert.equal(donor390.consistencyStatus, 'canonical', 'fixture contract: the donor makes the canonical shell claim');
+  assert.equal(collision390.consistencyStatus, 'canonical', 'fixture contract: the committed recipient makes the canonical shell claim');
+  assert.equal(control390.consistencyStatus, 'silent', 'must stay silent: canvas/content-only variation makes no canonical-write claim');
+  assert.equal(control390.actualSignature, donor390.actualSignature, 'must stay silent: canvas height and page content are outside the shell signature');
+  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');
+    const failure = audit.shellConsistencyFailures[0];
+    assert.equal(failure.reason, 'prototype-shell-signature-mismatch', 'pre-fix 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 },
+    ], 'pre-fix group carries the exact runtime signatures for only the donor and committed recipient');
+  } else {
+    assert.equal(collision390.actualSignature, donor390.actualSignature, 'must pass after the fix: transplanted donor render matches its canonical source at 390');
+    assert.deepEqual(audit.shellConsistencyFailures, [], 'post-fix runtime audit has no canonical shell consistency failures');
+  }
+
+  process.stdout.write(JSON.stringify({
+    expectation: expectFailure ? 'pre-fix-failure' : 'post-fix-pass',
+    groups,
+    mobile: {
+      donor: donor390.actualSignature,
+      collision: collision390.actualSignature,
+      control: control390.actualSignature,
+      geometry: donor390.actualGeometry,
+    },
+    native: {
+      donor: donor1536.actualSignature,
+      collision: collision1536.actualSignature,
+    },
+    canvasHeights: {
+      donor: bandHeight(inventory, 'p0-donor', 'mobile-390'),
+      control: bandHeight(inventory, 'p2-canvas-control', 'mobile-390'),
+    },
+  }, null, 2) + '\n');
+} finally {
+  if (browser) await browser.close();
+  if (server) await server.close();
+  fs.rmSync(scratch, { recursive: true, force: true });
+}

package/skills/12ui-design/SKILL.md

@@ -39,10 +39,14 @@ Execute stays in the foreground through its network work; `next` can report prog
 
 Use `--prototype` with `--convert html` when the deliverable should be clickable. The export becomes a working app — navigation, shared shells, and holding pages for unbuilt routes — written to `<run-dir>/branch/prototype/`.
 
+Add `--polish` only when the user wants the opt-in production-feel pass. It runs the retained deterministic, harm-guarded rules after build, records every rule as fired, silent, or reverted, and runs the prototype runtime gates on that polished output.
+
 For a completed branch that was exported without the flag, run:
 
     12ui prototype <run-dir>
 
+The same opt-in is available here as `12ui prototype <run-dir> --polish`.
+
 ## 3. Convert
 
 When you have a single image to convert (or for example only designing a single viewport), you can directly convert the image instead of branching it.