@flowdrop/flowdrop 1.15.0 → 2.0.0-beta.2

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

@@ -1,136 +1,120 @@
 /**
  * History Store for FlowDrop (Svelte 5 Runes)
  *
- * Provides reactive Svelte 5 rune-based bindings for the history service.
+ * Provides reactive Svelte 5 rune-based bindings for a history service.
  * Exposes undo/redo state and actions for the workflow editor.
  *
+ * The reactive state lives in the {@link HistoryStore} class — one per
+ * FlowDrop instance, created by `createFlowDropInstance()` and resolved in
+ * components via `getInstance().historyBindings`.
+ *
  * @module stores/historyStore
  */
-import { type HistoryState, type PushOptions } from '../services/historyService.js';
+import { HistoryService, type HistoryState, type PushOptions } from '../services/historyService.js';
 import type { Workflow } from '../types/index.js';
 /**
- * Clean up the historyService subscription created at module initialisation.
- * Call this when tearing down the history store (e.g., in tests or on app
- * unmount) to prevent memory leaks.
- */
-export declare function cleanupHistorySubscription(): void;
-/**
- * Get the current history state snapshot.
- *
- * Use this for binding to UI elements like undo/redo buttons.
+ * Undo/redo actions for a {@link HistoryStore}.
  *
- * @example
- * ```svelte
- * <script>
- *   import { getHistoryState } from "./historyStore.svelte.js";
- *
- *   const state = $derived(getHistoryState());
- * </script>
- *
- * <button disabled={!state.canUndo} onclick={historyActions.undo}>
- *   Undo
- * </button>
- * ```
+ * Bound facade — safe to detach (`onclick={fd.historyBindings.actions.undo}`)
+ * because every entry is bound to its store in the constructor.
  */
-export declare function getHistoryState(): HistoryState;
-/**
- * Convenience getter for canUndo state.
- *
- * @returns Whether undo is currently available
- */
-export declare function getCanUndo(): boolean;
-/**
- * Convenience getter for canRedo state.
- *
- * @returns Whether redo is currently available
- */
-export declare function getCanRedo(): boolean;
-/**
- * Set the callback for restoring workflow state
- *
- * This callback is invoked when undo/redo operations return a workflow.
- * Use this to update the workflow store or other state management.
- *
- * @param callback - Function to call with restored workflow
- */
-export declare function setOnRestoreCallback(callback: ((workflow: Workflow) => void) | null): void;
+export interface HistoryStoreActions {
+    initialize: (workflow: Workflow) => void;
+    pushState: (workflow: Workflow, options?: PushOptions) => void;
+    undo: () => boolean;
+    redo: () => boolean;
+    startTransaction: (workflow: Workflow, description?: string) => void;
+    commitTransaction: () => void;
+    cancelTransaction: () => void;
+    clear: (currentWorkflow?: Workflow) => void;
+    canUndo: () => boolean;
+    canRedo: () => boolean;
+    getState: () => HistoryState;
+}
 /**
- * History actions for undo/redo operations
+ * Reactive rune bindings around a {@link HistoryService}.
  *
- * Use these functions to interact with the history service.
- * They handle the coordination between history and workflow state.
+ * Subscribes to the service on construction; call {@link cleanup} when the
+ * owning instance is destroyed to release the subscription.
  */
