@transitrix/diagrams 1.0.0

package/src/webview/render-goals.ts

@@ -0,0 +1,110 @@
+/**
+ * Browser-safe SVG renderer for the canonical Goals notation.
+ *
+ * Step 3 of the IntelliJ epic (ADR 0001): the webview bundle must turn a
+ * validated GoalTree into renderable SVG so JCEF can drop it into the preview
+ * panel. The VS Code path lives in `extension/src/goals-preview.ts` and pulls
+ * in VS Code-specific concerns (themes, title block, save dialogs); this
+ * module is the host-neutral subset — pure layout → SVG with no VS Code APIs,
+ * no `node:fs`, no `node:path`.
+ *
+ * Step 4 will follow the same shape for the remaining ten notations.
+ */
+import { layoutGoalTree } from '../goals/layout.js';
+import type { GoalTree, GoalTreeLayout, LaidOutEdge } from '../goals/types.js';
+import { horizontalCubicEdgePath, DEFAULT_EDGE_CURVATURE } from '../edge-path.js';
+import { generateSvgEmbedCss } from '../theme/index.js';
+
+const NODE_W = 250;
+const NODE_H = 60;
+const RANK_SEP = 100;
+const NODE_SEP = 24;
+const PAD = 24;
+const LABEL_MAX = 36;
+const LABEL_TRIM = 34;
+
+function escXml(s: string): string {
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+export interface RenderGoalsOptions {
+  treeName?: string;
+  curvature?: number;
+}
+
+export function renderGoalsSvg(tree: GoalTree, options: RenderGoalsOptions = {}): string {
+  const { treeName = '', curvature = DEFAULT_EDGE_CURVATURE } = options;
+
+  const layout: GoalTreeLayout = layoutGoalTree(tree, {
+    nodeWidth: NODE_W,
+    nodeHeight: NODE_H,
+    rankSep: RANK_SEP,
+    nodeSep: NODE_SEP,
+  });
+
+  if (layout.nodes.length === 0) {
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="0" height="0" viewBox="0 0 0 0"></svg>`;
+  }
+
+  const w = layout.bounds.width + PAD * 2;
+  const h = layout.bounds.height + PAD * 2;
+  const ox = -layout.bounds.x + PAD;
+  const oy = -layout.bounds.y + PAD;
+
+  const nodeMap = new Map(layout.nodes.map((n) => [n.id, n]));
+
+  function edgePath(e: LaidOutEdge): string {
+    const s = nodeMap.get(e.source);
+    const t = nodeMap.get(e.target);
+    if (!s || !t) return '';
+    const sx = s.x + ox + s.width;
+    const sy = s.y + oy + s.height / 2;
+    const tx = t.x + ox;
+    const ty = t.y + oy + t.height / 2;
+    return horizontalCubicEdgePath(sx, sy, tx, ty, curvature);
+  }
+
+  const edgeSvg = layout.edges
+    .map((e) => `<path d="${edgePath(e)}" class="diagram-edge" marker-end="url(#arrow)"/>`)
+    .join('\n');
+
+  const nodeSvg = layout.nodes
+    .map((n) => {
+      const x = n.x + ox;
+      const y = n.y + oy;
+      const level = n.data.level % 8;
+      const labelText = n.data.name ?? String(n.id);
+      const label = labelText.length > LABEL_MAX ? labelText.slice(0, LABEL_TRIM) + '…' : labelText;
+      return `<g>
+  <rect class="diagram-node level-${level}" x="${x}" y="${y}" width="${n.width}" height="${n.height}" rx="8"/>
+  <text class="text-primary" x="${x + n.width / 2}" y="${y + n.height / 2}" text-anchor="middle" dominant-baseline="central">${escXml(label)}</text>
+</g>`;
+    })
+    .join('\n');
+
+  const titleSvg = treeName
+    ? `<text class="text-header" x="${PAD}" y="${PAD - 6}">${escXml(`Goal tree — ${treeName}`)}</text>`
+    : '';
+
+  // Embed the shared theme CSS inside the SVG so the rendered output is
+  // self-contained — the JCEF host page only needs to drop the SVG into the
+  // DOM and styling resolves without any cooperation from the host stylesheet.
+  // Matches what the VS Code path produces via `prepareSvgForExport`.
+  const embedCss = generateSvgEmbedCss('transitrix');
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">
+<style>${embedCss}</style>
+<defs>
+  <marker id="arrow" markerWidth="8" markerHeight="8" refX="8" refY="3" orient="auto">
+    <path d="M0,0 L0,6 L8,3 z" class="arrow-fill"/>
+  </marker>
+</defs>
+${titleSvg}
+${nodeSvg}
+${edgeSvg}
+</svg>`;
+}

package/src/webview/render-process-blueprint.ts

@@ -0,0 +1,207 @@
+/**
+ * Host-neutral SVG renderer for the Process Blueprint notation.
+ *
+ * Step 4 of the IntelliJ epic (ADR 0001): ported from the pure SVG core of
+ * `extension/src/process-blueprint-preview.ts` (`layoutToSvg`). The VS Code
+ * title block (`svg-title-block.ts`) is intentionally dropped — JCEF has no
+ * VS Code APIs — and replaced with `render-goals.ts`' simple optional
+ * `<text class="text-header">` heading. No `vscode`, no `node:*`, no host APIs;
+ * the shared theme CSS is embedded inside the `<svg>` so the output is
+ * self-contained.
+ */
+import { layoutProcessBlueprint } from '../process-blueprint/layout.js';
+import type {
+  ComplianceChip,
+  ProcessBlueprintFile,
+  ProcessBlueprintLayout,
+} from '../process-blueprint/types.js';
+import { generateSvgEmbedCss } from '../theme/index.js';
+import { escXml } from './render-util.js';
+
+const PAD = 24;
+
+function truncate(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  return text.slice(0, Math.max(0, maxChars - 1)) + '…';
+}
+
+/**
+ * Render a left-anchored, vertically centred multi-line text cell. `lines` are
+ * pre-wrapped by the layout; the block is centred within the cell height.
+ */
+function textCellSvg(
+  lines: string[],
+  cls: string,
+  x: number,
+  cellTop: number,
+  cellHeight: number,
+  lineHeight: number,
+): string {
+  const ls = lines.length > 0 ? lines : [''];
+  const first = cellTop + cellHeight / 2 - ((ls.length - 1) / 2) * lineHeight;
+  const tspans = ls
+    .map((ln, i) => `<tspan x="${x}" y="${first + i * lineHeight}">${escXml(ln)}</tspan>`)
+    .join('');
+  return `<text class="${cls}" dominant-baseline="central">${tspans}</text>`;
+}
+
+/**
+ * Render a single compliance law chip.
+ *
+ * Three orthogonal decorations are expressed as SVG overrides:
+ * - `new`      — dashed stroke border  (`stroke-dasharray="4 2"`)
+ * - `gap`      — warning-level fill    (`class="…compliance-gap"`)
+ * - `deadline` — urgent fill override  (`class="…compliance-deadline"`) + a small
+ *                badge circle in the top-right corner
+ */
+function complianceChipSvg(chip: ComplianceChip, ox: number, oy: number): string {
+  const { x, y, width, height, lawId, decorations } = chip;
+  const ax = x + ox;
+  const ay = y + oy;
+  const rx = 6;
+  const hasNew = decorations.includes('new');
+  const hasGap = decorations.includes('gap');
+  const hasDeadline = decorations.includes('deadline');
+
+  let rectClass = 'diagram-node level-5 compliance-chip';
+  if (hasDeadline) rectClass += ' compliance-deadline';
+  else if (hasGap) rectClass += ' compliance-gap';
+
+  const strokeDash = hasNew ? ' stroke-dasharray="4 2"' : '';
+  const parts: string[] = [];
+  parts.push(
+    `<rect class="${rectClass}" x="${ax}" y="${ay}" width="${width}" height="${height}" rx="${rx}"${strokeDash}/>`,
+  );
+  parts.push(
+    `<text class="text-pill" x="${ax + width / 2}" y="${ay + height / 2}" text-anchor="middle" dominant-baseline="central">${escXml(truncate(lawId, Math.floor(width / 8)))}</text>`,
+  );
+  if (hasDeadline) {
+    const br = 5;
+    const bx = ax + width - br - 3;
+    const by = ay + br + 3;
+    parts.push(`<circle class="compliance-badge" cx="${bx}" cy="${by}" r="${br}"/>`);
+    parts.push(
+      `<text class="compliance-badge-text" x="${bx}" y="${by}" text-anchor="middle" dominant-baseline="central">!</text>`,
+    );
+  }
+  return parts.join('\n');
+}
+
+export interface RenderProcessBlueprintOptions {
+  title?: string;
+}
+
+export function renderProcessBlueprintSvg(
+  doc: ProcessBlueprintFile,
+  options: RenderProcessBlueprintOptions = {},
+): string {
+  const { title = '' } = options;
+
+  const layout: ProcessBlueprintLayout = layoutProcessBlueprint(doc);
+
+  if (layout.bounds.width === 0 || layout.bounds.height === 0) {
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="0" height="0" viewBox="0 0 0 0"></svg>`;
+  }
+
+  const titleH = title ? PAD : 0;
+  const w = layout.bounds.width + PAD * 2;
+  const h = layout.bounds.height + PAD * 2 + titleH;
+  const ox = PAD;
+  const oy = PAD + titleH;
+
+  const parts: string[] = [];
+
+  parts.push(
+    `<rect class="diagram-node level-0" x="${ox}" y="${oy}" width="${layout.bounds.width}" height="${layout.bounds.height}" rx="6"/>`,
+  );
+
+  for (const s of layout.stageHeaders) {
+    parts.push(
+      `<rect class="diagram-node level-1" x="${s.x + ox}" y="${s.y + oy}" width="${s.width}" height="${s.height}"/>`,
+    );
+    parts.push(
+      `<text class="text-header" x="${s.x + ox + s.width / 2}" y="${s.y + oy + s.height / 2}" text-anchor="middle" dominant-baseline="central">${escXml(truncate(s.name, 28))}</text>`,
+    );
+  }
+
+  for (const l of layout.legend) {
+    parts.push(
+      `<rect class="diagram-node level-2" x="${ox}" y="${l.y + oy}" width="${layout.legendColumnWidth}" height="${l.height}"/>`,
+    );
+    parts.push(
+      `<text class="text-primary" x="${ox + 12}" y="${l.y + oy + l.height / 2}" dominant-baseline="central">${escXml(l.label)}</text>`,
+    );
+  }
+
+  const textX = layout.cellTextPadX;
+  for (const c of layout.goalCells) {
+    parts.push(
+      `<rect class="diagram-node level-3" x="${c.x + ox}" y="${c.y + oy}" width="${c.width}" height="${c.height}"/>`,
+    );
+    parts.push(
+      textCellSvg(c.lines, 'text-secondary', c.x + ox + textX, c.y + oy, c.height, layout.textLineHeight),
+    );
+  }
+  for (const c of layout.resultCells) {
+    parts.push(
+      `<rect class="diagram-node level-4" x="${c.x + ox}" y="${c.y + oy}" width="${c.width}" height="${c.height}"/>`,
+    );
+    parts.push(
+      textCellSvg(c.lines, 'text-secondary', c.x + ox + textX, c.y + oy, c.height, layout.textLineHeight),
+    );
+  }
+
+  for (let r = 0; r < layout.aspectRows.length; r++) {
+    const row = layout.aspectRows[r];
+    const level = 5 + (r % 3);
+    parts.push(
+      `<rect class="diagram-node level-${level}" x="${layout.legendColumnWidth + ox}" y="${row.y + oy}" width="${layout.bounds.width - layout.legendColumnWidth}" height="${row.height}" opacity="0.15"/>`,
+    );
+    for (let i = 1; i < layout.stageHeaders.length; i++) {
+      const x = layout.legendColumnWidth + i * layout.stageColumnWidth + ox;
+      parts.push(
+        `<line class="diagram-edge" x1="${x}" y1="${row.y + oy}" x2="${x}" y2="${row.y + row.height + oy}" opacity="0.3"/>`,
+      );
+    }
+    for (const p of row.pills) {
+      parts.push(
+        `<rect class="diagram-node level-${level}" x="${p.x + ox}" y="${p.y + oy}" width="${p.width}" height="${p.height}" rx="6"/>`,
+      );
+      const label = p.id ? `${p.name} · ${p.id}` : p.name;
+      parts.push(
+        `<text class="text-pill" x="${p.x + ox + p.width / 2}" y="${p.y + oy + p.height / 2}" text-anchor="middle" dominant-baseline="central">${escXml(truncate(label, Math.floor(p.width / 8)))}</text>`,
+      );
+    }
+  }
+
+  // Compliance row (optional).
+  if (layout.complianceRow) {
+    const row = layout.complianceRow;
+    parts.push(
+      `<rect class="diagram-node level-5" x="${layout.legendColumnWidth + ox}" y="${row.y + oy}" width="${layout.bounds.width - layout.legendColumnWidth}" height="${row.height}" opacity="0.10"/>`,
+    );
+    for (let i = 1; i < layout.stageHeaders.length; i++) {
+      const x = layout.legendColumnWidth + i * layout.stageColumnWidth + ox;
+      parts.push(
+        `<line class="diagram-edge" x1="${x}" y1="${row.y + oy}" x2="${x}" y2="${row.y + row.height + oy}" opacity="0.3"/>`,
+      );
+    }
+    for (const chip of row.chips) {
+      parts.push(complianceChipSvg(chip, ox, oy));
+    }
+  }
+
+  const titleSvg = title
+    ? `<text class="text-header" x="${PAD}" y="${PAD - 6}">${escXml(title)}</text>`
+    : '';
+
+  // Embed the shared theme CSS inside the SVG so the rendered output is
+  // self-contained for the JCEF host — matches render-goals.ts.
+  const embedCss = generateSvgEmbedCss('transitrix');
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">
+<style>${embedCss}</style>
+${titleSvg}
+${parts.join('\n')}
+</svg>`;
+}

package/src/webview/render-process-map.ts

@@ -0,0 +1,93 @@
+/**
+ * Host-neutral renderer for the Process Map notation.
+ * Mirrors `extension/src/process-map-preview.ts`; emits a self-contained HTML
+ * fragment for the JCEF host (Step 4 of ADR 0001).
+ */
+import type { MapProcess, ProcessGroup, ProcessMapHeader } from '../process-map/types.js';
+import { escHtml } from './render-util.js';
+
+const STATUS_BADGE: Record<string, string> = {
+  Active: 'badge-active',
+  Draft: 'badge-draft',
+  Deprecated: 'badge-deprecated',
+};
+
+const GROUP_LABEL: Record<string, string> = {
+  operating: 'Operating',
+  supporting: 'Supporting',
+  management: 'Management',
+};
+
+function maturityDots(m: number | undefined): string {
+  if (m === undefined) return '<span class="cell-empty">—</span>';
+  const filled = '●'.repeat(Math.max(0, Math.min(5, m)));
+  const empty = '○'.repeat(5 - Math.max(0, Math.min(5, m)));
+  return `<span class="maturity-dots">${filled}${empty}</span>`;
+}
+
+function renderProcessRow(p: MapProcess): string {
+  return `<tr>
+  <td class="col-name">
+    <div class="catalogue-name">${escHtml(p.name)}</div>
+    <div class="catalogue-id">${escHtml(p.process_id)}</div>
+    ${p.description ? `<div class="catalogue-desc">${escHtml(p.description)}</div>` : ''}
+  </td>
+  <td class="col-status"><span class="tx-badge ${escHtml(STATUS_BADGE[p.status] ?? '')}">${escHtml(p.status)}</span></td>
+  <td class="col-maturity">${maturityDots(p.maturity)}</td>
+  <td class="col-owner">${p.owner_role ? escHtml(p.owner_role) : '<span class="cell-empty">—</span>'}</td>
+  <td class="col-capability">${p.capability ? `<span class="cap-tag">${escHtml(p.capability)}</span>` : '<span class="cell-empty">—</span>'}</td>
+  <td class="col-bpmn">${p.bpmn_file ? `<span class="bpmn-link" title="${escHtml(p.bpmn_file)}">📄 BPMN</span>` : '<span class="cell-empty">—</span>'}</td>
+</tr>`;
+}
+
+function renderGroup(g: ProcessGroup): string {
+  const processes = g.processes ?? [];
+  const rows = processes.length === 0
+    ? `<tr><td colspan="6" class="empty-group">No processes in this group.</td></tr>`
+    : processes.map(renderProcessRow).join('\n');
+  const typeKey = String(g.type ?? '');
+  return `<section class="group-section group-${escHtml(typeKey)}">
+  <header class="group-header">
+    <div class="group-meta">
+      <span class="group-tag group-tag-${escHtml(typeKey)}">${escHtml(GROUP_LABEL[typeKey] ?? typeKey)}</span>
+      <span class="group-id">${escHtml(g.id)}</span>
+    </div>
+    <h2 class="group-title">${escHtml(g.name)}</h2>
+    ${g.description ? `<p class="group-desc">${escHtml(g.description)}</p>` : ''}
+  </header>
+  <table class="catalogue-table">
+    <thead>
+      <tr>
+        <th>Process</th>
+        <th>Status</th>
+        <th>Maturity</th>
+        <th>Owner</th>
+        <th>Capability</th>
+        <th>BPMN</th>
+      </tr>
+    </thead>
+    <tbody>
+      ${rows}
+    </tbody>
+  </table>
+</section>`;
+}
+
+export function renderProcessMapHtml(map: ProcessMapHeader): string {
+  const header = `<header class="catalogue-header">
+    <div class="catalogue-title">${escHtml(map.name)}</div>
+    <div class="catalogue-meta">
+      <span class="catalogue-id-tag">${escHtml(map.id)}</span>
+      <span class="catalogue-updated">Updated ${escHtml(map.updated_at)}</span>
+      ${map.version ? `<span class="catalogue-version">v${escHtml(map.version)}</span>` : ''}
+    </div>
+    ${map.description ? `<div class="catalogue-subtitle">${escHtml(map.description)}</div>` : ''}
+  </header>`;
+  const body = map.groups.length === 0
+    ? '<div class="empty-map">No groups defined.</div>'
+    : map.groups.map(renderGroup).join('\n');
+  return `<section class="tx-catalogue tx-process-map">
+${header}
+${body}
+</section>`;
+}

package/src/webview/render-products.ts

@@ -0,0 +1,91 @@
+/**
+ * Host-neutral renderer for the Products catalogue notation.
+ * Mirrors `extension/src/products-preview.ts`; emits a self-contained HTML
+ * fragment for the JCEF host (Step 4 of ADR 0001).
+ */
+import type { Product, ProductsCatalogueHeader } from '../products/types.js';
+import { escHtml } from './render-util.js';
+
+const TYPE_LABEL: Record<string, string> = {
+  digital_product: 'Digital Product',
+  service: 'Service',
+  platform: 'Platform',
+  bundle: 'Bundle',
+};
+
+const STATUS_BADGE: Record<string, string> = {
+  Active: 'badge-active',
+  Draft: 'badge-draft',
+  Deprecated: 'badge-deprecated',
+};
+
+function maturityDots(m: number | undefined): string {
+  if (m === undefined) return '<span class="cell-empty">—</span>';
+  const filled = '●'.repeat(Math.max(0, Math.min(5, m)));
+  const empty = '○'.repeat(5 - Math.max(0, Math.min(5, m)));
+  return `<span class="maturity-dots">${filled}${empty}</span>`;
+}
+
+function disclosureList(label: string, items: string[] | undefined): string {
+  if (!items || items.length === 0) return '';
+  const lis = items.map((i) => `<li>${escHtml(i)}</li>`).join('');
+  return `<details><summary>${escHtml(label)} (${items.length})</summary><ul>${lis}</ul></details>`;
+}
+
+function renderRow(p: Product): string {
+  const extras = [
+    disclosureList('Capabilities', p.capabilities),
+    disclosureList('Processes', p.processes),
+    disclosureList('Apps', p.supporting_apps),
+  ]
+    .filter(Boolean)
+    .join('');
+  return `<tr>
+  <td class="col-name">
+    <div class="catalogue-name">${escHtml(p.name)}</div>
+    <div class="catalogue-id">${escHtml(p.product_id)}</div>
+    ${p.description ? `<div class="catalogue-desc">${escHtml(p.description)}</div>` : ''}
+    ${extras}
+  </td>
+  <td class="col-type"><span class="type-tag">${escHtml(TYPE_LABEL[p.type] ?? p.type)}</span></td>
+  <td class="col-status"><span class="tx-badge ${escHtml(STATUS_BADGE[p.status] ?? '')}">${escHtml(p.status)}</span></td>
+  <td class="col-maturity">${maturityDots(p.maturity)}</td>
+  <td class="col-domain">${p.domain ? escHtml(p.domain) : '<span class="cell-empty">—</span>'}</td>
+  <td class="col-owner">${p.owner_role ? escHtml(p.owner_role) : '<span class="cell-empty">—</span>'}</td>
+</tr>`;
+}
+
+export function renderProductsHtml(catalogue: ProductsCatalogueHeader): string {
+  const rows = catalogue.products.map(renderRow).join('\n');
+  const emptyRow = catalogue.products.length === 0
+    ? `<tr><td colspan="6" class="empty-catalogue">No products defined.</td></tr>`
+    : '';
+  const header = `<header class="catalogue-header">
+    <div class="catalogue-title">${escHtml(catalogue.name)}</div>
+    <div class="catalogue-meta">
+      <span class="catalogue-id-tag">${escHtml(catalogue.id)}</span>
+      <span class="catalogue-updated">Updated ${escHtml(catalogue.updated_at)}</span>
+      ${catalogue.version ? `<span class="catalogue-version">v${escHtml(catalogue.version)}</span>` : ''}
+    </div>
+    ${catalogue.description ? `<div class="catalogue-subtitle">${escHtml(catalogue.description)}</div>` : ''}
+  </header>`;
+  return `<section class="tx-catalogue tx-products">
+${header}
+<table class="catalogue-table">
+  <thead>
+    <tr>
+      <th>Name / ID</th>
+      <th>Type</th>
+      <th>Status</th>
+      <th>Maturity</th>
+      <th>Domain</th>
+      <th>Owner Role</th>
+    </tr>
+  </thead>
+  <tbody>
+    ${rows}
+    ${emptyRow}
+  </tbody>
+</table>
+</section>`;
+}

package/src/webview/render-scenarios.ts

@@ -0,0 +1,90 @@
+/**
+ * Host-neutral renderer for the Scenarios notation.
+ * Mirrors `extension/src/scenarios-preview.ts`; emits a self-contained HTML
+ * fragment for the JCEF host (Step 4 of ADR 0001).
+ */
+import type { FactorView, ScenarioHeader } from '../scenarios/types.js';
+import { escHtml } from './render-util.js';
+
+const STATUS_BADGE: Record<string, string> = {
+  Active: 'badge-active',
+  Draft: 'badge-draft',
+  Archived: 'badge-archived',
+};
+
+const RELEVANCE_BADGE: Record<string, string> = {
+  High: 'badge-high',
+  Medium: 'badge-medium',
+  Low: 'badge-low',
+};
+
+function buildFactorsTable(factors: FactorView[] | undefined): string {
+  if (!factors || factors.length === 0) return '';
+  const rows = factors
+    .map(
+      (f) => `<tr>
+  <td class="col-factor-id">${escHtml(f.factor_id)}</td>
+  <td class="col-relevance">${
+    f.relevance
+      ? `<span class="tx-badge ${escHtml(RELEVANCE_BADGE[f.relevance] ?? '')}">${escHtml(f.relevance)}</span>`
+      : '<span class="cell-empty">—</span>'
+  }</td>
+  <td class="col-impact">${f.impact ? escHtml(f.impact) : '<span class="cell-empty">—</span>'}</td>
+</tr>`,
+    )
+    .join('\n');
+  return `<section class="scn-section">
+  <h2 class="scn-section-title">Factors view <span class="scn-count">${factors.length}</span></h2>
+  <table class="catalogue-table">
+    <thead><tr><th>Factor ID</th><th>Relevance</th><th>Impact</th></tr></thead>
+    <tbody>${rows}</tbody>
+  </table>
+</section>`;
+}
+
+function buildRefSection(label: string, items: string[]): string {
+  if (items.length === 0) return '';
+  const lis = items.map((id) => `<li><code>${escHtml(id)}</code></li>`).join('');
+  return `<section class="scn-section">
+  <h2 class="scn-section-title">${escHtml(label)} <span class="scn-count">${items.length}</span></h2>
+  <ul class="scn-ref-list">${lis}</ul>
+</section>`;
+}
+
+function extractIds(list: readonly unknown[] | undefined, key: string): string[] {
+  return (list ?? []).map((x) => String((x as Record<string, unknown>)[key] ?? ''));
+}
+
+export function renderScenarioHtml(scn: ScenarioHeader): string {
+  const blocks: string[] = [];
+  if (scn.vision) {
+    blocks.push(`<section class="scn-section scn-vision">
+  <h2 class="scn-section-title">Vision</h2>
+  <p class="scn-vision-text">${escHtml(scn.vision)}</p>
+</section>`);
+  }
+  blocks.push(buildFactorsTable(scn.factors_view));
+  blocks.push(buildRefSection('Goals', extractIds(scn.goals, 'goal_id')));
+  blocks.push(buildRefSection('Capabilities', extractIds(scn.capabilities, 'capability_id')));
+  blocks.push(buildRefSection('Activities', extractIds(scn.activities, 'activity_id')));
+  blocks.push(buildRefSection('Products', extractIds(scn.products, 'product_id')));
+  blocks.push(buildRefSection('Processes', extractIds(scn.processes, 'process_id')));
+  blocks.push(buildRefSection('Applications', extractIds(scn.applications, 'app_id')));
+  const content = blocks.filter(Boolean).join('\n');
+
+  const statusBadge = `<span class="tx-badge ${escHtml(STATUS_BADGE[scn.status] ?? '')}">${escHtml(scn.status)}</span>`;
+  const header = `<header class="catalogue-header">
+    <div class="catalogue-title">${escHtml(scn.name)}</div>
+    <div class="catalogue-meta">
+      ${statusBadge}
+      <span class="catalogue-id-tag">${escHtml(scn.id)}</span>
+      ${scn.created_at ? `<span class="catalogue-updated">Created ${escHtml(scn.created_at)}</span>` : ''}
+    </div>
+    ${scn.description ? `<div class="catalogue-subtitle">${escHtml(scn.description)}</div>` : ''}
+  </header>`;
+  const body = content || '<div class="empty-scenario">Scenario has no content yet (no vision, factors, or references).</div>';
+  return `<section class="tx-catalogue tx-scenarios">
+${header}
+${body}
+</section>`;
+}

package/src/webview/render-util.ts

@@ -0,0 +1,34 @@
+/**
+ * Small set of host-neutral helpers shared by the `render-*.ts` modules.
+ *
+ * The webview bundle (ADR 0001) runs inside JCEF without access to any host
+ * APIs, so all string/markup utilities must stay framework-free here.
+ */
+
+export function escXml(s: string): string {
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/** Same encoding as `escXml`; aliased so HTML-table renderers read clearly. */
+export const escHtml = escXml;
+
+/** Pull common frontmatter for the optional preview heading. */
+export function readDocHeader(doc: unknown): {
+  title?: string;
+  subtitle?: string;
+  version?: string;
+  date?: string;
+} {
+  if (!doc || typeof doc !== 'object') return {};
+  const raw = doc as Record<string, unknown>;
+  const out: { title?: string; subtitle?: string; version?: string; date?: string } = {};
+  if (typeof raw['title'] === 'string') out.title = raw['title'];
+  if (typeof raw['description'] === 'string') out.subtitle = raw['description'];
+  if (raw['version'] !== undefined) out.version = String(raw['version']);
+  if (typeof raw['date'] === 'string') out.date = raw['date'];
+  return out;
+}