@transitrix/diagrams 1.0.0

package/src/webview/__tests__/entry-notations.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Step 4 parity check: every supported notation must render through the
+ * webview bundle's `render(kind, source)` API from the same example fixtures
+ * the VS Code previews consume — a valid document yields `status: 'ok'` with
+ * non-empty markup, and a malformed document degrades to the error panel
+ * (structured errors, no thrown exception reaching the JVM host).
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { describe, expect, it } from 'vitest';
+
+import { api, render, type NotationKind } from '../entry.js';
+
+const EXAMPLES = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../../tests/fixtures/notation-corpus');
+
+interface Fixture {
+  kind: NotationKind;
+  file: string;
+  /** The markup wrapper the renderer emits: an <svg> diagram or an HTML <section>. */
+  markup: 'svg' | 'section';
+}
+
+// Mirrors the fixtures used by the VS Code previews. One representative
+// example per notation is enough to prove the dispatch + renderer wiring.
+const FIXTURES: Fixture[] = [
+  { kind: 'goals', file: 'goals/strategy-2026.goals.transitrix.yaml', markup: 'svg' },
+  { kind: 'fgca', file: 'fgca/strategy-2026.fgca.transitrix.yaml', markup: 'svg' },
+  { kind: 'fga', file: 'fga/strategy-2026.fga.transitrix.yaml', markup: 'svg' },
+  { kind: 'activities', file: 'activities/platform-launch.activities.transitrix.yaml', markup: 'svg' },
+  { kind: 'activity-card', file: 'activity-card/eu-programme.activity-card.transitrix.yaml', markup: 'svg' },
+  { kind: 'process-blueprint', file: 'process-blueprint/order-fulfilment.process-blueprint.transitrix.yaml', markup: 'svg' },
+  { kind: 'blocks', file: 'blocks/architecture.blocks.transitrix.yaml', markup: 'svg' },
+  { kind: 'applications', file: 'applications/portfolio-2026.applications.transitrix.yaml', markup: 'section' },
+  { kind: 'products', file: 'products/portfolio-2026.products.transitrix.yaml', markup: 'section' },
+  { kind: 'process-map', file: 'process-map/enterprise.process-map.transitrix.yaml', markup: 'section' },
+  { kind: 'scenarios', file: 'scenarios/omnichannel-2028.scenarios.transitrix.yaml', markup: 'section' },
+  { kind: 'capability-map', file: 'capability-map/business.capability-map.transitrix.yaml', markup: 'section' },
+];
+
+describe('webview/entry — Step 4 notation coverage', () => {
+  it('wires every supported kind (no kind left on NOTATION-NOT-WIRED)', () => {
+    // The fixture table must cover the full supported-kinds surface, so a new
+    // kind added to the bundle without a renderer fails this test loudly.
+    const covered = new Set(FIXTURES.map((f) => f.kind));
+    for (const kind of api.supportedKinds) {
+      expect(covered.has(kind)).toBe(true);
+    }
+  });
+
+  for (const fx of FIXTURES) {
+    it(`renders ${fx.kind} from its example fixture`, () => {
+      const source = readFileSync(path.join(EXAMPLES, fx.file), 'utf8');
+      const r = render(fx.kind, source);
+      expect(r.notation).toBe(fx.kind);
+      expect(r.errors).toEqual([]);
+      expect(r.status).toBe('ok');
+      expect(r.svg.length).toBeGreaterThan(0);
+      expect(r.svg).toContain(fx.markup === 'svg' ? '<svg ' : '<section');
+    });
+  }
+
+  it('degrades malformed input to the error panel for a diagram notation', () => {
+    const r = render('process-blueprint', 'process_blueprint:\n  stages: "not a list"\n');
+    expect(r.status).toBe('error');
+    expect(r.errors.length).toBeGreaterThan(0);
+    expect(r.svg).toBe('');
+  });
+
+  it('degrades malformed input to the error panel for a catalogue notation', () => {
+    const r = render('applications', 'applications_catalogue:\n  applications: "not a list"\n');
+    expect(r.status).toBe('error');
+    expect(r.errors.length).toBeGreaterThan(0);
+    expect(r.svg).toBe('');
+  });
+});

