@stephen-netu/design-system 0.1.0

package/src/n0-node-graph/validate.ts

@@ -0,0 +1,371 @@
+// N0 Node Graph — Validation
+// Pure TypeScript — no side effects, no mutations
+
+import type {
+  GraphSchema,
+  NodeInstance,
+  EdgeDefinition,
+  PortDefinition,
+  NodeDefinition,
+  ValidationError,
+  ValidationResult,
+} from './types';
+
+// Helper: Get a node definition by kind
+function getNodeDefinition(
+  nodeDefinitions: NodeDefinition[],
+  kind: string
+): NodeDefinition | undefined {
+  return nodeDefinitions.find((def) => def.kind === kind);
+}
+
+// Helper: Get a node instance by id
+function getNodeInstance(
+  nodes: NodeInstance[],
+  id: string
+): NodeInstance | undefined {
+  return nodes.find((node) => node.id === id);
+}
+
+// Helper: Get a port definition from a node definition
+function getPortDefinition(
+  nodeDefinition: NodeDefinition,
+  portId: string
+): PortDefinition | undefined {
+  return nodeDefinition.ports.find((port) => port.id === portId);
+}
+
+// Helper: Count connections to a specific port
+function countConnectionsToPort(
+  edges: EdgeDefinition[],
+  nodeId: string,
+  portId: string,
+  direction: 'source' | 'target'
+): number {
+  return edges.filter((edge) => {
+    if (direction === 'source') {
+      return edge.sourceNodeId === nodeId && edge.sourcePortId === portId;
+    }
+    return edge.targetNodeId === nodeId && edge.targetPortId === portId;
+  }).length;
+}
+
+// Helper: Check if an edge is a duplicate
+function isDuplicateEdge(
+  edges: EdgeDefinition[],
+  edge: EdgeDefinition
+): boolean {
+  return edges.some((existing) =>
+    existing.id !== edge.id &&
+    existing.sourceNodeId === edge.sourceNodeId &&
+    existing.sourcePortId === edge.sourcePortId &&
+    existing.targetNodeId === edge.targetNodeId &&
+    existing.targetPortId === edge.targetPortId
+  );
+}
+
+// Validation Rule 1: NodeInstance.kind must reference a registered NodeDefinition.kind
+function validateNodeKindReferences(
+  schema: GraphSchema
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+  
+  for (const node of schema.nodes) {
+    const definition = getNodeDefinition(schema.nodeDefinitions, node.kind);
+    if (!definition) {
+      errors.push({
+        code: 'INVALID_NODE_KIND',
+        message: `Node instance "${node.id}" references undefined kind "${node.kind}"`,
+        nodeId: node.id,
+      });
+    }
+  }
+  
+  return errors;
+}
+
+// Validation Rule 2: Every edge must connect existing nodes and existing ports
+function validateEdgeConnections(
+  schema: GraphSchema
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+  
+  for (const edge of schema.edges) {
+    // Check source node exists
+    const sourceNode = getNodeInstance(schema.nodes, edge.sourceNodeId);
+    if (!sourceNode) {
+      errors.push({
+        code: 'INVALID_SOURCE_NODE',
+        message: `Edge "${edge.id}" references non-existent source node "${edge.sourceNodeId}"`,
+        edgeId: edge.id,
+      });
+      continue;
+    }
+    
+    // Check target node exists
+    const targetNode = getNodeInstance(schema.nodes, edge.targetNodeId);
+    if (!targetNode) {
+      errors.push({
+        code: 'INVALID_TARGET_NODE',
+        message: `Edge "${edge.id}" references non-existent target node "${edge.targetNodeId}"`,
+        edgeId: edge.id,
+      });
+      continue;
+    }
+    
+    // Get node definitions
+    const sourceDef = getNodeDefinition(schema.nodeDefinitions, sourceNode.kind);
+    const targetDef = getNodeDefinition(schema.nodeDefinitions, targetNode.kind);
+    
+    if (!sourceDef) {
+      errors.push({
+        code: 'INVALID_SOURCE_NODE_KIND',
+        message: `Source node "${sourceNode.id}" has no registered definition`,
+        edgeId: edge.id,
+        nodeId: sourceNode.id,
+      });
+      continue;
+    }
+    
+    if (!targetDef) {
+      errors.push({
+        code: 'INVALID_TARGET_NODE_KIND',
+        message: `Target node "${targetNode.id}" has no registered definition`,
+        edgeId: edge.id,
+        nodeId: targetNode.id,
+      });
+      continue;
+    }
+    
+    // Check source port exists
+    const sourcePort = getPortDefinition(sourceDef, edge.sourcePortId);
+    if (!sourcePort) {
+      errors.push({
+        code: 'INVALID_SOURCE_PORT',
+        message: `Edge "${edge.id}" references non-existent source port "${edge.sourcePortId}" on node "${sourceNode.id}"`,
+        edgeId: edge.id,
+        portId: edge.sourcePortId,
+      });
+    }
+    
+    // Check target port exists
+    const targetPort = getPortDefinition(targetDef, edge.targetPortId);
+    if (!targetPort) {
+      errors.push({
+        code: 'INVALID_TARGET_PORT',
+        message: `Edge "${edge.id}" references non-existent target port "${edge.targetPortId}" on node "${targetNode.id}"`,
+        edgeId: edge.id,
+        portId: edge.targetPortId,
+      });
+    }
+  }
+  
+  return errors;
+}
+
+// Validation Rule 3: Port direction — edges go from output port to input port only
+function validatePortDirection(
+  schema: GraphSchema
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+  
+  for (const edge of schema.edges) {
+    const sourceNode = getNodeInstance(schema.nodes, edge.sourceNodeId);
+    const targetNode = getNodeInstance(schema.nodes, edge.targetNodeId);
+    
+    if (!sourceNode || !targetNode) continue;
+    
+    const sourceDef = getNodeDefinition(schema.nodeDefinitions, sourceNode.kind);
+    const targetDef = getNodeDefinition(schema.nodeDefinitions, targetNode.kind);
+    
+    if (!sourceDef || !targetDef) continue;
+    
+    const sourcePort = getPortDefinition(sourceDef, edge.sourcePortId);
+    const targetPort = getPortDefinition(targetDef, edge.targetPortId);
+    
+    if (sourcePort && targetPort) {
+      if (sourcePort.direction !== 'output') {
+        errors.push({
+          code: 'INVALID_PORT_DIRECTION',
+          message: `Edge "${edge.id}" must start from an output port, but port "${edge.sourcePortId}" on node "${sourceNode.id}" is "${sourcePort.direction}"`,
+          edgeId: edge.id,
+          portId: edge.sourcePortId,
+        });
+      }
+      
+      if (targetPort.direction !== 'input') {
+        errors.push({
+          code: 'INVALID_PORT_DIRECTION',
+          message: `Edge "${edge.id}" must end at an input port, but port "${edge.targetPortId}" on node "${targetNode.id}" is "${targetPort.direction}"`,
+          edgeId: edge.id,
+          portId: edge.targetPortId,
+        });
+      }
+    }
+  }
+  
+  return errors;
+}
+
+// Validation Rule 4: Port type compatibility — exact match required
+function validateTypeCompatibility(
+  schema: GraphSchema
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+  
+  for (const edge of schema.edges) {
+    const sourceNode = getNodeInstance(schema.nodes, edge.sourceNodeId);
+    const targetNode = getNodeInstance(schema.nodes, edge.targetNodeId);
+    
+    if (!sourceNode || !targetNode) continue;
+    
+    const sourceDef = getNodeDefinition(schema.nodeDefinitions, sourceNode.kind);
+    const targetDef = getNodeDefinition(schema.nodeDefinitions, targetNode.kind);
+    
+    if (!sourceDef || !targetDef) continue;
+    
+    const sourcePort = getPortDefinition(sourceDef, edge.sourcePortId);
+    const targetPort = getPortDefinition(targetDef, edge.targetPortId);
+    
+    if (sourcePort && targetPort && sourcePort.type !== targetPort.type) {
+      errors.push({
+        code: 'TYPE_MISMATCH',
+        message: `Edge "${edge.id}" connects incompatible types: source port "${edge.sourcePortId}" has type "${sourcePort.type}" but target port "${edge.targetPortId}" has type "${targetPort.type}"`,
+        edgeId: edge.id,
+      });
+    }
+  }
+  
+  return errors;
+}
+
+// Validation Rule 5: Connection limits — port.maxConnections not exceeded
+function validateConnectionLimits(
+  schema: GraphSchema
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+  
+  for (const node of schema.nodes) {
+    const definition = getNodeDefinition(schema.nodeDefinitions, node.kind);
+    if (!definition) continue;
+    
+    for (const port of definition.ports) {
+      const connectionCount = countConnectionsToPort(
+        schema.edges,
+        node.id,
+        port.id,
+        port.direction === 'output' ? 'source' : 'target'
+      );
+      
+      if (connectionCount > port.maxConnections) {
+        errors.push({
+          code: 'MAX_CONNECTIONS_EXCEEDED',
+          message: `Port "${port.id}" on node "${node.id}" has ${connectionCount} connections but maximum allowed is ${port.maxConnections}`,
+          nodeId: node.id,
+          portId: port.id,
+        });
+      }
+    }
+  }
+  
+  return errors;
+}
+
+// Validation Rule 6: Required ports — all required:true ports must have at least one connection
+function validateRequiredPorts(
+  schema: GraphSchema
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+  
+  for (const node of schema.nodes) {
+    const definition = getNodeDefinition(schema.nodeDefinitions, node.kind);
+    if (!definition) continue;
+    
+    for (const port of definition.ports) {
+      if (!port.required) continue;
+      
+      const connectionCount = countConnectionsToPort(
+        schema.edges,
+        node.id,
+        port.id,
+        port.direction === 'output' ? 'source' : 'target'
+      );
+      
+      if (connectionCount === 0) {
+        errors.push({
+          code: 'REQUIRED_PORT_UNCONNECTED',
+          message: `Required port "${port.id}" on node "${node.id}" has no connections`,
+          nodeId: node.id,
+          portId: port.id,
+        });
+      }
+    }
+  }
+  
+  return errors;
+}
+
+// Validation Rule 7: No self-loops (edge source === edge target on same node)
+function validateNoSelfLoops(
+  schema: GraphSchema
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+  
+  for (const edge of schema.edges) {
+    if (edge.sourceNodeId === edge.targetNodeId) {
+      errors.push({
+        code: 'SELF_LOOP',
+        message: `Edge "${edge.id}" creates a self-loop on node "${edge.sourceNodeId}"`,
+        edgeId: edge.id,
+      });
+    }
+  }
+  
+  return errors;
+}
+
+// Validation Rule 8: No duplicate edges (same source port → same target port)
+function validateNoDuplicateEdges(
+  schema: GraphSchema
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+  
+  for (const edge of schema.edges) {
+    if (isDuplicateEdge(schema.edges, edge)) {
+      errors.push({
+        code: 'DUPLICATE_EDGE',
+        message: `Edge "${edge.id}" is a duplicate: same source "${edge.sourceNodeId}:${edge.sourcePortId}" to target "${edge.targetNodeId}:${edge.targetPortId}"`,
+        edgeId: edge.id,
+      });
+    }
+  }
+  
+  return errors;
+}
+
+/**
+ * Validates a graph schema against all 8 validation rules.
+ * 
+ * Pure function — no side effects, no mutation of input.
+ * 
+ * @param schema - The graph schema to validate
+ * @returns ValidationResult with valid flag and array of errors
+ */
+export function validateGraph(schema: GraphSchema): ValidationResult {
+  // Collect all errors from all validation rules
+  const allErrors: ValidationError[] = [
+    ...validateNodeKindReferences(schema),
+    ...validateEdgeConnections(schema),
+    ...validatePortDirection(schema),
+    ...validateTypeCompatibility(schema),
+    ...validateConnectionLimits(schema),
+    ...validateRequiredPorts(schema),
+    ...validateNoSelfLoops(schema),
+    ...validateNoDuplicateEdges(schema),
+  ];
+  
+  return {
+    valid: allErrors.length === 0,
+    errors: allErrors,
+  };
+}

