@foresthubai/workflow-builder 0.3.0

package/src/utils/history.ts

@@ -0,0 +1,207 @@
+import { StateCreator, StoreMutatorIdentifier } from "zustand";
+
+// Opaque type for exporting/importing history state
+export interface HistoryData {
+  past: HistoryFrame<unknown>[];
+  future: HistoryFrame<unknown>[];
+}
+
+// Public interface - only actions
+export interface History {
+  /**
+   * Manually saves the current state as an undo checkpoint.
+   * Must be called BEFORE a state change that should be undoable.
+   */
+  takeCheckpoint: () => void;
+
+  /**
+   * Run the given operation and save a checkpoint if the state did change.
+   * Good to wrap multiple state changes in a single undoable action.
+   * If the operation throws, no checkpoint is saved and the error is propagated.
+   * @param operation Function that may perform a state change.
+   * @returns The result of the operation.
+   */
+  withCheckpoint: <R>(operation: () => R) => R;
+
+  /**
+   * Reverts the state to the previous snapshot in the undo history, if available.
+   * Moves the current state to the redo history.
+   */
+  undo: () => void;
+
+  /**
+   * Reapplies the most recently undone state from the redo history, if available.
+   * Moves the current state to the undo history.
+   */
+  redo: () => void;
+
+  /**
+   * Clears both the undo and redo history, but does not affect the current state.
+   */
+  clearHistory: () => void;
+
+  /**
+   * Returns true if there is at least one state in the undo history.
+   */
+  canUndo: () => boolean;
+
+  /**
+   * Returns true if there is at least one state in the redo history.
+   */
+  canRedo: () => boolean;
+
+  /**
+   * Exports the current undo/redo history as an opaque blob.
+   */
+  exportHistory: () => HistoryData;
+
+  /**
+   * Restores a previously exported history blob.
+   */
+  importHistory: (data: HistoryData) => void;
+}
+
+// A single frame in history
+interface HistoryFrame<T> {
+  state: T;
+  timestamp: number;
+}
+
+// Internal state - not exposed publicly
+interface HistoryState<T> {
+  _history_past: HistoryFrame<T>[];
+  _history_future: HistoryFrame<T>[];
+}
+
+/**
+ * Public, opaque change signal: a monotonic counter the middleware bumps on every
+ * history transition (checkpoint, undo, redo, clear, import). Subscribe to it to
+ * detect domain mutations and undo/redo in O(1). It never ticks on selection or
+ * drag — those mutate state without a checkpoint. Mirrors editorStore's counter
+ * of the same name for project-scoped (channel/memory/model) mutations.
+ */
+export interface MutationCount {
+  readonly mutationCount: number;
+}
+
+// Configuration for history middleware
+interface HistoryConfig<T> {
+  limit?: number;
+  partialize?: (state: T) => Partial<T>;
+  equality?: (before: Partial<T>, after: Partial<T>) => boolean;
+}
+
+export const history =
+  <T>(config: HistoryConfig<T> = {}) =>
+  <Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = []>(
+    storeInitializer: StateCreator<T, Mps, Mcs>,
+  ): StateCreator<T & HistoryState<T> & History & MutationCount, Mps, Mcs> => {
+    const {
+      limit = 50,
+      partialize = (state) => state,
+      equality = (before, after) => JSON.stringify(before) !== JSON.stringify(after),
+    } = config;
+
+    return (set, get, store) => {
+      type FullState = T & HistoryState<T> & History & MutationCount;
+
+      const initialState = storeInitializer(
+        set as Parameters<StateCreator<T, Mps, Mcs>>[0],
+        get as Parameters<StateCreator<T, Mps, Mcs>>[1],
+        store as Parameters<StateCreator<T, Mps, Mcs>>[2],
+      );
+
+      return {
+        ...initialState,
+        _history_past: [],
+        _history_future: [],
+        mutationCount: 0,
+
+        takeCheckpoint: () => {
+          const currentState = partialize(get() as T);
+          set((state: FullState) => ({
+            ...state,
+            _history_past: [...state._history_past, { state: currentState as T, timestamp: Date.now() }].slice(-limit),
+            _history_future: [],
+            mutationCount: state.mutationCount + 1,
+          }));
+        },
+
+        withCheckpoint: <R>(operation: () => R): R => {
+          const beforeState = partialize(get() as T);
+          // Execute operation and capture result to return later to caller
+          const result = operation();
+          const afterState = partialize(get() as T);
+          // Compare using provided equality function
+          const areEqual = equality(beforeState, afterState);
+          if (!areEqual) {
+            set((state: FullState) => ({
+              ...state,
+              _history_past: [...state._history_past, { state: beforeState as T, timestamp: Date.now() }].slice(-limit),
+              _history_future: [],
+              mutationCount: state.mutationCount + 1,
+            }));
+          }
+          return result;
+        },
+
+        undo: () => {
+          const state = get();
+          if (state._history_past.length === 0) return;
+          const past = [...state._history_past];
+          const previousFrame = past.pop()!;
+          // Save current state to future before restoring
+          const currentState = partialize(state as T);
+          set({
+            ...state,
+            ...previousFrame.state,
+            _history_past: past,
+            _history_future: [...state._history_future, { state: currentState as T, timestamp: Date.now() }],
+            mutationCount: state.mutationCount + 1,
+          } as FullState);
+        },
+
+        redo: () => {
+          const state = get();
+          if (state._history_future.length === 0) return;
+          const future = [...state._history_future];
+          const nextFrame = future.pop()!;
+          // Save current state to past before restoring
+          const currentState = partialize(state as T);
+          set({
+            ...state,
+            ...nextFrame.state,
+            _history_past: [...state._history_past, { state: currentState as T, timestamp: Date.now() }].slice(-limit),
+            _history_future: future,
+            mutationCount: state.mutationCount + 1,
+          } as FullState);
+        },
+
+        clearHistory: () => {
+          set((state: FullState) => ({
+            ...state,
+            _history_past: [],
+            _history_future: [],
+            mutationCount: state.mutationCount + 1,
+          }));
+        },
+
+        canUndo: () => (get() as FullState)._history_past.length > 0,
+        canRedo: () => (get() as FullState)._history_future.length > 0,
+
+        exportHistory: () => ({
+          past: [...(get() as FullState)._history_past],
+          future: [...(get() as FullState)._history_future],
+        }),
+
+        importHistory: (data: HistoryData) => {
+          set((state: FullState) => ({
+            ...state,
+            _history_past: [...data.past] as HistoryFrame<T>[],
+            _history_future: [...data.future] as HistoryFrame<T>[],
+            mutationCount: state.mutationCount + 1,
+          }));
+        },
+      } as FullState;
+    };
+  };

