@foresthubai/workflow-builder 0.3.0

package/dist/utils/translation.d.ts

@@ -0,0 +1,20 @@
+import type { TFunction } from "i18next";
+import type { NodeDefinition } from "@foresthubai/workflow-core/node";
+import type { Parameter } from "@foresthubai/workflow-core/parameter";
+/**
+ * Convention-based i18n helpers for description strings only.
+ *
+ * Keys follow the pattern:
+ *   nodes.<NodeType>.description
+ *   edges.<EdgeType>.description
+ *   <prefix>.params.<paramId>.description
+ *
+ * Labels, categories, port names, and option labels stay as raw English code values.
+ * Only natural-language descriptions are translated.
+ */
+export declare function getNodeDescription(t: TFunction, def: NodeDefinition): string;
+export declare function getParamDescription(t: TFunction, translationPrefix: string, param: Parameter): string;
+export declare function getEdgeDescription(t: TFunction, def: {
+    description: string;
+}, portType: string): string;
+//# sourceMappingURL=translation.d.ts.map

package/dist/utils/translation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation.d.ts","sourceRoot":"","sources":["../../src/utils/translation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAEtE;;;;;;;;;;GAUG;AAEH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,cAAc,GAAG,MAAM,CAE5E;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAGrG;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEvG"}

package/dist/utils/translation.js

@@ -0,0 +1,23 @@
+/**
+ * Convention-based i18n helpers for description strings only.
+ *
+ * Keys follow the pattern:
+ *   nodes.<NodeType>.description
+ *   edges.<EdgeType>.description
+ *   <prefix>.params.<paramId>.description
+ *
+ * Labels, categories, port names, and option labels stay as raw English code values.
+ * Only natural-language descriptions are translated.
+ */
+export function getNodeDescription(t, def) {
+    return t(`nodes.${def.type}.description`, { defaultValue: def.description });
+}
+export function getParamDescription(t, translationPrefix, param) {
+    if (!param.description)
+        return "";
+    return t(`${translationPrefix}.params.${param.id}.description`, { defaultValue: param.description });
+}
+export function getEdgeDescription(t, def, portType) {
+    return t(`edges.${portType}.description`, { defaultValue: def.description });
+}
+//# sourceMappingURL=translation.js.map

package/dist/utils/translation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation.js","sourceRoot":"","sources":["../../src/utils/translation.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,MAAM,UAAU,kBAAkB,CAAC,CAAY,EAAE,GAAmB;IAClE,OAAO,CAAC,CAAC,SAAS,GAAG,CAAC,IAAI,cAAc,EAAE,EAAE,YAAY,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;AAC/E,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,CAAY,EAAE,iBAAyB,EAAE,KAAgB;IAC3F,IAAI,CAAC,KAAK,CAAC,WAAW;QAAE,OAAO,EAAE,CAAC;IAClC,OAAO,CAAC,CAAC,GAAG,iBAAiB,WAAW,KAAK,CAAC,EAAE,cAAc,EAAE,EAAE,YAAY,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;AACvG,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,CAAY,EAAE,GAA4B,EAAE,QAAgB;IAC7F,OAAO,CAAC,CAAC,SAAS,QAAQ,cAAc,EAAE,EAAE,YAAY,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;AAC/E,CAAC"}

package/dist/utils/variableOperations.d.ts

@@ -0,0 +1,15 @@
+import { type DeclaredVariable } from "@foresthubai/workflow-core/variable";
+import type { DataType } from "@foresthubai/workflow-core";
+/** Create a new declared variable on the given canvas. Returns its uid. */
+export declare function addDeclaredVariable(canvasId: string): string;
+/** Apply a partial patch to a declared variable. `kind`/`uid` are fixed. */
+export declare function updateDeclaredVariable(canvasId: string, uid: string, updates: Partial<Omit<DeclaredVariable, "kind" | "uid">>): void;
+/**
+ * Change a declared variable's dataType. The previous initialValue is dropped —
+ * a value entered for one type rarely makes sense for another, so we reset
+ * rather than attempt a lossy coercion.
+ */
+export declare function setDeclaredVariableType(canvasId: string, uid: string, dataType: DataType): void;
+/** Delete a declared variable and clear its selection if it was open. */
+export declare function deleteDeclaredVariable(canvasId: string, uid: string): void;
+//# sourceMappingURL=variableOperations.d.ts.map

