@foresthubai/workflow-builder 0.3.0

package/src/graph/CustomEdge.tsx

@@ -0,0 +1,185 @@
+import { Tooltip, TooltipContent, TooltipTrigger } from "../components/ui/tooltip";
+import { BaseEdge, EdgeLabelRenderer, getBezierPath, Position, useEdges } from "@xyflow/react";
+import { AlertTriangle } from "lucide-react";
+import { EdgeData, isControlFlow, isToolFlow, type EdgeType } from "@foresthubai/workflow-core/edge";
+import { useEffect, useMemo } from "react";
+import { useAvailableVariables } from "../hooks/useAvailableVariables";
+import { useDiagnosticsStore } from "../stores/diagnosticsStore";
+import { useEditorStore } from "../stores/editorStore";
+import { isReadOnly } from "../WorkflowBuilder";
+import { computeEdgeDiagnostics } from "@foresthubai/workflow-core/diagnostics";
+
+const EDGE_BASE_COLOR = "hsl(var(--edge-default))";
+const AGENT_COLOR = "hsl(var(--node-agent))";
+const ERROR_COLOR = "hsl(var(--destructive))";
+
+/**
+ * Source/target stroke colors per edge type. Plain control and tool edges use
+ * the neutral edge base on both ends. Edges that touch an Agent pick up the
+ * agent color on that side, so the SVG gradient makes the edge visually
+ * announce its agent endpoint (e.g. agentTask fades base → agent toward the
+ * target Agent).
+ */
+function endColors(type: EdgeType): { source: string; target: string } {
+  switch (type) {
+    case "control":
+    case "tool":
+      return { source: EDGE_BASE_COLOR, target: EDGE_BASE_COLOR };
+    case "agentTask":
+      return { source: EDGE_BASE_COLOR, target: AGENT_COLOR };
+    case "agentChoice":
+      return { source: AGENT_COLOR, target: EDGE_BASE_COLOR };
+    case "agentDelegate":
+      return { source: AGENT_COLOR, target: AGENT_COLOR };
+  }
+}
+
+export const CustomEdge = ({
+  id,
+  source,
+  type,
+  sourceX,
+  sourceY,
+  targetX,
+  targetY,
+  data,
+  selected,
+}: {
+  id: string;
+  source: string;
+  type: string;
+  sourceX: number;
+  sourceY: number;
+  targetX: number;
+  targetY: number;
+  data?: EdgeData;
+  selected?: boolean;
+}) => {
+  const isHighlighted = selected ?? false;
+  const isPreview = useEditorStore((s) => isReadOnly(s.builderMode));
+  const edgeType = (type ?? "control") as EdgeType;
+  const edges = useEdges();
+  const activeCanvasId = useEditorStore.getState().activeCanvasId;
+  const { lookup: availableVariables } = useAvailableVariables(activeCanvasId);
+
+  const sourceControlEdgeCount = edges.filter((e) => e.source === source && isControlFlow(e.type as EdgeType)).length;
+
+  // Compute edge diagnostics via extracted pure function
+  const diagnostics = useMemo(
+    () =>
+      computeEdgeDiagnostics({
+        canvasId: activeCanvasId,
+        edgeId: id,
+        edgeType,
+        edgeData: data,
+        availableVariables,
+        sourceControlEdgeCount,
+      }),
+    [edgeType, sourceControlEdgeCount, data, availableVariables, activeCanvasId, id],
+  );
+
+  const hasErrors = diagnostics.length > 0;
+
+  // Write diagnostics to store (cleanup on unmount; validateAllCanvases handles full-project)
+  const setEdgeDiagnostics = useDiagnosticsStore((s) => s.setEdgeDiagnostics);
+  const clearEdgeDiagnostics = useDiagnosticsStore((s) => s.clearEdgeDiagnostics);
+  useEffect(() => {
+    if (isPreview) return;
+    setEdgeDiagnostics(id, diagnostics);
+    return () => clearEdgeDiagnostics(id);
+  }, [id, diagnostics, setEdgeDiagnostics, clearEdgeDiagnostics, isPreview]);
+
+  const getEdgePath = () => {
+    if (isToolFlow(edgeType)) {
+      // Tool ports are diamonds, and React Flow anchors the wire at the handle
+      // box's edge midpoint — i.e. the diamond's pointed tip — so a wire meeting
+      // it looks pinched/detached. Pull each end into its node (tool output sits
+      // on a node's bottom, tool input on the next node's top) so the wire
+      // overlaps the diamond body (hidden under the z-20 port) and reads solid.
+      const OVERLAP = 3;
+      return getBezierPath({
+        sourceX,
+        sourceY: sourceY - OVERLAP,
+        targetX,
+        targetY: targetY + OVERLAP,
+      });
+    }
+    // Control flow: ends have horizontal slope
+    const OVERLAP = 2;
+    return getBezierPath({
+      sourceX: sourceX - OVERLAP,
+      sourceY,
+      sourcePosition: Position.Right,
+      targetX: targetX + OVERLAP,
+      targetY,
+      targetPosition: Position.Left,
+    });
+  };
+
+  const [edgePath, labelX, labelY] = getEdgePath();
+  const colors = hasErrors ? { source: ERROR_COLOR, target: ERROR_COLOR } : endColors(edgeType);
+  const strokeWidth = 3;
+  const gradientId = `edge-gradient-${id}`;
+
+  // Glow effect for highlighted edges — uniform high-contrast color (or
+  // destructive when the edge itself is errored).
+  const glowColor = hasErrors ? ERROR_COLOR : "hsl(var(--selection-glow))";
+  const glowFilter = isHighlighted ? `drop-shadow(0 0 8px ${glowColor}) drop-shadow(0 0 16px ${glowColor})` : undefined;
+
+  return (
+    <>
+      <g style={{ filter: glowFilter }}>
+        <defs>
+          {/* gradientUnits=userSpaceOnUse anchors the stops to the edge's actual
+              source/target coordinates, so the fade follows the wire regardless
+              of its bounding box (which is what objectBoundingBox would use). */}
+          <linearGradient
+            id={gradientId}
+            gradientUnits="userSpaceOnUse"
+            x1={sourceX}
+            y1={sourceY}
+            x2={targetX}
+            y2={targetY}
+          >
+            <stop offset="0%" stopColor={colors.source} />
+            <stop offset="100%" stopColor={colors.target} />
+          </linearGradient>
+        </defs>
+        <BaseEdge
+          id={id}
+          path={edgePath}
+          style={{
+            stroke: `url(#${gradientId})`,
+            strokeWidth,
+            strokeDasharray: "none",
+          }}
+        />
+      </g>
+      <EdgeLabelRenderer>
+        <div
+          style={{
+            position: "absolute",
+            transform: `translate(-50%, -50%) translate(${labelX}px,${labelY}px)`,
+            pointerEvents: "all",
+          }}
+          className="flex flex-col items-center gap-0.5"
+        >
+          {hasErrors && (
+            <Tooltip delayDuration={300}>
+              <TooltipTrigger asChild>
+                <div className="cursor-help">
+                  <AlertTriangle className="h-5 w-5 text-destructive fill-background" />
+                </div>
+              </TooltipTrigger>
+              <TooltipContent side="top" className="bg-destructive text-destructive-foreground text-xs px-2 py-1">
+                {diagnostics[0]?.message ?? "This edge has errors"}
+              </TooltipContent>
+            </Tooltip>
+          )}
+        </div>
+      </EdgeLabelRenderer>
+    </>
+  );
+};
+
+export default CustomEdge;

