@flowdrop/flowdrop 1.14.0 → 2.0.0-beta.1

package/dist/stores/workflowStore.svelte.d.ts

@@ -1,283 +1,248 @@
 /**
  * Workflow Store for FlowDrop (Svelte 5 Runes)
  *
- * Provides global state management for workflows with dirty state tracking
- * and undo/redo history integration.
+ * Provides per-instance state management for workflows with dirty state
+ * tracking and undo/redo history integration.
  *
- * **Important: Single-instance only.** This store uses module-level singletons.
- * Only one FlowDrop editor instance per page is supported. Mounting multiple
- * FlowDrop editors on the same page will cause them to share workflow state.
+ * The reactive state lives in the {@link WorkflowStore} class — one per
+ * FlowDrop instance, created by `createFlowDropInstance()` and resolved in
+ * components via `getInstance().workflow`.
  *
  * @module stores/workflowStore
  */
 import type { Workflow, WorkflowNode, WorkflowEdge } from '../types';
 import type { WorkflowChangeType } from '../types/events.js';
-type WorkflowMetadata = NonNullable<Workflow['metadata']>;
+import type { HistoryService } from '../services/historyService.js';
+type WorkflowMetadata = Workflow['metadata'];
 /**
- * Get the current workflow store value reactively
- *
- * @returns The current workflow or null
- */
-export declare function getWorkflowStore(): Workflow | null;
-/**
- * Get the current dirty state reactively
- *
- * Reads both _editVersion and _savedVersion, so Svelte tracks them
- * as reactive dependencies — any component using this will re-render
- * when dirty state changes.
- *
- * @returns true if there are unsaved changes
- */
-export declare function getIsDirty(): boolean;
-/**
- * Get the workflow ID reactively
- *
- * @returns The workflow ID or null
- */
-export declare function getWorkflowId(): string | null;
-/**
- * Get the workflow name reactively
- *
- * @returns The workflow name or 'Untitled Workflow'
- */
-export declare function getWorkflowName(): string;
-/**
- * Get the workflow nodes reactively
- *
- * @returns Array of workflow nodes
- */
-export declare function getWorkflowNodes(): WorkflowNode[];
-/**
- * Get the workflow edges reactively
- *
- * @returns Array of workflow edges
+ * Loosely-typed shape a workflow may arrive in before healing — a 1.x document
+ * may have no `metadata`, or metadata carrying the legacy `version` key instead
+ * of `schemaVersion`.
  */
