@12ui/design 0.2.43 → 0.2.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12ui/design",
-  "version": "0.2.43",
+  "version": "0.2.44",
   "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/tests/rules-check.mjs && node prototype-kit/tests/offline-check.mjs && node prototype-kit/tests/adversarial-runtime.mjs --assert",
+    "test:prototype": "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",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.type-tests.json",
     "prepublishOnly": "npm run build"
   },

package/prototype-kit/build.mjs

@@ -3,7 +3,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseHTML } from 'linkedom';
-import { suppressDeterministicAction, usableDropdownOptions } from './lib/actions.mjs';
+import { resolveDropdownAction } from './lib/actions.mjs';
 import { restoreActionPointerReachability } from './lib/action-target.mjs';
 import {
   HOLDING_SHELL_ATTRIBUTE,
@@ -13,6 +13,12 @@ import {
   shellPlacementCss,
 } from './lib/holding-composition.mjs';
 import { injectReviewFraming } from './lib/review-framing.mjs';
+import {
+  isolateTransplantedShell,
+  rulesFor,
+  shellElementsForSourceId,
+  shellSelectorForSourceId,
+} from './lib/shell-identity.mjs';
 import { stitchUnitShells } from './lib/shell-stitching.mjs';
 import { shouldSuppressDroppedShell } from './lib/shells.mjs';
 import { normalizeText as norm, slugText as slug } from './lib/text.mjs';
@@ -98,11 +104,6 @@ function loadDoc(file) {
   return parseHTML(docCache.get(file));
 }
 function styleText(document) { return [...document.querySelectorAll('style')].map((s) => s.textContent).join('\n'); }
-function rulesFor(css, id) {
-  // one selector per rule in these exports; grab every rule whose selector is #id or #id-...
-  const re = new RegExp(`#${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:-[A-Za-z0-9_-]*)?(?:[:>\\s][^{]*)?\\{[^}]*\\}`, 'g');
-  return (css.match(re) || []).join('\n');
-}
 
 // ---- canonical shell HTML/CSS per region
 const shell = {};
@@ -154,6 +155,7 @@ const report = {
   units: [],
   unbound: [],
   invalidDropdowns: [],
+  actionDemotions: [],
   shellSizeDelta: [],
   shellAmbiguities: model.shellAmbiguities || [],
   suppressedShellOverlaps: [],
@@ -198,15 +200,27 @@ function actionsFor(s) {
     if (d && l) { if (d.action === l.action) report.counts.agree++; else report.counts.disagree++; }
     else if (d) report.counts.detOnly++; else if (l) report.counts.lunaOnly++;
     let a = null;
-    if (suppressDeterministicAction(l)) {
+    const dropdown = resolveDropdownAction({
+      deterministic: d,
+      label: l,
+      labelId: d?.labelId || c.textId || (c.kind === 'link' ? c.id : null),
+    });
+    if (dropdown.disposition === 'dropdown') a = dropdown.action;
+    else if (dropdown.disposition === 'static') {
+      const demotion = {
+        state: s.stateId,
+        id: c.id,
+        ...dropdown.degradation,
+      };
+      report.actionDemotions.push(demotion);
+      if (dropdown.degradation.code === 'dropdown_options_incomplete') {
+        report.invalidDropdowns.push(demotion);
+      }
+    }
+    else if (dropdown.disposition === 'suppressed') {
       // A recovered explicit none is the labeler's durable decision that this
       // candidate is not safely actionable. Do not resurrect a deterministic
-      // dropdown with missing choices and fail publication downstream.
-    }
-    else if (d?.action === 'dropdown' || l?.action === 'dropdown') {
-      const options = usableDropdownOptions(l?.options);
-      if (options) a = { action: 'dropdown', labelId: d?.labelId || c.textId || (c.kind === 'link' ? c.id : null), options };
-      else report.invalidDropdowns.push({ state: s.stateId, id: c.id, options: l?.options || [] });
+      // dropdown with missing choices.
     }
     else if (l?.action === 'modal') a = { action: 'modal', modal: l.modal || { title: c.text, body: '', confirm: 'OK' } };
     else if (l?.action === 'navigate' || d?.action === 'navigate') {
@@ -269,7 +283,6 @@ for (const u of units) {
         unit: u,
         canonicalShell: model.canonicalShell,
         navRows,
-        rulesFor,
         styleText,
       })
     : { extraCss: [], bands: [], decisions: [], changes: 0 };
@@ -308,6 +321,13 @@ for (const u of units) {
       report.counts[a.action]++;
       allActions[id] = a;
     }
+    for (const demotion of report.actionDemotions.filter((candidate) => candidate.state === s.stateId)) {
+      const el = document.getElementById(demotion.id);
+      if (!el) continue;
+      el.removeAttribute('data-proto-action');
+      el.removeAttribute('data-proto-options');
+      el.setAttribute('data-proto-demoted', demotion.code);
+    }
     // fields
     for (const f of s.fields) {
       if (acts.has(f.id)) continue;
@@ -334,8 +354,14 @@ for (const u of units) {
   // after every transplant so shared dropdowns/utilities behave on every page.
   const unitRegions = new Set(u.states.flatMap((state) => state.shell.map((item) => item.region)));
   for (const region of unitRegions) for (const [id, action] of canonicalShellActions[region] || []) {
-    const elements = [...document.querySelectorAll('[id]')].filter((element) => element.id === id);
-    for (const element of elements) bindAction(element, action);
+    const elements = shellElementsForSourceId(document, id);
+    for (const element of elements) {
+      const scope = element.closest('.ly-band[data-ly-band]') || document;
+      const labelId = action.labelId
+        ? shellElementsForSourceId(scope, action.labelId)[0]?.id || action.labelId
+        : null;
+      bindAction(element, labelId ? { ...action, labelId } : action);
+    }
     if (elements.length && !allActions[id]) {
       allActions[id] = action;
       report.shellActionRemaps++;
@@ -343,13 +369,15 @@ for (const u of units) {
   }
   // nav wiring on the (now shared) canonical shell ids — present wherever a shell was transplanted or is native
   for (const n of navRows) {
-    const el = document.getElementById(n.rowId) || document.getElementById(n.id);
-    if (!el) continue;
-    const tgt = n.target ? (unitOf(n.target)?.id === u.id ? null : fileOf(n.target)) : holdingFile(n.text);
-    if (!tgt) { el.removeAttribute('data-proto-action'); continue; }
-    el.setAttribute('data-proto-action', 'navigate'); el.setAttribute('data-proto-target', tgt);
-    for (const d of el.querySelectorAll('[data-proto-action]')) { d.removeAttribute('data-proto-action'); d.removeAttribute('data-proto-target'); delete allActions[d.id]; }
-    allActions[n.rowId] = { action: 'navigate', target: tgt, nav: true };
+    const elements = shellElementsForSourceId(document, n.rowId);
+    const targets = elements.length > 0 ? elements : shellElementsForSourceId(document, n.id);
+    for (const el of targets) {
+      const tgt = n.target ? (unitOf(n.target)?.id === u.id ? null : fileOf(n.target)) : holdingFile(n.text);
+      if (!tgt) { el.removeAttribute('data-proto-action'); continue; }
+      el.setAttribute('data-proto-action', 'navigate'); el.setAttribute('data-proto-target', tgt);
+      for (const d of el.querySelectorAll('[data-proto-action]')) { d.removeAttribute('data-proto-action'); d.removeAttribute('data-proto-target'); delete allActions[d.id]; }
+      allActions[n.rowId] = { action: 'navigate', target: tgt, nav: true };
+    }
   }
   // active nav highlight: move the pill style from the canonical active item to this unit's item
   for (const [region, p] of Object.entries(pills)) {
@@ -358,7 +386,7 @@ for (const u of units) {
       // no nav item maps to this page: show no active item rather than the canonical page's
       const anyRow = u.states.some((s) => s.shell.some((x) => x.region === region));
       if (anyRow && p.pill) { const inactive = navRows.find((n) => n.region === region && n.id !== p.own.id); const inText = inactive && shell[region].section.items.find((x) => x.id === inactive.id);
-        extraCss.push(`#${p.pill.id}{background:transparent!important;box-shadow:none!important}`); if (inText) extraCss.push(`#${p.own.id}{color:${inText.color}!important;font-weight:${inText.fontWeight}!important}`); }
+        extraCss.push(`${shellSelectorForSourceId(document, p.pill.id)}{background:transparent!important;box-shadow:none!important}`); if (inText) extraCss.push(`${shellSelectorForSourceId(document, p.own.id)}{color:${inText.color}!important;font-weight:${inText.fontWeight}!important}`); }
       continue;
     }
     if (activeNav.id === p.own.id) continue;
@@ -366,15 +394,15 @@ for (const u of units) {
     const curText = shell[region].section.items.find((x) => x.id === cur.id);
     const ownText = shell[region].section.items.find((x) => x.id === p.own.id);
     if (p.pill) {
-      extraCss.push(`#${p.pill.id}{background:transparent!important;box-shadow:none!important}`);
-      if (cur.row) extraCss.push(`#${cur.row.id}{background:${p.pill.bg}!important;border-radius:${p.pill.radius}!important}`);
+      extraCss.push(`${shellSelectorForSourceId(document, p.pill.id)}{background:transparent!important;box-shadow:none!important}`);
+      if (cur.row) extraCss.push(`${shellSelectorForSourceId(document, cur.row.id)}{background:${p.pill.bg}!important;border-radius:${p.pill.radius}!important}`);
     }
-    extraCss.push(`#${cur.id}{color:${p.textColor}!important;font-weight:${p.textWeight}!important}`);
-    extraCss.push(`#${p.own.id}{color:${curText.color}!important;font-weight:${curText.fontWeight}!important}`);
+    extraCss.push(`${shellSelectorForSourceId(document, cur.id)}{color:${p.textColor}!important;font-weight:${p.textWeight}!important}`);
+    extraCss.push(`${shellSelectorForSourceId(document, p.own.id)}{color:${curText.color}!important;font-weight:${curText.fontWeight}!important}`);
     // swap icon colours too (icon = previous sibling of the text inside the row)
     const ownIcon = shell[region].section.items.find((x) => x.cls.includes('icon') && p.own.row && x.chain.includes(p.own.row.id));
     const curIcon = shell[region].section.items.find((x) => x.cls.includes('icon') && cur.row && x.chain.includes(cur.row.id));
-    if (ownIcon && curIcon) { extraCss.push(`#${curIcon.id}{color:${ownIcon.color}!important}`); extraCss.push(`#${ownIcon.id}{color:${curIcon.color}!important}`); }
+    if (ownIcon && curIcon) { extraCss.push(`${shellSelectorForSourceId(document, curIcon.id)}{color:${ownIcon.color}!important}`); extraCss.push(`${shellSelectorForSourceId(document, ownIcon.id)}{color:${curIcon.color}!important}`); }
   }
   // inject runtime
   const head = document.querySelector('head');
@@ -474,7 +502,8 @@ for (const u of units) {
         return {
           ...candidate,
           region,
-          html: element.outerHTML,
+          sourceContainerId: candidate.containerId,
+          sourceElement: element.cloneNode(true),
           css: rulesFor(styleText(donorDocument), candidate.containerId),
           ancestorIds,
         };
@@ -485,18 +514,30 @@ for (const u of units) {
       }
       for (const child of [...host.children]) child.remove();
       const parentShell = (placed) => placedShells.find((candidate) => (
-        candidate !== placed && placed.ancestorIds.includes(candidate.containerId)
+        candidate !== placed && placed.ancestorIds.includes(candidate.sourceContainerId)
       ));
       for (const placed of placedShells.filter((candidate) => !parentShell(candidate))) {
-        host.insertAdjacentHTML('beforeend', placed.html);
+        const subtreeCss = placedShells
+          .filter((candidate) => candidate === placed || candidate.ancestorIds.includes(placed.sourceContainerId))
+          .map((candidate) => candidate.css)
+          .filter(Boolean)
+          .join('\n');
+        const isolated = isolateTransplantedShell({
+          document,
+          sourceElement: placed.sourceElement,
+          css: subtreeCss,
+          namespaceParts: ['holding', key, placed.region],
+        });
+        host.insertAdjacentHTML('beforeend', isolated.html);
+        if (isolated.css) extraCss.push(isolated.css);
       }
       for (const placed of placedShells) {
-        const element = document.getElementById(placed.containerId);
+        const element = shellElementsForSourceId(host, placed.sourceContainerId)[0];
         if (!element || !host.contains(element)) {
-          throw new Error(`Holding composition failed to retain ${placed.region} shell ${placed.containerId} in band ${key}.`);
+          throw new Error(`Holding composition failed to retain ${placed.region} shell ${placed.sourceContainerId} in band ${key}.`);
         }
+        placed.containerId = element.id;
         element.setAttribute(HOLDING_SHELL_ATTRIBUTE, placed.region);
-        if (placed.css) extraCss.push(placed.css);
         const parent = parentShell(placed);
         const box = parent
           ? [placed.box[0] - parent.box[0], placed.box[1] - parent.box[1], placed.box[2], placed.box[3]]
@@ -553,16 +594,18 @@ for (const u of units) {
       const p = pills[navMatch.region];
       if (p && p.own.id !== navMatch.id) {
         const curText = shell[navMatch.region].section.items.find((x) => x.id === navMatch.id);
-        if (p.pill) { extraCss.push(`#${p.pill.id}{background:transparent!important;box-shadow:none!important}`); if (navMatch.row) extraCss.push(`#${navMatch.row.id}{background:${p.pill.bg}!important;border-radius:${p.pill.radius}!important}`); }
-        extraCss.push(`#${navMatch.id}{color:${p.textColor}!important;font-weight:${p.textWeight}!important}`);
-        extraCss.push(`#${p.own.id}{color:${curText.color}!important;font-weight:${curText.fontWeight}!important}`);
+        if (p.pill) { extraCss.push(`${shellSelectorForSourceId(document, p.pill.id)}{background:transparent!important;box-shadow:none!important}`); if (navMatch.row) extraCss.push(`${shellSelectorForSourceId(document, navMatch.row.id)}{background:${p.pill.bg}!important;border-radius:${p.pill.radius}!important}`); }
+        extraCss.push(`${shellSelectorForSourceId(document, navMatch.id)}{color:${p.textColor}!important;font-weight:${p.textWeight}!important}`);
+        extraCss.push(`${shellSelectorForSourceId(document, p.own.id)}{color:${curText.color}!important;font-weight:${curText.fontWeight}!important}`);
       }
     }
     for (const n of navRows) {
-      const el = document.getElementById(n.rowId) || document.getElementById(n.id);
-      if (!el) continue;
-      const tgt = n.holding === hslug ? null : n.target ? fileOf(n.target) : holdingFile(n.text);
-      if (tgt) { el.setAttribute('data-proto-action', 'navigate'); el.setAttribute('data-proto-target', tgt); for (const d of el.querySelectorAll('[data-proto-action]')) d.removeAttribute('data-proto-action'); }
+      const elements = shellElementsForSourceId(document, n.rowId);
+      const targets = elements.length > 0 ? elements : shellElementsForSourceId(document, n.id);
+      for (const el of targets) {
+        const tgt = n.holding === hslug ? null : n.target ? fileOf(n.target) : holdingFile(n.text);
+        if (tgt) { el.setAttribute('data-proto-action', 'navigate'); el.setAttribute('data-proto-target', tgt); for (const d of el.querySelectorAll('[data-proto-action]')) d.removeAttribute('data-proto-action'); }
+      }
     }
     document.title = htitle;
     document.querySelector('head').insertAdjacentHTML('beforeend', `<style id="proto-extra">${extraCss.join('\n')}</style><link rel="stylesheet" href="proto.css">`);
@@ -580,5 +623,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, 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 } : {}), 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/actions.mjs

@@ -17,3 +17,51 @@ export function usableDropdownOptions(options) {
 export function suppressDeterministicAction(label) {
   return label?.action === 'none';
 }
+
+/**
+ * One policy boundary for a dropdown-shaped control. The analyzer may know
+ * that the source looks like a dropdown while the semantic label chooses a
+ * different action or supplies an incomplete option set. Only a proven set of
+ * three distinct options is actionable; every other dropdown-shaped result is
+ * deliberately static and carries a machine-readable degradation fact.
+ */
+export function resolveDropdownAction({ deterministic, label, labelId }) {
+  if (suppressDeterministicAction(label)) {
+    return deterministic?.action === 'dropdown'
+      ? {
+          disposition: 'static',
+          degradation: {
+            code: 'label_none_overrode_deterministic_dropdown',
+            reason: 'explicit-label-none',
+            fromAction: 'dropdown',
+            toAction: 'none',
+            options: [],
+          },
+        }
+      : { disposition: 'suppressed' };
+  }
+  if (deterministic?.action !== 'dropdown' && label?.action !== 'dropdown') {
+    return { disposition: 'not-dropdown' };
+  }
+  const options = usableDropdownOptions(label?.options);
+  if (!options) {
+    return {
+      disposition: 'static',
+      degradation: {
+        code: 'dropdown_options_incomplete',
+        reason: 'fewer-than-three-distinct-options',
+        fromAction: label?.action || deterministic?.action || 'dropdown',
+        toAction: 'none',
+        options: Array.isArray(label?.options) ? label.options : [],
+      },
+    };
+  }
+  return {
+    disposition: 'dropdown',
+    action: {
+      action: 'dropdown',
+      labelId,
+      options,
+    },
+  };
+}

package/prototype-kit/lib/shell-identity.mjs

@@ -0,0 +1,139 @@
+const SOURCE_ID_ATTRIBUTE = 'data-proto-shell-source-id';
+const ID_REFERENCE_ATTRIBUTES = new Set([
+  'aria-activedescendant',
+  'aria-controls',
+  'aria-describedby',
+  'aria-details',
+  'aria-errormessage',
+  'aria-flowto',
+  'aria-labelledby',
+  'aria-owns',
+  'commandfor',
+  'data-proto-field',
+  'data-proto-label',
+  'data-proto-submit-for',
+  'for',
+  'form',
+  'headers',
+  'list',
+  'popovertarget',
+]);
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function safeIdentityPart(value) {
+  return String(value).toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '') || 'shell';
+}
+
+function rewriteHashIds(value, identities) {
+  let rewritten = value;
+  for (const [sourceId, physicalId] of [...identities].sort(([left], [right]) => right.length - left.length)) {
+    rewritten = rewritten.replace(
+      new RegExp(`#${escapeRegex(sourceId)}(?=[^A-Za-z0-9_-]|$)`, 'g'),
+      `#${physicalId}`,
+    );
+  }
+  return rewritten;
+}
+
+function rewriteIdentityReferences(root, identities) {
+  for (const element of [root, ...root.querySelectorAll('*')]) for (const attribute of [...element.attributes]) {
+    let value = attribute.value;
+    if (ID_REFERENCE_ATTRIBUTES.has(attribute.name)) {
+      value = value.split(/(\s+)/).map((token) => identities.get(token) || token).join('');
+    }
+    value = rewriteHashIds(value, identities);
+    if (attribute.name === 'begin' || attribute.name === 'end') {
+      for (const [sourceId, physicalId] of identities) {
+        value = value.replace(
+          new RegExp(`(^|;)${escapeRegex(sourceId)}(?=\\.)`, 'g'),
+          `$1${physicalId}`,
+        );
+      }
+    }
+    if (value !== attribute.value) element.setAttribute(attribute.name, value);
+  }
+}
+
+function unusedNamespace(document, parts) {
+  const existing = [...document.querySelectorAll('[id]')].map((element) => element.id);
+  const base = `proto-shell-${parts.map(safeIdentityPart).join('-')}`;
+  let namespace = base;
+  let suffix = 2;
+  while (existing.some((id) => id === namespace || id.startsWith(`${namespace}-`))) {
+    namespace = `${base}-${suffix}`;
+    suffix++;
+  }
+  return namespace;
+}
+
+function isolatedElements(root, sourceId) {
+  const elements = [];
+  if (root.nodeType === 1 && root.getAttribute(SOURCE_ID_ATTRIBUTE) === sourceId) elements.push(root);
+  for (const element of root.querySelectorAll(`[${SOURCE_ID_ATTRIBUTE}]`)) {
+    if (element.getAttribute(SOURCE_ID_ATTRIBUTE) === sourceId) elements.push(element);
+  }
+  return elements;
+}
+
+function identitiesIn(root) {
+  return new Map(
+    [root, ...root.querySelectorAll(`[${SOURCE_ID_ATTRIBUTE}]`)]
+      .filter((element) => element.getAttribute(SOURCE_ID_ATTRIBUTE))
+      .map((element) => [element.getAttribute(SOURCE_ID_ATTRIBUTE), element.id]),
+  );
+}
+
+/** Clone foreign shell DOM under opaque physical ids and rewrite every internal reference and donor selector. */
+export function isolateTransplantedShell({ document, sourceElement, css, namespaceParts }) {
+  const clone = sourceElement.cloneNode(true);
+  const identityNodes = [clone, ...clone.querySelectorAll('[id]')].filter((element) => element.id);
+  const identities = new Map();
+  const namespace = unusedNamespace(document, namespaceParts);
+  for (const [index, element] of identityNodes.entries()) {
+    if (identities.has(element.id)) {
+      throw new Error(`Canonical shell isolation found duplicate donor id ${element.id}.`);
+    }
+    identities.set(element.id, `${namespace}-${index + 1}`);
+  }
+  rewriteIdentityReferences(clone, identities);
+  for (const element of identityNodes) {
+    const sourceId = element.id;
+    element.id = identities.get(sourceId);
+    element.setAttribute(SOURCE_ID_ATTRIBUTE, sourceId);
+  }
+  return {
+    css: rewriteHashIds(css, identities),
+    html: clone.outerHTML,
+    identities,
+    rootId: identities.get(sourceElement.id),
+  };
+}
+
+/** Resolve a logical donor id to the physical nodes emitted for this document or subtree. */
+export function shellElementsForSourceId(root, sourceId) {
+  const isolated = isolatedElements(root, sourceId);
+  if (isolated.length > 0) return isolated;
+  const document = root.nodeType === 9 ? root : root.ownerDocument;
+  const original = document?.getElementById(sourceId) || null;
+  return original && (root.nodeType === 9 || root === original || root.contains(original)) ? [original] : [];
+}
+
+/** Build a CSS selector that follows a logical donor identity through shell isolation. */
+export function shellSelectorForSourceId(document, sourceId) {
+  const elements = shellElementsForSourceId(document, sourceId);
+  return (elements.length > 0 ? elements.map((element) => `#${element.id}`) : [`#${sourceId}`]).join(',');
+}
+
+/** Rewrite an additional donor rule set for a shell that was already isolated as part of an ancestor. */
+export function cssForIsolatedShell(root, css) {
+  return rewriteHashIds(css, identitiesIn(root));
+}
+
+export function rulesFor(css, id) {
+  // One selector per rule in these exports; retain rules owned by this shell id family.
+  const re = new RegExp(`#${escapeRegex(id)}(?:-[A-Za-z0-9_-]*)?(?:[:>\\s][^{]*)?\\{[^}]*\\}`, 'g');
+  return (css.match(re) || []).join('\n');
+}

package/prototype-kit/lib/shell-stitching.mjs

@@ -1,5 +1,11 @@
 import { declaredActiveMarkers, linkedNavForUnit } from './nav-active-state.mjs';
 import { needsCanonicalShell, shellForBand } from './shell-consistency.mjs';
+import {
+  cssForIsolatedShell,
+  isolateTransplantedShell,
+  rulesFor,
+  shellElementsForSourceId,
+} from './shell-identity.mjs';
 import { shouldTransplantShell } from './shells.mjs';
 import { normalizeText } from './text.mjs';
 
@@ -26,6 +32,7 @@ function markerSnapshots({ document, shell, markers, rulesFor, styleText }) {
     if (!element) return [];
     return [{
       ...marker,
+      element: element.cloneNode(true),
       html: element.outerHTML,
       css: rulesFor(css, marker.id),
       item: shell.items.find((item) => item.id === marker.id),
@@ -34,20 +41,28 @@ function markerSnapshots({ document, shell, markers, rulesFor, styleText }) {
   });
 }
 
-function removeMarkers(document, markers) {
-  for (const marker of markers) document.getElementById(marker.id)?.remove();
+function removeMarkers(shellElement, markers) {
+  for (const marker of markers) shellElementsForSourceId(shellElement, marker.id)[0]?.remove();
 }
 
-function placeMarker({ shellElement, shell, marker, targetItem, extraCss }) {
-  shellElement.insertAdjacentHTML('beforeend', marker.html);
-  if (marker.css) extraCss.push(marker.css);
+function placeMarker({ document, shellElement, shell, marker, targetItem, extraCss, namespaceParts }) {
+  const isolated = isolateTransplantedShell({
+    document,
+    sourceElement: marker.element,
+    css: marker.css,
+    namespaceParts,
+  });
+  shellElement.insertAdjacentHTML('beforeend', isolated.html);
+  if (isolated.css) extraCss.push(isolated.css);
+  const outputMarker = { ...marker, id: isolated.identities.get(marker.id) };
   const sourceTarget = marker.targetItem;
   const source = marker.item;
-  if (!source) return;
+  if (!source) return outputMarker;
   const desiredX = targetItem && sourceTarget ? targetItem.x + (source.x - sourceTarget.x) : source.x;
   const desiredY = targetItem && sourceTarget ? targetItem.y + (source.y - sourceTarget.y) : source.y;
-  extraCss.push(`#${marker.id}{position:absolute!important;left:${desiredX - shell.box[0]}px!important;top:${desiredY - shell.box[1]}px!important;`
+  extraCss.push(`#${outputMarker.id}{position:absolute!important;left:${desiredX - shell.box[0]}px!important;top:${desiredY - shell.box[1]}px!important;`
     + `width:${source.w}px!important;height:${source.h}px!important;margin:0!important;translate:none!important}`);
+  return outputMarker;
 }
 
 function decisionForRegion({ unit, donorPage, recipientPage, region, canonicalShell }) {
@@ -83,7 +98,6 @@ export function stitchUnitShells({
   unit,
   canonicalShell,
   navRows,
-  rulesFor,
   styleText,
 }) {
   const extraCss = [];
@@ -142,31 +156,39 @@ export function stitchUnitShells({
         const donorElement = donorDocument.getElementById(pair.canonical.containerId);
         const root = bandRoot(document, pair.key);
         const host = shellHost(root);
-        const alreadyPlaced = document.getElementById(pair.canonical.containerId);
+        const alreadyPlaced = root && shellElementsForSourceId(root, pair.canonical.containerId)[0];
         if (!donorElement || !root || !host || (!root.contains(recipientElement) && !root.contains(alreadyPlaced))) {
           throw new Error(`Canonical shell commit lost declared ${region} DOM in band ${pair.key}.`);
         }
+        const donorAlreadyIsolated = alreadyPlaced && alreadyPlaced.id !== pair.canonical.containerId;
+        let outputShell = donorAlreadyIsolated ? alreadyPlaced : null;
         if (recipientElement && root.contains(recipientElement)) {
-          const recipientId = recipientElement.id;
-          recipientElement.insertAdjacentHTML('beforebegin', donorElement.outerHTML);
-          recipientElement.replaceChildren();
-          if (recipientId === pair.canonical.containerId) {
-            const placeholderId = `${recipientId}-proto-shell-space`;
-            const placeholderCss = rulesFor(styleText(document), recipientId)
-              .replaceAll(`#${recipientId}`, `#${placeholderId}`);
-            recipientElement.id = placeholderId;
-            if (placeholderCss) extraCss.push(placeholderCss);
+          if (!donorAlreadyIsolated) {
+            const isolated = isolateTransplantedShell({
+              document,
+              sourceElement: donorElement,
+              css: rulesFor(styleText(donorDocument), pair.canonical.containerId),
+              namespaceParts: [pair.key, region],
+            });
+            recipientElement.insertAdjacentHTML('beforebegin', isolated.html);
+            outputShell = document.getElementById(isolated.rootId);
+            if (isolated.css) extraCss.push(isolated.css);
           }
+          recipientElement.replaceChildren();
           recipientElement.setAttribute('data-proto-shell-space', region);
           recipientElement.setAttribute('aria-hidden', 'true');
           extraCss.push(`#${recipientElement.id}{visibility:hidden!important;pointer-events:none!important}`);
         }
-        outputShellId = pair.canonical.containerId;
-        const outputShell = document.getElementById(outputShellId);
+        outputShellId = outputShell?.id || null;
         if (!outputShell || !root.contains(outputShell)) {
           throw new Error(`Canonical shell commit did not place ${region} in band ${pair.key}.`);
         }
-        extraCss.push(rulesFor(styleText(donorDocument), pair.canonical.containerId));
+        if (outputShell === alreadyPlaced) {
+          extraCss.push(cssForIsolatedShell(
+            outputShell,
+            rulesFor(styleText(donorDocument), pair.canonical.containerId),
+          ));
+        }
         const donorBand = donorPage.bands.find((band) => band.key === pair.key);
         const parentShell = donorBand?.shells.find((candidate) => {
           if (candidate.containerId === pair.canonical.containerId) return false;
@@ -180,21 +202,36 @@ export function stitchUnitShells({
               pair.canonical.box[1] - parentShell.box[1],
             ]
           : pair.canonical.box;
-        extraCss.push(`#${pair.canonical.containerId}{position:absolute!important;left:${x}px!important;top:${y}px!important;`
+        extraCss.push(`#${outputShellId}{position:absolute!important;left:${x}px!important;top:${y}px!important;`
           + 'margin:0!important;z-index:100000!important}');
-        removeMarkers(document, canonicalMarkers);
+        removeMarkers(outputShell, canonicalMarkers);
         const matchingSource = linkedNav
           ? sourceSnapshots.find((marker) => normalizeText(marker.targetText) === normalizeText(linkedNav.text))
           : null;
         const markerToPlace = matchingSource || (linkedNav ? donorSnapshots[0] : null);
         if (markerToPlace) {
-          placeMarker({ shellElement: outputShell, shell: pair.canonical, marker: markerToPlace, targetItem, extraCss });
-          outputMarkers = [{ ...markerToPlace, id: markerToPlace.id }];
+          outputMarkers = [placeMarker({
+            document,
+            shellElement: outputShell,
+            shell: pair.canonical,
+            marker: markerToPlace,
+            targetItem,
+            extraCss,
+            namespaceParts: [pair.key, region, 'marker'],
+          })];
         } else if (!linkedNav) {
+          outputMarkers = [];
           for (const marker of sourceSnapshots) {
-            placeMarker({ shellElement: outputShell, shell: pair.canonical, marker, targetItem: null, extraCss });
+            outputMarkers.push(placeMarker({
+              document,
+              shellElement: outputShell,
+              shell: pair.canonical,
+              marker,
+              targetItem: null,
+              extraCss,
+              namespaceParts: [pair.key, region, 'marker'],
+            }));
           }
-          outputMarkers = sourceSnapshots;
         } else outputMarkers = [];
         changes++;
       }
@@ -203,6 +240,10 @@ export function stitchUnitShells({
           || outputMarkers[0]
           || null
         : null;
+      const outputShell = document.getElementById(outputShellId);
+      const outputNavId = targetItem
+        ? shellElementsForSourceId(outputShell || document, targetItem.id)[0]?.id || targetItem.id
+        : null;
       bands.get(pair.key)?.regions.push({
         region,
         shellId: outputShellId,
@@ -210,8 +251,8 @@ export function stitchUnitShells({
         consistencyStatus: decision.commit || decision.reason === 'canonical-page' ? 'canonical' : 'silent',
         activeMarkerIds: outputMarkers.map((marker) => marker.id),
         active: linkedNav && targetItem && activeMarker
-          ? { status: 'linked', navText: linkedNav.text, navId: targetItem.id, markerId: activeMarker.id }
-          : linkedNav ? { status: 'unproven', navText: linkedNav.text, navId: targetItem?.id || null, markerId: null }
+          ? { status: 'linked', navText: linkedNav.text, navId: outputNavId, markerId: activeMarker.id }
+          : linkedNav ? { status: 'unproven', navText: linkedNav.text, navId: outputNavId, markerId: null }
             : { status: 'silent', navText: null, navId: null, markerId: null },
         changed: decision.commit,
       });