package/src/graph/CustomNode.tsx

@@ -0,0 +1,16 @@
+import { NodeData, NodeRegistry } from "@foresthubai/workflow-core/node";
+import { NodeProps } from "@xyflow/react";
+import { memo, useMemo } from "react";
+import { BaseNode } from "./BaseNode";
+
+// Standard node component for all non-FunctionCall nodes
+// Simply resolves the node definition from the registry and delegates to BaseNode
+export const CustomNode = memo((props: NodeProps) => {
+  const nodeData = props.data as NodeData;
+
+  // Get node definition from static registry
+  const nodeDefinition = useMemo(() => {
+    return NodeRegistry.getByType(nodeData.type);
+  }, [nodeData.type]);
+  return <BaseNode {...props} nodeDefinition={nodeDefinition} />;
+});

package/src/graph/FunctionCallNode.tsx

@@ -0,0 +1,30 @@
+import { FunctionCallNode as DomainFunctionCallNode } from "@foresthubai/workflow-core/node";
+import { NodeProps } from "@xyflow/react";
+import { memo, useMemo } from "react";
+import { buildFunctionNodeDef } from "../hooks/useNodeDefinitions";
+import { useFunctionRegistry } from "../hooks/useFunctionRegistry";
+import { BaseNode } from "./BaseNode";
+
+// Specialized node component for FunctionCall nodes
+// Renders from node's stored data (usually up-to-date via auto-migration,
+// but may be stale after undo)
+export const FunctionCallNode = memo((props: NodeProps) => {
+  const nodeData = props.data as DomainFunctionCallNode;
+
+  // Get function info for staleness check and live label
+  const { getFunction } = useFunctionRegistry();
+  const registryFunctionInfo = getFunction(nodeData.functionInfo.id);
+
+  const isDeleted = !registryFunctionInfo;
+  const isStale = registryFunctionInfo
+    ? nodeData.functionInfo.version !== registryFunctionInfo.version
+    : false;
+
+  // Build node definition from node's stored functionInfo, using registry name for label
+  const nodeDefinition = useMemo(() => {
+    const name = registryFunctionInfo?.name ?? nodeData.functionInfo.name;
+    return buildFunctionNodeDef({ ...nodeData.functionInfo, name });
+  }, [nodeData.functionInfo, registryFunctionInfo?.name]);
+
+  return <BaseNode {...props} nodeDefinition={nodeDefinition} isStale={isStale} isDeleted={isDeleted} />;
+});