-export declare const historyActions: {
+export declare class HistoryStore {
+    #private;
+    /** Bound action facade — see {@link HistoryStoreActions}. */
+    readonly actions: HistoryStoreActions;
+    constructor(service: HistoryService);
     /**
-     * Initialize history with the current workflow
+     * The current history state snapshot.
+     *
+     * Use this for binding to UI elements like undo/redo buttons.
      *
-     * Call this when loading a new workflow to reset history.
+     * @example
+     * ```svelte
+     * <script>
+     *   const fd = getInstance();
+     *   const state = $derived(fd.historyBindings.state);
+     * </script>
      *
-     * @param workflow - The initial workflow state
+     * <button disabled={!state.canUndo} onclick={fd.historyBindings.actions.undo}>
+     *   Undo
+     * </button>
+     * ```
      */
-    initialize: (workflow: Workflow) => void;
+    get state(): HistoryState;
+    /** Whether undo is currently available (reactive). */
+    get canUndo(): boolean;
+    /** Whether redo is currently available (reactive). */
+    get canRedo(): boolean;
     /**
-     * Push the current state to history before making changes
+     * Set the callback for restoring workflow state.
      *
-     * Call this BEFORE modifying the workflow to capture the "before" state.
+     * This callback is invoked when undo/redo operations return a workflow.
+     * Use this to update the workflow store or other state management.
+     */
+    setOnRestoreCallback(callback: ((workflow: Workflow) => void) | null): void;
+    /**
+     * Release the history service subscription.
+     * Called by the owning instance's destroy(); safe to call repeatedly.
+     */
+    cleanup(): void;
+    /** Initialize history with the current workflow (resets history). */
+    initialize(workflow: Workflow): void;
+    /**
+     * Push the current state to history before making changes.
      *
-     * @param workflow - The current workflow state (before changes)
-     * @param options - Options for this history entry
+     * Call this BEFORE modifying the workflow to capture the "before" state.
      */
-    pushState: (workflow: Workflow, options?: PushOptions) => void;
+    pushState(workflow: Workflow, options?: PushOptions): void;
     /**
-     * Undo the last change
+     * Undo the last change.
      *
      * Restores the previous workflow state and invokes the restore callback.
      *
      * @returns true if undo was successful, false if at beginning of history
      */
-    undo: () => boolean;
+    undo(): boolean;
     /**
-     * Redo the last undone change
+     * Redo the last undone change.
      *
      * Restores the next workflow state and invokes the restore callback.
      *
      * @returns true if redo was successful, false if at end of history
      */
-    redo: () => boolean;
+    redo(): boolean;
     /**
-     * Start a transaction for grouping multiple changes
+     * Start a transaction for grouping multiple changes.
      *
      * All changes during a transaction are combined into a single undo entry.
-     *
-     * @param workflow - The current workflow state (before changes)
-     * @param description - Description for the combined change
-     */
-    startTransaction: (workflow: Workflow, description?: string) => void;
-    /**
-     * Commit the current transaction
-     */
-    commitTransaction: () => void;
-    /**
-     * Cancel the current transaction without committing
      */
-    cancelTransaction: () => void;
+    startTransaction(workflow: Workflow, description?: string): void;
+    /** Commit the current transaction. */
+    commitTransaction(): void;
+    /** Cancel the current transaction without committing. */
+    cancelTransaction(): void;
     /**
-     * Clear all history
+     * Clear all history.
      *
      * @param currentWorkflow - If provided, keeps this as the initial state
      */
-    clear: (currentWorkflow?: Workflow) => void;
-    /**
-     * Check if undo is available
-     */
-    canUndo: () => boolean;
-    /**
-     * Check if redo is available
-     */
-    canRedo: () => boolean;
-    /**
-     * Get the current history state synchronously
-     *
-     * @returns The current history state
-     */
-    getState: () => HistoryState;
-};
+    clear(currentWorkflow?: Workflow): void;
+}
 export type { HistoryEntry, HistoryState, PushOptions } from '../services/historyService.js';
-export { HistoryService, historyService } from '../services/historyService.js';

package/dist/stores/historyStore.svelte.js

@@ -1,207 +1,181 @@
 /**
  * History Store for FlowDrop (Svelte 5 Runes)
  *
- * Provides reactive Svelte 5 rune-based bindings for the history service.
+ * Provides reactive Svelte 5 rune-based bindings for a history service.
  * Exposes undo/redo state and actions for the workflow editor.
  *
- * @module stores/historyStore
- */
-import { historyService } from '../services/historyService.js';
-// =========================================================================
-// Reactive State (Runes)
-// =========================================================================
-/**
- * Internal reactive state for history, powered by $state.
- */
-let historyState = $state({
-    canUndo: false,
-    canRedo: false,
-    currentIndex: 0,
-    historyLength: 0,
-    isInTransaction: false
-});
-// Subscribe to history service changes and update the rune state.
-// The unsubscribe function is stored so it can be called via
-// cleanupHistorySubscription() when the store is torn down.
-const _unsubscribeHistoryService = historyService.subscribe((state) => {
-    historyState = state;
-});
-/**
- * Clean up the historyService subscription created at module initialisation.
- * Call this when tearing down the history store (e.g., in tests or on app
- * unmount) to prevent memory leaks.
- */
-export function cleanupHistorySubscription() {
-    _unsubscribeHistoryService();
-}
-// =========================================================================
-// Reactive Getters
-// =========================================================================
-/**
- * Get the current history state snapshot.
- *
- * Use this for binding to UI elements like undo/redo buttons.
- *
- * @example
- * ```svelte
- * <script>
- *   import { getHistoryState } from "./historyStore.svelte.js";
- *
- *   const state = $derived(getHistoryState());
- * </script>
- *
- * <button disabled={!state.canUndo} onclick={historyActions.undo}>
- *   Undo
- * </button>
- * ```
- */
-export function getHistoryState() {
-    return historyState;
-}
-/**
- * Convenience getter for canUndo state.
+ * The reactive state lives in the {@link HistoryStore} class — one per
+ * FlowDrop instance, created by `createFlowDropInstance()` and resolved in
+ * components via `getInstance().historyBindings`.
  *
- * @returns Whether undo is currently available
- */
-export function getCanUndo() {
-    return historyState.canUndo;
-}
-/**
- * Convenience getter for canRedo state.
- *
- * @returns Whether redo is currently available
+ * @module stores/historyStore
  */