package/src/utils/memoryOperations.ts

@@ -0,0 +1,57 @@
+import { MemoryRegistry, type MemoryType, type Memory } from "@foresthubai/workflow-core/memory";
+import { useEditorStore } from "../stores/editorStore";
+import { generateId } from "@foresthubai/workflow-core/id";
+import { seedDefaultArguments, uniqueName } from "./resourceHelpers";
+
+/** Default label prefix per memory type. */
+const LABEL_PREFIX: Record<MemoryType, string> = {
+  MemoryFile: "memory",
+  VectorDatabase: "vectordb",
+};
+
+/** Create a new memory primitive of the given type in the editor store. Returns the new instance. */
+export function addMemory(type: MemoryType): Memory {
+  const id = generateId();
+  const existing = Object.values(useEditorStore.getState().memory).map((m) => m.label);
+  const instance: Memory = {
+    id,
+    label: uniqueName(LABEL_PREFIX[type], existing),
+    type,
+    arguments: seedDefaultArguments(MemoryRegistry.getByType(type)?.parameters ?? []),
+  };
+  useEditorStore.getState().setMemory((mem) => ({ ...mem, [id]: instance }));
+  return instance;
+}
+
+/**
+ * Apply a partial patch to a memory primitive. Top-level `label` and the
+ * `arguments` record are merged separately. The `type` discriminator is fixed
+ * at creation (the user picks a type when adding), so it is never patched here.
+ */
+export function updateMemory(id: string, patch: { label?: string; arguments?: Record<string, unknown> }): void {
+  const key = id;
+  useEditorStore.getState().setMemory((mem) => {
+    const existing = mem[key];
+    if (!existing) return mem;
+    return {
+      ...mem,
+      [key]: {
+        ...existing,
+        ...(patch.label !== undefined ? { label: patch.label } : {}),
+        ...(patch.arguments ? { arguments: { ...existing.arguments, ...patch.arguments } } : {}),
+      },
+    };
+  });
+}
+
+export function deleteMemory(id: string): void {
+  const key = id;
+  useEditorStore.getState().setMemory((mem) => {
+    const { [key]: _drop, ...rest } = mem;
+    return rest;
+  });
+  const sel = useEditorStore.getState().selection;
+  if (sel.kind === "memory" && sel.id === id) {
+    useEditorStore.getState().clearSelection();
+  }
+}