package/src/n1-flow-canvas/FlowCanvas.svelte

@@ -0,0 +1,202 @@
+<script lang="ts">
+  // N1 FlowCanvas — Canvas 2D graph with ELK layout + BFS edge reveal
+  // S-02: BFS order drives edge reveal stagger (no Math.random)
+  // S-05: worker terminated on component destroy
+
+  import { onMount, onDestroy } from 'svelte';
+  import { Canvas, Layer } from 'svelte-canvas';
+  import { getArrow } from 'perfect-arrows';
+  import type { GraphSnapshot, GraphStateApi } from './types.js';
+  import { GraphState } from './graph-state.svelte.js';
+  import { runLayout } from './layout.js';
+  import { EDGE_REVEAL_STAGGER_MS } from './types.js';
+
+  // ── Props ────────────────────────────────────────────────────────────────────
+
+  interface Props {
+    snapshot: GraphSnapshot;
+    state?: GraphStateApi;
+    width?: number;
+    height?: number;
+  }
+
+  // Destructure as `graphStateProp` to avoid conflict with the `$state` rune.
+  let { snapshot, state: graphStateProp, width = 800, height = 600 }: Props = $props();
+
+  // ── Internal state ──────────────────────────────────────────────────────────
+
+  // svelte-ignore state_referenced_locally
+  const _state = graphStateProp instanceof GraphState ? graphStateProp : new GraphState();
+  let mounted = false;
+  /** Edge reveal offsets: edge id → 0.0 (hidden) .. 1.0 (fully drawn) */
+  let edgeOffsets = $state<Map<string, number>>(new Map());
+
+  // ── Layout (runs on main thread — ELK is async, won't block UI) ─────────────
+  // The previous Worker approach failed in Tauri: ELK's bundled JS tries to
+  // spawn a sub-Worker inside the layout Worker, which Tauri's WKWebView
+  // doesn't support (nested Workers unavailable, Worker = undefined in scope).
+
+  function requestLayout() {
+    if (!mounted) return;
+    runLayout(snapshot, width, height).then(result => {
+      _state.applyLayout(result);
+      scheduleEdgeReveal(result.bfsOrder);
+    }).catch(() => {
+      // Layout failed — leave existing positions in place
+    });
+  }
+
+  onMount(() => {
+    mounted = true;
+    requestLayout();
+  });
+
+  onDestroy(() => {
+    mounted = false;
+    if (_state instanceof GraphState) _state.destroy();
+  });
+
+  // Re-layout when snapshot changes
+  $effect(() => {
+    void snapshot;
+    requestLayout();
+  });
+
+  // ── Edge reveal animation (BFS stagger) ────────────────────────────────────
+
+  function scheduleEdgeReveal(bfsOrder: ReadonlyArray<string>) {
+    // Reset all edges to hidden
+    const next = new Map<string, number>();
+    for (const e of snapshot.edges) next.set(e.id, 0.0);
+    edgeOffsets = next;
+
+    // BFS order: each node index N → reveal its outgoing edges after N * STAGGER_MS
+    const nodeIndex = new Map<string, number>();
+    bfsOrder.forEach((id, i) => nodeIndex.set(id, i));
+
+    for (const edge of snapshot.edges) {
+      const idx = nodeIndex.get(edge.sourceId) ?? 0;
+      setTimeout(() => {
+        edgeOffsets = new Map(edgeOffsets).set(edge.id, 1.0);
+      }, idx * EDGE_REVEAL_STAGGER_MS);
+    }
+  }
+
+  // ── Design tokens ──────────────────────────────────────────────────────────
+
+  const COLORS = {
+    bg:          '#1a1a1a',
+    node:        '#2a2a2a',
+    nodeBorder:  '#b87333',
+    nodeHover:   '#3a3a3a',
+    nodeText:    '#e8e0d0',
+    edgeLine:    '#b87333',
+    edgeFade:    '#5a4a30',
+    focus:       '#d4943a',
+  };
+
+  const NODE_RADIUS = 4;
+  const FONT = '12px var(--font-mono, monospace)';
+
+  // ── Render ──────────────────────────────────────────────────────────────────
+
+  function render({ context }: { context: CanvasRenderingContext2D }) {
+    const positions = _state.positions;
+    const focusId   = (_state as GraphState).focusCenterId;
+
+    context.clearRect(0, 0, width, height);
+
+    // Background
+    context.fillStyle = COLORS.bg;
+    context.fillRect(0, 0, width, height);
+
+    // ── Edges ──
+    context.font = FONT;
+    for (const edge of snapshot.edges) {
+      const src = positions.get(edge.sourceId);
+      const tgt = positions.get(edge.targetId);
+      if (!src || !tgt) continue;
+
+      const progress = edgeOffsets.get(edge.id) ?? 0;
+      if (progress <= 0) continue;
+
+      const sx = src.x + src.width  / 2;
+      const sy = src.y + src.height / 2;
+      const tx = tgt.x + tgt.width  / 2;
+      const ty = tgt.y + tgt.height / 2;
+
+      const [ax, ay, cx, cy, ex, ey, ae] = getArrow(sx, sy, tx, ty, {
+        bow: 0.2,
+        stretch: 0.4,
+        padStart: src.width / 2 + 4,
+        padEnd:   tgt.width / 2 + 4,
+      });
+
+      // BFS reveal via lineDashOffset
+      const path = new Path2D();
+      path.moveTo(ax, ay);
+      path.quadraticCurveTo(cx, cy, ex, ey);
+
+      // Estimate path length for dash sizing (approximation)
+      const dx = ex - ax, dy2 = ey - ay;
+      const approxLen = Math.sqrt(dx * dx + dy2 * dy2) * 1.2;
+      const dash = approxLen * progress;
+
+      context.save();
+      context.strokeStyle = progress >= 1.0 ? COLORS.edgeLine : COLORS.edgeFade;
+      context.lineWidth   = 1.5;
+      context.setLineDash([dash, approxLen]);
+      context.lineDashOffset = 0;
+      context.stroke(path);
+      context.restore();
+
+      // Arrowhead
+      if (progress >= 1.0) {
+        context.save();
+        context.fillStyle = COLORS.edgeLine;
+        context.translate(ex, ey);
+        context.rotate(ae);
+        context.beginPath();
+        context.moveTo(0, 0);
+        context.lineTo(-8, -4);
+        context.lineTo(-8,  4);
+        context.closePath();
+        context.fill();
+        context.restore();
+      }
+    }
+
+    // ── Nodes ──
+    for (const node of snapshot.nodes) {
+      const pos = positions.get(node.id);
+      if (!pos) continue;
+
+      const isFocus  = node.id === focusId;
+      const { x, y, width: w, height: h } = pos;
+
+      // Node body
+      context.fillStyle   = isFocus ? COLORS.focus : COLORS.node;
+      context.strokeStyle = COLORS.nodeBorder;
+      context.lineWidth   = isFocus ? 2 : 1;
+
+      context.beginPath();
+      context.roundRect(x, y, w, h, NODE_RADIUS);
+      context.fill();
+      context.stroke();
+
+      // Label
+      context.fillStyle  = COLORS.nodeText;
+      context.font       = FONT;
+      context.textAlign  = 'center';
+      context.textBaseline = 'middle';
+      // Truncate if needed
+      const maxWidth = w - 16;
+      const label = node.label.length > 18 ? node.label.slice(0, 16) + '…' : node.label;
+      context.fillText(label, x + w / 2, y + h / 2, maxWidth);
+    }
+  }
+</script>
+
+<Canvas {width} {height}>
+  <Layer {render} />
+</Canvas>

