rcf-lite 0.28.1 → 0.28.4

package/src/view/doc-renderers/helpers.js

@@ -77,6 +77,43 @@ export function fieldList(label, items) {
   return `<section class="field-list"><h4>${escapeHtml(label)}</h4><ul>${li}</ul></section>`;
 }
 
+/**
+ * 0.28.2 (issue #235): render an array-of-object field as a HTML
+ * table with the schema-known columns. Empty columns are suppressed so
+ * schema-optional fields do not surface as blank columns. Every cell
+ * is escaped. Used by the TAD renderer for the three structured
+ * fields the TAD schema names (dataStores, coreEntities,
+ * externalSystems) so a review-surface reader sees a legible table
+ * instead of a single-line `JSON.stringify` dump.
+ *
+ * @param {string} label       section heading
+ * @param {object[]} rows       array of row objects (dropped when empty)
+ * @param {Array<{ key: string, label?: string }>} columns
+ * @returns {string}
+ */
+export function fieldObjectTable(label, rows, columns) {
+  if (!Array.isArray(rows) || rows.length === 0) return '';
+  if (!Array.isArray(columns) || columns.length === 0) return '';
+  // Drop columns that are empty across every row so a schema-optional
+  // field (`purpose`, `description`, `protocol`) does not surface as
+  // a blank column.
+  const usedColumns = columns.filter((col) => rows.some((r) => {
+    const v = r?.[col.key];
+    return v !== undefined && v !== null && String(v).length > 0;
+  }));
+  if (usedColumns.length === 0) return '';
+  const thead = usedColumns.map((c) => `<th>${escapeHtml(c.label ?? c.key)}</th>`).join('');
+  const tbody = rows.map((r) => {
+    const cells = usedColumns.map((c) => {
+      const v = r?.[c.key];
+      const text = v === undefined || v === null ? '' : String(v);
+      return `<td>${escapeHtml(text)}</td>`;
+    }).join('');
+    return `<tr>${cells}</tr>`;
+  }).join('');
+  return `<section class="field-list"><h4>${escapeHtml(label)}</h4><table class="field-table"><thead><tr>${thead}</tr></thead><tbody>${tbody}</tbody></table></section>`;
+}
+
 /**
  * Render the "Show raw JSON" disclosure block for a document.
  *
@@ -91,9 +128,9 @@ export function fieldList(label, items) {
  * @param {string} parentDocId - the enclosing doc's display id (e.g. "REQ-002")
  * @returns {string}
  */