-export declare function getWorkflowEdges(): WorkflowEdge[];
-/**
- * Get the workflow metadata reactively
- *
- * @returns The workflow metadata with defaults
- */
-export declare function getWorkflowMetadata(): WorkflowMetadata;
-/**
- * Get the current workflow format reactively
- *
- * @returns The workflow format string
- */
-export declare function getWorkflowFormat(): string;
-/**
- * Get workflow change summary reactively (useful for triggering saves)
- *
- * @returns Object with nodes, edges, and name
- */
-export declare function getWorkflowChanged(): {
-    nodes: WorkflowNode[];
-    edges: WorkflowEdge[];
-    name: string;
+type LegacyWorkflow = Omit<Workflow, 'metadata'> & {
+    metadata?: (Partial<WorkflowMetadata> & {
+        version?: string;
+    }) | null;
 };
 /**
- * Get workflow validation state reactively
+ * Normalize workflow metadata at load time (the only back-compat path we keep,
+ * mirroring the storage-key migration in commit 8fab9157).
  *
- * @returns Validation info object
- */
-export declare function getWorkflowValidation(): {
-    hasNodes: boolean;
-    hasEdges: boolean;
-    nodeCount: number;
-    edgeCount: number;
-    isValid: boolean;
-};
-/**
- * Get workflow metadata change summary reactively
+ * Rules:
+ * - missing `metadata` → `buildMetadata(undefined)` (fresh required defaults)
+ * - legacy `version` key present → copied to `schemaVersion` when absent, then
+ *   the legacy key is dropped
  *
- * @returns Metadata change info
+ * Idempotent: re-running on an already-healed workflow returns equivalent
+ * metadata (round-trip stable).
  */
-export declare function getWorkflowMetadataChanged(): {
-    createdAt: string;
-    updatedAt: string;
-    version: string;
-};
+export declare function normalizeWorkflowMetadata(workflow: LegacyWorkflow): Workflow;
 /**
- * Get connected handles reactively
- *
- * Provides a Set of all handle IDs that are currently connected to edges.
- * Used by node components to implement hideUnconnectedHandles functionality.
+ * Mutation actions for a {@link WorkflowStore}.
  *
- * @example
- * ```typescript
- * import { getConnectedHandles } from './workflowStore.svelte.js';
- *
- * // Check if a specific handle is connected
- * const isConnected = getConnectedHandles().has('node-1-input-data');
- * ```
+ * Bound facade — safe to detach (`onclick={fd.workflow.actions.undo}`)
+ * because every entry is bound to its store in the constructor.
  */
-export declare function getConnectedHandles(): Set<string>;
-/**
- * Set the dirty state change callback
- *
- * @param callback - Function to call when dirty state changes
- */
-export declare function setOnDirtyStateChange(callback: ((isDirty: boolean) => void) | null): void;
-/**
- * Set the workflow change callback
- *
- * @param callback - Function to call when workflow changes
- */
-export declare function setOnWorkflowChange(callback: ((workflow: Workflow, changeType: WorkflowChangeType) => void) | null): void;
-/**
- * Mark the current workflow state as saved.
- *
- * Captures the current edit version so isDirty becomes false.
- * Call this after a successful backend save.
- */
-export declare function markAsSaved(): void;
-/**
- * Check if there are unsaved changes (non-reactive version for plain TS)
- *
- * @returns true if there are unsaved changes
- */
-export declare function isDirty(): boolean;
-/**
- * Get the current edit version.
- *
- * Use this for the save verification protocol:
- * 1. Before save: `const v = getEditVersion()`
- * 2. Include `v` in the save request payload
- * 3. Backend echoes `v` in the response
- * 4. If echoed version matches: `markAsSaved()`
- * 5. If not: the save didn't persist the version you submitted — reset from backend response
- *
- * @returns The current monotonic edit version
- */
-export declare function getEditVersion(): number;
-/**
- * Enable or disable history recording
- *
- * Useful for bulk operations where you don't want individual history entries.
- *
- * @param enabled - Whether history should be recorded
- */
-export declare function setHistoryEnabled(enabled: boolean): void;
-/**
- * Check if history recording is enabled
- *
- * @returns true if history is being recorded
- */
-export declare function isHistoryEnabled(): boolean;
-/**
- * Set the restoring from history flag
- *
- * Used internally by the history store when performing undo/redo.
- *
- * @param restoring - Whether we're currently restoring from history
- */
-export declare function setRestoringFromHistory(restoring: boolean): void;
-/**
- * Get the current workflow (non-reactive version for plain TS)
- *
- * @returns The current workflow or null
- */
-export declare function getWorkflow(): Workflow | null;
+export interface WorkflowStoreActions {
+    initialize: (workflow: Workflow) => void;
+    updateWorkflow: (workflow: Workflow) => void;
+    restoreFromHistory: (workflow: Workflow) => void;
+    updateNodes: (nodes: WorkflowNode[]) => void;
+    updateEdges: (edges: WorkflowEdge[]) => void;
+    updateName: (name: string) => void;
+    addNode: (node: WorkflowNode) => void;
+    removeNode: (nodeId: string) => void;
+    addEdge: (edge: WorkflowEdge) => void;
+    removeEdge: (edgeId: string) => void;
+    updateNode: (nodeId: string, updates: Partial<WorkflowNode>) => void;
+    clear: () => void;
+    updateMetadata: (metadata: Partial<Workflow['metadata']>) => void;
+    batchUpdate: (updates: {
+        nodes?: WorkflowNode[];
+        edges?: WorkflowEdge[];
+        name?: string;
+        description?: string;
+        metadata?: Partial<Workflow['metadata']>;
+        config?: Record<string, unknown>;
+    }) => void;
+    swapNode: (updates: {
+        nodes: WorkflowNode[];
+        edges: WorkflowEdge[];
+        description?: string;
+    }) => void;
+    pushHistory: (description?: string, workflow?: Workflow) => void;
+}
 /**
- * Actions for updating the workflow
+ * Per-instance workflow state with dirty tracking and history integration.
  *
- * All actions that modify the workflow will trigger dirty state updates
- * and emit change events.
+ * All reads go through getters backed by `$state`, so reading them inside a
+ * component template or `$derived` tracks reactively, exactly like the
+ * legacy module-level functions did.
  */
-export declare const workflowActions: {
+export declare class WorkflowStore {
+    #private;
+    /** Bound mutation facade — see {@link WorkflowStoreActions}. */
+    readonly actions: WorkflowStoreActions;
+    constructor(history: HistoryService);
+    /** The current workflow, or null when none is loaded. */
+    get current(): Workflow | null;
     /**
-     * Initialize workflow (from load or new)
+     * Whether there are unsaved changes.
      *
-     * This sets the initial saved snapshot, clears dirty state, and initializes history.
-     */
-    initialize: (workflow: Workflow) => void;
-    /**
-     * Update the entire workflow
+     * Reads both #editVersion and #savedVersion, so Svelte tracks them as
+     * reactive dependencies — any component using this re-renders when dirty
+     * state changes.
+     */
+    get isDirty(): boolean;
+    /** The workflow ID, or null. */
+    get id(): string | null;
+    /** The workflow name, or 'Untitled Workflow'. */
+    get name(): string;
+    /** The workflow nodes. */
+    get nodes(): WorkflowNode[];
+    /** The workflow edges. */
+    get edges(): WorkflowEdge[];
+    /** The workflow metadata, with defaults. */
+    get metadata(): WorkflowMetadata;
+    /** The workflow format string. */
+    get format(): string;
+    /** Workflow change summary (useful for triggering saves). */
+    get changeSummary(): {
+        nodes: WorkflowNode[];
+        edges: WorkflowEdge[];
+        name: string;
+    };
+    /** Workflow validation state. */
+    get validation(): {
+        hasNodes: boolean;
+        hasEdges: boolean;
+        nodeCount: number;
+        edgeCount: number;
+        isValid: boolean;
+    };
+    /** Workflow metadata change summary. */
+    get metadataChangeSummary(): {
+        createdAt: string;
+        updatedAt: string;
+        schemaVersion: string;
+    };
+    /**
+     * Set of all handle IDs currently connected to edges.
      *
-     * Note: This is typically called from SvelteFlow sync and should not push to history
-     * for every small change. History is pushed by specific actions or drag handlers.
+     * Used by node components to implement hideUnconnectedHandles.
      */
-    updateWorkflow: (workflow: Workflow) => void;
+    get connectedHandles(): Set<string>;
     /**
-     * Restore workflow from history (undo/redo)
+     * The current monotonic edit version.
      *
-     * This bypasses history recording to prevent recursive loops.
+     * Use this for the save verification protocol:
+     * 1. Before save: `const v = store.editVersion`
+     * 2. Include `v` in the save request payload
+     * 3. Backend echoes `v` in the response
+     * 4. If echoed version matches: `store.markAsSaved()`
+     * 5. If not: the save didn't persist the version you submitted — reset from backend response
+     */
+    get editVersion(): number;
+    /** Whether history recording is enabled. */
+    get historyEnabled(): boolean;
+    /** Enable or disable history recording (e.g. for bulk operations). */
+    set historyEnabled(enabled: boolean);
+    /** Set the dirty state change callback. */
+    setOnDirtyStateChange(callback: ((isDirty: boolean) => void) | null): void;
+    /** Set the workflow change callback. */
+    setOnWorkflowChange(callback: ((workflow: Workflow, changeType: WorkflowChangeType) => void) | null): void;
+    /**
+     * Mark the current workflow state as saved.
+     *
+     * Captures the current edit version so isDirty becomes false.
+     * Call this after a successful backend save.
      */
-    restoreFromHistory: (workflow: Workflow) => void;
+    markAsSaved(): void;
     /**
-     * Update nodes
+     * Set the restoring from history flag.
+     *
+     * Used internally by the history store when performing undo/redo.
      */
-    updateNodes: (nodes: WorkflowNode[]) => void;
+    setRestoringFromHistory(restoring: boolean): void;
     /**
-     * Update edges
+     * Initialize workflow (from load or new).
+     *
+     * This sets the initial saved snapshot, clears dirty state, and initializes history.
      */
-    updateEdges: (edges: WorkflowEdge[]) => void;
+    initialize(workflow: Workflow): void;
     /**
-     * Update workflow name
+     * Update the entire workflow.
+     *
+     * Note: This is typically called from SvelteFlow sync and should not push to history
+     * for every small change. History is pushed by specific actions or drag handlers.
      */
-    updateName: (name: string) => void;
+    updateWorkflow(workflow: Workflow): void;
     /**
-     * Add a node
+     * Restore workflow from history (undo/redo).
+     *
+     * This bypasses history recording to prevent recursive loops.
      */
-    addNode: (node: WorkflowNode) => void;
-    /**
-     * Remove a node
+    restoreFromHistory(workflow: Workflow): void;
+    /** Update nodes. */
+    updateNodes(nodes: WorkflowNode[]): void;
+    /** Update edges. */
+    updateEdges(edges: WorkflowEdge[]): void;
+    /** Update workflow name. */
+    updateName(name: string): void;
+    /** Add a node. */
+    addNode(node: WorkflowNode): void;
+    /**
+     * Remove a node.
      *
      * This is an atomic operation that also removes connected edges.
      * A single undo will restore both the node and its edges.
      */
-    removeNode: (nodeId: string) => void;
-    /**
-     * Add an edge
-     */
-    addEdge: (edge: WorkflowEdge) => void;
-    /**
-     * Remove an edge
-     */
-    removeEdge: (edgeId: string) => void;
+    removeNode(nodeId: string): void;
+    /** Add an edge. */
+    addEdge(edge: WorkflowEdge): void;
+    /** Remove an edge. */
+    removeEdge(edgeId: string): void;
     /**
-     * Update a specific node
+     * Update a specific node.
      *
      * Used for config changes. Pushes to history for undo support.
      */
-    updateNode: (nodeId: string, updates: Partial<WorkflowNode>) => void;
+    updateNode(nodeId: string, updates: Partial<WorkflowNode>): void;
     /**
-     * Clear the workflow
+     * Clear the workflow.
      *
      * Resets the workflow and clears history.
      */
-    clear: () => void;
-    /**
-     * Update workflow metadata
-     */
-    updateMetadata: (metadata: Partial<Workflow["metadata"]>) => void;
+    clear(): void;
+    /** Update workflow metadata. */
+    updateMetadata(metadata: Partial<Workflow['metadata']>): void;
     /**
-     * Batch update nodes and edges
+     * Batch update nodes and edges.
      *
      * Useful for complex operations that update multiple things at once.
      * Creates a single history entry for the entire batch.
      */
-    batchUpdate: (updates: {
+    batchUpdate(updates: {
         nodes?: WorkflowNode[];
         edges?: WorkflowEdge[];
         name?: string;
         description?: string;
-        metadata?: Partial<Workflow["metadata"]>;
+        metadata?: Partial<Workflow['metadata']>;
         config?: Record<string, unknown>;
-    }) => void;
+    }): void;
     /**
      * Swap a node — atomically replaces nodes and edges with a descriptive history entry.
      *
      * Unlike batchUpdate, this uses `"node_swap"` as the change type and
      * records a meaningful description for the undo history.
      */
-    swapNode: (updates: {
+    swapNode(updates: {
         nodes: WorkflowNode[];
         edges: WorkflowEdge[];
         description?: string;
-    }) => void;
+    }): void;
     /**
-     * Push current state to history manually
+     * Push current state to history manually.
      *
      * Use this before operations that modify the workflow through other means
      * (e.g., drag operations handled by SvelteFlow directly).
@@ -285,6 +250,6 @@ export declare const workflowActions: {
      * @param description - Description of the upcoming change
      * @param workflow - Optional workflow to push (uses store state if not provided)
      */
-    pushHistory: (description?: string, workflow?: Workflow) => void;
-};
+    pushHistory(description?: string, workflow?: Workflow): void;
+}
 export {};