@transitrix/diagrams 1.0.1 → 1.2.0

package/src/activities/validate.ts

@@ -19,20 +19,31 @@ export function validateActivities(input: unknown): ActivityValidationResult {
 
   const raw = input as Record<string, unknown>;
 
-  // ACT-001: notation must equal "activities"
+  // ACT-001: notation must be "action" (canonical) or "activities" (deprecated)
   if (raw.notation === undefined) {
     errors.push({ code: 'ACT-001', message: 'notation field is required' });
     return { valid: false, errors, warnings };
   }
-  if (raw.notation !== 'activities') {
-    errors.push({ code: 'ACT-001', message: `notation must be "activities", got "${String(raw.notation)}"` });
+  if (raw.notation !== 'action' && raw.notation !== 'activities') {
+    errors.push({ code: 'ACT-001', message: `notation must be "action", got "${String(raw.notation)}"` });
     return { valid: false, errors, warnings };
   }
+  if (raw.notation === 'activities') {
+    warnings.push({ code: 'DEPRECATED_NOTATION', message: 'notation: "activities" is deprecated — migrate to notation: "action"' });
+  }
 
-  if (!Array.isArray(raw.activities)) {
-    errors.push({ code: 'SCHEMA_INVALID', message: 'activities must be an array', path: 'activities' });
+  // Accept "actions:" (canonical) or "activities:" (deprecated)
+  const rawArray = Array.isArray(raw.actions) ? raw.actions : (Array.isArray(raw.activities) ? raw.activities : undefined);
+  if (Array.isArray(raw.activities) && !Array.isArray(raw.actions)) {
+    warnings.push({ code: 'DEPRECATED_FIELD', message: 'Root key "activities:" is deprecated — rename to "actions:"' });
+  }
+  if (!rawArray) {
+    const canonKey = raw.notation === 'action' ? 'actions' : 'activities';
+    errors.push({ code: 'SCHEMA_INVALID', message: `${canonKey} must be an array`, path: canonKey });
     return { valid: false, errors, warnings };
   }
+  // Normalise onto raw.activities for the rest of this function (avoids touching downstream code)
+  if (!Array.isArray(raw.activities)) raw.activities = raw.actions;
 
   // ACT-014 / ACT-015: project.calendar validation (run before per-activity loop;
   // surfaces clearly even when activities also have issues).
@@ -99,6 +110,11 @@ export function validateActivities(input: unknown): ActivityValidationResult {
     }
     const act = a as Record<string, unknown>;
 
+    // Normalise action_type → activity_type (canonical rename; old name kept for compat)
+    if (act['action_type'] !== undefined && act['activity_type'] === undefined) {
+      act['activity_type'] = act['action_type'];
+    }
+
     // ACT-010: reject single-value forms
     if ('goal' in act) {
       errors.push({ code: 'ACT-010', message: `Use "goals: []" array form instead of "goal:" (activity at index ${i})`, path });
@@ -130,7 +146,7 @@ export function validateActivities(input: unknown): ActivityValidationResult {
     }
 
     // ACT-009: non-negative numeric fields
-    const numericFields = ['duration', 'labor_cost', 'resources_cost', 'effort', 'score', 'sort'] as const;
+    const numericFields = ['duration', 'duration_days', 'labor_cost', 'resources_cost', 'effort', 'score', 'sort'] as const;
     for (const field of numericFields) {
       const val = act[field];
       if (val !== undefined && val !== null) {
@@ -140,8 +156,8 @@ export function validateActivities(input: unknown): ActivityValidationResult {
       }
     }
 
-    // ACT-011: warn if no duration
-    if (act.duration === undefined || act.duration === null) {
+    // ACT-011: warn if no duration (duration_days is accepted as an alias)
+    if ((act.duration === undefined || act.duration === null) && (act.duration_days === undefined || act.duration_days === null)) {
       warnings.push({ code: 'ACT-011', message: `Activity "${id}" has no duration — cannot participate in CPM analysis`, path });
     }
   }

package/src/activity-card/__tests__/resolver.test.ts

@@ -41,7 +41,7 @@ const UNRELATED = {
   name: 'Other',
   parent: 'ACTIVITY-SOMETHING-ELSE-1',
 };
-const FACTOR = { notation: 'factor', id: 'FACTOR-EU-MDR-1', name: 'EU MDR regulation' };
+const FACTOR = { notation: 'driver', id: 'FACTOR-EU-MDR-1', name: 'EU MDR regulation' };
 const GOAL = { notation: 'goal', id: 'GOAL-EU-MARKET-1', name: 'Access EU market', factors: ['FACTOR-EU-MDR-1'] };
 const CHANGE = {
   notation: 'change',
@@ -233,6 +233,29 @@ describe('resolveActivityCard', () => {
     expect(r.errors.some((e) => e.code === 'PC-001')).toBe(true);
   });
 
+  it('PC-001 diagnostic discloses paths searched and actionable hint (#344)', () => {
+    const r = resolveActivityCard(CARD, { elements: [FACTOR, GOAL, CHANGE], relations });
+    const pc001 = r.errors.find((e) => e.code === 'PC-001');
+    expect(pc001).toBeDefined();
+    // Must disclose both searched paths (§7 PC-001)
+    expect(pc001!.message).toContain('canon/elements/**');
+    expect(pc001!.message).toContain('canon/views/activities/**');
+    // Must include actionable hint with expected file pattern (§7 PC-001)
+    expect(pc001!.message).toContain('notation: action');
+    expect(pc001!.message).toContain(`id: "${CARD.activity_card.project}"`);
+  });
+
+  it('resolves without PC-001 when project activity lives in a deep canon/elements subfolder (#344)', () => {
+    // Regression: the resolver must accept elements regardless of which subfolder
+    // they were loaded from (e.g. canon/elements/05_implementation/activities/).
+    // The resolver is filesystem-free, so we simulate the deep-path scenario by
+    // including the PROJECT element in the elements pool — just as loadCanon does
+    // after walking canon/elements/** recursively.
+    const r = resolveActivityCard(CARD, sources);
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+    expect(r.errors.some((e) => e.code === 'PC-001')).toBe(false);
+  });
+
   it('resolves activity_type and status from the Activity element', () => {
     const r = resolveActivityCard(CARD, {
       elements: [{ ...PROJECT, activity_type: 'programme', status: 'on_track' }, CHILD, FACTOR, GOAL, CHANGE],

package/src/activity-card/__tests__/validate.test.ts

@@ -20,10 +20,34 @@ const VALID = {
 };
 
 describe('validateActivityCard', () => {
-  it('accepts a well-formed card', () => {
+  it('accepts a well-formed card (deprecated notation: activity-card)', () => {
     const r = validateActivityCard(VALID);
     expect(r.valid).toBe(true);
     expect(r.errors).toHaveLength(0);
+    expect(r.warnings.some(w => w.code === 'DEPRECATED_NOTATION')).toBe(true);
+  });
+
+  it('accepts notation: action-card with action_card block (canonical)', () => {
+    const r = validateActivityCard({
+      notation: 'action-card',
+      action_card: {
+        id: 'ACTION_CARD-EU-PROGRAMME-1',
+        project: 'ACTION-EU-PROGRAMME-1',
+      },
+    });
+    expect(r.valid).toBe(true);
+    expect(r.warnings.some(w => w.code === 'DEPRECATED_NOTATION')).toBe(false);
+  });
+
+  it('accepts action_card block with legacy ACTIVITY_CARD id prefix', () => {
+    const r = validateActivityCard({
+      notation: 'action-card',
+      action_card: {
+        id: 'ACTIVITY_CARD-EU-PROGRAMME-1',
+        project: 'ACTION-EU-PROGRAMME-1',
+      },
+    });
+    expect(r.valid).toBe(true);
   });
 
   it('rejects non-object input', () => {

package/src/activity-card/resolver.ts

@@ -104,16 +104,17 @@ function collectByNotation(
 }
 
 /**
- * GOAL ids reached by an *active* `activity_goal` relation originating at
- * `fromId`. A relation with a non-null `valid_to` has ended (the activity was
- * re-aimed) and is excluded — the card shows the currently-served goals.
+ * GOAL ids reached by an *active* `action_goal` (or legacy `activity_goal`)
+ * relation originating at `fromId`. A relation with a non-null `valid_to` has
+ * ended (the activity was re-aimed) and is excluded.
  */
 function activeActivityGoals(relations: unknown[], fromId: string): string[] {
   const out: string[] = [];
   for (const doc of relations) {
     if (!isObject(doc)) continue;
     if (str(doc['notation']) !== 'relation') continue;
-    if (str(doc['type']) !== 'activity_goal') continue;
+    const type = str(doc['type']);
+    if (type !== 'action_goal' && type !== 'activity_goal') continue;
     if (str(doc['from']) !== fromId) continue;
     const to = str(doc['to']);
     if (!to) continue;
@@ -125,11 +126,8 @@ function activeActivityGoals(relations: unknown[], fromId: string): string[] {
 }
 
 /**
- * STAKEHOLDER ids + roles reached by an *active* `activity_stakeholder`
- * relation originating at `fromId`. A relation with a non-null `valid_to` has
- * ended and is excluded, so the card shows the project's currently-engaged
- * stakeholders. The optional `role` field on the relation carries the
- * project-role (initiator | owner | sponsor | project_manager).
+ * STAKEHOLDER ids + roles reached by an *active* `action_stakeholder` (or
+ * legacy `activity_stakeholder`) relation originating at `fromId`.
  */
 function activeActivityStakeholders(
   relations: unknown[],
@@ -139,7 +137,8 @@ function activeActivityStakeholders(
   for (const doc of relations) {
     if (!isObject(doc)) continue;
     if (str(doc['notation']) !== 'relation') continue;
-    if (str(doc['type']) !== 'activity_stakeholder') continue;
+    const type = str(doc['type']);
+    if (type !== 'action_stakeholder' && type !== 'activity_stakeholder') continue;
     if (str(doc['from']) !== fromId) continue;
     const to = str(doc['to']);
     if (!to) continue;
@@ -165,14 +164,22 @@ export function resolveActivityCard(
     return { valid: false, errors, warnings };
   }
 
-  const activities = collectByNotation(sources.elements, 'activity');
-  const projectRec = activities.get(projectId);
+  // Look up by canonical `notation: action` first, then legacy `notation: activity`.
+  const actionElements = collectByNotation(sources.elements, 'action');
+  const activityElements = collectByNotation(sources.elements, 'activity');
+  const allActionElements = new Map([...activityElements, ...actionElements]); // action wins on duplicate id
+  const projectRec = allActionElements.get(projectId);
 
-  // PC-001 — project must resolve to an admitted ACTIVITY element in canon.
+  // PC-001 — project must resolve to an admitted ACTION (or legacy ACTIVITY)
+  // element after exhausting the canonical resolution scope (§6.1).
   if (!projectRec) {
     errors.push({
       code: 'PC-001',
-      message: `activity_card.project "${projectId}" does not resolve to an ACTIVITY element in the canon element store`,
+      message:
+        `action_card.project "${projectId}" not found after searching ` +
+        `canon/elements/** and canon/views/activities/** — ` +
+        `add a YAML file with notation: action and id: "${projectId}" ` +
+        `(e.g. canon/elements/05_implementation/actions/${projectId}.yaml)`,
     });
     return { valid: false, errors, warnings };
   }
@@ -268,9 +275,10 @@ export function resolveActivityCard(
   }
 
   // ── Motivation chain — expand against canon DRIVER / GOAL / CHANGE elements ──
-  // Note: YAML corpus still uses `notation: factor` and `goal.factors` field names;
-  // the YAML keys are stable. The resolved TypeScript API uses "driver/driverIds".
-  const driverElems = collectByNotation(sources.elements, 'factor');
+  // Canon elements use `notation: driver`; `notation: factor` accepted for backward compat.
+  const driverElemsLegacy = collectByNotation(sources.elements, 'factor');
+  const driverElemsNew = collectByNotation(sources.elements, 'driver');
+  const driverElems = new Map([...driverElemsLegacy, ...driverElemsNew]);
   const goalElems = collectByNotation(sources.elements, 'goal');
   const changeElems = collectByNotation(sources.elements, 'change');
 
@@ -342,13 +350,14 @@ export function resolveActivityCard(
   });
 
   // ── Child activities — parent = project id ──────────────────────────────────
+  // Look in both `notation: action` and legacy `notation: activity` elements.
   const childActivities: ResolvedChildActivity[] = [];
-  for (const [id, rec] of activities) {
+  for (const [id, rec] of allActionElements) {
     if (str(rec['parent']) !== projectId) continue;
     childActivities.push({
       id,
       name: str(rec['name']) ?? id,
-      activity_type: str(rec['activity_type']),
+      activity_type: str(rec['action_type']) ?? str(rec['activity_type']),
       start_date: str(rec['start_date']),
       end_date: str(rec['end_date']),
       owner: str(rec['owner']),
@@ -394,7 +403,7 @@ export function resolveActivityCard(
     valid_to: validToOk ? (validToRaw as string) : undefined,
     start_date: str(projectRec['start_date']),
     end_date: str(projectRec['end_date']),
-    activity_type: str(projectRec['activity_type']),
+    activity_type: str(projectRec['action_type']) ?? str(projectRec['activity_type']),
     status: str(projectRec['status']),
   };
 

package/src/activity-card/validate.ts

@@ -26,8 +26,8 @@ import type { ValidationError, ValidationWarning, ValidationResult } from '../va
 
 export type { ValidationError, ValidationWarning, ValidationResult };
 
-const ACTIVITY_CARD_ID_RE = /^ACTIVITY_CARD(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
-const ACTIVITY_ID_RE = /^ACTIVITY(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const ACTIVITY_CARD_ID_RE = /^(ACTIVITY_CARD|ACTION_CARD)(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const ACTIVITY_ID_RE = /^(ACTIVITY|ACTION)(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 const MILESTONE_ID_RE = /^MILESTONE(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 const CHANGE_ID_RE = /^CHANGE(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
@@ -49,37 +49,46 @@ export function validateActivityCard(input: unknown): ValidationResult {
   // ── Header (CONTRACT.md §2) ────────────────────────────────────────────────
   if (!('notation' in raw)) {
     errors.push({ code: 'HDR-001', message: 'notation field is required' });
-  } else if (raw['notation'] !== 'activity-card') {
+  } else if (raw['notation'] !== 'action-card' && raw['notation'] !== 'activity-card') {
     errors.push({
       code: 'HDR-002',
-      message: `notation must be "activity-card", got "${String(raw['notation'])}"`,
+      message: `notation must be "action-card", got "${String(raw['notation'])}"`,
     });
+  } else if (raw['notation'] === 'activity-card') {
+    warnings.push({ code: 'DEPRECATED_NOTATION', message: 'notation: "activity-card" is deprecated — migrate to notation: "action-card"' });
   }
 
-  // ── activity_card block ─────────────────────────────────────────────────────
-  const block = raw['activity_card'];
+  // ── action_card / activity_card block ───────────────────────────────────────
+  // "action_card:" is canonical; "activity_card:" is accepted for compat.
+  const rawBlock = raw['action_card'] ?? raw['activity_card'];
+  if (raw['activity_card'] !== undefined && raw['action_card'] === undefined) {
+    warnings.push({ code: 'DEPRECATED_FIELD', message: 'Root key "activity_card:" is deprecated — rename to "action_card:"' });
+  }
+  const block = rawBlock;
   if (!block || typeof block !== 'object' || Array.isArray(block)) {
-    errors.push({ code: 'AC-001', message: 'Missing required root key: activity_card (object)' });
+    errors.push({ code: 'AC-001', message: 'Missing required root key: action_card (object)' });
     return { valid: false, errors, warnings };
   }
+  // Normalise onto activity_card for downstream (resolver reads doc.activity_card)
+  if (raw['activity_card'] === undefined) raw['activity_card'] = rawBlock;
   const card = block as Record<string, unknown>;
 
   if (!isNonEmptyString(card['id'])) {
-    errors.push({ code: 'AC-002', message: 'activity_card.id is required' });
+    errors.push({ code: 'AC-002', message: 'action_card.id is required' });
   } else if (!ACTIVITY_CARD_ID_RE.test(card['id'])) {
     errors.push({
       code: 'AC-002',
-      message: `activity_card.id "${card['id']}" must match ACTIVITY_CARD-[<middle>-]<INTEGER>`,
+      message: `action_card.id "${card['id']}" must match ACTION_CARD-[<middle>-]<INTEGER> (or legacy ACTIVITY_CARD-…)`,
     });
   }
 
   // PC-001 (document-local half): project present + well-formed.
   if (!isNonEmptyString(card['project'])) {
-    errors.push({ code: 'PC-001', message: 'activity_card.project is required (an ACTIVITY-… id)' });
+    errors.push({ code: 'PC-001', message: 'action_card.project is required (an ACTION-… id)' });
   } else if (!ACTIVITY_ID_RE.test(card['project'])) {
     errors.push({
       code: 'PC-001',
-      message: `activity_card.project "${card['project']}" is malformed; must match ACTIVITY-[<middle>-]<INTEGER>`,
+      message: `action_card.project "${card['project']}" is malformed; must match ACTION-[<middle>-]<INTEGER> (or legacy ACTIVITY-…)`,
     });
   }
 

package/src/capability-map/index.ts

@@ -6,3 +6,14 @@ export type {
 } from './types.js';
 
 export { validateCapabilityMap } from './validate.js';
+
+export type {
+  CapabilityTreeNode,
+  CapabilityTreeEdge,
+  CapabilityTreeLevelCounts,
+  CapabilityTreeLayout,
+} from './layout-tree.js';
+export { layoutCapabilityTree, TREE_NODE_WIDTH, TREE_NODE_HEIGHT, TREE_RANK_SEP, TREE_NODE_SEP } from './layout-tree.js';
+
+export type { RenderCapabilityTreeOptions } from './render-capability-tree.js';
+export { renderCapabilityTreeSvg } from './render-capability-tree.js';

package/src/capability-map/layout-tree.ts

@@ -0,0 +1,114 @@
+import type { CapabilityNode, CapabilityMapHeader } from './types.js';
+
+export const TREE_NODE_WIDTH = 250;
+export const TREE_NODE_HEIGHT = 64;
+/** Gap between sibling columns (node width + rank sep = 330px, matching DSM). */
+export const TREE_RANK_SEP = 80;
+/** Vertical gap between sibling nodes. */
+export const TREE_NODE_SEP = 24;
+
+export interface CapabilityTreeNode {
+  id: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  data: CapabilityNode;
+  depth: number;
+  hasChildren: boolean;
+  isCollapsed: boolean;
+}
+
+export interface CapabilityTreeEdge {
+  source: string;
+  target: string;
+}
+
+export interface CapabilityTreeLevelCounts {
+  /** Nodes at depth 0–2 (pink band). */
+  band0: number;
+  /** Nodes at depth 3–4 (yellow band). */
+  band1: number;
+  /** Nodes at depth 5+ (blue band). */
+  band2: number;
+}
+
+export interface CapabilityTreeLayout {
+  nodes: CapabilityTreeNode[];
+  edges: CapabilityTreeEdge[];
+  bounds: { x: number; y: number; width: number; height: number };
+  levelCounts: CapabilityTreeLevelCounts;
+}
+
+export function layoutCapabilityTree(
+  map: CapabilityMapHeader,
+  collapsedIds: Set<string> = new Set(),
+): CapabilityTreeLayout {
+  const nodes: CapabilityTreeNode[] = [];
+  const edges: CapabilityTreeEdge[] = [];
+
+  const colNextY = new Map<number, number>();
+  function getNextY(col: number): number {
+    return colNextY.get(col) ?? 0;
+  }
+  function advanceY(col: number, delta: number): void {
+    colNextY.set(col, (colNextY.get(col) ?? 0) + delta);
+  }
+
+  function placeNode(node: CapabilityNode, depth: number): { top: number; bottom: number } {
+    const isCollapsed = collapsedIds.has(node.id);
+    const hasChildren = Boolean(node.children?.length);
+    const visibleChildren = !isCollapsed && node.children?.length ? node.children : [];
+
+    const x = depth * (TREE_NODE_WIDTH + TREE_RANK_SEP);
+
+    if (visibleChildren.length === 0) {
+      const y = getNextY(depth);
+      advanceY(depth, TREE_NODE_HEIGHT + TREE_NODE_SEP);
+      nodes.push({ id: node.id, x, y, width: TREE_NODE_WIDTH, height: TREE_NODE_HEIGHT, data: node, depth, hasChildren, isCollapsed });
+      return { top: y, bottom: y + TREE_NODE_HEIGHT };
+    }
+
+    const childSpans: Array<{ top: number; bottom: number }> = [];
+    for (const child of visibleChildren) {
+      childSpans.push(placeNode(child, depth + 1));
+      edges.push({ source: node.id, target: child.id });
+    }
+
+    const spanTop = Math.min(...childSpans.map(s => s.top));
+    const spanBottom = Math.max(...childSpans.map(s => s.bottom));
+    const parentY = spanTop + (spanBottom - spanTop) / 2 - TREE_NODE_HEIGHT / 2;
+
+    const curColY = getNextY(depth);
+    const finalY = Math.max(parentY, curColY);
+    advanceY(depth, finalY - curColY + TREE_NODE_HEIGHT + TREE_NODE_SEP);
+
+    nodes.push({ id: node.id, x, y: finalY, width: TREE_NODE_WIDTH, height: TREE_NODE_HEIGHT, data: node, depth, hasChildren, isCollapsed });
+    return { top: Math.min(finalY, spanTop), bottom: Math.max(finalY + TREE_NODE_HEIGHT, spanBottom) };
+  }
+
+  for (const root of map.capabilities) {
+    placeNode(root, 0);
+    for (const [col, y] of colNextY) {
+      colNextY.set(col, y + TREE_NODE_SEP);
+    }
+  }
+
+  if (nodes.length === 0) {
+    return { nodes: [], edges: [], bounds: { x: 0, y: 0, width: 0, height: 0 }, levelCounts: { band0: 0, band1: 0, band2: 0 } };
+  }
+
+  const minX = Math.min(...nodes.map(n => n.x));
+  const minY = Math.min(...nodes.map(n => n.y));
+  const maxX = Math.max(...nodes.map(n => n.x + n.width));
+  const maxY = Math.max(...nodes.map(n => n.y + n.height));
+
+  const levelCounts: CapabilityTreeLevelCounts = { band0: 0, band1: 0, band2: 0 };
+  for (const n of nodes) {
+    if (n.depth <= 2) levelCounts.band0++;
+    else if (n.depth <= 4) levelCounts.band1++;
+    else levelCounts.band2++;
+  }
+
+  return { nodes, edges, bounds: { x: minX, y: minY, width: maxX - minX, height: maxY - minY }, levelCounts };
+}

package/src/capability-map/render-capability-tree.ts

@@ -0,0 +1,131 @@
+import type { CapabilityMapHeader } from './types.js';
+import { layoutCapabilityTree, TREE_NODE_WIDTH, TREE_NODE_HEIGHT, TREE_NODE_SEP } from './layout-tree.js';
+import { horizontalCubicEdgePath, DEFAULT_EDGE_CURVATURE } from '../edge-path.js';
+import { escXml } from '../webview/render-util.js';
+
+const PAD = 24;
+const BTN_R = 8;
+const LEGEND_H = 40;
+const LABEL_MAX_CHARS = 28;
+const LABEL_TRIM_CHARS = 26;
+
+const BAND_LABELS = ['Levels 0–2', 'Levels 3–4', 'Levels 5+'] as const;
+
+function depthBand(depth: number): 0 | 1 | 2 {
+  if (depth <= 2) return 0;
+  if (depth <= 4) return 1;
+  return 2;
+}
+
+function truncate(s: string, max: number, trim: number): string {
+  return s.length > max ? s.slice(0, trim) + '…' : s;
+}
+
+export interface RenderCapabilityTreeOptions {
+  collapsedIds?: Set<string>;
+  curvature?: number;
+}
+
+/**
+ * Renders a capability-map as a left-to-right SVG node tree with DSM-matching
+ * visual design: depth-banded fills, maturity badges, and +/− collapse buttons.
+ *
+ * The SVG uses CSS classes (`tree-level-N`, `tree-maturity-N`, `tree-collapse-btn`)
+ * that must be resolved by the host's stylesheet (injected via `diagramClassCss()`
+ * in themes.ts). Collapse buttons carry `data-node-id` / `data-collapsed` attributes
+ * for the webview click handler.
+ */
+export function renderCapabilityTreeSvg(
+  map: CapabilityMapHeader,
+  opts: RenderCapabilityTreeOptions = {},
+): string {
+  const { collapsedIds = new Set(), curvature = DEFAULT_EDGE_CURVATURE } = opts;
+  const layout = layoutCapabilityTree(map, collapsedIds);
+
+  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 ox = -layout.bounds.x + PAD;
+  const oy = -layout.bounds.y + PAD;
+  const svgW = layout.bounds.width + PAD * 2 + BTN_R;
+  const svgH = layout.bounds.height + PAD * 2 + LEGEND_H + TREE_NODE_SEP;
+
+  const nodeMap = new Map(layout.nodes.map(n => [n.id, n]));
+
+  const edgeSvg = layout.edges.map(e => {
+    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 `<path d="${horizontalCubicEdgePath(sx, sy, tx, ty, curvature)}" class="diagram-edge"/>`;
+  }).filter(Boolean).join('\n');
+
+  const nodeSvg = layout.nodes.map(n => {
+    const x = n.x + ox;
+    const y = n.y + oy;
+    const band = depthBand(n.depth);
+    const mat = Math.max(1, Math.min(5, n.data.current_maturity | 0));
+
+    const nameText = truncate(n.data.name, LABEL_MAX_CHARS, LABEL_TRIM_CHARS);
+    const nameTitle = n.data.name.length > LABEL_MAX_CHARS ? escXml(n.data.name) : '';
+
+    // Maturity badge: left side of node
+    const badgeW = 28;
+    const badgeH = 18;
+    const badgeX = x + 10;
+    const badgeY = y + (TREE_NODE_HEIGHT - badgeH) / 2;
+
+    // Text area: right of badge
+    const textX = badgeX + badgeW + 8;
+    const nameY = y + TREE_NODE_HEIGHT / 2 - 8;
+    const idY = y + TREE_NODE_HEIGHT / 2 + 9;
+
+    // Collapse button: centered on right edge of node
+    const btnCx = x + TREE_NODE_WIDTH;
+    const btnCy = y + TREE_NODE_HEIGHT / 2;
+
+    const collapseBtn = n.hasChildren
+      ? `<circle class="tree-collapse-btn" cx="${btnCx}" cy="${btnCy}" r="${BTN_R}" data-node-id="${escXml(n.id)}" data-collapsed="${n.isCollapsed}"/>
+  <text class="tree-collapse-lbl" x="${btnCx}" y="${btnCy}" text-anchor="middle">${n.isCollapsed ? '+' : '−'}</text>`
+      : '';
+
+    return `<g${nameTitle ? ` title="${nameTitle}"` : ''}>
+  <rect class="tree-level-${band}" x="${x}" y="${y}" width="${TREE_NODE_WIDTH}" height="${TREE_NODE_HEIGHT}" rx="11" stroke="var(--ts-node-stroke,#94a3b8)" stroke-width="3"/>
+  <rect class="tree-maturity-${mat}" x="${badgeX}" y="${badgeY}" width="${badgeW}" height="${badgeH}" rx="4"/>
+  <text class="text-pill" x="${badgeX + badgeW / 2}" y="${badgeY + badgeH / 2}" text-anchor="middle" fill="white">L${mat}</text>
+  <text class="text-primary" x="${textX}" y="${nameY}" dominant-baseline="central">${escXml(nameText)}</text>
+  <text class="text-id" x="${textX}" y="${idY}" dominant-baseline="central">${escXml(n.id)}</text>
+  ${collapseBtn}
+</g>`;
+  }).join('\n');
+
+  // Legend band: proportional coloured blocks per level-count band
+  const legendY = layout.bounds.height + PAD * 2 + TREE_NODE_SEP / 2;
+  const legendW = svgW - PAD * 2;
+  const totalNodes = layout.nodes.length || 1;
+  const bandCounts = [layout.levelCounts.band0, layout.levelCounts.band1, layout.levelCounts.band2];
+  let legendX = PAD;
+  const legendSvg = bandCounts.map((count, i) => {
+    const bw = Math.max(1, Math.round(legendW * count / totalNodes));
+    const bx = legendX;
+    legendX += bw;
+    if (count === 0) return '';
+    return `<rect class="tree-level-${i}" x="${bx}" y="${legendY}" width="${bw}" height="24" rx="4" stroke="var(--ts-node-stroke,#94a3b8)" stroke-width="1"/>
+  <text class="text-id" x="${bx + bw / 2}" y="${legendY + 12}" text-anchor="middle" dominant-baseline="central">${escXml(BAND_LABELS[i])}</text>`;
+  }).filter(Boolean).join('\n');
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${svgW}" height="${svgH}" viewBox="0 0 ${svgW} ${svgH}">
+<defs>
+  <marker id="cap-tree-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>
+${edgeSvg}
+${nodeSvg}
+${legendSvg}
+</svg>`;
+}

package/src/capability-map/types.ts

@@ -25,5 +25,7 @@ export interface CapabilityMapHeader {
 export interface CapabilityMapFile {
   notation: string;
   spec_version?: string;
+  /** Render mode for Studio previews. Defaults to 'cards'. */
+  view?: 'cards' | 'tree';
   capability_map: CapabilityMapHeader;
 }