@flowdrop/flowdrop 1.15.0 → 2.0.0-beta.1

package/dist/stories/EdgeDecorator.svelte

@@ -8,7 +8,8 @@
   import '@xyflow/svelte/dist/style.css';
   import UniversalNode from '../components/UniversalNode.svelte';
   import FlowDropEdge from '../components/FlowDropEdge.svelte';
-  import { registerBuiltinNodes } from '../registry/builtinNodes.js';
+  import { getDefaultInstance } from '../stores/instanceContainer.svelte.js';
+  import { provideInstance } from '../stores/getInstance.svelte.js';
   import { EDGE_MARKER_SIZES } from '../config/constants.js';
 
   interface Props {
@@ -33,7 +34,9 @@
     targetHandleId = 'input'
   }: Props = $props();
 
-  registerBuiltinNodes();
+  // Provide an instance so UniversalNode can resolve built-in node components
+  // (the registry is seeded with BUILTIN_NODE_COMPONENTS at construction).
+  provideInstance(getDefaultInstance());
 
   const nodeTypes = {
     universalNode: UniversalNode

package/dist/stories/NodeDecorator.svelte

@@ -7,12 +7,14 @@
   import type { Node, ColorMode } from '@xyflow/svelte';
   import '@xyflow/svelte/dist/style.css';
   import UniversalNode from '../components/UniversalNode.svelte';
-  import { registerBuiltinNodes } from '../registry/builtinNodes.js';
+  import { getDefaultInstance } from '../stores/instanceContainer.svelte.js';
+  import { provideInstance } from '../stores/getInstance.svelte.js';
 
   let { data, selected = false }: { data: Record<string, unknown>; selected?: boolean } = $props();
 
-  // Ensure built-in node components are registered
-  registerBuiltinNodes();
+  // Provide an instance so UniversalNode can resolve built-in node components
+  // (the registry is seeded with BUILTIN_NODE_COMPONENTS at construction).
+  provideInstance(getDefaultInstance());
 
   const nodeTypes = {
     universalNode: UniversalNode

package/dist/svelte-app.d.ts

@@ -12,7 +12,8 @@ import type { AuthProvider } from './types/auth.js';
 import type { FlowDropEventHandlers, FlowDropFeatures } from './types/events.js';
 import type { FlowDropTheme, FlowDropThemeName } from './types/theme.js';
 import type { WorkflowFormatAdapter } from './registry/workflowFormatRegistry.js';
-import './registry/builtinFormats.js';
+import { type FlowDropInstance } from './stores/instanceContainer.svelte.js';
+import { type DraftStorageOption } from './services/draftStorage.js';
 import type { PartialSettings, SettingsCategory } from './types/settings.js';
 import type { NavbarAction } from './types/navbar.js';
 export type { NavbarAction };
@@ -38,20 +39,25 @@ export interface FlowDropMountOptions {
     showNavbar?: boolean;
     /** Disable the node sidebar */
     disableSidebar?: boolean;
-    /** Lock the workflow (prevent changes) */
-    lockWorkflow?: boolean;
-    /** Read-only mode */
-    readOnly?: boolean;
+    /**
+     * Editor interaction mode. Replaces the former `readOnly` + `lockWorkflow`
+     * mount options (2.0). `'edit'` (default) allows editing; `'readonly'` and
+     * `'locked'` disable all canvas interaction (identical behavior today — see
+     * App's `mode` prop JSDoc for the full matrix). Migration: `readOnly: true`
+     * → `mode: 'readonly'`; `lockWorkflow: true` → `mode: 'locked'`.
+     * @default 'edit'
+     */
+    mode?: 'edit' | 'readonly' | 'locked';
     /** Pipeline ID for status display */
     pipelineId?: string;
-    /** Node execution statuses */
-    nodeStatuses?: Record<string, 'pending' | 'running' | 'completed' | 'error'>;
     /** Custom navbar title */
     navbarTitle?: string;
     /** Custom navbar actions */
     navbarActions?: NavbarAction[];
     /** Show settings gear icon in navbar */
     showSettings?: boolean;
+    /** Show the "Connected" status indicator in the navbar (default: true) */
+    showStatus?: boolean;
     /** Authentication provider for API requests */
     authProvider?: AuthProvider;
     /** Event handlers for workflow lifecycle */
@@ -60,8 +66,28 @@ export interface FlowDropMountOptions {
     features?: FlowDropFeatures;
     /** Initial settings overrides (theme, behavior, editor, ui, api) */
     settings?: PartialSettings;
-    /** Custom storage key for localStorage drafts */
+    /** Custom storage key for workflow drafts */
     draftStorageKey?: string;
+    /**
+     * Where workflow drafts are persisted.
+     *
+     * - `'local'` (default): `localStorage` — drafts survive reloads and remain
+     *   stored on the device even after the tab or browser is closed, until
+     *   saved or cleared. Call `clearAllDrafts()` on logout for shared devices.
+     * - `'session'`: `sessionStorage` — drafts are scoped to the tab and removed
+     *   when it closes (they do not survive crash-and-reopen).
+     * - A custom `DraftStorageAdapter` — note the adapter interface is
+     *   synchronous, so it suits in-memory stores and write-through caches;
+     *   async backends (IndexedDB, network) need a sync cache in front.
+     *
+     * The resolved adapter is captured per mount, so multiple FlowDrop
+     * instances on one page can use different backends.
+     *
+     * Note: neither built-in backend protects against same-origin script access
+     * (XSS). End users can additionally opt out of draft persistence at runtime
+     * via the "Store Drafts in Browser" behavior setting.
+     */
+    draftStorage?: DraftStorageOption;
     /** Custom workflow format adapters to register */
     formatAdapters?: WorkflowFormatAdapter[];
     /** Visual theme — named built-in ('default' | 'minimal') or custom theme object */
@@ -72,11 +98,32 @@ export interface FlowDropMountOptions {
     showSettingsSyncButton?: boolean;
     /** Show the reset buttons in the settings modal */
     showSettingsResetButton?: boolean;
+    /**
+     * Identifier for this FlowDrop instance.
+     *
+     * When omitted, the first mount on the page becomes the *default* instance
+     * (id `default`). Additional mounts get auto-generated ids (`fd-1`,
+     * `fd-2`, …). Every instance scopes its draft/panel storage keys by id
+     * (`flowdrop:draft:<id>:…`); the default instance migrates 1.x bare keys
+     * on first read.
+     *
+     * Pass an explicit id whenever you mount more than one editor with drafts
+     * enabled, so keys stay stable across page loads.
+     */
+    instanceId?: string;
 }
 /**
  * Return type for mounted FlowDrop app
  */
 export interface MountedFlowDropApp {
+    /**
+     * This mount's state container — workflow, history, playground, interrupts,
+     * categories, and the rest. The 2.0 replacement for the removed
+     * module-level store APIs: where 1.x called `workflowActions.addNode(...)`
+     * or `historyService.undo()`, call `app.instance.workflow.addNode(...)` /
+     * `app.instance.history.undo()` on the mount that owns the editor.
+     */
+    instance: FlowDropInstance;
     /**
      * Destroy the app and clean up resources
      */
@@ -102,7 +149,8 @@ export interface MountedFlowDropApp {
      */
     export: () => void;
     /**
-     * Clear all FlowDrop workflow drafts from `localStorage`.
+     * Clear all FlowDrop workflow drafts from the configured draft storage
+     * (`localStorage` unless changed via the `draftStorage` mount option).
      *
      * Removes every key beginning with `flowdrop:draft:` plus the custom
      * `draftStorageKey` configured at mount time (if any). Call this from
@@ -148,12 +196,14 @@ export declare function mountFlowDropApp(container: HTMLElement, options?: FlowD
  * @returns Promise resolving to a MountedFlowDropApp instance
  */
 export declare function mountWorkflowEditor(container: HTMLElement, options?: {
+    /** Initial workflow to load into the editor */
     workflow?: Workflow;
-    nodes?: NodeMetadata[];
     endpointConfig?: EndpointConfig;
     portConfig?: PortConfig;
     categories?: CategoryDefinition[];
     authProvider?: AuthProvider;
+    /** Instance identifier — see {@link FlowDropMountOptions.instanceId}. */
+    instanceId?: string;
 }): Promise<MountedFlowDropApp>;
 /**
  * Unmount a FlowDrop app

package/dist/svelte-app.js

@@ -9,19 +9,52 @@
 import { mount, unmount } from 'svelte';
 import WorkflowEditor from './components/WorkflowEditor.svelte';
 import App from './components/App.svelte';
-import { workflowFormatRegistry } from './registry/workflowFormatRegistry.js';
-import './registry/builtinFormats.js';
-import { initializePortCompatibility } from './utils/connections.js';
 import { DEFAULT_PORT_CONFIG } from './config/defaultPortConfig.js';
 import { fetchPortConfig } from './services/portConfigApi.js';
 import { fetchCategories } from './services/categoriesApi.js';
-import { initializeCategories } from './stores/categoriesStore.svelte.js';
-import { isDirty, markAsSaved, getWorkflow as getWorkflowFromStore, setOnDirtyStateChange, setOnWorkflowChange } from './stores/workflowStore.svelte.js';
-import { DraftAutoSaveManager, getDraftStorageKey, clearAllDrafts as clearAllDraftsFromStorage } from './services/draftStorage.js';
+import { createFlowDropInstance, getDefaultInstance, DEFAULT_DRAFT_PREFIX } from './stores/instanceContainer.svelte.js';
+import { DraftAutoSaveManager, getDraftStorageKey, migrateLegacyDraftKey, setDraftStorage, resolveDraftStorage, clearAllDrafts as clearAllDraftsFromStorage } from './services/draftStorage.js';
 import { mergeFeatures } from './types/events.js';
-import { initializeSettings } from './stores/settingsStore.svelte.js';
+import { initializeSettings, getBehaviorSettings, onSettingsChange } from './stores/settingsStore.svelte.js';
 import { logger } from './utils/logger.js';
 import { globalSaveWorkflow, globalExportWorkflow } from './services/globalSave.js';
+// ---------------------------------------------------------------------------
+// Instance acquisition
+// ---------------------------------------------------------------------------
+/** Whether a mount currently owns the page-default instance. */
+let defaultInstanceClaimed = false;
+/**
+ * Resolve the FlowDrop instance for a new mount.
+ *
+ * No `instanceId` + default unclaimed → the page-default instance (legacy
+ * storage keys, reachable via the module-level store APIs). Everything else
+ * gets its own isolated instance.
+ */
+function acquireInstance(instanceId) {
+    if (!instanceId && !defaultInstanceClaimed) {
+        defaultInstanceClaimed = true;
+        return { fd: getDefaultInstance(), isDefault: true };
+    }
+    return { fd: createFlowDropInstance({ id: instanceId }), isDefault: false };
+}
+/**
+ * Release a mount's instance on destroy.
+ *
+ * Non-default instances are fully destroyed (subscriptions, effect roots,
+ * callbacks). The default instance is only *released* — its callbacks are
+ * cleared but its reactive wiring stays alive, matching the pre-multi-instance
+ * behavior where module stores survived unmount and a later mount reused them.
+ */
+function releaseInstance(fd, isDefault) {
+    if (isDefault) {
+        fd.workflow.setOnDirtyStateChange(null);
+        fd.workflow.setOnWorkflowChange(null);
+        defaultInstanceClaimed = false;
+    }
+    else {
+        fd.destroy();
+    }
+}
 /**
  * Mount the full FlowDrop App with navbar, sidebars, and workflow editor
  *
@@ -47,15 +80,25 @@ import { globalSaveWorkflow, globalExportWorkflow } from './services/globalSave.
  * ```
  */
 export async function mountFlowDropApp(container, options = {}) {
-    const { workflow, nodes, endpointConfig, portConfig, categories, height = '100vh', width = '100%', showNavbar = false, disableSidebar, lockWorkflow, readOnly, nodeStatuses, pipelineId, navbarTitle, navbarActions, showSettings, authProvider, eventHandlers, features: userFeatures, settings: initialSettings, draftStorageKey: customDraftKey, formatAdapters, theme, settingsCategories, showSettingsSyncButton, showSettingsResetButton } = options;
+    const { workflow, nodes, endpointConfig, portConfig, categories, height = '100vh', width = '100%', showNavbar = false, disableSidebar, mode, pipelineId, navbarTitle, navbarActions, showSettings, showStatus, authProvider, eventHandlers, features: userFeatures, settings: initialSettings, draftStorageKey: customDraftKey, draftStorage, formatAdapters, theme, settingsCategories, showSettingsSyncButton, showSettingsResetButton, instanceId } = options;
+    // Per-instance state container — this is what allows multiple FlowDrop
+    // editors to coexist on one page without sharing workflow/history state.
+    const { fd, isDefault } = acquireInstance(instanceId);
     // Register custom format adapters before mounting
     if (formatAdapters) {
         for (const adapter of formatAdapters) {
-            workflowFormatRegistry.register(adapter);
+            fd.formats.register(adapter);
         }
     }
     // Merge features with defaults
     const features = mergeFeatures(userFeatures);
+    // Resolve this instance's draft storage backend. The adapter is captured
+    // here and threaded into the draft manager and clearAllDrafts, so a later
+    // mount with a different backend cannot retarget this instance. The
+    // module-level default is also updated for the standalone helpers
+    // (last mount wins there — instance paths do not depend on it).
+    const draftStorageAdapter = resolveDraftStorage(draftStorage ?? 'local');
+    setDraftStorage(draftStorageAdapter);
     // Apply initial settings overrides and initialize theme
     await initializeSettings({
         defaults: initialSettings
@@ -94,47 +137,64 @@ export async function mountFlowDropApp(container, options = {}) {
     else if (!finalPortConfig) {
         finalPortConfig = DEFAULT_PORT_CONFIG;
     }
-    initializePortCompatibility(finalPortConfig);
-    // Initialize categories
+    // Configure this instance's API context (endpoints + auth provider) so
+    // <App> and services resolve it via getInstance().api.
+    if (config) {
+        fd.api.configure(config, authProvider);
+    }
+    // Re-initialize this instance's port compatibility checker with the resolved
+    // config (it was seeded with DEFAULT_PORT_CONFIG at construction).
+    fd.portCompatibility.reinitialize(finalPortConfig);
+    // Initialize this instance's categories
     if (categories) {
-        initializeCategories(categories);
+        fd.categories.initialize(categories);
     }
     else if (config) {
         try {
             const fetchedCategories = await fetchCategories(config, authProvider);
-            initializeCategories(fetchedCategories);
+            fd.categories.initialize(fetchedCategories);
         }
         catch (error) {
             logger.warn('Failed to fetch categories from API, using defaults:', error);
         }
     }
-    // Set up event handler callbacks in the store
+    // Set up event handler callbacks in this instance's store
     if (eventHandlers?.onDirtyStateChange) {
-        setOnDirtyStateChange(eventHandlers.onDirtyStateChange);
+        fd.workflow.setOnDirtyStateChange(eventHandlers.onDirtyStateChange);
     }
     if (eventHandlers?.onWorkflowChange) {
-        setOnWorkflowChange(eventHandlers.onWorkflowChange);
+        fd.workflow.setOnWorkflowChange(eventHandlers.onWorkflowChange);
     }
     // Create the Svelte App component with configuration
     const svelteApp = mount(App, {
         target: container,
         props: {
+            instance: fd,
             workflow,
             nodes,
             height,
             width,
             showNavbar,
             disableSidebar,
-            lockWorkflow,
-            readOnly,
-            nodeStatuses,
+            mode,
             pipelineId,
             navbarTitle,
             navbarActions,
             showSettings,
+            showStatus,
             endpointConfig: config,
             authProvider,
-            eventHandlers,
+            // App's event-handler props are flat (the grouped `eventHandlers` option
+            // is a mount-API convenience). onDirtyStateChange / onWorkflowChange are
+            // wired into the instance store above; onBeforeUnmount is handled in
+            // unmount() below; the remaining handlers map 1:1 to App props.
+            onBeforeSave: eventHandlers?.onBeforeSave,
+            onAfterSave: eventHandlers?.onAfterSave,
+            onSaveError: eventHandlers?.onSaveError,
+            onApiError: eventHandlers?.onApiError,
+            onWorkflowLoad: eventHandlers?.onWorkflowLoad,
+            onBeforeSwap: eventHandlers?.onBeforeSwap,
+            onAfterSwap: eventHandlers?.onAfterSwap,
             features,
             theme,
             settingsCategories,
@@ -144,88 +204,119 @@ export async function mountFlowDropApp(container, options = {}) {
     });
     // Set up draft auto-save manager
     let draftManager = null;
+    let unsubscribeDraftSettings = null;
     if (features.autoSaveDraft) {
-        const storageKey = getDraftStorageKey(workflow?.id, customDraftKey);
+        // Instance-scoped prefix: every instance (including the default) gets
+        // 'flowdrop:draft:<id>' sub-keys.
+        const storageKey = getDraftStorageKey(workflow?.id, customDraftKey, fd.storagePrefix);
+        // One-time migration: 1.x stored the page-default instance's drafts under
+        // the bare 'flowdrop:draft:<workflowId>' key. Move an existing draft to
+        // the scoped key so an upgrade mid-edit doesn't lose work.
+        if (fd.isDefault && !customDraftKey) {
+            migrateLegacyDraftKey(getDraftStorageKey(workflow?.id, undefined, DEFAULT_DRAFT_PREFIX), storageKey, draftStorageAdapter);
+        }
         draftManager = new DraftAutoSaveManager({
             storageKey,
             interval: features.autoSaveDraftInterval,
             enabled: features.autoSaveDraft,
-            getWorkflow: getWorkflowFromStore,
-            isDirty
+            getWorkflow: () => fd.workflow.current,
+            isDirty: () => fd.workflow.isDirty,
+            // User-facing opt-out: the "Store Drafts in Browser" behavior setting.
+            // Checked on every save so toggling it takes effect immediately.
+            isPersistenceAllowed: () => getBehaviorSettings().storeDraftsInBrowser,
+            storage: draftStorageAdapter
         });
         draftManager.start();
+        // When the user opts out, also remove the draft already in storage.
+        unsubscribeDraftSettings = onSettingsChange((event) => {
+            if (event.category === 'behavior' &&
+                event.key === 'storeDraftsInBrowser' &&
+                event.newValue === false) {
+                draftManager?.clearDraft();
+            }
+        });
     }
     // Store state for cleanup
     const state = {
         svelteApp,
         draftManager,
-        eventHandlers: eventHandlers ?? null
+        eventHandlers: eventHandlers ?? null,
+        unsubscribeDraftSettings
     };
     // Create the mounted app interface
     const mountedApp = {
+        instance: fd,
         destroy: () => {
             // Call onBeforeUnmount if provided
             if (state.eventHandlers?.onBeforeUnmount) {
-                const currentWorkflow = getWorkflowFromStore();
+                const currentWorkflow = fd.workflow.current;
                 if (currentWorkflow) {
-                    state.eventHandlers.onBeforeUnmount(currentWorkflow, isDirty());
+                    state.eventHandlers.onBeforeUnmount(currentWorkflow, fd.workflow.isDirty);
                 }
             }
             // Stop draft manager
             if (state.draftManager) {
-                // Save one final draft if dirty
-                if (isDirty()) {
+                // Save one final draft if dirty (no-op when the user opted out)
+                if (fd.workflow.isDirty) {
                     state.draftManager.forceSave();
                 }
                 state.draftManager.stop();
             }
-            // Clear event callbacks
-            setOnDirtyStateChange(null);
-            setOnWorkflowChange(null);
+            // Stop listening for the draft opt-out setting
+            if (state.unsubscribeDraftSettings) {
+                state.unsubscribeDraftSettings();
+                state.unsubscribeDraftSettings = null;
+            }
+            // Release this mount's instance: clears its callbacks (and, for
+            // non-default instances, all subscriptions/effect roots) without
+            // touching sibling instances on the same page.
+            releaseInstance(fd, isDefault);
             // Unmount Svelte app
             unmount(state.svelteApp);
         },
-        isDirty: () => isDirty(),
+        isDirty: () => fd.workflow.isDirty,
         markAsSaved: () => {
-            markAsSaved();
+            fd.workflow.markAsSaved();
             if (state.draftManager) {
                 // Migrate the draft key when the host confirms a save. New workflows start
-                // on 'flowdrop:draft:new', a key shared across all tabs. If the host has
+                // on '<prefix>:new', a key shared across all tabs. If the host has
                 // written the server-assigned ID back into the store before calling
                 // markAsSaved(), we can move to a unique per-workflow key and stop
                 // competing with other tabs that may also have unsaved new workflows.
                 // Skip when customDraftKey is set — the host manages that key explicitly.
                 if (!customDraftKey) {
-                    const currentWorkflow = getWorkflowFromStore();
+                    const currentWorkflow = fd.workflow.current;
                     if (currentWorkflow?.id) {
-                        state.draftManager.updateStorageKey(getDraftStorageKey(currentWorkflow.id));
+                        state.draftManager.updateStorageKey(getDraftStorageKey(currentWorkflow.id, undefined, fd.storagePrefix));
                     }
                 }
                 state.draftManager.markAsSaved();
             }
         },
-        getWorkflow: () => getWorkflowFromStore(),
+        getWorkflow: () => fd.workflow.current,
         save: async () => {
             await globalSaveWorkflow({
+                instance: fd,
                 onSaved: (saved) => {
                     // globalSaveWorkflow does not write the server-assigned ID back to the
-                    // workflow store, so we cannot read it from getWorkflowFromStore() here.
+                    // workflow store, so we cannot read it from the store here.
                     // Instead we use the savedWorkflow returned by the API directly.
-                    // This migrates 'flowdrop:draft:new' to a unique per-workflow key
+                    // This migrates '<prefix>:new' to a unique per-workflow key
                     // immediately after the first save, preventing cross-tab collisions
                     // when multiple new workflows are open simultaneously.
                     if (state.draftManager && !customDraftKey && saved.id) {
-                        state.draftManager.updateStorageKey(getDraftStorageKey(saved.id));
+                        state.draftManager.updateStorageKey(getDraftStorageKey(saved.id, undefined, fd.storagePrefix));
                     }
                 }
             });
         },
         export: () => {
-            globalExportWorkflow();
+            globalExportWorkflow({ instance: fd });
         },
         clearAllDrafts: () => {
             const extras = customDraftKey ? [customDraftKey] : [];
-            const removed = clearAllDraftsFromStorage(extras);
+            // Clear this instance's backend, not whatever the module default is now
+            const removed = clearAllDraftsFromStorage(extras, draftStorageAdapter);
             if (state.draftManager) {
                 state.draftManager.markAsSaved();
             }
@@ -244,7 +335,9 @@ export async function mountFlowDropApp(container, options = {}) {
  * @returns Promise resolving to a MountedFlowDropApp instance
  */
 export async function mountWorkflowEditor(container, options = {}) {
-    const { nodes = [], endpointConfig, portConfig, categories, authProvider } = options;
+    const { workflow, endpointConfig, portConfig, categories, authProvider, instanceId } = options;
+    // Per-instance state container (see mountFlowDropApp)
+    const { fd, isDefault } = acquireInstance(instanceId);
     // Create endpoint configuration
     let config;
     if (endpointConfig) {
@@ -279,41 +372,52 @@ export async function mountWorkflowEditor(container, options = {}) {
     else if (!finalPortConfig) {
         finalPortConfig = DEFAULT_PORT_CONFIG;
     }
-    initializePortCompatibility(finalPortConfig);
-    // Initialize categories
+    // Configure this instance's API context and port compatibility checker.
+    if (config) {
+        fd.api.configure(config, authProvider);
+    }
+    fd.portCompatibility.reinitialize(finalPortConfig);
+    // Initialize this instance's categories
     if (categories) {
-        initializeCategories(categories);
+        fd.categories.initialize(categories);
     }
     else if (config) {
         try {
             const fetchedCategories = await fetchCategories(config, authProvider);
-            initializeCategories(fetchedCategories);
+            fd.categories.initialize(fetchedCategories);
         }
         catch (error) {
             logger.warn('Failed to fetch categories from API, using defaults:', error);
         }
     }
+    // Seed the instance's workflow before mounting so the editor renders it
+    // immediately. (1.x accepted this option but silently ignored it.)
+    if (workflow) {
+        fd.workflow.initialize(workflow);
+    }
     // Create the Svelte component
     const svelteApp = mount(WorkflowEditor, {
         target: container,
         props: {
-            nodes,
+            instance: fd,
             endpointConfig: config
         }
     });
     // Create the mounted app interface (simpler version)
     const mountedApp = {
+        instance: fd,
         destroy: () => {
+            releaseInstance(fd, isDefault);
             unmount(svelteApp);
         },
-        isDirty: () => isDirty(),
-        markAsSaved: () => markAsSaved(),
-        getWorkflow: () => getWorkflowFromStore(),
+        isDirty: () => fd.workflow.isDirty,
+        markAsSaved: () => fd.workflow.markAsSaved(),
+        getWorkflow: () => fd.workflow.current,
         save: async () => {
-            await globalSaveWorkflow();
+            await globalSaveWorkflow({ instance: fd });
         },
         export: () => {
-            globalExportWorkflow();
+            globalExportWorkflow({ instance: fd });
         },
         clearAllDrafts: () => clearAllDraftsFromStorage()
     };

package/dist/types/events.d.ts

@@ -166,10 +166,13 @@ export interface FlowDropEventHandlers {
  */
 export interface FlowDropFeatures {
     /**
-     * Save drafts to localStorage automatically
+     * Save drafts to browser storage automatically
      *
      * When enabled, FlowDrop will periodically save the current workflow
-     * to localStorage as a draft. This helps prevent data loss.
+     * to draft storage (localStorage by default, configurable via the
+     * `draftStorage` mount option). This helps prevent data loss. End users
+     * can additionally opt out at runtime via the "Store Drafts in Browser"
+     * behavior setting.
      *
      * @default true
      */
@@ -177,7 +180,7 @@ export interface FlowDropFeatures {
     /**
      * Auto-save interval in milliseconds
      *
-     * How often to save drafts to localStorage when autoSaveDraft is enabled.
+     * How often to save drafts to storage when autoSaveDraft is enabled.
      *
      * @default 30000 (30 seconds)
      */

package/dist/types/index.d.ts

@@ -208,7 +208,7 @@ export type BuiltinNodeType = 'note' | 'simple' | 'square' | 'atom' | 'tool' | '
  * Includes built-in types and allows custom registered types.
  *
  * Built-in types: note, simple, square, tool, gateway, terminal, default
- * Custom types: Any string registered via nodeComponentRegistry
+ * Custom types: Any string registered via fd.nodes
  *
  * @example
  * ```typescript
@@ -1188,8 +1188,9 @@ export interface Workflow {
     description?: string;
     nodes: WorkflowNode[];
     edges: WorkflowEdge[];
-    metadata?: {
-        version: string;
+    metadata: {
+        /** Workflow schema format version — identifies the document format, not the workflow's own revision. */
+        schemaVersion: string;
         createdAt: string;
         updatedAt: string;
         author?: string;
@@ -1243,6 +1244,31 @@ export interface PipelineViewDef {
     /** Svelte component that receives PipelineViewProps */
     component: Component<PipelineViewProps>;
 }
+/**
+ * One job execution of a node within a pipeline run.
+ *
+ * Loop-orchestrated workflows create one job per iteration for the same
+ * node (labels carry an iteration suffix, e.g. "Invoke tool #2"), so a node
+ * can have several of these per run.
+ */
+export interface NodeJobExecution {
+    /** Job entity ID */
+    id?: string;
+    /** Job label, carries the iteration suffix (e.g. "Invoke tool #2") */
+    label?: string;
+    /** Job status */
+    status: NodeExecutionStatus;
+    /** ISO timestamp the job started, if it ran */
+    started?: string;
+    /** ISO timestamp the job completed, if it finished */
+    completed?: string;
+    /** Execution duration in milliseconds, if the job ran to completion */
+    executionTime?: number;
+    /** Precise execution duration in microseconds, when the backend provides it */
+    executionTimeUs?: number;
+    /** Error message if the job failed */
+    error?: string;
+}
 /**
  * Node execution tracking information
  */
@@ -1255,12 +1281,16 @@ export interface NodeExecutionInfo {
     lastExecuted?: string;
     /** Last execution duration in milliseconds */
     lastExecutionDuration?: number;
+    /** Precise last execution duration in microseconds, when the backend provides it */
+    lastExecutionDurationUs?: number;
     /** Last error message if execution failed */
     lastError?: string;
     /** Whether the node is currently being executed */
     isExecuting: boolean;
     /** Execution output data (e.g., active branches for gateway nodes) */
     output?: Record<string, unknown>;
+    /** Per-job execution history (loop iterations), in pipeline order */
+    jobs?: NodeJobExecution[];
 }
 /**
  * Workflow execution status

package/dist/types/navbar.d.ts

@@ -11,4 +11,11 @@ export interface NavbarAction {
     onclick?: (event: Event) => void;
     /** If true, opens link in new tab with `rel="noopener noreferrer"`. */
     external?: boolean;
+    /**
+     * Optional group label. Items sharing the same `group` cluster together
+     * under a header inside the flyout dropdown. Ungrouped items render first.
+     * Group order follows first occurrence in the array. Ignored when the
+     * navbar is in split mode (the inline row of buttons).
+     */
+    group?: string;
 }