@stigmer/react 1.0.4 → 2.0.1

package/src/workflow/layout/elk-layout-engine.ts

@@ -0,0 +1,125 @@
+/// <reference path="./elkjs.d.ts" />
+
+import type { LayoutEngine, LayoutInput, LayoutResult, ElkGraph, ElkLayoutResult } from "./types";
+import { preprocessForElk } from "./workflow-preprocessor";
+import { postprocessElkResult } from "./layout-postprocessor";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ElkLayoutEngineOptions {
+  /**
+   * Factory function that creates a Web Worker for off-main-thread layout.
+   * When provided, the engine uses `elkjs/lib/elk-api.js` (lightweight ~5KB)
+   * and delegates computation to the worker.
+   *
+   * When omitted, the engine dynamically imports `elkjs/lib/elk.bundled.js`
+   * which includes the full WASM layout algorithms (~1.5MB) and runs on
+   * the main thread with an async API.
+   *
+   * Example (Next.js / Vite):
+   * ```ts
+   * const workerFactory = () =>
+   *   new Worker(new URL('elkjs/lib/elk-worker.min.js', import.meta.url));
+   * ```
+   */
+  workerFactory?: () => Worker;
+  /**
+   * Additional ELK layout options to merge with workflow defaults.
+   * See: https://eclipse.dev/elk/reference/options.html
+   */
+  layoutOptions?: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates an ELK-based layout engine with optional Web Worker support.
+ *
+ * This function dynamically imports elkjs — the import is deferred so that
+ * the ~1.5MB WASM module is only loaded when layout is first requested,
+ * not at SDK initialization time.
+ *
+ * If elkjs is not installed (optional peer dependency), the import will
+ * reject and the caller should fall back to the dagre engine.
+ *
+ * @throws If elkjs cannot be imported (not installed or bundler misconfiguration).
+ */
+export async function createElkLayoutEngine(
+  options?: ElkLayoutEngineOptions,
+): Promise<LayoutEngine> {
+  const elk = await instantiateElk(options);
+  return new ElkLayoutEngineImpl(elk, options?.layoutOptions);
+}
+
+// ---------------------------------------------------------------------------
+// ELK Instantiation
+// ---------------------------------------------------------------------------
+
+interface ElkInstance {
+  layout(graph: unknown): Promise<unknown>;
+}
+
+async function instantiateElk(options?: ElkLayoutEngineOptions): Promise<ElkInstance> {
+  if (options?.workerFactory) {
+    try {
+      const module = await import("elkjs/lib/elk-api.js");
+      const ELK = module.default ?? module;
+      return new ELK({ workerFactory: options.workerFactory });
+    } catch {
+      // Worker path failed — fall through to bundled
+    }
+  }
+
+  const module = await import("elkjs/lib/elk.bundled.js");
+  const ELK = module.default ?? module;
+  return new ELK();
+}
+
+// ---------------------------------------------------------------------------
+// Engine Implementation
+// ---------------------------------------------------------------------------
+
+class ElkLayoutEngineImpl implements LayoutEngine {
+  readonly name = "elk-layered";
+  private readonly elk: ElkInstance;
+  private readonly optionOverrides: Record<string, string> | undefined;
+  private terminated = false;
+
+  constructor(elk: ElkInstance, optionOverrides?: Record<string, string>) {
+    this.elk = elk;
+    this.optionOverrides = optionOverrides;
+  }
+
+  async layout(input: LayoutInput): Promise<LayoutResult> {
+    if (this.terminated) {
+      throw new Error("ELK layout engine has been terminated.");
+    }
+
+    const start = performance.now();
+
+    const elkGraph: ElkGraph = preprocessForElk(input, this.optionOverrides);
+    const rawResult = await this.elk.layout(elkGraph as unknown);
+    const elkResult = rawResult as ElkLayoutResult;
+
+    const durationMs = performance.now() - start;
+
+    return postprocessElkResult(
+      elkResult,
+      input.scope,
+      input.graph,
+      durationMs,
+      this.name,
+    );
+  }
+
+  terminate(): void {
+    this.terminated = true;
+    if ("terminateWorker" in this.elk && typeof (this.elk as Record<string, unknown>).terminateWorker === "function") {
+      (this.elk as { terminateWorker: () => void }).terminateWorker();
+    }
+  }
+}

package/src/workflow/layout/elkjs.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Ambient module declarations for elkjs subpath imports.
+ *
+ * elkjs is an optional peer dependency (AD-T03-001). These declarations
+ * allow TypeScript to resolve the dynamic imports without requiring the
+ * package to be installed at type-check time in all environments.
+ */
+
+declare module "elkjs/lib/elk-api.js" {
+  interface ElkConstructorOptions {
+    workerFactory?: () => Worker;
+    defaultLayoutOptions?: Record<string, string>;
+  }
+
+  class ELK {
+    constructor(options?: ElkConstructorOptions);
+    layout(graph: unknown): Promise<unknown>;
+    terminateWorker(): void;
+  }
+
+  export default ELK;
+}
+
+declare module "elkjs/lib/elk.bundled.js" {
+  interface ElkConstructorOptions {
+    defaultLayoutOptions?: Record<string, string>;
+  }
+
+  class ELK {
+    constructor(options?: ElkConstructorOptions);
+    layout(graph: unknown): Promise<unknown>;
+  }
+
+  export default ELK;
+}

package/src/workflow/layout/index.ts

@@ -0,0 +1,55 @@
+// ---------------------------------------------------------------------------
+// Types (public API for platform builders implementing custom engines)
+// ---------------------------------------------------------------------------
+
+export type {
+  LayoutEngine,
+  LayoutInput,
+  LayoutResult,
+  LayoutScope,
+  LayoutOptions,
+  NodeDimensions,
+  Position2D,
+  NodePortAssignment,
+  PortDefinition,
+  PortSide,
+} from "./types";
+
+// ---------------------------------------------------------------------------
+// Engine factories
+// ---------------------------------------------------------------------------
+
+export { createDagreLayoutEngine } from "./dagre-layout-engine";
+export { createElkLayoutEngine } from "./elk-layout-engine";
+export type { ElkLayoutEngineOptions } from "./elk-layout-engine";
+
+// ---------------------------------------------------------------------------
+// React behavior hooks
+// ---------------------------------------------------------------------------
+
+export { useWorkflowLayout } from "./use-workflow-layout";
+export type { UseWorkflowLayoutOptions, UseWorkflowLayoutReturn } from "./use-workflow-layout";
+
+export { useElkLayoutEngine } from "./useElkLayoutEngine";
+export type { UseElkLayoutEngineOptions } from "./useElkLayoutEngine";
+
+// ---------------------------------------------------------------------------
+// Synchronous layout utility (shared by editor and execution graph)
+// ---------------------------------------------------------------------------
+
+export { applyDagreLayout } from "./apply-dagre-layout";
+export type { DagreLayoutConfig } from "../canvas-constants";
+
+// ---------------------------------------------------------------------------
+// Registry-aware node dimensions (canonical adapter from visual registry)
+// ---------------------------------------------------------------------------
+
+export { registryNodeDimensions } from "./registry-dimensions";
+
+// ---------------------------------------------------------------------------
+// Preprocessor (exported for advanced use cases and testing)
+// ---------------------------------------------------------------------------
+
+export { preprocessForElk, ELK_WORKFLOW_DEFAULTS } from "./workflow-preprocessor";
+export { computePortAssignments, computeNodePorts } from "./port-assignment";
+export { postprocessElkResult } from "./layout-postprocessor";

package/src/workflow/layout/layout-postprocessor.ts

@@ -0,0 +1,197 @@
+import type { WorkflowGraphModel, WorkflowGraphEdge } from "../workflow-graph-model";
+import type {
+  ElkLayoutResult,
+  ElkEdgeSection,
+  LayoutResult,
+  LayoutScope,
+  Position2D,
+} from "./types";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Transforms ELK layout output into a {@link LayoutResult}, applying scope
+ * filtering to determine which nodes receive new positions.
+ *
+ * ELK produces center coordinates for nodes. This function converts them
+ * to top-left coordinates (React Flow convention: position = top-left corner).
+ *
+ * Scope filtering (AD-T03-005):
+ * - `whole-graph`: all computed positions are included
+ * - `selected`: only positions for nodes in the selection set are included
+ * - `downstream`: only positions for the target node and all reachable
+ *   downstream nodes (via BFS on edges) are included
+ *
+ * @param elkResult - The raw result from `elk.layout()`.
+ * @param scope - Which nodes should receive new positions.
+ * @param graph - The original graph (needed for downstream traversal).
+ * @param durationMs - Wall-clock layout time to include in the result.
+ * @param engine - Engine name for attribution.
+ */
+export function postprocessElkResult(
+  elkResult: ElkLayoutResult,
+  scope: LayoutScope,
+  graph: WorkflowGraphModel,
+  durationMs: number,
+  engine: string,
+): LayoutResult {
+  const allPositions = extractPositions(elkResult);
+  const edgePaths = extractEdgePaths(elkResult);
+  const filteredPositions = filterByScope(allPositions, scope, graph);
+
+  return {
+    positions: filteredPositions,
+    edgePaths: edgePaths.size > 0 ? edgePaths : undefined,
+    durationMs,
+    engine,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Position extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * ELK returns node positions as (x, y) relative to the parent.
+ * Since we have a flat graph (no compound nodes), all positions are
+ * relative to the root — which maps directly to React Flow coordinates.
+ *
+ * ELK's (x, y) is the top-left corner of the node bounding box,
+ * which matches React Flow's position convention.
+ */
+function extractPositions(elkResult: ElkLayoutResult): Map<string, Position2D> {
+  const positions = new Map<string, Position2D>();
+
+  if (!elkResult.children) return positions;
+
+  for (const child of elkResult.children) {
+    positions.set(child.id, { x: child.x, y: child.y });
+  }
+
+  return positions;
+}
+
+// ---------------------------------------------------------------------------
+// Edge path extraction
+// ---------------------------------------------------------------------------
+
+function extractEdgePaths(elkResult: ElkLayoutResult): Map<string, Position2D[]> {
+  const paths = new Map<string, Position2D[]>();
+
+  if (!elkResult.edges) return paths;
+
+  for (const edge of elkResult.edges) {
+    if (!edge.sections || edge.sections.length === 0) continue;
+
+    const points = flattenEdgeSections(edge.sections);
+    if (points.length > 0) {
+      paths.set(edge.id, points);
+    }
+  }
+
+  return paths;
+}
+
+function flattenEdgeSections(sections: readonly ElkEdgeSection[]): Position2D[] {
+  const points: Position2D[] = [];
+
+  for (const section of sections) {
+    points.push(section.startPoint);
+    if (section.bendPoints) {
+      points.push(...section.bendPoints);
+    }
+    points.push(section.endPoint);
+  }
+
+  return points;
+}
+
+// ---------------------------------------------------------------------------
+// Scope filtering
+// ---------------------------------------------------------------------------
+
+function filterByScope(
+  positions: Map<string, Position2D>,
+  scope: LayoutScope,
+  graph: WorkflowGraphModel,
+): ReadonlyMap<string, Position2D> {
+  switch (scope.type) {
+    case "whole-graph":
+      return positions;
+
+    case "selected":
+      return filterToSet(positions, scope.nodeIds);
+
+    case "downstream":
+      return filterToDownstream(positions, scope.fromNodeId, graph.edges);
+  }
+}
+
+function filterToSet(
+  positions: Map<string, Position2D>,
+  nodeIds: ReadonlySet<string>,
+): ReadonlyMap<string, Position2D> {
+  const filtered = new Map<string, Position2D>();
+  for (const [id, pos] of positions) {
+    if (nodeIds.has(id)) {
+      filtered.set(id, pos);
+    }
+  }
+  return filtered;
+}
+
+function filterToDownstream(
+  positions: Map<string, Position2D>,
+  fromNodeId: string,
+  edges: readonly WorkflowGraphEdge[],
+): ReadonlyMap<string, Position2D> {
+  const reachable = computeDownstreamSet(fromNodeId, edges);
+  const filtered = new Map<string, Position2D>();
+  for (const [id, pos] of positions) {
+    if (reachable.has(id)) {
+      filtered.set(id, pos);
+    }
+  }
+  return filtered;
+}
+
+/**
+ * BFS from a starting node following directed edges to find all
+ * reachable downstream nodes (including the starting node itself).
+ */
+function computeDownstreamSet(
+  fromNodeId: string,
+  edges: readonly WorkflowGraphEdge[],
+): ReadonlySet<string> {
+  const adjacency = new Map<string, string[]>();
+  for (const edge of edges) {
+    const targets = adjacency.get(edge.source);
+    if (targets) {
+      targets.push(edge.target);
+    } else {
+      adjacency.set(edge.source, [edge.target]);
+    }
+  }
+
+  const visited = new Set<string>();
+  const queue: string[] = [fromNodeId];
+
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    if (visited.has(current)) continue;
+    visited.add(current);
+
+    const neighbors = adjacency.get(current);
+    if (neighbors) {
+      for (const neighbor of neighbors) {
+        if (!visited.has(neighbor)) {
+          queue.push(neighbor);
+        }
+      }
+    }
+  }
+
+  return visited;
+}

package/src/workflow/layout/port-assignment.ts

@@ -0,0 +1,171 @@
+import { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
+import type { WorkflowGraphNode, WorkflowGraphEdge } from "../workflow-graph-model";
+import { START_NODE_ID, END_NODE_ID } from "../workflow-graph-model";
+import type { NodePortAssignment, PortDefinition, PortSide } from "./types";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Computes port assignments for all nodes in a workflow graph.
+ *
+ * Port IDs are deterministic and align with the React Flow handle IDs
+ * used in `WorkflowNode` (`case_{name}`, `outcome_{name}`). This ensures
+ * ELK routes edges to the correct port and the postprocessor can map
+ * results back to the React Flow model without translation.
+ *
+ * @param nodes - All nodes in the workflow graph.
+ * @param edges - All edges (used to infer fork branch count).
+ */
+export function computePortAssignments(
+  nodes: readonly WorkflowGraphNode[],
+  edges: readonly WorkflowGraphEdge[],
+): ReadonlyMap<string, NodePortAssignment> {
+  const result = new Map<string, NodePortAssignment>();
+
+  for (const node of nodes) {
+    result.set(node.id, computeNodePorts(node, edges));
+  }
+
+  return result;
+}
+
+/**
+ * Computes port assignment for a single node.
+ * Exported for unit testing individual cases.
+ */
+export function computeNodePorts(
+  node: WorkflowGraphNode,
+  edges: readonly WorkflowGraphEdge[],
+): NodePortAssignment {
+  const nodeId = node.id;
+
+  if (nodeId === START_NODE_ID) {
+    return {
+      nodeId,
+      inputPorts: [],
+      outputPorts: [makePort(`${nodeId}__out`, "SOUTH", 0)],
+    };
+  }
+
+  if (nodeId === END_NODE_ID) {
+    return {
+      nodeId,
+      inputPorts: [makePort(`${nodeId}__in`, "NORTH", 0)],
+      outputPorts: [],
+    };
+  }
+
+  const inputPorts: PortDefinition[] = [makePort(`${nodeId}__in`, "NORTH", 0)];
+  const outputPorts = computeOutputPorts(node, edges);
+
+  return { nodeId, inputPorts, outputPorts };
+}
+
+// ---------------------------------------------------------------------------
+// Output port computation per task kind
+// ---------------------------------------------------------------------------
+
+function computeOutputPorts(
+  node: WorkflowGraphNode,
+  edges: readonly WorkflowGraphEdge[],
+): PortDefinition[] {
+  const config = node.config as Record<string, unknown> | undefined;
+
+  if (node.kind === WorkflowTaskKind.switch_case && config) {
+    return computeSwitchCasePorts(node.id, config);
+  }
+
+  if (node.kind === WorkflowTaskKind.human_input && config) {
+    return computeHumanInputPorts(node.id, config);
+  }
+
+  if (node.kind === WorkflowTaskKind.fork) {
+    return computeForkPorts(node.id, edges);
+  }
+
+  return [makePort(`${node.id}__out`, "SOUTH", 0)];
+}
+
+/**
+ * switch_case: one output port per case entry.
+ * Handle ID format matches CanvasTaskNode: `case_{caseName}`.
+ */
+function computeSwitchCasePorts(
+  nodeId: string,
+  config: Record<string, unknown>,
+): PortDefinition[] {
+  const cases = config.cases;
+  if (!Array.isArray(cases) || cases.length === 0) {
+    return [makePort(`${nodeId}__out`, "SOUTH", 0)];
+  }
+
+  const ports: PortDefinition[] = [];
+  let index = 0;
+
+  for (const c of cases) {
+    if (c != null && typeof c === "object" && typeof (c as Record<string, unknown>).name === "string") {
+      const caseName = (c as Record<string, unknown>).name as string;
+      ports.push(makePort(`${nodeId}__case_${caseName}`, "SOUTH", index, caseName));
+      index++;
+    }
+  }
+
+  return ports.length > 0 ? ports : [makePort(`${nodeId}__out`, "SOUTH", 0)];
+}
+
+/**
+ * human_input: one output port per outcome entry.
+ * Handle ID format matches CanvasTaskNode: `outcome_{outcomeName}`.
+ */
+function computeHumanInputPorts(
+  nodeId: string,
+  config: Record<string, unknown>,
+): PortDefinition[] {
+  const outcomes = config.outcomes;
+  if (!Array.isArray(outcomes) || outcomes.length === 0) {
+    return [makePort(`${nodeId}__out`, "SOUTH", 0)];
+  }
+
+  const ports: PortDefinition[] = [];
+  let index = 0;
+
+  for (const o of outcomes) {
+    if (o != null && typeof o === "object" && typeof (o as Record<string, unknown>).name === "string") {
+      const outcomeName = (o as Record<string, unknown>).name as string;
+      ports.push(makePort(`${nodeId}__outcome_${outcomeName}`, "SOUTH", index, outcomeName));
+      index++;
+    }
+  }
+
+  return ports.length > 0 ? ports : [makePort(`${nodeId}__out`, "SOUTH", 0)];
+}
+
+/**
+ * fork: one output port per outgoing edge from this node.
+ * Handle IDs use a stable index: `branch_{index}`.
+ */
+function computeForkPorts(
+  nodeId: string,
+  edges: readonly WorkflowGraphEdge[],
+): PortDefinition[] {
+  const outgoing = edges.filter((e) => e.source === nodeId);
+
+  if (outgoing.length <= 1) {
+    return [makePort(`${nodeId}__out`, "SOUTH", 0)];
+  }
+
+  return outgoing.map((edge, index) => {
+    const handleId = edge.sourceHandle ?? `branch_${index}`;
+    return makePort(`${nodeId}__${handleId}`, "SOUTH", index);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makePort(id: string, side: PortSide, index: number, label?: string): PortDefinition {
+  return { id, side, index, ...(label !== undefined && { label }) };
+}

package/src/workflow/layout/registry-dimensions.ts

@@ -0,0 +1,30 @@
+import { getVisualSpec } from "../task-type-visual-registry";
+import { taskKindToString } from "../workflow-graph-conversions";
+import { START_NODE_ID, END_NODE_ID } from "../workflow-graph-model";
+import type { WorkflowGraphNode } from "../workflow-graph-model";
+import type { NodeDimensions } from "./types";
+
+/**
+ * Resolves per-node dimensions from the visual registry (T01).
+ *
+ * This is the canonical adapter that bridges `WorkflowGraphNode` to the
+ * `NodeDimensions` contract expected by layout engines. It handles both
+ * sentinel nodes (`__start__`, `__end__`) and task nodes by delegating
+ * to `getVisualSpec`, which returns shape-appropriate dimensions
+ * (diamonds, bars, circles, octagons, containers, and cards).
+ *
+ * The returned height includes `captionHeight` — the space reserved for
+ * the task name caption below non-rectangular shapes. This ensures the
+ * layout engine allocates sufficient vertical spacing to prevent overlap
+ * between caption text and subsequent nodes/edges.
+ *
+ * Defined at module scope — referentially stable with no closure over
+ * React state. Safe to pass directly as `getNodeDimensions` without
+ * wrapping in `useCallback` (DD-010).
+ */
+export function registryNodeDimensions(node: WorkflowGraphNode): NodeDimensions {
+  const isSentinel = node.id === START_NODE_ID || node.id === END_NODE_ID;
+  const kindKey = isSentinel ? node.id : taskKindToString(node.kind);
+  const spec = getVisualSpec(kindKey);
+  return { width: spec.defaultWidth, height: spec.defaultHeight + spec.captionHeight };
+}