package/src/utils/migrateFunctionNodes.ts

@@ -0,0 +1,107 @@
+import type { OutputBinding, FunctionCallNode } from "@foresthubai/workflow-core/node";
+import type { Expression } from "@foresthubai/workflow-core";
+import { toast } from "../hooks/use-toast";
+import i18n from "../i18n";
+import { getAllCanvasStores } from "../stores/canvasStore";
+import { useEditorStore } from "../stores/editorStore";
+import { toFunctionInfo, type FunctionInfo } from "@foresthubai/workflow-core/function";
+import { paramKey } from "@foresthubai/workflow-core/variable";
+import { updateNodeInStore } from "./graphOperations";
+
+// ============================================================================
+// Single-Node Migration — builds the update payload for updateNodeInStore
+// ============================================================================
+
+function buildMigrationUpdate(
+  node: FunctionCallNode,
+  latest: FunctionInfo,
+): { arguments: Record<string, unknown>; functionInfo: FunctionInfo } {
+  const oldArgs = node.arguments;
+  const newArgs: Record<string, Expression | OutputBinding> = {};
+
+  // Preserve existing input expressions where uid matches; default empty otherwise.
+  // Always update dataType to match the latest function definition.
+  for (const arg of latest.arguments) {
+    const key = paramKey(arg);
+    const existing = oldArgs[key] as Expression | undefined;
+    newArgs[key] = existing ? { ...existing, dataType: arg.dataType } : { expression: "", references: [], dataType: arg.dataType };
+  }
+
+  // Preserve existing output bindings where uid matches; default emit for new returns.
+  for (const ret of latest.returns) {
+    const key = paramKey(ret);
+    const existing = oldArgs[key] as OutputBinding | undefined;
+    newArgs[key] = existing ?? { active: true, mode: "emit", name: ret.name };
+  }
+
+  return {
+    functionInfo: { ...latest },
+    arguments: newArgs,
+  };
+}
+
+// ============================================================================
+// All-Canvas Migration
+// ============================================================================
+
+/**
+ * Iterate all canvas stores and migrate any stale FunctionCallNodes
+ * to match the latest function definitions.
+ *
+ * Does NOT create undo history entries — migration is automatic and transparent.
+ * Uses updateNodeInStore for proper store reactivity.
+ */
+export function migrateFunctionCallNodes(): void {
+  const allStores = getAllCanvasStores();
+
+  // Latest call-site signatures come from the project-scoped declarations, projected
+  // to the flat snapshot form a FunctionCall stores (expressions dropped).
+  const latestFunctions: Record<string, FunctionInfo> = {};
+  for (const [id, def] of Object.entries(useEditorStore.getState().functions)) {
+    latestFunctions[id] = toFunctionInfo(def);
+  }
+
+  // Iterate all canvases and migrate stale FunctionCallNodes
+  let totalMigrated = 0;
+
+  for (const [, store] of Object.entries(allStores)) {
+    const nodes = store.getState().nodes;
+
+    for (const node of nodes) {
+      if (node.data.type !== "FunctionCall") continue;
+
+      const fnNode = node.data as FunctionCallNode;
+      const latest = latestFunctions[fnNode.functionInfo.id];
+      if (!latest) continue;
+
+      // Check if migration is needed (version or name change)
+      if (fnNode.functionInfo.version === latest.version && fnNode.functionInfo.name === latest.name) {
+        continue;
+      }
+
+      updateNodeInStore(store, node.id, buildMigrationUpdate(fnNode, latest));
+      totalMigrated++;
+    }
+  }
+
+  if (totalMigrated > 0) {
+    toast({
+      title: i18n.t("functionCallNodesMigrated"),
+      description: i18n.t("functionCallNodesMigratedDesc", { count: totalMigrated }),
+    });
+  }
+}
+
+// ============================================================================
+// Module-Level Subscription
+// ============================================================================
+
+// Automatically migrate FunctionCallNodes whenever a function declaration changes.
+// Declarations are non-undo-tracked editorStore edits, so this is a forward-only
+// reconcile — no undo can revert a definition out from under its call sites.
+let prevFunctions = useEditorStore.getState().functions;
+useEditorStore.subscribe((state) => {
+  if (state.functions === prevFunctions) return;
+  prevFunctions = state.functions;
+  migrateFunctionCallNodes();
+});

