@transitrix/diagrams 1.0.0

package/src/target-state/__tests__/validate.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from 'vitest';
+import { validateTargetState } from '../validate.js';
+
+function valid(): Record<string, unknown> {
+  return {
+    notation: 'target-state',
+    id: 'TARGET_STATE-EU-LIVE-1',
+    name: 'EU operations live — three markets, localised CRM and payments',
+    description: 'The structural end-state in which Acme operates in three EU markets.',
+    capabilities: ['CAPABILITY-V1', 'CAPABILITY-V1.2', 'CAPABILITY-V2'],
+    processes: ['PROCESS-CUST-ONBOARD-1', 'PROCESS-ORD-FULFILL-1'],
+    applications: ['APPLICATION-CRM-1', 'APPLICATION-OMS-1'],
+    zone: 'canon',
+    admitted_at: '2026-05-31',
+    admitted_by: 'v.korobeinikov',
+    gate_checks: { uniqueness: 'pass', consistency: 'pass', completeness: 'pass' },
+    valid_from: '2026-05-31',
+    valid_to: null,
+  };
+}
+
+const codes = (input: unknown): string[] => validateTargetState(input).errors.map(e => e.code);
+
+describe('validateTargetState — positive', () => {
+  it('accepts the worked-example TARGET_STATE-EU-LIVE-1', () => {
+    const r = validateTargetState(valid());
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+    expect(r.errors).toHaveLength(0);
+  });
+
+  it('accepts a minimal target state (name + envelope only)', () => {
+    const r = valid();
+    delete r.capabilities;
+    delete r.processes;
+    delete r.applications;
+    expect(validateTargetState(r).valid).toBe(true);
+  });
+});
+
+describe('validateTargetState — TARGET_STATE-001 (envelope / shape)', () => {
+  it('flags a non-object', () => {
+    expect(codes(null)).toEqual(['TARGET_STATE-001']);
+  });
+
+  it('flags a wrong notation tag', () => {
+    expect(codes({ ...valid(), notation: 'plateau' })).toContain('TARGET_STATE-001');
+  });
+
+  it('flags an id with the wrong TYPE prefix', () => {
+    expect(codes({ ...valid(), id: 'SCENARIO-EU-LIVE-1' })).toContain('TARGET_STATE-001');
+  });
+
+  it('flags an inline goals field (it belongs on a REL)', () => {
+    expect(codes({ ...valid(), goals: ['GOAL-EU-1'] })).toContain('TARGET_STATE-001');
+  });
+});
+
+describe('validateTargetState — TARGET_STATE-002 (composition refs)', () => {
+  it('flags a non-CAPABILITY id in capabilities', () => {
+    expect(codes({ ...valid(), capabilities: ['PROCESS-X-1'] })).toContain('TARGET_STATE-002');
+  });
+
+  it('flags a non-PROCESS id in processes', () => {
+    expect(codes({ ...valid(), processes: ['CAPABILITY-V1'] })).toContain('TARGET_STATE-002');
+  });
+
+  it('flags a non-APPLICATION id in applications', () => {
+    expect(codes({ ...valid(), applications: ['PRODUCT-X-1'] })).toContain('TARGET_STATE-002');
+  });
+
+  it('flags a composition field that is not an array', () => {
+    expect(codes({ ...valid(), capabilities: 'CAPABILITY-V1' })).toContain('TARGET_STATE-002');
+  });
+});

package/src/target-state/index.ts

@@ -0,0 +1,2 @@
+export type { TargetState } from './types.js';
+export { validateTargetState } from './validate.js';

package/src/target-state/types.ts

