npm - rcf-lite - Versions diffs - 0.28.4 → 0.29.0 - Mend

rcf-lite 0.28.4 → 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (168) hide show

package/CHANGELOG.md +107 -1
package/bin/rcf.js +4 -0
package/fixtures/canary-manifest.json +9 -9
package/guidance/define-draft-shapes.md +89 -0
package/guidance/define-intake.md +97 -0
package/guidance/define-intent.md +107 -0
package/guidance/discover-prototype.md +67 -0
package/guidance/discovery-prototypes.md +69 -0
package/guidance/harness-template.md +34 -0
package/guidance/managed/agent-instructions-block.hash +1 -1
package/guidance/managed/agent-instructions-block.md +34 -0
package/guidance/manifest.json +9 -2
package/package.json +1 -1
package/rcf/adrs/adr-4124-define-freeze-verb.json +30 -0
package/rcf/adrs/adr-4126-persona-tagged-blockers-two-levels.json +40 -0
package/rcf/adrs/adr-4127-readiness-tab-order-and-register.json +40 -0
package/rcf/adrs/adr-4129-questions-harness-driven-loop.json +25 -0
package/rcf/adrs/adr-4130-intake-harness-split-tool-scanned.json +20 -0
package/rcf/adrs/adr-4132-prototypes-in-discovery-as-evidence.json +20 -0
package/rcf/adrs/adr-4133-dag-dependency-depth-layout.json +40 -0
package/rcf/adrs/adr-4134-index-json-route.json +35 -0
package/rcf/adrs/adr-4135-readiness-po-register-and-adapter.json +35 -0
package/rcf/adrs/adr-4136-embedding-host-fixture.json +35 -0
package/rcf/code-nodes/cn-725.json +18 -2
package/rcf/code-nodes/cn-726.json +10 -2
package/rcf/code-nodes/cn-727.json +13 -4
package/rcf/code-nodes/cn-728.json +18 -2
package/rcf/code-nodes/cn-729.json +10 -2
package/rcf/code-nodes/cn-730.json +13 -3
package/rcf/code-nodes/cn-731.json +20 -0
package/rcf/code-nodes/cn-732.json +14 -0
package/rcf/code-nodes/cn-733.json +14 -0
package/rcf/code-nodes/cn-734.json +14 -0
package/rcf/code-nodes/cn-735.json +20 -0
package/rcf/code-nodes/cn-736.json +14 -0
package/rcf/code-nodes/cn-737.json +14 -0
package/rcf/code-nodes/cn-738.json +14 -0
package/rcf/code-nodes/cn-739.json +18 -0
package/rcf/code-nodes/cn-740.json +19 -0
package/rcf/code-nodes/cn-741.json +16 -0
package/rcf/code-nodes/cn-742.json +16 -0
package/rcf/code-nodes/cn-743.json +15 -0
package/rcf/code-nodes/cn-744.json +22 -0
package/rcf/code-nodes/cn-745.json +16 -0
package/rcf/code-nodes/cn-746.json +14 -0
package/rcf/code-nodes/cn-747.json +18 -0
package/rcf/code-nodes/cn-748.json +16 -0
package/rcf/code-nodes/cn-749.json +16 -0
package/rcf/code-nodes/cn-750.json +15 -0
package/rcf/code-nodes/cn-751.json +18 -0
package/rcf/code-nodes/cn-752.json +14 -0
package/rcf/fbs/fbs-196.json +13 -5
package/rcf/fbs/fbs-198.json +42 -0
package/rcf/fbs/fbs-199.json +59 -0
package/rcf/fbs/fbs-200.json +46 -0
package/rcf/fbs/fbs-201.json +49 -0
package/rcf/fbs/fbs-202.json +110 -0
package/rcf/fbs/fbs-203.json +100 -0
package/rcf/requirements/req-002.json +2 -2
package/rcf/requirements/req-173.json +2 -2
package/rcf/requirements/req-174.json +10 -4
package/rcf/requirements/req-175.json +10 -4
package/rcf/requirements/req-176.json +25 -0
package/rcf/requirements/req-180.json +31 -0
package/rcf/requirements/req-181.json +31 -0
package/rcf/requirements/req-182.json +25 -0
package/rcf/requirements/req-186.json +25 -0
package/rcf/requirements/req-187.json +31 -0
package/rcf/requirements/req-188.json +25 -0
package/rcf/tacs/tac-4121-define-ledgers.json +15 -3
package/rcf/tacs/tac-4122-define-gates.json +40 -4
package/rcf/tacs/tac-4123-define-readiness.json +39 -3
package/rcf/tacs/tac-4124-define-freeze.json +28 -0
package/rcf/tacs/tac-4127-readiness-view.json +49 -0
package/rcf/tacs/tac-4128-define-guidance.json +53 -0
package/rcf/tacs/tac-4129-define-questions.json +45 -0
package/rcf/tacs/tac-4130-define-intake-brief.json +35 -0
package/rcf/tacs/tac-4131-build-dag-view.json +39 -0
package/rcf/tacs/tac-4132-id-lookup.json +42 -0
package/rcf/tacs/tac-4133-readiness-po-layer.json +37 -0
package/rcf/tacs/tac-4134-wespa-host-fixture.json +54 -0
package/rcf/test-suites/ts-016.json +3 -3
package/rcf/test-suites/ts-215.json +148 -4
package/rcf/test-suites/ts-216.json +19 -3
package/rcf/test-suites/ts-218.json +78 -0
package/rcf/test-suites/ts-219.json +70 -0
package/rcf/test-suites/ts-220.json +78 -0
package/rcf/test-suites/ts-221.json +78 -0
package/rcf/test-suites/ts-222.json +100 -0
package/rcf/test-suites/ts-223.json +94 -0
package/rcf/test-suites/ts-224.json +70 -0
package/rcf/test-suites/ts-225.json +78 -0
package/rcf/test-suites/ts-226.json +158 -0
package/rcf/test-suites/ts-227.json +38 -0
package/rcf/test-suites/ts-228.json +86 -0
package/rcf/test-suites/ts-229.json +83 -0
package/rcf/user-stories/us-17302.json +50 -0
package/rcf/user-stories/us-17401.json +14 -2
package/rcf/user-stories/us-17402.json +55 -0
package/rcf/user-stories/us-17403.json +60 -0
package/rcf/user-stories/us-17502.json +60 -0
package/rcf/user-stories/us-17503.json +65 -0
package/rcf/user-stories/us-17601.json +58 -0
package/rcf/user-stories/us-18001.json +55 -0
package/rcf/user-stories/us-18002.json +35 -0
package/rcf/user-stories/us-18101.json +35 -0
package/rcf/user-stories/us-18202.json +40 -0
package/rcf/user-stories/us-18601.json +55 -0
package/rcf/user-stories/us-18602.json +50 -0
package/rcf/user-stories/us-18603.json +45 -0
package/rcf/user-stories/us-18701.json +50 -0
package/rcf/user-stories/us-18702.json +50 -0
package/rcf/user-stories/us-18801.json +45 -0
package/rcf/user-stories/us-204.json +59 -0
package/rcf/user-stories/us-205.json +64 -0
package/rcf/user-stories/us-206.json +54 -0
package/releases/releases.yaml +11 -1
package/src/cli/freeze.js +730 -0
package/src/cli/help.js +12 -0
package/src/cli/ledger.js +228 -12
package/src/cli/questions.js +288 -0
package/src/cli/readiness.js +267 -49
package/src/cli/view.js +29 -0
package/src/define/freeze-record.js +30 -15
package/src/define/ledgers.js +210 -11
package/src/intake/index.js +1 -1
package/src/intake/orchestrator.js +117 -0
package/src/mcp/tools.js +354 -0
package/src/query/delta.js +6 -0
package/src/query/gates.js +314 -39
package/src/query/index.js +16 -2
package/src/query/questions.js +438 -0
package/src/query/readiness.js +248 -7
package/src/server/index.js +24 -2
package/src/server/routes.js +68 -1
package/src/setup/identity-seed.js +17 -0
package/src/view/build-dag.js +563 -0
package/src/view/components/badge.js +41 -0
package/src/view/components/diff.js +72 -0
package/src/view/components/doc-row.js +62 -0
package/src/view/components/empty-state.js +35 -0
package/src/view/components/entity-selector.js +137 -0
package/src/view/components/filter-bar.js +97 -0
package/src/view/components/findings-list.js +49 -0
package/src/view/components/index.js +12 -0
package/src/view/components/pill.js +46 -0
package/src/view/components/sub-tab-strip.js +43 -0
package/src/view/components/toast.js +25 -0
package/src/view/components-fixture.js +265 -0
package/src/view/doc-renderers/architecture.js +304 -0
package/src/view/doc-renderers/build.js +160 -0
package/src/view/doc-renderers/index.js +2 -0
package/src/view/doc-renderers/prd.js +35 -6
package/src/view/html-page.js +700 -602
package/src/view/index.js +96 -3
package/src/view/live-client.js +39 -6
package/src/view/needs-work.js +79 -0
package/src/view/page-init.js +2193 -0
package/src/view/readiness/phrasebook.js +115 -0
package/src/view/readiness/po-layer.js +288 -0
package/src/view/readiness/question-adapter.js +329 -0
package/src/view/readiness/stage-legend.js +71 -0
package/src/view/readiness.js +505 -0
package/src/view/style.css +2017 -382
package/src/view/test-host/embed-client.js +121 -0
package/src/view/test-host/fixture.js +183 -0
package/src/view/test-host/lints.js +220 -0
package/src/view/view-index.js +323 -0

package/src/view/html-page.js CHANGED Viewed