package/src/graph/PortHandle.tsx

@@ -0,0 +1,189 @@
+import React from "react";
+import { Handle, Position } from "@xyflow/react";
+import { Plus } from "lucide-react";
+import type { EdgeType } from "@foresthubai/workflow-core/edge";
+
+export interface PortActionDetail {
+  nodeId: string;
+  handleId: string;
+  portType: EdgeType;
+}
+
+export interface PortHandleProps {
+  id: string;
+  nodeId?: string;
+  type: "source" | "target";
+  position: Position;
+  portType: EdgeType;
+  label?: string;
+  style?: React.CSSProperties;
+  disabled?: boolean;
+  showPlus?: boolean;
+}
+
+export const PortHandle = ({
+  id,
+  nodeId,
+  type,
+  position,
+  portType,
+  label,
+  style,
+  disabled,
+  showPlus,
+}: PortHandleProps) => {
+  const getHandleStyle = () => {
+    const baseStyle: React.CSSProperties = {
+      width: "12px",
+      height: "12px",
+      // Outline matches the canonical graph-line color (same as edges + node borders).
+      border: "2px solid hsl(var(--edge-default))",
+    };
+
+    if (disabled) {
+      return {
+        ...baseStyle,
+        backgroundColor: "hsl(var(--muted-foreground) / 0.3)",
+        border: "2px solid hsl(var(--muted-foreground) / 0.4)",
+        borderRadius: portType === "control" ? "2px" : portType === "tool" ? "2px" : "50%",
+        opacity: 0.8,
+        cursor: "not-allowed",
+        ...(portType === "tool" ? { clipPath: "polygon(50% 0%, 100% 50%, 50% 100%, 0% 50%)" } : {}),
+      };
+    }
+
+    switch (portType) {
+      case "control":
+        // Square shape for execution/control ports. Fill matches the node body
+        // (--card) so the port reads as a recessed hole outlined in the graph color.
+        return {
+          ...baseStyle,
+          backgroundColor: "hsl(var(--card))",
+          borderRadius: "2px",
+        };
+      case "tool":
+        // Diamond via clip-path so the handle stays anchored on the node edge
+        // (rotating it would override React Flow's centering transform). A
+        // clip-path can't show a border, so the handle background is the outline
+        // color and an inset inner diamond (rendered as a child below) paints the
+        // canonical tool fill (--node-tool), leaving a 2px edge-default outline.
+        return {
+          ...baseStyle,
+          backgroundColor: "hsl(var(--edge-default))",
+          border: "none",
+          borderRadius: "0",
+          clipPath: "polygon(50% 0%, 100% 50%, 50% 100%, 0% 50%)",
+        };
+      default:
+        // Circle shape as fallback
+        return {
+          ...baseStyle,
+          backgroundColor: "white",
+          borderRadius: "50%",
+        };
+    }
+  };
+
+  const getLabelPositionClass = () => {
+    switch (position) {
+      case Position.Left:
+        return "right-full mr-3 text-right";
+      case Position.Right:
+        return "left-full ml-3 text-left";
+      case Position.Top:
+        return "bottom-full mb-2 text-center left-1/2 -translate-x-1/2";
+      case Position.Bottom:
+        return "top-full mt-2 text-center left-1/2 -translate-x-1/2";
+      default:
+        return "left-full ml-3 text-left";
+    }
+  };
+
+  const getLabelStyle = (): React.CSSProperties => {
+    if (position === Position.Left || position === Position.Right) {
+      return {
+        top: "50%",
+        transform: "translateY(calc(-50% + 12px))",
+      };
+    }
+    return {};
+  };
+
+  const getPlusPositionClass = () => {
+    // Center with a negative margin (button is w-4 h-4 = 16px, so -8px = -2),
+    // NOT a translate. The hover effect uses `transform: scale()`, and reusing
+    // transform for centering too makes the translate drop out mid-animation,
+    // which both off-centers the plus and makes it jump on hover.
+    switch (position) {
+      case Position.Bottom:
+        return "top-[15px] left-1/2 -ml-2";
+      default:
+        return "left-[15px] top-1/2 -mt-2";
+    }
+  };
+
+  // Nudge the *visible* dot 1px toward the node interior so it sits on the
+  // outline centerline (the SVG border is strokeW=2). The offset is on a child,
+  // NOT the Handle — React Flow anchors edges to the Handle's measured box, so
+  // keeping that on the node edge means edges still connect flush instead of
+  // stopping 1px short.
+  const dotOffset =
+    position === Position.Top
+      ? "translateY(1px)"
+      : position === Position.Bottom
+        ? "translateY(-1px)"
+        : position === Position.Left
+          ? "translateX(1px)"
+          : "translateX(-1px)";
+
+  return (
+    <div className="absolute z-20" style={style}>
+      <Handle
+        id={id}
+        type={type}
+        position={position}
+        isConnectable={!disabled}
+        style={{ width: "12px", height: "12px", background: "transparent", border: "none", minWidth: 0, minHeight: 0 }}
+      >
+        <div
+          style={{ ...getHandleStyle(), position: "absolute", inset: 0, transform: dotOffset, pointerEvents: "none" }}
+        >
+          {portType === "tool" && !disabled && (
+            <div
+              style={{
+                position: "absolute",
+                inset: "2px",
+                backgroundColor: "hsl(var(--node-tool))",
+                clipPath: "polygon(50% 0%, 100% 50%, 50% 100%, 0% 50%)",
+              }}
+            />
+          )}
+        </div>
+      </Handle>
+      {label && !disabled && (
+        <div
+          className={`absolute text-xs text-muted-foreground pointer-events-none select-none whitespace-nowrap ${getLabelPositionClass()}`}
+          style={getLabelStyle()}
+        >
+          {label}
+        </div>
+      )}
+      {showPlus && !disabled && nodeId && (
+        <button
+          type="button"
+          title="Add port"
+          className={`nodrag absolute flex items-center justify-center w-4 h-4 rounded-full bg-muted-foreground/60 text-card hover:bg-primary hover:scale-110 transition-all cursor-pointer ${getPlusPositionClass()}`}
+          onClick={(e) => {
+            e.stopPropagation();
+            e.preventDefault();
+            const detail: PortActionDetail = { nodeId, handleId: id, portType };
+            e.currentTarget.dispatchEvent(new CustomEvent("port-plus-click", { detail, bubbles: true }));
+          }}
+          onPointerDown={(e) => e.stopPropagation()}
+        >
+          <Plus className="w-2.5 h-2.5" strokeWidth={3} />
+        </button>
+      )}
+    </div>
+  );
+};

