@foresthubai/workflow-builder 0.3.0

package/src/hooks/useCanvasTabs.ts

@@ -0,0 +1,168 @@
+import { useState, useCallback, useEffect } from "react";
+import { MAIN_CANVAS_ID } from "../stores/canvasStore";
+import { useEditorStore } from "../stores/editorStore";
+
+// Holds info for a canvas tab. id is identical to canvasId.
+export interface CanvasTab {
+  id: string;
+  label: string;
+}
+
+/**
+ * Hook for managing canvas tabs UI.
+ * Tab switching directly updates the UI store's activeCanvasId.
+ */
+export const useCanvasTabs = () => {
+  const [tabs, setTabs] = useState<CanvasTab[]>([{ id: MAIN_CANVAS_ID, label: "Main" }]);
+
+  // Get active canvas ID and setter from editor store
+  const activeCanvasId = useEditorStore((state) => state.activeCanvasId);
+  const setActiveCanvas = useEditorStore((state) => state.setActiveCanvas);
+  const selectFunction = useEditorStore((state) => state.selectFunction);
+
+  // Tabs are a projection of the function declarations: a deleted function drops its
+  // tab (falling back to Main if it was active), a renamed one relabels. Open/close
+  // of an existing function's tab is still explicit (openTab/closeTab) — this only
+  // reconciles against the source of truth so the strip can't show a stale function.
+  const functions = useEditorStore((state) => state.functions);
+  useEffect(() => {
+    setTabs((prev) => {
+      let changed = false;
+      const next = prev.flatMap<CanvasTab>((t) => {
+        if (t.id === MAIN_CANVAS_ID) return [t];
+        const fn = functions[t.id];
+        if (!fn) {
+          changed = true;
+          return [];
+        }
+        if (fn.name !== t.label) {
+          changed = true;
+          return [{ ...t, label: fn.name }];
+        }
+        return [t];
+      });
+      return changed ? next : prev;
+    });
+    if (activeCanvasId !== MAIN_CANVAS_ID && !functions[activeCanvasId]) {
+      setActiveCanvas(MAIN_CANVAS_ID);
+    }
+  }, [functions, activeCanvasId, setActiveCanvas]);
+
+  // Switch to a tab's canvas. A function tab focuses its declaration (selectFunction
+  // switches the canvas AND selects the function so its config panel opens) — matching
+  // the dropdown/sidebar open path; any other tab just switches the canvas.
+  const setActiveTabId = useCallback(
+    (tabId: string) => {
+      if (tabId !== MAIN_CANVAS_ID && functions[tabId]) {
+        selectFunction(tabId);
+      } else {
+        setActiveCanvas(tabId);
+      }
+    },
+    [functions, selectFunction, setActiveCanvas],
+  );
+
+  // Open a tab for a function (add if not exists, switch to it)
+  const openTab = useCallback(
+    (id: string, label: string) => {
+      setTabs((prev) => {
+        const existing = prev.find((t) => t.id === id);
+        if (existing) {
+          return prev; // Already exists
+        }
+        return [...prev, { id, label }];
+      });
+      setActiveCanvas(id);
+      return id;
+    },
+    [setActiveCanvas],
+  );
+
+  // Close a tab (just removes from visible tabs, does NOT delete canvas data)
+  const closeTab = useCallback(
+    (tabId: string) => {
+      // Cannot close main tab
+      if (tabId === MAIN_CANVAS_ID) return;
+
+      setTabs((prev) => {
+        const filtered = prev.filter((t) => t.id !== tabId);
+        // If closing active tab, switch to main
+        if (tabId === activeCanvasId) {
+          setActiveCanvas(MAIN_CANVAS_ID);
+        }
+        return filtered;
+      });
+    },
+    [activeCanvasId, setActiveCanvas],
+  );
+
+  // Remove a tab completely (called when function is deleted)
+  const removeTab = useCallback(
+    (tabId: string) => {
+      if (tabId === MAIN_CANVAS_ID) return;
+
+      setTabs((prev) => {
+        const filtered = prev.filter((t) => t.id !== tabId);
+        // Switch to main canvas if removing active tab
+        if (tabId === activeCanvasId) {
+          setActiveCanvas(MAIN_CANVAS_ID);
+        }
+        return filtered;
+      });
+    },
+    [activeCanvasId, setActiveCanvas],
+  );
+
+  const renameTab = useCallback((tabId: string, newLabel: string) => {
+    setTabs((prev) => prev.map((t) => (t.id === tabId ? { ...t, label: newLabel } : t)));
+  }, []);
+
+  const reorderTabs = useCallback((fromIndex: number, toIndex: number) => {
+    if (fromIndex === 0 || toIndex === 0) return;
+    setTabs((prev) => {
+      const updated = [...prev];
+      const [moved] = updated.splice(fromIndex, 1);
+      if (!moved) return prev;
+      updated.splice(toIndex, 0, moved);
+      return updated;
+    });
+  }, []);
+
+  // Reset to main canvas only (closes all function tabs)
+  const resetToMain = useCallback(() => {
+    setTabs([{ id: MAIN_CANVAS_ID, label: "Main" }]);
+    setActiveCanvas(MAIN_CANVAS_ID);
+  }, [setActiveCanvas]);
+
+  // Restore a previously saved tab state
+  const restoreTabState = useCallback(
+    (savedTabs: CanvasTab[], savedActiveId: string) => {
+      setTabs(savedTabs);
+      setActiveCanvas(savedActiveId);
+    },
+    [setActiveCanvas],
+  );
+
+  // Get label for a tab
+  const getTabLabel = useCallback(
+    (tabId: string) => {
+      return tabs.find((t) => t.id === tabId)?.label || "Unknown";
+    },
+    [tabs],
+  );
+
+  return {
+    tabs,
+    activeTabId: activeCanvasId,
+    setActiveTabId,
+    openTab,
+    closeTab,
+    removeTab,
+    renameTab,
+    reorderTabs,
+    resetToMain,
+    restoreTabState,
+    getTabLabel,
+    isMainCanvas: activeCanvasId === MAIN_CANVAS_ID,
+  };
+};

