@flowdrop/flowdrop 1.4.0 → 1.6.0

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

@@ -10,9 +10,9 @@
  *
  * @module stores/workflowStore
  */
-import type { Workflow, WorkflowNode, WorkflowEdge } from "../types";
-import type { WorkflowChangeType } from "../types/events.js";
-type WorkflowMetadata = NonNullable<Workflow["metadata"]>;
+import type { Workflow, WorkflowNode, WorkflowEdge } from '../types';
+import type { WorkflowChangeType } from '../types/events.js';
+type WorkflowMetadata = NonNullable<Workflow['metadata']>;
 /**
  * Get the current workflow store value reactively
  *
@@ -22,6 +22,10 @@ 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;
@@ -121,9 +125,10 @@ export declare function setOnDirtyStateChange(callback: ((isDirty: boolean) => v
  */
 export declare function setOnWorkflowChange(callback: ((workflow: Workflow, changeType: WorkflowChangeType) => void) | null): void;
 /**
- * Mark the current workflow state as saved
+ * Mark the current workflow state as saved.
  *
- * Clears the dirty state by updating the saved snapshot.
+ * Captures the current edit version so isDirty becomes false.
+ * Call this after a successful backend save.
  */
 export declare function markAsSaved(): void;
 /**
@@ -132,6 +137,19 @@ export declare function markAsSaved(): void;
  * @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
  *
@@ -246,6 +264,17 @@ export declare const workflowActions: {
         description?: string;
         metadata?: Partial<Workflow["metadata"]>;
     }) => 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: {
+        nodes: WorkflowNode[];
+        edges: WorkflowEdge[];
+        description?: string;
+    }) => void;
     /**
      * Push current state to history manually
      *

package/dist/stores/workflowStore.svelte.js

@@ -10,14 +10,14 @@
  *
  * @module stores/workflowStore
  */