@@ -4,30 +4,68 @@
 // drill-down under Requirements. Phase 3.6 dropped the top-of-overview
 // diagram - it was redundant with the PRD body's requirementIds list
 // and unwieldy past ~15 REQs. Overview tab now renders the PRD body
-// only. Client-side tabs + hash routing are wired by an inline script
-// at the end of `<body>`; if JS is unavailable, every tabpanel is
-// visible in DOM order (D12).
+// only. If JS is unavailable, every tabpanel is visible in DOM order (D12).
 //
 // Phase 3.8 wraps the swappable tree content in a stable
 // `<div id="rcf-live-content">` (D13a) and always injects the live
-// client script `<script src="/live-client.js" defer>` before `</body>`.
-// The tab init routine is exposed as `window.rcfPage.init()` so the
-// live client can re-invoke it after every SSE innerHTML swap.
+// client script before `</body>`. The tab init routine is exposed as
+// `window.rcfPage.init()` so the live client can re-invoke it after
+// every SSE innerHTML swap.
+//
+// Viewer UI refresh PR 1 (w-2026-10-02-dave-010, Dex / wespa relay
+// f0384046 on 2026-10-02):
+//   - compact Stravica-brand shell: data-theme light|dark|auto on
+//     <html>, data-embed=1 suppresses the brand block and the footer
+//     and keeps the tab nav sticky, viewport-height scroll box owned
+//     by <main>, never scrolls horizontally.
+//   - asset and SSE references are RELATIVE (./live-client.js,
+//     ./page-init.js, ./style.css, ./mermaid.min.js, ./product-map/,
+//     ./events, ./scope.json) so the wespa reverse-proxy mount under
+//     /rcf-viewer/ keeps working without rewrites (issue #263).
+//   - the single former inline script lives at ./page-init.js;
+//     wespa's CSP pins inline scripts by hash and we no longer have
+//     any. page-init.js carries the theme/embed boot, origin-checked
+//     postMessage listener for { type:"rcf-view-theme", theme } and
+//     the Router (#tab=&sub=&entity=, bare #REQ-002, host query
+//     preserved on every write).
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import {
   renderAdr,
-  renderBuildSequence,
-  renderFbs,
+  renderBuildPageHead,
+  renderBuildStats,
   renderPrd,
-  renderReq,
+  renderSpecBody,
   renderTac,
-  renderTad,
-  renderTestSuite,
+  renderTadSections,
   renderUserStory,
+  shortenDocId,
 } from './doc-renderers/index.js';
 import { detailsWrap, escapeHtml } from './doc-renderers/helpers.js';
+import { computeQueue } from '../build/queue.js';
 import { allRequirementSubdiagrams } from './mermaid-diagram.js';
 import { renderProductMapPanel } from './product-map.js';
+import { renderReadinessPanel } from './readiness.js';
+import { renderToastContainer } from './components/toast.js';
+import { renderDocRow } from './components/doc-row.js';
+import { renderFilterBar } from './components/filter-bar.js';
+import { renderBadge } from './components/badge.js';
+import { pill } from './components/pill.js';
+import { renderEmptyState } from './components/empty-state.js';
+import { renderEntitySelector } from './components/entity-selector.js';
+import { renderSubTabStrip } from './components/sub-tab-strip.js';
+import { buildDagLayout, buildDagInspectorPayload, renderBuildDag } from './build-dag.js';
+import { computeReqNeedsWorkIds, needsWorkReasonFor } from './needs-work.js';
+import { renderLookupModal, renderSearchButton } from './view-index.js';
+// Umbrella version stamped at module load (same pattern as src/ruleset/index.js).
+// Used by the shell footer so the muted "RCF Lite X.Y.Z" line tracks the
+// installed package without a build step.
+const pkgJsonPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+const RCF_LITE_VERSION = JSON.parse(readFileSync(pkgJsonPath, 'utf8')).version;
 // Inline SVG favicon: the Stravica kit mark (deep-navy tile with the
 // ribbon symbol in Stravica blue), taken from the estate brand kit at