@@ -0,0 +1,28 @@
+// TARGET_STATE — implementation-layer plateau primitive (ArchiMate Plateau).
+// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.17 + envelope §3.
+//
+// The id TYPE prefix is `TARGET_STATE` (underscore — uppercase identifier in
+// IDS_AND_REFERENCES.md §3.1). The notation tag is the lowercased hyphenated
+// short name `target-state` (per ELEMENT_PRIMITIVES.md §4).
+
+import type { GateChecks } from '../requirement/types.js';
+
+export interface TargetState {
+  notation: 'target-state';
+  id: string;
+  name: string;
+  /** Composition lists are inline; they are timeless on the element file. */
+  capabilities?: string[];
+  processes?: string[];
+  applications?: string[];
+  description?: string;
+  link?: string;
+
+  zone: 'canon';
+  admitted_at: string;
+  admitted_by: string;
+  gate_checks: GateChecks;
+
+  valid_from: string;
+  valid_to: string | null;
+}

package/src/target-state/validate.ts

@@ -0,0 +1,67 @@
+// TARGET_STATE validator — methodology notations/ELEMENT_PRIMITIVES.md §7.17.
+//
+// Implements TARGET_STATE-001..002. Goal-satisfaction lives on the
+// `target_state_satisfies_goal` REL kind (elements/17-relations.md §3) and is
+// never inline here; a `goals:` field on a TARGET_STATE is flagged.
+
+import type { ValidationError, ValidationResult, ValidationWarning } from '../validation-types.js';
+import { typeOfId } from '../typed-id.js';
+import { validateElementEnvelope } from '../element-envelope.js';
+
+/** Composition fields and the TYPE each entry must carry. */
+const COMPOSITION_TYPES = {
+  capabilities: 'CAPABILITY',
+  processes: 'PROCESS',
+  applications: 'APPLICATION',
+} as const;
+
+export function validateTargetState(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  const { record, errors: envErrors } = validateElementEnvelope(input, {
+    notation: 'target-state',
+    idType: 'TARGET_STATE',
+    code: 'TARGET_STATE-001',
+  });
+  errors.push(...envErrors);
+  if (!record) return { valid: false, errors, warnings };
+
+  // TARGET_STATE-002 — composition entries must carry the right TYPE prefix.
+  for (const [field, expectedType] of Object.entries(COMPOSITION_TYPES)) {
+    const value = record[field];
+    if (value === undefined) continue;
+    if (!Array.isArray(value)) {
+      errors.push({
+        code: 'TARGET_STATE-002',
+        message: `${field} must be a list of ${expectedType} typed IDs.`,
+        path: field,
+      });
+      continue;
+    }
+    value.forEach((ref, i) => {
+      // CAPABILITY uses a V/H terminal (e.g. CAPABILITY-V1.2) rather than a
+      // plain integer; the prefix-TYPE gate is what this validator enforces,
+      // and the V/H grammar is owned by the capability-map module.
+      if (typeOfId(ref) !== expectedType) {
+        errors.push({
+          code: 'TARGET_STATE-002',
+          message: `${field}[${i}] "${String(ref)}" must be a ${expectedType} typed ID.`,
+          path: `${field}[${i}]`,
+        });
+      }
+    });
+  }
+
+  // TARGET_STATE-001 — `goals:` is not an inline field on this element. Goal
+  // satisfaction is a target_state_satisfies_goal REL (§7.17).
+  if ('goals' in record) {
+    errors.push({
+      code: 'TARGET_STATE-001',
+      message: 'goals is not an inline field on TARGET_STATE — use a target_state_satisfies_goal REL.',
+      path: 'goals',
+    });
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/theme/index.ts

@@ -0,0 +1,4 @@
+export type { AdaptiveTokens } from './tokens.js';
+export { BRAND, FUNCTIONAL, LAYER_COLORS, LEVEL_COLORS, MATURITY_COLORS, STRUCTURAL, TYPOGRAPHY, CSS_VAR, getBaseResetCss } from './tokens.js';
+export type { ThemeId } from './themes.js';
+export { generateWebviewCss, generateSvgEmbedCss } from './themes.js';

package/src/theme/themes.ts

@@ -0,0 +1,237 @@
+import {
+  LAYER_COLORS,
+  LEVEL_COLORS,
+  MATURITY_COLORS,
+  STRUCTURAL,
+  TYPOGRAPHY,
+  CSS_VAR,
+  getBaseResetCss,
+  type AdaptiveTokens,
+} from './tokens.js';
+
+export type ThemeId = 'transitrix' | 'transitrix-dark' | 'vscode-adaptive';
+
+const TRANSITRIX_LIGHT: AdaptiveTokens = {
+  bg:              '#ffffff',
+  bgSurface:       '#f8fafc',
+  bgElevated:      '#f1f5f9',
+  text:            '#0f172a',
+  textMuted:       '#64748b',
+  textInverse:     '#ffffff',
+  border:          '#e2e8f0',
+  divider:         '#cbd5e1',
+  statusSuccessBg: '#d1fae5',
+  statusSuccessFg: '#065f46',
+  statusWarningBg: '#fef9c3',
+  statusWarningFg: '#854d0e',
+  statusInfoBg:    '#e0f2fe',
+  statusInfoFg:    '#0c4a6e',
+  statusErrorBg:   '#fee2e2',
+  statusErrorFg:   '#991b1b',
+};
+
+const TRANSITRIX_DARK: AdaptiveTokens = {
+  bg:              '#0a1628',
+  bgSurface:       '#0f1f3d',
+  bgElevated:      '#162544',
+  text:            '#f1f5f9',
+  textMuted:       '#94a3b8',
+  textInverse:     '#0f172a',
+  border:          '#1e3a5f',
+  divider:         '#1a3050',
+  statusSuccessBg: '#022c22',
+  statusSuccessFg: '#6ee7b7',
+  statusWarningBg: '#1e1500',
+  statusWarningFg: '#fcd34d',
+  statusInfoBg:    '#071e2e',
+  statusInfoFg:    '#7dd3fc',
+  statusErrorBg:   '#2c0a0a',
+  statusErrorFg:   '#fca5a5',
+};
+
+function adaptiveVars(t: AdaptiveTokens): string {
+  return [
+    `${CSS_VAR.bg}:${t.bg}`,
+    `${CSS_VAR.bgSurface}:${t.bgSurface}`,
+    `${CSS_VAR.bgElevated}:${t.bgElevated}`,
+    `${CSS_VAR.text}:${t.text}`,
+    `${CSS_VAR.textMuted}:${t.textMuted}`,
+    `${CSS_VAR.textInverse}:${t.textInverse}`,
+    `${CSS_VAR.border}:${t.border}`,
+    `${CSS_VAR.divider}:${t.divider}`,
+    `${CSS_VAR.statusSuccessBg}:${t.statusSuccessBg}`,
+    `${CSS_VAR.statusSuccessFg}:${t.statusSuccessFg}`,
+    `${CSS_VAR.statusWarningBg}:${t.statusWarningBg}`,
+    `${CSS_VAR.statusWarningFg}:${t.statusWarningFg}`,
+    `${CSS_VAR.statusInfoBg}:${t.statusInfoBg}`,
+    `${CSS_VAR.statusInfoFg}:${t.statusInfoFg}`,
+    `${CSS_VAR.statusErrorBg}:${t.statusErrorBg}`,
+    `${CSS_VAR.statusErrorFg}:${t.statusErrorFg}`,
+  ].join(';') + ';';
+}
+
+function diagramVars(variant: 'light' | 'dark' | 'hc'): string {
+  const lc = LAYER_COLORS;
+  const sc = STRUCTURAL;
+  const lv = LEVEL_COLORS[variant];
+  const mat = MATURITY_COLORS[variant];
+  const levelVars = lv.map((c, i) => `--ts-level-${i}:${c}`).join(';') + ';';
+  return [
+    `${CSS_VAR.layerFactor}:${lc.factor[variant]}`,
+    `${CSS_VAR.layerGoal}:${lc.goal[variant]}`,
+    `${CSS_VAR.layerChange}:${lc.change[variant]}`,
+    `${CSS_VAR.layerActivity}:${lc.activity[variant]}`,
+    `${CSS_VAR.nodeStroke}:${sc.nodeStroke[variant]}`,
+    `${CSS_VAR.edgeStroke}:${sc.edgeStroke[variant]}`,
+    `${CSS_VAR.textPrimary}:${sc.textPrimary[variant]}`,
+    `${CSS_VAR.textSecondary}:${sc.textSecondary[variant]}`,
+    `${CSS_VAR.headerText}:${sc.headerText[variant]}`,
+    `${CSS_VAR.maturity1}:${mat[0]}`,
+    `${CSS_VAR.maturity2}:${mat[1]}`,
+    `${CSS_VAR.maturity3}:${mat[2]}`,
+    `${CSS_VAR.maturity4}:${mat[3]}`,
+    `${CSS_VAR.maturity5}:${mat[4]}`,
+  ].join(';') + ';' + levelVars;
+}
+
+/** CSS for the webview shell (toolbar, canvas). */
+function shellCss(): string {
+  const cv = CSS_VAR;
+  const t = TYPOGRAPHY;
+  // Full-height flex chain lifted from blocks-preview / activities-preview
+  // into the shared shell (per strategy hub #35). Body is a flex column
+  // sized to the iframe; #canvas takes the remaining height with its own
+  // scroll region. Without this, #canvas was content-height and any
+  // overflow-x scrollbar landed mid-panel with empty space below it — the
+  // "two-page" split flagged on goals, activities, and others.
+  //
+  // html bg + min-height are set per-theme in generateWebviewCss (literal
+  // hex / VS Code var) so they don't depend on `--ts-bg` resolving on html —
+  // CSS custom properties only cascade DOWN, and `--ts-bg` is defined on the
+  // body[data-theme] selector, so html itself can't read it. Without that
+  // explicit html bg, the iframe's underlying VS Code editor background
+  // showed through any uncovered area below short diagrams.
+  return `html,body{height:100%;}
+body{background:var(${cv.bg});color:var(${cv.text});display:flex;flex-direction:column;}
+#toolbar{position:sticky;top:0;z-index:10;padding:6px 12px;border-bottom:1px solid var(${cv.border});font-family:${t.fontFamily};font-size:${t.sizes.secondary}px;color:var(${cv.textMuted});background:var(${cv.bg});flex-shrink:0;}
+#canvas{flex:1;min-height:0;padding:16px;overflow:auto;}
+svg{display:block;}`;
+}
+
+/** CSS for SVG diagram classes — all consume --ts-* variables. */
+function diagramClassCss(): string {
+  const cv = CSS_VAR;
+  const t = TYPOGRAPHY;
+  const levelCount = LEVEL_COLORS.light.length;
+  const levelRules = Array.from({ length: levelCount }, (_, i) =>
+    `.level-${i}{fill:var(--ts-level-${i});}`
+  ).join('');
+  // Typography: every <text> in a preview SVG resolves font-family, size and
+  // weight from these classes instead of inline attributes. That is the
+  // contract every notation preview honours so the catalogue reads as one
+  // visual family.
+  return `.diagram-node{stroke:var(${cv.nodeStroke});stroke-width:1;}
+.layer-factor{fill:var(${cv.layerFactor});}
+.layer-goal{fill:var(${cv.layerGoal});}
+.layer-change{fill:var(${cv.layerChange});}
+.layer-activity{fill:var(${cv.layerActivity});}
+${levelRules}
+.diagram-edge{stroke:var(${cv.edgeStroke});stroke-width:1.5;fill:none;}
+.arrow-fill{fill:var(${cv.edgeStroke});}
+.text-header{fill:var(${cv.headerText});font-family:${t.fontFamily};font-size:${t.sizes.header}px;font-weight:${t.weights.header};}
+.text-primary{fill:var(${cv.textPrimary});font-family:${t.fontFamily};font-size:${t.sizes.primary}px;font-weight:${t.weights.primary};}
+.text-secondary{fill:var(${cv.textSecondary});font-family:${t.fontFamily};font-size:${t.sizes.secondary}px;font-weight:${t.weights.secondary};}
+.text-id{fill:var(${cv.textSecondary});font-family:${t.fontFamily};font-size:${t.sizes.id}px;font-weight:${t.weights.id};}
+.text-pill{fill:var(${cv.textPrimary});font-family:${t.fontFamily};font-size:${t.sizes.pill}px;font-weight:${t.weights.pill};}
+.maturity-1{fill:var(${cv.maturity1});}
+.maturity-2{fill:var(${cv.maturity2});}
+.maturity-3{fill:var(${cv.maturity3});}
+.maturity-4{fill:var(${cv.maturity4});}
+.maturity-5{fill:var(${cv.maturity5});}
+.compliance-gap{fill:var(${cv.statusWarningBg});stroke:var(${cv.statusWarningFg});}
+.compliance-gap text{fill:var(${cv.statusWarningFg});}
+.compliance-deadline{fill:var(${cv.statusErrorBg});stroke:var(${cv.statusErrorFg});}
+.compliance-deadline text{fill:var(${cv.statusErrorFg});}
+.compliance-badge{fill:var(${cv.statusErrorFg});}
+.compliance-badge-text{fill:var(${cv.textInverse});font-family:${t.fontFamily};font-size:8px;font-weight:700;}`;
+}
+
+/**
+ * Generates a self-contained CSS block for embedding inside a standalone SVG file.
+ * Defines all --ts-* custom properties on :root so diagram classes resolve correctly
+ * when the SVG is opened outside of VS Code.
+ * vscode-adaptive falls back to the light palette (runtime VS Code variables are unavailable).
+ */
+export function generateSvgEmbedCss(themeId: ThemeId): string {
+  const variant = themeId === 'transitrix-dark' ? 'dark' : 'light';
+  const adaptive = themeId === 'transitrix-dark' ? TRANSITRIX_DARK : TRANSITRIX_LIGHT;
+  return `:root{${adaptiveVars(adaptive)}${diagramVars(variant)}}${diagramClassCss()}`;
+}
+
+/**
+ * Generates complete CSS for a static SVG diagram webview.
+ *
+ * For transitrix/transitrix-dark: sets --ts-* vars with fixed brand colors.
+ * For vscode-adaptive: maps --ts-* vars to --vscode-* CSS vars, with
+ * body.vscode-dark / body.vscode-high-contrast overrides for diagram colors.
+ */
+export function generateWebviewCss(themeId: ThemeId): string {
+  const base = getBaseResetCss();
+  const shell = shellCss();
+  const classes = diagramClassCss();
+
+  if (themeId === 'transitrix') {
+    return `${base}
+html{background:${TRANSITRIX_LIGHT.bg};min-height:100vh;}
+body[data-theme="transitrix"]{${adaptiveVars(TRANSITRIX_LIGHT)}${diagramVars('light')}}
+${shell}
+${classes}`;
+  }
+
+  if (themeId === 'transitrix-dark') {
+    return `${base}
+html{background:${TRANSITRIX_DARK.bg};min-height:100vh;}
+body[data-theme="transitrix-dark"]{${adaptiveVars(TRANSITRIX_DARK)}${diagramVars('dark')}}
+${shell}
+${classes}`;
+  }
+
+  // vscode-adaptive: map --ts-shell vars to --vscode-* CSS variables;
+  // layer/level/structural colors follow the VS Code theme body class.
+  const cv = CSS_VAR;
+  return `${base}
+html{background:var(--vscode-editor-background,${TRANSITRIX_LIGHT.bg});min-height:100vh;}
+body[data-theme="vscode-adaptive"]{
+  ${cv.bg}:var(--vscode-editor-background);
+  ${cv.bgSurface}:var(--vscode-sideBar-background,var(--vscode-editor-background));
+  ${cv.bgElevated}:var(--vscode-editorHoverWidget-background,var(--vscode-editor-background));
+  ${cv.text}:var(--vscode-foreground);
+  ${cv.textMuted}:var(--vscode-descriptionForeground);
+  ${cv.textInverse}:var(--vscode-editor-background);
+  ${cv.border}:var(--vscode-panel-border);
+  ${cv.divider}:var(--vscode-panel-border);
+  ${cv.statusSuccessBg}:${TRANSITRIX_LIGHT.statusSuccessBg};
+  ${cv.statusSuccessFg}:${TRANSITRIX_LIGHT.statusSuccessFg};
+  ${cv.statusWarningBg}:${TRANSITRIX_LIGHT.statusWarningBg};
+  ${cv.statusWarningFg}:${TRANSITRIX_LIGHT.statusWarningFg};
+  ${cv.statusInfoBg}:${TRANSITRIX_LIGHT.statusInfoBg};
+  ${cv.statusInfoFg}:${TRANSITRIX_LIGHT.statusInfoFg};
+  ${cv.statusErrorBg}:${TRANSITRIX_LIGHT.statusErrorBg};
+  ${cv.statusErrorFg}:${TRANSITRIX_LIGHT.statusErrorFg};
+  ${diagramVars('light')}
+}
+body[data-theme="vscode-adaptive"].vscode-dark{
+  ${cv.statusSuccessBg}:${TRANSITRIX_DARK.statusSuccessBg};
+  ${cv.statusSuccessFg}:${TRANSITRIX_DARK.statusSuccessFg};
+  ${cv.statusWarningBg}:${TRANSITRIX_DARK.statusWarningBg};
+  ${cv.statusWarningFg}:${TRANSITRIX_DARK.statusWarningFg};
+  ${cv.statusInfoBg}:${TRANSITRIX_DARK.statusInfoBg};
+  ${cv.statusInfoFg}:${TRANSITRIX_DARK.statusInfoFg};
+  ${cv.statusErrorBg}:${TRANSITRIX_DARK.statusErrorBg};
+  ${cv.statusErrorFg}:${TRANSITRIX_DARK.statusErrorFg};
+  ${diagramVars('dark')}
+}
+body[data-theme="vscode-adaptive"].vscode-high-contrast{${diagramVars('hc')}}
+${shell}
+${classes}`;
+}

package/src/theme/tokens.ts

@@ -0,0 +1,133 @@
+/** Transitrix brand palette. */
+export const BRAND = {
+  petrol: '#004d67',
+  amber:  '#ffaf00',
+  orange: '#ff4d00',
+} as const;
+
+/** Functional status colors. */
+export const FUNCTIONAL = {
+  success: '#1a7f5c',
+  warning: '#c07030',
+  error:   '#b91c1c',
+  info:    '#1d6fa8',
+} as const;
+
+/** Fill colors for FGCA notation columns. */
+export const LAYER_COLORS = {
+  factor:   { light: '#fef3c7', dark: '#292108', hc: '#f59e0b' },
+  goal:     { light: '#e0e7ff', dark: '#1e1b4b', hc: '#818cf8' },
+  change:   { light: '#dbeafe', dark: '#0c2042', hc: '#60a5fa' },
+  activity: { light: '#d4edda', dark: '#0a2414', hc: '#4ade80' },
+} as const;
+
+/** Level fill colors for Goals tree nodes — 8 slots, cycled by level index. */
+export const LEVEL_COLORS = {
+  light: ['#dbeafe', '#e0e7ff', '#d4edda', '#fef3c7', '#fce7f3', '#e0f2fe', '#f3e8ff', '#fef9c3'],
+  dark:  ['#0c2042', '#1e1b4b', '#0a2414', '#292108', '#2a0c1f', '#071e2e', '#1a0c33', '#2a2107'],
+  hc:    ['#60a5fa', '#818cf8', '#4ade80', '#f59e0b', '#f472b6', '#38bdf8', '#a78bfa', '#facc15'],
+} as const;
+
+/** Structural diagram colors (nodes, edges, text). */
+export const STRUCTURAL = {
+  nodeStroke:    { light: '#94a3b8', dark: '#475569', hc: '#e2e8f0' },
+  edgeStroke:    { light: '#94a3b8', dark: '#475569', hc: '#e2e8f0' },
+  textPrimary:   { light: '#1e293b', dark: '#f1f5f9', hc: '#ffffff' },
+  textSecondary: { light: '#64748b', dark: '#94a3b8', hc: '#cbd5e1' },
+  headerText:    { light: '#374151', dark: '#e5e7eb', hc: '#ffffff' },
+} as const;
+
+/**
+ * Maturity scale fill colors — Likert 1..5, danger→success.
+ * Used by Capability Map and any future maturity-based notation.
+ */
+export const MATURITY_COLORS = {
+  light: ['#b91c1c', '#d97706', '#ca8a04', '#65a30d', '#15803d'],
+  dark:  ['#7f1d1d', '#92400e', '#854d0e', '#3f6212', '#14532d'],
+  hc:    ['#f87171', '#fb923c', '#facc15', '#a3e635', '#4ade80'],
+} as const;
+
+/**
+ * Typography hierarchy. All previews resolve text styling from these roles
+ * — never from inline font-* attributes on individual <text> elements.
+ *
+ * fontFamily threads through the VS Code font setting so the preview reads
+ * as part of the editor; size + weight encode the visual hierarchy.
+ */
+export const TYPOGRAPHY = {
+  fontFamily: 'var(--vscode-font-family, system-ui, -apple-system, sans-serif)',
+  sizes: {
+    header:    13,  // stage/column headers, diagram captions
+    primary:   12,  // primary node/cell labels
+    secondary: 11,  // annotations, secondary lines, meta
+    id:        10,  // compact id/code chips
+    pill:      11,  // pill labels (process-blueprint aspects, badges)
+    caption:   11,  // figcaption under the canvas
+  },
+  weights: {
+    header:    700,
+    primary:   600,
+    secondary: 400,
+    id:        600,
+    pill:      500,
+    caption:   400,
+  },
+} as const;
+
+/** Adaptive shell tokens (background, text, border, status). */
+export interface AdaptiveTokens {
+  bg:               string;
+  bgSurface:        string;
+  bgElevated:       string;
+  text:             string;
+  textMuted:        string;
+  textInverse:      string;
+  border:           string;
+  divider:          string;
+  statusSuccessBg:  string;
+  statusSuccessFg:  string;
+  statusWarningBg:  string;
+  statusWarningFg:  string;
+  statusInfoBg:     string;
+  statusInfoFg:     string;
+  statusErrorBg:    string;
+  statusErrorFg:    string;
+}
+
+/** CSS custom property names for --ts-* variables. */
+export const CSS_VAR = {
+  bg:               '--ts-bg',
+  bgSurface:        '--ts-bg-surface',
+  bgElevated:       '--ts-bg-elevated',
+  text:             '--ts-text',
+  textMuted:        '--ts-text-muted',
+  textInverse:      '--ts-text-inverse',
+  border:           '--ts-border',
+  divider:          '--ts-divider',
+  statusSuccessBg:  '--ts-status-success-bg',
+  statusSuccessFg:  '--ts-status-success-fg',
+  statusWarningBg:  '--ts-status-warning-bg',
+  statusWarningFg:  '--ts-status-warning-fg',
+  statusInfoBg:     '--ts-status-info-bg',
+  statusInfoFg:     '--ts-status-info-fg',
+  statusErrorBg:    '--ts-status-error-bg',
+  statusErrorFg:    '--ts-status-error-fg',
+  layerFactor:      '--ts-layer-factor',
+  layerGoal:        '--ts-layer-goal',
+  layerChange:      '--ts-layer-change',
+  layerActivity:    '--ts-layer-activity',
+  nodeStroke:       '--ts-node-stroke',
+  edgeStroke:       '--ts-edge-stroke',
+  textPrimary:      '--ts-text-primary',
+  textSecondary:    '--ts-text-secondary',
+  headerText:       '--ts-header-text',
+  maturity1:        '--ts-maturity-1',
+  maturity2:        '--ts-maturity-2',
+  maturity3:        '--ts-maturity-3',
+  maturity4:        '--ts-maturity-4',
+  maturity5:        '--ts-maturity-5',
+} as const;
+
+export function getBaseResetCss(): string {
+  return `*,*:before,*:after{box-sizing:border-box;}html,body{margin:0;padding:0;}`;
+}

package/src/typed-id.ts

@@ -0,0 +1,56 @@
+// Canonical typed-ID grammar + cross-reference resolution catalogue.
+//
+// Every element ID and cross-reference in the Transitrix canon follows the
+// grammar in methodology `notations/IDS_AND_REFERENCES.md` §1:
+//
+//     <TYPE>-[<middle segment(s)>-]<INTEGER>
+//
+//   - TYPE: uppercase, starts with a letter, may contain digits and `_`
+//     (multi-word TYPEs like INTERNAL_STANDARD / PROCESS_BLUEPRINT).
+//   - middle: optional, notation-specific segments.
+//   - INTEGER: terminal positive integer, no leading zeros.
+//
+// CAPABILITY is the one exception (§2): its terminal is a V/H diagram address
+// (CAPABILITY-V1.2) rather than a plain integer. Compliance artefacts only
+// *resolve* capability ids (they never own one), so the catalogue handles
+// them; the strict integer-terminal grammar below is used only for an
+// artefact's own id (REQUIREMENT-… / ASSERTION-…).
+
+/** TYPE prefix of a typed id — the segment before the first hyphen. */
+const TYPE_PREFIX_RE = /^([A-Z][A-Z0-9_]*)-/;
+
+/** Full integer-terminal canonical id. Middle segments may be mixed-case
+ *  (real canon ids such as INTERNAL_STANDARD-coding-conventions-1 exist). */
+const CANONICAL_ID_RE = /^[A-Z][A-Z0-9_]*(?:-[A-Za-z0-9]+)*-[1-9][0-9]*$/;
+
+/** Extracts the TYPE prefix of a typed id, or null when `id` is not a typed
+ *  reference (`PRODUCT-MOBILE-1` → `PRODUCT`, `CAPABILITY-V2` → `CAPABILITY`). */
+export function typeOfId(id: unknown): string | null {
+  if (typeof id !== 'string') return null;
+  const m = TYPE_PREFIX_RE.exec(id);
+  return m ? m[1] : null;
+}
+
+/** True when `id` is a well-formed integer-terminal canonical id. */
+export function isCanonicalId(id: unknown): id is string {
+  return typeof id === 'string' && CANONICAL_ID_RE.test(id);
+}
+
+/** True when `id` is a well-formed canonical id whose TYPE is exactly `type`. */
+export function isCanonicalIdOfType(id: unknown, type: string): boolean {
+  return isCanonicalId(id) && typeOfId(id) === type;
+}
+
+/**
+ * A read-only view of an organisation's admitted canon, used to resolve typed
+ * cross-references during validation. Phase 1 validators accept it optionally:
+ * with no catalogue they perform shape + prefix-TYPE checks only; given one,
+ * they additionally enforce the resolution rules (REQ-002, ASSERT-002/004/005…)
+ * that depend on whether a referenced artefact actually exists.
+ *
+ * The compliance previews (Phase 2+) build a catalogue by scanning the repo.
+ */
+export interface CanonCatalog {
+  /** TYPE of an admitted artefact with this id, or undefined if not admitted. */
+  typeOf(id: string): string | undefined;
+}

package/src/validation-types.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared validation result shape across every notation module in this
+ * package.
+ *
+ * Before this file existed, each notation declared its own
+ * `ValidationError` / `ValidationWarning` / `ValidationResult` triple inside
+ * its own `validate.ts`. The shapes happened to agree (or almost agree —
+ * some had an optional `path` field, others didn't), but having N parallel
+ * declarations made it easy to accidentally drift one of them, and made the
+ * "what does our validator return?" answer fuzzier than it should be.
+ *
+ * The pre-release code review on 2026-05-21 called this out as a
+ * `should-fix` cross-module concern; this is the canonical shape.
+ *
+ * Notations that historically exported PREFIXED type names — `FGCA…` and
+ * `Activity…` — keep those names as type aliases re-exported from their own
+ * modules, so existing consumers continue to compile.
+ */
+export interface ValidationError {
+  code: string;
+  message: string;
+  /** Optional JSON-path-ish locator inside the source document. */
+  path?: string;
+}
+
+export interface ValidationWarning {
+  code: string;
+  message: string;
+  path?: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+  warnings: ValidationWarning[];
+}