package/src/hooks/useFunctionDiagnosticsSync.ts

@@ -0,0 +1,40 @@
+import { useEffect } from "react";
+import { validateFunction } from "@foresthubai/workflow-core/diagnostics";
+import { computeAvailableVariables } from "@foresthubai/workflow-core/variable";
+import { useEditorStore } from "../stores/editorStore";
+import { useDiagnosticsStore } from "../stores/diagnosticsStore";
+import { getCanvasStore } from "../stores/canvasStore";
+
+/**
+ * Keeps the `byFunctionId` diagnostics slot in sync with the function declarations —
+ * the single source for the sidebar tab badge, the function list ring, AND the config
+ * panel's per-output rings (they all read this slot). Mounted once at the
+ * workflow-builder root so it survives tab open/close.
+ *
+ * Scope-aware: each function is validated against its own body canvas's variables, so
+ * invalid/typed return expressions surface here too — not just missing ones. (Reacts
+ * to declaration/expression edits via `functions`; a body-only edit that changes the
+ * available variables without touching a declaration refreshes on the next
+ * declaration change or a full `validate`.)
+ */
+export function useFunctionDiagnosticsSync(): void {
+  const functions = useEditorStore((s) => s.functions);
+
+  useEffect(() => {
+    const ds = useDiagnosticsStore.getState();
+
+    const seen = new Set<string>();
+    for (const [id, def] of Object.entries(functions)) {
+      seen.add(id);
+      const store = getCanvasStore(id);
+      const lookup = store
+        ? computeAvailableVariables(store.getState().variables, store.getState().edges).lookup
+        : undefined;
+      ds.setFunctionDiagnostics(id, validateFunction(def, lookup));
+    }
+
+    for (const id of Object.keys(ds.byFunctionId)) {
+      if (!seen.has(id)) ds.clearFunctionDiagnostics(id);
+    }
+  }, [functions]);
+}

package/src/hooks/useFunctionRegistry.ts

@@ -0,0 +1,26 @@
+import { useCallback, useMemo } from "react";
+import { useEditorStore } from "../stores/editorStore";
+import type { FunctionDeclaration } from "@foresthubai/workflow-core/function";
+
+// Functions are a project-scoped resource: the registry IS editorStore.functions —
+// the domain FunctionDeclaration, no conversion. (Crossing to the flat api FunctionInfo
+// is done only when stamping a call-site snapshot; see useNodeDefinitions/migration.)
+
+/**
+ * Access to all function declarations by id. Reactive over editorStore.functions.
+ * - functions: Record of FunctionDeclaration by id
+ * - functionsList: array of FunctionDeclaration
+ * - getFunction(id): one declaration by id
+ */
+export function useFunctionRegistry() {
+  const functions = useEditorStore((s) => s.functions);
+  const functionsList = useMemo(() => Object.values(functions), [functions]);
+  const getFunction = useCallback((id: string): FunctionDeclaration | undefined => functions[id], [functions]);
+
+  return { functions, functionsList, getFunction };
+}
+
+/** All function declarations without React subscription (for non-component code). */
+export function getAllFunctions(): Record<string, FunctionDeclaration> {
+  return useEditorStore.getState().functions;
+}