package/dist/utils/variableOperations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variableOperations.d.ts","sourceRoot":"","sources":["../../src/utils/variableOperations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAC5F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAqB3D,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAe5D;AAED,4EAA4E;AAC5E,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC,GAAG,IAAI,CASpI;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAE/F;AAED,yEAAyE;AACzE,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAY1E"}

package/dist/utils/variableOperations.js

@@ -0,0 +1,71 @@
+import { declaredVarKey } from "@foresthubai/workflow-core/variable";
+import { getOrCreateCanvasStore } from "../stores/canvasStore";
+import { useEditorStore } from "../stores/editorStore";
+import { generateId } from "@foresthubai/workflow-core/id";
+/**
+ * Per-canvas mutation helpers for declared variables. Mirrors
+ * utils/modelOperations.ts, but declared variables are canvas-scoped (they live
+ * in canvasStore.variables, not editorStore), so every helper takes a canvasId.
+ *
+ * Each write takes a history checkpoint first, matching the inline editor it
+ * replaces, so a single edit is one undo step.
+ */
+/** Pick a fresh `var<N>` name that doesn't collide with existing declared variables. */
+function nextDefaultName(existingNames) {
+    let counter = 1;
+    while (existingNames.includes(`var${counter}`))
+        counter++;
+    return `var${counter}`;
+}
+/** Create a new declared variable on the given canvas. Returns its uid. */
+export function addDeclaredVariable(canvasId) {
+    const store = getOrCreateCanvasStore(canvasId);
+    store.takeCheckpoint();
+    const existingNames = Object.values(store.getState().variables)
+        .filter((v) => v.kind === "declared")
+        .map((v) => v.name);
+    const uid = generateId();
+    const newVar = {
+        kind: "declared",
+        uid,
+        name: nextDefaultName(existingNames),
+        dataType: "int",
+    };
+    store.getState().setVariables((vars) => ({ ...vars, [declaredVarKey(uid)]: newVar }));
+    return uid;
+}
+/** Apply a partial patch to a declared variable. `kind`/`uid` are fixed. */
+export function updateDeclaredVariable(canvasId, uid, updates) {
+    const store = getOrCreateCanvasStore(canvasId);
+    store.takeCheckpoint();
+    const key = declaredVarKey(uid);
+    store.getState().setVariables((vars) => {
+        const existing = vars[key];
+        if (!existing || existing.kind !== "declared")
+            return vars;
+        return { ...vars, [key]: { ...existing, ...updates } };
+    });
+}
+/**
+ * Change a declared variable's dataType. The previous initialValue is dropped —
+ * a value entered for one type rarely makes sense for another, so we reset
+ * rather than attempt a lossy coercion.
+ */
+export function setDeclaredVariableType(canvasId, uid, dataType) {
+    updateDeclaredVariable(canvasId, uid, { dataType, initialValue: undefined });
+}
+/** Delete a declared variable and clear its selection if it was open. */
+export function deleteDeclaredVariable(canvasId, uid) {
+    const store = getOrCreateCanvasStore(canvasId);
+    store.takeCheckpoint();
+    const key = declaredVarKey(uid);
+    store.getState().setVariables((vars) => {
+        const { [key]: _drop, ...rest } = vars;
+        return rest;
+    });
+    const sel = useEditorStore.getState().selection;
+    if (sel.kind === "variable" && sel.uid === uid) {
+        useEditorStore.getState().clearSelection();
+    }
+}
+//# sourceMappingURL=variableOperations.js.map

