@transitrix/diagrams 1.5.0 → 1.6.0

package/src/capability-map/CapabilityMapView.tsx

@@ -0,0 +1,331 @@
+import React, { useCallback, useMemo, useState, useEffect } from 'react';
+import ReactFlow, {
+  Controls,
+  MiniMap,
+  Background,
+  Panel,
+  ConnectionLineType,
+  useNodesState,
+  useEdgesState,
+  type Node,
+  type Edge,
+  type NodeMouseHandler,
+  type NodeDragHandler,
+} from 'reactflow';
+import 'reactflow/dist/style.css';
+import type { Capability, CapabilityMap, CapabilityMapLayout, LayoutOptions } from './dsm-schema.js';
+import { layoutCapabilityMap } from './dsm-layout.js';
+import { reparent, addChild, deleteWithDescendants, moveBranchToBacklog, restoreFromBacklog, normaliseAddresses } from './dsm-mutations.js';
+import type { ThemeTokens } from './dsm-theme.js';
+import { resolveTheme, DEFAULT_MATURITY_COLOURS } from './dsm-theme.js';
+import CapabilityCardNode, { type CapabilityCardNodeData } from './CapabilityCardNode.js';
+import CapabilityRootNode, { type CapabilityRootNodeData } from './CapabilityRootNode.js';
+
+export type { ThemeTokens } from './dsm-theme.js';
+
+export interface CapabilityMapViewProps {
+  map: CapabilityMap;
+  layout?: CapabilityMapLayout;
+  layoutOptions?: LayoutOptions;
+  theme?: ThemeTokens;
+  readOnly?: boolean;
+  showBacklog?: boolean;
+  showMiniMap?: boolean;
+  maturityColours?: Record<number, string>;
+  selectedSet?: string;
+  onChange?: (event: CapabilityMapChange) => void;
+  onEditRequest?: (cap: Capability) => void;
+}
+
+export type CapabilityMapChange =
+  | { kind: 'reparent'; sourceId: number; targetId: number; result: CapabilityMap }
+  | { kind: 'addChild'; parentId: number; newCap: Capability; result: CapabilityMap }
+  | { kind: 'delete'; id: number; result: CapabilityMap }
+  | { kind: 'moveBranchToBacklog'; id: number; result: CapabilityMap }
+  | { kind: 'restoreFromBacklog'; id: number; parentId: number; result: CapabilityMap }
+  | { kind: 'normaliseAddresses'; result: CapabilityMap };
+
+const BACKLOG_DRAG_MIME = 'application/x-transitrix-capability-id';
+const ROOT_NODE_ID = '__root__';
+const nodeTypes = { capabilityCard: CapabilityCardNode, capabilityRoot: CapabilityRootNode };
+
+/** Where a card was dropped, as classified from the pointer position at
+ *  drag-stop — mirrors goals' computeDragOutcome split (see GoalTreeView.tsx)
+ *  so the reparent/moveBranchToBacklog decision is unit-testable without a
+ *  live drag through reactflow's DOM-measurement-gated dragging. */
+export type DropTarget = { kind: 'node'; id: number } | { kind: 'root' } | { kind: 'backlog' } | null;
+
+export function computeDragOutcome(map: CapabilityMap, sourceId: number, dropTarget: DropTarget): CapabilityMapChange | null {
+  if (!dropTarget) return null;
+  if (dropTarget.kind === 'backlog') {
+    const mutation = moveBranchToBacklog(map, sourceId);
+    if (!mutation.ok || !mutation.result) return null;
+    return { kind: 'moveBranchToBacklog', id: sourceId, result: mutation.result };
+  }
+  const targetId = dropTarget.kind === 'root' ? 0 : dropTarget.id;
+  if (targetId === sourceId) return null;
+  const mutation = reparent(map, sourceId, targetId);
+  if (!mutation.ok || !mutation.result) return null;
+  return { kind: 'reparent', sourceId, targetId, result: mutation.result };
+}
+
+function CapabilityMapViewInner({
+  map,
+  layout: layoutProp,
+  layoutOptions,
+  theme: themeProp,
+  readOnly = false,
+  showBacklog = false,
+  showMiniMap = false,
+  maturityColours = DEFAULT_MATURITY_COLOURS,
+  onChange,
+  onEditRequest,
+}: CapabilityMapViewProps): React.ReactElement {
+  const theme = useMemo(() => resolveTheme(themeProp), [themeProp]);
+  const [collapsedIds, setCollapsedIds] = useState<Set<number>>(new Set());
+  const [hoveredId, setHoveredId] = useState<number | 'root' | null>(null);
+
+  const backlogCaps = useMemo(() => map.capabilities.filter((c) => c.backlog), [map.capabilities]);
+
+  const layout = useMemo<CapabilityMapLayout>(() => {
+    if (layoutProp) return layoutProp;
+    const hideCollapsed = [...(layoutOptions?.hideCollapsed ?? []), ...collapsedIds];
+    return layoutCapabilityMap(map, { ...layoutOptions, hideCollapsed });
+  }, [layoutProp, layoutOptions, collapsedIds, map]);
+
+  const rootLabel = layoutOptions?.organisationLabel ?? map.organisation;
+
+  const onAddChild = useCallback(
+    (parentId: number) => {
+      if (readOnly) return;
+      const before = new Set(map.capabilities.map((c) => c.id));
+      const mutation = addChild(map, parentId, { name: 'New capability' });
+      if (!mutation.ok || !mutation.result) return;
+      const newCap = mutation.result.capabilities.find((c) => !before.has(c.id));
+      if (!newCap) return;
+      onChange?.({ kind: 'addChild', parentId, newCap, result: mutation.result });
+    },
+    [map, readOnly, onChange],
+  );
+
+  const onDeleteNode = useCallback(
+    (id: number) => {
+      if (readOnly) return;
+      const mutation = deleteWithDescendants(map, id);
+      if (!mutation.ok || !mutation.result) return;
+      onChange?.({ kind: 'delete', id, result: mutation.result });
+    },
+    [map, readOnly, onChange],
+  );
+
+  const onRestoreFromBacklog = useCallback(
+    (id: number, parentId: number) => {
+      if (readOnly) return;
+      const mutation = restoreFromBacklog(map, id, parentId);
+      if (!mutation.ok || !mutation.result) return;
+      onChange?.({ kind: 'restoreFromBacklog', id, parentId, result: mutation.result });
+    },
+    [map, readOnly, onChange],
+  );
+
+  const onNormalise = useCallback(() => {
+    if (readOnly) return;
+    onChange?.({ kind: 'normaliseAddresses', result: normaliseAddresses(map) });
+  }, [map, readOnly, onChange]);
+
+  const onToggleCollapse = useCallback((id: number) => {
+    setCollapsedIds((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+  }, []);
+
+  const buildNodes = useCallback((): Node[] => {
+    const rootNode: Node<CapabilityRootNodeData> = {
+      id: ROOT_NODE_ID,
+      type: 'capabilityRoot',
+      position: { x: layout.rootNode.x, y: layout.rootNode.y },
+      draggable: false,
+      data: { label: rootLabel, theme },
+    };
+    const cardNodes: Node<CapabilityCardNodeData>[] = layout.nodes.map((n) => ({
+      id: String(n.id),
+      type: 'capabilityCard',
+      position: { x: n.x, y: n.y },
+      draggable: !readOnly,
+      data: {
+        capability: n.data!,
+        theme,
+        maturityColours,
+        readOnly,
+        isDropTarget: hoveredId === n.id,
+        hasHiddenChildren: n.hasHiddenChildren,
+        isCollapsed: collapsedIds.has(n.id),
+        onAddChild,
+        onDelete: onDeleteNode,
+        onToggleCollapse,
+      },
+    }));
+    return [rootNode, ...cardNodes];
+  }, [layout, theme, rootLabel, readOnly, hoveredId, collapsedIds, maturityColours, onAddChild, onDeleteNode, onToggleCollapse]);
+
+  const buildEdges = useCallback((): Edge[] => {
+    return layout.edges.map((e) => ({
+      id: `e${e.source}-${e.target}`,
+      source: e.source === 'root' ? ROOT_NODE_ID : String(e.source),
+      target: String(e.target),
+      type: 'default',
+      style: { stroke: theme.edgeColor, strokeWidth: theme.edgeWidth },
+    }));
+  }, [layout.edges, theme]);
+
+  const [nodes, setNodes, onNodesChange] = useNodesState(buildNodes());
+  const [edges, setEdges, onEdgesChange] = useEdgesState(buildEdges());
+
+  useEffect(() => {
+    setNodes(buildNodes());
+    setEdges(buildEdges());
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [layout, theme, readOnly, hoveredId, collapsedIds, maturityColours]);
+
+  const checkIntersection = useCallback((a: Node, b: Node): boolean => {
+    const midX = a.position.x + 125;
+    const midY = a.position.y + 32;
+    return midX > b.position.x && midX < b.position.x + 250 && midY > b.position.y && midY < b.position.y + 64;
+  }, []);
+
+  const onNodeDrag: NodeDragHandler = useCallback(
+    (_event, node) => {
+      if (readOnly) return;
+      const hit = nodes.find((n) => n.id !== node.id && checkIntersection(node, n));
+      if (!hit) {
+        setHoveredId(null);
+      } else {
+        setHoveredId(hit.id === ROOT_NODE_ID ? 'root' : Number(hit.id));
+      }
+    },
+    [readOnly, nodes, checkIntersection],
+  );
+
+  const onNodeDragStop: NodeDragHandler = useCallback(
+    (event, node) => {
+      if (readOnly) {
+        setHoveredId(null);
+        return;
+      }
+      const sourceId = Number(node.id);
+      const mouseEvent = event as unknown as MouseEvent;
+      const dropEl = typeof document !== 'undefined' && 'clientX' in mouseEvent
+        ? document.elementFromPoint(mouseEvent.clientX, mouseEvent.clientY)
+        : null;
+      let dropTarget: DropTarget;
+      if (dropEl?.closest('[data-capmap-backlog-zone]')) dropTarget = { kind: 'backlog' };
+      else if (hoveredId === 'root') dropTarget = { kind: 'root' };
+      else if (hoveredId != null) dropTarget = { kind: 'node', id: hoveredId };
+      else dropTarget = null;
+      const change = computeDragOutcome(map, sourceId, dropTarget);
+      if (change) onChange?.(change);
+      setHoveredId(null);
+    },
+    [readOnly, hoveredId, map, onChange],
+  );
+
+  const onNodeDoubleClick: NodeMouseHandler = useCallback(
+    (_event, node) => {
+      const cap = map.capabilities.find((c) => c.id === Number(node.id));
+      if (cap) onEditRequest?.(cap);
+    },
+    [map.capabilities, onEditRequest],
+  );
+
+  const onBacklogItemDragStart = useCallback((event: React.DragEvent, capId: number) => {
+    event.dataTransfer.setData(BACKLOG_DRAG_MIME, String(capId));
+    event.dataTransfer.effectAllowed = 'move';
+  }, []);
+
+  const onCanvasDragOver = useCallback(
+    (event: React.DragEvent) => {
+      if (readOnly) return;
+      event.preventDefault();
+    },
+    [readOnly],
+  );
+
+  const onCanvasDrop = useCallback(
+    (event: React.DragEvent) => {
+      if (readOnly) return;
+      event.preventDefault();
+      const idStr = event.dataTransfer.getData(BACKLOG_DRAG_MIME);
+      if (!idStr) return;
+      const capId = Number(idStr);
+      const targetEl = document.elementFromPoint(event.clientX, event.clientY);
+      const nodeEl = targetEl?.closest('.react-flow__node');
+      const targetIdAttr = nodeEl?.getAttribute('data-id');
+      if (targetIdAttr == null) return;
+      const parentId = targetIdAttr === ROOT_NODE_ID ? 0 : Number(targetIdAttr);
+      onRestoreFromBacklog(capId, parentId);
+    },
+    [readOnly, onRestoreFromBacklog],
+  );
+
+  const showBacklogPanel = showBacklog && backlogCaps.length > 0;
+
+  return (
+    <div style={{ display: 'flex', width: '100%', height: '100%' }}>
+      {showBacklogPanel && (
+        <div
+          data-capmap-backlog-zone
+          style={{ width: 220, flexShrink: 0, borderRight: '1px solid #e2e8f0', padding: 10, overflowY: 'auto', background: '#f8fafc' }}
+        >
+          <div style={{ fontWeight: 700, fontSize: 12, color: '#334155', marginBottom: 8 }}>Backlog</div>
+          {backlogCaps.map((cap) => (
+            <div
+              key={cap.id}
+              draggable={!readOnly}
+              onDragStart={(e) => onBacklogItemDragStart(e, cap.id)}
+              onDoubleClick={() => onEditRequest?.(cap)}
+              title="Drag onto a card (or the root) to set its parent"
+              style={{ padding: 8, marginBottom: 6, background: '#ffffff', border: '1px solid #cbd5e1', borderRadius: 6, fontSize: 11, cursor: readOnly ? 'default' : 'grab' }}
+            >
+              <div style={{ fontWeight: 600 }}>{cap.name}</div>
+            </div>
+          ))}
+        </div>
+      )}
+
+      <div style={{ flex: 1, position: 'relative' }} onDragOver={onCanvasDragOver} onDrop={onCanvasDrop}>
+        <ReactFlow
+          nodes={nodes}
+          edges={edges}
+          onNodesChange={readOnly ? undefined : onNodesChange}
+          onEdgesChange={readOnly ? undefined : onEdgesChange}
+          nodeTypes={nodeTypes}
+          nodesDraggable={!readOnly}
+          nodesConnectable={false}
+          onNodeDrag={onNodeDrag}
+          onNodeDragStop={onNodeDragStop}
+          onNodeDoubleClick={onNodeDoubleClick}
+          connectionLineType={ConnectionLineType.Bezier}
+          fitView
+        >
+          <Background />
+          <Controls />
+          {showMiniMap && <MiniMap pannable zoomable />}
+          {!readOnly && (
+            <Panel position="top-right">
+              <button type="button" onClick={onNormalise} style={{ fontSize: 11, padding: '4px 8px', cursor: 'pointer' }}>
+                Normalise addresses
+              </button>
+            </Panel>
+          )}
+        </ReactFlow>
+      </div>
+    </div>
+  );
+}
+
+export function CapabilityMapView(props: CapabilityMapViewProps): React.ReactElement {
+  return <CapabilityMapViewInner {...props} />;
+}

package/src/capability-map/CapabilityRootNode.tsx

@@ -0,0 +1,38 @@
+import React, { memo } from 'react';
+import { Handle, Position } from 'reactflow';
+import type { ThemeTokens } from './dsm-theme.js';
+
+export interface CapabilityRootNodeData {
+  label: string;
+  theme: Required<ThemeTokens>;
+}
+
+/** The virtual organisation root — single node, no maturity dot, no
+ *  add/delete/collapse affordances (it isn't a mutable Capability). */
+const CapabilityRootNode = memo(({ data }: { data: CapabilityRootNodeData }) => (
+  <div
+    style={{
+      width: 200,
+      height: 64,
+      background: data.theme.rootFill,
+      color: data.theme.rootTextColor,
+      borderRadius: 8,
+      border: `1px solid ${data.theme.cardBorderColor}`,
+      boxShadow: '0 1px 4px rgba(0,0,0,0.12)',
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      textAlign: 'center',
+      fontWeight: 700,
+      fontSize: 12,
+      padding: '4px 10px',
+    }}
+  >
+    <Handle type="source" position={Position.Right} style={{ opacity: 0 }} />
+    {data.label}
+  </div>
+));
+
+CapabilityRootNode.displayName = 'CapabilityRootNode';
+
+export default CapabilityRootNode;

package/src/capability-map/__tests__/CapabilityMapView.test.tsx

@@ -0,0 +1,232 @@
+// @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 { CapabilityMapView, computeDragOutcome } from '../CapabilityMapView.js';
+import type { CapabilityMap } from '../dsm-schema.js';
+import type { CapabilityMapChange } from '../CapabilityMapView.js';
+
+// See goals/__tests__/GoalTreeView.test.tsx for why these three shims are
+// needed — reactflow keeps a node `visibility: hidden` (and inert to
+// drag/measurement logic) until ResizeObserver reports its size, and reads
+// the computed transform back out via DOMMatrixReadOnly; jsdom has neither.
+class MockResizeObserver {
+  #callback: ResizeObserverCallback;
+  constructor(callback: ResizeObserverCallback) {
+    this.#callback = callback;
+  }
+  observe(target: Element) {
+    queueMicrotask(() => {
+      this.#callback([{ target, contentRect: target.getBoundingClientRect() } as ResizeObserverEntry], this as unknown as ResizeObserver);
+    });
+  }
+  unobserve() {}
+  disconnect() {}
+}
+
+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]);
+    }
+  }
+}
+
+function makeMap(): CapabilityMap {
+  return {
+    organisation: 'Acme Corp',
+    set_id: 'v1.0',
+    capabilities: [
+      { id: 1, name: 'Customer Acquisition', address: '1.0.0', maturity: [{ date: '2026-04-01', level: 3 }] },
+      { id: 2, name: 'Lead Qualification', address: '1.1.0' },
+      { id: 3, name: 'Inbound Lead Scoring', address: '1.1.1' },
+    ],
+  };
+}
+
+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) {
+    const isNode = this.classList?.contains('react-flow__node');
+    const width = isNode ? 250 : 1000;
+    const height = isNode ? 64 : 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('CapabilityMapView', () => {
+  it('renders the virtual root and every on-diagram capability', async () => {
+    render(<CapabilityMapView map={makeMap()} />);
+    await waitFor(() => {
+      expect(screen.getByText('Acme Corp')).toBeTruthy();
+      expect(screen.getByText('Customer Acquisition')).toBeTruthy();
+      expect(screen.getByText('Lead Qualification')).toBeTruthy();
+      expect(screen.getByText('Inbound Lead Scoring')).toBeTruthy();
+    });
+  });
+
+  it('renders a maturity dot only for capabilities with a maturity snapshot', async () => {
+    render(<CapabilityMapView map={makeMap()} />);
+    await waitFor(() => expect(screen.getByText('Customer Acquisition')).toBeTruthy());
+    expect(screen.getByLabelText('Maturity 3')).toBeTruthy();
+    expect(screen.queryByLabelText(/Maturity/, { selector: '[aria-label="Maturity undefined"]' })).toBeNull();
+  });
+
+  it('shows backlog capabilities in the sidebar, not on canvas', async () => {
+    const map: CapabilityMap = {
+      organisation: 'Acme Corp',
+      set_id: 'v1.0',
+      capabilities: [
+        { id: 1, name: 'Customer Acquisition', address: '1.0.0' },
+        { id: 2, name: 'Parked idea', address: '0.0.0', backlog: true },
+      ],
+    };
+    render(<CapabilityMapView map={map} showBacklog />);
+    await waitFor(() => expect(screen.getByText('Customer Acquisition')).toBeTruthy());
+    expect(screen.getByText('Backlog')).toBeTruthy();
+    expect(screen.getByText('Parked idea')).toBeTruthy();
+  });
+
+  it('does not render add/delete affordances when readOnly', async () => {
+    render(<CapabilityMapView map={makeMap()} readOnly />);
+    await waitFor(() => expect(screen.getByText('Customer Acquisition')).toBeTruthy());
+    expect(screen.queryByLabelText('Add child capability')).toBeNull();
+    expect(screen.queryByLabelText('Delete capability')).toBeNull();
+  });
+
+  it('fires onChange with kind "addChild" when the add-child button is clicked', async () => {
+    const onChange = vi.fn<(e: CapabilityMapChange) => void>();
+    render(<CapabilityMapView map={makeMap()} onChange={onChange} />);
+    await waitFor(() => expect(screen.getByText('Customer Acquisition')).toBeTruthy());
+    const rootCard = document.querySelector('.react-flow__node[data-id="1"]')!;
+    rootCard.querySelector<HTMLElement>('[aria-label="Add child capability"]')!
+      .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.newCap.address).toBe('1.2.0');
+    }
+  });
+
+  it('fires onChange with kind "delete" when the delete button is clicked', async () => {
+    const onChange = vi.fn<(e: CapabilityMapChange) => void>();
+    render(<CapabilityMapView map={makeMap()} onChange={onChange} />);
+    await waitFor(() => expect(screen.getByText('Inbound Lead Scoring')).toBeTruthy());
+    const leafCard = document.querySelector('.react-flow__node[data-id="3"]')!;
+    leafCard.querySelector<HTMLElement>('[aria-label="Delete capability"]')!
+      .dispatchEvent(new MouseEvent('click', { bubbles: true }));
+
+    await waitFor(() => expect(onChange).toHaveBeenCalledTimes(1));
+    expect(onChange.mock.calls[0][0].kind).toBe('delete');
+  });
+
+  it('fires onEditRequest on double-click', async () => {
+    const onEditRequest = vi.fn();
+    render(<CapabilityMapView map={makeMap()} onEditRequest={onEditRequest} />);
+    await waitFor(() => expect(screen.getByText('Customer Acquisition')).toBeTruthy());
+    document.querySelector('.react-flow__node[data-id="1"]')!
+      .dispatchEvent(new MouseEvent('dblclick', { bubbles: true }));
+
+    await waitFor(() => expect(onEditRequest).toHaveBeenCalledTimes(1));
+    expect(onEditRequest.mock.calls[0][0]).toMatchObject({ id: 1, name: 'Customer Acquisition' });
+  });
+
+  it('fires onChange with kind "normaliseAddresses" from the toolbar button', async () => {
+    const onChange = vi.fn<(e: CapabilityMapChange) => void>();
+    render(<CapabilityMapView map={makeMap()} onChange={onChange} />);
+    await waitFor(() => expect(screen.getByText('Customer Acquisition')).toBeTruthy());
+    screen.getByText('Normalise addresses').dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    await waitFor(() => expect(onChange).toHaveBeenCalledTimes(1));
+    expect(onChange.mock.calls[0][0].kind).toBe('normaliseAddresses');
+  });
+
+  it('fires onChange with kind "restoreFromBacklog" when a backlog card is dropped onto a canvas card', async () => {
+    const map: CapabilityMap = {
+      organisation: 'Acme Corp',
+      set_id: 'v1.0',
+      capabilities: [
+        { id: 1, name: 'Customer Acquisition', address: '1.0.0' },
+        { id: 2, name: 'Parked idea', address: '0.0.0', backlog: true },
+      ],
+    };
+    const onChange = vi.fn<(e: CapabilityMapChange) => void>();
+    render(<CapabilityMapView map={map} onChange={onChange} showBacklog />);
+    await waitFor(() => expect(screen.getByText('Parked idea')).toBeTruthy());
+
+    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('Parked idea').closest('div[draggable]')!;
+    const rootCard = document.querySelector('.react-flow__node[data-id="1"]')!;
+    document.elementFromPoint = vi.fn().mockReturnValue(rootCard);
+
+    fireDnd(backlogItem, 'dragstart', { clientX: 0, clientY: 0 });
+    fireDnd(rootCard, '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.parentId).toBe(1);
+    }
+  });
+});
+
+// Dragging a card is choreographed by reactflow's own pointer/DOM-measurement
+// machinery — see the equivalent note in goals/__tests__/GoalTreeView.test.tsx.
+// computeDragOutcome() is the pure decision this component's onNodeDragStop
+// calls once reactflow reports a drag, tested directly here.
+describe('computeDragOutcome (reparent / moveBranchToBacklog decision logic)', () => {
+  const map = makeMap();
+
+  it('fires a "reparent" change when dropped onto another card', () => {
+    const change = computeDragOutcome(map, 3, { kind: 'node', id: 1 });
+    expect(change?.kind).toBe('reparent');
+    if (change?.kind === 'reparent') {
+      expect(change.sourceId).toBe(3);
+      expect(change.targetId).toBe(1);
+    }
+  });
+
+  it('fires a "reparent" change (promotion to L1) when dropped on the root', () => {
+    const change = computeDragOutcome(map, 2, { kind: 'root' });
+    expect(change?.kind).toBe('reparent');
+    if (change?.kind === 'reparent') {
+      expect(change.targetId).toBe(0);
+      expect(change.result.capabilities.find((c) => c.id === 2)?.address).toBe('2.0.0');
+    }
+  });
+
+  it('fires a "moveBranchToBacklog" change when dropped on the backlog zone', () => {
+    const change = computeDragOutcome(map, 2, { kind: 'backlog' });
+    expect(change?.kind).toBe('moveBranchToBacklog');
+  });
+
+  it('is a no-op when dropped nowhere in particular', () => {
+    expect(computeDragOutcome(map, 2, null)).toBeNull();
+  });
+
+  it('is a no-op when dropped on itself', () => {
+    expect(computeDragOutcome(map, 2, { kind: 'node', id: 2 })).toBeNull();
+  });
+});

