@transitrix/diagrams 1.6.0 → 1.8.1

package/dist/webview/render-process-blueprint.js

@@ -10,45 +10,24 @@
  * self-contained. No `vscode`, no `node:*`, no host APIs.
  */
 import { layoutProcessBlueprint } from '../process-blueprint/layout.js';
+import { parseNodeSizePreset, resolveProcessBlueprintSize, } from '../node-size-presets.js';
 import { generateSvgEmbedCss } from '../theme/index.js';
+import { layoutCenteredPillText, layoutLeftCellLines, maxCharsForInnerWidth, truncateLine, } from './entity-text-layout.js';
 import { escXml } from './render-util.js';
 const PAD = 24;
-// Blueprint-specific rules not carried by the shared theme CSS. The outer
-// border is drawn last on top of the clipped inner content; the row
-// backgrounds are transparent (pills/chips carry the colour). Mirrors
-// `BLUEPRINT_CSS` from the VS Code preview so the self-contained JCEF output
-// matches the editor.
 const BP_EMBED_CSS = `
 .bp-row-bg { fill: none; }
 .bp-border { fill: none; stroke: var(--ts-border, #cbd5e1); stroke-width: 1; }`;
-function truncate(text, maxChars) {
-    if (text.length <= maxChars)
-        return text;
-    return text.slice(0, Math.max(0, maxChars - 1)) + '…';
-}
-/**
- * Render a left-anchored, vertically centred multi-line text cell. `lines` are
- * pre-wrapped by the layout; the block is centred within the cell height.
- */
 function textCellSvg(lines, cls, x, cellTop, cellHeight, lineHeight) {
+    const specs = layoutLeftCellLines(lines, x, cellTop, cellHeight, lineHeight, cls);
     const ls = lines.length > 0 ? lines : [''];
     const first = cellTop + cellHeight / 2 - ((ls.length - 1) / 2) * lineHeight;
     const tspans = ls
         .map((ln, i) => `<tspan x="${x}" y="${first + i * lineHeight}">${escXml(ln)}</tspan>`)
         .join('');
+    void specs;
     return `<text class="${cls}" dominant-baseline="central">${tspans}</text>`;
 }