package/src/utils/modelOperations.ts

@@ -0,0 +1,55 @@
+import { ModelRegistry, type ModelType, type Model } from "@foresthubai/workflow-core/model";
+import { useEditorStore } from "../stores/editorStore";
+import { generateId } from "@foresthubai/workflow-core/id";
+import { seedDefaultArguments, uniqueName } from "./resourceHelpers";
+
+/** Default label prefix per model type. */
+const LABEL_PREFIX: Record<ModelType, string> = {
+  LLMModel: "model",
+};
+
+/** Create a new declared (custom) model of the given type. Returns the new instance. */
+export function addModel(type: ModelType): Model {
+  const id = generateId();
+  const existing = Object.values(useEditorStore.getState().models).map((m) => m.label);
+  const instance: Model = {
+    id,
+    label: uniqueName(LABEL_PREFIX[type], existing),
+    type,
+    arguments: seedDefaultArguments(ModelRegistry.getByType(type)?.parameters ?? []),
+  };
+  useEditorStore.getState().setModels((models) => ({ ...models, [id]: instance }));
+  return instance;
+}
+
+/**
+ * Apply a partial patch to a declared model. Top-level `label` and the
+ * `arguments` record merge separately. `type` is fixed at creation.
+ */
+export function updateModel(id: string, patch: { label?: string; arguments?: Record<string, unknown> }): void {
+  const key = id;
+  useEditorStore.getState().setModels((models) => {
+    const existing = models[key];
+    if (!existing) return models;
+    return {
+      ...models,
+      [key]: {
+        ...existing,
+        ...(patch.label !== undefined ? { label: patch.label } : {}),
+        ...(patch.arguments ? { arguments: { ...existing.arguments, ...patch.arguments } } : {}),
+      },
+    };
+  });
+}
+
+export function deleteModel(id: string): void {
+  const key = id;
+  useEditorStore.getState().setModels((models) => {
+    const { [key]: _drop, ...rest } = models;
+    return rest;
+  });
+  const sel = useEditorStore.getState().selection;
+  if (sel.kind === "model" && sel.id === id) {
+    useEditorStore.getState().clearSelection();
+  }
+}

package/src/utils/paramDisplay.ts

@@ -0,0 +1,71 @@
+// Presentation-only formatters for inline node display. These render domain
+// values to human-readable text; they live in the builder (not headless
+// workflow-core) because formatting for display is an editor concern.
+import type { Parameter } from "@foresthubai/workflow-core/parameter";
+import type { Reference } from "@foresthubai/workflow-core";
+import { refToLookupKey, type Variable } from "@foresthubai/workflow-core/variable";
+import type { ResolvedExpr } from "@foresthubai/workflow-core/expression";
+
+export interface ParamDisplayResult {
+  text: string;
+  isInvalid?: boolean;
+}
+
+/** Format a non-expression parameter value for inline display on the node. */
+export function formatParamDisplay(
+  param: Parameter,
+  value: unknown,
+  variables: Record<string, Variable>,
+  channelLabels?: Record<string, string>,
+  memoryLabels?: Record<string, string>,
+  modelLabels?: Record<string, string>,
+): ParamDisplayResult {
+  switch (param.type) {
+    case "variableSelect": {
+      const ref = value as Reference | undefined;
+      if (!ref?.varId) return { text: "" };
+      const v = variables[refToLookupKey(ref)];
+      return v ? { text: v.name } : { text: "unknown", isInvalid: true };
+    }
+    case "bool":
+      return { text: (value as boolean) ? "true" : "false" };
+    case "weekdays": {
+      const days = value as string[] | undefined;
+      return { text: !days?.length ? "every day" : days.join(", ") };
+    }
+    case "selection": {
+      const option = param.options.find((o) => o.value === value);
+      return { text: option?.label ?? String(value ?? "") };
+    }
+    case "memorySelect": {
+      const memoryId = value as string | undefined;
+      if (!memoryId) return { text: "" };
+      return memoryLabels?.[memoryId] ? { text: memoryLabels[memoryId] } : { text: "unknown", isInvalid: true };
+    }
+    case "channelSelect": {
+      const channelId = value as string | undefined;
+      if (!channelId) return { text: "" };
+      return channelLabels?.[channelId] ? { text: channelLabels[channelId] } : { text: "unknown", isInvalid: true };
+    }
+    case "modelSelect": {
+      // A ModelID is human-meaningful (e.g. "claude-opus-4-7"); show the catalog/
+      // custom label when known, otherwise the id itself. Staleness is surfaced
+      // by diagnostics, not inline, since the catalog isn't available headlessly.
+      const modelId = value as string | undefined;
+      if (!modelId) return { text: "" };
+      return { text: modelLabels?.[modelId] ?? modelId };
+    }
+    default:
+      return { text: String(value ?? "") };
+  }
+}
+
+/** Format an expression for display by replacing variable-reference placeholders with their names. */
+export function displayValue(expr: ResolvedExpr): string {
+  let result = expr.expression;
+  // Replace each variable reference placeholder with its name
+  expr.variables.forEach((variable) => {
+    result = result.replace(/\$\{\}/, variable?.name || "unknown");
+  });
+  return result;
+}

