@12ui/design 0.2.36 → 0.2.38

package/prototype-kit/build.mjs

@@ -4,12 +4,22 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseHTML } from 'linkedom';
 import { usableDropdownOptions } from './lib/actions.mjs';
-import { shouldSuppressDroppedShell, shouldTransplantShell } from './lib/shells.mjs';
+import {
+  HOLDING_SHELL_ATTRIBUTE,
+  holdingBlockGeometry,
+  holdingBlockMarkup,
+  holdingContentArea,
+  shellPlacementCss,
+} from './lib/holding-composition.mjs';
+import { injectReviewFraming } from './lib/review-framing.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';
 
 const [runDir, invFile, modelFile, labelsDir, outDir] = process.argv.slice(2);
 const inv = JSON.parse(fs.readFileSync(invFile, 'utf8'));
 const model = JSON.parse(fs.readFileSync(modelFile, 'utf8'));
+const review = model.review || null;
 const here = path.dirname(new URL(import.meta.url).pathname);
 fs.mkdirSync(path.join(outDir, 'content'), { recursive: true });
 fs.copyFileSync(path.join(here, 'runtime/proto.js'), path.join(outDir, 'proto.js'));
@@ -31,8 +41,21 @@ for (const s of states) {
     u.states.push(s);
   } else units.push({ id: s.stateId, pageId: s.pageId, file: s.file, states: [s], title: s.title, isSource: s.isSource });
 }
+const reviewRealRoutes = review && Array.isArray(review.realRoutes) ? review.realRoutes : [];
+const reviewMissingRoutes = review && Array.isArray(review.missingRoutes) ? review.missingRoutes : [];
+const routeKey = (value) => norm(String(value || '').replace(/^p\d+-/, '').replace(/-/g, ' '));
+const reviewRealRouteForUnit = (unit) => reviewRealRoutes.find((route) => {
+  const keys = new Set([
+    unit.id,
+    unit.pageId,
+    unit.title,
+    ...unit.states.flatMap((state) => [state.stateId, state.pageId, state.title]),
+  ].map(routeKey));
+  return keys.has(routeKey(route.id)) || keys.has(routeKey(route.title));
+});
+const outputFileOfUnit = (unit) => reviewRealRouteForUnit(unit)?.file || `${unit.id}.html`;
 const unitOf = (stateId) => units.find((u) => u.states.some((s) => s.stateId === stateId));
-const fileOf = (stateId) => unitOf(stateId) ? unitOf(stateId).id + '.html' : null;
+const fileOf = (stateId) => unitOf(stateId) ? outputFileOfUnit(unitOf(stateId)) : null;
 
 // ---- labels (Luna) per state
 const labels = {};
@@ -46,7 +69,23 @@ const holdings = new Map(); // slug -> title
 for (const n of model.nav) if (n.holding) holdings.set(n.holding, n.text);
 for (const acts of Object.values(labels)) for (const a of acts) if (a.action === 'navigate' && /^holding:/.test(a.target || '')) { const t = a.target.slice(8).trim(); holdings.set('holding-' + slug(t), t); }
 const usedHoldings = new Map(); // slug -> title, only those actually referenced by a bound action or nav item
-const holdingFile = (title) => { usedHoldings.set('holding-' + slug(title), holdings.get('holding-' + slug(title)) || title); return 'holding-' + slug(title) + '.html'; };
+const reviewMissingByHolding = new Map(reviewMissingRoutes.map((route) => [route.holding, route]));
+const reviewMissingForTitle = (title) => reviewMissingRoutes.find((route) => (
+  norm(route.title) === norm(title) || routeKey(route.id) === routeKey(title)
+));
+for (const route of reviewMissingRoutes) {
+  holdings.set(route.holding, route.title);
+  usedHoldings.set(route.holding, route.title);
+}
+const holdingFile = (title) => {
+  const reviewRoute = reviewMissingForTitle(title);
+  if (reviewRoute) {
+    usedHoldings.set(reviewRoute.holding, reviewRoute.title);
+    return reviewRoute.file;
+  }
+  usedHoldings.set('holding-' + slug(title), holdings.get('holding-' + slug(title)) || title);
+  return 'holding-' + slug(title) + '.html';
+};
 
 // ---- page docs cache
 const docCache = new Map();
