@foresthubai/workflow-builder 0.3.0

package/src/RightConfigPanel.tsx

@@ -0,0 +1,266 @@
+import { useCallback, useMemo, type ReactNode } from "react";
+import type { NodeData, NodeDefinition } from "@foresthubai/workflow-core/node";
+import type { EdgeData, EdgeType } from "@foresthubai/workflow-core/edge";
+import { isControlFlow } from "@foresthubai/workflow-core/edge";
+import type { NodeCategory as NodeCategoryEnum } from "@foresthubai/workflow-core/node";
+
+import { ScrollArea } from "./components/ui/scroll-area";
+import { cn } from "./cn";
+import { ChannelConfigPanel } from "./panels/ChannelConfigPanel";
+import { DebugExternalIOPanel } from "./panels/DebugExternalIOPanel";
+import { EdgeConfigPanel } from "./panels/EdgeConfigPanel";
+import { FunctionConfigPanel } from "./panels/FunctionConfigPanel";
+import { MemoryConfigPanel } from "./panels/MemoryConfigPanel";
+import { ModelConfigPanel } from "./panels/ModelConfigPanel";
+import { NodeConfigPanel } from "./panels/NodeConfigPanel";
+import { VariableConfigPanel } from "./panels/VariableConfigPanel";
+import { getOrCreateCanvasStore } from "./stores/canvasStore";
+import { useEditorStore } from "./stores/editorStore";
+import { declaredVarKey } from "@foresthubai/workflow-core/variable";
+
+/**
+ * Right-side selection-routed config panel.
+ *
+ * Reads the current selection from editorStore (project-wide) and the
+ * selected node/edge from the active canvas store, then renders the
+ * appropriate config component. Receives graph mutation handlers from
+ * BuilderLayout — it never touches the canvas store directly for writes.
+ *
+ * Hidden while the user is mid selection-drag to avoid flicker.
+ */
+export interface RightConfigPanelProps {
+  canvasId: string;
+  isDebugMode: boolean;
+  selectionDrag: boolean;
+
+  // Lookups
+  getNodeDef: (node: NodeData) => NodeDefinition | undefined;
+
+  // Mutation handlers (live in BuilderLayout, bound to active canvas)
+  onNodeUpdate: (nodeId: string, updates: Partial<NodeData>) => void;
+  onNodeDelete: (nodeId: string) => void;
+  onEdgeUpdate: (edgeId: string, updates: Partial<EdgeData>) => void;
+  onEdgeDelete: (edgeId: string) => void;
+  onClearSelection: () => void;
+
+  // Embedder-fulfilled
+  onTestNode?: (nodeId: string) => void;
+  onDebugStep?: (nodeId?: string) => void;
+}
+
+export const RightConfigPanel = ({
+  canvasId,
+  isDebugMode,
+  selectionDrag,
+  getNodeDef,
+  onNodeUpdate,
+  onNodeDelete,
+  onEdgeUpdate,
+  onEdgeDelete,
+  onClearSelection,
+  onTestNode,
+  onDebugStep,
+}: RightConfigPanelProps) => {
+  const selection = useEditorStore((s) => s.selection);
+  const clearSelection = useEditorStore((s) => s.clearSelection);
+  const channels = useEditorStore((s) => s.channels);
+  const memory = useEditorStore((s) => s.memory);
+  const models = useEditorStore((s) => s.models);
+  const functions = useEditorStore((s) => s.functions);
+
+  const useStore = getOrCreateCanvasStore(canvasId);
+
+  const selectedNode = useStore(
+    useCallback(
+      (s) => {
+        if (selection.kind !== "graph" || selection.nodeIds.length !== 1) return null;
+        const node = s.nodes.find((n) => n.id === selection.nodeIds[0]);
+        return node?.data ?? null;
+      },
+      [selection],
+    ),
+  );
+
+  const selectedVariable = useStore(
+    useCallback(
+      (s) => {
+        if (selection.kind !== "variable") return null;
+        const v = s.variables[declaredVarKey(selection.uid)];
+        return v && v.kind === "declared" ? v : null;
+      },
+      [selection],
+    ),
+  );
+
+  const selectedEdgeRaw = useStore(
+    useCallback(
+      (s) => {
+        // Edge panel shows only for a lone edge (a node selection takes priority).
+        if (selection.kind !== "graph" || selection.edgeIds.length !== 1 || selection.nodeIds.length > 0) return null;
+        return s.edges.find((e) => e.id === selection.edgeIds[0]) ?? null;
+      },
+      [selection],
+    ),
+  );
+  const selectedEdge = selectedEdgeRaw
+    ? {
+        id: selectedEdgeRaw.id,
+        source: selectedEdgeRaw.source,
+        type: (selectedEdgeRaw.type ?? "control") as EdgeType,
+        data: (selectedEdgeRaw.data ?? {}) as EdgeData,
+      }
+    : null;
+
+  const sourceControlEdgeCount = useStore(
+    useCallback(
+      (s) => {
+        if (!selectedEdge) return 0;
+        return s.edges.filter((e) => e.source === selectedEdge.source && isControlFlow(e.type as EdgeType)).length;
+      },
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      [selectedEdge?.source],
+    ),
+  );
+
+  const selectedChannel = useMemo(
+    () => (selection.kind === "channel" ? (Object.values(channels).find((v) => v.id === selection.id) ?? null) : null),
+    [selection, channels],
+  );
+
+  const selectedMemory = useMemo(
+    () => (selection.kind === "memory" ? (Object.values(memory).find((m) => m.id === selection.id) ?? null) : null),
+    [selection, memory],
+  );
+
+  const selectedModel = useMemo(
+    () => (selection.kind === "model" ? (Object.values(models).find((m) => m.id === selection.id) ?? null) : null),
+    [selection, models],
+  );
+
+  const selectedFunction = useMemo(
+    () => (selection.kind === "function" ? (functions[selection.id] ?? null) : null),
+    [selection, functions],
+  );
+
+  const getNodeCategory = useCallback(
+    (node: NodeData) => getNodeDef(node)?.category as NodeCategoryEnum | undefined,
+    [getNodeDef],
+  );
+
+  const handleTestNode = useCallback((nodeId: string) => onTestNode?.(nodeId), [onTestNode]);
+
+  if (selectionDrag) return null;
+
+  if (isDebugMode) {
+    if (!selectedNode) return null;
+    return (
+      <Shell bg="bg-background" pad>
+        <DebugExternalIOPanel
+          canvasId={canvasId}
+          onStep={onDebugStep ?? (() => {})}
+          getNodeCategory={getNodeCategory}
+        />
+      </Shell>
+    );
+  }
+
+  if (selectedNode) {
+    return (
+      <Shell>
+        <NodeConfigPanel
+          canvasId={canvasId}
+          selectedNode={selectedNode}
+          onNodeUpdate={onNodeUpdate}
+          onNodeDelete={onNodeDelete}
+          onClose={onClearSelection}
+          onOpenTest={handleTestNode}
+          getNodeDef={getNodeDef}
+        />
+      </Shell>
+    );
+  }
+
+  if (selectedEdge) {
+    return (
+      <Shell>
+        <EdgeConfigPanel
+          canvasId={canvasId}
+          edgeId={selectedEdge.id}
+          edgeType={selectedEdge.type}
+          edgeData={selectedEdge.data}
+          sourceControlEdgeCount={sourceControlEdgeCount}
+          onEdgeUpdate={onEdgeUpdate}
+          onEdgeDelete={onEdgeDelete}
+          onClose={onClearSelection}
+        />
+      </Shell>
+    );
+  }
+
+  if (selectedVariable) {
+    return (
+      <Shell>
+        <VariableConfigPanel
+          canvasId={canvasId}
+          variable={selectedVariable}
+          onClose={clearSelection}
+        />
+      </Shell>
+    );
+  }
+
+  if (selectedChannel) {
+    return (
+      <Shell>
+        <ChannelConfigPanel channel={selectedChannel} onClose={clearSelection} />
+      </Shell>
+    );
+  }
+
+  if (selectedMemory) {
+    return (
+      <Shell>
+        <MemoryConfigPanel memory={selectedMemory} onClose={clearSelection} />
+      </Shell>
+    );
+  }
+
+  if (selectedModel) {
+    return (
+      <Shell>
+        <ModelConfigPanel model={selectedModel} onClose={clearSelection} />
+      </Shell>
+    );
+  }
+
+  if (selectedFunction) {
+    return (
+      <Shell>
+        <FunctionConfigPanel func={selectedFunction} onClose={clearSelection} />
+      </Shell>
+    );
+  }
+
+  return null;
+};
+
+/**
+ * Right-panel chrome — fixed-width column with the bordered card background
+ * and an overlay scrollbar. Extracted because all eight selection branches
+ * render the same shell; keeping them in lockstep by hand was an obvious
+ * drift risk. The debug variant overrides the surface and adds inner padding
+ * (other variants pad inside their own ConfigPanel).
+ */
+const Shell = ({
+  bg = "bg-card",
+  pad = false,
+  children,
+}: {
+  bg?: string;
+  pad?: boolean;
+  children: ReactNode;
+}) => (
+  <ScrollArea className={cn("w-80 border-l border-border", bg)} viewportClassName={pad ? "p-3" : undefined}>
+    {children}
+  </ScrollArea>
+);