package/src/hooks/useFunctions.ts

@@ -0,0 +1,44 @@
+import { useCallback } from "react";
+import { useEditorStore } from "../stores/editorStore";
+import { getOrCreateCanvasStore } from "../stores/canvasStore";
+import { useFunctionRegistry } from "./useFunctionRegistry";
+import { addFunction } from "../utils/functionOperations";
+
+export interface UseFunctionsOptions {
+  /** Open (or focus) a tab for a function canvas. */
+  onOpenTab: (id: string, label: string) => void;
+}
+
+/**
+ * Coordinates the canvas-tab UI with function declarations (editorStore). The
+ * declarations themselves are CRUD'd in utils/functionOperations; this hook only
+ * handles the open/create flows that must also touch the tab strip and selection.
+ */
+export const useFunctions = ({ onOpenTab }: UseFunctionsOptions) => {
+  const { functionsList: functions, getFunction } = useFunctionRegistry();
+  const selectFunction = useEditorStore((s) => s.selectFunction);
+
+  // Open an existing function: ensure its body canvas exists, open its tab, and
+  // select it so the right panel shows its definition. onOpenTab switches the active
+  // canvas first; selectFunction sets the selection last so it isn't cleared.
+  const openFunction = useCallback(
+    (functionId: string) => {
+      const fn = getFunction(functionId);
+      if (!fn) return;
+      getOrCreateCanvasStore(functionId);
+      onOpenTab(functionId, fn.name);
+      selectFunction(functionId);
+    },
+    [getFunction, onOpenTab, selectFunction],
+  );
+
+  // Create a new function and open it (the canvas body is created by addFunction).
+  const createFunction = useCallback(() => {
+    const fn = addFunction();
+    onOpenTab(fn.id, fn.name);
+    selectFunction(fn.id);
+    return fn.id;
+  }, [onOpenTab, selectFunction]);
+
+  return { functions, openFunction, createFunction };
+};

package/src/hooks/useGraph.ts