package/src/capability-map/__tests__/address.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest';
+import { parseAddress, formatAddress, getLevel, getParentAddress, getFirstFreeAddress, isAddressTaken } from '../address.js';
+import type { Capability } from '../dsm-schema.js';
+
+function cap(id: number, address: string, backlog = false): Capability {
+  return { id, name: `Cap ${id}`, address, backlog };
+}
+
+describe('parseAddress / formatAddress', () => {
+  it('round-trips X.Y.Z', () => {
+    for (const addr of ['1.0.0', '1.2.0', '1.2.3', '0.0.0', '42.7.19']) {
+      expect(formatAddress(parseAddress(addr))).toBe(addr);
+    }
+  });
+
+  it('throws on malformed input', () => {
+    expect(() => parseAddress('1.2')).toThrow();
+    expect(() => parseAddress('1.2.3.4')).toThrow();
+    expect(() => parseAddress('a.b.c')).toThrow();
+  });
+});
+
+describe('getLevel', () => {
+  it('classifies each address shape', () => {
+    expect(getLevel('1.0.0')).toBe(1);
+    expect(getLevel('1.2.0')).toBe(2);
+    expect(getLevel('1.2.3')).toBe(3);
+    expect(getLevel('0.0.0')).toBe('backlog');
+  });
+});
+
+describe('getParentAddress', () => {
+  it('walks up one level at a time', () => {
+    expect(getParentAddress('1.2.3')).toBe('1.2.0');
+    expect(getParentAddress('1.2.0')).toBe('1.0.0');
+    expect(getParentAddress('1.0.0')).toBeNull();
+  });
+});
+
+describe('getFirstFreeAddress / isAddressTaken', () => {
+  it('finds the first unused L2 slot under an L1 parent', () => {
+    const caps = [cap(1, '1.0.0'), cap(2, '1.1.0'), cap(3, '1.2.0')];
+    expect(getFirstFreeAddress('1.0.0', caps)).toBe('1.3.0');
+  });
+
+  it('finds the first unused L3 slot under an L2 parent', () => {
+    const caps = [cap(1, '1.0.0'), cap(2, '1.1.0'), cap(3, '1.1.1')];
+    expect(getFirstFreeAddress('1.1.0', caps)).toBe('1.1.2');
+  });
+
+  it('ignores backlog entries when checking occupancy', () => {
+    const caps = [cap(1, '1.0.0'), cap(2, '0.0.0', true)];
+    expect(isAddressTaken('1.1.0', caps)).toBe(false);
+  });
+
+  it('rejects an L3 address as a parent', () => {
+    expect(() => getFirstFreeAddress('1.1.1', [])).toThrow();
+  });
+});