package/src/WorkflowBuilder.tsx

@@ -0,0 +1,412 @@
+import type { ApiWorkflow } from "@foresthubai/workflow-core/workflow";
+import type { ModelInfo } from "@foresthubai/workflow-core/model";
+import {
+  validateWorkflowState,
+  validateChannel,
+  validateMemory,
+  validateModel,
+  type Diagnostic,
+  type ValidationResult,
+} from "@foresthubai/workflow-core/diagnostics";
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useRef, useState } from "react";
+import { I18nextProvider } from "react-i18next";
+
+import i18n from "./i18n";
+import { toast } from "./hooks/use-toast";
+import ValidationDialog from "./dialogs/ValidationDialog";
+import { BuilderLayout } from "./BuilderLayout";
+import { TooltipProvider } from "./components/ui/tooltip";
+import { Toaster } from "./components/ui/toaster";
+import { useCanvasTabs } from "./hooks/useCanvasTabs";
+import { useResourceDiagnosticsSync } from "./hooks/useResourceDiagnosticsSync";
+import { useFunctionDiagnosticsSync } from "./hooks/useFunctionDiagnosticsSync";
+import { useSuppressThemeTransition } from "./hooks/useSuppressThemeTransition";
+import { useFunctions } from "./hooks/useFunctions";
+import { useWorkflowSerialization, readStateFromStores } from "./hooks/useWorkflowSerialization";
+import {
+  clearAllCanvasStores,
+  getAllCanvasStores,
+  getOrCreateCanvasStore,
+  subscribeCanvasRegistryChanges,
+  MAIN_CANVAS_ID,
+  type CanvasStore,
+} from "./stores/canvasStore";
+import { useDebugStore, type DebugSessionPhase } from "./stores/debugStore";
+import { useEditorStore } from "./stores/editorStore";
+
+/** BuilderMode steers the overall behavior of the workflow builder. */
+export type BuilderMode = { type: "edit" } | { type: "preview" } | { type: "debug" };
+
+/** True when canvas mutations should be blocked (preview or debug). */
+export function isReadOnly(mode: BuilderMode): boolean {
+  return mode.type !== "edit";
+}
+
+/** Type guard for preview mode. */
+export function isPreview(mode: BuilderMode): boolean {
+  return mode.type === "preview";
+}
+
+// ============================================================================
+// Public contract
+// ============================================================================
+
+export interface WorkflowBuilderProps {
+  /** Workflow loaded on mount. If none is provided, an empty workflow is created. */
+  initialWorkflow?: ApiWorkflow;
+  /** Builder mode on mount. Defaults to { type: "edit" }. */
+  initialMode?: BuilderMode;
+  /**
+   * Static model catalog — the models the llmproxy supports. Shown as the
+   * built-in options in agent model pickers. Self-hosted/custom models are
+   * declared in the Models tab instead. Defaults to [] (empty dropdown).
+   */
+  models?: ModelInfo[];
+  /**
+   * UI language (e.g. "en", "de"). The host owns locale; the builder follows.
+   * Defaults to "en". The builder never auto-detects language.
+   */
+  language?: string;
+
+  // ── Embedder-fulfilled actions (builder asks, embedder does) ──
+  /** A node requested embedder-side testing (e.g. Agent "Test" button). */
+  onTestNode?: (nodeId: string) => void;
+  /** Step request from the in-builder debug panel — embedder forwards to the engine. */
+  onDebugStep?: (nodeId?: string) => void;
+
+  // ── Lifecycle events ──
+  /** Fires after any domain-state mutation. Pull current state via handle.exportWorkflow(). */
+  onChange?: () => void;
+  /**
+   * Undo/redo availability for the ACTIVE canvas changed — on history mutation,
+   * undo/redo, or a tab switch (each canvas has its own history). For wiring host
+   * undo/redo buttons.
+   */
+  onHistoryChange?: (state: { canUndo: boolean; canRedo: boolean }) => void;
+  /** Unexpected error during builder operations (e.g. failed load). */
+  onError?: (error: Error) => void;
+}
+
+export interface WorkflowBuilderHandle {
+  // State I/O
+  loadWorkflow: (workflow: ApiWorkflow) => void;
+  exportWorkflow: () => ApiWorkflow;
+  clear: () => void;
+
+  // Mode (replaces preview/debug entry-point props)
+  setMode: (mode: BuilderMode) => void;
+  getMode: () => BuilderMode;
+
+  // Initiate the in-builder validation process which will either show the validation dialog or a toast if clean.
+  validate: () => void;
+
+  // History (so embedder chrome can wire undo/redo buttons)
+  undo: () => void;
+  redo: () => void;
+
+  // Debug (embedder pushes engine events for visualization)
+  setDebugPhase: (phase: DebugSessionPhase) => void;
+}
+
+// ============================================================================
+// Component — owns tabs/functions/dialogs; exposes the handle; delegates
+// layout/canvas rendering to BuilderLayout.
+// ============================================================================
+
+export const WorkflowBuilder = forwardRef<WorkflowBuilderHandle, WorkflowBuilderProps>(
+  function WorkflowBuilder(props, ref) {
+    const {
+      initialWorkflow,
+      initialMode,
+      models,
+      language,
+      onTestNode,
+      onDebugStep,
+      onChange,
+      onHistoryChange,
+      onError,
+    } = props;
+
+    // Host drives locale. useLayoutEffect (not useEffect) so the language is set
+    // before paint — mounting with language="de" shows German on the first frame
+    // rather than flashing English. changeLanguage is sync here (bundled resources).
+    useLayoutEffect(() => {
+      if (language && i18n.language !== language) i18n.changeLanguage(language);
+    }, [language]);
+
+    const { importProject, exportProject } = useWorkflowSerialization();
+
+    // Color-mode toggles should snap, not fade — see hook docs.
+    useSuppressThemeTransition();
+
+    // Keep project-scoped (channel + memory + model) diagnostics in sync. Mounted
+    // once here at the root so badges survive sidebar tab open/close.
+    useResourceDiagnosticsSync({
+      selectItems: (s) => s.channels,
+      validate: validateChannel,
+      getStored: (d) => d.byChannelId,
+      set: (d, id, diags) => d.setChannelDiagnostics(id, diags),
+      clear: (d, id) => d.clearChannelDiagnostics(id),
+    });
+    useResourceDiagnosticsSync({
+      selectItems: (s) => s.memory,
+      validate: validateMemory,
+      getStored: (d) => d.byMemoryId,
+      set: (d, id, diags) => d.setMemoryDiagnostics(id, diags),
+      clear: (d, id) => d.clearMemoryDiagnostics(id),
+    });
+    useResourceDiagnosticsSync({
+      selectItems: (s) => s.models,
+      validate: validateModel,
+      getStored: (d) => d.byModelId,
+      set: (d, id, diags) => d.setModelDiagnostics(id, diags),
+      clear: (d, id) => d.clearModelDiagnostics(id),
+    });
+    // Functions are a FunctionDeclaration (not a flat resource bag), so they use a
+    // dedicated diagnostics sync.
+    useFunctionDiagnosticsSync();
+
+    // Push the embedder-supplied model catalog into the store so agent model
+    // pickers can read it. Catalog is config (not workflow content), so this
+    // never fires onChange.
+    useEffect(() => {
+      useEditorStore.getState().setAvailableModels(models ?? []);
+    }, [models]);
+
+    // Canvas tabs + functions live here because they survive canvas switches.
+    const canvasTabs = useCanvasTabs();
+    const functionsHook = useFunctions({ onOpenTab: canvasTabs.openTab });
+
+    // Built-in validation UX. validate() presents the result itself rather than
+    // returning it: a success toast when clean, else this dialog. Non-null = open.
+    const [validation, setValidation] = useState<ValidationResult | null>(null);
+
+    const runValidate = useCallback(() => {
+      const result = validateWorkflowState(readStateFromStores());
+      if (result.totalErrors === 0 && result.totalWarnings === 0) {
+        toast({ title: i18n.t("validationPassed") });
+      } else {
+        setValidation(result);
+      }
+    }, []);
+
+    // Jump to a diagnostic's target, then dismiss the dialog so it's visible.
+    const navigateToDiagnostic = useCallback(
+      (d: Diagnostic) => {
+        const editor = useEditorStore.getState();
+        // Project-scoped targets: open the matching sidebar tab AND select the item.
+        if (d.channelId) {
+          editor.setActiveSidebarTab("channels");
+          editor.selectChannel(d.channelId);
+        } else if (d.memoryId) {
+          editor.setActiveSidebarTab("memory");
+          editor.selectMemory(d.memoryId);
+        } else if (d.modelId) {
+          editor.setActiveSidebarTab("models");
+          editor.selectModel(d.modelId);
+        } else if (d.canvasId) {
+          // Switch first so selectGraph targets the right canvas, then select.
+          if (d.canvasId === MAIN_CANVAS_ID) editor.setActiveCanvas(MAIN_CANVAS_ID);
+          else functionsHook.openFunction(d.canvasId);
+          if (d.nodeId) editor.selectGraph([d.nodeId], []);
+          else if (d.edgeId) editor.selectGraph([], [d.edgeId]);
+        }
+        setValidation(null);
+      },
+      [functionsHook],
+    );
+
+    // Initial load (runs once, even under StrictMode double-mount).
+    const initialLoadDone = useRef(false);
+    useEffect(() => {
+      if (initialLoadDone.current) return;
+      initialLoadDone.current = true;
+      try {
+        if (initialMode) useEditorStore.getState().setBuilderMode(initialMode);
+        if (initialWorkflow) importProject(initialWorkflow);
+      } catch (e) {
+        onError?.(e instanceof Error ? e : new Error(String(e)));
+      }
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    // ── Lifecycle subscriptions ────────────────────────────────────────────
+    // Stash latest callbacks in refs so the subscription effect runs once.
+    const onChangeRef = useRef(onChange);
+    const onHistoryChangeRef = useRef(onHistoryChange);
+    onChangeRef.current = onChange;
+    onHistoryChangeRef.current = onHistoryChange;
+
+    // onChange fires on any domain change. For canvas content we watch the
+    // history middleware's `mutationCount`, which bumps on checkpoints AND
+    // undo/redo but never on selection/drag (those go through setNodes without a
+    // checkpoint). That makes onChange honest for undo/redo and silent on
+    // view-state — the thing a raw store subscription can't do, since selection
+    // lives inside the nodes array. (editorStore exposes its own `mutationCount`
+    // for project-scoped channel/memory/model edits; watched separately below.)
+    useEffect(() => {
+      const subs: Array<() => void> = [];
+      const subscribedStores = new WeakSet<CanvasStore>();
+
+      function subscribeCanvas(store: CanvasStore) {
+        if (subscribedStores.has(store)) return;
+        subscribedStores.add(store);
+        let prev = store.getState().mutationCount;
+        const unsub = store.subscribe((state) => {
+          if (state.mutationCount !== prev) {
+            prev = state.mutationCount;
+            onChangeRef.current?.();
+          }
+        });
+        subs.push(unsub);
+      }
+
+      function subscribeAllCanvases() {
+        for (const store of Object.values(getAllCanvasStores())) {
+          subscribeCanvas(store);
+        }
+      }
+
+      subscribeAllCanvases();
+
+      // Canvas stores come and go (function add/delete, project load). Re-subscribe
+      // to the new set so newly created function bodies are watched. We do NOT fire
+      // onChange here: function add/delete/rename and all definition edits flow
+      // through editorStore.mutationCount (setFunctions), caught by the editor
+      // subscription below — so the change signal is covered without double-firing.
+      const unsubRegistry = subscribeCanvasRegistryChanges(() => {
+        subscribeAllCanvases();
+      });
+      subs.push(unsubRegistry);
+
+      // Project-scoped mutations (channels, memory, models, functions).
+      let prevEditorCount = useEditorStore.getState().mutationCount;
+      const unsubEditor = useEditorStore.subscribe((state) => {
+        if (state.mutationCount !== prevEditorCount) {
+          prevEditorCount = state.mutationCount;
+          onChangeRef.current?.();
+        }
+      });
+      subs.push(unsubEditor);
+
+      return () => {
+        for (const u of subs) u();
+      };
+    }, []);
+
+    // History-affordance subscription — emits the ACTIVE canvas's canUndo/canRedo
+    // so host chrome can drive undo/redo buttons. Distinct from onChange: a tab
+    // switch changes which history is active without being a domain mutation, so
+    // it must update buttons without marking the document dirty.
+    useEffect(() => {
+      let prevCanUndo: boolean | null = null;
+      let prevCanRedo: boolean | null = null;
+      let unsubActive: (() => void) | null = null;
+
+      const emit = () => {
+        const store = getOrCreateCanvasStore(useEditorStore.getState().activeCanvasId);
+        const canUndo = store.canUndo();
+        const canRedo = store.canRedo();
+        if (canUndo === prevCanUndo && canRedo === prevCanRedo) return;
+        prevCanUndo = canUndo;
+        prevCanRedo = canRedo;
+        onHistoryChangeRef.current?.({ canUndo, canRedo });
+      };
+
+      // Bind to the current active canvas (a) and emit. Re-run on tab switch (b)
+      // and on store-instance rebuilds from load/clear (c) — both can change which
+      // store, or store object, is active under us.
+      const bindActive = () => {
+        unsubActive?.();
+        unsubActive = getOrCreateCanvasStore(useEditorStore.getState().activeCanvasId).subscribe(emit);
+        emit();
+      };
+
+      bindActive();
+
+      let prevActive = useEditorStore.getState().activeCanvasId;
+      const unsubEditor = useEditorStore.subscribe((state) => {
+        if (state.activeCanvasId !== prevActive) {
+          prevActive = state.activeCanvasId;
+          bindActive(); // (b) tab switch
+        }
+      });
+      const unsubRegistry = subscribeCanvasRegistryChanges(bindActive); // (c) load/clear rebuild
+
+      return () => {
+        unsubActive?.();
+        unsubEditor();
+        unsubRegistry();
+      };
+    }, []);
+
+    // ── Imperative handle ─────────────────────────────────────────────────
+    useImperativeHandle(
+      ref,
+      (): WorkflowBuilderHandle => ({
+        loadWorkflow: (workflow) => {
+          try {
+            importProject(workflow);
+          } catch (e) {
+            onError?.(e instanceof Error ? e : new Error(String(e)));
+          }
+        },
+        exportWorkflow: () => exportProject(),
+        clear: () => {
+          clearAllCanvasStores();
+          // Function declarations are project-scoped (not in canvas stores), so reset
+          // them explicitly alongside the cleared bodies.
+          useEditorStore.getState().setFunctions(() => ({}));
+          useEditorStore.getState().clearSelection();
+        },
+        setMode: (mode) => useEditorStore.getState().setBuilderMode(mode),
+        getMode: () => useEditorStore.getState().builderMode,
+        validate: runValidate,
+        undo: () => getOrCreateCanvasStore(useEditorStore.getState().activeCanvasId).undo(),
+        redo: () => getOrCreateCanvasStore(useEditorStore.getState().activeCanvasId).redo(),
+        setDebugPhase: (phase) => useDebugStore.getState().setPhase(phase),
+      }),
+      [importProject, exportProject, onError, runValidate],
+    );
+
+    // I18nextProvider scopes the builder's PRIVATE i18n instance to this subtree,
+    // so the useTranslation() consumers read it (never the host's i18next).
+    //
+    // The `fh-builder` root carries the builder's OWN base look (font,
+    // text color, antialiasing) on its own element. The builder no longer styles
+    // the host's <body> — the host owns the page. `h-full w-full` makes the
+    // builder fill whatever container it's mounted in; it never assumes the
+    // viewport. TooltipProvider + Toaster live inside the package so the embedder
+    // doesn't need to know we use Radix tooltips or shadcn toasts internally.
+    return (
+      <I18nextProvider i18n={i18n}>
+        <TooltipProvider delayDuration={300}>
+          <div className="fh-builder h-full w-full bg-background text-foreground font-sans antialiased">
+            <BuilderLayout
+              functions={functionsHook.functions}
+              onOpenFunction={functionsHook.openFunction}
+              onCreateFunction={functionsHook.createFunction}
+              canvasTabs={canvasTabs.tabs}
+              onCanvasTabChange={canvasTabs.setActiveTabId}
+              onCanvasTabClose={canvasTabs.closeTab}
+              onCanvasTabReorder={canvasTabs.reorderTabs}
+              onTestNode={onTestNode}
+              onDebugStep={onDebugStep}
+            />
+            <Toaster />
+            {validation && (
+              <ValidationDialog
+                open
+                onOpenChange={(o) => {
+                  if (!o) setValidation(null);
+                }}
+                validation={validation}
+                onSelectDiagnostic={navigateToDiagnostic}
+              />
+            )}
+          </div>
+        </TooltipProvider>
+      </I18nextProvider>
+    );
+  },
+);

package/src/cn.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}