@@ -0,0 +1,161 @@
+import { NodeDefinition, NodeData } from "@foresthubai/workflow-core/node";
+import { Connection, Edge, Node } from "@xyflow/react";
+import type { EdgeData } from "@foresthubai/workflow-core/edge";
+import { useCallback } from "react";
+import { getOrCreateCanvasStore, MAIN_CANVAS_ID } from "../stores/canvasStore";
+import {
+  addNodeToStore,
+  type Clipboard,
+  connectNodesInStore,
+  deleteEdgesFromStore,
+  deleteNodeFromStore,
+  pasteToStore,
+  updateEdgeInStore,
+  updateNodeInStore,
+} from "../utils/graphOperations";
+import type { EdgeType } from "@foresthubai/workflow-core/edge";
+import { useNodeDefinitions } from "./useNodeDefinitions";
+
+// Shared across all useGraph instances (one per canvas) so copy/paste works
+// across canvas switches within a single builder session.
+const clipboardRef: { current: Clipboard | null } = { current: null };
+
+/**
+ * Hook that provides graph management actions for a specific canvas.
+ *
+ * All mutations are:
+ * - Gated by readOnly (no-op when true)
+ * - Automatically wrapped in a history checkpoint (undo/redo)
+ *
+ * Callers don't need to worry about either concern.
+ */
+export const useGraph = (canvasId: string = MAIN_CANVAS_ID, readOnly: boolean = false) => {
+  const canvasStore = getOrCreateCanvasStore(canvasId);
+  const nodes = canvasStore((s) => s.nodes);
+  const edges = canvasStore((s) => s.edges);
+  const { withCheckpoint } = canvasStore;
+
+  const { getNodeDefinition } = useNodeDefinitions();
+
+  // Guarded checkpoint: skips when readOnly, otherwise wraps in undo history entry
+  const guarded = useCallback(
+    <R>(operation: () => R): R | undefined => {
+      if (readOnly) return undefined;
+      return withCheckpoint(operation);
+    },
+    [readOnly, withCheckpoint],
+  );
+
+  const addNode = useCallback(
+    (nodeDef: NodeDefinition, position?: { x: number; y: number }) => {
+      return guarded(() => addNodeToStore(canvasStore, nodeDef, position)) ?? null;
+    },
+    [canvasStore, guarded],
+  );
+
+  const updateNode = useCallback(
+    (nodeId: string, updates: { arguments?: Record<string, unknown>; label?: string }) => {
+      guarded(() => updateNodeInStore(canvasStore, nodeId, updates));
+    },
+    [canvasStore, guarded],
+  );
+
+  const deleteNode = useCallback(
+    (nodeId: string) => {
+      guarded(() => deleteNodeFromStore(canvasStore, nodeId, getNodeDefinition));
+    },
+    [canvasStore, getNodeDefinition, guarded],
+  );
+
+  const onConnect = useCallback(
+    (connection: Connection): EdgeType | false => {
+      return guarded(() => connectNodesInStore(canvasStore, connection)) ?? false;
+    },
+    [canvasStore, guarded],
+  );
+
+  const updateEdge = useCallback(
+    (edgeId: string, updates: Record<string, unknown>) => {
+      guarded(() => updateEdgeInStore(canvasStore, edgeId, updates));
+    },
+    [canvasStore, guarded],
+  );
+
+  const deleteEdges = useCallback(
+    (edgeIds: string[]) => {
+      guarded(() => deleteEdgesFromStore(canvasStore, edgeIds));
+    },
+    [canvasStore, guarded],
+  );
+
+  // Batch delete nodes and edges as a single undo entry
+  const deleteSelected = useCallback(
+    (nodeIds: string[], edgeIds: string[]) => {
+      if (nodeIds.length === 0 && edgeIds.length === 0) return;
+      guarded(() => {
+        for (const nodeId of nodeIds) deleteNodeFromStore(canvasStore, nodeId, getNodeDefinition);
+        if (edgeIds.length > 0) deleteEdgesFromStore(canvasStore, edgeIds);
+      });
+    },
+    [canvasStore, getNodeDefinition, guarded],
+  );
+
+  // Copy is read-only — no checkpoint, no readOnly gate
+  const copySelection = useCallback(
+    (nodeIds: string[]) => {
+      if (nodeIds.length === 0) return;
+
+      const nodeIdSet = new Set(nodeIds);
+
+      const copiedNodes = nodes
+        .filter((node) => nodeIdSet.has(node.id))
+        .map((node) => JSON.parse(JSON.stringify(node)) as Node<NodeData>);
+
+      const copiedEdges = edges
+        .filter((edge) => nodeIdSet.has(edge.source) && nodeIdSet.has(edge.target))
+        .map((edge) => JSON.parse(JSON.stringify(edge)) as Edge<EdgeData>);
+
+      clipboardRef.current = { nodes: copiedNodes, edges: copiedEdges };
+    },
+    [nodes, edges],
+  );
+
+  const pasteSelection = useCallback(
+    (offset?: { x: number; y: number }) => {
+      const clipboard = clipboardRef.current;
+      if (!clipboard) return undefined;
+      return guarded(() => pasteToStore(canvasStore, clipboard, offset, getNodeDefinition));
+    },
+    [canvasStore, getNodeDefinition, guarded],
+  );
+
+  // Batch add node + connect as a single undo entry (used by contextual node picker)
+  const addNodeAndConnect = useCallback(
+    (nodeDef: NodeDefinition, position: { x: number; y: number }, connection: Connection): string | null => {
+      return (
+        guarded(() => {
+          const nodeId = addNodeToStore(canvasStore, nodeDef, position);
+          if (nodeId == null) return null;
+          connectNodesInStore(canvasStore, { ...connection, target: nodeId });
+          return nodeId;
+        }) ?? null
+      );
+    },
+    [canvasStore, guarded],
+  );
+
+  return {
+    nodes,
+    edges,
+    addNode,
+    updateNode,
+    updateEdge,
+    deleteNode,
+    deleteEdges,
+    deleteSelected,
+    onConnect,
+    addNodeAndConnect,
+    copySelection,
+    pasteSelection,
+  };
+};

package/src/hooks/useNodeDefinitions.ts

