@12ui/design 0.2.36 → 0.2.38

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

@@ -5,6 +5,19 @@ function errorText(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+function configuredWidths(protoDir, file) {
+  const html = fs.readFileSync(path.join(protoDir, file), 'utf8');
+  const state = html.match(/<script id="proto-state" type="application\/json">([\s\S]*?)<\/script>/)?.[1];
+  if (!state) return [1536, 390];
+  try {
+    const cfg = JSON.parse(state);
+    return [...new Set([1536, 390, ...(cfg.holdingBands || []).map((band) => band.viewportWidth)])]
+      .filter((width) => Number.isFinite(width) && width > 0);
+  } catch {
+    return [1536, 390];
+  }
+}
+
 async function smokeInteraction(page, selector, assertion) {
   const locator = page.locator(selector).first();
   if (!await locator.count()) return { present: false, ok: true };
@@ -72,48 +85,365 @@ async function checkDeepLinkBack(browser, url, pageFile) {
 }
 
 export async function checkRuntime({ browser, baseUrl, relativeProtoPath, protoDir }) {
+  const manifestFile = path.join(protoDir, 'proto-manifest.json');
+  const manifest = fs.existsSync(manifestFile)
+    ? JSON.parse(fs.readFileSync(manifestFile, 'utf8'))
+    : { units: [] };
+  const unitByFile = new Map((manifest.units || []).map((unit) => [`${unit.id}.html`, unit]));
   const htmlFiles = fs.readdirSync(protoDir).filter((name) => name.endsWith('.html') && name !== 'index.html').sort();
   const pages = [];
   const brokenTargets = [];
   let deepLinkFile = null;
   for (const file of htmlFiles) {
-    const pageErrors = [];
-    const consoleErrors = [];
-    const page = await browser.newPage({ viewport: { width: 1536, height: 1024 } });
-    page.on('pageerror', (error) => pageErrors.push(error.message));
-    page.on('console', (message) => { if (message.type() === 'error') consoleErrors.push(message.text()); });
     const url = `${baseUrl}/${relativeProtoPath}/${encodeURIComponent(file)}`;
-    try {
-      await page.goto(url, { waitUntil: 'networkidle', timeout: 15_000 });
-      const boundRaw = await page.evaluate(() => document.documentElement.dataset.protoBound || null);
-      const bound = boundRaw ? JSON.parse(boundRaw) : null;
-      const duplicateIds = await page.locator('[id]').evaluateAll((nodes) => {
-        const counts = new Map();
-        for (const node of nodes) counts.set(node.id, (counts.get(node.id) || 0) + 1);
-        return [...counts].filter(([, count]) => count > 1).map(([id, count]) => ({ id, count }));
-      });
-      const targets = await page.locator('[data-proto-action="navigate"]').evaluateAll((nodes) => nodes.map((node) => node.getAttribute('data-proto-target')));
-      for (const target of targets.filter(Boolean)) {
-        const [targetFile, hash] = target.split('#');
-        if (!deepLinkFile && targetFile === file && hash) deepLinkFile = file;
-        const targetPath = path.join(protoDir, targetFile);
-        if (!fs.existsSync(targetPath)) brokenTargets.push({ page: file, target, reason: 'missing file' });
-        else if (hash && !fs.readFileSync(targetPath, 'utf8').includes(`id="${hash}"`)) brokenTargets.push({ page: file, target, reason: 'missing anchor' });
+    const viewports = [];
+    let bound = null;
+    let duplicateIds = [];
+    let dropdown = { present: false, ok: true };
+    let modal = { present: false, ok: true };
+    const expectedUnit = unitByFile.get(file) || null;
+    for (const width of configuredWidths(protoDir, file)) {
+      const pageErrors = [];
+      const consoleErrors = [];
+      const page = await browser.newPage({ viewport: { width, height: 1024 } });
+      page.on('pageerror', (error) => pageErrors.push(error.message));
+      page.on('console', (message) => { if (message.type() === 'error') consoleErrors.push(message.text()); });
+      try {
+        await page.goto(url, { waitUntil: 'networkidle', timeout: 15_000 });
+        await page.evaluate(() => document.fonts.ready);
+        const boundRaw = await page.evaluate(() => document.documentElement.dataset.protoBound || null);
+        if (width === 1536) bound = boundRaw ? JSON.parse(boundRaw) : null;
+        const composition = await page.evaluate(() => {
+          const state = document.getElementById('proto-state');
+          const cfg = state ? JSON.parse(state.textContent || '{}') : {};
+          if (!cfg.holding) return { holding: false, ok: true };
+          const roots = [...document.querySelectorAll('.ly-band[data-ly-band]')];
+          const active = roots.length > 0
+            ? roots.filter((root) => {
+                const box = root.getBoundingClientRect();
+                return getComputedStyle(root).display !== 'none' && box.width > 0 && box.height > 0;
+              })
+            : [document.body];
+          const activeRoot = active.length === 1 ? active[0] : null;
+          const activeKey = roots.length === 0 ? 'native' : activeRoot?.getAttribute('data-ly-band') || null;
+          const declared = (cfg.holdingBands || []).find((band) => band.key === activeKey) || null;
+          const surfaces = activeRoot ? [...activeRoot.querySelectorAll('[data-proto-holding-surface="true"]')] : [];
+          const surface = surfaces.length === 1 ? surfaces[0] : null;
+          const screen = activeRoot?.querySelector('.generated-screen') || (activeRoot === document.body ? document.body : null);
+          const emittedGroundRegistration = screen?.getAttribute('data-ly-ground-registration') || null;
+          const declaredGroundRegistration = declared?.groundRegistration || null;
+          const groundRegistrationMismatch = !!declared
+            && emittedGroundRegistration !== declaredGroundRegistration;
+          const shellIntersections = [];
+          const shellGeometryMismatches = [];
+          let hostGeometryMismatch = null;
+          if (activeRoot && surface && declared) {
+            const holdingBox = surface.getBoundingClientRect();
+            const host = activeRoot.querySelector(`[data-proto-holding-band="${CSS.escape(activeKey)}"]`);
+            const hostBox = host?.getBoundingClientRect() || null;
+            const screenBox = screen?.getBoundingClientRect() || null;
+            const hostZoom = host ? parseFloat(getComputedStyle(host).zoom) || 1 : 1;
+            const hasDeclaredHostOrigins = Array.isArray(declared.hostOrigins);
+            const hostOrigin = (declared.hostOrigins || [])
+              .find((sample) => sample.viewportWidth === window.innerWidth)?.origin || null;
+            if (hasDeclaredHostOrigins && !hostOrigin) {
+              hostGeometryMismatch = { reason: `missing-declared-origin-at-${window.innerWidth}` };
+            }
+            if (hostBox && screenBox && hostOrigin) {
+              const [hostLeft, hostTop] = hostOrigin;
+              const deltas = {
+                left: Math.abs(hostBox.left - (screenBox.left + hostLeft * hostZoom)),
+                top: Math.abs(hostBox.top - (screenBox.top + hostTop * hostZoom)),
+              };
+              if (Object.values(deltas).some((delta) => delta > 1)) hostGeometryMismatch = { deltas };
+            }
+            const declaredBoxes = new Map((declared.shellBoxes || []).map((entry) => [entry.id, entry.box]));
+            for (const id of declared.shellIds || []) {
+              const shell = document.getElementById(id);
+              if (!shell || !activeRoot.contains(shell)) {
+                shellIntersections.push({ shellId: id, reason: 'missing-declared-shell' });
+                continue;
+              }
+              const shellBox = shell.getBoundingClientRect();
+              const expected = declaredBoxes.get(id);
+              if (expected && screenBox && hostOrigin) {
+                const [x, y, width, height] = expected;
+                const [hostLeft, hostTop] = hostOrigin;
+                const deltas = {
+                  left: Math.abs(shellBox.left - (screenBox.left + (hostLeft + x) * hostZoom)),
+                  top: Math.abs(shellBox.top - (screenBox.top + (hostTop + y) * hostZoom)),
+                  width: Math.abs(shellBox.width - width * hostZoom),
+                  height: Math.abs(shellBox.height - height * hostZoom),
+                };
+                if (Object.values(deltas).some((delta) => delta > 1)) {
+                  shellGeometryMismatches.push({ shellId: id, deltas });
+                }
+              }
+              const overlapWidth = Math.min(holdingBox.right, shellBox.right) - Math.max(holdingBox.left, shellBox.left);
+              const overlapHeight = Math.min(holdingBox.bottom, shellBox.bottom) - Math.max(holdingBox.top, shellBox.top);
+              if (overlapWidth > 0.5 && overlapHeight > 0.5) {
+                shellIntersections.push({ shellId: id, overlapWidth, overlapHeight });
+              }
+            }
+          }
+          let donorGroundActive = false;
+          let donorGround = null;
+          if (activeRoot && declared?.groundRegistration === 'positioned-scene') {
+            if (!screen) donorGroundActive = true;
+            else {
+              const style = getComputedStyle(screen);
+              const before = getComputedStyle(screen, '::before');
+              const after = getComputedStyle(screen, '::after');
+              const paints = (pseudo) => !['none', 'normal'].includes(pseudo.content)
+                && pseudo.display !== 'none';
+              donorGroundActive = style.backgroundImage !== 'none' || paints(before) || paints(after);
+              donorGround = {
+                backgroundImage: style.backgroundImage === 'none' ? 'none' : 'painted',
+                before: before.content,
+                after: after.content,
+              };
+            }
+          }
+          const parseRgb = (value) => {
+            const match = String(value).match(/rgba?\((\d+(?:\.\d+)?)[, ]+(\d+(?:\.\d+)?)[, ]+(\d+(?:\.\d+)?)/);
+            return match ? match.slice(1, 4).map(Number) : null;
+          };
+          const luminance = (value) => {
+            const channels = parseRgb(value);
+            if (!channels) return null;
+            const linear = channels.map((channel) => {
+              const normalized = channel / 255;
+              return normalized <= 0.04045 ? normalized / 12.92 : ((normalized + 0.055) / 1.055) ** 2.4;
+            });
+            return linear[0] * 0.2126 + linear[1] * 0.7152 + linear[2] * 0.0722;
+          };
+          const contrast = (foreground, background) => {
+            const left = luminance(foreground);
+            const right = luminance(background);
+            if (left === null || right === null) return 0;
+            return (Math.max(left, right) + 0.05) / (Math.min(left, right) + 0.05);
+          };
+          const surfaceColor = screen ? getComputedStyle(screen).backgroundColor : null;
+          const title = surface?.querySelector('.proto-holding-title');
+          const body = surface?.querySelector('.proto-holding-sub');
+          const contrastRatios = {
+            title: title && surfaceColor ? contrast(getComputedStyle(title).color, surfaceColor) : 0,
+            body: body && surfaceColor ? contrast(getComputedStyle(body).color, surfaceColor) : 0,
+          };
+          const holdingContrastFailure = declared?.groundRegistration === 'positioned-scene' && !!surface
+            && (contrastRatios.title < 4.5 || contrastRatios.body < 4.5);
+          const failures = [];
+          if (active.length !== 1) failures.push('active-band-count');
+          if (!declared) failures.push('undeclared-active-band');
+          if (surfaces.length !== 1) failures.push('holding-surface-count');
+          if (shellIntersections.length > 0) failures.push('shell-intersection');
+          if (hostGeometryMismatch || shellGeometryMismatches.length > 0) failures.push('shell-geometry-mismatch');
+          if (groundRegistrationMismatch) failures.push('ground-registration-mismatch');
+          if (donorGroundActive) failures.push('donor-ground-active');
+          if (holdingContrastFailure) failures.push('holding-contrast');
+          return {
+            holding: true,
+            ok: failures.length === 0,
+            activeBandCount: active.length,
+            activeBand: activeKey,
+            holdingSurfaceCount: surfaces.length,
+            shellIntersections,
+            shellGeometryMismatches,
+            hostGeometryMismatch,
+            emittedGroundRegistration,
+            declaredGroundRegistration,
+            groundRegistrationMismatch,
+            donorGroundActive,
+            donorGround,
+            contrastRatios,
+            failures,
+          };
+        });
+        const shellState = await page.evaluate(async (expected) => {
+          if (!expected?.shellBands?.length) return { applicable: false, ok: true, failures: [] };
+          const roots = [...document.querySelectorAll('.ly-band[data-ly-band]')];
+          const visibleRoots = roots.length > 0
+            ? roots.filter((root) => {
+                const box = root.getBoundingClientRect();
+                return getComputedStyle(root).display !== 'none' && box.width > 0 && box.height > 0;
+              })
+            : [document.body];
+          const activeRoot = visibleRoots.length === 1 ? visibleRoots[0] : null;
+          const activeBand = roots.length === 0 ? 'native' : activeRoot?.getAttribute('data-ly-band') || null;
+          const declared = expected.shellBands.find((band) => band.key === activeBand) || null;
+          const failures = [];
+          const regions = [];
+          if (!activeRoot || !declared) {
+            failures.push({ kind: 'shell-consistency', reason: !activeRoot ? 'active-band-count' : 'undeclared-active-band' });
+            return { applicable: true, ok: false, activeBand, failures, regions };
+          }
+          const screen = activeRoot.querySelector('.generated-screen') || (activeRoot === document.body ? activeRoot : null);
+          const host = screen?.querySelector('.ly-anchor-canvas') || screen;
+          const hostZoom = host ? parseFloat(getComputedStyle(host).zoom) || 1 : 1;
+          const round = (value) => Math.round(value * 10) / 10;
+          const visualSignature = async (shell, declaration) => {
+            const rootBox = shell.getBoundingClientRect();
+            const markerIds = new Set(declaration.activeMarkerIds || []);
+            const visualNodes = [shell, ...shell.querySelectorAll('*')]
+              .filter((node) => {
+                for (const id of markerIds) if (node.id === id || node.closest(`#${CSS.escape(id)}`)) return false;
+                return true;
+              })
+              .map((node) => {
+                const box = node.getBoundingClientRect();
+                const style = getComputedStyle(node);
+                return {
+                  tag: node.tagName.toLowerCase(),
+                  cls: typeof node.className === 'string'
+                    ? node.className.split(/\s+/).filter((name) => name && !name.startsWith('proto-')).join(' ')
+                    : '',
+                  text: node.children.length === 0 ? (node.textContent || '').replace(/\s+/g, ' ').trim() : '',
+                  label: node.getAttribute('alt') || node.getAttribute('aria-label') || '',
+                  source: node.getAttribute('src') || '',
+                  box: [
+                    round((box.left - rootBox.left) / hostZoom),
+                    round((box.top - rootBox.top) / hostZoom),
+                    round(box.width / hostZoom),
+                    round(box.height / hostZoom),
+                  ],
+                  style: [
+                    style.display, node === shell ? 'shell-root' : style.position,
+                    style.fontFamily, style.fontSize, style.lineHeight,
+                    style.borderTopWidth, style.borderRadius,
+                    style.opacity, style.objectFit,
+                  ],
+                };
+              }).filter((node) => node.box[2] > 0 && node.box[3] > 0);
+            const bytes = new TextEncoder().encode(JSON.stringify({ region: declaration.region, visualNodes }));
+            const digest = await crypto.subtle.digest('SHA-256', bytes);
+            return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+          };
+          for (const declaration of declared.regions || []) {
+            const shell = document.getElementById(declaration.shellId);
+            if (!shell || !activeRoot.contains(shell)) {
+              failures.push({ kind: 'shell-consistency', region: declaration.region, reason: 'missing-declared-shell' });
+              continue;
+            }
+            const actualSignature = await visualSignature(shell, declaration);
+            const shellBox = shell.getBoundingClientRect();
+            const hostBox = host?.getBoundingClientRect() || { left: 0, top: 0 };
+            const actualGeometry = [
+              round((shellBox.left - hostBox.left) / hostZoom),
+              round((shellBox.top - hostBox.top) / hostZoom),
+              round(shellBox.width / hostZoom),
+              round(shellBox.height / hostZoom),
+            ];
+            let activeMatches = true;
+            if (declaration.active?.status === 'linked') {
+              const marker = document.getElementById(declaration.active.markerId);
+              const nav = document.getElementById(declaration.active.navId);
+              if (!marker || !nav || !shell.contains(marker) || !shell.contains(nav)) activeMatches = false;
+              else {
+                const markerBox = marker.getBoundingClientRect();
+                const navBox = nav.getBoundingClientRect();
+                const overlap = Math.min(markerBox.right, navBox.right) - Math.max(markerBox.left, navBox.left);
+                const overlapRatio = overlap / Math.max(1, Math.min(markerBox.width, navBox.width));
+                activeMatches = overlapRatio >= 0.7
+                  && markerBox.top >= navBox.bottom - 2
+                  && markerBox.top - navBox.bottom <= 32;
+              }
+              if (!activeMatches) failures.push({
+                kind: 'active-navigation',
+                region: declaration.region,
+                reason: 'marker-target-mismatch',
+                navText: declaration.active.navText,
+                navId: declaration.active.navId,
+                markerId: declaration.active.markerId,
+              });
+            }
+            regions.push({
+              region: declaration.region,
+              shellId: declaration.shellId,
+              actualSignature,
+              actualGeometry,
+              inventorySampleSignature: declaration.canonicalSignature,
+              consistencyStatus: declaration.consistencyStatus || 'canonical',
+              activeStatus: declaration.active?.status || 'silent',
+              activeMatches,
+            });
+          }
+          return { applicable: true, ok: failures.length === 0, activeBand, failures, regions };
+        }, expectedUnit);
+        if (width === 1536) {
+          duplicateIds = await page.locator('[id]').evaluateAll((nodes) => {
+            const counts = new Map();
+            for (const node of nodes) counts.set(node.id, (counts.get(node.id) || 0) + 1);
+            return [...counts].filter(([, count]) => count > 1).map(([id, count]) => ({ id, count }));
+          });
+          const targets = await page.locator('[data-proto-action="navigate"]').evaluateAll((nodes) => nodes.map((node) => node.getAttribute('data-proto-target')));
+          for (const target of targets.filter(Boolean)) {
+            const [targetFile, hash] = target.split('#');
+            if (!deepLinkFile && targetFile === file && hash) deepLinkFile = file;
+            const targetPath = path.join(protoDir, targetFile);
+            if (!fs.existsSync(targetPath)) brokenTargets.push({ page: file, target, reason: 'missing file' });
+            else if (hash && !fs.readFileSync(targetPath, 'utf8').includes(`id="${hash}"`)) brokenTargets.push({ page: file, target, reason: 'missing anchor' });
+          }
+          dropdown = await smokeInteraction(page, '[data-proto-action="dropdown"]', '.proto-menu');
+          modal = await smokeInteraction(page, '[data-proto-action="modal"]', '.proto-modal');
+        }
+        viewports.push({ width, ok: pageErrors.length === 0 && composition.ok && shellState.ok, pageErrors, consoleErrors, composition, shellState });
+      } catch (error) {
+        viewports.push({ width, ok: false, pageErrors, consoleErrors, loadError: errorText(error), composition: null });
+      } finally {
+        await page.close();
       }
-      const dropdown = await smokeInteraction(page, '[data-proto-action="dropdown"]', '.proto-menu');
-      const modal = await smokeInteraction(page, '[data-proto-action="modal"]', '.proto-modal');
-      pages.push({ file, ok: pageErrors.length === 0 && dropdown.ok && modal.ok, bound, duplicateIds, pageErrors, consoleErrors, dropdown, modal });
-    } catch (error) {
-      pages.push({ file, ok: false, bound: null, pageErrors, consoleErrors, loadError: errorText(error) });
-    } finally {
-      await page.close();
     }
+    const pageErrors = viewports.flatMap((viewport) => viewport.pageErrors || []);
+    const consoleErrors = viewports.flatMap((viewport) => viewport.consoleErrors || []);
+    const loadError = viewports.find((viewport) => viewport.loadError)?.loadError;
+    pages.push({
+      file,
+      ok: viewports.every((viewport) => viewport.ok) && dropdown.ok && modal.ok,
+      bound,
+      duplicateIds,
+      pageErrors,
+      consoleErrors,
+      ...(loadError ? { loadError } : {}),
+      dropdown,
+      modal,
+      viewports,
+    });
   }
   let deepLinkBack = { present: false, ok: true };
   if (deepLinkFile) {
     const result = await checkDeepLinkBack(browser, `${baseUrl}/${relativeProtoPath}/${encodeURIComponent(deepLinkFile)}`, deepLinkFile);
     deepLinkBack = { ...result, file: deepLinkFile };
   }
+  const compositionFailures = pages.flatMap((page) => page.viewports.flatMap((viewport) => (
+    viewport.composition?.failures?.map((failure) => ({ file: page.file, width: viewport.width, failure })) || []
+  )));
+  const shellConsistencyFailures = pages.flatMap((page) => page.viewports.flatMap((viewport) => (
+    viewport.shellState?.failures?.filter((failure) => failure.kind === 'shell-consistency')
+      .map((failure) => ({ file: page.file, width: viewport.width, ...failure })) || []
+  )));
+  const shellRuntimeGroups = new Map();
+  for (const page of pages) for (const viewport of page.viewports) {
+    if (!unitByFile.has(page.file)) continue;
+    for (const region of viewport.shellState?.regions || []) {
+      if (region.consistencyStatus !== 'canonical') continue;
+      const key = `${viewport.width}:${viewport.shellState.activeBand}:${region.region}`;
+      if (!shellRuntimeGroups.has(key)) shellRuntimeGroups.set(key, []);
+      shellRuntimeGroups.get(key).push({ file: page.file, signature: region.actualSignature, geometry: region.actualGeometry });
+    }
+  }
+  for (const [key, entries] of shellRuntimeGroups) {
+    const fingerprints = new Set(entries.map((entry) => JSON.stringify([entry.signature, entry.geometry])));
+    if (fingerprints.size > 1) shellConsistencyFailures.push({
+      kind: 'shell-consistency',
+      reason: 'prototype-shell-signature-mismatch',
+      group: key,
+      pages: entries,
+    });
+  }
+  const activeNavigationFailures = pages.flatMap((page) => page.viewports.flatMap((viewport) => (
+    viewport.shellState?.failures?.filter((failure) => failure.kind === 'active-navigation')
+      .map((failure) => ({ file: page.file, width: viewport.width, ...failure })) || []
+  )));
   return {
     pages,
     pageErrors: pages.reduce((sum, page) => sum + page.pageErrors.length + (page.loadError ? 1 : 0), 0),
@@ -121,6 +451,9 @@ export async function checkRuntime({ browser, baseUrl, relativeProtoPath, protoD
     duplicateIds: pages.reduce((sum, page) => sum + (page.duplicateIds?.length || 0), 0),
     brokenTargets,
     interactionFailures: pages.filter((page) => page.dropdown?.ok === false || page.modal?.ok === false).map((page) => page.file),
+    compositionFailures,
+    shellConsistencyFailures,
+    activeNavigationFailures,
     deepLinkBack,
   };
 }

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

@@ -0,0 +1,68 @@
+/**
+ * The one policy owner for selecting a prototype-wide shell donor.
+ *
+ * Analysis has already established which regions are genuine repeated shells.
+ * Inventory supplies the measured band/region declarations.  The donor is one
+ * real page, never a synthetic mixture: prefer the page covering the greatest
+ * number of declared band/region pairs, then the page that already won the
+ * most canonical-region comparisons, then the approved source page, and
+ * finally stable plan/state order.
+ */
+
+function pageStates(states, pageId) {
+  return states.filter((state) => state.pageId === pageId);
+}
+
+function measuredCoverage(page, regions) {
+  return (page.bands || []).reduce((total, band) => total + (band.shells || [])
+    .filter((shell) => regions.has(shell.region)).length, 0);
+}
+
+export function selectCanonicalShellPage({ pages, states, canonicalShell }) {
+  const regions = new Set(Object.keys(canonicalShell || {}));
+  if (regions.size === 0) return null;
+  const winners = Object.values(canonicalShell || {}).map((shell) => shell.stateId);
+  const candidates = pages.flatMap((page, pageOrder) => {
+    const ownedStates = pageStates(states, page.pageId);
+    if (ownedStates.length === 0) return [];
+    const stateOrder = Math.min(...ownedStates.map((state) => states.indexOf(state)));
+    return [{
+      pageId: page.pageId,
+      stateId: ownedStates[0].stateId,
+      coverage: measuredCoverage(page, regions),
+      canonicalWins: winners.filter((stateId) => ownedStates.some((state) => state.stateId === stateId)).length,
+      isSource: ownedStates.some((state) => state.isSource),
+      pageIndex: Number.isFinite(page.planPage?.index) ? page.planPage.index : pageOrder,
+      stateOrder,
+    }];
+  });
+  candidates.sort((left, right) => right.coverage - left.coverage
+    || right.canonicalWins - left.canonicalWins
+    || Number(right.isSource) - Number(left.isSource)
+    || left.pageIndex - right.pageIndex
+    || left.stateOrder - right.stateOrder
+    || left.pageId.localeCompare(right.pageId));
+  return candidates[0] || null;
+}
+
+export function shellForBand(page, bandKey, region) {
+  return page?.bands?.find((band) => band.key === bandKey)?.shells
+    ?.find((shell) => shell.region === region) || null;
+}
+
+export function needsCanonicalShell(recipient, canonical) {
+  if (!canonical) return false;
+  if (!recipient) return true;
+  return recipient.signature !== canonical.signature;
+}
+
+export function canonicalShellRule() {
+  return [
+    'most declared band-region pairs',
+    'most existing canonical-region wins',
+    'approved source page',
+    'plan order',
+    'state order',
+    'page id',
+  ];
+}