package/src/webview/__tests__/entry.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+
+import { api, render } from '../entry.js';
+
+const VALID_GOALS_DOC = `
+notation: goals
+id: GOALS-WEBVIEW-1
+name: "Webview entry smoke test"
+goal_types:
+  - { name: "Strategy", level: 0 }
+goals:
+  - id: GOAL-MOON-1
+    name: "Reach the moon"
+    type: "Strategy"
+    level: 0
+`;
+
+describe('webview/entry — Step 2 host API', () => {
+  it('exposes a version + supportedKinds + render() trio', () => {
+    expect(api.version).toMatch(/^\d+\.\d+\.\d+/);
+    expect(api.supportedKinds).toContain('goals');
+    expect(typeof api.render).toBe('function');
+  });
+
+  it('parses + validates + renders SVG for a well-formed goals document', () => {
+    const r = render('goals', VALID_GOALS_DOC);
+    expect(r.notation).toBe('goals');
+    expect(r.status).toBe('ok');
+    expect(r.errors).toEqual([]);
+    // Step 3 wires the goals renderer — SVG must now be non-empty and contain
+    // the goal name from the YAML.
+    expect(r.svg).toContain('<svg ');
+    expect(r.svg).toContain('Reach the moon');
+  });
+
+  it('returns YAML-PARSE on malformed input — no exception escapes to the host', () => {
+    const r = render('goals', 'goals:\n  - id: g1\n    name: [unterminated');
+    expect(r.status).toBe('error');
+    expect(r.errors[0].code).toBe('YAML-PARSE');
+  });
+
+  it('returns KIND-UNKNOWN for a non-Transitrix notation kind', () => {
+    const r = render('plantuml', VALID_GOALS_DOC);
+    expect(r.status).toBe('error');
+    expect(r.errors[0].code).toBe('KIND-UNKNOWN');
+  });
+
+  it('routes non-goals kinds to their validator after Step 4 (no NOTATION-NOT-WIRED)', () => {
+    // Every supported kind is now wired to its validator + renderer. A
+    // malformed fgca document must surface a structured validation error from
+    // the fgca validator — never the Step-2/3 "not wired" placeholder.
+    const r = render('fgca', 'changes: []\n');
+    expect(r.status).toBe('error');
+    expect(r.errors.length).toBeGreaterThan(0);
+    expect(r.errors.every((e) => e.code !== 'NOTATION-NOT-WIRED')).toBe(true);
+  });
+
+  it('surfaces goals validation errors structurally (e.g. missing notation header)', () => {
+    const r = render('goals', 'goals: []\n');
+    expect(r.status).toBe('error');
+    // parseCanonicalGoals emits GOALS-* codes for canonical-shape violations.
+    expect(r.errors.some((e) => e.code.startsWith('GOALS-'))).toBe(true);
+  });
+});