-export function getCanRedo() {
-    return historyState.canRedo;
-}
+import { HistoryService } from '../services/historyService.js';
 // =========================================================================
-// History Actions
+// HistoryStore (per-instance reactive bindings)
 // =========================================================================
 /**
- * Callback for when workflow state is restored from history
+ * Reactive rune bindings around a {@link HistoryService}.
  *
- * Set this to handle the restored workflow state (e.g., update the workflow store)
+ * Subscribes to the service on construction; call {@link cleanup} when the
+ * owning instance is destroyed to release the subscription.
  */
-let onRestoreCallback = null;
-/**
- * Set the callback for restoring workflow state
- *
- * This callback is invoked when undo/redo operations return a workflow.
- * Use this to update the workflow store or other state management.
- *
- * @param callback - Function to call with restored workflow
- */
-export function setOnRestoreCallback(callback) {
-    onRestoreCallback = callback;
-}
-/**
- * History actions for undo/redo operations
- *
- * Use these functions to interact with the history service.
- * They handle the coordination between history and workflow state.
- */
-export const historyActions = {
+export class HistoryStore {
+    /** Reactive snapshot of the history service state. */
+    #state = $state({
+        canUndo: false,
+        canRedo: false,
+        currentIndex: 0,
+        historyLength: 0,
+        isInTransaction: false
+    });
+    /**
+     * Callback for when workflow state is restored from history.
+     * Invoked when undo/redo operations return a workflow.
+     */
+    #onRestore = null;
+    /** Unsubscribe handle for the service subscription. */
+    #unsubscribe;
+    /** The underlying (non-reactive) history service. */
+    #service;
+    /** Bound action facade — see {@link HistoryStoreActions}. */
+    actions;
+    constructor(service) {
+        this.#service = service;
+        this.#unsubscribe = service.subscribe((state) => {
+            this.#state = state;
+        });
+        this.actions = Object.freeze({
+            initialize: this.initialize.bind(this),
+            pushState: this.pushState.bind(this),
+            undo: this.undo.bind(this),
+            redo: this.redo.bind(this),
+            startTransaction: this.startTransaction.bind(this),
+            commitTransaction: this.commitTransaction.bind(this),
+            cancelTransaction: this.cancelTransaction.bind(this),
+            clear: this.clear.bind(this),
+            canUndo: () => this.#service.canUndo(),
+            canRedo: () => this.#service.canRedo(),
+            getState: () => this.#state
+        });
+    }
+    // -----------------------------------------------------------------------
+    // Reactive getters
+    // -----------------------------------------------------------------------
     /**
-     * Initialize history with the current workflow
+     * The current history state snapshot.
+     *
+     * Use this for binding to UI elements like undo/redo buttons.
      *
-     * Call this when loading a new workflow to reset history.
+     * @example
+     * ```svelte
+     * <script>
+     *   const fd = getInstance();
+     *   const state = $derived(fd.historyBindings.state);
+     * </script>
      *
-     * @param workflow - The initial workflow state
+     * <button disabled={!state.canUndo} onclick={fd.historyBindings.actions.undo}>
+     *   Undo
+     * </button>
+     * ```
      */
-    initialize: (workflow) => {
-        historyService.initialize(workflow);
-    },
+    get state() {
+        return this.#state;
+    }
+    /** Whether undo is currently available (reactive). */
+    get canUndo() {
+        return this.#state.canUndo;
+    }
+    /** Whether redo is currently available (reactive). */
+    get canRedo() {
+        return this.#state.canRedo;
+    }
+    // -----------------------------------------------------------------------
+    // Wiring & lifecycle
+    // -----------------------------------------------------------------------
     /**
-     * Push the current state to history before making changes
+     * Set the callback for restoring workflow state.
      *
-     * Call this BEFORE modifying the workflow to capture the "before" state.
+     * This callback is invoked when undo/redo operations return a workflow.
+     * Use this to update the workflow store or other state management.
+     */
+    setOnRestoreCallback(callback) {
+        this.#onRestore = callback;
+    }
+    /**
+     * Release the history service subscription.
+     * Called by the owning instance's destroy(); safe to call repeatedly.
+     */
+    cleanup() {
+        this.#unsubscribe();
+    }
+    // -----------------------------------------------------------------------
+    // Actions
+    // -----------------------------------------------------------------------
+    /** Initialize history with the current workflow (resets history). */
+    initialize(workflow) {
+        this.#service.initialize(workflow);
+    }
+    /**
+     * Push the current state to history before making changes.
      *
-     * @param workflow - The current workflow state (before changes)
-     * @param options - Options for this history entry
+     * Call this BEFORE modifying the workflow to capture the "before" state.
      */