package/src/graph/reactFlowRegistry.ts

@@ -0,0 +1,26 @@
+// ReactFlow node/edge type registries
+// Maps ReactFlow type strings to the React components that render them.
+// Shared between CanvasArea (editor) and VersionPreviewCanvas (read-only preview).
+// Lives in graph/ because it references sibling components, but is only consumed
+// by higher-level composing components — no graph/ component imports this file.
+
+import { NodeCategory } from "@foresthubai/workflow-core/node";
+import { CustomNode } from "./CustomNode";
+import { FunctionCallNode } from "./FunctionCallNode";
+import CustomEdge from "./CustomEdge";
+
+export const nodeTypes = {
+  Standard: CustomNode,
+  FunctionCall: FunctionCallNode,
+  [NodeCategory.Trigger]: CustomNode,
+  [NodeCategory.Tool]: CustomNode,
+  [NodeCategory.AI]: CustomNode,
+};
+
+export const edgeTypes = {
+  control: CustomEdge,
+  tool: CustomEdge,
+  agentTask: CustomEdge,
+  agentChoice: CustomEdge,
+  agentDelegate: CustomEdge,
+};

package/src/hooks/use-toast.ts

@@ -0,0 +1,125 @@
+// Standard shadcn toast hook + dispatcher
+import * as React from "react";
+
+import type { ToastActionElement, ToastProps } from "../components/ui/toast";
+
+const TOAST_LIMIT = 1;
+const TOAST_REMOVE_DELAY = 1_000_000;
+
+type ToasterToast = ToastProps & {
+  id: string;
+  title?: React.ReactNode;
+  description?: React.ReactNode;
+  action?: ToastActionElement;
+};
+
+const actionTypes = {
+  ADD_TOAST: "ADD_TOAST",
+  UPDATE_TOAST: "UPDATE_TOAST",
+  DISMISS_TOAST: "DISMISS_TOAST",
+  REMOVE_TOAST: "REMOVE_TOAST",
+} as const;
+
+let count = 0;
+function genId(): string {
+  count = (count + 1) % Number.MAX_SAFE_INTEGER;
+  return count.toString();
+}
+
+type ActionType = typeof actionTypes;
+
+type Action =
+  | { type: ActionType["ADD_TOAST"]; toast: ToasterToast }
+  | { type: ActionType["UPDATE_TOAST"]; toast: Partial<ToasterToast> & { id: string } }
+  | { type: ActionType["DISMISS_TOAST"]; toastId?: ToasterToast["id"] }
+  | { type: ActionType["REMOVE_TOAST"]; toastId?: ToasterToast["id"] };
+
+interface State {
+  toasts: ToasterToast[];
+}
+
+const toastTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
+
+function addToRemoveQueue(toastId: string) {
+  if (toastTimeouts.has(toastId)) return;
+  const timeout = setTimeout(() => {
+    toastTimeouts.delete(toastId);
+    dispatch({ type: "REMOVE_TOAST", toastId });
+  }, TOAST_REMOVE_DELAY);
+  toastTimeouts.set(toastId, timeout);
+}
+
+export const reducer = (state: State, action: Action): State => {
+  switch (action.type) {
+    case "ADD_TOAST":
+      return { ...state, toasts: [action.toast, ...state.toasts].slice(0, TOAST_LIMIT) };
+    case "UPDATE_TOAST":
+      return {
+        ...state,
+        toasts: state.toasts.map((t) => (t.id === action.toast.id ? { ...t, ...action.toast } : t)),
+      };
+    case "DISMISS_TOAST": {
+      const { toastId } = action;
+      if (toastId) {
+        addToRemoveQueue(toastId);
+      } else {
+        state.toasts.forEach((t) => addToRemoveQueue(t.id));
+      }
+      return {
+        ...state,
+        toasts: state.toasts.map((t) => (t.id === toastId || toastId === undefined ? { ...t, open: false } : t)),
+      };
+    }
+    case "REMOVE_TOAST":
+      if (action.toastId === undefined) return { ...state, toasts: [] };
+      return { ...state, toasts: state.toasts.filter((t) => t.id !== action.toastId) };
+  }
+};
+
+const listeners: Array<(state: State) => void> = [];
+let memoryState: State = { toasts: [] };
+
+function dispatch(action: Action) {
+  memoryState = reducer(memoryState, action);
+  listeners.forEach((listener) => listener(memoryState));
+}
+
+type Toast = Omit<ToasterToast, "id">;
+
+function toast({ ...props }: Toast) {
+  const id = genId();
+  const update = (next: ToasterToast) => dispatch({ type: "UPDATE_TOAST", toast: { ...next, id } });
+  const dismiss = () => dispatch({ type: "DISMISS_TOAST", toastId: id });
+
+  dispatch({
+    type: "ADD_TOAST",
+    toast: {
+      ...props,
+      id,
+      open: true,
+      onOpenChange: (open) => {
+        if (!open) dismiss();
+      },
+    },
+  });
+  return { id, dismiss, update };
+}
+
+function useToast() {
+  const [state, setState] = React.useState<State>(memoryState);
+  React.useEffect(() => {
+    listeners.push(setState);
+    return () => {
+      const index = listeners.indexOf(setState);
+      if (index > -1) listeners.splice(index, 1);
+    };
+  }, []);
+
+  return {
+    ...state,
+    toast,
+    dismiss: (toastId?: string) => dispatch({ type: "DISMISS_TOAST", toastId }),
+  };
+}
+
+export { useToast, toast };