@@ -0,0 +1,82 @@
+import { useMemo, useCallback } from "react";
+import i18n from "../i18n";
+import { NodeCategory, NodeRegistry, NodeDefinition, NodeData } from "@foresthubai/workflow-core/node";
+import { useFunctionRegistry } from "./useFunctionRegistry";
+import { toFunctionInfo, type FunctionInfo } from "@foresthubai/workflow-core/function";
+import { FunctionCallNode, FunctionNodeDefinition, buildFunctionNodeDef as coreBuildFunctionNodeDef } from "@foresthubai/workflow-core/node";
+
+/**
+ * Workflow-builder binding for {@link coreBuildFunctionNodeDef} — passes
+ * `i18n.t` so descriptions are translated. Consumers continue to call
+ * `buildFunctionNodeDef(fn)` unchanged; core's signature is the pure
+ * `(fn, t?)` form.
+ */
+export function buildFunctionNodeDef(fn: FunctionInfo): FunctionNodeDefinition {
+  return coreBuildFunctionNodeDef(fn, i18n.t.bind(i18n));
+}
+
+// Use function registry to provide dynamic node definitions based on available functions
+export const useNodeDefinitions = () => {
+  // Get static node definitions from registry (these never change)
+  const staticNodeDefs: NodeDefinition[] = NodeRegistry.getAll();
+
+  // Subscribe to function registry (derived from all canvas stores)
+  const { functions } = useFunctionRegistry();
+
+  // Dynamically create node definitions for each function. The call-site node def is
+  // built from the flat signature snapshot, so project the domain declaration here.
+  const functionNodeDefs: FunctionNodeDefinition[] = useMemo(
+    () => Object.values(functions).map((fn) => buildFunctionNodeDef(toFunctionInfo(fn))),
+    [functions],
+  );
+
+  // Get node definition for a node instance (still depending on all functions)
+  const getNodeDefinition = useCallback(
+    (node: NodeData): NodeDefinition | undefined => {
+      if (node.type === "FunctionCall") {
+        const fnNode = node as FunctionCallNode;
+        return functionNodeDefs.find((def) => def.type === "FunctionCall" && def.functionInfo.id === fnNode.functionInfo.id);
+      }
+      return NodeRegistry.getByType(node.type);
+    },
+    [functionNodeDefs],
+  );
+
+  const getNodeDefinitionsByCategory = useCallback(
+    (category: NodeCategory) => {
+      const staticNodes = NodeRegistry.getByCategory(category);
+      if (category === NodeCategory.Function) {
+        return [...staticNodes, ...functionNodeDefs];
+      }
+      return staticNodes;
+    },
+    [functionNodeDefs],
+  );
+
+  const getAllCategories = useCallback((): NodeCategory[] => {
+    const staticCategories = NodeRegistry.getAllCategories();
+    const allCategories = new Set([...staticCategories]);
+    if (functionNodeDefs.length > 0) {
+      allCategories.add(NodeCategory.Function);
+    }
+    const categoryOrder = [
+      NodeCategory.Trigger,
+      NodeCategory.Input,
+      NodeCategory.Logic,
+      NodeCategory.Data,
+      NodeCategory.Function,
+      NodeCategory.AI,
+      NodeCategory.Tool,
+      NodeCategory.Output,
+    ];
+    return categoryOrder.filter((cat) => allCategories.has(cat));
+  }, [functionNodeDefs]);
+
+  return {
+    nodeDefinitions: [...staticNodeDefs, ...functionNodeDefs],
+    getAllCategories,
+    getNodeDefinition,
+    getNodeDefinitionsByCategory,
+  };
+};
+

package/src/hooks/useParamErrors.ts

@@ -0,0 +1,26 @@
+import { useMemo } from "react";
+import type { Diagnostic } from "@foresthubai/workflow-core/diagnostics";
+
+/**
+ * Build a per-parameter error map (`paramId → messages`) from a resource's
+ * diagnostics, keeping only `error`-severity entries. Shared by every config
+ * panel that renders a parameter list (node / edge / channel / memory / model)
+ * so the inline Map-building loop lives in exactly one place.
+ *
+ * Memoized on `diags`, so callers can read it from the diagnostics store with a
+ * plain selector and pass the result straight through to `<ParameterEditor>`.
+ */
+export function useParamErrors(diags: Diagnostic[] | undefined): Map<string, string[]> {
+  return useMemo(() => {
+    const map = new Map<string, string[]>();
+    if (!diags) return map;
+    for (const d of diags) {
+      if (d.paramId && d.severity === "error") {
+        const arr = map.get(d.paramId);
+        if (arr) arr.push(d.message);
+        else map.set(d.paramId, [d.message]);
+      }
+    }
+    return map;
+  }, [diags]);
+}