@@ -110,7 +149,21 @@ function findPill(region) {
 const pills = Object.fromEntries(Object.keys(shell).map((r) => [r, findPill(r)]));
 
 // ---- action resolution for one state
-const report = { units: [], unbound: [], invalidDropdowns: [], shellSizeDelta: [], shellAmbiguities: model.shellAmbiguities || [], suppressedShellOverlaps: [], skippedShellTransplants: [], replacedShellActions: 0, shellActionRemaps: 0, holdings: [...holdings.values()], counts: { navigate: 0, dropdown: 0, modal: 0, field: 0, none: 0, lunaOnly: 0, detOnly: 0, agree: 0, disagree: 0 } };
+const report = {
+  units: [],
+  unbound: [],
+  invalidDropdowns: [],
+  shellSizeDelta: [],
+  shellAmbiguities: model.shellAmbiguities || [],
+  suppressedShellOverlaps: [],
+  skippedShellTransplants: [],
+  replacedShellActions: 0,
+  shellActionRemaps: 0,
+  canonicalShellPage: model.canonicalShellPage || null,
+  shellConsistency: { changes: 0, decisions: [] },
+  holdings: [...holdings.values()],
+  counts: { navigate: 0, dropdown: 0, modal: 0, field: 0, none: 0, lunaOnly: 0, detOnly: 0, agree: 0, disagree: 0 },
+};
 function resolveTarget(target, currentStateId) {
   if (!target) return null;
   if (/^holding:/.test(target)) return holdingFile(target.slice(8).trim());
@@ -119,7 +172,10 @@ function resolveTarget(target, currentStateId) {
     if (unitOf(target) === unitOf(currentStateId)) return fileOf(target) + '#' + byState[target].sectionId;
     return fileOf(target);
   }
-  if (holdings.has(target)) return 'holding-' + target.replace(/^holding-/, '') + '.html';
+  if (holdings.has(target)) {
+    const reviewRoute = reviewMissingByHolding.get(target) || reviewMissingForTitle(holdings.get(target));
+    return reviewRoute?.file || 'holding-' + target.replace(/^holding-/, '') + '.html';
+  }
   // an invented id like "reports" -> a holding page titled "Reports"
   if (/^[a-z][a-z0-9-]{2,40}$/.test(target)) return holdingFile(target.split('-').map((w) => w[0].toUpperCase() + w.slice(1)).join(' '));
   return null;
@@ -193,7 +249,34 @@ for (const u of units) {
   const allActions = {};
   const content = {};
   let fieldCount = 0;
-  const activeNav = navRows.find((n) => n.target && unitOf(n.target)?.id === u.id);
+  const recipientPage = inv.pages.find((page) => page.pageId === u.pageId);
+  const donorPage = inv.pages.find((page) => page.pageId === model.canonicalShellPage?.pageId);
+  const donorState = states.find((state) => state.pageId === donorPage?.pageId);
+  if (!recipientPage) throw new Error(`Prototype shell consistency cannot resolve recipient page for ${u.id}.`);
+  const stitched = donorPage && donorState
+    ? stitchUnitShells({
+        document,
+        donorDocument: loadDoc(donorState.file).document,
+        donorPage,
+        recipientPage,
+        unit: u,
+        canonicalShell: model.canonicalShell,
+        navRows,
+        rulesFor,
+        styleText,
+      })
+    : { extraCss: [], bands: [], decisions: [], changes: 0 };
+  extraCss.push(...stitched.extraCss);
+  report.shellConsistency.changes += stitched.changes;
+  report.shellConsistency.decisions.push(...stitched.decisions.map((decision) => ({ unit: u.id, ...decision })));
+  for (const decision of stitched.decisions.filter((candidate) => candidate.reason.startsWith('incompatible-') || candidate.reason.startsWith('missing-'))) {
+    report.skippedShellTransplants.push({ unit: u.id, region: decision.region, reason: decision.reason });
+  }
+  const activeRegionFact = stitched.bands.flatMap((band) => band.regions)
+    .find((region) => region.active?.status === 'linked') || null;
+  const activeNav = activeRegionFact
+    ? navRows.find((row) => row.region === activeRegionFact.region && norm(row.text) === norm(activeRegionFact.active.navText))
+    : navRows.find((row) => row.target && unitOf(row.target)?.id === u.id);
 
   for (const s of u.states) {
     const section = document.getElementById(s.sectionId);
@@ -205,23 +288,6 @@ for (const u of units) {
         report.suppressedShellOverlaps.push({ state: s.stateId, region: ambiguity.region, dropped: ambiguity.dropped, kept: ambiguity.kept });
       }
     }
-    // shell transplant
-    for (const sh of s.shell) {
-      const can = shell[sh.region]; if (!can) continue;
-      const own = document.getElementById(sh.containerId);
-      if (!own) continue;
-      if (can.containerId === sh.containerId) continue; // this is the canonical page
-      if (!shouldTransplantShell(sh.box, can.box)) {
-        report.skippedShellTransplants.push({ state: s.stateId, region: sh.region, own: sh.box.slice(2), canonical: can.box.slice(2) });
-        continue;
-      }
-      // keep this page's own layout box (it may be in normal flow); swap in the canonical children + background
-      own.innerHTML = can.inner;
-      own.setAttribute('data-proto-shell', can.containerId);
-      extraCss.push(can.css);
-      extraCss.push(`#${sh.containerId}{${can.background ? `background:${can.background}!important;` : ''}overflow:visible!important;z-index:5}`);
-      if (Math.abs(sh.box[2] - can.box[2]) > 2 || Math.abs(sh.box[3] - can.box[3]) > 2) report.shellSizeDelta.push({ state: s.stateId, region: sh.region, own: sh.box.slice(2), canonical: can.box.slice(2) });
-    }
     // actions
     const acts = stateActions.get(s.stateId);
     for (const [id, a] of acts) {
@@ -308,52 +374,174 @@ for (const u of units) {
   head.insertAdjacentHTML('beforeend', `<style id="proto-extra">${extraCss.join('\n')}</style><link rel="stylesheet" href="proto.css">`);
   const cfg = { unit: u.id, states: u.states.map((s) => s.stateId), tokens: model.tokens, contentFile: `${u.id}.json`, activeNav: activeNav?.text || null };
   document.body.insertAdjacentHTML('beforeend', `<script id="proto-state" type="application/json">${JSON.stringify(cfg).replace(/</g, '\\u003c')}</script><script src="proto.js"></script>`);
-  fs.writeFileSync(path.join(outDir, u.id + '.html'), '<!doctype html>\n' + document.documentElement.outerHTML);
+  if (review) injectReviewFraming(document, review);
+  fs.writeFileSync(path.join(outDir, outputFileOfUnit(u)), '<!doctype html>\n' + document.documentElement.outerHTML);
   fs.writeFileSync(path.join(outDir, 'content', u.id + '.json'), JSON.stringify(content, null, 1));
-  report.units.push({ id: u.id, states: u.states.map((s) => s.stateId), actions: Object.keys(allActions).length, fields: fieldCount, texts: Object.keys(content).length, activeNav: activeNav?.text || null });
+  report.units.push({
+    id: u.id,
+    states: u.states.map((s) => s.stateId),
+    actions: Object.keys(allActions).length,
+    fields: fieldCount,
+    texts: Object.keys(content).length,
+    activeNav: activeNav?.text || null,
+    shellBands: stitched.bands,
+    shellDecisions: stitched.decisions,
+  });
   console.error(`${u.id}.html  actions=${Object.keys(allActions).length} fields=${fieldCount} texts=${Object.keys(content).length} active=${activeNav?.text || '-'}`);
 }
 
-// ---- holding pages: canonical shell(s) + page background + a styled block in the content area
+// ---- holding pages: fresh per-band composition from measured shells + neutral surface + holding block
 {
   const primaryRegion = model.canonicalShell.sidebar ? 'sidebar' : model.canonicalShell.header ? 'header' : Object.keys(model.canonicalShell)[0];
   const can = primaryRegion ? shell[primaryRegion] : null;
   const base = can ? byState[can.stateId] : (states.find((s) => s.isSource) || states[0]);
   const baseSec = invSection(base);
-  // content area: the section minus shell boxes
-  let area = { x: 0, y: 0, w: 1536, h: baseSec.height };
-  for (const sh of base.shell) {
-    const [x, y, w, h] = sh.box;
-    if (sh.region === 'sidebar') { area.x = Math.max(area.x, x + w); }
-    if (sh.region === 'header') { area.y = Math.max(area.y, y + h); }
-    if (sh.region === 'footer') { area.h = Math.min(area.h, y); }
+  const basePage = inv.pages.find((page) => page.pageId === base.pageId);
+  if (!basePage?.bands?.length) {
+    throw new Error(`Holding composition requires measured band inventory for ${base.pageId}.`);
   }
-  // heading style from the base page's largest content text
-  // anchor the block where the page's own title sits: the top-most large text in the content area
-  const heading = baseSec.items.filter((t) => t.text && t.x >= area.x && t.fontSize >= 20 && t.y < area.y + 200).sort((a, b) => a.y - b.y || a.x - b.x)[0]
-    || baseSec.items.filter((t) => t.text && t.x >= area.x).sort((a, b) => b.fontSize - a.fontSize)[0];
-  const pad = Math.min(160, Math.max(32, Math.round((heading?.x || area.x + 40) - area.x)));
-  const top = Math.min(200, Math.max(40, Math.round(heading?.y || 60)));
+  const sourceState = states.find((state) => state.isSource) || states[0];
   for (const n of navRows) if (n.holding) holdingFile(n.text);
   for (const [hslug, htitle] of usedHoldings) {
     const { document } = loadDoc(base.file);
-    for (const sec of [...document.querySelectorAll('section[id^="viewport-"]')]) if (/^viewport-\d+-[A-Za-z0-9]+$/.test(sec.id) && sec.id !== base.sectionId) sec.remove();
     for (const sc of [...document.querySelectorAll('script')]) sc.remove();
-    const section = document.getElementById(base.sectionId);
-    const keepIds = new Set(base.shell.map((x) => x.containerId));
-    const bgIds = new Set(baseSec.containers.filter((c) => c.x === 0 && c.y === 0 && c.w >= 1535 && c.children === 0).map((c) => c.id));
-    for (const child of [...section.children]) if (!keepIds.has(child.id) && !bgIds.has(child.id)) child.remove();
     const navMatch = navRows.find((n) => n.holding === hslug);
-    const extraCss = [`.ly-anchor-canvas,#page-flow{height:${baseSec.height}px!important}`];
-    // composite the other canonical shell regions (e.g. a footer that lives in a different state)
-    for (const [region, can] of Object.entries(shell)) {
-      if (base.shell.some((x) => x.region === region)) continue;
-      section.insertAdjacentHTML('beforeend', can.html);
-      extraCss.push(can.css);
-      const top = region === 'footer' ? baseSec.height - can.box[3] : can.box[1];
-      extraCss.push(`#${can.containerId}{position:absolute!important;left:${can.box[0]}px!important;top:${top}px!important;margin:0!important;z-index:5}`);
-      if (region === 'footer') area.h = Math.min(area.h, top);
+    const reviewRoute = reviewMissingByHolding.get(hslug);
+    const outputFile = reviewRoute?.file || hslug + '.html';
+    const reviewBackRoute = review?.entry?.file === outputFile
+      ? reviewRealRoutes[0]
+      : review?.entry;
+    const backTarget = reviewBackRoute?.file || fileOf(sourceState.stateId);
+    const backTitle = reviewBackRoute?.title || sourceState.title;
+    const extraCss = [];
+    const bandDeclarations = [];
+    const bandRoots = [...document.querySelectorAll('.ly-band[data-ly-band]')];
+    const declared = bandRoots.length > 0
+      ? bandRoots.map((root) => ({ key: root.getAttribute('data-ly-band'), root }))
+      : [{ key: 'native', root: document.body }];
+
+    for (const { key, root } of declared) {
+      const screen = root.querySelector('.generated-screen') || (root === document.body ? root : null);
+      if (!screen) throw new Error(`Holding composition requires a screen root in band ${key}.`);
+      const band = basePage.bands.find((candidate) => candidate.key === key);
+      if (!band) {
+        throw new Error(`Holding composition has no measured inventory for declared band ${key} on ${base.pageId}.`);
+      }
+      if (!Array.isArray(band.hostOrigins) || band.hostOrigins.length === 0) {
+        throw new Error(`Holding composition has no measured viewport host origins for declared band ${key} on ${base.pageId}.`);
+      }
+      const host = screen.querySelector('.ly-anchor-canvas') || screen;
+      if (!host) throw new Error(`Holding composition requires a declared composition host in band ${key}.`);
+
+      const regions = new Set((band.shells || []).map((candidate) => candidate.region));
+      const canonicalBands = new Map();
+      for (const [region, canonical] of Object.entries(shell)) {
+        const canonicalState = byState[canonical.stateId];
+        const canonicalPage = inv.pages.find((page) => page.pageId === canonicalState.pageId);
+        const canonicalBand = canonicalPage?.bands?.find((candidate) => candidate.key === key) || null;
+        canonicalBands.set(region, { canonicalState, canonicalBand });
+        if (canonicalBand?.shells?.some((candidate) => candidate.region === region)) regions.add(region);
+      }
+      const placedShells = [...regions].map((region) => {
+        const canonical = canonicalBands.get(region);
+        const canonicalCandidate = canonical?.canonicalBand?.shells?.find((candidate) => candidate.region === region);
+        const baseCandidate = band.shells.find((candidate) => candidate.region === region);
+        const candidate = canonicalCandidate || baseCandidate;
+        const donorState = canonicalCandidate ? canonical.canonicalState : base;
+        if (!candidate || !donorState) {
+          throw new Error(`Holding composition cannot resolve measured ${region} shell geometry in band ${key}.`);
+        }
+        const { document: donorDocument } = loadDoc(donorState.file);
+        const donorRoots = [...donorDocument.querySelectorAll('.ly-band[data-ly-band]')];
+        const donorRoot = donorRoots.length > 0
+          ? donorRoots.find((candidateRoot) => candidateRoot.getAttribute('data-ly-band') === key)
+          : donorDocument.body;
+        const element = donorDocument.getElementById(candidate.containerId);
+        if (!donorRoot || !element || !donorRoot.contains(element)) {
+          throw new Error(`Holding composition cannot find declared ${region} shell ${candidate.containerId} in band ${key}.`);
+        }
+        const ancestorIds = [];
+        for (let ancestor = element.parentElement; ancestor && ancestor !== donorRoot; ancestor = ancestor.parentElement) {
+          if (ancestor.id) ancestorIds.push(ancestor.id);
+        }
+        return {
+          ...candidate,
+          region,
+          html: element.outerHTML,
+          css: rulesFor(styleText(donorDocument), candidate.containerId),
+          ancestorIds,
+        };
+      });
+
+      if (host !== screen) {
+        for (const child of [...screen.children]) if (child !== host) child.remove();
+      }
+      for (const child of [...host.children]) child.remove();
+      const parentShell = (placed) => placedShells.find((candidate) => (
+        candidate !== placed && placed.ancestorIds.includes(candidate.containerId)
+      ));
+      for (const placed of placedShells.filter((candidate) => !parentShell(candidate))) {
+        host.insertAdjacentHTML('beforeend', placed.html);
+      }
+      for (const placed of placedShells) {
+        const element = document.getElementById(placed.containerId);
+        if (!element || !host.contains(element)) {
+          throw new Error(`Holding composition failed to retain ${placed.region} shell ${placed.containerId} in band ${key}.`);
+        }
+        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]]
+          : placed.box;
+        extraCss.push(shellPlacementCss({ ...placed, box }));
+      }
+
+      const area = holdingContentArea({ width: band.width, height: band.height, shells: placedShells });
+      const heading = band.heading || baseSec.items
+        .filter((item) => item.text && item.x >= area.left && item.fontSize >= 20 && item.y < area.top + 200)
+        .sort((left, right) => left.y - right.y || left.x - right.x)[0]
+        || baseSec.items.filter((item) => item.text && item.x >= area.left)
+          .sort((left, right) => right.fontSize - left.fontSize)[0];
+      const geometry = holdingBlockGeometry({ area, heading, viewportWidth: band.viewportWidth });
+      const purpose = `${htitle} is planned, but it is not included in this prototype yet.`;
+      host.insertAdjacentHTML('beforeend', holdingBlockMarkup({
+        title: htitle,
+        purpose,
+        backTarget,
+        backTitle,
+        geometry,
+        heading,
+        tokens: model.tokens,
+        textColor: band.readableTextColor,
+        mobile: band.viewportWidth <= 600,
+      }));
+      const holdingSurfaces = root.querySelectorAll('[data-proto-holding-surface="true"]');
+      if (holdingSurfaces.length !== 1) {
+        throw new Error(`Holding composition requires exactly one surface in band ${key}; found ${holdingSurfaces.length}.`);
+      }
+      const hostId = host.id || `proto-holding-${key}-host`;
+      if (!host.id) host.id = hostId;
+      host.setAttribute('data-proto-holding-band', key);
+      if (band.groundRegistration === 'positioned-scene') {
+        const selector = bandRoots.length > 0
+          ? `.ly-band[data-ly-band="${key}"]>.generated-screen`
+          : document.querySelector('.generated-screen') ? '.generated-screen' : 'body';
+        extraCss.push(`${selector}{background:${band.neutralSurface}!important;background-image:none!important}`);
+        extraCss.push(`${selector}::before,${selector}::after{content:none!important;display:none!important;background:none!important;border:0!important}`);
+        screen.setAttribute('data-proto-ground-neutralized', 'positioned-scene');
+      }
+      bandDeclarations.push({
+        key,
+        viewportWidth: band.viewportWidth,
+        hostOrigins: band.hostOrigins,
+        shellIds: placedShells.map((placed) => placed.containerId),
+        shellBoxes: placedShells.map((placed) => ({ id: placed.containerId, box: placed.box })),
+        groundRegistration: band.groundRegistration,
+        neutralSurface: band.neutralSurface,
+      });
     }
+
     if (navMatch) {
       const p = pills[navMatch.region];
       if (p && p.own.id !== navMatch.id) {
@@ -363,14 +551,6 @@ for (const u of units) {
         extraCss.push(`#${p.own.id}{color:${curText.color}!important;font-weight:${curText.fontWeight}!important}`);
       }
     }
-    const purpose = navMatch ? `${htitle} is part of the planned product but was not one of the screens in this branch run.` : `${htitle} opens here in the full product. It was not one of the screens in this branch run.`;
-    const block = `<div class="proto-holding-block" style="left:${area.x + pad}px;top:${top}px;width:${Math.min(area.w - area.x - pad * 2, 1100)}px">
-      <h1 class="proto-holding-title" style="font-family:'${heading?.fontFamily || model.tokens.headingFont}',sans-serif;font-size:${heading?.fontSize || model.tokens.headingSize || 28}px;font-weight:${heading?.fontWeight || 600};color:${heading?.color || model.tokens.headingColor}">${esc(htitle)}</h1>
-      <p class="proto-holding-sub">${esc(purpose)}</p>
-      <div class="proto-holding-cards">${[1, 2, 3].map((i) => `<div class="proto-holding-card"><p class="proto-holding-card-title">${esc(htitle)} ${i}</p><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">Prototype holding page · <span class="proto-clickable" data-proto-action="navigate" data-proto-target="${fileOf((states.find((s) => s.isSource) || states[0]).stateId)}">Back to ${esc((states.find((s) => s.isSource) || states[0]).title)}</span></p>
-    </div>`;
-    section.insertAdjacentHTML('beforeend', block);
     for (const n of navRows) {
       const el = document.getElementById(n.rowId) || document.getElementById(n.id);
       if (!el) continue;
@@ -379,15 +559,19 @@ for (const u of units) {
     }
     document.title = htitle;
     document.querySelector('head').insertAdjacentHTML('beforeend', `<style id="proto-extra">${extraCss.join('\n')}</style><link rel="stylesheet" href="proto.css">`);
-    const cfg = { unit: hslug, holding: true, tokens: model.tokens, contentFile: null, activeNav: navMatch?.text || null };
+    const cfg = { unit: hslug, holding: true, holdingBands: bandDeclarations, tokens: model.tokens, contentFile: null, activeNav: navMatch?.text || null };
     document.body.insertAdjacentHTML('beforeend', `<script id="proto-state" type="application/json">${JSON.stringify(cfg)}</script><script src="proto.js"></script>`);
-    fs.writeFileSync(path.join(outDir, hslug + '.html'), '<!doctype html>\n' + document.documentElement.outerHTML);
+    if (review) injectReviewFraming(document, review);
+    fs.writeFileSync(path.join(outDir, outputFile), '<!doctype html>\n' + document.documentElement.outerHTML);
   }
   console.error(`holding pages: ${usedHoldings.size}`);
 }
 
 // index -> source
-const home = fileOf((states.find((s) => s.isSource) || states[0]).stateId);
+const home = review?.entry?.file || fileOf((states.find((s) => s.isSource) || states[0]).stateId);
 fs.writeFileSync(path.join(outDir, 'index.html'), `<!doctype html><meta http-equiv="refresh" content="0;url=${home}"><a href="${home}">${home}</a>`);
-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: [...usedHoldings.entries()], 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 }, null, 1));
+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));
 console.error('counts', JSON.stringify(report.counts), 'unbound', report.unbound.length);