@transitrix/diagrams 1.5.0 → 1.7.6

package/src/goals/__tests__/GoalTreeView.test.tsx

@@ -0,0 +1,361 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import React from 'react';
+import { render, screen, cleanup, waitFor } from '@testing-library/react';
+import { GoalTreeView, computeDragOutcome } from '../GoalTreeView.js';
+import type { GoalTree } from '../types.js';
+import type { GoalTreeChange } from '../GoalTreeView.js';
+
+// jsdom has no ResizeObserver / layout engine. reactflow keeps a node's DOM
+// wrapper `visibility: hidden` and excludes it from drag/intersection logic
+// until it has been "measured" via ResizeObserver — so the mock must
+// actually invoke its callback (with the mocked getBoundingClientRect below)
+// for nodes to become interactive, not just satisfy the constructor call.
+class MockResizeObserver {
+  #callback: ResizeObserverCallback;
+  constructor(callback: ResizeObserverCallback) {
+    this.#callback = callback;
+  }
+  observe(target: Element) {
+    queueMicrotask(() => {
+      const rect = target.getBoundingClientRect();
+      this.#callback(
+        [{ target, contentRect: rect } as ResizeObserverEntry],
+        this as unknown as ResizeObserver,
+      );
+    });
+  }
+  unobserve() {}
+  disconnect() {}
+}
+
+// jsdom also has no DOMMatrixReadOnly, which reactflow's dimension-tracking
+// uses to read the translateX/Y out of a node's computed transform. Only
+// translate() (no scale/rotate) ever appears in this component's own CSS, so
+// a minimal shim covering that one case is enough.
+class MockDOMMatrixReadOnly {
+  m41 = 0;
+  m42 = 0;
+  constructor(transform?: string) {
+    if (!transform || transform === 'none') return;
+    const t = /translate\((-?[\d.]+)px,\s*(-?[\d.]+)px\)/.exec(transform);
+    if (t) {
+      this.m41 = Number(t[1]);
+      this.m42 = Number(t[2]);
+      return;
+    }
+    const m = /matrix\(([^)]+)\)/.exec(transform);
+    if (m) {
+      const parts = m[1].split(',').map((p) => Number(p.trim()));
+      this.m41 = parts[4] ?? 0;
+      this.m42 = parts[5] ?? 0;
+    }
+  }
+}
+
+function makeTree(): GoalTree {
+  return {
+    goal_types: [
+      { name: 'Strategy', level: 0 },
+      { name: 'Business Goal', level: 1 },
+    ],
+    goals: [
+      { id: 1, name: 'Triple revenue', type: 'Strategy', level: 0, parent_id: 0 },
+      { id: 2, name: 'Launch in EU', type: 'Business Goal', level: 1, parent_id: 1 },
+      {
+        id: 3,
+        name: 'Cut churn',
+        type: 'Business Goal',
+        level: 1,
+        parent_id: 1,
+        factors: [
+          { id: 10, name: 'Support backlog', impact_type: 'risk' },
+          { id: 11, name: 'New pricing', impact_type: 'opportunity' },
+        ],
+      },
+    ],
+  };
+}
+
+beforeEach(() => {
+  (global as unknown as { ResizeObserver: unknown }).ResizeObserver = MockResizeObserver;
+  (window as unknown as { DOMMatrixReadOnly: unknown }).DOMMatrixReadOnly = MockDOMMatrixReadOnly;
+  vi.spyOn(Element.prototype, 'getBoundingClientRect').mockImplementation(function (this: Element) {
+    // Individual goal cards report their real 250x80 footprint (matters for
+    // reactflow's own drag/measurement bookkeeping); the flow container and
+    // everything else gets a generously large rect so viewport fitting has
+    // room to work with.
+    const isNode = this.classList?.contains('react-flow__node');
+    const width = isNode ? 250 : 1000;
+    const height = isNode ? 80 : 800;
+    return {
+      width, height, top: 0, left: 0, right: width, bottom: height, x: 0, y: 0,
+      toJSON() { return this; },
+    } as DOMRect;
+  });
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+describe('GoalTreeView', () => {
+  it('renders without crashing and shows every canvas goal', async () => {
+    render(<GoalTreeView tree={makeTree()} />);
+    await waitFor(() => {
+      expect(screen.getByText('Triple revenue')).toBeTruthy();
+      expect(screen.getByText('Launch in EU')).toBeTruthy();
+      expect(screen.getByText('Cut churn')).toBeTruthy();
+    });
+  });
+
+  it('renders factor indicators from goal.factors', async () => {
+    render(<GoalTreeView tree={makeTree()} />);
+    await waitFor(() => {
+      expect(screen.getByText('Triple revenue')).toBeTruthy();
+    });
+    // One up-caret (opportunity) and one down-caret (risk) on "Cut churn".
+    expect(screen.getByLabelText('1 positive factor')).toBeTruthy();
+    expect(screen.getByLabelText('1 negative factor')).toBeTruthy();
+  });
+
+  it('puts a goal with a broken parent_id in the backlog, not on canvas', async () => {
+    const tree: GoalTree = {
+      goal_types: [
+        { name: 'Strategy', level: 0 },
+        { name: 'Business Goal', level: 1 },
+      ],
+      goals: [
+        { id: 1, name: 'Root goal', type: 'Strategy', level: 0, parent_id: 0 },
+        // level 1 + a parent_id that resolves to nothing — not a root by
+        // either "Roots: level === 0 || parent_id === 0" clause, and
+        // unreachable from goal 1 — must land in the backlog.
+        { id: 2, name: 'Orphaned goal', type: 'Business Goal', level: 1, parent_id: 999 },
+      ],
+    };
+    render(<GoalTreeView tree={tree} showBacklog />);
+    await waitFor(() => {
+      expect(screen.getByText('Root goal')).toBeTruthy();
+    });
+    expect(screen.getByText('Orphaned goal')).toBeTruthy();
+    expect(screen.queryByText('Backlog')).toBeTruthy();
+  });
+
+  it('does not render add/delete affordances when readOnly', async () => {
+    render(<GoalTreeView tree={makeTree()} readOnly />);
+    await waitFor(() => {
+      expect(screen.getByText('Triple revenue')).toBeTruthy();
+    });
+    expect(screen.queryByLabelText('Add child goal')).toBeNull();
+    expect(screen.queryByLabelText('Delete goal')).toBeNull();
+  });
+
+  it('fires onChange with kind "addChild" when the add-child button is clicked', async () => {
+    const onChange = vi.fn<(e: GoalTreeChange) => void>();
+    render(<GoalTreeView tree={makeTree()} onChange={onChange} />);
+    await waitFor(() => {
+      expect(screen.getByText('Triple revenue')).toBeTruthy();
+    });
+    // Target the root (id 1, level 0) specifically — makeTree()'s goal_types
+    // only go up to level 1, so clicking "add child" on an existing level-1
+    // goal would be correctly refused (would exceed max level) and never
+    // fire onChange at all.
+    const rootNode = document.querySelector('.react-flow__node[data-id="1"]');
+    const addButton = rootNode!.querySelector('[aria-label="Add child goal"]')!;
+    addButton.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+
+    await waitFor(() => expect(onChange).toHaveBeenCalledTimes(1));
+    const event = onChange.mock.calls[0][0];
+    expect(event.kind).toBe('addChild');
+    if (event.kind === 'addChild') {
+      expect(event.result.goals.length).toBe(4);
+    }
+  });
+
+  it('fires onChange with kind "delete" when the delete button is clicked', async () => {
+    const onChange = vi.fn<(e: GoalTreeChange) => void>();
+    render(<GoalTreeView tree={makeTree()} onChange={onChange} />);
+    await waitFor(() => {
+      expect(screen.getByText('Cut churn')).toBeTruthy();
+    });
+    const deleteButtons = screen.getAllByLabelText('Delete goal');
+    deleteButtons[deleteButtons.length - 1].dispatchEvent(new MouseEvent('click', { bubbles: true }));
+
+    await waitFor(() => expect(onChange).toHaveBeenCalledTimes(1));
+    const event = onChange.mock.calls[0][0];
+    expect(event.kind).toBe('delete');
+  });
+
+  it('fires onChange with kind "restoreFromBacklog" when a backlog card is dropped onto a canvas card', async () => {
+    const tree: GoalTree = {
+      goal_types: [
+        { name: 'Strategy', level: 0 },
+        { name: 'Business Goal', level: 1 },
+      ],
+      goals: [
+        { id: 1, name: 'Root goal', type: 'Strategy', level: 0, parent_id: 0 },
+        { id: 2, name: 'Orphaned goal', type: 'Business Goal', level: 1, parent_id: 999 },
+      ],
+    };
+    const onChange = vi.fn<(e: GoalTreeChange) => void>();
+    render(<GoalTreeView tree={tree} onChange={onChange} showBacklog />);
+    await waitFor(() => {
+      expect(screen.getByText('Orphaned goal')).toBeTruthy();
+    });
+
+    // jsdom has no native DataTransfer; stub the minimal setData/getData
+    // surface this component's native (non-reactflow) HTML5 drag path uses
+    // and attach it directly to the dispatched events.
+    const store = new Map<string, string>();
+    const dataTransfer = {
+      setData: (k: string, v: string) => store.set(k, v),
+      getData: (k: string) => store.get(k) ?? '',
+      effectAllowed: 'move',
+    };
+    function fireDnd(el: Element, type: string, coords: { clientX: number; clientY: number }) {
+      const event = new Event(type, { bubbles: true, cancelable: true });
+      Object.defineProperty(event, 'dataTransfer', { value: dataTransfer });
+      Object.assign(event, coords);
+      el.dispatchEvent(event);
+    }
+
+    const backlogItem = screen.getByText('Orphaned goal').closest('div[draggable]')!;
+    const rootNode = document.querySelector('.react-flow__node[data-id="1"]')!;
+    // jsdom doesn't implement elementFromPoint at all (not just "returns null").
+    document.elementFromPoint = vi.fn().mockReturnValue(rootNode);
+
+    fireDnd(backlogItem, 'dragstart', { clientX: 0, clientY: 0 });
+    fireDnd(rootNode, 'drop', { clientX: 10, clientY: 10 });
+
+    await waitFor(() => expect(onChange).toHaveBeenCalledTimes(1));
+    const event = onChange.mock.calls[0][0];
+    expect(event.kind).toBe('restoreFromBacklog');
+    if (event.kind === 'restoreFromBacklog') {
+      expect(event.id).toBe(2);
+      expect(event.newParentId).toBe(1);
+      expect(event.result.goals.find((g) => g.id === 2)?.parent_id).toBe(1);
+    }
+  });
+
+  // Dragging a card is choreographed by reactflow's own pointer/DOM-measurement
+  // machinery (ResizeObserver-gated node "readiness", d3-drag pointer capture,
+  // viewport transform math) — faithfully simulating that in jsdom means
+  // re-implementing reactflow's internals rather than testing this component.
+  // computeDragOutcome() is the pure decision GoalTreeView's onNodeDragStop
+  // calls once reactflow reports a drag: given where a card was dropped, which
+  // mutation fires and what onChange payload it produces. Testing it directly
+  // covers the actual reparent/moveToBacklog logic without that DOM coupling.
+  describe('computeDragOutcome (reparent / moveToBacklog decision logic)', () => {
+    const tree: GoalTree = {
+      goal_types: [
+        { name: 'Strategy', level: 0 },
+        { name: 'Business Goal', level: 1 },
+      ],
+      goals: [
+        { id: 1, name: 'Goal A', type: 'Strategy', level: 0, parent_id: 0 },
+        { id: 2, name: 'Goal C', type: 'Strategy', level: 0, parent_id: 0 },
+        { id: 3, name: 'Goal B', type: 'Business Goal', level: 1, parent_id: 1 },
+      ],
+    };
+
+    it('fires a "reparent" change when dropped onto another card', () => {
+      const change = computeDragOutcome(tree, 3, { kind: 'node', id: 2 });
+      expect(change?.kind).toBe('reparent');
+      if (change?.kind === 'reparent') {
+        expect(change.sourceId).toBe(3);
+        expect(change.targetId).toBe(2);
+        expect(change.result.goals.find((g) => g.id === 3)?.parent_id).toBe(2);
+      }
+    });
+
+    it('fires a "moveToBacklog" change when dropped on the backlog zone', () => {
+      const change = computeDragOutcome(tree, 3, { kind: 'backlog' });
+      expect(change?.kind).toBe('moveToBacklog');
+      if (change?.kind === 'moveToBacklog') {
+        expect(change.id).toBe(3);
+        expect(change.result.goals.find((g) => g.id === 3)?.parent_id).toBe(0);
+      }
+    });
+
+    it('is a no-op when dropped nowhere in particular', () => {
+      expect(computeDragOutcome(tree, 3, null)).toBeNull();
+    });
+
+    it('is a no-op when dropped on itself', () => {
+      expect(computeDragOutcome(tree, 3, { kind: 'node', id: 3 })).toBeNull();
+    });
+
+    it('is a no-op when the reparent would exceed the schema max level', () => {
+      // Goal 3 is already level 1 (max); reparenting it under itself-sibling
+      // level-1 goal would push it to level 2.
+      const deeper: GoalTree = {
+        ...tree,
+        goals: [...tree.goals, { id: 4, name: 'Goal D', type: 'Business Goal', level: 1, parent_id: 1 }],
+      };
+      expect(computeDragOutcome(deeper, 3, { kind: 'node', id: 4 })).toBeNull();
+    });
+  });
+
+  it('fires onFactorClick with the clicked factor when a popover item is clicked', async () => {
+    const onFactorClick = vi.fn();
+    render(<GoalTreeView tree={makeTree()} onFactorClick={onFactorClick} />);
+    await waitFor(() => {
+      expect(screen.getByText('Cut churn')).toBeTruthy();
+    });
+
+    // Open the negative-factor panel on "Cut churn" (id=3, has risk factor "Support backlog")
+    const negativeBadge = screen.getByLabelText('1 negative factor');
+    negativeBadge.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+
+    // The popover item for the risk factor should now be in the DOM
+    const factorItem = await waitFor(() => screen.getByText('Support backlog'));
+    factorItem.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+
+    await waitFor(() => expect(onFactorClick).toHaveBeenCalledTimes(1));
+    expect(onFactorClick.mock.calls[0][0]).toMatchObject({ id: 10, name: 'Support backlog', impact_type: 'risk' });
+  });
+
+  it('backlog panel is collapsible — toggle hides and restores content', async () => {
+    const tree: GoalTree = {
+      goal_types: [
+        { name: 'Strategy', level: 0 },
+        { name: 'Business Goal', level: 1 },
+      ],
+      goals: [
+        { id: 1, name: 'Root goal', type: 'Strategy', level: 0, parent_id: 0 },
+        { id: 2, name: 'Orphaned goal', type: 'Business Goal', level: 1, parent_id: 999 },
+      ],
+    };
+    render(<GoalTreeView tree={tree} showBacklog />);
+    await waitFor(() => {
+      expect(screen.getByText('Backlog')).toBeTruthy();
+    });
+
+    // Collapse
+    screen.getByLabelText('Collapse backlog').dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    await waitFor(() => {
+      expect(screen.queryByText('Backlog')).toBeNull();
+    });
+
+    // Expand again
+    screen.getByLabelText('Expand backlog').dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    await waitFor(() => {
+      expect(screen.getByText('Backlog')).toBeTruthy();
+    });
+  });
+
+  it('fires onEditRequest on double-click', async () => {
+    const onEditRequest = vi.fn();
+    render(<GoalTreeView tree={makeTree()} onEditRequest={onEditRequest} />);
+    await waitFor(() => {
+      expect(screen.getByText('Triple revenue')).toBeTruthy();
+    });
+    const nodeEl = document.querySelector('.react-flow__node[data-id="1"]');
+    expect(nodeEl).toBeTruthy();
+    nodeEl!.dispatchEvent(new MouseEvent('dblclick', { bubbles: true }));
+
+    await waitFor(() => expect(onEditRequest).toHaveBeenCalledTimes(1));
+    expect(onEditRequest.mock.calls[0][0]).toMatchObject({ id: 1, name: 'Triple revenue' });
+  });
+});

package/src/goals/__tests__/mutations.test.ts

@@ -109,3 +109,45 @@ describe('restoreFromBacklog', () => {
     expect(r.result!.goals.find(g => g.id === 3)!.parent_id).toBe(1);
   });
 });