-/**
- * Render a single compliance law chip wrapped in a `<g data-chip-law…>` so the
- * VS Code host can wire click-to-drill-down. Other hosts (JCEF) simply ignore
- * the data attributes.
- *
- * Three orthogonal decorations are expressed as SVG overrides:
- * - `new`      — dashed stroke border  (`stroke-dasharray="4 2"`)
- * - `gap`      — warning-level fill    (`class="…compliance-gap"`)
- * - `deadline` — urgent fill override  (`class="…compliance-deadline"`) + a small
- *                badge circle in the top-right corner
- */
 function complianceChipSvg(chip, ox, oy, stageId) {
     const { x, y, width, height, lawId, decorations } = chip;
     const ax = x + ox;
@@ -62,9 +41,10 @@ function complianceChipSvg(chip, ox, oy, stageId) {
     else if (hasGap)
         rectClass += ' compliance-gap';
     const strokeDash = hasNew ? ' stroke-dasharray="4 2"' : '';
+    const maxChars = maxCharsForInnerWidth(Math.max(0, width - 8), 8);
     const parts = [];
     parts.push(`<rect class="${rectClass}" x="${ax}" y="${ay}" width="${width}" height="${height}" rx="6"${strokeDash}/>`);
-    parts.push(`<text class="text-pill" x="${ax + width / 2}" y="${ay + height / 2}" text-anchor="middle" dominant-baseline="central">${escXml(truncate(lawId, Math.floor(width / 8)))}</text>`);
+    parts.push(`<text class="text-pill" x="${ax + width / 2}" y="${ay + height / 2}" text-anchor="middle" dominant-baseline="central">${escXml(truncateLine(lawId, maxChars))}</text>`);
     if (hasDeadline) {
         const br = 5;
         const bx = ax + width - br - 3;
@@ -74,38 +54,23 @@ function complianceChipSvg(chip, ox, oy, stageId) {
     }
     return `<g data-chip-law="${escXml(lawId)}" data-chip-stage="${escXml(stageId)}">\n${parts.join('\n')}\n</g>`;
 }
-/**
- * Canonical Process Blueprint body — everything inside the `<svg>` except the
- * host-specific title block. Shared verbatim by the VS Code preview and the
- * host-neutral wrapper below so both surfaces stay pixel-identical.
- *
- * Layering: a clipped group holds the row fills and grid lines; pills and
- * compliance chips render on top (so grid lines sit under pill content); the
- * outer rounded border is drawn last so corner cells never overflow it.
- */
 export function renderProcessBlueprintBody(layout, ox, oy, clipId = 'bp-clip') {
     const tw = layout.bounds.width;
     const th = layout.bounds.height;
     const parts = [];
-    // Pills and chips collected separately so they render after (on top of) grid lines.
     const topParts = [];
-    // Outer background (fill only; border drawn last on top).
     parts.push(`<rect class="diagram-node level-0 bp-row-bg" x="${ox}" y="${oy}" width="${tw}" height="${th}" rx="6" stroke="none"/>`);
-    // ClipPath — clips all inner content to the outer rounded rect so corner cells
-    // don't visually overflow the rx=6 boundary.
     parts.push(`<defs><clipPath id="${clipId}"><rect x="${ox}" y="${oy}" width="${tw}" height="${th}" rx="6"/></clipPath></defs>`);
     const inner = [];
-    // Stage headers (top row).
+    const headerMaxChars = Math.max(8, Math.floor((layout.stageColumnWidth - 16) / 7));
     for (const s of layout.stageHeaders) {
         inner.push(`<rect class="diagram-node level-1" x="${s.x + ox}" y="${s.y + oy}" width="${s.width}" height="${s.height}" stroke="none"/>`);
-        inner.push(`<text class="text-header" x="${s.x + ox + s.width / 2}" y="${s.y + oy + s.height / 2}" text-anchor="middle" dominant-baseline="central">${escXml(truncate(s.name, 28))}</text>`);
+        inner.push(`<text class="text-header" x="${s.x + ox + s.width / 2}" y="${s.y + oy + s.height / 2}" text-anchor="middle" dominant-baseline="central">${escXml(truncateLine(s.name, headerMaxChars))}</text>`);
     }
-    // Legend column (row labels).
     for (const l of layout.legend) {
         inner.push(`<rect class="diagram-node level-2 bp-row-bg" x="${ox}" y="${l.y + oy}" width="${layout.legendColumnWidth}" height="${l.height}" stroke="none"/>`);
         inner.push(`<text class="text-primary" x="${ox + 12}" y="${l.y + oy + l.height / 2}" dominant-baseline="central">${escXml(l.label)}</text>`);
     }
-    // Goal and result cells.
     const textX = layout.cellTextPadX;
     for (const c of layout.goalCells) {
         inner.push(`<rect class="diagram-node level-3 bp-row-bg" x="${c.x + ox}" y="${c.y + oy}" width="${c.width}" height="${c.height}" stroke="none"/>`);
@@ -115,32 +80,22 @@ export function renderProcessBlueprintBody(layout, ox, oy, clipId = 'bp-clip') {
         inner.push(`<rect class="diagram-node level-4 bp-row-bg" x="${c.x + ox}" y="${c.y + oy}" width="${c.width}" height="${c.height}" stroke="none"/>`);
         inner.push(textCellSvg(c.lines, 'text-secondary', c.x + ox + textX, c.y + oy, c.height, layout.textLineHeight));
     }
-    // Aspect rows — transparent background; pills carry the colour.
     for (let r = 0; r < layout.aspectRows.length; r++) {
         const row = layout.aspectRows[r];
         const level = 5 + (r % 3);
         inner.push(`<rect class="diagram-node level-${level} bp-row-bg" x="${layout.legendColumnWidth + ox}" y="${row.y + oy}" width="${tw - layout.legendColumnWidth}" height="${row.height}" stroke="none"/>`);
         for (const p of row.pills) {
-            const cx = p.x + ox + p.width / 2;
-            const pillLH = 15;
-            // p.lines: name lines (possibly wrapped), optionally with id as last line.
             const hasIdLine = !!(p.id && p.lines.length > 0 && p.lines[p.lines.length - 1] === p.id);
             const nameLines = hasIdLine ? p.lines.slice(0, -1) : p.lines;
             const idLine = hasIdLine ? p.id : undefined;
-            const pillFirstY = p.y + oy + p.height / 2 - ((p.lines.length - 1) / 2) * pillLH;
+            const pillSpecs = layoutCenteredPillText(p.x + ox, p.y + oy, p.width, p.height, nameLines, idLine);
             topParts.push(`<rect class="diagram-node level-${level}" x="${p.x + ox}" y="${p.y + oy}" width="${p.width}" height="${p.height}" rx="6"/>`);
-            if (nameLines.length > 0) {
-                const tspans = nameLines
-                    .map((ln, i) => `<tspan x="${cx}" y="${pillFirstY + i * pillLH}">${escXml(ln)}</tspan>`)
-                    .join('');
-                topParts.push(`<text class="text-pill" text-anchor="middle" dominant-baseline="central">${tspans}</text>`);
-            }
-            if (idLine) {
-                topParts.push(`<text class="text-secondary" x="${cx}" y="${pillFirstY + nameLines.length * pillLH}" text-anchor="middle" dominant-baseline="central">${escXml(idLine)}</text>`);
+            for (const spec of pillSpecs) {
+                const anchor = spec.cls === 'text-pill' || spec.cls === 'text-secondary' ? ' text-anchor="middle"' : '';
+                topParts.push(`<text class="${spec.cls}" x="${spec.x}" y="${spec.y}"${anchor} dominant-baseline="central">${escXml(spec.text)}</text>`);
             }
         }
     }
-    // Compliance row (optional).
     if (layout.complianceRow) {
         const row = layout.complianceRow;
         inner.push(`<rect class="diagram-node level-5 bp-row-bg" x="${layout.legendColumnWidth + ox}" y="${row.y + oy}" width="${tw - layout.legendColumnWidth}" height="${row.height}" stroke="none"/>`);
@@ -149,7 +104,6 @@ export function renderProcessBlueprintBody(layout, ox, oy, clipId = 'bp-clip') {
             topParts.push(complianceChipSvg(chip, ox, oy, stageId));
         }
     }
-    // Grid lines — drawn before pills so they appear under pill content.
     const gridX1 = ox;
     const gridX2 = ox + tw;
     const gridY1 = oy;
@@ -168,15 +122,17 @@ export function renderProcessBlueprintBody(layout, ox, oy, clipId = 'bp-clip') {
         const stageLineX = ox + layout.legendColumnWidth + i * layout.stageColumnWidth;
         inner.push(`<line class="diagram-edge" x1="${stageLineX}" y1="${gridY1}" x2="${stageLineX}" y2="${gridY2}"/>`);
     }
-    // Inner content (fills + grid lines) clipped to rounded outer rect.
     parts.push(`<g clip-path="url(#${clipId})">${inner.join('\n')}${topParts.join('\n')}</g>`);
-    // Outer border on top — fill="none" as attribute so PNG export (no external CSS) never shows black.
     parts.push(`<rect class="bp-border" x="${ox}" y="${oy}" width="${tw}" height="${th}" rx="6" fill="none"/>`);
     return parts.join('\n');
 }
 export function renderProcessBlueprintSvg(doc, options = {}) {
-    const { title = '' } = options;
-    const layout = layoutProcessBlueprint(doc);
+    const { title = '', nodeSizePreset = 'normal', layoutOptions } = options;
+    const sizing = resolveProcessBlueprintSize(parseNodeSizePreset(nodeSizePreset));
+    const layout = layoutProcessBlueprint(doc, {
+        ...sizing,
+        ...layoutOptions,
+    });
     if (layout.bounds.width === 0 || layout.bounds.height === 0) {
         return `<svg xmlns="http://www.w3.org/2000/svg" width="0" height="0" viewBox="0 0 0 0"></svg>`;
     }
@@ -189,8 +145,6 @@ export function renderProcessBlueprintSvg(doc, options = {}) {
     const titleSvg = title
         ? `<text class="text-header" x="${PAD}" y="${PAD - 6}">${escXml(title)}</text>`
         : '';
-    // Embed the shared theme CSS plus the blueprint-specific rules inside the SVG
-    // so the rendered output is self-contained for the JCEF host.
     const embedCss = generateSvgEmbedCss('transitrix') + BP_EMBED_CSS;
     return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">
 <style>${embedCss}</style>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transitrix/diagrams",
-  "version": "1.6.0",
+  "version": "1.8.1",
   "type": "module",
   "description": "Shared rendering, validation, and pure mutations for Transitrix custom diagram formats.",
   "license": "MIT",

package/src/activities/layout.ts

@@ -1,13 +1,18 @@
 import type { ActivityDoc, Activity, ActivitiesLayout, ActivitiesLayoutOptions, LayoutNode, LayoutEdge } from './types.js';
 import { computeCpm } from './cpm.js';
 
-const NODE_W = 200;
-const NODE_H = 80;
+const DEFAULT_NODE_W = 200;
+const DEFAULT_NODE_H = 80;
 const H_GAP = 80;
 const V_GAP = 24;
 
 export function layoutActivities(doc: ActivityDoc, options: ActivitiesLayoutOptions = {}): ActivitiesLayout {
-  const { horizontalGap = H_GAP, verticalGap = V_GAP } = options;
+  const {
+    horizontalGap = H_GAP,
+    verticalGap = V_GAP,
+    nodeWidth = DEFAULT_NODE_W,
+    nodeHeight = DEFAULT_NODE_H,
+  } = options;
   const activities = doc.activities;
   if (activities.length === 0) {
     return { nodes: [], edges: [], bounds: { x: 0, y: 0, width: 0, height: 0 } };
@@ -70,21 +75,21 @@ export function layoutActivities(doc: ActivityDoc, options: ActivitiesLayoutOpti
 
   for (let c = 0; c < colCount; c++) {
     const list = cols.get(c) ?? [];
-    const x = c * (NODE_W + horizontalGap);
+    const x = c * (nodeWidth + horizontalGap);
     let y = 0;
     for (const a of list) {
       const node: LayoutNode = {
         id: a.id,
         x,
         y,
-        width: NODE_W,
-        height: NODE_H,
+        width: nodeWidth,
+        height: nodeHeight,
         data: a,
         cpm: cpm.get(a.id),
       };
       nodes.push(node);
       nodeMap.set(a.id, node);
-      y += NODE_H + verticalGap;
+      y += nodeHeight + verticalGap;
     }
   }
 

package/src/activities/types.ts

@@ -100,6 +100,10 @@ export interface ActivitiesLayoutOptions {
   horizontalGap?: number;
   /** Vertical gap (px) between stacked activity nodes. Default matches the historical hardcoded value. */
   verticalGap?: number;
+  /** Activity node width (px). Default 200. */
+  nodeWidth?: number;
+  /** Activity node height (px). Default 80. */
+  nodeHeight?: number;
 }
 
 // ── Gantt view (spec §9) ─────────────────────────────────────────────────────

package/src/capability-map/dsm-schema.ts

@@ -1,5 +1,5 @@
 /**
- * Types for the DSM-migration capability map (docs/extraction/capability-map.md).
+// Types for the DSM-migration capability map (docs/internal/extraction/capability-map.md).
  *
  * Distinct from `./types.ts` (`CapabilityNode`/`CapabilityMapFile`), which is
  * Transitrix's own native `*.capability-map.transitrix.yaml` notation — a

package/src/capability-map/index.ts

@@ -18,7 +18,7 @@ export { layoutCapabilityTree, TREE_NODE_WIDTH, TREE_NODE_HEIGHT, TREE_RANK_SEP,
 export type { RenderCapabilityTreeOptions } from './render-capability-tree.js';
 export { renderCapabilityTreeSvg } from './render-capability-tree.js';
 
-// ── DSM-migration capability map (docs/extraction/capability-map.md) ───────
+// ── DSM-migration capability map (docs/internal/extraction/capability-map.md) ───────
 // A separate, flat, address-triple data model from CapabilityNode above —
 // see dsm-schema.ts for why the two coexist in this folder. Named
 // `validateCapabilityMapData` rather than `validateCapabilityMap` because

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

@@ -40,10 +40,18 @@ export interface CapabilityTreeLayout {
   levelCounts: CapabilityTreeLevelCounts;
 }
 
+export interface CapabilityTreeLayoutOptions {
+  nodeWidth?: number;
+  nodeHeight?: number;
+}
+
 export function layoutCapabilityTree(
   map: CapabilityMapHeader,
   collapsedIds: Set<string> = new Set(),
+  options: CapabilityTreeLayoutOptions = {},
 ): CapabilityTreeLayout {
+  const nodeWidth = options.nodeWidth ?? TREE_NODE_WIDTH;
+  const nodeHeight = options.nodeHeight ?? TREE_NODE_HEIGHT;
   const nodes: CapabilityTreeNode[] = [];
   const edges: CapabilityTreeEdge[] = [];
 
@@ -60,13 +68,13 @@ export function layoutCapabilityTree(
     const hasChildren = Boolean(node.children?.length);
     const visibleChildren = !isCollapsed && node.children?.length ? node.children : [];
 
-    const x = depth * (TREE_NODE_WIDTH + TREE_RANK_SEP);
+    const x = depth * (nodeWidth + 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 };
+      advanceY(depth, nodeHeight + TREE_NODE_SEP);
+      nodes.push({ id: node.id, x, y, width: nodeWidth, height: nodeHeight, data: node, depth, hasChildren, isCollapsed });
+      return { top: y, bottom: y + nodeHeight };
     }
 
     const childSpans: Array<{ top: number; bottom: number }> = [];
@@ -77,14 +85,14 @@ export function layoutCapabilityTree(
 
     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 parentY = spanTop + (spanBottom - spanTop) / 2 - nodeHeight / 2;
 
     const curColY = getNextY(depth);
     const finalY = Math.max(parentY, curColY);
-    advanceY(depth, finalY - curColY + TREE_NODE_HEIGHT + TREE_NODE_SEP);
+    advanceY(depth, finalY - curColY + nodeHeight + 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) };
+    nodes.push({ id: node.id, x, y: finalY, width: nodeWidth, height: nodeHeight, data: node, depth, hasChildren, isCollapsed });
+    return { top: Math.min(finalY, spanTop), bottom: Math.max(finalY + nodeHeight, spanBottom) };
   }
 
   for (const root of map.capabilities) {

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

@@ -1,13 +1,13 @@
 import type { CapabilityMapHeader } from './types.js';
-import { layoutCapabilityTree, TREE_NODE_WIDTH, TREE_NODE_HEIGHT, TREE_NODE_SEP } from './layout-tree.js';
+import { layoutCapabilityTree, TREE_NODE_SEP } from './layout-tree.js';
 import { horizontalCubicEdgePath, DEFAULT_EDGE_CURVATURE } from '../edge-path.js';
+import { parseNodeSizePreset, resolveCapabilityMapNodeSize, type NodeSizePreset } from '../node-size-presets.js';
+import { maxCharsForInnerWidth, truncateLine } from '../webview/entity-text-layout.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;
 
@@ -17,30 +17,19 @@ function depthBand(depth: number): 0 | 1 | 2 {
   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;
+  nodeSizePreset?: NodeSizePreset;
 }
 
-/**
- * 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);
+  const { collapsedIds = new Set(), curvature = DEFAULT_EDGE_CURVATURE, nodeSizePreset = 'normal' } = opts;
+  const nodeSize = resolveCapabilityMapNodeSize(parseNodeSizePreset(nodeSizePreset));
+  const layout = layoutCapabilityTree(map, collapsedIds, nodeSize);
 
   if (layout.nodes.length === 0) {
     return `<svg xmlns="http://www.w3.org/2000/svg" width="0" height="0" viewBox="0 0 0 0"></svg>`;
@@ -70,23 +59,22 @@ export function renderCapabilityTreeSvg(
     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 textAreaW = Math.max(0, n.width - badgeW - 26);
+    const maxChars = maxCharsForInnerWidth(textAreaW, 7);
+    const nameText = truncateLine(n.data.name, maxChars);
+    const nameTitle = n.data.name.length > maxChars ? escXml(n.data.name) : '';
+
     const badgeX = x + 10;
-    const badgeY = y + (TREE_NODE_HEIGHT - badgeH) / 2;
+    const badgeY = y + (n.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;
+    const nameY = y + n.height / 2 - 8;
+    const idY = y + n.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 btnCx = x + n.width;
+    const btnCy = y + n.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}"/>
@@ -94,7 +82,7 @@ export function renderCapabilityTreeSvg(
       : '';
 
     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-level-${band}" x="${x}" y="${y}" width="${n.width}" height="${n.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>

package/src/codex/__tests__/example.test.ts

@@ -0,0 +1,40 @@
+// Conformance test for CODEX worked examples under
+// `tests/fixtures/notation-corpus/codex/` — pins #518 Phase C2 corpus signal.
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { validateCodex, folderJurisdictionFromPath } from '../validate.js';
+
+const corpusRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../../../tests/fixtures/notation-corpus/codex',
+);
+
+function codexFixturePaths(): Array<{ rel: string; folderJurisdiction?: string }> {
+  const out: Array<{ rel: string; folderJurisdiction?: string }> = [];
+  for (const zone of ['external/EU', 'internal']) {
+    const dir = path.join(corpusRoot, zone);
+    for (const f of readdirSync(dir).filter((x) => x.endsWith('.yaml'))) {
+      const rel = path.join('codex', zone, f).replace(/\\/g, '/');
+      out.push({
+        rel,
+        folderJurisdiction: folderJurisdictionFromPath(rel),
+      });
+    }
+  }
+  return out;
+}
+
+describe('codex worked examples (notation-corpus)', () => {
+  for (const { rel, folderJurisdiction } of codexFixturePaths()) {
+    it(`validates ${rel} without error`, () => {
+      const data = yaml.load(readFileSync(path.join(corpusRoot, rel.replace(/^codex\//, '')), 'utf-8'));
+      const v = validateCodex(data, { folderJurisdiction });
+      expect(v.valid, JSON.stringify(v.errors)).toBe(true);
+      expect(v.errors).toHaveLength(0);
+    });
+  }
+});

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

@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest';
+import {
+  validateCodex,
+  isCodexDoc,
+  folderJurisdictionFromPath,
+} from '../validate.js';
+
+const VALID_EXTERNAL = {
+  zone: 'codex',
+  id: 'LAW-GDPR-1',
+  name: 'General Data Protection Regulation',
+  type: 'LAW',
+  jurisdiction: 'eu',
+  effective_date: '2018-05-25',
+  admitted_at: '2026-06-01',
+  admitted_by: 'legal.team',
+  gate_checks: { uniqueness: 'pass' },
+};
+
+const VALID_INTERNAL = {
+  zone: 'codex',
+  id: 'INTERNAL_STANDARD-coding-conventions-1',
+  name: 'Engineering Coding Conventions',
+  type: 'INTERNAL_STANDARD',
+  issuing_authority: 'VP Engineering',
+  effective_date: '2026-01-01',
+  admitted_at: '2026-05-27',
+  admitted_by: 'vp.engineering',
+  gate_checks: { source_authority: 'VP Engineering' },
+};
+
+describe('validateCodex', () => {
+  it('accepts a valid external artefact', () => {
+    const r = validateCodex(VALID_EXTERNAL, { folderJurisdiction: 'eu' });
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+  });
+
+  it('accepts a valid internal artefact', () => {
+    expect(validateCodex(VALID_INTERNAL).valid).toBe(true);
+  });
+
+  it('CODEX-001 rejects non-mapping input', () => {
+    expect(validateCodex(null).errors.some((e) => e.code === 'CODEX-001')).toBe(true);
+  });
+
+  it('CODEX-001 rejects wrong zone', () => {
+    const r = validateCodex({ ...VALID_EXTERNAL, zone: 'canon' });
+    expect(r.errors.some((e) => e.code === 'CODEX-001' && e.path === 'zone')).toBe(true);
+  });
+
+  it('CODEX-002 rejects type/id prefix mismatch', () => {
+    const r = validateCodex({ ...VALID_EXTERNAL, type: 'REGULATION' });
+    expect(r.errors.some((e) => e.code === 'CODEX-002')).toBe(true);
+  });
+
+  it('CODEX-003 requires jurisdiction on external artefacts', () => {
+    const r = validateCodex({ ...VALID_EXTERNAL, jurisdiction: '' });
+    expect(r.errors.some((e) => e.code === 'CODEX-003' && e.path === 'jurisdiction')).toBe(true);
+  });
+
+  it('CODEX-005 enforces folder jurisdiction match', () => {
+    const r = validateCodex(VALID_EXTERNAL, { folderJurisdiction: 'ge' });
+    expect(r.errors.some((e) => e.code === 'CODEX-005')).toBe(true);
+  });
+
+  it('CODEX-004 requires issuing_authority on internal artefacts', () => {
+    const r = validateCodex({ ...VALID_INTERNAL, issuing_authority: '' });
+    expect(r.errors.some((e) => e.code === 'CODEX-004')).toBe(true);
+  });
+});
+
+describe('isCodexDoc', () => {
+  it('detects zone: codex', () => {
+    expect(isCodexDoc({ zone: 'codex', id: 'LAW-1' })).toBe(true);
+    expect(isCodexDoc({ zone: 'canon' })).toBe(false);
+  });
+});
+
+describe('folderJurisdictionFromPath', () => {
+  it('parses codex/external/<jurisdiction>/ paths', () => {
+    expect(folderJurisdictionFromPath('codex/external/eu/LAW-GDPR-1.yaml')).toBe('eu');
+    expect(folderJurisdictionFromPath('codex/internal/POLICY-1.yaml')).toBeUndefined();
+  });
+});

package/src/codex/index.ts

@@ -0,0 +1,4 @@
+export { CODEX_ARTEFACT_TYPES, EXTERNAL_CODEX_TYPES, INTERNAL_CODEX_TYPES } from './types.js';
+export type { CodexArtefactType } from './types.js';
+export { validateCodex, isCodexDoc, folderJurisdictionFromPath } from './validate.js';
+export type { CodexValidateOptions } from './validate.js';

package/src/codex/types.ts

@@ -0,0 +1,13 @@
+// Codex artefact — external laws/regulations and internal policies/standards.
+// Schema: methodology notations/elements/14-codex.md §3–§4.
+
+/** TYPE prefixes admitted in the codex zone (REQ-003 / 14-codex.md). */
+export const CODEX_ARTEFACT_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD'] as const;
+
+export type CodexArtefactType = (typeof CODEX_ARTEFACT_TYPES)[number];
+
+/** External codex artefacts (codex/external/<jurisdiction>/). */
+export const EXTERNAL_CODEX_TYPES: readonly CodexArtefactType[] = ['LAW', 'REGULATION'];
+
+/** Internal codex artefacts (codex/internal/). */
+export const INTERNAL_CODEX_TYPES: readonly CodexArtefactType[] = ['POLICY', 'INTERNAL_STANDARD'];