@transitrix/diagrams 1.0.1 → 1.2.0

package/dist/webview/render-process.js

@@ -0,0 +1,392 @@
+/**
+ * Host-neutral SVG emitter for the BPMN process notation.
+ *
+ * Part of the custom process renderer programme (ADR 2026-06-22).
+ * P1: skeleton emitter — current DSL element subset: tasks, user/service tasks,
+ * XOR/AND gateways, start/end events, data objects, sequence flows (with
+ * default-flow markers), and association edges.
+ *
+ * Single-emitter unification (review C): `renderProcessBody` is the canonical
+ * body shared by every host. Callers wrap it with a host-specific title block
+ * or a standalone SVG shell.
+ *
+ * No VS Code APIs. No Node.js built-ins. Browser-safe.
+ */
+import { generateSvgEmbedCss } from '../theme/index.js';
+import { escXml } from './render-util.js';
+// ---------------------------------------------------------------------------
+// Constants — match DEFAULT_LAYOUT_DIAGRAM_OPTIONS in src/layout-options.ts
+// ---------------------------------------------------------------------------
+/** Width of the lane-name column (px). Matches the laneLabelWidth default. */
+const LANE_LABEL_BAND = 44;
+/** End margin (px) along the header height axis for rotated pool/lane captions. */
+const HEADER_LABEL_AXIS_PAD = 32;
+/** Estimated horizontal advance (px) per character at the header label font size. */
+const HEADER_LABEL_CHAR_W = 6.5;
+/** Maximum characters per wrapped line inside a task box. */
+const TASK_CHARS = 14;
+/** Line height for wrapped task-name text (px). */
+const TASK_LINE_H = 14;
+/** Maximum characters per line for below-element labels (events, gateways). */
+const LABEL_CHARS = 18;
+/** Line height for multi-line below-element labels (px). */
+const LABEL_LINE_H = 13;
+// ---------------------------------------------------------------------------
+// BPMN-specific CSS — no font-style:italic per CLAUDE.md design rule
+// ---------------------------------------------------------------------------
+export const BPMN_PROCESS_CSS = `
+.bpmn-pool { fill: var(--ts-bg-surface,#f8fafc); stroke: var(--ts-node-stroke,#94a3b8); stroke-width: 1.5; }
+.bpmn-pool-name { fill: var(--ts-bg-elevated,#f1f5f9); stroke: var(--ts-node-stroke,#94a3b8); stroke-width: 0.75; }
+.bpmn-lane { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#94a3b8); stroke-width: 0.75; }
+.bpmn-lane-header { fill: var(--ts-bg-elevated,#f1f5f9); stroke: var(--ts-node-stroke,#94a3b8); stroke-width: 0.75; }
+.bpmn-pool-label { fill: var(--ts-text-primary,#1e293b); font-size: 11px; font-weight: 700; }
+.bpmn-lane-label { fill: var(--ts-text-primary,#1e293b); font-size: 11px; font-weight: 600; }
+.bpmn-task { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#94a3b8); stroke-width: 1.5; }
+.bpmn-task-name { fill: var(--ts-text-primary,#1e293b); font-size: 11px; text-anchor: middle; }
+.bpmn-event { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#94a3b8); }
+.bpmn-event-start { stroke-width: 1.5; }
+.bpmn-event-end { stroke-width: 4; }
+.bpmn-event-label { fill: var(--ts-text-secondary,#64748b); font-size: 10px; text-anchor: middle; }
+.bpmn-gateway { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#94a3b8); stroke-width: 1.5; }
+.bpmn-gateway-marker { stroke: var(--ts-node-stroke,#94a3b8); stroke-width: 2.5; stroke-linecap: round; fill: none; }
+.bpmn-gateway-label { fill: var(--ts-text-secondary,#64748b); font-size: 10px; text-anchor: middle; }
+.bpmn-seq-flow { fill: none; stroke: var(--ts-edge-stroke,#64748b); stroke-width: 1.5; }
+.bpmn-default-mark { stroke: var(--ts-edge-stroke,#64748b); stroke-width: 1.5; stroke-linecap: round; }
+.bpmn-assoc { fill: none; stroke: var(--ts-edge-stroke,#64748b); stroke-width: 1; stroke-dasharray: 4 2; }
+.bpmn-data-obj { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#94a3b8); stroke-width: 1; }
+.bpmn-data-obj-label { fill: var(--ts-text-secondary,#64748b); font-size: 10px; text-anchor: middle; }
+.bpmn-event-intermediate { fill: none; stroke: var(--ts-node-stroke,#94a3b8); stroke-width: 1; }
+.bpmn-event-icon { fill: none; stroke: var(--ts-node-stroke,#94a3b8); stroke-width: 1.5; stroke-linecap: round; stroke-linejoin: round; }
+`;
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function r(n) {
+    return Math.round(n);
+}
+/** Truncate at a word boundary so rotated header labels never break mid-word. */
+function wordTruncate(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    const cut = text.slice(0, maxChars - 1);
+    const lastSpace = cut.lastIndexOf(' ');
+    return (lastSpace > maxChars / 2 ? cut.slice(0, lastSpace) : cut) + '…';
+}
+function fitRotatedHeaderText(name, spanPx) {
+    const maxChars = Math.max(4, Math.floor(spanPx / HEADER_LABEL_CHAR_W));
+    return wordTruncate(name, maxChars);
+}
+function wrapTaskName(name) {
+    if (!name)
+        return [];
+    const words = name.split(/\s+/);
+    const lines = [];
+    let cur = '';
+    for (const w of words) {
+        const token = w.length > TASK_CHARS ? w.slice(0, TASK_CHARS - 1) + '…' : w;
+        if (!cur) {
+            cur = token;
+        }
+        else if (cur.length + 1 + token.length <= TASK_CHARS) {
+            cur += ' ' + token;
+        }
+        else {
+            lines.push(cur);
+            if (lines.length === 3) {
+                if (lines[2].length > TASK_CHARS - 1)
+                    lines[2] = lines[2].slice(0, TASK_CHARS - 1) + '…';
+                return lines;
+            }
+            cur = token;
+        }
+    }
+    if (cur && lines.length < 3)
+        lines.push(cur);
+    if (lines.length === 0)
+        lines.push(name.slice(0, TASK_CHARS));
+    return lines;
+}
+function taskNameSvg(name, cx, cy) {
+    if (!name)
+        return '';
+    const lines = wrapTaskName(name);
+    const totalH = lines.length * TASK_LINE_H;
+    const startY = cy - totalH / 2 + TASK_LINE_H * 0.8;
+    const tspans = lines
+        .map((ln, i) => `<tspan x="${r(cx)}" y="${r(startY + i * TASK_LINE_H)}">${escXml(ln)}</tspan>`)
+        .join('');
+    return `<text class="bpmn-task-name">${tspans}</text>`;
+}
+function wrapBelowLabel(name) {
+    const words = name.split(/\s+/).filter(Boolean);
+    const allLines = [];
+    let cur = '';
+    for (const word of words) {
+        const tok = word.length > LABEL_CHARS ? word.slice(0, LABEL_CHARS - 1) + '…' : word;
+        const test = cur ? `${cur} ${tok}` : tok;
+        if (test.length <= LABEL_CHARS) {
+            cur = test;
+        }
+        else {
+            if (cur)
+                allLines.push(cur);
+            cur = tok;
+        }
+    }
+    if (cur)
+        allLines.push(cur);
+    if (allLines.length === 0)
+        return [name.slice(0, LABEL_CHARS)];
+    if (allLines.length <= 3)
+        return allLines;
+    const lines = allLines.slice(0, 3);
+    const last = lines[2];
+    lines[2] = last.length + 1 <= LABEL_CHARS ? last + '…' : last.slice(0, LABEL_CHARS - 1) + '…';
+    return lines;
+}
+function belowLabelSvg(name, cls, cx, belowY, minX = 0) {
+    if (!name)
+        return '';
+    const lines = wrapBelowLabel(name);
+    const halfW = Math.max(...lines.map((l) => l.length)) * 3;
+    const textX = minX > 0 ? Math.max(cx, minX + halfW + 2) : cx;
+    const startY = r(belowY + 12);
+    if (lines.length === 1) {
+        return `<text class="${cls}" x="${r(textX)}" y="${startY}">${escXml(lines[0])}</text>`;
+    }
+    const tspans = lines
+        .map((ln, i) => `<tspan x="${r(textX)}" dy="${i === 0 ? 0 : LABEL_LINE_H}">${escXml(ln)}</tspan>`)
+        .join('');
+    return `<text class="${cls}" x="${r(textX)}" y="${startY}">${tspans}</text>`;
+}
+// ---------------------------------------------------------------------------
+// Element renderer
+// ---------------------------------------------------------------------------
+function renderElement(el, b, ox, oy, minLabelX = 0) {
+    const ex = b.x + ox;
+    const ey = b.y + oy;
+    const cx = ex + b.width / 2;
+    const cy = ey + b.height / 2;
+    const halfR = Math.min(b.width, b.height) / 2;
+    switch (el.type) {
+        case 'startEvent':
+            return [
+                `<circle class="bpmn-event bpmn-event-start" cx="${r(cx)}" cy="${r(cy)}" r="${r(halfR)}"/>`,
+                belowLabelSvg(el.name, 'bpmn-event-label', cx, ey + b.height, minLabelX),
+            ].join('\n');
+        case 'endEvent':
+            return [
+                `<circle class="bpmn-event bpmn-event-end" cx="${r(cx)}" cy="${r(cy)}" r="${r(halfR - 2)}"/>`,
+                belowLabelSvg(el.name, 'bpmn-event-label', cx, ey + b.height, minLabelX),
+            ].join('\n');
+        case 'task':
+        case 'userTask':
+        case 'serviceTask':
+            return [
+                `<rect class="diagram-node bpmn-task" x="${r(ex)}" y="${r(ey)}" width="${r(b.width)}" height="${r(b.height)}" rx="4" ry="4"/>`,
+                taskNameSvg(el.name, cx, cy),
+            ].join('\n');
+        case 'exclusiveGateway':
+            return [
+                `<path class="bpmn-gateway" d="M ${r(cx)},${r(ey)} L ${r(ex + b.width)},${r(cy)} L ${r(cx)},${r(ey + b.height)} L ${r(ex)},${r(cy)} Z"/>`,
+                `<path class="bpmn-gateway-marker" d="M ${r(cx - 10)},${r(cy - 10)} L ${r(cx + 10)},${r(cy + 10)} M ${r(cx + 10)},${r(cy - 10)} L ${r(cx - 10)},${r(cy + 10)}"/>`,
+                belowLabelSvg(el.name, 'bpmn-gateway-label', cx, ey + b.height, minLabelX),
+            ].join('\n');
+        case 'parallelGateway':
+            return [
+                `<path class="bpmn-gateway" d="M ${r(cx)},${r(ey)} L ${r(ex + b.width)},${r(cy)} L ${r(cx)},${r(ey + b.height)} L ${r(ex)},${r(cy)} Z"/>`,
+                `<path class="bpmn-gateway-marker" d="M ${r(cx)},${r(cy - 12)} L ${r(cx)},${r(cy + 12)} M ${r(cx - 12)},${r(cy)} L ${r(cx + 12)},${r(cy)}"/>`,
+                belowLabelSvg(el.name, 'bpmn-gateway-label', cx, ey + b.height, minLabelX),
+            ].join('\n');
+        case 'inclusiveGateway':
+            return [
+                `<path class="bpmn-gateway" d="M ${r(cx)},${r(ey)} L ${r(ex + b.width)},${r(cy)} L ${r(cx)},${r(ey + b.height)} L ${r(ex)},${r(cy)} Z"/>`,
+                `<circle class="bpmn-gateway-marker" cx="${r(cx)}" cy="${r(cy)}" r="${r(halfR * 0.4)}"/>`,
+                belowLabelSvg(el.name, 'bpmn-gateway-label', cx, ey + b.height, minLabelX),
+            ].join('\n');
+        case 'intermediateMessageEvent': {
+            const innerR = r(halfR - 4);
+            const eHW = r(halfR * 0.45);
+            const eHH = r(halfR * 0.3);
+            return [
+                `<circle class="bpmn-event bpmn-event-start" cx="${r(cx)}" cy="${r(cy)}" r="${r(halfR)}"/>`,
+                `<circle class="bpmn-event-intermediate" cx="${r(cx)}" cy="${r(cy)}" r="${innerR}"/>`,
+                `<rect class="bpmn-event-icon" x="${r(cx - eHW)}" y="${r(cy - eHH)}" width="${r(eHW * 2)}" height="${r(eHH * 2)}"/>`,
+                `<path class="bpmn-event-icon" d="M ${r(cx - eHW)},${r(cy - eHH)} L ${r(cx)},${r(cy)} L ${r(cx + eHW)},${r(cy - eHH)}"/>`,
+                belowLabelSvg(el.name, 'bpmn-event-label', cx, ey + b.height, minLabelX),
+            ].join('\n');
+        }
+        case 'intermediateTimerEvent': {
+            const innerR = r(halfR - 4);
+            const clockR = r(halfR * 0.5);
+            const handLen = r(halfR * 0.38);
+            return [
+                `<circle class="bpmn-event bpmn-event-start" cx="${r(cx)}" cy="${r(cy)}" r="${r(halfR)}"/>`,
+                `<circle class="bpmn-event-intermediate" cx="${r(cx)}" cy="${r(cy)}" r="${innerR}"/>`,
+                `<circle class="bpmn-event-icon" cx="${r(cx)}" cy="${r(cy)}" r="${clockR}"/>`,
+                `<line class="bpmn-event-icon" x1="${r(cx)}" y1="${r(cy)}" x2="${r(cx)}" y2="${r(cy - handLen)}"/>`,
+                `<line class="bpmn-event-icon" x1="${r(cx)}" y1="${r(cy)}" x2="${r(cx + r(handLen * 0.7))}" y2="${r(cy)}"/>`,
+                belowLabelSvg(el.name, 'bpmn-event-label', cx, ey + b.height, minLabelX),
+            ].join('\n');
+        }
+        case 'dataObject': {
+            const fold = Math.min(8, b.width / 3, b.height / 3);
+            return [
+                `<path class="bpmn-data-obj" d="M ${r(ex)},${r(ey)} L ${r(ex + b.width - fold)},${r(ey)} L ${r(ex + b.width)},${r(ey + fold)} L ${r(ex + b.width)},${r(ey + b.height)} L ${r(ex)},${r(ey + b.height)} Z"/>`,
+                `<path class="bpmn-data-obj" fill="none" d="M ${r(ex + b.width - fold)},${r(ey)} L ${r(ex + b.width - fold)},${r(ey + fold)} L ${r(ex + b.width)},${r(ey + fold)}"/>`,
+                belowLabelSvg(el.name, 'bpmn-data-obj-label', cx, ey + b.height, minLabelX),
+            ].join('\n');
+        }
+        default:
+            return [
+                `<rect class="diagram-node" x="${r(ex)}" y="${r(ey)}" width="${r(b.width)}" height="${r(b.height)}"/>`,
+                el.name
+                    ? `<text class="text-primary" x="${r(cx)}" y="${r(cy)}" text-anchor="middle" dominant-baseline="central">${escXml(el.name)}</text>`
+                    : '',
+            ].join('\n');
+    }
+}
+// ---------------------------------------------------------------------------
+// Pool / lane structure
+// ---------------------------------------------------------------------------
+function renderPoolLanes(layout, ox, oy) {
+    const { process, laneBounds, poolBounds: pb } = layout;
+    const parts = [];
+    const px = r(pb.x + ox);
+    const py = r(pb.y + oy);
+    const pw = r(pb.width);
+    const ph = r(pb.height);
+    // Pool name band width: distance from pool left edge to first lane left edge
+    const firstLb = laneBounds.size > 0 ? [...laneBounds.values()][0] : undefined;
+    const poolNameW = firstLb ? r(firstLb.x - pb.x) : 48;
+    parts.push(`<rect class="bpmn-pool" x="${px}" y="${py}" width="${pw}" height="${ph}"/>`);
+    parts.push(`<rect class="bpmn-pool-name" x="${px}" y="${py}" width="${poolNameW}" height="${ph}"/>`);
+    const pLX = r(px + poolNameW / 2);
+    const poolLabelSpan = Math.max(ph - 2 * HEADER_LABEL_AXIS_PAD, 0);
+    const pLY = r(py + HEADER_LABEL_AXIS_PAD + poolLabelSpan / 2);
+    parts.push(`<text class="bpmn-pool-label" text-anchor="middle" dominant-baseline="central"` +
+        ` transform="rotate(-90,${pLX},${pLY})" x="${pLX}" y="${pLY}">${escXml(fitRotatedHeaderText(process.poolName, poolLabelSpan))}</text>`);
+    for (const lane of process.lanes) {
+        const lb = laneBounds.get(lane.id);
+        if (!lb)
+            continue;
+        const lx = r(lb.x + ox);
+        const ly = r(lb.y + oy);
+        const lw = r(lb.width);
+        const lh = r(lb.height);
+        parts.push(`<rect class="bpmn-lane" x="${lx}" y="${ly}" width="${lw}" height="${lh}"/>`);
+        parts.push(`<rect class="bpmn-lane-header" x="${lx}" y="${ly}" width="${LANE_LABEL_BAND}" height="${lh}"/>`);
+        const lLX = r(lx + LANE_LABEL_BAND / 2);
+        const laneLabelSpan = Math.max(lh - 2 * HEADER_LABEL_AXIS_PAD, 0);
+        const lLY = r(ly + HEADER_LABEL_AXIS_PAD + laneLabelSpan / 2);
+        parts.push(`<text class="bpmn-lane-label" text-anchor="middle" dominant-baseline="central"` +
+            ` transform="rotate(-90,${lLX},${lLY})" x="${lLX}" y="${lLY}">${escXml(fitRotatedHeaderText(lane.name, laneLabelSpan))}</text>`);
+    }
+    return parts.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Canonical body emitter, shared by every host (VS Code, JCEF, static export).
+ *
+ * Renders: pool + lane structure, all flow elements, sequence flows (with
+ * default-flow markers), and association edges. The `<defs>` block
+ * containing the arrowhead marker is included so the body is self-contained.
+ *
+ * @param layout - Positioned process layout (output of `layoutProcess`).
+ * @param ox - Horizontal canvas offset (px) applied to all coordinates.
+ * @param oy - Vertical canvas offset (px) applied to all coordinates.
+ */
+export function renderProcessBody(layout, ox, oy) {
+    const parts = [];
+    // Build clip-path rects for every lane so element labels can't bleed into the
+    // lane-name header strip on the left.
+    const laneClipDefs = layout.process.lanes.map((lane) => {
+        const lb = layout.laneBounds.get(lane.id);
+        if (!lb)
+            return '';
+        const clipId = `bpmn-lc-${escXml(lane.id)}`;
+        const cx2 = r(lb.x + ox + LANE_LABEL_BAND);
+        const cy2 = r(lb.y + oy);
+        const cw = r(lb.width - LANE_LABEL_BAND);
+        const ch = r(lb.height);
+        return `  <clipPath id="${clipId}"><rect x="${cx2}" y="${cy2}" width="${cw}" height="${ch}"/></clipPath>`;
+    }).filter(Boolean).join('\n');
+    parts.push(`<defs>\n` +
+        `  <marker id="bpmn-arrow" viewBox="0 0 10 10" refX="9" refY="5"` +
+        ` markerWidth="8" markerHeight="8" orient="auto">\n` +
+        `    <path d="M 0 0 L 10 5 L 0 10 z" class="arrow-fill"/>\n` +
+        `  </marker>\n` +
+        (laneClipDefs ? laneClipDefs + '\n' : '') +
+        `</defs>`);
+    parts.push(renderPoolLanes(layout, ox, oy));
+    for (const lane of layout.process.lanes) {
+        const lb = layout.laneBounds.get(lane.id);
+        const clipId = lb ? `bpmn-lc-${escXml(lane.id)}` : undefined;
+        const laneContentX = lb ? lb.x + ox + LANE_LABEL_BAND : 0;
+        if (clipId)
+            parts.push(`<g clip-path="url(#${clipId})">`);
+        for (const el of lane.elements) {
+            const b = layout.elements.get(el.id);
+            if (!b)
+                continue;
+            parts.push(renderElement(el, b, ox, oy, laneContentX));
+        }
+        if (clipId)
+            parts.push('</g>');
+    }
+    for (const flow of layout.flows) {
+        if (flow.waypoints.length < 2)
+            continue;
+        const pts = flow.waypoints.map((p) => `${r(p.x + ox)},${r(p.y + oy)}`).join(' ');
+        parts.push(`<polyline class="bpmn-seq-flow" points="${pts}" marker-end="url(#bpmn-arrow)"/>`);
+        if (flow.default) {
+            const p0 = flow.waypoints[0];
+            const p1 = flow.waypoints[1];
+            const dx = p1.x - p0.x;
+            const dy = p1.y - p0.y;
+            const len = Math.sqrt(dx * dx + dy * dy);
+            if (len >= 1) {
+                const nx = dx / len;
+                const ny = dy / len;
+                const HALF = 5;
+                const OFFSET = 8;
+                const cx = p0.x + ox + nx * OFFSET;
+                const cy = p0.y + oy + ny * OFFSET;
+                // Perpendicular slash: marks the default outflow per BPMN 2.0 §10.3.3
+                parts.push(`<line class="bpmn-default-mark" x1="${r(cx - ny * HALF)}" y1="${r(cy + nx * HALF)}" x2="${r(cx + ny * HALF)}" y2="${r(cy - nx * HALF)}"/>`);
+            }
+        }
+    }
+    for (const assoc of layout.associations) {
+        if (assoc.waypoints.length < 2)
+            continue;
+        const pts = assoc.waypoints.map((p) => `${r(p.x + ox)},${r(p.y + oy)}`).join(' ');
+        parts.push(`<polyline class="bpmn-assoc" points="${pts}"/>`);
+    }
+    return parts.join('\n');
+}
+/**
+ * Self-contained SVG for the BPMN process notation.
+ *
+ * Embeds the shared Transitrix theme CSS plus BPMN-specific rules so the
+ * output can be dropped into a static webview panel or saved as an `.svg`
+ * file. VS Code's dynamic preview (which supplies CSS separately via a
+ * webview stylesheet) should call `renderProcessBody` directly and wrap it
+ * with its own HTML shell.
+ */
+export function renderProcessLayoutSvg(layout, options = {}) {
+    const { title = '', topInset = title ? 32 : 0 } = options;
+    const pb = layout.poolBounds;
+    const PAD = 16;
+    const svgW = r(pb.x + pb.width + PAD);
+    const svgH = r(pb.y + pb.height + PAD + topInset);
+    const embedCss = generateSvgEmbedCss('transitrix') + BPMN_PROCESS_CSS;
+    const body = renderProcessBody(layout, 0, topInset);
+    return (`<svg xmlns="http://www.w3.org/2000/svg" width="${svgW}" height="${svgH}" viewBox="0 0 ${svgW} ${svgH}">\n` +
+        `<style>${embedCss}</style>\n` +
+        (title ? `${title}\n` : '') +
+        `${body}\n` +
+        `</svg>`);
+}

package/dist/webview/render-scenarios.js

@@ -9,7 +9,7 @@ const RELEVANCE_BADGE = {
     Medium: 'badge-medium',
     Low: 'badge-low',
 };
-function buildFactorsTable(factors) {
+function buildDriversTable(factors) {
     if (!factors || factors.length === 0)
         return '';
     const rows = factors
@@ -49,7 +49,7 @@ export function renderScenarioHtml(scn) {
   <p class="scn-vision-text">${escHtml(scn.vision)}</p>
 </section>`);
     }
-    blocks.push(buildFactorsTable(scn.factors_view));
+    blocks.push(buildDriversTable(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')));

package/dist/webview/render-util.d.ts

@@ -7,10 +7,23 @@
 export declare function escXml(s: string): string;
 /** Same encoding as `escXml`; aliased so HTML-table renderers read clearly. */
 export declare const escHtml: typeof escXml;
-/** Pull common frontmatter for the optional preview heading. */
-export declare function readDocHeader(doc: unknown): {
-    title?: string;
-    subtitle?: string;
-    version?: string;
-    date?: string;
+/**
+ * Extracts standard diagram-level metadata from a raw parsed YAML document.
+ *
+ * Per CONTRACT §1.1, every notation stores its canonical metadata at the root level:
+ *   name:         "Human-readable diagram title"  # required
+ *   generated_at: "YYYY-MM-DD"                    # optional
+ *
+ * Backward-compat reads: `title` (legacy alias for `name`), `date` (legacy alias
+ * for `generated_at`), and `description`/`version` which are not in the standard
+ * but widely present in existing files.
+ *
+ * Host-neutral so both the VS Code preview chrome and the webview bundle share a
+ * single metadata reader (review E). Accepts `unknown` and guards internally.
+ */
+export declare function extractDiagramMeta(doc: unknown): {
+    title: string | undefined;
+    subtitle: string | undefined;
+    date: string | undefined;
+    version: string | undefined;
 };

package/dist/webview/render-util.js

@@ -13,19 +13,27 @@ export function escXml(s) {
 }
 /** 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) {
-    if (!doc || typeof doc !== 'object')
-        return {};
-    const raw = doc;
-    const out = {};
-    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;
+/**
+ * Extracts standard diagram-level metadata from a raw parsed YAML document.
+ *
+ * Per CONTRACT §1.1, every notation stores its canonical metadata at the root level:
+ *   name:         "Human-readable diagram title"  # required
+ *   generated_at: "YYYY-MM-DD"                    # optional
+ *
+ * Backward-compat reads: `title` (legacy alias for `name`), `date` (legacy alias
+ * for `generated_at`), and `description`/`version` which are not in the standard
+ * but widely present in existing files.
+ *
+ * Host-neutral so both the VS Code preview chrome and the webview bundle share a
+ * single metadata reader (review E). Accepts `unknown` and guards internally.
+ */
+export function extractDiagramMeta(doc) {
+    const raw = (doc && typeof doc === 'object' ? doc : {});
+    const name = typeof raw['name'] === 'string' ? raw['name'] : undefined;
+    const title = name ?? (typeof raw['title'] === 'string' ? raw['title'] : undefined);
+    const subtitle = typeof raw['description'] === 'string' ? raw['description'] : undefined;
+    const genAt = typeof raw['generated_at'] === 'string' ? raw['generated_at'] : undefined;
+    const date = genAt ?? (typeof raw['date'] === 'string' ? raw['date'] : undefined);
+    const version = raw['version'] !== undefined ? String(raw['version']) : undefined;
+    return { title, subtitle, date, version };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transitrix/diagrams",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "type": "module",
   "description": "Shared rendering, validation, and pure mutations for Transitrix custom diagram formats.",
   "license": "MIT",
@@ -15,6 +15,20 @@
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js"
+    },
+    "./*": {
+      "types": "./dist/*/index.d.ts",
+      "import": "./dist/*/index.js"
+    }
+  },
   "files": [
     "dist",
     "src"

package/src/activities/__tests__/validate.test.ts

@@ -15,9 +15,43 @@ 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: Record<string, unknown> = {
+      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 as Array<Record<string, unknown>>)[0];
+    expect(entry['activity_type']).toBe('project');
   });
 
   it('ACT-001 — rejects missing notation', () => {

package/src/activities/cpm.ts

@@ -5,6 +5,18 @@ export function computeCpm(activities: Activity[]): CpmResult {
 
   if (activities.length === 0) return result;
 
+  // When no activity carries any duration data, critical path is indeterminate —
+  // return all non-critical so the diagram renders in default grey.
+  const hasDuration = activities.some(
+    (a) => (a.duration !== undefined && a.duration !== null) || (a.duration_days !== undefined && a.duration_days !== null),
+  );
+  if (!hasDuration) {
+    for (const a of activities) {
+      result.set(a.id, { es: 0, ef: 0, ls: 0, lf: 0, slack: 0, isCritical: false });
+    }
+    return result;
+  }
+
   // Build successor map and in-degree for topological sort
   const successors = new Map<string, string[]>();
   const predecessors = new Map<string, string[]>();
@@ -45,7 +57,7 @@ export function computeCpm(activities: Activity[]): CpmResult {
   const ef = new Map<string, number>();
   for (const id of topoOrder) {
     const a = actById.get(id)!;
-    const dur = a.duration ?? 0;
+    const dur = a.duration ?? a.duration_days ?? 0;
     const maxPredEf = Math.max(0, ...(predecessors.get(id) ?? []).map(p => ef.get(p) ?? 0));
     es.set(id, maxPredEf);
     ef.set(id, maxPredEf + dur);
@@ -59,7 +71,7 @@ export function computeCpm(activities: Activity[]): CpmResult {
   const lf = new Map<string, number>();
   for (const id of [...topoOrder].reverse()) {
     const a = actById.get(id)!;
-    const dur = a.duration ?? 0;
+    const dur = a.duration ?? a.duration_days ?? 0;
     const succs = successors.get(id) ?? [];
     const minSuccLs = succs.length === 0 ? projectFinish : Math.min(...succs.map(s => ls.get(s) ?? projectFinish));
     lf.set(id, minSuccLs);

package/src/activities/gantt.ts

@@ -113,9 +113,10 @@ function detectMode(doc: ActivityDoc, leaves: Activity[]): 'computed' | 'pinned'
   if (allPinned) return 'pinned';
   const hasProjectStart =
     typeof doc.project?.start_date === 'string' && doc.project.start_date.length > 0;
-  const allHaveDuration = leaves.every(
-    (a) => typeof a.duration === 'number' && Number.isFinite(a.duration) && a.duration >= 0,
-  );
+  const allHaveDuration = leaves.every((a) => {
+    const d = a.duration ?? a.duration_days;
+    return typeof d === 'number' && Number.isFinite(d) && d >= 0;
+  });
   if (hasProjectStart && allHaveDuration) return 'computed';
   return null;
 }
@@ -144,7 +145,7 @@ export function computeGanttLayout(doc: ActivityDoc): GanttResult {
     for (const a of leaves) {
       const startDate = a.start_date as string;
       const endDate = a.end_date as string;
-      const isMilestone = a.duration === 0 || startDate === endDate;
+      const isMilestone = (a.duration ?? a.duration_days) === 0 || startDate === endDate;
       const bar: GanttBar = {
         id: a.id,
         name: a.name,
@@ -166,7 +167,7 @@ export function computeGanttLayout(doc: ActivityDoc): GanttResult {
     for (const a of leaves) {
       const c = cpm.get(a.id);
       const es = c?.es ?? 0;
-      const dur = a.duration ?? 0;
+      const dur = a.duration ?? a.duration_days ?? 0;
       const startDate = nthWorkingDay(projectStart, es, calendar);
       const endDate = dur === 0
         ? startDate

package/src/activities/types.ts

@@ -15,6 +15,7 @@ export interface Activity {
   id: string;
   name: string;
   duration?: number;
+  duration_days?: number;
   activity_type?: string;
   goals?: string[];
   scenario?: string;