+
+describe('reparent — descendant type relabeling and level cap', () => {
+  const DEEP: GoalTree = {
+    goal_types: [
+      { name: 'Strategy', level: 0 },
+      { name: 'Business Goal', level: 1 },
+      { name: 'Project', level: 2 },
+      { name: 'Task', level: 3 },
+    ],
+    goals: [
+      { id: 1, name: 'Root', type: 'Strategy', level: 0, parent_id: 0 },
+      { id: 2, name: 'BG1', type: 'Business Goal', level: 1, parent_id: 1 },
+      { id: 3, name: 'Proj1', type: 'Project', level: 2, parent_id: 2 },
+      { id: 4, name: 'Task1', type: 'Task', level: 3, parent_id: 3 },
+    ],
+  };
+
+  it('relabels descendant types via getTypeForLevel when reparenting shifts levels', () => {
+    // Move Proj1 (id=3, level=2) directly under Root (id=1, level=0); delta = -1
+    // Task1 (child of Proj1, level=3): new level = 2, type should be 'Project'
+    const r = reparent(DEEP, 3, 1);
+    expect(r.ok).toBe(true);
+    const proj = r.result!.goals.find(g => g.id === 3)!;
+    const task = r.result!.goals.find(g => g.id === 4)!;
+    expect(proj.level).toBe(1);
+    expect(proj.type).toBe('Business Goal');
+    expect(task.level).toBe(2);
+    expect(task.type).toBe('Project');
+  });
+
+  it('caps descendant level at maxLevel and refuses when that violates GOALS-012', () => {
+    // Move Root (id=1, level=0) under Root2 (id=5, level=0); delta = +1
+    // BG1: 1→2, Proj1: 2→3 (maxLevel), Task1: 3→4, capped at 3
+    // Task1 (capped level=3) under Proj1 (level=3) violates GOALS-012 → refused
+    const tree: GoalTree = {
+      ...DEEP,
+      goals: [...DEEP.goals, { id: 5, name: 'Root2', type: 'Strategy', level: 0, parent_id: 0 }],
+    };
+    const r = reparent(tree, 1, 5);
+    expect(r.ok).toBe(false);
+  });
+});