package/dist/utils/variableOperations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variableOperations.js","sourceRoot":"","sources":["../../src/utils/variableOperations.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@foresthubai/workflow-builder",
+  "version": "0.3.0",
+  "description": "Reusable React component library: the workflow canvas/editor. Imports workflow-core for types and validation.",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ForestHubAI/edge-agents.git",
+    "directory": "ts/workflow-builder"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles/index.css": "./src/styles/index.css",
+    "./tailwind-preset": "./tailwind-preset.ts"
+  },
+  "files": [
+    "dist",
+    "src",
+    "tailwind-preset.ts",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18",
+    "tailwindcss": "^3.4.0"
+  },
+  "dependencies": {
+    "@foresthubai/workflow-core": "0.3.0",
+    "@radix-ui/react-alert-dialog": "^1.1.1",
+    "@radix-ui/react-checkbox": "^1.1.1",
+    "@radix-ui/react-collapsible": "^1.1.0",
+    "@radix-ui/react-dialog": "^1.1.2",
+    "@radix-ui/react-dropdown-menu": "^2.1.1",
+    "@radix-ui/react-label": "^2.1.0",
+    "@radix-ui/react-scroll-area": "^1.1.0",
+    "@radix-ui/react-select": "^2.1.1",
+    "@radix-ui/react-separator": "^1.1.0",
+    "@radix-ui/react-slot": "^1.1.0",
+    "@radix-ui/react-switch": "^1.1.0",
+    "@radix-ui/react-toast": "^1.2.1",
+    "@radix-ui/react-toggle": "^1.1.0",
+    "@radix-ui/react-toggle-group": "^1.1.0",
+    "@radix-ui/react-tooltip": "^1.1.4",
+    "@xyflow/react": "^12.8.1",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.0.0",
+    "i18next": "^25.3.2",
+    "lucide-react": "^0.462.0",
+    "react-i18next": "^15.6.1",
+    "react-resizable-panels": "^2.1.3",
+    "tailwind-merge": "^2.5.2",
+    "tailwindcss-animate": "^1.0.7",
+    "zustand": "^5.0.10"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "tailwindcss": "^3.4.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.8"
+  }
+}

package/src/BuilderLayout.tsx

