@foresthubai/workflow-builder 0.3.0

package/src/panels/VariableConfigPanel.tsx

@@ -0,0 +1,161 @@
+import { useEffect, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { Button } from "../components/ui/button";
+import { Input } from "../components/ui/input";
+import { Separator } from "../components/ui/separator";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "../components/ui/select";
+import { ChevronRight } from "lucide-react";
+import type { DeclaredVariable } from "@foresthubai/workflow-core/variable";
+import type { DataType } from "@foresthubai/workflow-core";
+import { useEditorStore } from "../stores/editorStore";
+import { isReadOnly } from "../WorkflowBuilder";
+import { ReadOnlyBanner } from "../components/ui/readonly-banner";
+import { DeleteButton } from "../components/ui/delete-button";
+import { deleteDeclaredVariable, setDeclaredVariableType, updateDeclaredVariable } from "../utils/variableOperations";
+
+interface VariableConfigPanelProps {
+  canvasId: string;
+  variable: DeclaredVariable;
+  onClose: () => void;
+}
+
+const DATA_TYPES: DataType[] = ["int", "float", "bool", "string"];
+
+export const VariableConfigPanel = ({ canvasId, variable, onClose }: VariableConfigPanelProps) => {
+  const { t } = useTranslation();
+  const readOnly = useEditorStore((s) => isReadOnly(s.builderMode));
+
+  // Local name state mirrors the other config panels — preserves cursor position
+  // while typing and resets when a different variable is opened.
+  const [localName, setLocalName] = useState(variable.name);
+  useEffect(() => {
+    setLocalName(variable.name);
+  }, [variable.uid, variable.name]);
+
+  const isEmptyName = variable.name.trim() === "";
+
+  // The initial-value widget is chosen by dataType: declared variables store
+  // `initialValue?: unknown` and the type is enforced here at the input layer,
+  // not in the data model (untyped DOM input + JSON round-trip would defeat a
+  // discriminated union). Switching dataType clears the value.
+  const renderInitialValueInput = () => {
+    switch (variable.dataType) {
+      case "bool":
+        return (
+          <Select
+            value={variable.initialValue != null ? String(variable.initialValue) : "false"}
+            onValueChange={(v) => updateDeclaredVariable(canvasId, variable.uid, { initialValue: v === "true" })}
+          >
+            <SelectTrigger className="h-8 text-sm">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="false">false</SelectItem>
+              <SelectItem value="true">true</SelectItem>
+            </SelectContent>
+          </Select>
+        );
+      case "string":
+        return (
+          <Input
+            className="h-8 text-sm"
+            value={(variable.initialValue as string) ?? ""}
+            onChange={(e) => updateDeclaredVariable(canvasId, variable.uid, { initialValue: e.target.value })}
+            placeholder='""'
+          />
+        );
+      case "int":
+      case "float":
+        return (
+          <Input
+            type="number"
+            step={variable.dataType === "float" ? "any" : 1}
+            className="h-8 text-sm"
+            value={variable.initialValue != null ? Number(variable.initialValue) : ""}
+            onChange={(e) => {
+              const num = variable.dataType === "float" ? parseFloat(e.target.value) : parseInt(e.target.value, 10);
+              updateDeclaredVariable(canvasId, variable.uid, { initialValue: isNaN(num) ? undefined : num });
+            }}
+            placeholder="0"
+          />
+        );
+      default:
+        return null;
+    }
+  };
+
+  return (
+    <div className="p-4">
+      <div className="space-y-4">
+        <div className="flex items-center justify-between gap-2">
+          <div className="flex-1 min-w-0">
+            <div className="group flex items-center gap-1.5 rounded-md border border-transparent px-1.5 -mx-1.5 hover:border-input focus-within:border-input transition-colors">
+              <input
+                type="text"
+                title={t("variableName", "Variable name")}
+                className="font-semibold text-lg font-mono bg-transparent w-full outline-none cursor-text py-0.5"
+                value={localName}
+                readOnly={readOnly}
+                onChange={(e) => {
+                  setLocalName(e.target.value);
+                  updateDeclaredVariable(canvasId, variable.uid, { name: e.target.value });
+                }}
+              />
+            </div>
+            <p className="text-sm text-muted-foreground">
+              {t("variableDescription", "A declared variable you can read and write across this canvas")}
+            </p>
+            {isEmptyName && (
+              <p className="text-xs text-destructive mt-1">{t("variableNameRequired", "Name is required")}</p>
+            )}
+          </div>
+          <Button variant="ghost" size="icon" className="shrink-0" onClick={onClose}>
+            <ChevronRight className="h-4 w-4" />
+          </Button>
+        </div>
+
+        {readOnly && <ReadOnlyBanner />}
+
+        <Separator />
+
+        <div className={`space-y-4 ${readOnly ? "pointer-events-none opacity-60" : ""}`}>
+          <div className="space-y-1.5">
+            <label className="text-xs font-medium text-foreground/80">{t("dataType", "Data type")}</label>
+            <Select
+              value={variable.dataType}
+              onValueChange={(v) => setDeclaredVariableType(canvasId, variable.uid, v as DataType)}
+            >
+              <SelectTrigger className="h-8 text-sm">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                {DATA_TYPES.map((dt) => (
+                  <SelectItem key={dt} value={dt}>
+                    {dt}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+
+          <div className="space-y-1.5">
+            <label className="text-xs font-medium text-foreground/80">
+              {t("initialValue")}{" "}
+              <span className="font-normal text-muted-foreground">({t("optional", "optional")})</span>
+            </label>
+            {renderInitialValueInput()}
+          </div>
+        </div>
+
+        {!readOnly && (
+          <>
+            <Separator />
+            <DeleteButton onClick={() => deleteDeclaredVariable(canvasId, variable.uid)}>
+              {t("deleteVariable", "Delete variable")}
+            </DeleteButton>
+          </>
+        )}
+      </div>
+    </div>
+  );
+};

package/src/panels/VariablesPanel.tsx

@@ -0,0 +1,145 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+import { AddButton } from "../components/ui/add-button";
+import { Variable as VariableIcon } from "lucide-react";
+import { cn } from "../cn";
+import { useEditorStore } from "../stores/editorStore";
+import { isReadOnly } from "../WorkflowBuilder";
+import { useAvailableVariables } from "../hooks/useAvailableVariables";
+import { getOrCreateCanvasStore, MAIN_CANVAS_ID } from "../stores/canvasStore";
+import { type Variable, type DeclaredVariable } from "@foresthubai/workflow-core/variable";
+import { addDeclaredVariable } from "../utils/variableOperations";
+
+interface VariablesPanelProps {
+  canvasId: string;
+  onSelectNode: (nodeId: string) => void;
+}
+
+export const VariablesPanel = ({ canvasId, onSelectNode }: VariablesPanelProps) => {
+  const readOnly = useEditorStore((s) => isReadOnly(s.builderMode));
+  const { t } = useTranslation();
+  const { list: variables } = useAvailableVariables(canvasId);
+  const selection = useEditorStore((s) => s.selection);
+  const selectVariable = useEditorStore((s) => s.selectVariable);
+
+  const store = getOrCreateCanvasStore(canvasId);
+  const allVariables = store((s) => s.variables);
+  const isMainCanvas = canvasId === MAIN_CANVAS_ID;
+
+  // Extract declared variables from the unified record
+  const declaredVariables = React.useMemo(() => {
+    const result: { uid: string; var: DeclaredVariable }[] = [];
+    for (const v of Object.values(allVariables)) {
+      if (v.kind === "declared") {
+        result.push({ uid: v.uid, var: v });
+      }
+    }
+    return result;
+  }, [allVariables]);
+
+  // Create a declared variable and immediately open its config panel.
+  const handleAddVariable = () => {
+    const uid = addDeclaredVariable(canvasId);
+    selectVariable(uid);
+  };
+
+  // Filter variables into groups (each canvas is self-contained — no main-canvas leakage)
+  const functionArgs = variables.filter((v) => v.kind === "fnarg");
+  const nodeOutputs = variables.filter((v) => v.kind === "node");
+
+  const hasContent = functionArgs.length > 0 || nodeOutputs.length > 0 || declaredVariables.length > 0;
+
+  if (!hasContent) {
+    return (
+      <div className="flex flex-col items-center justify-center py-8 text-center">
+        <VariableIcon className="w-10 h-10 text-muted-foreground/50 mb-3" />
+        <p className="text-sm text-muted-foreground">{t("noVariables")}</p>
+        <p className="text-xs text-muted-foreground/70 mt-1">{t("addNodesForVariables")}</p>
+        {!readOnly && (
+          <div className="mt-3 w-full px-2">
+            <AddButton onClick={handleAddVariable}>{t("addVariable")}</AddButton>
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  const renderVariableItem = (ref: Variable, onClick?: () => void, isSelected = false) => {
+    const clickable = !!onClick;
+
+    return (
+      <div
+        key={
+          ref.kind === "node"
+            ? `${ref.nodeId}-${ref.outputId}`
+            : ref.kind === "declared"
+              ? `declared-${ref.uid}`
+              : `fnarg-${ref.uid}`
+        }
+        onClick={onClick}
+        className={cn(
+          "p-3 rounded-lg transition-all",
+          isSelected
+            ? "bg-accent shadow-md border border-primary/40 ring-1 ring-primary/40"
+            : "bg-card shadow-sm border border-border",
+          clickable ? "hover:shadow-md cursor-pointer" : "cursor-default",
+        )}
+      >
+        <div className="flex items-center justify-between">
+          <div className="flex items-center gap-2">
+            <VariableIcon className="w-4 h-4 text-muted-foreground" />
+            <span className="font-mono text-sm text-foreground">{ref.name}</span>
+          </div>
+          <span className="text-[10px] font-medium px-1.5 py-0.5 rounded border border-border/50 text-muted-foreground shrink-0">
+            {ref.dataType}
+          </span>
+        </div>
+      </div>
+    );
+  };
+
+  const SectionHeader = ({ title }: { title: string }) => (
+    <div className="flex items-center justify-between px-1 mb-2">
+      <span className="text-sm font-medium text-foreground/80">{title}</span>
+    </div>
+  );
+
+  return (
+    <div className="space-y-5">
+      {/* Function Arguments (function canvas only) — read-only, arrive by value */}
+      {!isMainCanvas && functionArgs.length > 0 && (
+        <div>
+          <SectionHeader title={t("functionArguments")} />
+          <div className="space-y-1.5">{functionArgs.map((v) => renderVariableItem(v))}</div>
+        </div>
+      )}
+
+      {/* Node Output Variables — click opens the emitting node */}
+      {nodeOutputs.length > 0 && (
+        <div>
+          <SectionHeader title={t("nodeOutputVariables")} />
+          <div className="space-y-1.5">
+            {nodeOutputs.map((v) =>
+              renderVariableItem(v, v.kind === "node" ? () => onSelectNode(v.nodeId) : undefined),
+            )}
+          </div>
+        </div>
+      )}
+
+      {/* Defined Variables — click opens the VariableConfigPanel */}
+      <div>
+        <SectionHeader title={t("definedVariables")} />
+        <div className="space-y-1.5">
+          {declaredVariables.map(({ uid, var: dv }) =>
+            renderVariableItem(
+              dv,
+              readOnly ? undefined : () => selectVariable(uid),
+              selection.kind === "variable" && selection.uid === uid,
+            ),
+          )}
+          {!readOnly && <AddButton onClick={handleAddVariable}>{t("addVariable")}</AddButton>}
+        </div>
+      </div>
+    </div>
+  );
+};

package/src/stores/canvasStore.test.ts

@@ -0,0 +1,44 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  clearAllCanvasStores,
+  getAllCanvasStores,
+  getCanvasStore,
+  getOrCreateCanvasStore,
+  subscribeCanvasRegistryChanges,
+  MAIN_CANVAS_ID,
+} from "./canvasStore";
+
+// Reset the module-level registry between tests (it's a singleton).
+afterEach(() => clearAllCanvasStores());
+
+describe("clearAllCanvasStores", () => {
+  it("re-seeds an empty main canvas and drops the rest", () => {
+    const mainBefore = getOrCreateCanvasStore(MAIN_CANVAS_ID);
+    getOrCreateCanvasStore("fn-1"); // a function canvas
+    expect(Object.keys(getAllCanvasStores())).toEqual(expect.arrayContaining([MAIN_CANVAS_ID, "fn-1"]));
+
+    clearAllCanvasStores();
+
+    const mainAfter = getCanvasStore(MAIN_CANVAS_ID);
+    expect(mainAfter).toBeDefined(); // "main always exists" invariant holds
+    expect(mainAfter).not.toBe(mainBefore); // it's a fresh, empty instance
+    expect(mainAfter?.getState().nodes).toEqual([]);
+    expect(getCanvasStore("fn-1")).toBeUndefined(); // function canvas removed
+  });
+
+  it("notifies registry listeners with main already present", () => {
+    // Regression guard: the notification must fire AFTER main is re-seeded, not
+    // while the registry is empty — otherwise subscribers (onChange / history)
+    // snapshot an empty set and never re-attach to the recreated main canvas, so
+    // edits after New/clear wouldn't mark the workflow dirty.
+    let mainPresentAtNotify = false;
+    const unsubscribe = subscribeCanvasRegistryChanges(() => {
+      mainPresentAtNotify = MAIN_CANVAS_ID in getAllCanvasStores();
+    });
+
+    clearAllCanvasStores();
+    unsubscribe();
+
+    expect(mainPresentAtNotify).toBe(true);
+  });
+});

package/src/stores/canvasStore.ts

@@ -0,0 +1,245 @@
+import { create, UseBoundStore, StoreApi } from "zustand";
+import { Node, Edge, Viewport } from "@xyflow/react";
+import { NodeCategory, type NodeData } from "@foresthubai/workflow-core/node";
+import type { EdgeData } from "@foresthubai/workflow-core/edge";
+import { history, History, type HistoryData, type MutationCount } from "../utils/history";
+import { generateId } from "@foresthubai/workflow-core/id";
+import { fnargKey, type Variable, type ApiVariable } from "@foresthubai/workflow-core/variable";
+import { computeVariablesFromNodes } from "@foresthubai/workflow-core/workflow";
+
+/**
+ * Sync fnarg:* entries in a canvas's variables to match a function's arguments.
+ * fnarg variables are *derived* from the (project-scoped) function declaration —
+ * they are not authored canvas state, so the source of truth is `editorStore`;
+ * callers pass the declaration's argument list here. Removes stale fnarg entries
+ * and adds the current ones.
+ */
+export function syncFunctionArgVariables(store: CanvasStore, args: readonly ApiVariable[]): void {
+  store.getState().setVariables((vars) => {
+    const updated = { ...vars };
+    // Remove all existing fnarg entries
+    for (const key of Object.keys(updated)) {
+      if (key.startsWith("fnarg:")) delete updated[key];
+    }
+    // Add current args
+    for (const arg of args) {
+      updated[fnargKey(arg.uid)] = { kind: "fnarg", uid: arg.uid, name: arg.name, dataType: arg.dataType };
+    }
+    return updated;
+  });
+}
+
+export { MAIN_CANVAS_ID } from "@foresthubai/workflow-core/workflow";
+import { MAIN_CANVAS_ID } from "@foresthubai/workflow-core/workflow";
+const HISTORY_LIMIT = 50 as const;
+
+// ============================================================================
+// Canvas Registry Change Notification System
+// ============================================================================
+
+// Listeners notified when the *set* of canvas stores changes (a store is created,
+// deleted, or the whole registry is cleared/retained). This is decoupled from
+// function definitions — those now live in editorStore. Its sole consumer is
+// WorkflowBuilder, which re-subscribes to every live store's mutationCount/history
+// when the set changes so newly created (or dropped) canvases are watched.
+const canvasRegistryListeners = new Set<() => void>();
+
+// Notify subscribers that the canvas store set changed.
+export function notifyCanvasRegistryChange(): void {
+  canvasRegistryListeners.forEach((listener) => listener());
+}
+
+// Subscribe to canvas registry (store set) changes.
+export function subscribeCanvasRegistryChanges(listener: () => void): () => void {
+  canvasRegistryListeners.add(listener);
+  return () => canvasRegistryListeners.delete(listener);
+}
+
+// ============================================================================
+// Canvas Store Registry
+// ============================================================================
+
+// Registry - Module-level map of independent store instances
+const canvasStores = new Map<string, CanvasStore>();
+
+canvasStores.set(MAIN_CANVAS_ID, createCanvasStore()); // Always exists
+
+export interface CanvasState {
+  nodes: Node<NodeData>[];
+  edges: Edge<EdgeData>[];
+  // Unified variable record: node outputs (nodeId:outputId), declared (declared:uid), fn args (fnarg:uid).
+  // fnarg:* entries are derived from the project-scoped function declaration (editorStore) via
+  // syncFunctionArgVariables — they are not authored here.
+  variables: Record<string, Variable>;
+  // Session-only pan/zoom of the canvas viewport. View state, NOT workflow content:
+  // kept out of partialize (no history/serialization) so it never enters the contract,
+  // and lost on reload like selection. Persisted across tab switches so re-entering a
+  // canvas restores its view via defaultViewport instead of a post-paint fitView jump.
+  // null until first visited (then fitView seeds it).
+  viewport: Viewport | null;
+
+  setNodes: (updater: (nodes: Node<NodeData>[]) => Node<NodeData>[]) => void;
+  setEdges: (updater: (edges: Edge<EdgeData>[]) => Edge<EdgeData>[]) => void;
+  setVariables: (updater: (variables: Record<string, Variable>) => Record<string, Variable>) => void;
+  setViewport: (viewport: Viewport) => void;
+  /**
+   * Visual-only: set ReactFlow selected flags on nodes AND edges in one atomic update.
+   * This will call a single re-render and a single onSelectionChange callback.
+   * Not an update of domain state, so it can be used in read-only mode.
+   */
+  setRFselect: (nodeIds: string[], edgeIds: string[]) => void;
+  initialize: (nodes: Node<NodeData>[], edges: Edge<EdgeData>[]) => void;
+}
+
+// Canvas store is a Zustand store + history (undo/redo capabilities) + mutation count.
+export type CanvasStore = UseBoundStore<StoreApi<CanvasState & MutationCount>> & History;
+
+function createCanvasStore(): CanvasStore {
+  // Create base store with history middleware
+  const baseStore = create(
+    history<CanvasState>({
+      limit: HISTORY_LIMIT,
+      partialize: (state) => ({
+        nodes: state.nodes,
+        edges: state.edges,
+        variables: state.variables,
+      }),
+      equality: (before, after) => before.nodes === after.nodes && before.edges === after.edges && before.variables === after.variables,
+    })((set) => ({
+      nodes: [],
+      edges: [],
+      variables: {},
+      viewport: null,
+
+      setNodes: (updater) =>
+        set((state) => {
+          const next = updater(state.nodes);
+          if (next === state.nodes) return state;
+          return { nodes: next };
+        }),
+
+      setEdges: (updater) =>
+        set((state) => {
+          const next = updater(state.edges);
+          if (next === state.edges) return state;
+          return { edges: next };
+        }),
+
+      setVariables: (updater) =>
+        set((state) => {
+          const next = updater(state.variables);
+          if (next === state.variables) return state;
+          return { variables: next };
+        }),
+
+      // View-only — outside partialize, so it neither takes a checkpoint nor bumps
+      // mutationCount (no spurious dirty dot / onChange from panning).
+      setViewport: (viewport) => set({ viewport }),
+
+      setRFselect: (nodeIds, edgeIds) => {
+        const nodeIdSet = new Set(nodeIds);
+        const edgeIdSet = new Set(edgeIds);
+        set((state) => ({
+          nodes: state.nodes.map((n) => {
+            const shouldSelect = nodeIdSet.has(n.id);
+            return n.selected === shouldSelect ? n : { ...n, selected: shouldSelect };
+          }),
+          edges: state.edges.map((e) => {
+            const shouldSelect = edgeIdSet.has(e.id);
+            return e.selected === shouldSelect ? e : { ...e, selected: shouldSelect };
+          }),
+        }));
+      },
+
+      initialize: (nodes, edges) => {
+        // Build node-output variables. fnarg entries (for function canvases) are
+        // seeded separately via syncFunctionArgVariables from the editorStore
+        // declaration, since the canvas store no longer owns the signature.
+        // computeVariablesFromNodes is the core (NodeData[]) variant; peel the
+        // React Flow wrapper at the call site.
+        const vars: Record<string, Variable> = computeVariablesFromNodes(nodes.map((n) => n.data));
+        set({ nodes, edges, variables: vars });
+      },
+    })),
+  );
+
+  // Bind history methods from state to CanvasStore object
+  // This makes them accessible as store.undo() instead of store.getState().undo()
+  const store = baseStore as unknown as CanvasStore;
+
+  store.takeCheckpoint = () => baseStore.getState().takeCheckpoint();
+  store.withCheckpoint = <R>(operation: () => R): R => baseStore.getState().withCheckpoint(operation);
+  store.undo = () => baseStore.getState().undo();
+  store.redo = () => baseStore.getState().redo();
+  store.clearHistory = () => baseStore.getState().clearHistory();
+  store.canUndo = () => baseStore.getState().canUndo();
+  store.canRedo = () => baseStore.getState().canRedo();
+  store.exportHistory = () => baseStore.getState().exportHistory();
+  store.importHistory = (data: HistoryData) => baseStore.getState().importHistory(data);
+
+  return store;
+}
+
+// ============================================================================
+// Store Access API
+// ============================================================================
+
+// Get a canvas store by ID, or undefined if not exists
+export function getCanvasStore(canvasId: string): CanvasStore | undefined {
+  return canvasStores.get(canvasId);
+}
+
+// Get or create a canvas store by ID
+// Non-main canvases (function canvases) are initialized with an OnFunctionCall node
+export function getOrCreateCanvasStore(canvasId: string): CanvasStore {
+  if (!canvasStores.has(canvasId)) {
+    const store = createCanvasStore();
+
+    // Initialize function canvases with OnFunctionCall trigger node
+    if (canvasId !== MAIN_CANVAS_ID) {
+      const nodeId = generateId();
+      const initialNode: Node<NodeData> = {
+        id: nodeId,
+        type: NodeCategory.Trigger,
+        position: { x: 100, y: 100 },
+        data: {
+          id: nodeId,
+          type: "OnFunctionCall",
+          arguments: {},
+        } as NodeData,
+      };
+      store.getState().initialize([initialNode], []);
+    }
+
+    canvasStores.set(canvasId, store);
+  }
+  return canvasStores.get(canvasId)!;
+}
+
+// Get all canvas stores
+export function getAllCanvasStores(): Record<string, CanvasStore> {
+  const result: Record<string, CanvasStore> = {};
+  canvasStores.forEach((store, id) => {
+    result[id] = store;
+  });
+  return result;
+}
+
+// Delete a canvas store by ID. Cannot delete the main canvas.
+export function deleteCanvasStore(canvasId: string): void {
+  if (canvasId === MAIN_CANVAS_ID) return;
+  canvasStores.delete(canvasId);
+  notifyCanvasRegistryChange();
+}
+
+// Clear all canvas stores, including the main canvas.
+export function clearAllCanvasStores(): void {
+  canvasStores.clear();
+  // Re-seed an empty main canvas BEFORE notifying. Two reasons: it preserves the
+  // "main always exists" invariant, and — critically — subscribers re-subscribe to
+  // the live store set on this notification. If main were absent here, they'd
+  // snapshot an empty registry and never attach to the lazily-recreated main, so
+  // edits after New/clear wouldn't fire onChange (no dirty dot, stale undo state).
+  canvasStores.set(MAIN_CANVAS_ID, createCanvasStore());
+  notifyCanvasRegistryChange();
+}

package/src/stores/debugStore.ts

@@ -0,0 +1,74 @@
+import { create } from "zustand";
+
+// ---------------------------------------------------------------------------
+// Session Phase State Machine
+// ---------------------------------------------------------------------------
+
+export type DebugSessionPhase =
+  | { status: "inactive" }
+  | { status: "building"; abortController: AbortController }
+  | { status: "idle"; sessionId: string }
+  | { status: "paused"; sessionId: string; cursorNodeId: string }
+  | { status: "stepping"; sessionId: string; cursorNodeId: string }
+  | { status: "error"; message: string };
+
+// ---------------------------------------------------------------------------
+// Console
+// ---------------------------------------------------------------------------
+
+export interface ConsoleEntry {
+  id: number;
+  timestamp: number;
+  type: "message" | "error" | "system";
+  text: string;
+}
+
+// ---------------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------------
+
+interface DebugState {
+  phase: DebugSessionPhase;
+  /** Workflow variable values — client-owned, sent with each step request */
+  context: Record<string, unknown>;
+  console: ConsoleEntry[];
+  nextConsoleId: number;
+
+  // Actions
+  setPhase: (phase: DebugSessionPhase) => void;
+  setContext: (ctx: Record<string, unknown>) => void;
+  updateContextVar: (key: string, value: unknown) => void;
+  appendConsole: (type: ConsoleEntry["type"], text: string) => void;
+  clearConsole: () => void;
+  reset: () => void;
+}
+
+export const useDebugStore = create<DebugState>((set) => ({
+  phase: { status: "inactive" },
+  context: {},
+  console: [],
+  nextConsoleId: 0,
+
+  setPhase: (phase) => set({ phase }),
+
+  setContext: (ctx) => set({ context: ctx }),
+
+  updateContextVar: (key, value) =>
+    set((s) => ({ context: { ...s.context, [key]: value } })),
+
+  appendConsole: (type, text) =>
+    set((s) => ({
+      console: [...s.console, { id: s.nextConsoleId, timestamp: Date.now(), type, text }],
+      nextConsoleId: s.nextConsoleId + 1,
+    })),
+
+  clearConsole: () => set({ console: [], nextConsoleId: 0 }),
+
+  reset: () =>
+    set({
+      phase: { status: "inactive" },
+      context: {},
+      console: [],
+      nextConsoleId: 0,
+    }),
+}));