package/src/n1-flow-canvas/graph-state.svelte.ts

@@ -0,0 +1,95 @@
+// N1 GraphState — Svelte 5 runes, Spring-animated node positions
+// S-02: positions lerped deterministically via rAF loop (no Math.random)
+// S-05: animation loop bounded by convergence threshold
+
+import type { NodeLayout, LayoutResult, GraphStateApi } from './types.js';
+
+const LERP_FACTOR   = 0.12;   // per frame (bounded, S-05)
+const SETTLE_THRESH = 0.5;    // pixels — stop animating below this delta
+const MAX_FRAMES    = 240;    // ~4s at 60fps hard cap (S-05 killability)
+
+export class GraphState implements GraphStateApi {
+  positions = $state<Map<string, NodeLayout>>(new Map());
+  bfsOrder  = $state<ReadonlyArray<string>>([]);
+
+  // Focus semantics
+  focusCenterId  = $state<string | null>(null);
+  layoutRootId   = $state<string | null>(null);
+
+  private _targets  = new Map<string, NodeLayout>();
+  private _rafId: number | null = null;
+  private _frameCount = 0;
+
+  // Callback invoked by FlowCanvas when layoutRootId changes
+  onLayoutRootChange: ((nodeId: string) => void) | null = null;
+
+  applyLayout(result: LayoutResult): void {
+    this._targets = new Map(result.positions);
+    this.bfsOrder = result.bfsOrder;
+    this._frameCount = 0;
+    this._startAnimation();
+  }
+
+  setFocusCenter(nodeId: string): void {
+    // Re-centers Poincaré disk — does NOT trigger re-layout
+    this.focusCenterId = nodeId;
+  }
+
+  setLayoutRoot(nodeId: string): void {
+    this.layoutRootId = nodeId;
+    this.onLayoutRootChange?.(nodeId);
+  }
+
+  // ── Animation ──────────────────────────────────────────────────────────────
+
+  private _startAnimation(): void {
+    if (this._rafId !== null) cancelAnimationFrame(this._rafId);
+    this._tick();
+  }
+
+  private _tick = (): void => {
+    if (this._frameCount >= MAX_FRAMES) {
+      // Force-snap to targets on hard cap (S-05)
+      this.positions = new Map(this._targets);
+      this._rafId = null;
+      return;
+    }
+
+    let maxDelta = 0;
+    const next = new Map<string, NodeLayout>();
+
+    for (const [id, target] of this._targets) {
+      const current = this.positions.get(id);
+      if (!current) {
+        // First appearance — snap directly, no lerp
+        next.set(id, { ...target });
+        continue;
+      }
+      const nx = current.x + (target.x - current.x) * LERP_FACTOR;
+      const ny = current.y + (target.y - current.y) * LERP_FACTOR;
+      const dx = Math.abs(target.x - nx);
+      const dy = Math.abs(target.y - ny);
+      if (dx > maxDelta) maxDelta = dx;
+      if (dy > maxDelta) maxDelta = dy;
+      next.set(id, { id, x: nx, y: ny, width: target.width, height: target.height });
+    }
+
+    this.positions = next;
+    this._frameCount++;
+
+    if (maxDelta > SETTLE_THRESH) {
+      this._rafId = requestAnimationFrame(this._tick);
+    } else {
+      // Settled — snap to exact targets
+      this.positions = new Map(this._targets);
+      this._rafId = null;
+    }
+  };
+
+  destroy(): void {
+    if (this._rafId !== null) {
+      cancelAnimationFrame(this._rafId);
+      this._rafId = null;
+    }
+  }
+}

package/src/n1-flow-canvas/index.ts

@@ -0,0 +1,21 @@
+// N1 Flow Canvas — Canvas 2D graph with ELK layout + BFS edge reveal
+// Depends on: graphology, elkjs, perfect-arrows, svelte-canvas
+
+export type {
+  GraphNode,
+  GraphEdge,
+  GraphSnapshot,
+  NodeLayout,
+  LayoutResult,
+  WorkerIn,
+  WorkerOut,
+  WorkerMessage,
+  GraphStateApi,
+  EdgeRevealState,
+} from './types.js';
+
+export { EDGE_REVEAL_STAGGER_MS } from './types.js';
+
+export { default as FlowCanvas } from './FlowCanvas.svelte';
+export { GraphState } from './graph-state.svelte';
+export { nodeHitTest, domEventToCanvasCoords, parseMentionEdges, parseGroupedSequenceEdges } from './utils.js';