package/src/goals/__tests__/parse-canonical.test.ts

@@ -122,8 +122,10 @@ describe('parseCanonicalGoals', () => {
   it('maps canonical IDs to internal numeric ids; parent_id is the parent\'s mapped id', () => {
     const r = parseCanonicalGoals(VALID);
     expect(r.parsed?.goals[0].id).toBe(1);
+    expect(r.parsed?.goals[0].canonical_id).toBe('GOAL-1');
     expect(r.parsed?.goals[0].parent_id).toBe(0);
     expect(r.parsed?.goals[1].id).toBe(2);
+    expect(r.parsed?.goals[1].canonical_id).toBe('GOAL-2');
     expect(r.parsed?.goals[1].parent_id).toBe(1);
   });
 });

package/src/goals/index.ts

@@ -18,3 +18,7 @@ export { parseCanonicalGoals } from './parse-canonical.js';
 export type { CanonicalGoalsResult } from './parse-canonical.js';
 export { layoutGoalTree, selectScopedGoals } from './layout.js';
 export { reparent, addChild, deleteWithDescendants, moveToBacklog, restoreFromBacklog } from './mutations.js';
+
+export { GoalTreeView } from './GoalTreeView.js';
+export type { GoalTreeViewProps, GoalTreeChange } from './GoalTreeView.js';
+export type { ThemeTokens } from './theme.js';