@@ -0,0 +1,345 @@
+import type { FunctionDeclaration } from "@foresthubai/workflow-core/function";
+import type { NodeDefinition } from "@foresthubai/workflow-core/node";
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { Connection, OnSelectionChangeFunc } from "@xyflow/react";
+
+import { toast } from "./hooks/use-toast";
+import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from "./components/ui/resizable";
+import { BuilderSidebar } from "./panels/BuilderSidebar";
+import { CanvasTabsToolbar } from "./CanvasTabsToolbar";
+import { CanvasEditor } from "./CanvasEditor";
+import { RightConfigPanel } from "./RightConfigPanel";
+import { useCanvasHistory } from "./hooks/useCanvasHistory";
+import { useGraph } from "./hooks/useGraph";
+import { useNodeDefinitions } from "./hooks/useNodeDefinitions";
+import { DebugConsolePanel } from "./panels/DebugConsolePanel";
+import type { CanvasTab } from "./hooks/useCanvasTabs";
+import { getOrCreateCanvasStore, MAIN_CANVAS_ID } from "./stores/canvasStore";
+import { useEditorStore } from "./stores/editorStore";
+import { isReadOnly } from "./WorkflowBuilder";
+
+/**
+ * Chrome composer. Stable across canvas switches — only the {@link CanvasEditor}
+ * child remounts via `key={activeCanvasId}`.
+ *
+ * Owns:
+ *  - Sidebar tab state and the mode → sidebar-tab auto-switch effect.
+ *  - viewportCenterRef (populated by ReactFlow, consumed by sidebar's
+ *    click-to-add path).
+ *  - Selection-drag flag (lifted here so RightConfigPanel can read it).
+ *  - All graph mutation handlers — bound to active canvas via
+ *    `useGraph(activeCanvasId)`. Handlers stay stable enough to pass to the
+ *    sidebar; closures refresh automatically when the active canvas changes.
+ *  - Document-level keyboard handlers (undo/redo/copy/paste/delete/escape).
+ *
+ * Receives the open-tab list and function-CRUD callbacks from
+ * {@link WorkflowBuilder} above (which owns long-lived editor state).
+ */
+export interface BuilderLayoutProps {
+  functions: FunctionDeclaration[];
+  /** Open (and select) an existing function — used by the sidebar list and tab dropdown. */
+  onOpenFunction: (functionId: string) => void;
+  /** Create a new function and open it — the sidebar list's "Add" action. */
+  onCreateFunction: () => string;
+
+  canvasTabs: CanvasTab[];
+  onCanvasTabChange: (tabId: string) => void;
+  onCanvasTabClose: (tabId: string) => void;
+  onCanvasTabReorder: (fromIndex: number, toIndex: number) => void;
+
+  onTestNode?: (nodeId: string) => void;
+  onDebugStep?: (nodeId?: string) => void;
+}
+
+export const BuilderLayout = ({
+  functions,
+  onOpenFunction,
+  onCreateFunction,
+  canvasTabs,
+  onCanvasTabChange,
+  onCanvasTabClose,
+  onCanvasTabReorder,
+  onTestNode,
+  onDebugStep,
+}: BuilderLayoutProps) => {
+  const activeCanvasId = useEditorStore((s) => s.activeCanvasId);
+  const builderMode = useEditorStore((s) => s.builderMode);
+  const readOnly = isReadOnly(builderMode);
+  const isDebugMode = builderMode.type === "debug";
+
+  // NodeRegistry (static) + dynamic function nodes — derived, not embedder-provided.
+  const { nodeDefinitions, getNodeDefinition, getAllCategories } = useNodeDefinitions();
+
+  const graph = useGraph(activeCanvasId, readOnly);
+  const { undo, redo, takeCheckpoint, canUndo, canRedo } = useCanvasHistory(activeCanvasId);
+
+  // Selection (project-wide in editorStore, mirrored to canvas store for RF visual)
+  const selection = useEditorStore((s) => s.selection);
+  const selectGraph = useEditorStore((s) => s.selectGraph);
+  const syncSelectionFromRF = useEditorStore((s) => s.syncSelectionFromRF);
+  const clearSelection = useEditorStore((s) => s.clearSelection);
+
+  // Sidebar tab state + mode auto-switch.
+  const activeSidebarTab = useEditorStore((s) => s.activeSidebarTab);
+  const setActiveSidebarTab = useEditorStore((s) => s.setActiveSidebarTab);
+  useEffect(() => {
+    const isDebugTab = activeSidebarTab === "debug-context";
+    if (isDebugMode && !isDebugTab) {
+      setActiveSidebarTab("debug-context");
+    } else if (!isDebugMode && isDebugTab) {
+      setActiveSidebarTab("nodes");
+    }
+  }, [isDebugMode, activeSidebarTab, setActiveSidebarTab]);
+
+  // Selection-drag flag (used by RightConfigPanel to suppress during drag).
+  const [selectionDrag, setSelectionDrag] = useState(false);
+
+  // ViewportCenter ref (populated by ReactFlow inside CanvasEditor, consumed
+  // here for sidebar's click-to-add path).
+  const viewportCenterRef = useRef<(() => { x: number; y: number }) | null>(null);
+
+  // ── Handlers ──────────────────────────────────────────────────────────────
+
+  const selectNodeById: (id: string) => void = useCallback(
+    (nodeId: string) => selectGraph([nodeId], []),
+    [selectGraph],
+  );
+
+  const selectEdgeById = useCallback((edgeId: string) => selectGraph([], [edgeId]), [selectGraph]);
+
+  const handleAddNode = useCallback(
+    (nodeDef: NodeDefinition, position?: { x: number; y: number }) => {
+      const pos = position ?? viewportCenterRef.current?.();
+      const id = graph.addNode(nodeDef, pos);
+      if (id == null) {
+        toast({ title: `Only one ${nodeDef.label} node allowed per canvas`, variant: "destructive" });
+      }
+      return id;
+    },
+    [graph],
+  );
+
+  const handleConnect = useCallback(
+    (conn: Connection) => {
+      const edgeType = graph.onConnect(conn);
+      // Auto-select agent edges so the config panel opens for parameter entry.
+      if (edgeType && edgeType !== "control" && edgeType !== "tool") {
+        const { edges: currentEdges } = getOrCreateCanvasStore(activeCanvasId).getState();
+        const newEdge = currentEdges.find(
+          (e) =>
+            e.source === conn.source &&
+            e.target === conn.target &&
+            e.sourceHandle === conn.sourceHandle &&
+            e.targetHandle === conn.targetHandle,
+        );
+        if (newEdge) selectEdgeById(newEdge.id);
+      }
+    },
+    [graph, activeCanvasId, selectEdgeById],
+  );
+
+  const handleAddNodeAndConnect = useCallback(
+    (
+      nodeDef: NodeDefinition,
+      position: { x: number; y: number },
+      connection: { source: string; sourceHandle: string; target: string; targetHandle: string },
+    ) => {
+      const newNodeId = graph.addNodeAndConnect(nodeDef, position, connection);
+      if (newNodeId == null) {
+        toast({ title: `Only one ${nodeDef.label} node allowed per canvas`, variant: "destructive" });
+      }
+      return newNodeId;
+    },
+    [graph],
+  );
+
+  const handleSelectionChange: OnSelectionChangeFunc = useCallback(
+    ({ nodes: selNodes, edges: selEdges }) => {
+      syncSelectionFromRF(
+        selNodes.map((n) => n.id),
+        selEdges.map((e) => e.id),
+      );
+    },
+    [syncSelectionFromRF],
+  );
+
+  const handleDeleteEdge = useCallback(
+    (edgeId: string) => {
+      graph.deleteEdges([edgeId]);
+      clearSelection();
+    },
+    [graph, clearSelection],
+  );
+
+  const handleNodeDragStart = useCallback(() => {
+    takeCheckpoint();
+  }, [takeCheckpoint]);
+
+  const deleteSelected = useCallback(() => {
+    const sel = useEditorStore.getState().selection;
+    const nodeIds = sel.kind === "graph" ? sel.nodeIds : [];
+    const edgeIds = sel.kind === "graph" ? sel.edgeIds : [];
+    graph.deleteSelected(nodeIds, edgeIds);
+    clearSelection();
+  }, [graph, clearSelection]);
+
+  const handlePaste = useCallback(
+    (offset?: { x: number; y: number }) => {
+      const result = graph.pasteSelection(offset);
+      if (result?.skippedLabels.length) {
+        for (const label of result.skippedLabels) {
+          toast({ title: `Only one ${label} node allowed per canvas`, variant: "destructive" });
+        }
+      }
+      return result;
+    },
+    [graph],
+  );
+
+  // Debug mode: clicking a node sets the debug cursor.
+  // useEffect(() => {
+  //   if (!isDebugMode || selectedNodeIds.length !== 1) return;
+  //   const nodeId = selectedNodeIds[0];
+  //   const phase = useDebugStore.getState().phase;
+  //   if (phase.status === "idle") {
+  //     useDebugStore
+  //       .getState()
+  //       .setPhase({ status: "paused", sessionId: phase.sessionId, cursorNodeId: nodeId });
+  //   } else if (phase.status === "paused") {
+  //     useDebugStore.getState().setPhase({ ...phase, cursorNodeId: nodeId });
+  //   }
+  // }, [isDebugMode, selectedNodeIds]);
+
+  // Keyboard handlers — undo/redo/copy/paste/delete/escape.
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      const target = event.target as HTMLElement;
+      if (target?.tagName === "INPUT" || target?.tagName === "TEXTAREA" || target?.isContentEditable) {
+        return;
+      }
+      if (readOnly) {
+        if (event.key === "Escape") clearSelection();
+        return;
+      }
+      if ((event.ctrlKey || event.metaKey) && event.key === "z" && !event.shiftKey) {
+        event.preventDefault();
+        if (canUndo()) {
+          clearSelection();
+          undo();
+        }
+        return;
+      }
+      if ((event.ctrlKey || event.metaKey) && (event.key === "y" || (event.key === "z" && event.shiftKey))) {
+        event.preventDefault();
+        if (canRedo()) {
+          clearSelection();
+          redo();
+        }
+        return;
+      }
+      if ((event.ctrlKey || event.metaKey) && event.key === "c") {
+        if (selection.kind === "graph" && selection.nodeIds.length > 0) {
+          event.preventDefault();
+          graph.copySelection(selection.nodeIds);
+        }
+        return;
+      }
+      if ((event.ctrlKey || event.metaKey) && event.key === "v") {
+        event.preventDefault();
+        handlePaste();
+        return;
+      }
+      if (event.key === "Delete" || event.key === "Backspace") {
+        deleteSelected();
+      }
+      if (event.key === "Escape") {
+        clearSelection();
+      }
+    };
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [canUndo, canRedo, undo, redo, clearSelection, deleteSelected, selection, graph, handlePaste, readOnly]);
+
+  const isFunctionCanvas = activeCanvasId !== MAIN_CANVAS_ID;
+
+  // ── Render ───────────────────────────────────────────────────────────────
+
+  const canvasArea = (
+    <div className="flex flex-col h-full min-w-0">
+      <CanvasTabsToolbar
+        tabs={canvasTabs}
+        activeTabId={activeCanvasId}
+        onTabChange={onCanvasTabChange}
+        onTabClose={onCanvasTabClose}
+        onTabReorder={onCanvasTabReorder}
+      />
+      <div className="flex-1 relative">
+        <CanvasEditor
+          key={activeCanvasId}
+          canvasId={activeCanvasId}
+          viewportCenterRef={viewportCenterRef}
+          nodeDefinitions={nodeDefinitions}
+          onConnect={handleConnect}
+          onAddNode={handleAddNode}
+          onAddNodeAndConnect={handleAddNodeAndConnect}
+          onSelectionChange={handleSelectionChange}
+          onPaneClick={clearSelection}
+          onNodeDragStart={handleNodeDragStart}
+          setSelectionDrag={setSelectionDrag}
+        />
+      </div>
+    </div>
+  );
+
+  return (
+    <div className="h-full bg-canvas-bg flex flex-col">
+      <div className="flex-1 flex overflow-hidden">
+        <BuilderSidebar
+          canvasId={activeCanvasId}
+          activeTab={activeSidebarTab}
+          onTabChange={setActiveSidebarTab}
+          onAddNode={handleAddNode}
+          nodeDefinitions={nodeDefinitions}
+          getAllCategories={getAllCategories}
+          onSelectNode={selectNodeById}
+          onSelectEdge={selectEdgeById}
+          isFunctionCanvas={isFunctionCanvas}
+          functions={functions}
+          onOpenFunction={onOpenFunction}
+          onCreateFunction={onCreateFunction}
+          isDebugMode={isDebugMode}
+        />
+
+        <div className="flex-1 flex flex-col h-full min-w-0">
+          {isDebugMode ? (
+            <ResizablePanelGroup direction="vertical">
+              <ResizablePanel defaultSize={75} minSize={30}>
+                {canvasArea}
+              </ResizablePanel>
+              <ResizableHandle withHandle />
+              <ResizablePanel defaultSize={25} minSize={10}>
+                <DebugConsolePanel />
+              </ResizablePanel>
+            </ResizablePanelGroup>
+          ) : (
+            canvasArea
+          )}
+        </div>
+
+        <RightConfigPanel
+          canvasId={activeCanvasId}
+          isDebugMode={isDebugMode}
+          selectionDrag={selectionDrag}
+          getNodeDef={getNodeDefinition}
+          onNodeUpdate={graph.updateNode}
+          onNodeDelete={graph.deleteNode}
+          onEdgeUpdate={graph.updateEdge}
+          onEdgeDelete={handleDeleteEdge}
+          onClearSelection={clearSelection}
+          onTestNode={onTestNode}
+          onDebugStep={onDebugStep}
+        />
+      </div>
+    </div>
+  );
+};