package/src/utils/resourceHelpers.ts

@@ -0,0 +1,32 @@
+import type { Parameter } from "@foresthubai/workflow-core/parameter";
+
+/**
+ * Build the initial `arguments` record for a new resource instance: each
+ * parameter that declares a `default` gets seeded. Defaults are `structuredClone`d
+ * so two instances never share a mutable reference (objects/arrays).
+ *
+ * Shared by the registry-backed project primitives (memory, model). Channels
+ * have conditional, activation-rule parameters and seed inside `channelOperations`
+ * instead.
+ */
+export function seedDefaultArguments(params: Parameter[]): Record<string, unknown> {
+  const args: Record<string, unknown> = {};
+  for (const param of params) {
+    if ("default" in param && param.default !== undefined) {
+      args[param.id] = structuredClone(param.default);
+    }
+  }
+  return args;
+}
+
+/**
+ * Return `desired` if it's free, otherwise append 2, 3, 4… until the result
+ * doesn't collide with `existing`.
+ */
+export function uniqueName(desired: string, existing: Iterable<string>): string {
+  const taken = existing instanceof Set ? existing : new Set(existing);
+  if (!taken.has(desired)) return desired;
+  let i = 2;
+  while (taken.has(`${desired}${i}`)) i++;
+  return `${desired}${i}`;
+}

package/src/utils/translation.ts

@@ -0,0 +1,28 @@
+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 function getNodeDescription(t: TFunction, def: NodeDefinition): string {
+  return t(`nodes.${def.type}.description`, { defaultValue: def.description });
+}
+
+export function getParamDescription(t: TFunction, translationPrefix: string, param: Parameter): string {
+  if (!param.description) return "";
+  return t(`${translationPrefix}.params.${param.id}.description`, { defaultValue: param.description });
+}
+
+export function getEdgeDescription(t: TFunction, def: { description: string }, portType: string): string {
+  return t(`edges.${portType}.description`, { defaultValue: def.description });
+}

package/src/utils/variableOperations.ts

@@ -0,0 +1,75 @@
+import { declaredVarKey, type DeclaredVariable } from "@foresthubai/workflow-core/variable";
+import type { DataType } from "@foresthubai/workflow-core";
+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: string[]): string {
+  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: string): string {
+  const store = getOrCreateCanvasStore(canvasId);
+  store.takeCheckpoint();
+  const existingNames = Object.values(store.getState().variables)
+    .filter((v): v is DeclaredVariable => v.kind === "declared")
+    .map((v) => v.name);
+  const uid = generateId();
+  const newVar: DeclaredVariable = {
+    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: string, uid: string, updates: Partial<Omit<DeclaredVariable, "kind" | "uid">>): void {
+  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: string, uid: string, dataType: DataType): void {
+  updateDeclaredVariable(canvasId, uid, { dataType, initialValue: undefined });
+}
+
+/** Delete a declared variable and clear its selection if it was open. */
+export function deleteDeclaredVariable(canvasId: string, uid: string): void {
+  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();
+  }
+}