@@ -47,9 +85,9 @@ const LIVE_WRAPPER_CLOSE = '</div>';
  * @returns {string}
  */
 export function renderPage(model) {
-  const projectName = model.manifest?.projectName ?? model.prd?.productName ?? 'RCF project';
+  const header = resolveProductHeader(model);
+  const projectName = header.projectName ?? 'RCF project';
   const contentHtml = renderContent(model);
-  const script = inlineScript();
   return `<!DOCTYPE html>
 <html lang="en-GB">
@@ -58,7 +96,7 @@ export function renderPage(model) {
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${escapeHtml(projectName)} - RCF review surface</title>
   <link rel="icon" type="image/svg+xml" href="${FAVICON_HREF}">
-  <link rel="stylesheet" href="style.css">
+  <link rel="stylesheet" href="./style.css">
   <noscript>
     <style>
       /* Progressive enhancement per D12: no JS -> every tabpanel is
@@ -70,29 +108,48 @@ export function renderPage(model) {
   </noscript>
 </head>
 <body>
-  <header>
-    <h1>${escapeHtml(projectName)}</h1>
-    <p class="subtitle">RCF review surface</p>
-    <nav class="tabs" role="tablist" aria-label="Document sections">
-      <button type="button" role="tab" data-tab="overview" aria-selected="true" aria-controls="tab-overview">Overview</button>
-      <button type="button" role="tab" data-tab="product-map" aria-selected="false" aria-controls="tab-product-map">Product Map</button>
-      <button type="button" role="tab" data-tab="requirements" aria-selected="false" aria-controls="tab-requirements">Requirements</button>
-      <button type="button" role="tab" data-tab="architecture" aria-selected="false" aria-controls="tab-architecture">Architecture</button>
-      <button type="button" role="tab" data-tab="build" aria-selected="false" aria-controls="tab-build">Build sequence</button>
-    </nav>
+  <header class="app-header">
+    <div class="bar">
+      <div class="brand" title="Review surface">
+        <svg class="mark" aria-hidden="true" viewBox="0 0 64 64" width="18" height="18"><rect x="0" y="0" width="64" height="64" rx="14" fill="#080F19"/><g fill="#7295FF"><path d="M38 9L17 21V32L38 20Z"/><path d="M30 27L46 36V46L30 37L23 33Z"/><path d="M46 46L25 58V47L37 40Z"/></g></svg>
+      </div>
+      ${renderProductBlock(header)}
+      <nav class="tabs" role="tablist" aria-label="Document sections">
+        <button type="button" role="tab" data-tab="readiness" aria-selected="true" aria-controls="tab-readiness">Readiness</button>
+        <button type="button" role="tab" data-tab="overview" aria-selected="false" aria-controls="tab-overview">PRD</button>
+        <button type="button" role="tab" data-tab="product-map" aria-selected="false" aria-controls="tab-product-map">Product Map</button>
+        <button type="button" role="tab" data-tab="requirements" aria-selected="false" aria-controls="tab-requirements">Requirements</button>
+        <button type="button" role="tab" data-tab="architecture" aria-selected="false" aria-controls="tab-architecture">Architecture</button>
+        <button type="button" role="tab" data-tab="build" aria-selected="false" aria-controls="tab-build">Build</button>
+      </nav>
+      <div class="tools" aria-label="Viewer tools">
+        ${renderSearchButton()}
+      </div>
+    </div>
   </header>
   <main>
     ${LIVE_WRAPPER_OPEN}
     ${contentHtml}
     ${LIVE_WRAPPER_CLOSE}
   </main>
-  <footer>
-    <p>Generated from the on-disk RCF tree at <code>rcf/</code>. Read-only; changes on disk stream to this tab automatically.</p>
-    <p>Learn more about the Requirements Confidence Framework at <a href="https://stravica.ai/rcf-methodology" target="_blank" rel="noopener">stravica.ai/rcf-methodology</a>.</p>
+  <footer class="app-footer">
+    <span class="ver">RCF Lite ${escapeHtml(RCF_LITE_VERSION)}</span>
+    <span class="sep" aria-hidden="true">&middot;</span>
+    <a href="https://github.com/Stravica/rcf-lite" target="_blank" rel="noopener">rcf-lite on GitHub</a>
+    <span class="sep" aria-hidden="true">&middot;</span>
+    <a href="https://stravica.ai/docs/rcf/" target="_blank" rel="noopener">RCF Lite docs</a>
+    <span class="sep" aria-hidden="true">&middot;</span>
+    <a href="https://stravica.ai/rcf-methodology/" target="_blank" rel="noopener">RCF method docs</a>
+    <span id="rcf-conn-pill" class="live reconnecting" role="status" aria-live="polite" title="Connecting to view server...">
+      <span class="dot" aria-hidden="true"></span>
+      <span class="label">Connecting&hellip;</span>
+    </span>
   </footer>
-  <script src="mermaid.min.js"></script>
-  <script>${script}</script>
-  <script src="/live-client.js" defer></script>
+  ${renderToastContainer()}
+  ${renderLookupModal()}
+  <script src="./mermaid.min.js"></script>
+  <script src="./page-init.js" defer></script>
+  <script src="./live-client.js" defer></script>
 </body>
 </html>
 `;
@@ -109,27 +166,40 @@ export function renderPage(model) {
  */
 export function renderContent(model) {
   const subdiagrams = allRequirementSubdiagrams(model);
+  const needsWorkIds = computeReqNeedsWorkIds(model.readiness);
   const prdSection = model.prd
     ? renderPrd(model.prd, {
       raw: model.rawById.get(model.prd.prdId),
       errors: model.errorsById.get(model.prd.prdId),
       requirementIds: model.childrenByParent.get(model.prd.prdId) ?? [],
+      suppressRequirementList: true,
+      collapsibleLists: true,
     })
     : '<p><em>No PRD on disk.</em></p>';
-  const requirementsPanel = renderRequirementsPanel(model, subdiagrams);
+  const prdSelector = renderPrdRequirementSelector(model);
+  const requirementsPanel = renderRequirementsPanel(model, subdiagrams, needsWorkIds);
   const architecturePanel = renderArchitecturePanel(model);
   const buildPanel = renderBuildPanel(model);
   const productMapPanel = renderProductMapPanel(model);
+  const readinessPanel = renderReadinessPanel(model.readiness ?? null, {
+    profile: model.profileText ?? null,
+    freezeRecord: model.freezeRecord ?? null,
+  });
   const errorBanner = renderErrorBanner(model.errors ?? []);
   return `${errorBanner}
-    <section id="tab-overview" role="tabpanel" aria-labelledby="tab-overview-button">
-      <h2 class="tab-heading">Overview</h2>
+    <section id="tab-readiness" role="tabpanel" aria-labelledby="tab-readiness-button">
+      <h2 class="tab-heading">Readiness</h2>
+      ${readinessPanel}
+    </section>
+    <section id="tab-overview" role="tabpanel" aria-labelledby="tab-overview-button" hidden>
+      <h2 class="tab-heading">PRD</h2>
       <div class="prd-body">
         ${prdSection}
+        ${prdSelector}
       </div>
     </section>
     <section id="tab-product-map" role="tabpanel" hidden>
@@ -145,48 +215,73 @@ export function renderContent(model) {
       ${architecturePanel}
     </section>
     <section id="tab-build" role="tabpanel" hidden>
-      <h2 class="tab-heading">Build sequence</h2>
+      <h2 class="tab-heading">Build</h2>
       ${buildPanel}
     </section>`;
 }
-function renderRequirementsPanel(model, subdiagrams) {
+/**
+ * Viewer UI refresh PR 3 (decision 2, decision 3, decision 14): the
+ * Requirements tab renders every REQ as a shared DocRow carrying
+ * area / US count / AC count badges and a status pill. The FilterBar
+ * above drives text / area / priority / status / Needs-work filtering;
+ * state is wired to the URL hash in page-init.js so a filtered view
+ * is a link. Each row stays closed by default; when opened it shows
+ * the renderReq body (description, rationale, tags), a nested row of
+ * user stories (with AC counts), and the slice diagram + raw JSON as
+ * their own collapsed inner details so the first-paint stays cheap.
+ *
+ * `#entity=US-304` resolves to REQ-003 and US-304: the hash router
+ * opens every ancestor <details> and the US row's data-doc-id anchor
+ * is the one the current router already walks (decision 11, PR 1).
+ *
+ * @param {import('./tree-model.js').BuiltTreeModel} model
+ * @param {Map<string, string>} subdiagrams - REQ id -> Mermaid source
+ * @param {Set<string>} needsWorkIds - REQ ids still needing PO work
+ */
+function renderRequirementsPanel(model, subdiagrams, needsWorkIds) {
   if (model.requirements.length === 0 && model.userStories.length === 0) {
-    return '<p><em>No requirements on disk.</em></p>';
-  }
-  const reqBlocks = model.requirements.map((r) => {
-    const reqBody = renderReq(r, {
-      raw: model.rawById.get(r.reqId),
-      errors: model.errorsById.get(r.reqId),
-      subdiagram: subdiagrams.get(r.reqId),
-    });
-    const stories = model.storiesByReqId.get(r.reqId) ?? [];
-    const usBlocks = stories.map((u) => detailsWrap({
-      id: u.usId,
-      summary: `${u.usId} - ${u.title ?? ''}`,
-      className: 'doc-us-wrap',
-      status: u.status,
-      body: renderUserStory(u, {
-        raw: model.rawById.get(u.usId),
-        errors: model.errorsById.get(u.usId),
-        fbsByAcId: model.fbsByAcId,
-      }),
-    })).join('\n');
-    const storiesSection = usBlocks
-      ? `<section class="nested-details"><h4>User stories</h4>${usBlocks}</section>`
-      : '<p><em>No user stories under this requirement.</em></p>';
-    return detailsWrap({
-      id: r.reqId,
-      summary: `${r.reqId} - ${r.title ?? ''}`,
-      className: 'doc-req-wrap',
-      status: r.status,
-      body: `${reqBody}\n${storiesSection}`,
+    return renderEmptyState({
+      title: 'No requirements on disk',
+      hint: 'Add requirements under rcf/requirements/ and the viewer picks them up on the next walk.',
     });
-  }).join('\n');
+  }
+  const areaCounts = countBy(model.requirements, (r) => normaliseFacet(r.domain));
+  const priorityCounts = countBy(model.requirements, (r) => normaliseFacet(r.priority));
+  const statusCounts = countBy(model.requirements, (r) => normaliseFacet(r.status));
+  const filterBar = renderFilterBar({
+    hashKey: 'requirements',
+    placeholder: 'Filter by id, title or text',
+    selects: [
+      {
+        key: 'domain',
+        label: 'Area',
+        options: [{ value: '', label: 'All areas' }, ...facetOptions(areaCounts)],
+      },
+      {
+        key: 'priority',
+        label: 'Priority',
+        options: [{ value: '', label: 'Any priority' }, ...facetOptions(priorityCounts)],
+      },
+      {
+        key: 'status',
+        label: 'Status',
+        options: [{ value: '', label: 'Any status' }, ...facetOptions(statusCounts)],
+      },
+    ],
+    toggles: [
+      { key: 'needswork', label: `Needs work (${needsWorkIds.size})` },
+    ],
+    count: { visible: model.requirements.length, total: model.requirements.length },
+    showExpandAll: true,
+  });
+  const reqRows = model.requirements.map((r) => renderRequirementRow(r, model, subdiagrams, needsWorkIds)).join('\n');
   const orphanUs = model.userStories.filter((u) => !u.reqId || !model.requirements.some((r) => r.reqId === u.reqId));
   const orphanBlock = orphanUs.length > 0
-    ? `<section class="orphan-us"><h3>Orphan user stories</h3>${orphanUs.map((u) => detailsWrap({
+    ? `<section class="orphan-us"><h3 class="group-heading">Orphan user stories</h3>${orphanUs.map((u) => detailsWrap({
       id: u.usId,
       summary: `${u.usId} - ${u.title ?? ''}`,
       className: 'doc-us-wrap',
@@ -199,583 +294,586 @@ function renderRequirementsPanel(model, subdiagrams) {
     })).join('\n')}</section>`
     : '';
-  return `${reqBlocks}\n${orphanBlock}`;
+  return `${filterBar}
+<div class="rcf-requirements-list" data-rcf-list="requirements">
+${reqRows}
+</div>
+${orphanBlock}`;
 }
-function renderArchitecturePanel(model) {
-  const tadChildren = model.tad ? (model.childrenByParent.get(model.tad.tadId) ?? []) : [];
-  const componentIds = tadChildren.filter((id) => id.startsWith('TAC-'));
-  const architecturalDecisionIds = tadChildren.filter((id) => id.startsWith('ADR-'));
-  const tadSection = model.tad
-    ? renderTad(model.tad, {
-      raw: model.rawById.get(model.tad.tadId),
-      errors: model.errorsById.get(model.tad.tadId),
-      componentIds,
-      architecturalDecisionIds,
-    })
-    : '<p><em>No TAD on disk.</em></p>';
-  const tacBlocks = model.tacs.map((t) => detailsWrap({
-    id: t.tacId,
-    summary: `${t.tacId} - ${t.name ?? ''}`,
-    className: 'doc-tac-wrap',
-    status: t.status,
-    body: renderTac(t, {
-      raw: model.rawById.get(t.tacId),
-      errors: model.errorsById.get(t.tacId),
-    }),
-  })).join('\n');
-  const adrBlocks = model.adrs.map((a) => detailsWrap({
-    id: a.adrId,
-    summary: `${a.adrId} - ${a.title ?? ''}`,
-    className: 'doc-adr-wrap',
-    status: a.status,
-    body: renderAdr(a, {
-      raw: model.rawById.get(a.adrId),
-      errors: model.errorsById.get(a.adrId),
-    }),
-  })).join('\n');
-  return `
-${tadSection}
-<h3 class="group-heading">Components</h3>
-${tacBlocks || '<p><em>No TAC components on disk.</em></p>'}
-<h3 class="group-heading">Architectural decisions</h3>
-${adrBlocks || '<p><em>No ADRs on disk.</em></p>'}
-`;
-}
+function renderRequirementRow(req, model, subdiagrams, needsWorkIds) {
+  const stories = model.storiesByReqId.get(req.reqId) ?? [];
+  const acCount = stories.reduce((n, u) => n + (u.acceptanceCriteria?.length ?? 0), 0);
+  const area = normaliseFacet(req.domain);
+  const priority = normaliseFacet(req.priority);
+  const status = normaliseFacet(req.status);
+  const needsWork = needsWorkIds.has(req.reqId);
+  const needsWorkReason = needsWork ? (needsWorkReasonFor(model.readiness, req.reqId) ?? 'needs engineer-ready detail') : '';
+  const metaParts = [];
+  if (area) metaParts.push(renderBadge({ value: area, variant: 'facet', title: 'Area' }));
+  metaParts.push(renderBadge({ value: stories.length, label: 'US', variant: 'count', title: 'User stories' }));
+  metaParts.push(renderBadge({ value: acCount, label: 'AC', variant: 'count', title: 'Acceptance criteria' }));
+  if (status) metaParts.push(pill({ value: status, variant: 'doc-status' }));
+  if (needsWork) metaParts.push(renderBadge({ value: 'needs work', variant: 'accent', title: needsWorkReason }));
+  const meta = metaParts.join(' ');
+  const usRows = stories.map((u) => renderUserStoryInnerRow(u, model)).join('\n');
+  const storiesBlock = stories.length > 0
+    ? `<section class="rcf-req-stories"><h4>User stories (${stories.length})</h4>${usRows}</section>`
+    : '<p class="muted"><em>No user stories under this requirement yet.</em></p>';
+  const description = typeof req.description === 'string' && req.description.length > 0
+    ? `<p class="rcf-req-description">${escapeHtml(req.description)}</p>`
+    : '';
+  const rationale = typeof req.rationale === 'string' && req.rationale.length > 0
+    ? `<p class="rcf-req-rationale muted"><strong>Why:</strong> ${escapeHtml(req.rationale)}</p>`
+    : '';
+  const tags = Array.isArray(req.tags) && req.tags.length > 0
+    ? `<div class="rcf-req-tags">${req.tags.map((t) => renderBadge({ value: t, variant: 'facet' })).join(' ')}</div>`
+    : '';
+  const needsWorkLine = needsWork
+    ? `<p class="rcf-req-needswork"><strong>Needs work:</strong> ${escapeHtml(needsWorkReason)}</p>`
+    : '';
-function renderBuildPanel(model) {
-  const bsSlots = model.bs
-    ? [...model.fbsItems]
-      .filter((f) => f.bsId === model.bs.bsId)
-      .sort((a, b) => (a.buildOrder ?? 0) - (b.buildOrder ?? 0))
-      .map((f) => ({
-        fbsId: f.fbsId,
-        buildOrder: f.buildOrder,
-        executionStatus: f.executionStatus,
-        title: f.title,
-      }))
-    : [];
-  const bsSection = model.bs
-    ? renderBuildSequence(model.bs, {
-      raw: model.rawById.get(model.bs.bsId),
-      errors: model.errorsById.get(model.bs.bsId),
-      slots: bsSlots,
-    })
-    : '<p><em>No build sequence on disk.</em></p>';
-  const fbsBlocks = model.fbsItems.map((f) => detailsWrap({
-    id: f.fbsId,
-    summary: `${f.fbsId} - ${f.title ?? ''}`,
-    className: 'doc-fbs-wrap',
-    status: f.executionStatus,
-    body: renderFbs(f, {
-      raw: model.rawById.get(f.fbsId),
-      errors: model.errorsById.get(f.fbsId),
-      usByAcId: model.usByAcId,
-    }),
-  })).join('\n');
-  const tsBlocks = model.testSuites.map((ts) => detailsWrap({
-    id: ts.id,
-    summary: `${ts.id} - ${ts.title ?? 'test suite'}`,
-    className: 'doc-ts-wrap',
-    status: ts.status,
-    body: renderTestSuite(ts, {
-      raw: model.rawById.get(ts.id),
-      errors: model.errorsById.get(ts.id),
-    }),
-  })).join('\n');
-  const tsSection = tsBlocks
-    ? `<h3 class="group-heading">Test suites</h3>${tsBlocks}`
+  const subdiagram = subdiagrams.get(req.reqId);
+  const sliceDetails = subdiagram
+    ? `<details class="rcf-req-slice"><summary>Slice diagram <span class="muted small">(REQ, stories, criteria and the FBS that deliver them)</span></summary><div class="rcf-req-slice-body"><pre class="mermaid">${escapeHtml(subdiagram)}</pre></div></details>`
     : '';
-  return `
-${bsSection}
-<h3 class="group-heading">Functional Build Specifications</h3>
-${fbsBlocks || '<p><em>No FBS items on disk.</em></p>'}
-${tsSection}
-`;
+  const rawJson = model.rawById.get(req.reqId) ?? JSON.stringify(req, null, 2);
+  const rawDetails = `<details class="rcf-req-raw raw-json" data-doc-id="${escapeHtml(req.reqId)}::raw"><summary class="muted small">Raw JSON</summary><pre>${escapeHtml(rawJson)}</pre></details>`;
+  const body = `${needsWorkLine}${description}${rationale}${tags}${storiesBlock}${sliceDetails}${rawDetails}`;
+  const extraClasses = ['doc-req-wrap'];
+  if (needsWork) extraClasses.push('needs-work');
+  const row = renderDocRow({
+    id: req.reqId,
+    title: req.title ?? '',
+    body,
+    meta,
+    className: extraClasses.join(' '),
+  });
+  // Attach the filter-facet data attributes to the <details> opening
+  // tag so page-init.js can hide / show rows without touching the body.
+  const dataAttrs = ` data-domain="${escapeHtml(area)}" data-priority="${escapeHtml(priority)}" data-status="${escapeHtml(status)}" data-needswork="${needsWork ? '1' : '0'}" data-text="${escapeHtml(buildFilterText(req, stories))}"`;
+  return row.replace(/^<details /, `<details${dataAttrs} `);
 }
-function renderErrorBanner(errors) {
-  if (!errors || errors.length === 0) return '';
-  const count = errors.length;
-  const noun = count === 1 ? 'error' : 'errors';
-  const items = errors.slice(0, 20).map((e) => {
-    const label = e.documentId ? `${e.documentId}` : e.filePath ?? '';
-    return `<li><strong>${escapeHtml(e.kind)}</strong> ${escapeHtml(label)} - ${escapeHtml(e.message)}</li>`;
-  }).join('');
-  const more = count > 20 ? `<p><em>... and ${count - 20} more</em></p>` : '';
-  return `<aside class="tree-errors" role="alert">
-  <h2>Tree has ${count} ${noun}</h2>
-  <ul>${items}</ul>
-  ${more}
-</aside>`;
+function renderUserStoryInnerRow(us, model) {
+  const acCount = us.acceptanceCriteria?.length ?? 0;
+  const status = normaliseFacet(us.status);
+  const metaParts = [renderBadge({ value: acCount, label: 'AC', variant: 'count', title: 'Acceptance criteria' })];
+  if (status) metaParts.push(pill({ value: status, variant: 'doc-status' }));
+  const body = renderUserStory(us, {
+    raw: model.rawById.get(us.usId),
+    errors: model.errorsById.get(us.usId),
+    fbsByAcId: model.fbsByAcId,
+  });
+  return renderDocRow({
+    id: us.usId,
+    title: us.title ?? '',
+    body,
+    meta: metaParts.join(' '),
+    className: 'doc-us-wrap rcf-row--inner',
+  });
 }
-// Inline client-side script: initialises Mermaid, wires tab switching,
-// resolves hash routes to a tab + opens any ancestor `<details>` on the
-// target. Vanilla; no dependencies beyond the vendored Mermaid loaded above.
-// Phase 3.8 note: this script is byte-identical to the Phase 3.6 shape
-// (the layout-regression test guards it). Live-swap recovery lives
-// entirely in `src/view/live-client.js`, which reads state from the DOM
-// after each SSE innerHTML swap - it does not call into this IIFE.
-function inlineScript() {
-  return `
-(function () {
-  var TABS = ['overview', 'requirements', 'architecture', 'build', 'product-map'];
-  var PM_GROUPS = ['shape', 'component', 'trace', 'capability', 'blueprint'];
-  var PM_STATUSES = ['all', 'draft', 'review', 'needsRevision', 'approved', 'superseded'];
-  // Partial-render cache: grouping -> HTML string. First fetch fills it,
-  // subsequent switches use the cache.
-  var pmPartialCache = {};
-  // Track whether an SSE swap has invalidated the cache since the last
-  // successful hydration - the live-client sets window.__rcfPmDirty
-  // after each swap, and we clear the cache on the next activation.
-  function pmCacheKey(group) { return group; }
-  function initMermaid() {
-    if (typeof window.mermaid !== 'undefined') {
-      window.mermaid.initialize({ startOnLoad: false, securityLevel: 'loose' });
-    }
+function buildFilterText(req, stories) {
+  const parts = [req.reqId, req.title, req.description, req.rationale, req.domain, req.priority, req.status];
+  if (Array.isArray(req.tags)) parts.push(req.tags.join(' '));
+  for (const u of stories) {
+    parts.push(u.usId, u.title, u.asA, u.iWant, u.soThat);
   }
+  return parts.filter((v) => typeof v === 'string' && v.length > 0).join(' ').toLowerCase();
+}
-  function runMermaidIn(container) {
-    if (!container || typeof window.mermaid === 'undefined') return;
-    var pending = container.querySelectorAll('.mermaid:not([data-processed="true"])');
-    if (pending.length === 0) return;
-    try {
-      window.mermaid.run({ nodes: Array.prototype.slice.call(pending) });
-    } catch (e) { /* swallow */ }
-  }
+function normaliseFacet(v) {
+  if (typeof v !== 'string') return '';
+  return v.trim();
+}
-  function tabButtons() {
-    return Array.prototype.slice.call(document.querySelectorAll('nav.tabs [role="tab"]'));
+function countBy(items, keyFn) {
+  const out = new Map();
+  for (const it of items) {
+    const k = keyFn(it);
+    if (!k) continue;
+    out.set(k, (out.get(k) ?? 0) + 1);
   }
+  return out;
+}
-  function panelFor(name) {
-    return document.getElementById('tab-' + name);
-  }
+function facetOptions(counts) {
+  const entries = [...counts.entries()];
+  entries.sort((a, b) => (b[1] - a[1]) || a[0].localeCompare(b[0]));
+  return entries.map(([value, count]) => ({ value, label: `${value} (${count})` }));
+}
-  function activateTab(name) {
-    if (TABS.indexOf(name) === -1) return false;
-    tabButtons().forEach(function (btn) {
-      var isTarget = btn.getAttribute('data-tab') === name;
-      btn.setAttribute('aria-selected', isTarget ? 'true' : 'false');
-    });
-    TABS.forEach(function (t) {
-      var p = panelFor(t);
-      if (!p) return;
-      if (t === name) {
-        p.removeAttribute('hidden');
-        runMermaidIn(p);
-      } else {
-        p.setAttribute('hidden', '');
-      }
+/**
+ * Viewer UI refresh PR 3 (decision 4): the PRD tab replaces the 109
+ * inline requirement links with an EntitySelector. Area chips deep-link
+ * into the Requirements tab filtered by domain. The jump input picks
+ * one REQ by id or title and writes `#tab=requirements&entity=<id>`.
+ *
+ * @param {import('./tree-model.js').BuiltTreeModel} model
+ */
+function renderPrdRequirementSelector(model) {
+  const reqs = model.requirements ?? [];
+  if (reqs.length === 0) return '';
+  const items = reqs.map((r) => ({
+    id: r.reqId,
+    title: r.title ?? '',
+    facet: normaliseFacet(r.domain),
+  }));
+  const areaCounts = countBy(reqs, (r) => normaliseFacet(r.domain));
+  const facets = [...areaCounts.entries()]
+    .sort((a, b) => (b[1] - a[1]) || a[0].localeCompare(b[0]))
+    .map(([value, count]) => ({ value, count }));
+  const acTotal = (model.userStories ?? []).reduce((n, u) => n + (u.acceptanceCriteria?.length ?? 0), 0);
+  const totalLabel = `${reqs.length} requirements in ${facets.length} area${facets.length === 1 ? '' : 's'}, ${model.userStories.length} stories, ${acTotal} acceptance criteria`;
+  const selector = renderEntitySelector({
+    hashKey: 'requirements',
+    targetTab: 'requirements',
+    facetKey: 'domain',
+    items,
+    facets,
+    totalLabel,
+    placeholder: `Jump to a requirement by id or title (e.g. REQ-040 or 'readiness')`,
+    chipsLabel: 'By area (click to open the Requirements tab filtered):',
+  });
+  return `<section class="rcf-prd-requirements" id="prd-requirements">
+    <div class="rcf-prd-requirements-head">
+      <h3>Requirements</h3>
+      <a class="rcf-prd-requirements-open" href="#tab=requirements">Open the Requirements tab</a>
+    </div>
+    ${selector}
+  </section>`;
+}
+/**
+ * Viewer UI refresh PR 4 (w-2026-10-02-dave-010 decisions 5 and 14,
+ * design doc section 5.5). The Architecture tab renders:
+ *   1. A compact page-head carrying the TAD id, its status pill and
+ *      the TAC / ADR tallies.
+ *   2. The TAD as six collapsed sections with one-line previews; an
+ *      absent section reads "Nothing written yet" and names the
+ *      `rcf define update TAD-001 --set <section>.<field>="..."` call
+ *      that authors it (decision 5).
+ *   3. Components (TAC) as a FilterBar + a shared DocRow list; rows
+ *      carry interface and dependency counts and a status pill. Long
+ *      ids are shortened on the summary; the full id stays on
+ *      data-doc-id and the title.
+ *   4. Architectural decisions (ADR) as a FilterBar + a shared DocRow
+ *      list; rows carry a status pill. Long ids shortened the same way.
+ *
+ * The tab never points at Readiness (amendment 12.4) - absence of
+ * content is handled inside this tab's own register.
+ */
+function renderArchitecturePanel(model) {
+  const pageHead = renderArchitecturePageHead(model);
+  const tadSection = model.tad
+    ? renderTadSections(model.tad)
+    : renderEmptyState({
+      title: 'No TAD on disk',
+      hint: 'Add rcf/tad.json and the viewer picks it up on the next walk.',
     });
-    return true;
-  }
-  function tabForNode(node) {
-    var cur = node;
-    while (cur && cur !== document.body) {
-      if (cur.getAttribute && cur.getAttribute('role') === 'tabpanel') {
-        var id = cur.id || '';
-        if (id.indexOf('tab-') === 0) return id.slice(4);
-      }
-      cur = cur.parentNode;
-    }
-    return null;
-  }
+  const tacPanel = renderComponentsPanel(model);
+  const adrPanel = renderDecisionsPanel(model);
-  function openAncestorDetails(node) {
-    var cur = node.parentNode;
-    while (cur && cur !== document.body) {
-      if (cur.tagName && cur.tagName.toLowerCase() === 'details') {
-        cur.open = true;
-      }
-      cur = cur.parentNode;
-    }
-  }
+  // Raw JSON for the whole TAD stays reachable but out of the first
+  // paint - the design doc deliberately drops "the long prose dump".
+  const rawTadDisclosure = model.tad
+    ? `<details class="rcf-tad-raw" data-doc-id="${escapeHtml(model.tad.tadId)}::raw"><summary class="muted small">Raw TAD JSON</summary><pre>${escapeHtml(model.rawById.get(model.tad.tadId) ?? JSON.stringify(model.tad, null, 2))}</pre></details>`
+    : '';
-  function findByDocId(id) {
-    if (!id) return null;
-    var byId = document.getElementById(id);
-    if (byId) return byId;
-    return document.querySelector('[data-doc-id="' + id.replace(/"/g, '\\\\"') + '"]');
-  }
+  // Hidden anchors so #TAD-001 / #entity=TAD-001 still land on this tab.
+  const tadAnchor = model.tad
+    ? `<span class="rcf-tad-anchor" data-doc-id="${escapeHtml(model.tad.tadId)}" aria-hidden="true"></span>`
+    : '';
-  function parseHashParams(raw) {
-    var out = {};
-    if (!raw) return out;
-    var parts = raw.split('&');
-    for (var i = 0; i < parts.length; i += 1) {
-      var eq = parts[i].indexOf('=');
-      if (eq === -1) continue;
-      var k = parts[i].slice(0, eq);
-      var v = parts[i].slice(eq + 1);
-      if (k) out[k] = v;
-    }
-    return out;
-  }
+  return `
+${tadAnchor}
+${pageHead}
+<section class="rcf-architecture-tad" aria-labelledby="arch-tad-heading">
+  <h3 id="arch-tad-heading" class="group-heading rcf-tad-group-heading">Technical architecture (TAD)</h3>
+  ${tadSection}
+  ${rawTadDisclosure}
+</section>
+${tacPanel}
+${adrPanel}
+`;
+}
-  function pmGroupPanel(name) {
-    return document.getElementById('pm-group-' + name);
+function renderArchitecturePageHead(model) {
+  if (!model.tad) {
+    return `<div class="rcf-architecture-head"><h3 class="rcf-architecture-head-title">Architecture</h3></div>`;
   }
+  const status = normaliseFacet(model.tad.status);
+  const statusPill = status ? pill({ value: status, variant: 'doc-status' }) : '';
+  const tacCount = (model.tacs ?? []).length;
+  const adrCount = (model.adrs ?? []).length;
+  return `<div class="rcf-architecture-head">
+    <span class="rcf-architecture-head-id mono">${escapeHtml(model.tad.tadId)}</span>
+    ${statusPill}
+    <span class="muted small">${tacCount} component${tacCount === 1 ? '' : 's'} - ${adrCount} decision${adrCount === 1 ? '' : 's'}</span>
+  </div>`;
+}
-  function hydrateLazyGroup(name, cb) {
-    var panel = pmGroupPanel(name);
-    if (!panel) { if (cb) cb(false); return; }
-    if (panel.getAttribute('data-pm-lazy') !== 'true' && !pmPartialCache[pmCacheKey(name)]) {
-      if (cb) cb(true);
-      return;
-    }
-    if (window.__rcfPmDirty) {
-      pmPartialCache = {};
-      window.__rcfPmDirty = false;
-    }
-    var cached = pmPartialCache[pmCacheKey(name)];
-    var heading = panel.querySelector('.pm-group-heading');
-    var headingHtml = heading ? heading.outerHTML : '';
-    if (cached) {
-      panel.innerHTML = headingHtml + cached;
-      panel.removeAttribute('data-pm-lazy');
-      wireProductMapWithin(panel);
-      if (cb) cb(true);
-      return;
-    }
-    // Show a lightweight loading state.
-    panel.setAttribute('data-pm-loading', 'true');
-    var xhr = new XMLHttpRequest();
-    xhr.open('GET', '/product-map/' + name, true);
-    xhr.onreadystatechange = function () {
-      if (xhr.readyState !== 4) return;
-      panel.removeAttribute('data-pm-loading');
-      if (xhr.status >= 200 && xhr.status < 300) {
-        pmPartialCache[pmCacheKey(name)] = xhr.responseText;
-        panel.innerHTML = headingHtml + xhr.responseText;
-        panel.removeAttribute('data-pm-lazy');
-        wireProductMapWithin(panel);
-        if (cb) cb(true);
-      } else {
-        panel.setAttribute('data-pm-lazy', 'true');
-        if (cb) cb(false);
-      }
-    };
-    xhr.send();
-  }
+function renderComponentsPanel(model) {
+  const tacs = model.tacs ?? [];
+  const statusCounts = countBy(tacs, (t) => normaliseFacet(t.status));
+  const filterBar = renderFilterBar({
+    hashKey: 'architecture-components',
+    placeholder: 'Filter components by id or text',
+    selects: [
+      {
+        key: 'status',
+        label: 'Status',
+        options: [{ value: '', label: 'Any status' }, ...facetOptions(statusCounts)],
+      },
+    ],
+    count: { visible: tacs.length, total: tacs.length },
+    showExpandAll: true,
+  });
+  const rows = tacs.map((t) => renderTacRow(t, model)).join('\n');
+  const emptyMessage = tacs.length === 0
+    ? renderEmptyState({ title: 'No TAC components on disk', hint: 'Add rcf/tacs/<file>.json files and the viewer picks them up.' })
+    : '';
-  function activatePmGroup(name, opts) {
-    if (PM_GROUPS.indexOf(name) === -1) return false;
-    var buttons = document.querySelectorAll('.pm-group-btn');
-    for (var i = 0; i < buttons.length; i += 1) {
-      var btn = buttons[i];
-      var isTarget = btn.getAttribute('data-pm-group') === name;
-      btn.setAttribute('aria-selected', isTarget ? 'true' : 'false');
-    }
-    var panels = document.querySelectorAll('.pm-group');
-    for (var j = 0; j < panels.length; j += 1) {
-      var p = panels[j];
-      if (p.getAttribute('data-pm-group') === name) {
-        p.removeAttribute('hidden');
-      } else {
-        p.setAttribute('hidden', '');
-      }
-    }
-    var target = pmGroupPanel(name);
-    if (target && target.getAttribute('data-pm-lazy') === 'true') {
-      hydrateLazyGroup(name, function () {
-        if (opts && opts.after) opts.after();
-        applyPmStatusFilter(currentStatus());
-      });
-    } else {
-      if (opts && opts.after) opts.after();
-      applyPmStatusFilter(currentStatus());
-    }
-    return true;
-  }
+  return `<section class="rcf-architecture-components" aria-labelledby="arch-tac-heading">
+  <h3 id="arch-tac-heading" class="group-heading">Components</h3>
+  ${filterBar}
+  <div class="rcf-tac-list" data-rcf-list="architecture-components">
+    ${rows}
+  </div>
+  ${emptyMessage}
+</section>`;
+}
-  function currentGroup() {
-    var sel = document.querySelector('.pm-group-btn[aria-selected="true"]');
-    return sel ? sel.getAttribute('data-pm-group') : 'shape';
-  }
+function renderDecisionsPanel(model) {
+  const adrs = model.adrs ?? [];
+  const statusCounts = countBy(adrs, (a) => normaliseFacet(a.status));
+  const filterBar = renderFilterBar({
+    hashKey: 'architecture-decisions',
+    placeholder: 'Filter decisions by id or text',
+    selects: [
+      {
+        key: 'status',
+        label: 'Status',
+        options: [{ value: '', label: 'Any status' }, ...facetOptions(statusCounts)],
+      },
+    ],
+    count: { visible: adrs.length, total: adrs.length },
+    showExpandAll: true,
+  });
+  const rows = adrs.map((a) => renderAdrRow(a, model)).join('\n');
+  const emptyMessage = adrs.length === 0
+    ? renderEmptyState({ title: 'No architectural decisions on disk', hint: 'Add rcf/adrs/<file>.json files and the viewer picks them up.' })
+    : '';
-  function currentStatus() {
-    var s = document.querySelector('.pm-status-select');
-    return s ? s.value : 'all';
-  }
+  return `<section class="rcf-architecture-decisions" aria-labelledby="arch-adr-heading">
+  <h3 id="arch-adr-heading" class="group-heading">Architectural decisions</h3>
+  ${filterBar}
+  <div class="rcf-adr-list" data-rcf-list="architecture-decisions">
+    ${rows}
+  </div>
+  ${emptyMessage}
+</section>`;
+}
-  function currentOpenBuckets() {
-    var group = currentGroup();
-    var panel = pmGroupPanel(group);
-    if (!panel) return [];
-    var nodes = panel.querySelectorAll('details.pm-bucket[open]');
-    var out = [];
-    for (var i = 0; i < nodes.length; i += 1) {
-      var id = nodes[i].getAttribute('data-pm-bucket-id');
-      if (id) out.push(id);
-    }
-    return out;
-  }
+function renderTacRow(tac, model) {
+  const id = tac.tacId ?? 'TAC';
+  const displayId = shortenDocId(id);
+  const title = tac.name ?? '';
+  const interfaceCount = Array.isArray(tac.interfaces) ? tac.interfaces.length : 0;
+  const depCount = Array.isArray(tac.dependencies) ? tac.dependencies.length : 0;
+  const status = normaliseFacet(tac.status);
+  const metaParts = [
+    renderBadge({ value: interfaceCount, label: 'interfaces', variant: 'count', title: 'Interface count' }),
+    renderBadge({ value: depCount, label: 'deps', variant: 'count', title: 'Dependency count' }),
+  ];
+  if (status) metaParts.push(pill({ value: status, variant: 'doc-status' }));
+  const meta = metaParts.join(' ');
+  const body = renderTac(tac, {
+    raw: model.rawById.get(id),
+    errors: model.errorsById.get(id),
+  });
+  const row = renderDocRow({
+    id: displayId,
+    title,
+    body,
+    meta,
+    className: 'doc-tac-wrap rcf-arch-row',
+    dataDocId: id,
+  });
+  const dataAttrs = ` data-status="${escapeHtml(status)}" data-text="${escapeHtml(buildTacFilterText(tac))}" title="${escapeHtml(id)}"`;
+  return row.replace(/^<details /, `<details${dataAttrs} `);
+}
-  function applyPmStatusFilter(status) {
-    if (PM_STATUSES.indexOf(status) === -1) return false;
-    var select = document.querySelector('.pm-status-select');
-    if (select) select.value = status;
-    var reqCards = document.querySelectorAll('#tab-product-map [data-req-status]');
-    for (var i = 0; i < reqCards.length; i += 1) {
-      var card = reqCards[i];
-      var s = card.getAttribute('data-req-status') || '';
-      if (status === 'all' || s === status) {
-        card.removeAttribute('hidden');
-      } else {
-        card.setAttribute('hidden', '');
-      }
-    }
-    // Per AC-17002-1: empty buckets under the filter are HIDDEN by
-    // default with a "N empty" summary line to reveal them. Also keep
-    // the legacy in-bucket note for tests / no-JS accessibility.
-    var buckets = document.querySelectorAll('#tab-product-map .pm-group:not([hidden]) details.pm-bucket');
-    var emptyCount = 0;
-    for (var k = 0; k < buckets.length; k += 1) {
-      var bk = buckets[k];
-      var visible = bk.querySelectorAll('[data-req-status]:not([hidden])');
-      var bodyEmpty = bk.querySelector('.pm-bucket-body') && bk.querySelector('.pm-bucket-body').children.length === 0;
-      var isEmpty = visible.length === 0 && !bodyEmpty; // lazy-empty buckets don't count
-      var body = bk.querySelector('.pm-bucket-body');
-      var emptyNote = body ? body.querySelector('.pm-bucket-empty-filter') : null;
-      if (isEmpty && status !== 'all') {
-        if (body && !emptyNote) {
-          emptyNote = document.createElement('p');
-          emptyNote.className = 'pm-bucket-empty pm-bucket-empty-filter';
-          emptyNote.innerHTML = '<em>0 requirements match this filter.</em>';
-          body.appendChild(emptyNote);
-        }
-        bk.setAttribute('data-pm-empty-under-filter', 'true');
-        emptyCount += 1;
-      } else {
-        if (emptyNote) emptyNote.parentNode.removeChild(emptyNote);
-        bk.removeAttribute('data-pm-empty-under-filter');
-      }
-    }
-    // Update the rollup summary.
-    var activePanel = document.querySelector('#tab-product-map .pm-group:not([hidden])');
-    if (activePanel) {
-      var roll = activePanel.querySelector('.pm-empty-roll');
-      if (roll) {
-        var showBtn = roll.querySelector('.pm-empty-count');
-        if (emptyCount > 0 && status !== 'all') {
-          if (showBtn) showBtn.textContent = String(emptyCount);
-          roll.removeAttribute('hidden');
-          activePanel.classList.add('pm-hide-empty');
-        } else {
-          roll.setAttribute('hidden', '');
-          activePanel.classList.remove('pm-hide-empty');
-        }
-      }
-    }
-    return true;
-  }
+function renderAdrRow(adr, model) {
+  const id = adr.adrId ?? 'ADR';
+  const displayId = shortenDocId(id);
+  const title = adr.title ?? '';
+  const status = normaliseFacet(adr.status);
+  const metaParts = [];
+  if (status) metaParts.push(pill({ value: status, variant: 'doc-status' }));
+  const meta = metaParts.join(' ');
+  const body = renderAdr(adr, {
+    raw: model.rawById.get(id),
+    errors: model.errorsById.get(id),
+  });
+  const row = renderDocRow({
+    id: displayId,
+    title,
+    body,
+    meta,
+    className: 'doc-adr-wrap rcf-arch-row',
+    dataDocId: id,
+  });
+  const dataAttrs = ` data-status="${escapeHtml(status)}" data-text="${escapeHtml(buildAdrFilterText(adr))}" title="${escapeHtml(id)}"`;
+  return row.replace(/^<details /, `<details${dataAttrs} `);
+}
-  function updatePmHash() {
-    if (!window.history || typeof window.history.pushState !== 'function') return;
-    var group = currentGroup();
-    var status = currentStatus();
-    var open = currentOpenBuckets();
-    var next = '#tab=product-map&group=' + group + '&status=' + status;
-    if (open.length > 0) next += '&open=' + encodeURIComponent(open.join(','));
-    if (window.location.hash === next) return;
-    window.history.pushState(null, '', next);
+function buildTacFilterText(tac) {
+  const parts = [tac.tacId, tac.name, tac.purpose, tac.internalStructure, tac.notes, tac.tradeoffs];
+  if (Array.isArray(tac.responsibilities)) parts.push(tac.responsibilities.join(' '));
+  if (Array.isArray(tac.interfaces)) {
+    for (const i of tac.interfaces) parts.push(i?.name, i?.description);
   }
-  function openPmBuckets(ids) {
-    if (!ids || ids.length === 0) return;
-    var group = currentGroup();
-    var panel = pmGroupPanel(group);
-    if (!panel) return;
-    for (var i = 0; i < ids.length; i += 1) {
-      var raw = ids[i];
-      if (!raw) continue;
-      var node = panel.querySelector('details.pm-bucket[data-pm-bucket-id="' + raw.replace(/"/g, '\\"') + '"]');
-      if (node) node.open = true;
-    }
+  if (Array.isArray(tac.dependencies)) {
+    for (const d of tac.dependencies) parts.push(d?.name, d?.description);
   }
+  return parts.filter((v) => typeof v === 'string' && v.length > 0).join(' ').toLowerCase();
+}
-  function wireProductMapWithin(root) {
-    root = root || document;
-    // Bucket toggle -> push hash on user toggle. The 'toggle' event
-    // fires for both open and close, from user action and from our own
-    // scripting; guard against feedback via a dirty flag.
-    var buckets = root.querySelectorAll('details.pm-bucket');
-    for (var i = 0; i < buckets.length; i += 1) {
-      var bk = buckets[i];
-      if (bk.__rcfPmBucketWired) continue;
-      bk.__rcfPmBucketWired = true;
-      bk.addEventListener('toggle', function () {
-        if (window.__rcfPmSuppress) return;
-        updatePmHash();
-      });
-    }
-    // Jump chip -> open bucket + scroll.
-    var chips = root.querySelectorAll('.pm-jump-chip');
-    for (var j = 0; j < chips.length; j += 1) {
-      var chip = chips[j];
-      if (chip.__rcfPmChipWired) continue;
-      chip.__rcfPmChipWired = true;
-      chip.addEventListener('click', function (ev) {
-        var target = ev.currentTarget.getAttribute('data-pm-jump');
-        var groupAttr = ev.currentTarget.closest('.pm-jump-nav').getAttribute('data-pm-jump-group');
-        var panel = pmGroupPanel(groupAttr);
-        if (!panel) return;
-        var node = panel.querySelector('details.pm-bucket[data-pm-bucket-id="' + target.replace(/"/g, '\\"') + '"]');
-        if (!node) return;
-        node.open = true;
-        try { node.scrollIntoView({ block: 'start' }); } catch (e) { node.scrollIntoView(); }
-      });
-    }
-    // Bulk expand/collapse.
-    var bulk = root.querySelectorAll('.pm-bulk-btn');
-    for (var b = 0; b < bulk.length; b += 1) {
-      var btn = bulk[b];
-      if (btn.__rcfPmBulkWired) continue;
-      btn.__rcfPmBulkWired = true;
-      btn.addEventListener('click', function (ev) {
-        var action = ev.currentTarget.getAttribute('data-pm-bulk');
-        var panel = document.querySelector('#tab-product-map .pm-group:not([hidden])');
-        if (!panel) return;
-        var all = panel.querySelectorAll('details.pm-bucket');
-        window.__rcfPmSuppress = true;
-        for (var i = 0; i < all.length; i += 1) all[i].open = (action === 'expand');
-        window.__rcfPmSuppress = false;
-        updatePmHash();
-      });
-    }
-    // Empty-roll toggle: reveals hidden empty buckets under the filter.
-    var rolls = root.querySelectorAll('.pm-empty-toggle');
-    for (var r = 0; r < rolls.length; r += 1) {
-      var rt = rolls[r];
-      if (rt.__rcfPmEmptyWired) continue;
-      rt.__rcfPmEmptyWired = true;
-      rt.addEventListener('click', function (ev) {
-        var panel = ev.currentTarget.closest('.pm-group');
-        if (!panel) return;
-        if (panel.classList.contains('pm-hide-empty')) {
-          panel.classList.remove('pm-hide-empty');
-          ev.currentTarget.textContent = 'Hide empty buckets';
-        } else {
-          panel.classList.add('pm-hide-empty');
-          var span = document.createElement('span');
-          span.className = 'pm-empty-count';
-          span.textContent = String(panel.querySelectorAll('details.pm-bucket[data-pm-empty-under-filter="true"]').length);
-          ev.currentTarget.textContent = '';
-          ev.currentTarget.appendChild(document.createTextNode('Show '));
-          ev.currentTarget.appendChild(span);
-          ev.currentTarget.appendChild(document.createTextNode(' empty buckets'));
-        }
-      });
-    }
+function buildAdrFilterText(adr) {
+  const parts = [adr.adrId, adr.title, adr.status, adr.context, adr.decision, adr.consequences];
+  if (Array.isArray(adr.alternativesConsidered)) {
+    for (const a of adr.alternativesConsidered) parts.push(a?.name, a?.summary, a?.reasonNotChosen);
   }
+  return parts.filter((v) => typeof v === 'string' && v.length > 0).join(' ').toLowerCase();
+}
-  function wireProductMap() {
-    var buttons = document.querySelectorAll('.pm-group-btn');
-    for (var i = 0; i < buttons.length; i += 1) {
-      if (buttons[i].__rcfPmWired) continue;
-      buttons[i].__rcfPmWired = true;
-      buttons[i].addEventListener('click', function (ev) {
-        var name = ev.currentTarget.getAttribute('data-pm-group');
-        if (activatePmGroup(name)) updatePmHash();
-      });
-    }
-    var select = document.querySelector('.pm-status-select');
-    if (select && !select.__rcfPmWired) {
-      select.__rcfPmWired = true;
-      select.addEventListener('change', function () {
-        applyPmStatusFilter(select.value);
-        updatePmHash();
-      });
-    }
-    wireProductMapWithin(document);
+/**
+ * Viewer UI refresh PR 5 (w-2026-10-02-dave-010 decisions 2, 3, 6, 12,
+ * 14; design doc section 5.6). The Build tab renders:
+ *
+ *   1. BuildStats card: totals from `computeQueue` (items, verified,
+ *      complete, inProgress, notStarted, buildable now). "Buildable now"
+ *      equals `queue.totals.actionable` - the authoritative state the
+ *      queue computes from `dependsOnFbsIds` and `executionStatus`.
+ *   2. SubTabStrip Specs | DAG (decision 6 + decision 12). The DAG
+ *      sub-panel (PR 6) lays FBS by `dependsOnFbsIds` depth with
+ *      click-to-highlight closure, an inspector and the unconnected
+ *      lane; `renderBuildDag` emits the full panel HTML string from
+ *      `buildDagLayout(fbsItems, buildableIds)`.
+ *   3. Specs sub-tab: FilterBar (text, status, area, size, Buildable-now
+ *      toggle) over a shared DocRow list; row meta carries order, AC
+ *      count, deps count, size, buildable pill, status.
+ *   4. Expanded Spec row body: summary, approach, AC and dep links,
+ *      deliverables, context links, Show in the DAG.
+ *
+ * Dropped from the old Build sequence tab: the FBS slots block (the
+ * 87-row list was repetition of the specs below) and the Test suites
+ * section (suites stay reachable through AC links and PR 7's ID
+ * lookup).
+ *
+ * @param {import('./tree-model.js').BuiltTreeModel} model
+ */
+function renderBuildPanel(model) {
+  const fbsItems = Array.isArray(model.fbsItems) ? model.fbsItems : [];
+  if (fbsItems.length === 0 && !model.bs) {
+    return renderEmptyState({
+      title: 'No build specifications on disk',
+      hint: 'Add rcf/fbs/<file>.json entries and the viewer picks them up on the next walk.',
+    });
   }
+  const queue = computeQueue({ fbsItems });
+  const buildableIds = new Set(
+    queue.items.filter((i) => i.state === 'actionable').map((i) => i.fbsId),
+  );
+  const stats = {
+    items: queue.totals.items,
+    verified: queue.totals.verified,
+    complete: queue.totals.complete,
+    inProgress: queue.totals.inProgress,
+    notStarted: queue.totals.notStarted,
+    buildableNow: queue.totals.actionable,
+  };
+  const buildStats = renderBuildStats(stats);
+  const pageHead = renderBuildPageHead(model.bs);
+  const subTabs = renderSubTabStrip({
+    hashKey: 'build',
+    items: [
+      { key: 'specs', label: 'Specs', controls: 'build-sub-specs' },
+      { key: 'dag', label: 'DAG', controls: 'build-sub-dag' },
+    ],
+  });
+  const specsPanel = renderBuildSpecsPanel(model, fbsItems, buildableIds);
+  const dagLayout = buildDagLayout(fbsItems, buildableIds);
+  const dagPanel = renderBuildDag({ layout: dagLayout, inspectorPayload: buildDagInspectorPayload(dagLayout) });
+  // Hidden anchor so #BS-001 / #entity=BS-001 still resolve to this tab.
+  const bsAnchor = model.bs
+    ? `<span class="rcf-build-anchor" data-doc-id="${escapeHtml(model.bs.bsId)}" aria-hidden="true"></span>`
+    : '';
-  function resolveHash(hash) {
-    if (!hash) { activateTab('overview'); return; }
-    var raw = hash.charAt(0) === '#' ? hash.slice(1) : hash;
-    if (raw.indexOf('tab=') === 0) {
-      var afterTab = raw.slice(4);
-      var amp = afterTab.indexOf('&');
-      var tab = amp === -1 ? afterTab : afterTab.slice(0, amp);
-      var rest = amp === -1 ? '' : afterTab.slice(amp + 1);
-      activateTab(tab);
-      if (tab === 'product-map') {
-        var params = parseHashParams(rest);
-        var openIds = params.open ? decodeURIComponent(params.open).split(',').filter(Boolean) : [];
-        activatePmGroup(params.group || 'shape', {
-          after: function () {
-            if (params.status) applyPmStatusFilter(params.status);
-            openPmBuckets(openIds);
-          },
-        });
-      }
-      return;
-    }
-    var target = findByDocId(raw);
-    if (!target) { activateTab('overview'); return; }
-    var tab = tabForNode(target);
-    if (tab) activateTab(tab);
-    openAncestorDetails(target);
-    if (target.tagName && target.tagName.toLowerCase() === 'details') target.open = true;
-    try { target.scrollIntoView({ block: 'start' }); } catch (e) { target.scrollIntoView(); }
-  }
+  return `${bsAnchor}
+${pageHead}
+${buildStats}
+${subTabs}
+<section id="build-sub-specs" class="rcf-build-subpanel" data-rcf-subpanel="specs">
+${specsPanel}
+</section>
+<section id="build-sub-dag" class="rcf-build-subpanel" data-rcf-subpanel="dag" hidden>
+${dagPanel}
+</section>`;
+}
-  function onTabClick(ev) {
-    var btn = ev.currentTarget;
-    var name = btn.getAttribute('data-tab');
-    if (!name) return;
-    activateTab(name);
-    if (name === 'product-map') {
-      // Hydrate whichever grouping was selected last (default: shape).
-      // No-op when the grouping is already inline.
-      activatePmGroup(currentGroup());
-    }
-    if (window.history && typeof window.history.replaceState === 'function') {
-      window.history.replaceState(null, '', '#tab=' + name);
-    }
-  }
+function renderBuildSpecsPanel(model, fbsItems, buildableIds) {
+  const sorted = [...fbsItems].sort((a, b) => (a.buildOrder ?? 0) - (b.buildOrder ?? 0));
+  const statusCounts = countBy(sorted, (f) => normaliseFacet(f.executionStatus));
+  const areaCounts = countBy(sorted, (f) => normaliseFacet(f.domain));
+  const sizeCounts = countBy(sorted, (f) => normaliseFacet(f.estimatedSize));
+  const filterBar = renderFilterBar({
+    hashKey: 'build-specs',
+    placeholder: 'Filter specs by id or title',
+    selects: [
+      {
+        key: 'status',
+        label: 'Status',
+        options: [{ value: '', label: 'Any status' }, ...facetOptions(statusCounts)],
+      },
+      {
+        key: 'domain',
+        label: 'Area',
+        options: [{ value: '', label: 'All areas' }, ...facetOptions(areaCounts)],
+      },
+      {
+        key: 'size',
+        label: 'Size',
+        options: [{ value: '', label: 'Any size' }, ...facetOptions(sizeCounts)],
+      },
+    ],
+    toggles: [
+      { key: 'buildable', label: `Buildable now (${buildableIds.size})` },
+    ],
+    count: { visible: sorted.length, total: sorted.length },
+    showExpandAll: true,
+  });
+  const rows = sorted.map((f) => renderSpecRow(f, model, buildableIds)).join('\n');
+  return `${filterBar}
+<div class="rcf-build-specs-list" data-rcf-list="build-specs">
+${rows}
+</div>`;
+}
-  function wireTabs() {
-    tabButtons().forEach(function (btn) {
-      if (btn.__rcfTabWired) return;
-      btn.__rcfTabWired = true;
-      btn.addEventListener('click', onTabClick);
-    });
+function renderSpecRow(fbs, model, buildableIds) {
+  const id = fbs.fbsId ?? 'FBS';
+  const title = fbs.title ?? '';
+  const order = typeof fbs.buildOrder === 'number' ? fbs.buildOrder : '';
+  const acCount = Array.isArray(fbs.acIds) ? fbs.acIds.length : 0;
+  const depCount = Array.isArray(fbs.dependsOnFbsIds) ? fbs.dependsOnFbsIds.length : 0;
+  const depTitle = Array.isArray(fbs.dependsOnFbsIds) ? fbs.dependsOnFbsIds.join(', ') : '';
+  const area = normaliseFacet(fbs.domain);
+  const size = normaliseFacet(fbs.estimatedSize);
+  const status = normaliseFacet(fbs.executionStatus);
+  const buildable = buildableIds.has(id);
+  const metaParts = [];
+  if (area) metaParts.push(renderBadge({ value: area, variant: 'facet', title: 'Area' }));
+  metaParts.push(renderBadge({ value: acCount, label: 'AC', variant: 'count', title: 'Acceptance criteria' }));
+  if (depCount > 0) {
+    metaParts.push(renderBadge({ value: depCount, label: 'deps', variant: 'count', title: depTitle || 'Dependency count' }));
   }
+  if (size) metaParts.push(renderBadge({ value: size, variant: 'facet', title: 'Estimated size' }));
+  if (buildable) metaParts.push(pill({ value: 'buildable', variant: 'build-queue', title: 'No unmet dependencies' }));
+  if (status) metaParts.push(pill({ value: status, variant: 'doc-status' }));
+  const meta = metaParts.join(' ');
+  const idPrefix = order !== '' ? `<span class="rcf-spec-order mono muted small" title="Build order">${escapeHtml(String(order))}</span>` : '';
+  const displayIdHtml = `${idPrefix}<span class="rcf-spec-id mono">${escapeHtml(id)}</span>`;
+  const body = renderSpecBody(fbs, model, model.rawById?.get(id));
+  // DocRow HTML-escapes the id arg; a sentinel string lets us swap in
+  // live markup (order chip beside the mono id) after the row renders.
+  const sentinel = '__RCF_SPEC_ID__';
+  const row = renderDocRow({
+    id: sentinel,
+    title,
+    body,
+    meta,
+    className: 'doc-fbs-wrap rcf-build-row',
+    dataDocId: id,
+  });
+  const dataAttrs = ` data-status="${escapeHtml(status)}" data-domain="${escapeHtml(area)}" data-size="${escapeHtml(size)}" data-buildable="${buildable ? '1' : '0'}" data-text="${escapeHtml(buildSpecFilterText(fbs))}" title="${escapeHtml(id)}"`;
+  return row
+    .replace(/^<details /, `<details${dataAttrs} `)
+    .replace(sentinel, displayIdHtml);
+}
-  var hashchangeWired = false;
-  function onReady() {
-    initMermaid();
-    wireTabs();
-    wireProductMap();
-    resolveHash(window.location.hash);
-    if (!hashchangeWired) {
-      hashchangeWired = true;
-      window.addEventListener('hashchange', function () {
-        resolveHash(window.location.hash);
-      });
-    }
-  }
+function buildSpecFilterText(fbs) {
+  const parts = [fbs.fbsId, fbs.title, fbs.summary, fbs.approach, fbs.domain, fbs.estimatedSize, fbs.executionStatus];
+  if (Array.isArray(fbs.deliverables)) parts.push(fbs.deliverables.join(' '));
+  if (Array.isArray(fbs.acIds)) parts.push(fbs.acIds.join(' '));
+  if (Array.isArray(fbs.dependsOnFbsIds)) parts.push(fbs.dependsOnFbsIds.join(' '));
+  return parts.filter((v) => typeof v === 'string' && v.length > 0).join(' ').toLowerCase();
+}
-  window.rcfPage = window.rcfPage || {};
-  window.rcfPage.init = onReady;
+/**
+ * Viewer UI refresh PR 2 (shell polish, Baz 2026-10-02; decision 17):
+ * the one-bar header carries the project name only. The project name
+ * is sourced from `manifest.projectName`, then `prd.productName`,
+ * then `prd.productTitle` (the PRD title the brief names). Decision 17
+ * is explicit: project name prominent after the icon mark, tool name
+ * out of the bar, no technology chip. When the tree exposes no
+ * project name, the whole product block collapses and the brand icon
+ * stands on its own (silent empty state; CSS `.product:empty { display:none; }`).
+ *
+ * @param {import('./tree-model.js').BuiltTreeModel} model
+ * @returns {{ projectName: string | null }}
+ */
+export function resolveProductHeader(model) {
+  const projectName = model.manifest?.projectName
+    ?? model.prd?.productName
+    ?? model.prd?.productTitle
+    ?? null;
+  return { projectName };
+}
-  if (document.readyState === 'loading') {
-    document.addEventListener('DOMContentLoaded', onReady);
-  } else {
-    onReady();
+function renderProductBlock(header) {
+  if (!header.projectName) {
+    // No project name: collapse. The empty .product block is hidden
+    // by CSS so the brand icon stands on its own and PR 2's silent
+    // empty state (brief) survives screen-reader output too.
+    return '<div class="product"></div>';
   }
-})();
-`.trim();
+  return `<div class="product"><span class="name">${escapeHtml(header.projectName)}</span>
+        <span class="sub">review surface</span></div>`;
+}
+function renderErrorBanner(errors) {
+  if (!errors || errors.length === 0) return '';
+  const count = errors.length;
+  const noun = count === 1 ? 'error' : 'errors';
+  const items = errors.slice(0, 20).map((e) => {
+    const label = e.documentId ? `${e.documentId}` : e.filePath ?? '';
+    return `<li><strong>${escapeHtml(e.kind)}</strong> ${escapeHtml(label)} - ${escapeHtml(e.message)}</li>`;
+  }).join('');
+  const more = count > 20 ? `<p><em>... and ${count - 20} more</em></p>` : '';
+  return `<aside class="tree-errors" role="alert">
+  <h2>Tree has ${count} ${noun}</h2>
+  <ul>${items}</ul>
+  ${more}
+</aside>`;
 }