package/src/goals/layout.ts

@@ -1,5 +1,6 @@
 import type { Goal, GoalTree, LayoutOptions, GoalTreeLayout, LaidOutNode, LaidOutEdge } from './types.js';
 import type { Scope } from '../scope.js';
+import { displayGoalId } from './parse-canonical.js';
 
 const DEFAULT_NODE_WIDTH = 250;
 const DEFAULT_NODE_HEIGHT = 80;
@@ -23,7 +24,7 @@ export function selectScopedGoals(goals: Goal[], scope: Scope): Goal[] {
     if (!children.has(g.parent_id)) children.set(g.parent_id, []);
     children.get(g.parent_id)!.push(g.id);
   }
-  const root = goals.find(g => String(g.id) === scope.rootGoalId);
+  const root = goals.find(g => displayGoalId(g) === scope.rootGoalId);
   if (!root) return [];
   const keep = new Set<number>();
   const stack = [root.id];

package/src/goals/mutations.ts

@@ -22,12 +22,12 @@ function getTypeForLevel(tree: GoalTree, level: number): string {
   return gt?.name ?? '';
 }
 
-function updateDescendantLevels(goals: Goal[], id: number, levelDelta: number): void {
-  for (const g of goals) {
+function updateDescendantLevels(clone: GoalTree, id: number, levelDelta: number, maxLevel: number): void {
+  for (const g of clone.goals) {
     if (g.parent_id === id) {
-      g.level += levelDelta;
-      g.type = '';
-      updateDescendantLevels(goals, g.id, levelDelta);
+      g.level = Math.min(g.level + levelDelta, maxLevel);
+      g.type = getTypeForLevel(clone, g.level);
+      updateDescendantLevels(clone, g.id, levelDelta, maxLevel);
     }
   }
 }
@@ -70,7 +70,7 @@ export function reparent(tree: GoalTree, sourceId: number, targetId: number): Mu
   source.parent_id = targetId;
   source.level = newLevel;
   source.type = getTypeForLevel(clone, newLevel);
-  if (levelDelta !== 0) updateDescendantLevels(clone.goals, sourceId, levelDelta);
+  if (levelDelta !== 0) updateDescendantLevels(clone, sourceId, levelDelta, maxLevel);
 
   const v = validateGoalTree(clone);
   if (!v.valid) return refusalError(v.errors[0]?.message ?? 'Validation failed after reparent');

package/src/goals/parse-canonical.ts

@@ -36,6 +36,11 @@ export interface CanonicalGoalsResult extends ValidationResult {
 const GOAL_ID_RE = /^GOAL(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 const GOALS_DOC_ID_RE = /^GOALS(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 
+/** Display id for previews — canonical `GOAL-…` when present, else internal numeric id. */
+export function displayGoalId(goal: { id: number; canonical_id?: string }): string {
+  return goal.canonical_id ?? String(goal.id);
+}
+
 function isNonEmptyString(v: unknown): v is string {
   return typeof v === 'string' && v.trim().length > 0;
 }
@@ -267,6 +272,7 @@ export function parseCanonicalGoals(input: unknown): CanonicalGoalsResult {
       isNonEmptyString(parent) && idToInternal.has(parent) ? idToInternal.get(parent)! : 0;
     return {
       id: idToInternal.get(o['id'] as string)!,
+      canonical_id: o['id'] as string,
       name: o['name'] as string,
       type: o['type'] as string,
       level: o['level'] as number,

package/src/goals/theme.ts

@@ -0,0 +1,54 @@
+/**
+ * Theme tokens for GoalTreeView — replaces DSM's Redux selectors
+ * (selectDiagramParams, selectGoalLevelColors) with a plain prop. Hosts
+ * that already carry Transitrix's --ts-* CSS custom properties (Studio)
+ * can pass those through; hosts with their own theme store (DSM) map
+ * their own values onto this shape.
+ */
+export interface ThemeTokens {
+  /** Card fill colour per goal level (0..7). Falls back to DEFAULT_GOAL_LEVEL_COLORS for missing levels. */
+  goalLevelColors?: Record<number, string>;
+  cardBorderColor?: string;
+  cardBorderWidth?: number;
+  cardTextColor?: string;
+  cardMetaColor?: string;
+  edgeColor?: string;
+  edgeWidth?: number;
+  /** Border colour a card takes on while it's a highlighted drop target during drag. */
+  dropTargetBorderColor?: string;
+}
+
+export const DEFAULT_GOAL_LEVEL_COLORS: Record<number, string> = {
+  0: '#e0e7ff',
+  1: '#c7d2fe',
+  2: '#a5b4fc',
+  3: '#93c5fd',
+  4: '#bae6fd',
+  5: '#bbf7d0',
+  6: '#fef08a',
+  7: '#fed7aa',
+};
+
+export const DEFAULT_THEME: Required<ThemeTokens> = {
+  goalLevelColors: DEFAULT_GOAL_LEVEL_COLORS,
+  cardBorderColor: '#94a3b8',
+  cardBorderWidth: 1,
+  cardTextColor: '#0f172a',
+  cardMetaColor: '#64748b',
+  edgeColor: '#94a3b8',
+  edgeWidth: 1.5,
+  dropTargetBorderColor: '#2563eb',
+};
+
+export function resolveTheme(theme?: ThemeTokens): Required<ThemeTokens> {
+  return {
+    goalLevelColors: theme?.goalLevelColors ?? DEFAULT_THEME.goalLevelColors,
+    cardBorderColor: theme?.cardBorderColor ?? DEFAULT_THEME.cardBorderColor,
+    cardBorderWidth: theme?.cardBorderWidth ?? DEFAULT_THEME.cardBorderWidth,
+    cardTextColor: theme?.cardTextColor ?? DEFAULT_THEME.cardTextColor,
+    cardMetaColor: theme?.cardMetaColor ?? DEFAULT_THEME.cardMetaColor,
+    edgeColor: theme?.edgeColor ?? DEFAULT_THEME.edgeColor,
+    edgeWidth: theme?.edgeWidth ?? DEFAULT_THEME.edgeWidth,
+    dropTargetBorderColor: theme?.dropTargetBorderColor ?? DEFAULT_THEME.dropTargetBorderColor,
+  };
+}

package/src/goals/types.ts

@@ -10,6 +10,8 @@ export interface Factor {
 
 export interface Goal {
   id: number;
+  /** Canonical typed id from the YAML (`GOAL-…`) when parsed from canonical form. */
+  canonical_id?: string;
   name: string;
   type: string;
   level: number;

package/src/index.ts

@@ -6,7 +6,35 @@ export * from "./geometry";
 export * from "./applications/index";
 export * from "./assertion/index";
 export * from "./blocks/index";
-export * from "./capability-map/index";
+// capability-map/index.js also exports a set of DSM-migration symbols
+// (Capability, reparent, addChild, LayoutOptions, ThemeTokens, ...) that
+// reuse the goals module's exact generic Layer-A/B naming convention by
+// design (both follow the same extraction-spec template) — the wildcard
+// re-export below would collide with goals' identically-named symbols.
+// Neither spec's acceptance criteria asks for root-barrel access (only
+// `@transitrix/diagrams/goals` / `@transitrix/diagrams/capability-map`
+// subpath imports), so the colliding names are simply left off the root
+// barrel; they're still importable via the capability-map subpath.
+export type {
+  CapabilityType,
+  CapabilityNode,
+  CapabilityMapHeader,
+  CapabilityMapFile,
+  CapabilityTreeNode,
+  CapabilityTreeEdge,
+  CapabilityTreeLevelCounts,
+  CapabilityTreeLayout,
+  RenderCapabilityTreeOptions,
+} from "./capability-map/index";
+export {
+  validateCapabilityMap,
+  layoutCapabilityTree,
+  TREE_NODE_WIDTH,
+  TREE_NODE_HEIGHT,
+  TREE_RANK_SEP,
+  TREE_NODE_SEP,
+  renderCapabilityTreeSvg,
+} from "./capability-map/index";
 export * from "./change/index";
 export * from "./compliance/index";
 export * from "./compliance-matrix/index";

package/src/repo-validate/types.ts

@@ -4,9 +4,8 @@
 // referential integrity, atomicity, ID uniqueness, policy — the checks that the
 // methodology's Python `.validators/lint.py` owns today. This converges those
 // checks onto the shared TypeScript model so there is a single validation
-// runtime (methodology ADR
-// `2026-06-11-validation-two-axis-model.md`; Studio referencing ADR
-// `docs/decisions/2026-06-11-validation-runtime-convergence.md`).
+// runtime (methodology ADR "Validation Two-Axis Model"; Studio decision
+// "Validation Runtime Convergence").
 //
 // The finding shape is deliberately minimal — `{ scope, id, message }`. The
 // richer `target` / `category` reporting taxonomy is explicitly DEFERRED per the

package/src/webview/__tests__/render-goals.test.ts

@@ -65,8 +65,22 @@ describe('renderGoalsSvg', () => {
     expect(svg).toContain('height="0"');
   });
 
-  it('omits the title block when treeName is missing', () => {
-    const svg = renderGoalsSvg(SIMPLE_TREE);
-    expect(svg).not.toContain('Goal tree —');
+  it('shows canonical goal ids in node labels when present', () => {
+    const tree: GoalTree = {
+      goal_types: [{ name: 'Strategy', level: 0 }],
+      goals: [
+        {
+          id: 1,
+          canonical_id: 'GOAL-REVENUE-1',
+          name: 'Triple revenue',
+          type: 'Strategy',
+          level: 0,
+          parent_id: 0,
+        },
+      ],
+    };
+    const svg = renderGoalsSvg(tree);
+    expect(svg).toContain('GOAL-REVENUE-1');
+    expect(svg).not.toMatch(/>\s*1\s*</);
   });
 });

package/src/webview/render-goals.ts

@@ -12,6 +12,7 @@
  */
 import { layoutGoalTree } from '../goals/layout.js';
 import type { GoalTree, GoalTreeLayout, LaidOutEdge } from '../goals/types.js';
+import { displayGoalId } from '../goals/parse-canonical.js';
 import { horizontalCubicEdgePath, DEFAULT_EDGE_CURVATURE } from '../edge-path.js';
 import { generateSvgEmbedCss, type ThemeId } from '../theme/index.js';
 import { escXml } from './render-util.js';
@@ -129,7 +130,7 @@ export function renderGoalsLayoutSvg(layout: GoalTreeLayout, options: RenderGoal
       const typeY = twoLines ? y + 43 : y + 35;
       const idY = twoLines ? y + 59 : y + 55;
       const typeLabel = n.data.type ?? '';
-      const idText = String(n.data.id);
+      const idText = displayGoalId(n.data);
       return `<g>
   <rect class="diagram-node level-${level}" x="${x}" y="${y}" width="${n.width}" height="${n.height}" rx="${ENTITY_NODE_RX}"/>
   <text class="text-primary" x="${x + n.width / 2}" y="${nameY1}" text-anchor="middle" dominant-baseline="central">${escXml(line1)}</text>${twoLines ? `