package/src/webview/__tests__/render-goals.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Unit tests for the host-neutral goals SVG renderer used by the IntelliJ
+ * JCEF preview bundle. The IntelliJ build can't run inside Vitest, so these
+ * tests are the only place the goals rendering path is exercised on the
+ * webview-bundle side of the codebase.
+ */
+import { describe, expect, it } from 'vitest';
+
+import type { GoalTree } from '../../goals/types.js';
+import { renderGoalsSvg } from '../render-goals.js';
+
+const SIMPLE_TREE: GoalTree = {
+  goal_types: [
+    { name: 'Strategy', level: 0 },
+    { name: 'Tactic', level: 1 },
+  ],
+  goals: [
+    { id: 1, name: 'Reach the moon', type: 'Strategy', level: 0, parent_id: 0 },
+    { id: 2, name: 'Build a rocket', type: 'Tactic', level: 1, parent_id: 1 },
+  ],
+};
+
+describe('renderGoalsSvg', () => {
+  it('produces a self-contained <svg> with embedded theme CSS', () => {
+    const svg = renderGoalsSvg(SIMPLE_TREE, { treeName: 'Apollo' });
+    expect(svg.startsWith('<svg ')).toBe(true);
+    expect(svg).toContain('xmlns="http://www.w3.org/2000/svg"');
+    expect(svg).toContain('<style>');
+    // The shared theme CSS contract: diagram classes are defined inline.
+    expect(svg).toContain('.diagram-node');
+    expect(svg).toContain('.diagram-edge');
+    // Both goal names made it into the output.
+    expect(svg).toContain('Reach the moon');
+    expect(svg).toContain('Build a rocket');
+    // The strategy → tactic parent link rendered as an edge with the arrow marker.
+    expect(svg).toContain('marker-end="url(#arrow)"');
+    // Title block is present when treeName is supplied.
+    expect(svg).toContain('Goal tree — Apollo');
+  });
+
+  it('escapes user-controlled strings (XML safety)', () => {
+    const tree: GoalTree = {
+      goal_types: [{ name: 'Strategy', level: 0 }],
+      goals: [
+        {
+          id: 1,
+          name: 'Drop <script>alert(1)</script> & friends',
+          type: 'Strategy',
+          level: 0,
+          parent_id: 0,
+        },
+      ],
+    };
+    const svg = renderGoalsSvg(tree);
+    expect(svg).not.toContain('<script>alert(1)</script>');
+    expect(svg).toContain('&lt;script&gt;');
+    expect(svg).toContain('&amp;');
+  });
+
+  it('returns an empty SVG when the tree has no goals', () => {
+    const empty: GoalTree = { goal_types: [{ name: 'Strategy', level: 0 }], goals: [] };
+    const svg = renderGoalsSvg(empty);
+    expect(svg).toContain('<svg ');
+    expect(svg).toContain('width="0"');
+    expect(svg).toContain('height="0"');
+  });
+
+  it('omits the title block when treeName is missing', () => {
+    const svg = renderGoalsSvg(SIMPLE_TREE);
+    expect(svg).not.toContain('Goal tree —');
+  });
+});

package/src/webview/entry.ts