-export function rawJsonDisclosure(raw, doc, parentDocId) {
+export function rawJsonDisclosure(raw, doc, parentDocId, idPrefix) {
   const json = raw ?? JSON.stringify(doc, null, 2);
-  const rawId = `${parentDocId ?? 'doc'}::raw`;
+  const rawId = `${idPrefix ?? ''}${parentDocId ?? 'doc'}::raw`;
   return `<details class="raw-json" data-doc-id="${escapeHtml(rawId)}"><summary>Show raw JSON</summary><pre>${escapeHtml(json)}</pre></details>`;
 }
 

package/src/view/doc-renderers/req.js

@@ -18,11 +18,19 @@ import {
  * @param {string|undefined} ctx.raw
  * @param {import('#core/errors').RcfError[]} [ctx.errors]
  * @param {string|undefined} [ctx.subdiagram]
+ * @param {string|undefined} [ctx.idPrefix] - prefix prepended to every emitted
+ *   id/anchor so the same REQ can be rendered under multiple Product Map
+ *   buckets without duplicating ids. Empty when rendered from the
+ *   Requirements tab so its anchors stay canonical.
+ * @param {boolean} [ctx.suppressRawJson] - when true, the raw-JSON disclosure
+ *   is not emitted (Product Map compact cards; the disclosure stays on
+ *   the Requirements tab). AC-17007-1 payload weight.
  * @returns {string}
  */
 export function renderReq(req, ctx) {
   if (!req) return '';
-  const anchor = anchorIdFor(req.reqId ?? 'REQ');
+  const prefix = ctx.idPrefix ?? '';
+  const anchor = `${prefix}${anchorIdFor(req.reqId ?? 'REQ')}`;
   const broken = ctx.errors?.length ? brokenBanner(ctx.errors) : '';
   const subdiagram = ctx.subdiagram
     ? `<section class="subdiagram"><h4>Slice diagram</h4><pre class="mermaid">${escapeHtml(ctx.subdiagram)}</pre></section>`
@@ -38,6 +46,6 @@ export function renderReq(req, ctx) {
   ${fieldPara('Rationale', req.rationale)}
   ${fieldList('Tags', req.tags)}
   ${subdiagram}
-  ${rawJsonDisclosure(ctx.raw, req, req.reqId)}
+  ${ctx.suppressRawJson ? '' : rawJsonDisclosure(ctx.raw, req, req.reqId, prefix)}
 </article>`.trim();
 }

package/src/view/doc-renderers/tad.js

@@ -9,10 +9,34 @@ import {
   docLinkList,
   escapeHtml,
   fieldList,
+  fieldObjectTable,
   fieldPara,
   rawJsonDisclosure,
 } from './helpers.js';
 
+// 0.28.2 (issue #235): structured fields the TAD schema explicitly
+// types as arrays of objects. Each entry maps a field-key to the
+// schema-documented column layout so `renderOptionalSections` can
+// pick a table renderer over the raw-JSON dump the pre-fix code
+// emitted. Columns follow @stravica-ai/rcf-schemas@0.6.3
+// schemas/tad.schema.json.
+const TAD_STRUCTURED_FIELDS = {
+  dataStores: [
+    { key: 'name', label: 'Name' },
+    { key: 'kind', label: 'Kind' },
+    { key: 'purpose', label: 'Purpose' },
+  ],
+  coreEntities: [
+    { key: 'name', label: 'Name' },
+    { key: 'description', label: 'Description' },
+  ],
+  externalSystems: [
+    { key: 'name', label: 'Name' },
+    { key: 'purpose', label: 'Purpose' },
+    { key: 'protocol', label: 'Protocol' },
+  ],
+};
+
 /**
  * @param {object} tad
  * @param {object} ctx
@@ -63,12 +87,49 @@ function renderOptionalSections(tad) {
   for (const [key, label] of Object.entries(named)) {
     const section = tad[key];
     if (!section || typeof section !== 'object') continue;
-    const rows = Object.entries(section).map(([k, v]) => {
-      if (typeof v === 'string') return `<dt>${escapeHtml(k)}</dt><dd>${escapeHtml(v)}</dd>`;
-      if (Array.isArray(v)) return `<dt>${escapeHtml(k)}</dt><dd>${v.map((x) => `<code>${escapeHtml(typeof x === 'object' ? JSON.stringify(x) : x)}</code>`).join(', ')}</dd>`;
-      return `<dt>${escapeHtml(k)}</dt><dd><pre>${escapeHtml(JSON.stringify(v, null, 2))}</pre></dd>`;
-    }).join('\n');
-    out.push(`<section class="field-list"><h4>${escapeHtml(label)}</h4><dl>${rows}</dl></section>`);
+    // 0.28.2 (issue #235): pull the schema-known structured fields
+    // (dataStores, coreEntities, externalSystems) out of the generic
+    // dl loop and render them as tables. The remaining scalar and
+    // array-of-string fields keep their dl treatment.
+    const structuredBlocks = [];
+    const dlEntries = [];
+    for (const [k, v] of Object.entries(section)) {
+      if (TAD_STRUCTURED_FIELDS[k] && Array.isArray(v) && v.length > 0 && v.every((x) => x && typeof x === 'object')) {
+        const table = fieldObjectTable(prettyStructuredLabel(k), v, TAD_STRUCTURED_FIELDS[k]);
+        if (table) structuredBlocks.push(table);
+        continue;
+      }
+      if (typeof v === 'string') {
+        dlEntries.push(`<dt>${escapeHtml(k)}</dt><dd>${escapeHtml(v)}</dd>`);
+        continue;
+      }
+      if (Array.isArray(v)) {
+        // Array-of-string keeps the existing inline shape. An
+        // unknown array-of-object surface falls through to a nested
+        // disclosure so it stays legible even when the schema grows
+        // a new field before this renderer knows about it.
+        if (v.every((x) => typeof x !== 'object' || x === null)) {
+          dlEntries.push(`<dt>${escapeHtml(k)}</dt><dd>${v.map((x) => `<code>${escapeHtml(typeof x === 'object' ? JSON.stringify(x) : x)}</code>`).join(', ')}</dd>`);
+        } else {
+          const items = v.map((x) => `<li><pre>${escapeHtml(JSON.stringify(x, null, 2))}</pre></li>`).join('');
+          dlEntries.push(`<dt>${escapeHtml(k)}</dt><dd><ul>${items}</ul></dd>`);
+        }
+        continue;
+      }
+      dlEntries.push(`<dt>${escapeHtml(k)}</dt><dd><pre>${escapeHtml(JSON.stringify(v, null, 2))}</pre></dd>`);
+    }
+    const dl = dlEntries.length > 0 ? `<dl>${dlEntries.join('\n')}</dl>` : '';
+    const structured = structuredBlocks.join('\n');
+    out.push(`<section class="field-list"><h4>${escapeHtml(label)}</h4>${dl}${structured}</section>`);
   }
   return out.join('\n');
 }
+
+function prettyStructuredLabel(key) {
+  const map = {
+    dataStores: 'Data stores',
+    coreEntities: 'Core entities',
+    externalSystems: 'External systems',
+  };
+  return map[key] ?? key;
+}

package/src/view/doc-renderers/user-story.js

@@ -18,13 +18,18 @@ import {
  * @param {string|undefined} ctx.raw
  * @param {import('#core/errors').RcfError[]} [ctx.errors]
  * @param {Map<string, object[]>} [ctx.fbsByAcId]
+ * @param {string|undefined} [ctx.idPrefix] - prefix prepended to every emitted
+ *   id/anchor (article, AC li items, raw-JSON disclosure) so a US rendered
+ *   under multiple Product Map buckets does not collide with the canonical
+ *   Requirements-tab anchors. Empty from the Requirements tab.
  * @returns {string}
  */
 export function renderUserStory(us, ctx) {
   if (!us) return '';
-  const anchor = anchorIdFor(us.usId ?? 'US');
+  const prefix = ctx.idPrefix ?? '';
+  const anchor = `${prefix}${anchorIdFor(us.usId ?? 'US')}`;
   const broken = ctx.errors?.length ? brokenBanner(ctx.errors) : '';
-  const acItems = (us.acceptanceCriteria ?? []).map((ac) => renderAcItem(ac, ctx)).join('\n');
+  const acItems = (us.acceptanceCriteria ?? []).map((ac) => renderAcItem(ac, ctx, prefix)).join('\n');
   return `
 <article id="${anchor}" class="doc doc-us">
   <h3>${escapeHtml(us.usId ?? 'US')} - ${escapeHtml(us.title ?? '')}</h3>
@@ -40,13 +45,13 @@ export function renderUserStory(us, ctx) {
       ${acItems}
     </ul>
   </section>
-  ${rawJsonDisclosure(ctx.raw, us, us.usId)}
+  ${ctx.suppressRawJson ? '' : rawJsonDisclosure(ctx.raw, us, us.usId, prefix)}
 </article>`.trim();
 }
 
-function renderAcItem(ac, ctx) {
+function renderAcItem(ac, ctx, prefix) {
   const acId = ac.id ?? 'AC';
-  const acAnchor = anchorIdFor(acId);
+  const acAnchor = `${prefix ?? ''}${anchorIdFor(acId)}`;
   const fbsList = ctx.fbsByAcId?.get(acId) ?? [];
   const coveredBy = fbsList.length === 0
     ? '<em>not yet delivered by any FBS</em>'

package/src/view/html-page.js

@@ -27,6 +27,7 @@ import {
 } from './doc-renderers/index.js';
 import { detailsWrap, escapeHtml } from './doc-renderers/helpers.js';
 import { allRequirementSubdiagrams } from './mermaid-diagram.js';
+import { renderProductMapPanel } from './product-map.js';
 
 // Inline SVG favicon: the Stravica kit mark (deep-navy tile with the
 // ribbon symbol in Stravica blue), taken from the estate brand kit at
@@ -74,6 +75,7 @@ export function renderPage(model) {
     <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>
@@ -119,6 +121,7 @@ export function renderContent(model) {
   const requirementsPanel = renderRequirementsPanel(model, subdiagrams);
   const architecturePanel = renderArchitecturePanel(model);
   const buildPanel = renderBuildPanel(model);
+  const productMapPanel = renderProductMapPanel(model);
 
   const errorBanner = renderErrorBanner(model.errors ?? []);
 
@@ -129,6 +132,10 @@ export function renderContent(model) {
         ${prdSection}
       </div>
     </section>
+    <section id="tab-product-map" role="tabpanel" hidden>
+      <h2 class="tab-heading">Product Map</h2>
+      ${productMapPanel}
+    </section>
     <section id="tab-requirements" role="tabpanel" hidden>
       <h2 class="tab-heading">Requirements</h2>
       ${requirementsPanel}
@@ -320,14 +327,19 @@ function renderErrorBanner(errors) {
 function inlineScript() {
   return `
 (function () {
-  var TABS = ['overview', 'requirements', 'architecture', 'build'];
+  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') {
-      // startOnLoad: false. Mermaid can't lay out diagrams inside a
-      // display:none tabpanel (getBoundingClientRect is 0x0 -> NaN
-      // transforms). We run each tab's diagrams on activation instead;
-      // runMermaidIn is idempotent via the data-processed attribute.
       window.mermaid.initialize({ startOnLoad: false, securityLevel: 'loose' });
     }
   }
@@ -338,13 +350,11 @@ function inlineScript() {
     if (pending.length === 0) return;
     try {
       window.mermaid.run({ nodes: Array.prototype.slice.call(pending) });
-    } catch (e) {
-      // Mermaid.run may throw on init errors; do not block the UI.
-    }
+    } catch (e) { /* swallow */ }
   }
 
   function tabButtons() {
-    return Array.prototype.slice.call(document.querySelectorAll('[role="tab"]'));
+    return Array.prototype.slice.call(document.querySelectorAll('nav.tabs [role="tab"]'));
   }
 
   function panelFor(name) {
@@ -399,32 +409,326 @@ function inlineScript() {
     return document.querySelector('[data-doc-id="' + id.replace(/"/g, '\\\\"') + '"]');
   }
 
-  function resolveHash(hash) {
-    if (!hash) {
-      activateTab('overview');
+  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;
+  }
+
+  function pmGroupPanel(name) {
+    return document.getElementById('pm-group-' + name);
+  }
+
+  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 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;
+  }
+
+  function currentGroup() {
+    var sel = document.querySelector('.pm-group-btn[aria-selected="true"]');
+    return sel ? sel.getAttribute('data-pm-group') : 'shape';
+  }
+
+  function currentStatus() {
+    var s = document.querySelector('.pm-status-select');
+    return s ? s.value : 'all';
+  }
+
+  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 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 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 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;
+    }
+  }
+
+  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 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);
+  }
+
+  function resolveHash(hash) {
+    if (!hash) { activateTab('overview'); return; }
     var raw = hash.charAt(0) === '#' ? hash.slice(1) : hash;
     if (raw.indexOf('tab=') === 0) {
-      activateTab(raw.slice(4));
+      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;
-    }
+    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();
-    }
+    if (target.tagName && target.tagName.toLowerCase() === 'details') target.open = true;
+    try { target.scrollIntoView({ block: 'start' }); } catch (e) { target.scrollIntoView(); }
   }
 
   function onTabClick(ev) {
@@ -432,6 +736,11 @@ function inlineScript() {
     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);
     }
@@ -439,19 +748,29 @@ function inlineScript() {
 
   function wireTabs() {
     tabButtons().forEach(function (btn) {
+      if (btn.__rcfTabWired) return;
+      btn.__rcfTabWired = true;
       btn.addEventListener('click', onTabClick);
     });
   }
 
+  var hashchangeWired = false;
   function onReady() {
     initMermaid();
     wireTabs();
+    wireProductMap();
     resolveHash(window.location.hash);
-    window.addEventListener('hashchange', function () {
-      resolveHash(window.location.hash);
-    });
+    if (!hashchangeWired) {
+      hashchangeWired = true;
+      window.addEventListener('hashchange', function () {
+        resolveHash(window.location.hash);
+      });
+    }
   }
 
+  window.rcfPage = window.rcfPage || {};
+  window.rcfPage.init = onReady;
+
   if (document.readyState === 'loading') {
     document.addEventListener('DOMContentLoaded', onReady);
   } else {