package/src/hooks/useAvailableVariables.ts

@@ -0,0 +1,20 @@
+import { useMemo } from "react";
+import { getOrCreateCanvasStore, MAIN_CANVAS_ID } from "../stores/canvasStore";
+import { computeAvailableVariables } from "@foresthubai/workflow-core/variable";
+
+// Re-export types for consumers
+export type { Variable as AvailableVariable } from "@foresthubai/workflow-core/variable";
+
+/**
+ * Hook that provides access to all available variables for a specific canvas.
+ * Each canvas is self-contained — main and function canvases do not share scope.
+ *
+ * Returns both an array (for iteration/UI) and a record (for O(1) lookup).
+ */
+export const useAvailableVariables = (canvasId: string = MAIN_CANVAS_ID) => {
+  const store = getOrCreateCanvasStore(canvasId);
+  const variables = store((s) => s.variables);
+  const edges = store((s) => s.edges);
+
+  return useMemo(() => computeAvailableVariables(variables, edges), [variables, edges]);
+};

package/src/hooks/useCanvasHistory.ts

@@ -0,0 +1,22 @@
+import { getOrCreateCanvasStore, MAIN_CANVAS_ID } from "../stores/canvasStore";
+
+/**
+ * Hook that exposes all history functions from a canvas store.
+ * Each canvas has its own independent undo/redo history.
+ */
+export const useCanvasHistory = (canvasId: string = MAIN_CANVAS_ID) => {
+  const canvasStore = getOrCreateCanvasStore(canvasId);
+
+  return {
+    // History actions
+    undo: canvasStore.undo,
+    redo: canvasStore.redo,
+    takeCheckpoint: canvasStore.takeCheckpoint,
+    withCheckpoint: canvasStore.withCheckpoint,
+    clearHistory: canvasStore.clearHistory,
+
+    // History state checks
+    canUndo: canvasStore.canUndo,
+    canRedo: canvasStore.canRedo,
+  };
+};