@12ui/design 0.2.36 → 0.2.38

package/prototype-kit/inventory.mjs

@@ -33,6 +33,294 @@ for (const file of files) {
   const planPage = planPages.find((p) => p.id === pageId);
   await page.goto('file://' + path.resolve(pagesDir, file), { waitUntil: 'load' });
   await page.evaluate(() => document.fonts.ready);
+  const declaredBands = await page.evaluate(() => {
+    const roots = [...document.querySelectorAll('.ly-band[data-ly-band]')];
+    if (roots.length === 0) return [{ key: 'native', conditions: [] }];
+    const out = new Map(roots.map((root) => [root.getAttribute('data-ly-band'), []]));
+    const visit = (rules, conditions = []) => {
+      for (const rule of rules) {
+        if (rule.cssRules && rule.conditionText) {
+          visit(rule.cssRules, [...conditions, rule.conditionText]);
+          continue;
+        }
+        if (!rule.selectorText || !rule.style) continue;
+        for (const key of out.keys()) {
+          if (rule.selectorText.includes(`.ly-band[data-ly-band="${key}"]`)
+            && rule.style.getPropertyValue('display') === 'block') {
+            out.set(key, conditions);
+          }
+        }
+      }
+    };
+    for (const sheet of document.styleSheets) {
+      try { visit(sheet.cssRules || []); } catch { /* cross-origin font sheet: no band rules */ }
+    }
+    return [...out].map(([key, conditions]) => ({ key, conditions }));
+  });
+  const viewportForBand = async ({ key, conditions }) => {
+    const suffix = Number(key.match(/(\d+)(?!.*\d)/)?.[1]);
+    const boundaries = conditions.flatMap((condition) => (
+      [...condition.matchAll(/(?:min|max)-width:\s*(\d+)px/g)].map((match) => Number(match[1]))
+    ));
+    const candidates = [
+      ...(key === 'native' && conditions.length === 0 ? [1536] : []),
+      ...(Number.isFinite(suffix) ? [suffix] : []),
+      ...boundaries.flatMap((value) => [value - 1, value, value + 1]),
+      390, 768, 1024, 1280, 1536, 1920, 2560,
+    ].filter((value, index, all) => value > 0 && value <= 4096 && all.indexOf(value) === index);
+    for (const width of candidates) {
+      await page.setViewportSize({ width, height: 1024 });
+      const selected = await page.evaluate(({ bandKey, media }) => (
+        media.every((condition) => matchMedia(condition).matches)
+        && (document.querySelectorAll('.ly-band[data-ly-band]').length === 0
+          ? bandKey === 'native'
+          : [...document.querySelectorAll('.ly-band[data-ly-band]')]
+            .filter((root) => getComputedStyle(root).display !== 'none')
+            .some((root) => root.getAttribute('data-ly-band') === bandKey))
+      ), { bandKey: key, media: conditions });
+      if (selected) return width;
+    }
+    throw new Error(`Prototype input error: declared responsive band ${key} has no selectable viewport`);
+  };
+  const bands = [];
+  for (const declared of declaredBands) {
+    const viewportWidth = await viewportForBand(declared);
+    await page.setViewportSize({ width: viewportWidth, height: 1024 });
+    const band = await page.evaluate(async ({ key, viewportWidth, conditions }) => {
+      const round = (value) => Math.round(value * 10) / 10;
+      const root = key === 'native' && !document.querySelector('.ly-band[data-ly-band]')
+        ? document.body
+        : [...document.querySelectorAll('.ly-band[data-ly-band]')]
+          .find((candidate) => candidate.getAttribute('data-ly-band') === key);
+      const screen = root?.querySelector('.generated-screen') || (root === document.body ? root : null);
+      if (!root || !screen || getComputedStyle(root).display === 'none') {
+        throw new Error(`responsive band ${key} is not active at ${viewportWidth}px`);
+      }
+      const screenBox = screen.getBoundingClientRect();
+      const host = screen.querySelector('.ly-anchor-canvas') || screen;
+      const hostBox = host.getBoundingClientRect();
+      const hostStyle = getComputedStyle(host);
+      const hostZoom = parseFloat(hostStyle.zoom) || 1;
+      const width = parseFloat(hostStyle.width) || screenBox.width / hostZoom;
+      const height = parseFloat(hostStyle.height) || screenBox.height / hostZoom;
+      const visibleCanvasHeight = Math.min(height, window.innerHeight / hostZoom);
+      const relativeBox = (element) => {
+        const box = element.getBoundingClientRect();
+        return [
+          round((box.left - hostBox.left) / hostZoom),
+          round((box.top - hostBox.top) / hostZoom),
+          round(box.width / hostZoom),
+          round(box.height / hostZoom),
+        ];
+      };
+      const shellCandidates = [...screen.querySelectorAll('header,footer,aside,nav,[id$="-nav"],[id$="-header"],[id$="-footer"],[id$="-sidebar"]')]
+        .map((element) => {
+          const [x, y, w, h] = relativeBox(element);
+          const tag = element.tagName.toLowerCase();
+          const id = element.id || '';
+          let region = null;
+          if ((tag === 'header' || tag === 'nav' || id.endsWith('-nav') || id.endsWith('-header')) && y <= visibleCanvasHeight * 0.2) region = 'header';
+          else if ((tag === 'footer' || id.endsWith('-footer')) && y + h >= visibleCanvasHeight * 0.8) region = 'footer';
+          else if ((tag === 'aside' || id.endsWith('-sidebar')) && x <= width * 0.1 && h >= visibleCanvasHeight * 0.5) region = 'sidebar';
+          return { containerId: element.id, region, box: [x, y, w, h] };
+        })
+        .filter((shell) => shell.containerId && shell.region && shell.box[2] > 0 && shell.box[3] > 0);
+      const shells = [];
+      for (const region of ['sidebar', 'header', 'footer']) {
+        const winner = shellCandidates.filter((shell) => shell.region === region)
+          .sort((left, right) => right.box[2] * right.box[3] - left.box[2] * left.box[3])[0];
+        if (winner) shells.push(winner);
+      }
+      const normalize = (value) => String(value || '').replace(/\s+/g, ' ').trim().toLocaleLowerCase();
+      const markerTarget = (label) => {
+        const value = String(label || '').replace(/\s+/g, ' ').trim();
+        const beneath = value.match(/\bunderline\s+beneath\s+(?:footer\s+)?(.+)$/i);
+        if (beneath) return beneath[1].trim();
+        const navigation = value.match(/^(.+?)\s+navigation\s+underline$/i);
+        return navigation ? navigation[1].trim() : null;
+      };
+      for (const shell of shells) {
+        const element = document.getElementById(shell.containerId);
+        const rootBox = element.getBoundingClientRect();
+        const itemNodes = [...element.querySelectorAll('.text,h1,h2,h3,h4,h5,h6,p,a,button,img,.divider,.icon')]
+          .filter((node, index, all) => node.id && all.indexOf(node) === index);
+        const items = itemNodes.map((node) => {
+          const box = relativeBox(node);
+          const style = getComputedStyle(node);
+          const chain = [];
+          for (let ancestor = node.parentElement; ancestor && ancestor !== element; ancestor = ancestor.parentElement) {
+            if (ancestor.id) chain.push(ancestor.id);
+          }
+          return {
+            id: node.id,
+            tag: node.tagName.toLowerCase(),
+            cls: typeof node.className === 'string' ? node.className : '',
+            text: ['IMG'].includes(node.tagName) ? '' : (node.textContent || '').replace(/\s+/g, ' ').trim(),
+            label: node.getAttribute('alt') || node.getAttribute('aria-label') || '',
+            x: box[0], y: box[1], w: box[2], h: box[3],
+            color: style.color,
+            background: style.backgroundColor,
+            fontSize: parseFloat(style.fontSize) || 0,
+            fontWeight: style.fontWeight,
+            chain,
+          };
+        }).filter((item) => item.w > 0 && item.h > 0);
+        const navItems = items.filter((item) => item.text && item.text.length <= 32 && item.fontSize >= 8);
+        const markerIds = new Set();
+        for (const item of items) {
+          const labelled = markerTarget(item.label);
+          if (labelled && navItems.some((nav) => normalize(nav.text) === normalize(labelled))) {
+            markerIds.add(item.id);
+            continue;
+          }
+          if (!String(item.cls).split(/\s+/).includes('divider')) continue;
+          const matches = navItems.filter((nav) => {
+            const overlap = Math.min(item.x + item.w, nav.x + nav.w) - Math.max(item.x, nav.x);
+            return overlap / Math.max(1, Math.min(item.w, nav.w)) >= 0.7
+              && item.y >= nav.y + nav.h - 2
+              && item.y - (nav.y + nav.h) <= 28
+              && item.w >= nav.w * 0.5
+              && item.w <= nav.w * 1.5;
+          });
+          if (matches.length === 1) markerIds.add(item.id);
+        }
+        const visualNodes = [element, ...element.querySelectorAll('*')]
+          .filter((node) => ![...markerIds].some((id) => node.id === id || node.closest(`#${CSS.escape(id)}`)))
+          .map((node) => {
+            const box = node.getBoundingClientRect();
+            const style = getComputedStyle(node);
+            return {
+              tag: node.tagName.toLowerCase(),
+              cls: typeof node.className === 'string' ? node.className : '',
+              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, style.position, style.color, style.backgroundColor,
+                style.fontFamily, style.fontSize, style.fontWeight, style.lineHeight,
+                style.borderTopWidth, style.borderTopColor, style.borderRadius,
+                style.opacity, style.objectFit,
+              ],
+            };
+          }).filter((node) => node.box[2] > 0 && node.box[3] > 0);
+        const encoded = new TextEncoder().encode(JSON.stringify({ region: shell.region, visualNodes }));
+        const digest = await crypto.subtle.digest('SHA-256', encoded);
+        shell.signature = [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+        shell.items = items;
+        shell.activeMarkerIds = [...markerIds];
+      }
+      const shellIds = new Set(shells.map((shell) => shell.containerId));
+      const textItems = [...screen.querySelectorAll('.text,h1,h2,h3,h4,h5,h6,p,a,button')]
+        .map((element) => {
+          const box = relativeBox(element);
+          const style = getComputedStyle(element);
+          const inShell = [...shellIds].some((id) => element.closest(`#${CSS.escape(id)}`));
+          return {
+            id: element.id,
+            text: (element.textContent || '').replace(/\s+/g, ' ').trim(),
+            x: box[0], y: box[1], w: box[2], h: box[3],
+            fontSize: parseFloat(style.fontSize) || 0,
+            fontWeight: style.fontWeight,
+            fontFamily: style.fontFamily.split(',')[0].replace(/["']/g, ''),
+            color: style.color,
+            inShell,
+          };
+        })
+        .filter((item) => item.text && !item.inShell && item.w > 0 && item.h > 0);
+      const rootColor = getComputedStyle(document.documentElement).backgroundColor;
+      const screenColor = getComputedStyle(screen).backgroundColor;
+      const neutralSurface = rootColor !== 'rgba(0, 0, 0, 0)'
+        ? rootColor
+        : screenColor !== 'rgba(0, 0, 0, 0)' ? screenColor : '#ffffff';
+      const rgb = (value) => {
+        const match = String(value).match(/rgba?\((\d+(?:\.\d+)?)[, ]+(\d+(?:\.\d+)?)[, ]+(\d+(?:\.\d+)?)/);
+        if (match) return match.slice(1, 4).map(Number);
+        const hex = String(value).match(/^#([0-9a-f]{6})$/i)?.[1];
+        return hex ? [0, 2, 4].map((offset) => parseInt(hex.slice(offset, offset + 2), 16)) : null;
+      };
+      const luminance = (value) => {
+        const channels = rgb(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 groundRegistration = screen.getAttribute('data-ly-ground-registration');
+      const colorCounts = new Map();
+      for (const item of textItems) colorCounts.set(item.color, (colorCounts.get(item.color) || 0) + 1);
+      const commonDesignInk = [...colorCounts]
+        .sort((left, right) => right[1] - left[1])[0]?.[0];
+      const neutralContrastInk = [...colorCounts.keys()]
+        .sort((left, right) => contrast(right, neutralSurface) - contrast(left, neutralSurface))[0];
+      const fallbackInk = contrast('#111111', neutralSurface) >= contrast('#ffffff', neutralSurface)
+        ? '#111111'
+        : '#ffffff';
+      const heading = textItems
+        .sort((left, right) => right.fontSize - left.fontSize || left.y - right.y)[0] || null;
+      const usesNeutralSurface = groundRegistration === 'positioned-scene';
+      const readableTextColor = usesNeutralSurface
+        ? contrast(neutralContrastInk, neutralSurface) >= 4.5 ? neutralContrastInk : fallbackInk
+        : heading?.color || commonDesignInk || fallbackInk;
+      if (heading && usesNeutralSurface && contrast(heading.color, neutralSurface) < 4.5) {
+        heading.color = readableTextColor;
+      }
+      return {
+        key,
+        viewportWidth,
+        conditions,
+        width: round(width),
+        height: round(height),
+        neutralSurface,
+        readableTextColor,
+        groundRegistration: groundRegistration === 'positioned-scene' ? groundRegistration : null,
+        shells,
+        heading,
+      };
+    }, { key: declared.key, viewportWidth, conditions: declared.conditions });
+    const hostOrigins = [];
+    for (const sampleWidth of [...new Set([1536, 390, viewportWidth])]) {
+      await page.setViewportSize({ width: sampleWidth, height: 1024 });
+      const origin = await page.evaluate(({ key }) => {
+        const round = (value) => Math.round(value * 10) / 10;
+        const root = key === 'native' && !document.querySelector('.ly-band[data-ly-band]')
+          ? document.body
+          : [...document.querySelectorAll('.ly-band[data-ly-band]')]
+            .find((candidate) => candidate.getAttribute('data-ly-band') === key);
+        const screen = root?.querySelector('.generated-screen') || (root === document.body ? root : null);
+        if (!root || !screen || getComputedStyle(root).display === 'none') return null;
+        const rootBox = root.getBoundingClientRect();
+        if (rootBox.width <= 0 || rootBox.height <= 0) return null;
+        const screenBox = screen.getBoundingClientRect();
+        const host = screen.querySelector('.ly-anchor-canvas') || screen;
+        const hostBox = host.getBoundingClientRect();
+        const hostZoom = parseFloat(getComputedStyle(host).zoom) || 1;
+        return [
+          round((hostBox.left - screenBox.left) / hostZoom),
+          round((hostBox.top - screenBox.top) / hostZoom),
+        ];
+      }, { key: declared.key });
+      if (origin) hostOrigins.push({ viewportWidth: sampleWidth, origin });
+    }
+    if (!hostOrigins.some((sample) => sample.viewportWidth === viewportWidth)) {
+      throw new Error(`Prototype input error: no measured host origin for band ${declared.key} at ${viewportWidth}px`);
+    }
+    bands.push({ ...band, hostOrigins });
+  }
+  await page.setViewportSize({ width: 1536, height: 1024 });
   const sections = await page.evaluate(() => {
     const secs = [...document.querySelectorAll('section[id^="viewport-"]')].filter((s) => /^viewport-\d+-[A-Za-z0-9]+$/.test(s.id));
     const out = [];
@@ -95,8 +383,8 @@ for (const file of files) {
     }
     return out;
   });
-  result.pages.push({ pageId, file, planPage, sections });
-  console.error(`${pageId}: ${sections.length} section(s), ${sections.reduce((n, s) => n + s.items.length, 0)} items`);
+  result.pages.push({ pageId, file, planPage, bands, sections });
+  console.error(`${pageId}: ${sections.length} section(s), ${bands.length} band(s), ${sections.reduce((n, s) => n + s.items.length, 0)} items`);
 }
 
 await browser.close();

package/prototype-kit/lib/holding-composition.mjs

@@ -0,0 +1,67 @@
+export const HOLDING_SURFACE_ATTRIBUTE = 'data-proto-holding-surface';
+export const HOLDING_SHELL_ATTRIBUTE = 'data-proto-shell-region';
+
+const escapeText = (value) => String(value)
+  .replace(/&/g, '&')
+  .replace(/</g, '&lt;');
+
+const escapeAttribute = (value) => escapeText(value).replace(/"/g, '&quot;');
+
+export function holdingContentArea({ width, height, shells }) {
+  const area = { left: 0, top: 0, right: width, bottom: height };
+  for (const shell of shells) {
+    const [x, y, w, h] = shell.box;
+    if (shell.region === 'sidebar') area.left = Math.max(area.left, x + w);
+    if (shell.region === 'header') area.top = Math.max(area.top, y + h);
+    if (shell.region === 'footer') area.bottom = Math.min(area.bottom, y);
+  }
+  if (area.right <= area.left || area.bottom <= area.top) {
+    throw new Error(`Holding composition has no content area inside ${width}x${height}.`);
+  }
+  return area;
+}
+
+export function holdingBlockGeometry({ area, heading, viewportWidth }) {
+  const mobile = viewportWidth <= 600;
+  const inset = mobile ? 20 : Math.min(160, Math.max(32, Math.round((heading?.x ?? area.left + 40) - area.left)));
+  const left = area.left + inset;
+  const top = mobile
+    ? area.top + 28
+    : Math.max(area.top + 40, Math.min(area.top + 200, Math.round(heading?.y ?? area.top + 60)));
+  const width = Math.min(area.right - left - inset, 1100);
+  if (width <= 0 || top >= area.bottom) {
+    throw new Error('Holding composition has no room for its holding surface.');
+  }
+  return { left, top, width };
+}
+
+export function shellPlacementCss(shell) {
+  const [left, top, width, height] = shell.box;
+  return `#${shell.containerId}{position:absolute!important;left:${left}px!important;top:${top}px!important;`
+    + `width:${width}px!important;height:${height}px!important;margin:0!important;z-index:5}`;
+}
+
+export function holdingBlockMarkup({
+  title,
+  purpose,
+  backTarget,
+  backTitle,
+  geometry,
+  heading,
+  tokens,
+  textColor,
+  mobile,
+}) {
+  const headingFamily = escapeAttribute(heading?.fontFamily || tokens.headingFont || 'system-ui');
+  const headingSize = Number(heading?.fontSize || tokens.headingSize || 28);
+  const headingWeight = escapeAttribute(heading?.fontWeight || tokens.headingWeight || 600);
+  const headingColor = escapeAttribute(heading?.color || tokens.headingColor || '#111111');
+  const bodyColor = escapeAttribute(textColor || headingColor);
+  const layout = mobile ? ' data-proto-holding-layout="mobile"' : '';
+  return `<div class="proto-holding-block" ${HOLDING_SURFACE_ATTRIBUTE}="true"${layout} style="left:${geometry.left}px;top:${geometry.top}px;width:${geometry.width}px">
+      <h1 class="proto-holding-title" style="font-family:'${headingFamily}',sans-serif;font-size:${headingSize}px;font-weight:${headingWeight};color:${headingColor}">${escapeText(title)}</h1>
+      <p class="proto-holding-sub" style="color:${bodyColor}">${escapeText(purpose)}</p>
+      <div class="proto-holding-cards" aria-hidden="true">${[1, 2, 3].map(() => '<div class="proto-holding-card"><div class="proto-holding-card-line"></div><div class="proto-holding-card-line short"></div><div class="proto-holding-card-line"></div></div>').join('')}</div>
+      <p class="proto-holding-note" style="color:${bodyColor}"><a class="proto-clickable" href="${escapeAttribute(backTarget)}" data-proto-action="navigate" data-proto-target="${escapeAttribute(backTarget)}" aria-label="Back to ${escapeAttribute(backTitle)}">Back</a></p>
+    </div>`;
+}

package/prototype-kit/lib/nav-active-state.mjs

@@ -0,0 +1,67 @@
+import { normalizeText } from './text.mjs';
+
+const explicitMarkerTarget = (label) => {
+  const normalized = String(label || '').replace(/\s+/g, ' ').trim();
+  if (!normalized) return null;
+  const beneath = normalized.match(/\bunderline\s+beneath\s+(?:footer\s+)?(.+)$/i);
+  if (beneath) return beneath[1].trim();
+  const navigation = normalized.match(/^(.+?)\s+navigation\s+underline$/i);
+  if (navigation) return navigation[1].trim();
+  return null;
+};
+
+function overlapsHorizontally(marker, nav) {
+  const overlap = Math.min(marker.x + marker.w, nav.x + nav.w) - Math.max(marker.x, nav.x);
+  return overlap / Math.max(1, Math.min(marker.w, nav.w)) >= 0.7;
+}
+
+function geometricDividerTarget(marker, navItems) {
+  if (!String(marker.cls || '').split(/\s+/).includes('divider')) return null;
+  const candidates = navItems.filter((nav) => overlapsHorizontally(marker, nav)
+    && marker.y >= nav.y + nav.h - 2
+    && marker.y - (nav.y + nav.h) <= 28
+    && marker.w >= nav.w * 0.5
+    && marker.w <= nav.w * 1.5);
+  return candidates.length === 1 ? candidates[0].text : null;
+}
+
+/**
+ * Finds only marker entities the converted page declared strongly enough to
+ * move: an explicit accessible underline label, or one unique divider directly
+ * below a declared nav entity. Ambiguity means silence.
+ */
+export function declaredActiveMarkers(shell, navItems) {
+  if (!shell) return [];
+  const normalizedNav = new Map(navItems.map((item) => [normalizeText(item.text), item]));
+  return (shell.items || []).flatMap((item) => {
+    const labelled = explicitMarkerTarget(item.label);
+    const targetText = labelled || geometricDividerTarget(item, navItems);
+    const target = targetText ? normalizedNav.get(normalizeText(targetText)) : null;
+    if (!target) return [];
+    return [{
+      id: item.id,
+      targetText: target.text,
+      targetId: target.id,
+      evidence: labelled ? 'declared-label' : 'measured-divider',
+      box: [item.x, item.y, item.w, item.h],
+      parentIds: item.chain || [],
+    }];
+  });
+}
+
+export function linkedNavForUnit({ navRows, unit, sourceMarkers, region }) {
+  const linked = navRows.filter((item) => item.region === region
+    && item.target
+    && unit.states.some((state) => state.stateId === item.target));
+  if (linked.length === 0) return null;
+  const declared = sourceMarkers
+    .map((marker) => linked.find((item) => normalizeText(item.text) === normalizeText(marker.targetText)))
+    .find(Boolean);
+  return declared || linked[0];
+}
+
+export function markerOverlapsNav(marker, nav) {
+  return overlapsHorizontally(marker, nav)
+    && marker.y >= nav.y + nav.h - 2
+    && marker.y - (nav.y + nav.h) <= 32;
+}

package/prototype-kit/lib/review-framing.mjs

@@ -0,0 +1,72 @@
+const escapeText = (value) => String(value ?? '')
+  .replace(/&/g, '&')
+  .replace(/</g, '&lt;')
+  .replace(/>/g, '&gt;');
+
+const escapeAttribute = (value) => escapeText(value).replace(/"/g, '&quot;');
+
+const branchStatus = (review) => {
+  const terminal = String(review.terminalStatus || '').toLowerCase();
+  return terminal === 'failed' ? 'Failed' : 'Partial';
+};
+
+const routeCountCopy = (available, expected) => {
+  const noun = expected === 1 ? 'route' : 'routes';
+  return `${available} of ${expected} ${noun} ${available === 1 ? 'is' : 'are'} available in this review.`;
+};
+
+export function reviewFramingMarkup(review) {
+  const available = Number.isFinite(review.availablePageCount) ? review.availablePageCount : 0;
+  const expected = Number.isFinite(review.expectedPageCount) ? review.expectedPageCount : 0;
+  const unavailable = Array.isArray(review.missingRoutes) ? review.missingRoutes : [];
+  const unavailableLinks = unavailable.map((route) => (
+    `<a href="${escapeAttribute(route.file)}">${escapeText(route.title)}</a>`
+  )).join('');
+  const startingPageCopy = review.winnerPageFailed
+    ? review.entry?.kind === 'holding'
+      ? '<p class="proto-review-framing__explanation">The approved starting page could not be built. This review opens on its unavailable-page notice instead of substituting another route.</p>'
+      : `<p class="proto-review-framing__explanation">The approved starting page could not be built. This review opens on ${escapeText(review.entry?.title || 'another available route')} instead, while keeping the missing page explicit.</p>`
+    : '';
+  const unavailableCopy = unavailable.length > 0
+    ? `<div class="proto-review-framing__routes"><span>Unavailable routes:</span>${unavailableLinks}</div>`
+    : '<p class="proto-review-framing__routes proto-review-framing__routes--empty">No unavailable routes are listed.</p>';
+
+  return `<aside id="proto-review-framing" class="proto-review-framing" aria-label="Prototype review status">
+    <p class="proto-review-framing__eyebrow">Prototype review</p>
+    <p class="proto-review-framing__status">Branch status: ${branchStatus(review)}</p>
+    <p class="proto-review-framing__count">${routeCountCopy(available, expected)}</p>
+    ${startingPageCopy}
+    ${unavailableCopy}
+  </aside>`;
+}
+
+const REVIEW_FRAMING_CSS = `
+#proto-review-framing.proto-review-framing{
+  position:fixed;right:18px;bottom:18px;z-index:2147483646;
+  box-sizing:border-box;width:min(430px,calc(100vw - 36px));max-height:calc(100vh - 36px);overflow:auto;
+  padding:16px 18px;border:1px solid rgba(255,255,255,.2);border-radius:14px;
+  background:rgba(20,22,26,.96);box-shadow:0 18px 54px rgba(0,0,0,.34);
+  color:#f7f7f5;font:500 14px/1.42 ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;
+  letter-spacing:0;text-align:left;writing-mode:horizontal-tb;direction:ltr;
+}
+#proto-review-framing.proto-review-framing p{margin:0;color:inherit;font:inherit;letter-spacing:inherit;text-transform:none}
+#proto-review-framing .proto-review-framing__eyebrow{margin-bottom:5px;color:#c8c9cd;font-size:11px;font-weight:700;letter-spacing:.08em}
+#proto-review-framing .proto-review-framing__status{font-size:18px;font-weight:750;line-height:1.2}
+#proto-review-framing .proto-review-framing__count{margin-top:5px;color:#e1e2e5}
+#proto-review-framing .proto-review-framing__explanation{margin-top:10px;padding-top:10px;border-top:1px solid rgba(255,255,255,.14);color:#fff}
+#proto-review-framing .proto-review-framing__routes{display:flex;flex-wrap:wrap;align-items:center;gap:7px;margin-top:11px;color:#c8c9cd}
+#proto-review-framing .proto-review-framing__routes span{margin-right:1px}
+#proto-review-framing .proto-review-framing__routes a{display:inline-flex;padding:4px 8px;border:1px solid rgba(255,255,255,.24);border-radius:999px;color:#fff;text-decoration:none;font:650 12px/1.25 ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}
+#proto-review-framing .proto-review-framing__routes a:hover,#proto-review-framing .proto-review-framing__routes a:focus-visible{background:#fff;color:#17191d;outline:none}
+#proto-review-framing .proto-review-framing__routes--empty{display:block}
+@media(max-width:600px){#proto-review-framing.proto-review-framing{right:10px;bottom:10px;width:calc(100vw - 20px);max-height:calc(100vh - 20px);padding:14px 15px}}
+`;
+
+export function injectReviewFraming(document, review) {
+  if (!review) return;
+  document.querySelector('head').insertAdjacentHTML(
+    'beforeend',
+    `<style id="proto-review-framing-style">${REVIEW_FRAMING_CSS}</style>`,
+  );
+  document.body.insertAdjacentHTML('afterbegin', reviewFramingMarkup(review));
+}