@transitrix/diagrams 1.1.0 → 1.2.0

package/dist/activities/__tests__/validate.test.js

@@ -12,9 +12,40 @@ const minimalValid = {
     ],
 };
 describe('validateActivities', () => {
-    it('ACT-001 — accepts valid notation field', () => {
+    it('ACT-001 — accepts notation: activities (deprecated)', () => {
         const r = validateActivities(minimalValid);
         expect(r.valid).toBe(true);
+        // deprecated notation emits a warning, not an error
+        expect(r.warnings.some(w => w.code === 'DEPRECATED_NOTATION')).toBe(true);
+    });
+    it('ACT-001 — accepts notation: action (canonical)', () => {
+        const r = validateActivities({
+            notation: 'action',
+            actions: [
+                { id: 'ACTION-001', name: 'Start', duration: 3 },
+                { id: 'ACTION-002', name: 'End', duration: 2, predecessors: ['ACTION-001'] },
+            ],
+        });
+        expect(r.valid).toBe(true);
+        expect(r.warnings.some(w => w.code === 'DEPRECATED_NOTATION')).toBe(false);
+    });
+    it('ACT-001 — accepts notation: action with deprecated activities: key (emits field warning)', () => {
+        const r = validateActivities({
+            notation: 'action',
+            activities: [{ id: 'ACTION-001', name: 'Foo', duration: 1 }],
+        });
+        expect(r.valid).toBe(true);
+        expect(r.warnings.some(w => w.code === 'DEPRECATED_FIELD')).toBe(true);
+    });
+    it('ACT-001 — normalises action_type to activity_type for downstream layout', () => {
+        const input = {
+            notation: 'action',
+            actions: [{ id: 'ACTION-001', name: 'Foo', duration: 1, action_type: 'project' }],
+        };
+        const r = validateActivities(input);
+        expect(r.valid).toBe(true);
+        const entry = input.actions[0];
+        expect(entry['activity_type']).toBe('project');
     });
     it('ACT-001 — rejects missing notation', () => {
         const r = validateActivities({ activities: [] });

package/dist/activities/validate.js

@@ -7,19 +7,31 @@ export function validateActivities(input) {
         return { valid: false, errors: [{ code: 'ACT-001', message: 'Input must be an object' }], warnings };
     }
     const raw = input;
-    // 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 (!Array.isArray(raw.activities)) {
-        errors.push({ code: 'SCHEMA_INVALID', message: 'activities must be an array', path: 'activities' });
+    if (raw.notation === 'activities') {
+        warnings.push({ code: 'DEPRECATED_NOTATION', message: 'notation: "activities" is deprecated — migrate to notation: "action"' });
+    }
+    // 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).
     if (raw.project && typeof raw.project === 'object') {
@@ -85,6 +97,10 @@ export function validateActivities(input) {
             continue;
         }
         const act = a;
+        // 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 });

package/dist/activity-card/__tests__/resolver.test.js

@@ -220,7 +220,7 @@ describe('resolveActivityCard', () => {
         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: activity');
+        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)', () => {

package/dist/activity-card/__tests__/validate.test.js

@@ -18,10 +18,32 @@ 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', () => {
         expect(validateActivityCard('x').valid).toBe(false);

package/dist/activity-card/resolver.js

@@ -81,9 +81,9 @@ function collectByNotation(docs, notation) {
     return out;
 }
 /**
- * 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, fromId) {
     const out = [];
@@ -92,7 +92,8 @@ function activeActivityGoals(relations, fromId) {
             continue;
         if (str(doc['notation']) !== 'relation')
             continue;
-        if (str(doc['type']) !== 'activity_goal')
+        const type = str(doc['type']);
+        if (type !== 'action_goal' && type !== 'activity_goal')
             continue;
         if (str(doc['from']) !== fromId)
             continue;
@@ -108,11 +109,8 @@ function activeActivityGoals(relations, fromId) {
     return out;
 }
 /**
- * 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, fromId) {
     const out = [];
@@ -121,7 +119,8 @@ function activeActivityStakeholders(relations, fromId) {
             continue;
         if (str(doc['notation']) !== 'relation')
             continue;
-        if (str(doc['type']) !== 'activity_stakeholder')
+        const type = str(doc['type']);
+        if (type !== 'action_stakeholder' && type !== 'activity_stakeholder')
             continue;
         if (str(doc['from']) !== fromId)
             continue;
@@ -146,18 +145,20 @@ export function resolveActivityCard(doc, sources) {
         errors.push({ code: 'PC-001', message: 'activity_card.project is missing' });
         return { valid: false, errors, warnings };
     }
-    const activities = collectByNotation(sources.elements, 'activity');
-    const projectRec = activities.get(projectId);
-    // PC-001 — project must resolve to an admitted ACTIVITY element after
-    // exhausting the canonical resolution scope (§6.1): canon/elements/**
-    // recursively first, then canon/views/activities/** as secondary fallback.
+    // 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 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}" not found after searching ` +
+            message: `action_card.project "${projectId}" not found after searching ` +
                 `canon/elements/** and canon/views/activities/** — ` +
-                `add a YAML file with notation: activity and id: "${projectId}" ` +
-                `(e.g. canon/elements/05_implementation/activities/${projectId}.yaml)`,
+                `add a YAML file with notation: action and id: "${projectId}" ` +
+                `(e.g. canon/elements/05_implementation/actions/${projectId}.yaml)`,
         });
         return { valid: false, errors, warnings };
     }
@@ -328,14 +329,15 @@ export function resolveActivityCard(doc, sources) {
         return a.observed_at < b.observed_at ? -1 : a.observed_at > b.observed_at ? 1 : 0;
     });
     // ── Child activities — parent = project id ──────────────────────────────────
+    // Look in both `notation: action` and legacy `notation: activity` elements.
     const childActivities = [];
-    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']),
@@ -378,7 +380,7 @@ export function resolveActivityCard(doc, sources) {
         valid_to: validToOk ? validToRaw : 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']),
     };
     const resolved = {

package/dist/activity-card/validate.js

@@ -21,8 +21,8 @@
 //   HDR-002  wrong `notation`             (CONTRACT.md §2)
 //   PC-001   `project` missing or malformed (the document-local half; the
 //            "does not resolve" half is emitted by the resolver)
-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}$/;
@@ -40,36 +40,47 @@ export function validateActivityCard(input) {
     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'])}"`,
         });
     }
-    // ── activity_card block ─────────────────────────────────────────────────────
-    const block = raw['activity_card'];
+    else if (raw['notation'] === 'activity-card') {
+        warnings.push({ code: 'DEPRECATED_NOTATION', message: 'notation: "activity-card" is deprecated — migrate to notation: "action-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;
     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-…)`,
         });
     }
     if (card['description'] !== undefined && typeof card['description'] !== 'string') {

package/dist/capability-map/index.d.ts

@@ -1,2 +1,6 @@
 export type { CapabilityType, CapabilityNode, CapabilityMapHeader, CapabilityMapFile, } 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/dist/capability-map/index.js

@@ -1 +1,3 @@
 export { validateCapabilityMap } from './validate.js';
+export { layoutCapabilityTree, TREE_NODE_WIDTH, TREE_NODE_HEIGHT, TREE_RANK_SEP, TREE_NODE_SEP } from './layout-tree.js';
+export { renderCapabilityTreeSvg } from './render-capability-tree.js';

package/dist/capability-map/layout-tree.d.ts

@@ -0,0 +1,42 @@
+import type { CapabilityNode, CapabilityMapHeader } from './types.js';
+export declare const TREE_NODE_WIDTH = 250;
+export declare const TREE_NODE_HEIGHT = 64;
+/** Gap between sibling columns (node width + rank sep = 330px, matching DSM). */
+export declare const TREE_RANK_SEP = 80;
+/** Vertical gap between sibling nodes. */
+export declare 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 declare function layoutCapabilityTree(map: CapabilityMapHeader, collapsedIds?: Set<string>): CapabilityTreeLayout;

package/dist/capability-map/layout-tree.js

@@ -0,0 +1,65 @@
+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 function layoutCapabilityTree(map, collapsedIds = new Set()) {
+    const nodes = [];
+    const edges = [];
+    const colNextY = new Map();
+    function getNextY(col) {
+        return colNextY.get(col) ?? 0;
+    }
+    function advanceY(col, delta) {
+        colNextY.set(col, (colNextY.get(col) ?? 0) + delta);
+    }
+    function placeNode(node, depth) {
+        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 = [];
+        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 = { 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/dist/capability-map/render-capability-tree.d.ts

@@ -0,0 +1,15 @@
+import type { CapabilityMapHeader } from './types.js';
+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 declare function renderCapabilityTreeSvg(map: CapabilityMapHeader, opts?: RenderCapabilityTreeOptions): string;

package/dist/capability-map/render-capability-tree.js

@@ -0,0 +1,108 @@
+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+'];
+function depthBand(depth) {
+    if (depth <= 2)
+        return 0;
+    if (depth <= 4)
+        return 1;
+    return 2;
+}
+function truncate(s, max, trim) {
+    return s.length > max ? s.slice(0, trim) + '…' : s;
+}
+/**
+ * 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, opts = {}) {
+    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/dist/capability-map/types.d.ts

@@ -22,5 +22,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;
 }

package/dist/fgca/__tests__/validate.test.js

@@ -47,11 +47,11 @@ describe('validateFGCADoc', () => {
         expect(result.valid).toBe(false);
         expect(result.errors.some(e => e.path === 'changes')).toBe(true);
     });
-    it('errors when activities array is missing', () => {
+    it('errors when actions array is missing', () => {
         const { activities: _, ...without } = VALID_DOC;
         const result = validateFGCADoc({ ...without, notation: 'fgca' });
         expect(result.valid).toBe(false);
-        expect(result.errors.some(e => e.path === 'activities')).toBe(true);
+        expect(result.errors.some(e => e.path === 'actions')).toBe(true);
     });
     it('errors on empty factor name', () => {
         const result = validateFGCADoc({ ...VALID_DOC, factors: [{ id: 1, name: '' }] });

package/dist/fgca/parse-canonical.js

@@ -91,7 +91,11 @@ export function parseCanonicalFGCA(input) {
     const factorsRaw = asObjectArray(raw['factors']);
     const goalsRaw = asObjectArray(raw['goals']);
     const changesRaw = asObjectArray(raw['changes']);
-    const activitiesRaw = asObjectArray(raw['activities']);
+    // Accept canonical `actions:` or deprecated `activities:`; warn on the latter.
+    const activitiesRaw = asObjectArray(raw['actions']) ?? asObjectArray(raw['activities']);
+    if ('activities' in raw && !('actions' in raw)) {
+        warnings.push({ code: 'FGCA-001', message: '"activities" key is deprecated — rename to "actions"' });
+    }
     if (factorsRaw === null)
         errors.push({ code: 'FGCA-004', message: 'factors must be an array', path: 'factors' });
     if (goalsRaw === null)
@@ -99,7 +103,7 @@ export function parseCanonicalFGCA(input) {
     if (changesRaw === null)
         errors.push({ code: 'FGCA-004', message: 'changes must be an array', path: 'changes' });
     if (activitiesRaw === null)
-        errors.push({ code: 'FGCA-004', message: 'activities must be an array', path: 'activities' });
+        errors.push({ code: 'FGCA-004', message: 'actions must be an array', path: 'actions' });
     if (errors.length > 0)
         return { valid: false, errors, warnings };
     // From here we know all four arrays exist.
@@ -237,11 +241,13 @@ export function parseCanonicalFGCA(input) {
         };
     });
     const internalActivities = activities.map((el, i) => {
-        const goalRefs = checkRefArray(el, 'goals', goalIds, GOAL_ID_RE, 'FGCA-011', `activities[${i}]`);
+        const goalRefs = checkRefArray(el, 'goals', goalIds, GOAL_ID_RE, 'FGCA-011', `actions[${i}]`);
+        const typeVal = typeof el['type'] === 'string' ? el['type'] : undefined;
         return {
             id: intId(String(el['id'])),
             name: String(el['name'] ?? ''),
             goal_id: goalRefs.length > 0 ? intId(goalRefs[0]) : null,
+            ...(typeVal !== undefined ? { type: typeVal } : {}),
         };
     });
     // FACTOR.references_constraint grammar check (FGCA-015).

package/dist/fgca/types.d.ts

@@ -22,6 +22,8 @@ export interface ActivityItem {
     name: string;
     goal_id?: number | string | null;
     activity_type_id?: number;
+    /** Canonical values: initiative | programme | project | work_package. Unknown values pass through without error. */
+    type?: string;
 }
 export interface ActivityTypeItem {
     id: number | string;