@12ui/design 0.2.28 → 0.2.30

package/prototype-kit/build.mjs

@@ -0,0 +1,393 @@
+// Assemble a clickable prototype from a branch run + model + (optional) Luna labels.
+// Usage: node build.mjs <run-dir> <inventory.json> <model.json> <labels-dir|-> <out-dir>
+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 { 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 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'));
+fs.copyFileSync(path.join(here, 'runtime/proto.css'), path.join(outDir, 'proto.css'));
+
+const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+
+// ---- state lookups
+const states = model.states;
+const byState = Object.fromEntries(states.map((s) => [s.stateId, s]));
+const invSection = (s) => inv.pages.find((p) => p.pageId === s.pageId).sections.find((x) => x.sectionId === s.sectionId);
+const isWebPage = (s) => s.surfaceType === 'web_page';
+// output unit: app states -> one file per state; web pages -> one file per page (stacked)
+const units = [];
+for (const s of states) {
+  if (isWebPage(s)) {
+    let u = units.find((x) => x.pageId === s.pageId);
+    if (!u) { u = { id: s.pageId.replace(/^p\d+-/, ''), pageId: s.pageId, file: s.file, states: [], title: s.title, isSource: s.isSource }; units.push(u); }
+    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 unitOf = (stateId) => units.find((u) => u.states.some((s) => s.stateId === stateId));
+const fileOf = (stateId) => unitOf(stateId) ? unitOf(stateId).id + '.html' : null;
+
+// ---- labels (Luna) per state
+const labels = {};
+if (labelsDir && labelsDir !== '-') for (const f of fs.readdirSync(labelsDir).filter((x) => x.endsWith('.json'))) {
+  const j = JSON.parse(fs.readFileSync(path.join(labelsDir, f), 'utf8'));
+  labels[f.replace(/\.json$/, '')] = j.actions || [];
+}
+
+// ---- holding targets: nav holdings + any Luna "holding:X"
+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'; };
+
+// ---- page docs cache
+const docCache = new Map();
+function loadDoc(file) {
+  if (!docCache.has(file)) {
+    const html = fs.readFileSync(path.join(runDir, 'pages', file), 'utf8');
+    docCache.set(file, html);
+  }
+  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 = {};
+for (const [region, can] of Object.entries(model.canonicalShell)) {
+  const s = byState[can.stateId];
+  const { document } = loadDoc(s.file);
+  const el = document.getElementById(can.containerId);
+  const css = rulesFor(styleText(document), can.containerId);
+  const ownRule = css.match(new RegExp(`#${can.containerId}\\{([^}]*)\\}`));
+  const background = ownRule ? (ownRule[1].match(/(?:^|;)background:([^;]+)/) || [])[1] : null;
+  shell[region] = { ...can, html: el.outerHTML, inner: el.innerHTML, background, css, section: invSection(s) };
+}
+
+// nav: click container for each nav text = nearest ancestor container with h <= 72 and w >= 100 (row), from canonical inventory
+function rowContainerFor(section, textId, otherTextIds, maxH = 72) {
+  const it = section.items.find((x) => x.id === textId);
+  if (!it) return null;
+  for (const cid of it.chain) {
+    const c = section.containers.find((x) => x.id === cid);
+    if (!c || c.h > maxH || c.w < 60) continue;
+    const holdsOther = section.items.some((o) => otherTextIds.includes(o.id) && o.chain.includes(cid));
+    if (holdsOther) break;
+    return c;
+  }
+  return null;
+}
+const navRows = model.nav.map((n) => {
+  const sec = shell[n.region]?.section;
+  const others = model.nav.filter((o) => o.region === n.region && o.id !== n.id).map((o) => o.id);
+  const row = sec ? rowContainerFor(sec, n.id, others) : null;
+  return { ...n, rowId: row ? row.id : n.id, row };
+});
+// active pill: in the canonical sidebar, a container with opaque bg enclosing the canonical state's own nav text
+function findPill(region) {
+  const sh = shell[region]; if (!sh) return null;
+  const own = navRows.find((n) => n.region === region && n.target && unitOf(n.target)?.id === unitOf(sh.stateId)?.id);
+  if (!own) return null;
+  const it = sh.section.items.find((x) => x.id === own.id);
+  const covers = (c) => c.x <= it.x + 1 && c.y <= it.y + 1 && c.x + c.w >= it.x + it.w - 1 && c.y + c.h >= it.y + it.h - 1;
+  const pill = sh.section.containers
+    .filter((c) => c.id !== sh.containerId && c.id.startsWith(sh.containerId) && c.h <= 80 && c.w >= 80 && covers(c) && c.bg && c.bg !== 'rgba(0, 0, 0, 0)')
+    .sort((a, b) => a.w * a.h - b.w * b.h)[0] || null;
+  return { pill, own, textColor: it.color, textWeight: it.fontWeight };
+}
+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 } };
+function resolveTarget(target, currentStateId) {
+  if (!target) return null;
+  if (/^holding:/.test(target)) return holdingFile(target.slice(8).trim());
+  if (byState[target]) {
+    if (target === currentStateId) return null;
+    if (unitOf(target) === unitOf(currentStateId)) return fileOf(target) + '#' + byState[target].sectionId;
+    return fileOf(target);
+  }
+  if (holdings.has(target)) return '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;
+}
+function actionsFor(s) {
+  const acts = new Map(); // elementId -> {action, ...}
+  const luna = labels[s.stateId] || [];
+  const lunaById = new Map(luna.map((a) => [a.id, a]));
+  const det = new Map();
+  // deterministic: dropdown triggers, rows -> dependent state, fields
+  const dependent = states.find((x) => x.dependsOn === s.stateId && unitOf(x.stateId) !== unitOf(s.stateId));
+  for (const c of s.candidates) {
+    if (c.kind === 'dropdown') det.set(c.id, { action: 'dropdown', labelId: c.textId, text: c.text });
+    if (c.kind === 'row' && dependent) det.set(c.id, { action: 'navigate', target: dependent.stateId });
+  }
+  // merge: deterministic kind wins for dropdown, Luna supplies options/targets/modals; Luna alone for the rest
+  for (const c of s.candidates) {
+    const d = det.get(c.id), l = lunaById.get(c.id) || luna.find((a) => a.id.startsWith(c.id + '-') || c.id.startsWith(a.id + '-'));
+    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 (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 || [] });
+    }
+    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') {
+      // a real follow-on state beats a Luna holding page for rows
+      const detTgt = d?.target ? fileOf(d.target) : null;
+      const lunaTgt = resolveTarget(l?.target, s.stateId);
+      const lunaReal = l?.target && byState[l.target] ? lunaTgt : null;
+      const tgt = detTgt && !lunaReal ? detTgt : (lunaTgt || detTgt);
+      if (tgt) a = { action: 'navigate', target: tgt };
+    }
+    if (a) acts.set(c.id, a);
+    else report.counts.none++;
+  }
+  return acts;
+}
+
+function bindAction(el, action) {
+  el.setAttribute('data-proto-action', action.action);
+  if (action.target) el.setAttribute('data-proto-target', action.target);
+  if (action.options) el.setAttribute('data-proto-options', JSON.stringify(action.options));
+  if (action.labelId) el.setAttribute('data-proto-label', action.labelId);
+  if (action.modal) el.setAttribute('data-proto-modal', JSON.stringify(action.modal));
+}
+
+const stateActions = new Map(states.map((state) => [state.stateId, actionsFor(state)]));
+const canonicalShellActions = {};
+for (const [region, canonical] of Object.entries(model.canonicalShell)) {
+  const state = byState[canonical.stateId];
+  const { document } = loadDoc(state.file);
+  const root = document.getElementById(canonical.containerId);
+  canonicalShellActions[region] = [...stateActions.get(state.stateId)].filter(([id]) => {
+    const element = document.getElementById(id);
+    return element && root?.contains(element);
+  });
+}
+
+// ---- build each unit
+for (const u of units) {
+  const { document } = loadDoc(u.file);
+  const keep = new Set(u.states.map((s) => s.sectionId));
+  for (const sec of [...document.querySelectorAll('section[id^="viewport-"]')]) if (/^viewport-\d+-[A-Za-z0-9]+$/.test(sec.id) && !keep.has(sec.id)) sec.remove();
+  for (const sc of [...document.querySelectorAll('script')]) sc.remove();
+  const totalH = u.states.reduce((n, s) => n + invSection(s).height, 0);
+  const extraCss = [`.ly-anchor-canvas,#page-flow{height:${totalH}px!important}`];
+  const title = u.title; document.title = title;
+  const allActions = {};
+  const content = {};
+  let fieldCount = 0;
+  const activeNav = navRows.find((n) => n.target && unitOf(n.target)?.id === u.id);
+
+  for (const s of u.states) {
+    const section = document.getElementById(s.sectionId);
+    for (const ambiguity of report.shellAmbiguities.filter((candidate) => candidate.state === s.stateId && shouldSuppressDroppedShell(candidate))) {
+      const dropped = document.getElementById(ambiguity.dropped);
+      const kept = document.getElementById(ambiguity.kept);
+      if (dropped && kept && !dropped.contains(kept) && !kept.contains(dropped)) {
+        dropped.remove();
+        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) {
+      const el = document.getElementById(id);
+      if (!el) {
+        if (s.candidates.find((candidate) => candidate.id === id)?.inShell) report.replacedShellActions++;
+        else report.unbound.push({ state: s.stateId, id, action: a.action });
+        continue;
+      }
+      bindAction(el, a);
+      report.counts[a.action]++;
+      allActions[id] = a;
+    }
+    // fields
+    for (const f of s.fields) {
+      if (acts.has(f.id)) continue;
+      if (s.fields.some((o) => o.id !== f.id && o.id.startsWith(f.id + '-'))) continue; // prefer the innermost field
+      const el = document.getElementById(f.id);
+      if (!el || el.closest('[data-proto-action]') || el.querySelector('[data-proto-action]')) continue;
+      const textEl = el.classList.contains('text') ? el
+        : [...el.querySelectorAll('.text')].find((t) => !t.closest('button'))
+        || (el.textContent.trim() && [...el.children].every((c) => !c.children.length) ? el : null);
+      if (!textEl || textEl.closest('button')) continue;
+      el.setAttribute('data-proto-field', textEl.id);
+      el.setAttribute('data-proto-submit', /search/i.test(f.id + f.placeholder) ? 'Search' : 'Send');
+      // a sibling send/submit button under the same parent submits the field
+      const parent = el.parentElement;
+      const send = parent && [...parent.querySelectorAll('button')].find((b) => /send|submit|go$|search|arrow/.test(b.id) && !b.textContent.trim());
+      // bind the button's container too: the icon often sits beside (not inside) the button and swallows the click
+      if (send) (send.parentElement && send.parentElement !== parent ? send.parentElement : send).setAttribute('data-proto-submit-for', textEl.id);
+      fieldCount++; report.counts.field++;
+    }
+    // content layer
+    for (const p of section.querySelectorAll('.text, h1, h2, h3, h4, h5, h6')) if (p.id && !p.querySelector('.text')) content[p.id] = p.textContent;
+  }
+  // Shell children come from the canonical state. Bind that state's shell actions
+  // 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);
+    if (elements.length && !allActions[id]) {
+      allActions[id] = action;
+      report.shellActionRemaps++;
+    }
+  }
+  // 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 };
+  }
+  // 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)) {
+    if (!p) continue;
+    if (!activeNav || activeNav.region !== region) {
+      // 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}`); }
+      continue;
+    }
+    if (activeNav.id === p.own.id) continue;
+    const cur = navRows.find((n) => n.id === activeNav.id);
+    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(`#${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}`);
+    // 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}`); }
+  }
+  // inject runtime
+  const head = document.querySelector('head');
+  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);
+  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 });
+  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
+{
+  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); }
+  }
+  // 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)));
+  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);
+    }
+    if (navMatch) {
+      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}`);
+      }
+    }
+    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;
+      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">`);
+    const cfg = { unit: hslug, holding: true, 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);
+  }
+  console.error(`holding pages: ${usedHoldings.size}`);
+}
+
+// index -> source
+const home = 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));
+console.error('counts', JSON.stringify(report.counts), 'unbound', report.unbound.length);