-import { DEFAULT_WORKFLOW_FORMAT } from "../types/index.js";
-import { historyService } from "../services/historyService.js";
+import { DEFAULT_WORKFLOW_FORMAT } from '../types/index.js';
+import { historyService } from '../services/historyService.js';
 /**
  * Safely build updated workflow metadata, providing defaults for required fields.
  */
 function buildMetadata(existing, updates) {
     return {
-        version: existing?.version ?? "1.0",
+        version: existing?.version ?? '1.0',
         createdAt: existing?.createdAt ?? new Date().toISOString(),
         updatedAt: new Date().toISOString(),
         author: existing?.author,
@@ -25,7 +25,7 @@ function buildMetadata(existing, updates) {
         versionId: existing?.versionId,
         updateNumber: existing?.updateNumber,
         format: existing?.format,
-        ...updates,
+        ...updates
     };
 }
 // =========================================================================
@@ -34,21 +34,23 @@ function buildMetadata(existing, updates) {
 /** Global workflow state */
 let workflowState = $state(null);
 // =========================================================================
-// Dirty State Tracking
+// Dirty State Tracking (Version Counter)
 // =========================================================================
 /**
- * State for tracking if there are unsaved changes
+ * Monotonic edit version — bumps on every mutation action.
  *
- * This is set to true whenever the workflow changes after initialization.
- * It can be reset to false by calling markAsSaved().
+ * Used for two purposes:
+ * 1. O(1) dirty detection: isDirty = _editVersion !== _savedVersion
+ * 2. Save verification protocol: include the version in the save request,
+ *    backend echoes it back. If the echoed version doesn't match, the save
+ *    didn't persist the version the client submitted.
  */
-let isDirtyState = $state(false);
+let _editVersion = $state(0);
 /**
- * Snapshot of the workflow when it was last saved
- *
- * Used to compare current state with saved state.
+ * Edit version captured at the last successful save.
+ * When _editVersion === _savedVersion, the workflow is clean.
  */
-let savedSnapshot = null;
+let _savedVersion = $state(0);
 /**
  * Callback for dirty state changes
  *
@@ -87,10 +89,14 @@ export function getWorkflowStore() {
 /**
  * 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 function getIsDirty() {
-    return isDirtyState;
+    return _editVersion !== _savedVersion;
 }
 /**
  * Get the workflow ID reactively
@@ -106,7 +112,7 @@ export function getWorkflowId() {
  * @returns The workflow name or 'Untitled Workflow'
  */
 export function getWorkflowName() {
-    return workflowState?.name ?? "Untitled Workflow";
+    return workflowState?.name ?? 'Untitled Workflow';
 }
 /**
  * Get the workflow nodes reactively
@@ -131,11 +137,11 @@ export function getWorkflowEdges() {
  */
 export function getWorkflowMetadata() {
     return (workflowState?.metadata ?? {
-        version: "1.0.0",
+        version: '1.0.0',
         createdAt: new Date().toISOString(),
         updatedAt: new Date().toISOString(),
         versionId: `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
-        updateNumber: 0,
+        updateNumber: 0
     });
 }
 /**
@@ -155,7 +161,7 @@ export function getWorkflowChanged() {
     return {
         nodes: getWorkflowNodes(),
         edges: getWorkflowEdges(),
-        name: getWorkflowName(),
+        name: getWorkflowName()
     };
 }
 /**
@@ -171,7 +177,7 @@ export function getWorkflowValidation() {
         hasEdges: edges.length > 0,
         nodeCount: nodes.length,
         edgeCount: edges.length,
-        isValid: nodes.length > 0 && edges.length >= 0,
+        isValid: nodes.length > 0 && edges.length >= 0
     };
 }
 /**
@@ -184,7 +190,7 @@ export function getWorkflowMetadataChanged() {
     return {
         createdAt: metadata.createdAt,
         updatedAt: metadata.updatedAt,
-        version: metadata.version ?? "1.0.0",
+        version: metadata.version ?? '1.0.0'
     };
 }
 /**
@@ -239,53 +245,21 @@ export function setOnWorkflowChange(callback) {
 // Internal Helpers
 // =========================================================================
 /**
- * Create a snapshot of the workflow for comparison
- *
- * @param workflow - The workflow to snapshot
- * @returns A JSON string representation for comparison
- */
-function createSnapshot(workflow) {
-    if (!workflow)
-        return null;
-    // Only include the parts that matter for "dirty" detection
-    const toSnapshot = {
-        name: workflow.name,
-        description: workflow.description,
-        nodes: workflow.nodes.map((n) => ({
-            id: n.id,
-            position: n.position,
-            data: {
-                label: n.data.label,
-                config: n.data.config,
-            },
-        })),
-        edges: workflow.edges.map((e) => ({
-            id: e.id,
-            source: e.source,
-            target: e.target,
-            sourceHandle: e.sourceHandle,
-            targetHandle: e.targetHandle,
-        })),
-    };
-    return JSON.stringify(toSnapshot);
-}
-/**
- * Update dirty state based on current workflow
- *
- * Compares current workflow with saved snapshot.
+ * Bump the edit version and notify dirty state change if needed.
+ * Called by every mutation action.
  */
-function updateDirtyState() {
-    const currentSnapshot = createSnapshot(workflowState);
-    const newIsDirty = currentSnapshot !== savedSnapshot;
-    if (newIsDirty !== isDirtyState) {
-        isDirtyState = newIsDirty;
+function bumpVersion() {
+    _editVersion++;
+    // Dirty state just flipped from clean → dirty
+    if (_editVersion - 1 === _savedVersion) {
         if (onDirtyStateChangeCallback) {
-            onDirtyStateChangeCallback(newIsDirty);
+            onDirtyStateChangeCallback(true);
         }
     }
 }
 /**
- * Mark the workflow change and update dirty state
+ * Notify external listeners of a workflow change.
+ * Does NOT bump the version — callers that mutate must call bumpVersion() explicitly.
  *
  * @param changeType - The type of change that occurred
  */
@@ -293,17 +267,17 @@ function notifyWorkflowChange(changeType) {
     if (workflowState && onWorkflowChangeCallback) {
         onWorkflowChangeCallback(workflowState, changeType);
     }
-    updateDirtyState();
 }
 /**
- * Mark the current workflow state as saved
+ * Mark the current workflow state as saved.
  *
- * Clears the dirty state by updating the saved snapshot.
+ * Captures the current edit version so isDirty becomes false.
+ * Call this after a successful backend save.
  */
 export function markAsSaved() {
-    savedSnapshot = createSnapshot(workflowState);
-    isDirtyState = false;
-    if (onDirtyStateChangeCallback) {
+    const wasDirty = _editVersion !== _savedVersion;
+    _savedVersion = _editVersion;
+    if (wasDirty && onDirtyStateChangeCallback) {
         onDirtyStateChangeCallback(false);
     }
 }
@@ -313,7 +287,22 @@ export function markAsSaved() {
  * @returns true if there are unsaved changes
  */
 export function isDirty() {
-    return isDirtyState;
+    return _editVersion !== _savedVersion;
+}
+/**
+ * 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 function getEditVersion() {
+    return _editVersion;
 }
 /**
  * Enable or disable history recording
@@ -390,7 +379,7 @@ function hasWorkflowDataChanged(currentWorkflow, newNodes, newEdges) {
         if (currentNode.position.x !== newNode.position.x ||
             currentNode.position.y !== newNode.position.y)
             return true;
-        if (JSON.stringify(currentNode.data) !== JSON.stringify(newNode.data))
+        if (currentNode.data !== newNode.data)
             return true;
     }
     // Check if edges have changed
@@ -403,8 +392,7 @@ function hasWorkflowDataChanged(currentWorkflow, newNodes, newEdges) {
             return true;
         if (currentEdge.id !== newEdge.id)
             return true;
-        if (currentEdge.source !== newEdge.source ||
-            currentEdge.target !== newEdge.target)
+        if (currentEdge.source !== newEdge.source || currentEdge.target !== newEdge.target)
             return true;
     }
     return false;
@@ -426,9 +414,9 @@ export const workflowActions = {
      */
     initialize: (workflow) => {
         workflowState = workflow;
-        // Set the saved snapshot - workflow is "clean" after initialization
-        savedSnapshot = createSnapshot(workflow);
-        isDirtyState = false;
+        // Reset version counters — workflow is "clean" after initialization
+        _editVersion = 0;
+        _savedVersion = 0;
         if (onDirtyStateChangeCallback) {
             onDirtyStateChangeCallback(false);
         }
@@ -443,7 +431,8 @@ export const workflowActions = {
      */
     updateWorkflow: (workflow) => {
         workflowState = workflow;
-        notifyWorkflowChange("metadata");
+        bumpVersion();
+        notifyWorkflowChange('metadata');
     },
     /**
      * Restore workflow from history (undo/redo)
@@ -453,7 +442,8 @@ export const workflowActions = {
     restoreFromHistory: (workflow) => {
         isRestoringFromHistory = true;
         workflowState = workflow;
-        notifyWorkflowChange("metadata");
+        bumpVersion();
+        notifyWorkflowChange('metadata');
         isRestoringFromHistory = false;
     },
     /**
@@ -473,10 +463,11 @@ export const workflowActions = {
             nodes,
             metadata: buildMetadata(workflowState.metadata, {
                 versionId,
-                updateNumber: (workflowState.metadata?.updateNumber ?? 0) + 1,
-            }),
+                updateNumber: (workflowState.metadata?.updateNumber ?? 0) + 1
+            })
         };
-        notifyWorkflowChange("node_move");
+        bumpVersion();
+        notifyWorkflowChange('node_move');
     },
     /**
      * Update edges
@@ -495,10 +486,11 @@ export const workflowActions = {
             edges,
             metadata: buildMetadata(workflowState.metadata, {
                 versionId,
-                updateNumber: (workflowState.metadata?.updateNumber ?? 0) + 1,
-            }),
+                updateNumber: (workflowState.metadata?.updateNumber ?? 0) + 1
+            })
         };
-        notifyWorkflowChange("edge_add");
+        bumpVersion();
+        notifyWorkflowChange('edge_add');
     },
     /**
      * Update workflow name
@@ -509,23 +501,25 @@ export const workflowActions = {
         workflowState = {
             ...workflowState,
             name,
-            metadata: buildMetadata(workflowState.metadata),
+            metadata: buildMetadata(workflowState.metadata)
         };
-        notifyWorkflowChange("name");
+        bumpVersion();
+        notifyWorkflowChange('name');
     },
     /**
      * Add a node
      */
     addNode: (node) => {
-        pushToHistory("Add node");
+        pushToHistory('Add node');
         if (!workflowState)
             return;
         workflowState = {
             ...workflowState,
             nodes: [...workflowState.nodes, node],
-            metadata: buildMetadata(workflowState.metadata),
+            metadata: buildMetadata(workflowState.metadata)
         };
-        notifyWorkflowChange("node_add");
+        bumpVersion();
+        notifyWorkflowChange('node_add');
     },
     /**
      * Remove a node
@@ -534,44 +528,47 @@ export const workflowActions = {
      * A single undo will restore both the node and its edges.
      */
     removeNode: (nodeId) => {
-        pushToHistory("Delete node");
+        pushToHistory('Delete node');
         if (!workflowState)
             return;
         workflowState = {
             ...workflowState,
             nodes: workflowState.nodes.filter((node) => node.id !== nodeId),
             edges: workflowState.edges.filter((edge) => edge.source !== nodeId && edge.target !== nodeId),
-            metadata: buildMetadata(workflowState.metadata),
+            metadata: buildMetadata(workflowState.metadata)
         };
-        notifyWorkflowChange("node_remove");
+        bumpVersion();
+        notifyWorkflowChange('node_remove');
     },
     /**
      * Add an edge
      */
     addEdge: (edge) => {
-        pushToHistory("Add connection");
+        pushToHistory('Add connection');
         if (!workflowState)
             return;
         workflowState = {
             ...workflowState,
             edges: [...workflowState.edges, edge],
-            metadata: buildMetadata(workflowState.metadata),
+            metadata: buildMetadata(workflowState.metadata)
         };
-        notifyWorkflowChange("edge_add");
+        bumpVersion();
+        notifyWorkflowChange('edge_add');
     },
     /**
      * Remove an edge
      */
     removeEdge: (edgeId) => {
-        pushToHistory("Delete connection");
+        pushToHistory('Delete connection');
         if (!workflowState)
             return;
         workflowState = {
             ...workflowState,
             edges: workflowState.edges.filter((edge) => edge.id !== edgeId),
-            metadata: buildMetadata(workflowState.metadata),
+            metadata: buildMetadata(workflowState.metadata)
         };
-        notifyWorkflowChange("edge_remove");
+        bumpVersion();
+        notifyWorkflowChange('edge_remove');
     },
     /**
      * Update a specific node
@@ -579,15 +576,16 @@ export const workflowActions = {
      * Used for config changes. Pushes to history for undo support.
      */
     updateNode: (nodeId, updates) => {
-        pushToHistory("Update node config");
+        pushToHistory('Update node config');
         if (!workflowState)
             return;
         workflowState = {
             ...workflowState,
             nodes: workflowState.nodes.map((node) => node.id === nodeId ? { ...node, ...updates } : node),
-            metadata: buildMetadata(workflowState.metadata),
+            metadata: buildMetadata(workflowState.metadata)
         };
-        notifyWorkflowChange("node_config");
+        bumpVersion();
+        notifyWorkflowChange('node_config');
     },
     /**
      * Clear the workflow
@@ -596,8 +594,8 @@ export const workflowActions = {
      */
     clear: () => {
         workflowState = null;
-        savedSnapshot = null;
-        isDirtyState = false;
+        _editVersion = 0;
+        _savedVersion = 0;
         historyService.clear();
         if (onDirtyStateChangeCallback) {
             onDirtyStateChangeCallback(false);
@@ -611,9 +609,10 @@ export const workflowActions = {
             return;
         workflowState = {
             ...workflowState,
-            metadata: buildMetadata(workflowState.metadata, metadata),
+            metadata: buildMetadata(workflowState.metadata, metadata)
         };
-        notifyWorkflowChange("metadata");
+        bumpVersion();
+        notifyWorkflowChange('metadata');
     },
     /**
      * Batch update nodes and edges
@@ -622,7 +621,7 @@ export const workflowActions = {
      * Creates a single history entry for the entire batch.
      */
     batchUpdate: (updates) => {
-        pushToHistory("Batch update");
+        pushToHistory('Batch update');
         if (!workflowState)
             return;
         workflowState = {
@@ -631,11 +630,31 @@ export const workflowActions = {
             ...(updates.edges && { edges: updates.edges }),
             ...(updates.name && { name: updates.name }),
             ...(updates.description !== undefined && {
-                description: updates.description,
+                description: updates.description
             }),
-            metadata: buildMetadata(workflowState.metadata, updates.metadata ?? undefined),
+            metadata: buildMetadata(workflowState.metadata, updates.metadata ?? undefined)
+        };
+        bumpVersion();
+        notifyWorkflowChange('metadata');
+    },
+    /**
+     * 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) => {
+        pushToHistory(updates.description ?? 'Swap node');
+        if (!workflowState)
+            return;
+        workflowState = {
+            ...workflowState,
+            nodes: updates.nodes,
+            edges: updates.edges,
+            metadata: buildMetadata(workflowState.metadata)
         };
-        notifyWorkflowChange("metadata");
+        bumpVersion();
+        notifyWorkflowChange('node_swap');
     },
     /**
      * Push current state to history manually
@@ -648,5 +667,5 @@ export const workflowActions = {
      */
     pushHistory: (description, workflow) => {
         pushToHistory(description, workflow);
-    },
+    }
 };

package/dist/stories/CanvasDecorator.svelte

@@ -3,28 +3,25 @@
   matching how overlay components (e.g. CanvasBanner) appear in the workflow editor.
 -->
 <script lang="ts">
-  import { SvelteFlow, Controls } from "@xyflow/svelte";
-  import type { ColorMode } from "@xyflow/svelte";
-  import "@xyflow/svelte/dist/style.css";
-  import type { Snippet } from "svelte";
+  import { SvelteFlow, Controls } from '@xyflow/svelte';
+  import type { ColorMode } from '@xyflow/svelte';
+  import '@xyflow/svelte/dist/style.css';
+  import type { Snippet } from 'svelte';
 
   let { children }: { children: Snippet } = $props();
 
   // Watch the data-theme attribute set by Storybook's addon-themes
   let colorMode = $state<ColorMode>(
-    (document.documentElement.getAttribute("data-theme") as ColorMode) ||
-      "light",
+    (document.documentElement.getAttribute('data-theme') as ColorMode) || 'light'
   );
 
   $effect(() => {
     const observer = new MutationObserver(() => {
-      colorMode =
-        (document.documentElement.getAttribute("data-theme") as ColorMode) ||
-        "light";
+      colorMode = (document.documentElement.getAttribute('data-theme') as ColorMode) || 'light';
     });
     observer.observe(document.documentElement, {
       attributes: true,
-      attributeFilter: ["data-theme"],
+      attributeFilter: ['data-theme']
     });
     return () => observer.disconnect();
   });

package/dist/stories/CanvasDecorator.svelte.d.ts

@@ -1,5 +1,5 @@
-import "@xyflow/svelte/dist/style.css";
-import type { Snippet } from "svelte";
+import '@xyflow/svelte/dist/style.css';
+import type { Snippet } from 'svelte';
 type $$ComponentProps = {
     children: Snippet;
 };