@@ -0,0 +1,292 @@
+/**
+ * Browser-bundle entry point for the IntelliJ JCEF preview surface (and any
+ * other host that wants the same in-browser API).
+ *
+ * Why: ADR 0001 picks JCEF + a bundled `@transitrix/diagrams` over a JVM-side
+ * re-implementation. This module is the API contract between the JVM host
+ * (which posts raw document text + the notation kind) and the rendering JS
+ * (which parses, validates, and — Step 3+ — renders SVG). Centralising the
+ * surface in one file means the JVM side only has to know about
+ * `window.transitrix.render(kind, source)` regardless of which notation the
+ * user opened.
+ *
+ * Step 2 scope: wire YAML parsing, dispatch to the right validator, surface
+ * validation/parse errors in a structured JSON shape.
+ * Step 3 scope: wire the `goals` SVG renderer so the bundle returns non-empty
+ * `svg` for a valid goals document.
+ * Step 4 scope (this PR): wire the remaining eleven notations — each one
+ * validates the parsed YAML and, when valid, renders host-neutral markup
+ * (SVG for the diagram notations, an HTML fragment for the catalogue
+ * notations). The JVM host drops whatever `svg` carries into the DOM, so the
+ * field name is historical — it transports any self-contained markup.
+ */
+import yaml from 'js-yaml';
+
+import { validateActivities } from '../activities/index.js';
+import type { ActivityDoc } from '../activities/index.js';
+import { validateActivityCard } from '../activity-card/index.js';
+import type { ActivityCardDoc } from '../activity-card/index.js';
+import { validateApplicationsCatalogue } from '../applications/index.js';
+import type { ApplicationsCatalogueFile } from '../applications/index.js';
+import { validateNestedBlocks } from '../blocks/index.js';
+import type { BlocksFile } from '../blocks/index.js';
+import { validateCapabilityMap } from '../capability-map/index.js';
+import type { CapabilityMapFile } from '../capability-map/index.js';
+import { parseCanonicalFGCA, parseCanonicalFGA } from '../fgca/parse-canonical.js';
+import { parseCanonicalGoals } from '../goals/parse-canonical.js';
+import { validateProcessBlueprint } from '../process-blueprint/index.js';
+import type { ProcessBlueprintFile } from '../process-blueprint/index.js';
+import { validateProcessMap } from '../process-map/index.js';
+import type { ProcessMapFile } from '../process-map/index.js';
+import { validateProductsCatalogue } from '../products/index.js';
+import type { ProductsCatalogueFile } from '../products/index.js';
+import { validateScenario } from '../scenarios/index.js';
+import type { ScenarioFile } from '../scenarios/index.js';
+import { coerceDatesToIsoStrings } from '../yaml-normalize.js';
+
+import { renderActivitiesSvg } from './render-activities.js';
+import { renderActivityCardSvg } from './render-activity-card.js';
+import { renderApplicationsHtml } from './render-applications.js';
+import { renderBlocksSvg } from './render-blocks.js';
+import { renderCapabilityMapHtml } from './render-capability-map.js';
+import { renderFgcaSvg } from './render-fgca.js';
+import { renderGoalsSvg } from './render-goals.js';
+import { renderProcessBlueprintSvg } from './render-process-blueprint.js';
+import { renderProcessMapHtml } from './render-process-map.js';
+import { renderProductsHtml } from './render-products.js';
+import { renderScenarioHtml } from './render-scenarios.js';
+
+export interface RenderError {
+  code: string;
+  message: string;
+  path?: string;
+}
+
+export interface RenderWarning {
+  code: string;
+  message: string;
+  path?: string;
+}
+
+export type RenderStatus = 'ok' | 'error';
+
+export interface RenderResult {
+  status: RenderStatus;
+  notation: string;
+  /**
+   * Self-contained markup for the rendered notation — an `<svg>` for the
+   * diagram notations, an HTML `<section>` for the catalogue notations. Empty
+   * on validation failure (the host shows the error panel instead). The field
+   * name is historical; the JVM host injects whatever it carries into the DOM.
+   */
+  svg: string;
+  errors: RenderError[];
+  warnings: RenderWarning[];
+}
+
+/**
+ * Notation kinds the host can request. Mirrors the `*.<kind>.<…>` suffix
+ * convention used by the VS Code extension's `activationEvents`. All twelve
+ * are wired to their validator + renderer as of Step 4.
+ */
+export type NotationKind =
+  | 'goals'
+  | 'fgca'
+  | 'fga'
+  | 'activities'
+  | 'activity-card'
+  | 'applications'
+  | 'products'
+  | 'process-map'
+  | 'process-blueprint'
+  | 'scenarios'
+  | 'capability-map'
+  | 'blocks';
+
+const SUPPORTED_KINDS: readonly NotationKind[] = [
+  'goals',
+  'fgca',
+  'fga',
+  'activities',
+  'activity-card',
+  'applications',
+  'products',
+  'process-map',
+  'process-blueprint',
+  'scenarios',
+  'capability-map',
+  'blocks',
+];
+
+const VERSION = '0.1.0';
+
+function emptyResult(notation: string, status: RenderStatus): RenderResult {
+  return { status, notation, svg: '', errors: [], warnings: [] };
+}
+
+function errorResult(notation: string, code: string, message: string, path?: string): RenderResult {
+  const r = emptyResult(notation, 'error');
+  r.errors.push(path !== undefined ? { code, message, path } : { code, message });
+  return r;
+}
+
+function parseYaml(source: string): { doc?: unknown; error?: string } {
+  try {
+    // Coerce native `Date`s (bare `2026-06-01` per YAML 1.1) back to ISO
+    // strings before validation — every notation validator expects string
+    // dates, and the VS Code previews apply the same normalisation. Without
+    // it the canonical-minus-quotes form would falsely fail shape checks.
+    return { doc: coerceDatesToIsoStrings(yaml.load(source)) };
+  } catch (e: unknown) {
+    return { error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+interface ValidationLike {
+  valid: boolean;
+  errors: RenderError[];
+  warnings: RenderWarning[];
+}
+
+/**
+ * Shared shape for the validate-then-render notations: copy the validator's
+ * errors/warnings into the result, and render markup only once the document is
+ * valid. `renderMarkup` is a thunk so the (type-asserted) render call never
+ * runs against a document the validator rejected.
+ */
+function renderFromValidation(
+  kind: NotationKind,
+  result: ValidationLike,
+  renderMarkup: () => string,
+): RenderResult {
+  const r = emptyResult(kind, result.valid ? 'ok' : 'error');
+  r.errors.push(...result.errors);
+  r.warnings.push(...result.warnings);
+  if (result.valid) {
+    r.svg = renderMarkup();
+  }
+  return r;
+}
+
+function dispatchValidate(kind: NotationKind, doc: unknown): RenderResult {
+  switch (kind) {
+    case 'goals': {
+      const v = parseCanonicalGoals(doc);
+      const r = emptyResult('goals', v.valid ? 'ok' : 'error');
+      r.errors.push(...v.errors);
+      r.warnings.push(...v.warnings);
+      if (v.valid && v.parsed) {
+        const meta = (doc ?? {}) as { name?: unknown };
+        const treeName = typeof meta.name === 'string' ? meta.name : '';
+        r.svg = renderGoalsSvg(v.parsed, { treeName });
+      }
+      return r;
+    }
+    // FGCA and FGA share the canonical parse + renderer; only the layer
+    // visibility differs (FGA collapses the Change column). Both carry the
+    // parsed `FGCADoc` on the result's `parsed` field when valid.
+    case 'fgca': {
+      const v = parseCanonicalFGCA(doc);
+      const r = emptyResult('fgca', v.valid ? 'ok' : 'error');
+      r.errors.push(...v.errors);
+      r.warnings.push(...v.warnings);
+      if (v.valid && v.parsed) {
+        r.svg = renderFgcaSvg(v.parsed, { variant: 'fgca' });
+      }
+      return r;
+    }
+    case 'fga': {
+      const v = parseCanonicalFGA(doc);
+      const r = emptyResult('fga', v.valid ? 'ok' : 'error');
+      r.errors.push(...v.errors);
+      r.warnings.push(...v.warnings);
+      if (v.valid && v.parsed) {
+        r.svg = renderFgcaSvg(v.parsed, { variant: 'fga' });
+      }
+      return r;
+    }
+    case 'activities':
+      return renderFromValidation('activities', validateActivities(doc), () =>
+        renderActivitiesSvg(doc as ActivityDoc),
+      );
+    case 'activity-card':
+      return renderFromValidation('activity-card', validateActivityCard(doc), () =>
+        renderActivityCardSvg(doc as ActivityCardDoc),
+      );
+    case 'process-blueprint':
+      return renderFromValidation('process-blueprint', validateProcessBlueprint(doc), () =>
+        renderProcessBlueprintSvg(doc as ProcessBlueprintFile),
+      );
+    case 'blocks':
+      return renderFromValidation('blocks', validateNestedBlocks(doc), () =>
+        renderBlocksSvg(doc as BlocksFile),
+      );
+    // Catalogue notations render an HTML fragment from the header nested under
+    // their top-level wrapper key (`<thing>_catalogue` / `scenario` / …).
+    case 'applications':
+      return renderFromValidation('applications', validateApplicationsCatalogue(doc), () =>
+        renderApplicationsHtml((doc as ApplicationsCatalogueFile).applications_catalogue),
+      );
+    case 'products':
+      return renderFromValidation('products', validateProductsCatalogue(doc), () =>
+        renderProductsHtml((doc as ProductsCatalogueFile).products_catalogue),
+      );
+    case 'process-map':
+      return renderFromValidation('process-map', validateProcessMap(doc), () =>
+        renderProcessMapHtml((doc as ProcessMapFile).process_map),
+      );
+    case 'scenarios':
+      return renderFromValidation('scenarios', validateScenario(doc), () =>
+        renderScenarioHtml((doc as ScenarioFile).scenario),
+      );
+    case 'capability-map':
+      return renderFromValidation('capability-map', validateCapabilityMap(doc), () =>
+        renderCapabilityMapHtml((doc as CapabilityMapFile).capability_map),
+      );
+    default:
+      return errorResult(
+        kind,
+        'NOTATION-NOT-WIRED',
+        `Notation '${kind}' is not wired into the IntelliJ bundle yet.`,
+      );
+  }
+}
+
+export function render(notationKind: string, source: string): RenderResult {
+  if (typeof notationKind !== 'string' || notationKind.length === 0) {
+    return errorResult('', 'KIND-MISSING', 'notationKind is required');
+  }
+  if (typeof source !== 'string') {
+    return errorResult(notationKind, 'SOURCE-INVALID', 'source must be a string');
+  }
+  if (!SUPPORTED_KINDS.includes(notationKind as NotationKind)) {
+    return errorResult(
+      notationKind,
+      'KIND-UNKNOWN',
+      `Unknown notation kind: '${notationKind}'. Expected one of: ${SUPPORTED_KINDS.join(', ')}.`,
+    );
+  }
+  const parsed = parseYaml(source);
+  if (parsed.error !== undefined) {
+    return errorResult(notationKind, 'YAML-PARSE', parsed.error);
+  }
+  return dispatchValidate(notationKind as NotationKind, parsed.doc);
+}
+
+export const api = {
+  version: VERSION,
+  supportedKinds: SUPPORTED_KINDS,
+  render,
+};
+
+export type TransitrixWebviewApi = typeof api;
+
+// Install the API on `window.transitrix` when running in a browser-ish host
+// (JCEF qualifies). In a Node/Vitest context `window` is undefined and the
+// install is a no-op — the named exports remain available for unit tests.
+declare const window: { transitrix?: TransitrixWebviewApi } | undefined;
+if (typeof window !== 'undefined') {
+  (window as { transitrix?: TransitrixWebviewApi }).transitrix = api;
+}
+
+export default api;

package/src/webview/render-activities.ts

@@ -0,0 +1,156 @@
+/**
+ * Browser-safe SVG renderer for the Activities notation (network / PSND view).
+ *
+ * Step 4 of the IntelliJ epic (ADR 0001): the webview bundle must turn a
+ * validated ActivityDoc into renderable SVG so JCEF can drop it into the
+ * preview panel. The VS Code path lives in `extension/src/activities-preview.ts`
+ * and pulls in VS Code-specific concerns (themes, title block, Gantt tab
+ * switcher, save dialogs); this module is the host-neutral subset — pure
+ * layout → SVG with no VS Code APIs, no `node:fs`, no `node:path`.
+ *
+ * Only the DEFAULT network view (Project Schedule Network Diagram) is ported.
+ * The Gantt view, the CSS-only tab switcher and the interactive spacing /
+ * curvature controls stay in the VS Code preview.
+ */
+import { layoutActivities } from '../activities/layout.js';
+import { computeCpm } from '../activities/cpm.js';
+import type {
+  ActivityDoc,
+  ActivitiesLayout,
+  ActivitiesLayoutOptions,
+} from '../activities/types.js';
+import { horizontalCubicEdgePath, DEFAULT_EDGE_CURVATURE } from '../edge-path.js';
+import { generateSvgEmbedCss } from '../theme/index.js';
+import { escXml } from './render-util.js';
+
+const N_NODE_W = 200;
+const N_NODE_H = 80;
+const N_PAD = 24;
+
+// Activities-specific diagram CSS. Mirrors `ACTIVITIES_DIAGRAM_CSS` from the
+// VS Code preview — the rules that shape the network diagram itself (critical
+// path, milestones, edge colours). Embedded alongside the shared theme CSS so
+// the SVG is self-contained for the JCEF host.
+const ACTIVITIES_DIAGRAM_CSS = `
+  .act-node { fill: var(--ts-bg-surface, #f8fafc); stroke: var(--ts-border, #94a3b8); stroke-width: 1.5; }
+  .critical-node { fill: #fff7ed; stroke: var(--ts-brand-orange, #ff4d00); stroke-width: 2.5; }
+  .milestone-node { fill: #ecfeff; stroke: var(--ts-text-muted, #64748b); stroke-dasharray: 4 2; }
+  .critical-edge { stroke: var(--ts-brand-orange, #ff4d00); stroke-width: 2; }
+  .arrow-fill-critical { fill: var(--ts-brand-orange, #ff4d00); }
+`;
+
+function truncate(s: string, maxLen: number): string {
+  return s.length > maxLen ? s.slice(0, maxLen - 1) + '…' : s;
+}
+
+export interface RenderActivitiesOptions {
+  /** Optional heading rendered as a `text-header` above the diagram. */
+  title?: string;
+  /** Network column / row gaps. Defaults match `layoutActivities`. */
+  gaps?: ActivitiesLayoutOptions;
+  /** Edge curvature; 1 = default, 0 = straight, higher = stronger arc. */
+  curvature?: number;
+}
+
+/**
+ * Render the network (PSND) view of an already-validated ActivityDoc to a
+ * self-contained SVG string.
+ *
+ * The caller passes a doc cast from the yaml-parsed `unknown` after
+ * `validateActivities` returns valid (the activities module has no parsed
+ * field, so the dispatcher does `doc as ActivityDoc`).
+ *
+ * Cyclic graphs degrade gracefully: `layoutActivities` / `computeCpm` defend
+ * against cycles internally (Kahn's topo-order omits cyclic nodes from the
+ * critical-path computation, which `computeCpm` backfills with neutral CPM
+ * values), so this renderer simply renders whatever the layout returns rather
+ * than short-circuiting.
+ */
+export function renderActivitiesSvg(doc: ActivityDoc, options: RenderActivitiesOptions = {}): string {
+  const { title = '', gaps = {}, curvature = DEFAULT_EDGE_CURVATURE } = options;
+
+  const layout: ActivitiesLayout = layoutActivities(doc, gaps);
+
+  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 cpm = computeCpm(doc.activities ?? []);
+  const titleH = title ? 24 : 0;
+  const w = layout.bounds.width + N_PAD * 2;
+  const h = layout.bounds.height + N_PAD * 2 + titleH;
+  const ox = -layout.bounds.x + N_PAD;
+  const oy = -layout.bounds.y + N_PAD + titleH;
+
+  const nodeMap = new Map(layout.nodes.map((n) => [n.id, n]));
+
+  // SVG paints later siblings over earlier ones. Sort non-critical first so the
+  // bright orange critical-path edges land on top — a gray edge crossing an
+  // orange one shouldn't bury the critical signal.
+  const orderedEdges = [...layout.edges].sort(
+    (a, b) => Number(Boolean(a.isCritical)) - Number(Boolean(b.isCritical)),
+  );
+
+  // Edge path = a single cubic Bézier with horizontal control handles (shared
+  // geometry in `edge-path.js`), so the curve meets the vertical node edge at a
+  // right angle and the marker-end arrow reads as perpendicular.
+  const edgeSvg = orderedEdges
+    .map((e) => {
+      const s = nodeMap.get(e.sourceId);
+      const t = nodeMap.get(e.targetId);
+      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;
+      const cls = e.isCritical ? 'diagram-edge critical-edge' : 'diagram-edge';
+      const marker = `url(#${e.isCritical ? 'arrow-crit' : 'arrow'})`;
+      return `<path d="${horizontalCubicEdgePath(sx, sy, tx, ty, curvature)}" class="${cls}" marker-end="${marker}"/>`;
+    })
+    .join('\n');
+
+  const nodeSvg = layout.nodes
+    .map((n) => {
+      const x = n.x + ox;
+      const y = n.y + oy;
+      const isCritical = cpm.get(n.id)?.isCritical ?? false;
+      const isMilestone = (n.data.duration ?? -1) === 0;
+      const cls = `diagram-node act-node ${isCritical ? 'critical-node' : ''} ${isMilestone ? 'milestone-node' : ''}`.trim();
+      const idLabel = escXml(n.id);
+      const nameLabel = escXml(truncate(n.data.name, 24));
+      const durLabel = n.data.duration !== undefined ? `${n.data.duration}d` : '—';
+      return [
+        `<rect class="${cls}" x="${x}" y="${y}" width="${N_NODE_W}" height="${N_NODE_H}" rx="6"/>`,
+        `<text class="text-id" x="${x + 8}" y="${y + 18}">${idLabel}</text>`,
+        `<text class="text-primary" x="${x + N_NODE_W / 2}" y="${y + N_NODE_H / 2}" text-anchor="middle" dominant-baseline="central">${nameLabel}</text>`,
+        `<text class="text-secondary" x="${x + N_NODE_W - 8}" y="${y + N_NODE_H - 10}" text-anchor="end">${escXml(durLabel)}</text>`,
+      ].join('\n');
+    })
+    .join('\n');
+
+  const titleSvg = title
+    ? `<text class="text-header" x="${N_PAD}" y="${N_PAD - 6}">${escXml(title)}</text>`
+    : '';
+
+  // Embed the shared theme CSS plus the activities-specific diagram 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') + ACTIVITIES_DIAGRAM_CSS;
+
+  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>
+  <marker id="arrow-crit" markerWidth="8" markerHeight="8" refX="8" refY="3" orient="auto">
+    <path d="M0,0 L0,6 L8,3 z" class="arrow-fill-critical"/>
+  </marker>
+</defs>
+${titleSvg}
+${nodeSvg}
+${edgeSvg}
+</svg>`;
+}