package/prototype-kit/inventory.mjs

@@ -0,0 +1,104 @@
+// Render each exported branch page and inventory every leaf element per state section.
+// Usage: node inventory.mjs <run-dir> <out.json>
+//   run-dir must hold branch.plan.json and pages/*.html
+import { chromium } from '@playwright/test';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const [runDir, outFile] = process.argv.slice(2);
+if (!runDir || !outFile) throw new Error('usage: inventory.mjs <run-dir> <out.json>');
+
+const planFile = path.join(runDir, 'branch.plan.json');
+if (!fs.existsSync(planFile)) throw new Error(`Prototype input error: missing ${planFile}`);
+let plan;
+try {
+  plan = JSON.parse(fs.readFileSync(planFile, 'utf8'));
+} catch (error) {
+  throw new Error(`Prototype input error: invalid branch.plan.json: ${error.message}`);
+}
+const planPages = Array.isArray(plan.pages) ? plan.pages : [];
+const pagesDir = path.join(runDir, 'pages');
+if (!fs.existsSync(pagesDir)) throw new Error(`Prototype input error: missing pages directory: ${pagesDir}`);
+const files = fs.readdirSync(pagesDir).filter((f) => f.endsWith('.html')).sort();
+if (!files.length) throw new Error(`Prototype input error: no exported HTML pages in ${pagesDir}`);
+
+const browser = await chromium.launch();
+const ctx = await browser.newContext({ viewport: { width: 1536, height: 1024 }, deviceScaleFactor: 1 });
+const page = await ctx.newPage();
+
+const result = { runDir, plan, pages: [] };
+
+for (const file of files) {
+  const pageId = file.replace(/\.html$/, '');
+  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 sections = await page.evaluate(() => {
+    const secs = [...document.querySelectorAll('section[id^="viewport-"]')].filter((s) => /^viewport-\d+-[A-Za-z0-9]+$/.test(s.id));
+    const out = [];
+    for (const sec of secs) {
+      const sb = sec.getBoundingClientRect();
+      const sectionStyle = getComputedStyle(sec);
+      const els = [...sec.querySelectorAll('.text, h1, h2, h3, h4, h5, h6, button, .icon, img, .divider, [class*="input"], [class*="field"]')];
+      const items = [];
+      for (const el of els) {
+        const r = el.getBoundingClientRect();
+        if (r.width === 0 || r.height === 0) continue;
+        const cs = getComputedStyle(el);
+        const chain = [];
+        let a = el.parentElement;
+        while (a && a !== sec) { if (a.id) chain.push(a.id); a = a.parentElement; }
+        const inButton = !!el.closest('button');
+        const btn = el.closest('button');
+        items.push({
+          id: el.id,
+          tag: el.tagName.toLowerCase(),
+          cls: el.className && typeof el.className === 'string' ? el.className : '',
+          text: el.tagName === 'IMG' || el.classList.contains('icon') ? '' : (el.textContent || '').replace(/\s+/g, ' ').trim(),
+          label: el.getAttribute('alt') || el.getAttribute('aria-label') || '',
+          x: Math.round((r.left - sb.left) * 10) / 10,
+          y: Math.round((r.top - sb.top) * 10) / 10,
+          w: Math.round(r.width * 10) / 10,
+          h: Math.round(r.height * 10) / 10,
+          fontSize: parseFloat(cs.fontSize) || 0,
+          fontWeight: cs.fontWeight,
+          fontFamily: cs.fontFamily.split(',')[0].replace(/["']/g, ''),
+          color: cs.color,
+          bg: cs.backgroundColor,
+          radius: cs.borderTopLeftRadius,
+          inButton,
+          buttonId: btn ? btn.id : null,
+          chain,
+        });
+      }
+      // containers: every element with an id that has children, for region analysis
+      const containers = [...sec.querySelectorAll('div[id], button[id], aside[id], header[id], footer[id], nav[id], section[id], article[id], form[id], main[id]')].map((c) => {
+        const r = c.getBoundingClientRect();
+        const cs = getComputedStyle(c);
+        return {
+          id: c.id, tag: c.tagName.toLowerCase(),
+          x: Math.round((r.left - sb.left) * 10) / 10, y: Math.round((r.top - sb.top) * 10) / 10,
+          w: Math.round(r.width * 10) / 10, h: Math.round(r.height * 10) / 10,
+          bg: cs.backgroundColor, border: cs.borderTopWidth + ' ' + cs.borderTopColor, radius: cs.borderTopLeftRadius,
+          children: c.children.length,
+        };
+      }).filter((c) => c.w > 0 && c.h > 0);
+      out.push({
+        sectionId: sec.id,
+        width: sb.width,
+        height: sb.height,
+        scriptDirection: sectionStyle.direction,
+        writingMode: sectionStyle.writingMode,
+        items,
+        containers,
+      });
+    }
+    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`);
+}
+
+await browser.close();
+fs.writeFileSync(outFile, JSON.stringify(result, null, 1));
+console.error('wrote', outFile);

package/prototype-kit/label-briefs.mjs

@@ -0,0 +1,47 @@
+// Emit one Luna labeling brief per state: candidates + destinations -> simple action schema.
+// Usage: node label-briefs.mjs <model.json> <briefs-dir>
+import fs from 'node:fs';
+import path from 'node:path';
+
+const [modelFile, outDir] = process.argv.slice(2);
+const model = JSON.parse(fs.readFileSync(modelFile, 'utf8'));
+fs.mkdirSync(outDir, { recursive: true });
+
+const destinations = model.states.map((s) => `- ${s.stateId}: "${s.title}"${s.ordinal > 1 ? ` (follow-on state ${s.ordinal})` : ''} — ${s.content || s.purpose}`).join('\n');
+const holdings = model.nav.filter((n) => n.holding).map((n) => `holding:${n.text}`);
+
+for (const s of model.states) {
+  const cands = s.candidates.filter((c) => c.kind !== 'nav' || c.inShell);
+  const list = cands.map((c) => `- id=${c.id} | kind=${c.kind} | text="${c.text}"${c.inShell ? ' | in shared chrome' : ''}`).join('\n');
+  const fields = s.fields.map((f) => `- id=${f.id} | placeholder="${f.placeholder}"`).join('\n') || '(none)';
+  const brief = `tier: luna
+You label interactive elements of ONE screen of a clickable HTML prototype. Reply with ONLY a JSON object, no prose, no markdown fences.
+
+Product: ${model.plan.sitePurpose || model.plan.concept.slice(0, 300)}
+
+Current screen: ${s.stateId} — "${s.title}". ${s.purpose} ${s.content}
+${(() => { const d = model.states.find((x) => x.dependsOn === s.stateId); return d ? `This screen has a follow-on detail state: ${d.stateId} — ${d.content}. Rows or links that open the item it describes should navigate there.` : ''; })()}
+
+Screens that exist (navigation targets):
+${destinations}
+Placeholder screens that also exist (use target exactly as written): ${holdings.join(', ') || '(none)'}
+
+Elements on the current screen:
+${list}
+
+Text fields on the current screen:
+${fields}
+
+For EVERY element id above output exactly one entry. Choose:
+- "navigate": clicking goes to another screen. target = one of the screen ids above, or one of the placeholder targets, or "holding:<Short title>" for a screen that should exist but does not. Never navigate to the current screen.
+- "dropdown": a filter/select/sort trigger. Give "options": 3-6 short plausible values; first option = the current label without a prefix like "All".
+- "modal": an action that submits, creates, runs, exports, approves, or confirms something. Give "modal": {"title": <=6 words, "body": one calm sentence in the product voice, "confirm": 1-2 word verb}.
+- "none": decorative, a heading, not really clickable, or the navigation item for the CURRENT screen.
+Rows (kind=row) and cards (kind=card, clickable card titled with the text) usually navigate to a detail screen if one exists, otherwise "holding:<Short title>" of the thing they open.
+Output schema:
+{"actions":[{"id":"<id>","action":"navigate|dropdown|modal|none","target":"<id or holding:Title>","options":["..."],"modal":{"title":"","body":"","confirm":""}}]}
+Omit keys that do not apply. Do not read or write any files. Do not run commands.
+`;
+  fs.writeFileSync(path.join(outDir, `${s.stateId}.md`), brief);
+}
+console.error(`wrote ${model.states.length} briefs to ${outDir}`);

package/prototype-kit/lib/actions.mjs

@@ -0,0 +1,15 @@
+import { normalizeText } from './text.mjs';
+
+export function usableDropdownOptions(options) {
+  if (!Array.isArray(options)) return null;
+  const unique = [];
+  const seen = new Set();
+  for (const option of options) {
+    const text = String(option || '').trim();
+    const key = normalizeText(text);
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    unique.push(text);
+  }
+  return unique.length >= 3 ? unique : null;
+}

package/prototype-kit/lib/navigation.mjs

@@ -0,0 +1,33 @@
+import { normalizeText, stemToken } from './text.mjs';
+
+function tokens(value) {
+  return new Set(normalizeText(value).split(' ').filter((token) => token.length > 2).map(stemToken));
+}
+
+function identityText(page) {
+  return [page.title, page.pageId?.replace(/^p\d+-/, '').replace(/-/g, ' '), page.stateId?.replace(/-/g, ' ')].filter(Boolean);
+}
+
+export function matchPlannedPage(text, pages) {
+  const normalized = normalizeText(text);
+  const exact = pages.filter((page) => identityText(page).some((value) => normalizeText(value) === normalized));
+  if (exact.length === 1) return exact[0];
+  if (exact.length > 1) return null;
+
+  const wanted = tokens(text);
+  if (!wanted.size) return null;
+  let bestScore = 0;
+  let best = [];
+  for (const page of pages) {
+    const available = tokens(identityText(page).join(' '));
+    const intersection = [...wanted].filter((token) => available.has(token)).length;
+    const score = intersection / Math.max(1, Math.min(wanted.size, available.size));
+    if (score > bestScore) {
+      bestScore = score;
+      best = [page];
+    } else if (score === bestScore && score > 0) {
+      best.push(page);
+    }
+  }
+  return bestScore >= 0.5 && best.length === 1 ? best[0] : null;
+}