package/src/hooks/useResolvedTheme.ts

@@ -0,0 +1,30 @@
+import { useEffect, useState } from "react";
+
+/**
+ * Returns "light" if `<html>` has the `light` class, else "dark". Subscribes to
+ * MutationObserver so toggles by the embedder propagate immediately.
+ *
+ * Dark is the default — the builder's CSS puts dark tokens on `:root` and
+ * overrides them under `.light`. This hook exists so things that need an
+ * explicit value — notably ReactFlow's `colorMode` prop — stay in sync.
+ */
+export function useResolvedTheme(): "dark" | "light" {
+  const [theme, setTheme] = useState<"dark" | "light">(() => detect());
+
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const root = document.documentElement;
+    const observer = new MutationObserver(() => setTheme(detect()));
+    observer.observe(root, { attributes: true, attributeFilter: ["class"] });
+    // Initial sync in case it changed between mount and effect.
+    setTheme(detect());
+    return () => observer.disconnect();
+  }, []);
+
+  return theme;
+}
+
+function detect(): "dark" | "light" {
+  if (typeof document === "undefined") return "dark";
+  return document.documentElement.classList.contains("light") ? "light" : "dark";
+}

package/src/hooks/useResourceDiagnosticsSync.ts

@@ -0,0 +1,58 @@
+import { useEffect } from "react";
+import { useEditorStore } from "../stores/editorStore";
+import { useDiagnosticsStore } from "../stores/diagnosticsStore";
+import type { Diagnostic } from "@foresthubai/workflow-core/diagnostics";
+
+type EditorState = ReturnType<typeof useEditorStore.getState>;
+type DiagnosticsState = ReturnType<typeof useDiagnosticsStore.getState>;
+
+interface ResourceDiagnosticsSyncConfig<I extends { id: string }> {
+  /** Pick the resource map (e.g. `s.channels`) off the editor store. */
+  selectItems: (s: EditorState) => Record<string, I>;
+  /** Validate one instance into its diagnostics. */
+  validate: (item: I) => Diagnostic[];
+  /** Read the matching diagnostics slot (e.g. `d.byChannelId`). */
+  getStored: (d: DiagnosticsState) => Record<string, Diagnostic[]>;
+  /** Write one instance's diagnostics. */
+  set: (d: DiagnosticsState, id: string, diags: Diagnostic[]) => void;
+  /** Drop one instance's diagnostics. */
+  clear: (d: DiagnosticsState, id: string) => void;
+}
+
+/**
+ * Keeps a project-scoped diagnostics slot (`byChannelId` / `byMemoryId` /
+ * `byModelId`) in sync with the editor's resource map.
+ *
+ * These resources are project-scoped, not canvas-scoped, and are only rendered
+ * visually when their sidebar tab is open. Tying diagnostic writes to card
+ * lifecycles would mean errors vanish the moment that tab closes, so this hook
+ * is mounted once at the workflow-builder root and reactively rewrites the store
+ * whenever the resource map changes.
+ *
+ * Lifecycle handled implicitly by the effect:
+ *  - Load   → setItems fires → effect re-runs → diagnostics written
+ *  - Edit   → store mutates  → effect re-runs → entry replaced
+ *  - Delete → item leaves    → orphan branch  → entry cleared
+ *  - Unmount → store goes down with the app (no cleanup needed)
+ */
+export function useResourceDiagnosticsSync<I extends { id: string }>(config: ResourceDiagnosticsSyncConfig<I>): void {
+  const items = useEditorStore(config.selectItems);
+
+  useEffect(() => {
+    const ds = useDiagnosticsStore.getState();
+
+    const seen = new Set<string>();
+    for (const item of Object.values(items)) {
+      seen.add(item.id);
+      config.set(ds, item.id, config.validate(item));
+    }
+
+    // Drop entries for items that have been deleted.
+    for (const id of Object.keys(config.getStored(ds))) {
+      if (!seen.has(id)) config.clear(ds, id);
+    }
+    // `config` is recreated each render but only `items` drives a resync; the
+    // effect reads the latest closure on every run.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [items]);
+}