-    pushState: (workflow, options) => {
-        historyService.push(workflow, options);
-    },
+    pushState(workflow, options) {
+        this.#service.push(workflow, options);
+    }
     /**
-     * Undo the last change
+     * Undo the last change.
      *
      * Restores the previous workflow state and invokes the restore callback.
      *
      * @returns true if undo was successful, false if at beginning of history
      */
-    undo: () => {
-        const previousState = historyService.undo();
-        if (previousState && onRestoreCallback) {
-            onRestoreCallback(previousState);
+    undo() {
+        const previousState = this.#service.undo();
+        if (previousState && this.#onRestore) {
+            this.#onRestore(previousState);
             return true;
         }
         return previousState !== null;
-    },
+    }
     /**
-     * Redo the last undone change
+     * Redo the last undone change.
      *
      * Restores the next workflow state and invokes the restore callback.
      *
      * @returns true if redo was successful, false if at end of history
      */
-    redo: () => {
-        const nextState = historyService.redo();
-        if (nextState && onRestoreCallback) {
-            onRestoreCallback(nextState);
+    redo() {
+        const nextState = this.#service.redo();
+        if (nextState && this.#onRestore) {
+            this.#onRestore(nextState);
             return true;
         }
         return false;
-    },
+    }
     /**
-     * Start a transaction for grouping multiple changes
+     * Start a transaction for grouping multiple changes.
      *
      * All changes during a transaction are combined into a single undo entry.
-     *
-     * @param workflow - The current workflow state (before changes)
-     * @param description - Description for the combined change
      */
-    startTransaction: (workflow, description) => {
-        historyService.startTransaction(workflow, description);
-    },
-    /**
-     * Commit the current transaction
-     */
-    commitTransaction: () => {
-        historyService.commitTransaction();
-    },
-    /**
-     * Cancel the current transaction without committing
-     */
-    cancelTransaction: () => {
-        historyService.cancelTransaction();
-    },
+    startTransaction(workflow, description) {
+        this.#service.startTransaction(workflow, description);
+    }
+    /** Commit the current transaction. */
+    commitTransaction() {
+        this.#service.commitTransaction();
+    }
+    /** Cancel the current transaction without committing. */
+    cancelTransaction() {
+        this.#service.cancelTransaction();
+    }
     /**
-     * Clear all history
+     * Clear all history.
      *
      * @param currentWorkflow - If provided, keeps this as the initial state
      */
-    clear: (currentWorkflow) => {
-        historyService.clear(currentWorkflow);
-    },
-    /**
-     * Check if undo is available
-     */
-    canUndo: () => {
-        return historyService.canUndo();
-    },
-    /**
-     * Check if redo is available
-     */
-    canRedo: () => {
-        return historyService.canRedo();
-    },
-    /**
-     * Get the current history state synchronously
-     *
-     * @returns The current history state
-     */
-    getState: () => {
-        return historyState;
+    clear(currentWorkflow) {
+        this.#service.clear(currentWorkflow);
     }
-};
-export { HistoryService, historyService } from '../services/historyService.js';
+}

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

@@ -0,0 +1,111 @@
+/**
+ * FlowDrop Instance Container
+ *
+ * Holds all per-instance state for one FlowDrop editor: workflow state,
+ * undo/redo history, playground sessions, interrupts, port coordinates,
+ * categories, and pipeline panel state. Creating one container per mount is
+ * what allows multiple FlowDrop editors to coexist on a single page.
+ *
+ * The container is provided to the component tree via Svelte context (see
+ * `getInstance.svelte.ts`). A lazily-created, browser-only default instance
+ * backs the legacy module-level store APIs so existing single-instance
+ * consumers keep working unchanged.
+ *
+ * @module stores/instanceContainer
+ */
+import { HistoryService } from '../services/historyService.js';
+import { WorkflowStore } from './workflowStore.svelte.js';
+import { HistoryStore } from './historyStore.svelte.js';
+import { PlaygroundStore } from './playgroundStore.svelte.js';
+import { InterruptStore } from './interruptStore.svelte.js';
+import { CategoriesStore } from './categoriesStore.svelte.js';
+import { PortCoordinateStore } from './portCoordinateStore.svelte.js';
+import { PipelinePanelStore } from './pipelinePanelStore.svelte.js';
+import { ApiContext } from './apiContext.js';
+import { PortCompatibilityChecker } from '../utils/connections.js';
+import { NodeComponentRegistry } from '../registry/nodeComponentRegistry.js';
+import { FieldComponentRegistry } from '../form/fieldRegistry.js';
+import { WorkflowFormatRegistry } from '../registry/workflowFormatRegistry.js';
+/** Storage key prefix shared by the default instance and legacy consumers. */
+export declare const DEFAULT_DRAFT_PREFIX = "flowdrop:draft";
+/**
+ * All per-instance FlowDrop state.
+ *
+ * Store fields are added phase-by-phase as the module-level stores are
+ * converted to classes (workflow, history bindings, playground, interrupts,
+ * categories, port coordinates, pipeline panel).
+ */
+export interface FlowDropInstance {
+    /** Unique id for this instance (used to scope storage keys). */
+    readonly id: string;
+    /** Prefix for draft localStorage keys — legacy bare prefix for the default instance. */
+    readonly storagePrefix: string;
+    /** Whether this is the page-default instance (legacy storage keys, module-API reachable). */
+    readonly isDefault: boolean;
+    /** Undo/redo engine for this instance. */
+    readonly history: HistoryService;
+    /** Workflow state with dirty tracking and history integration. */
+    readonly workflow: WorkflowStore;
+    /** Reactive rune bindings around `history` (undo/redo button state). */
+    readonly historyBindings: HistoryStore;
+    /** Playground sessions, messages, and execution state. */
+    readonly playground: PlaygroundStore;
+    /** Pending interrupt/confirmation dialogs. */
+    readonly interrupts: InterruptStore;
+    /** Endpoint configuration, auth provider, and API client for this instance. */
+    readonly api: ApiContext;
+    /** Node component registry, seeded with the built-in node components. */
+    readonly nodes: NodeComponentRegistry;
+    /**
+     * Form field component registry. Starts empty (built-in light fields are
+     * resolved inline); heavy editors are registered on demand via
+     * `registerCodeEditorField(fd.fields)` etc.
+     */
+    readonly fields: FieldComponentRegistry;
+    /** Workflow format registry, seeded with the flowdrop + agentspec adapters. */
+    readonly formats: WorkflowFormatRegistry;
+    /** Node category definitions. */
+    readonly categories: CategoriesStore;
+    /**
+     * Port-to-port data-type compatibility checker for this instance.
+     * Seeded with `DEFAULT_PORT_CONFIG`; re-initialized by mount after the
+     * backend's port config is fetched.
+     */
+    readonly portCompatibility: PortCompatibilityChecker;
+    /** Canvas port coordinates. */
+    readonly portCoordinates: PortCoordinateStore;
+    /** Pipeline panel open/close state (instance-scoped persistence). */
+    readonly pipelinePanel: PipelinePanelStore;
+    /**
+     * Dispose all per-instance resources (subscriptions, effect roots,
+     * external callbacks). Safe to call more than once. Must not touch
+     * sibling instances.
+     */
+    destroy(): void;
+}
+export interface CreateInstanceOptions {
+    /** Explicit instance id; auto-generated (`fd-<n>`) when omitted. */
+    id?: string;
+    /**
+     * Marks the page-default instance: it keeps the legacy (unscoped) storage
+     * keys and reuses the exported `historyService` singleton so legacy
+     * imports keep operating on the same history stack.
+     */
+    isDefault?: boolean;
+}
+/**
+ * Create a fully wired FlowDrop instance.
+ *
+ * Creation order matters: history first, then stores that depend on it
+ * (constructor injection — no module-singleton imports).
+ */
+export declare function createFlowDropInstance(options?: CreateInstanceOptions): FlowDropInstance;
+/**
+ * Get the page-default FlowDrop instance, creating it on first access.
+ *
+ * **Browser-only.** Reactive per-user state must never live at module scope
+ * on the server — a module-level default would leak between SvelteKit
+ * requests. Server renders must provide an instance via context instead
+ * (`<App>` and `<WorkflowEditor>` do this automatically).
+ */
+export declare function getDefaultInstance(): FlowDropInstance;