@flowdrop/flowdrop 1.14.0 → 2.0.0-beta.1

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

@@ -3,30 +3,35 @@
  *
  * Manages category definitions with merged defaults and API-provided overrides.
  * Exposes lookup helpers for icon, color, and label resolution.
+ *
+ * The reactive state lives in the {@link CategoriesStore} class — one per
+ * FlowDrop instance, resolved in components via `getInstance().categories`.
+ *
+ * @module stores/categoriesStore
  */
 import type { CategoryDefinition, NodeCategory } from '../types/index.js';
 /**
- * Get all category definitions, sorted by weight.
- */
-export declare function getCategories(): CategoryDefinition[];
-/**
- * Initialize categories with API data, merging with defaults.
- * API categories override defaults by name; custom categories are appended.
- */
-export declare function initializeCategories(apiCategories: CategoryDefinition[]): void;
-/**
- * Get the display label for a category.
- */
-export declare function getCategoryLabel(category: NodeCategory): string;
-/**
- * Get the icon for a category.
- */
-export declare function getCategoryIcon(category: NodeCategory): string;
-/**
- * Get the color token for a category.
- */
-export declare function getCategoryColor(category: NodeCategory): string;
-/**
- * Get the full category definition, or undefined if not found.
+ * Per-instance category definitions with a derived name→definition lookup.
+ *
+ * Reads go through getters backed by `$state`/`$derived`, so they track
+ * reactively in templates and `$derived`, exactly like the legacy
+ * module-level functions did.
  */
-export declare function getCategoryDefinition(category: NodeCategory): CategoryDefinition | undefined;
+export declare class CategoriesStore {
+    #private;
+    /** All category definitions, sorted by weight (reactive). */
+    get categories(): CategoryDefinition[];
+    /**
+     * Initialize categories with API data, merging with defaults.
+     * API categories override defaults by name; custom categories are appended.
+     */
+    initialize(apiCategories: CategoryDefinition[]): void;
+    /** Get the display label for a category. */
+    getLabel(category: NodeCategory): string;
+    /** Get the icon for a category. */
+    getIcon(category: NodeCategory): string;
+    /** Get the color token for a category. */
+    getColor(category: NodeCategory): string;
+    /** Get the full category definition, or undefined if not found. */
+    getDefinition(category: NodeCategory): CategoryDefinition | undefined;
+}

package/dist/stores/categoriesStore.svelte.js

@@ -3,75 +3,81 @@
  *
  * Manages category definitions with merged defaults and API-provided overrides.
  * Exposes lookup helpers for icon, color, and label resolution.
+ *
+ * The reactive state lives in the {@link CategoriesStore} class — one per
+ * FlowDrop instance, resolved in components via `getInstance().categories`.
+ *
+ * @module stores/categoriesStore
  */
 import { DEFAULT_CATEGORIES } from '../config/defaultCategories.js';
+// =========================================================================
+// CategoriesStore (per-instance reactive state)
+// =========================================================================
 /**
- * Internal reactive state holding the category definitions.
- * Initialized with defaults, updated when API data is fetched.
- */
-let categoriesState = $state([...DEFAULT_CATEGORIES]);
-/**
- * Derived lookup map: category name → CategoryDefinition
+ * Per-instance category definitions with a derived name→definition lookup.
+ *
+ * Reads go through getters backed by `$state`/`$derived`, so they track
+ * reactively in templates and `$derived`, exactly like the legacy
+ * module-level functions did.
  */
-let categoryMap = $derived((() => {
-    const map = new Map();
-    for (const cat of categoriesState) {
-        map.set(cat.name, cat);
+export class CategoriesStore {
+    /**
+     * Reactive state holding the category definitions.
+     * Initialized with defaults, updated when API data is fetched.
+     */
+    #categories = $state([...DEFAULT_CATEGORIES]);
+    /** Derived lookup map: category name → CategoryDefinition. */
+    #categoryMap = $derived((() => {
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity -- rebuilt whole inside $derived, never mutated afterwards
+        const map = new Map();
+        for (const cat of this.#categories) {
+            map.set(cat.name, cat);
+        }
+        return map;
+    })());
+    /** All category definitions, sorted by weight (reactive). */
+    get categories() {
+        return [...this.#categories].sort((a, b) => (a.weight ?? 999) - (b.weight ?? 999));
     }
-    return map;
-})());
-/**
- * Get all category definitions, sorted by weight.
- */
-export function getCategories() {
-    return [...categoriesState].sort((a, b) => (a.weight ?? 999) - (b.weight ?? 999));
-}
-/**
- * Initialize categories with API data, merging with defaults.
- * API categories override defaults by name; custom categories are appended.
- */
-export function initializeCategories(apiCategories) {
-    const defaultMap = new Map();
-    for (const cat of DEFAULT_CATEGORIES) {
-        defaultMap.set(cat.name, cat);
+    /**
+     * Initialize categories with API data, merging with defaults.
+     * API categories override defaults by name; custom categories are appended.
+     */
+    initialize(apiCategories) {
+        const defaultMap = new Map();
+        for (const cat of DEFAULT_CATEGORIES) {
+            defaultMap.set(cat.name, cat);
+        }
+        // API categories override defaults by name
+        for (const cat of apiCategories) {
+            defaultMap.set(cat.name, {
+                ...defaultMap.get(cat.name),
+                ...cat
+            });
+        }
+        this.#categories = Array.from(defaultMap.values());
     }
-    // API categories override defaults by name
-    for (const cat of apiCategories) {
-        defaultMap.set(cat.name, {
-            ...defaultMap.get(cat.name),
-            ...cat
-        });
+    /** Get the display label for a category. */
+    getLabel(category) {
+        const def = this.#categoryMap.get(category);
+        if (def?.label)
+            return def.label;
+        // Auto-generate: capitalize each word
+        return category
+            .split(/[\s_-]+/)
+            .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(' ');
+    }
+    /** Get the icon for a category. */
+    getIcon(category) {
+        return this.#categoryMap.get(category)?.icon ?? 'mdi:folder';
+    }
+    /** Get the color token for a category. */
+    getColor(category) {
+        return this.#categoryMap.get(category)?.color ?? 'var(--fd-node-slate)';
+    }
+    /** Get the full category definition, or undefined if not found. */
+    getDefinition(category) {
+        return this.#categoryMap.get(category);
     }
-    categoriesState = Array.from(defaultMap.values());
-}
-/**
- * Get the display label for a category.
- */
-export function getCategoryLabel(category) {
-    const def = categoryMap.get(category);
-    if (def?.label)
-        return def.label;
-    // Auto-generate: capitalize each word
-    return category
-        .split(/[\s_-]+/)
-        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-        .join(' ');
-}
-/**
- * Get the icon for a category.
- */
-export function getCategoryIcon(category) {
-    return categoryMap.get(category)?.icon ?? 'mdi:folder';
-}
-/**
- * Get the color token for a category.
- */
-export function getCategoryColor(category) {
-    return categoryMap.get(category)?.color ?? 'var(--fd-node-slate)';
-}
-/**
- * Get the full category definition, or undefined if not found.
- */
-export function getCategoryDefinition(category) {
-    return categoryMap.get(category);
 }

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

@@ -0,0 +1,39 @@
+/**
+ * Per-component access to the FlowDrop instance container.
+ *
+ * Components call `getInstance()` during init to resolve the instance
+ * provided by the nearest `<App>` / `<WorkflowEditor>` via Svelte context.
+ * When no provider exists (legacy single-instance usage), it falls back to
+ * the browser-only default instance.
+ *
+ * @module stores/getInstance
+ */
+import { type FlowDropInstance } from './instanceContainer.svelte.js';
+/**
+ * Context key under which the FlowDrop instance is provided.
+ * A Symbol (matching `messages/context.ts`) so consumer context can't collide.
+ */
+export declare const FLOWDROP_INSTANCE_KEY: unique symbol;
+/**
+ * Resolve the FlowDrop instance for the current component tree.
+ *
+ * Must be called during component initialisation (it reads Svelte context).
+ *
+ * Unlike the messages-context fallback (immutable defaults, silent), this
+ * fallback hands out *mutable shared state*, so it warns once in dev and
+ * throws during SSR rather than leaking state across server requests.
+ */
+export declare function getInstance(): FlowDropInstance;
+/**
+ * Resolve and provide the FlowDrop instance for a provider component
+ * (`<App>`, `<WorkflowEditor>`, `<Playground>`, `<PlaygroundStudio>`).
+ *
+ * Must be called during component initialisation. Resolution order:
+ * 1. An explicitly passed instance (from a mount function or consumer)
+ * 2. An instance already in context (provider nested inside another provider)
+ * 3. Browser: the page-default instance (legacy single-instance behavior)
+ *    Server: a fresh per-render instance (no cross-request leakage)
+ *
+ * The resolved instance is (re-)provided via context for all children.
+ */
+export declare function provideInstance(explicit?: FlowDropInstance): FlowDropInstance;

package/dist/stores/getInstance.svelte.js

@@ -0,0 +1,65 @@
+/**
+ * Per-component access to the FlowDrop instance container.
+ *
+ * Components call `getInstance()` during init to resolve the instance
+ * provided by the nearest `<App>` / `<WorkflowEditor>` via Svelte context.
+ * When no provider exists (legacy single-instance usage), it falls back to
+ * the browser-only default instance.
+ *
+ * @module stores/getInstance
+ */
+import { DEV } from 'esm-env';
+import { getContext, setContext } from 'svelte';
+import { createFlowDropInstance, getDefaultInstance } from './instanceContainer.svelte.js';
+/**
+ * Context key under which the FlowDrop instance is provided.
+ * A Symbol (matching `messages/context.ts`) so consumer context can't collide.
+ */
+export const FLOWDROP_INSTANCE_KEY = Symbol('flowdrop.instance');
+let warnedAboutFallback = false;
+/**
+ * Resolve the FlowDrop instance for the current component tree.
+ *
+ * Must be called during component initialisation (it reads Svelte context).
+ *
+ * Unlike the messages-context fallback (immutable defaults, silent), this
+ * fallback hands out *mutable shared state*, so it warns once in dev and
+ * throws during SSR rather than leaking state across server requests.
+ */
+export function getInstance() {
+    const instance = getContext(FLOWDROP_INSTANCE_KEY);
+    if (instance) {
+        return instance;
+    }
+    if (typeof window === 'undefined') {
+        throw new Error('[flowdrop] No FlowDrop instance in context during SSR. Render inside ' +
+            '<App> or <WorkflowEditor> (which set context), or provide one with ' +
+            'setContext(FLOWDROP_INSTANCE_KEY, createFlowDropInstance()).');
+    }
+    if (DEV && !warnedAboutFallback) {
+        warnedAboutFallback = true;
+        // eslint-disable-next-line no-console -- intentional one-time dev diagnostic for silent shared-state fallback
+        console.warn('[flowdrop] getInstance() fell back to the page-default instance — ' +
+            'fine for a single editor, but two editors mounted this way will share state.');
+    }
+    return getDefaultInstance();
+}
+/**
+ * Resolve and provide the FlowDrop instance for a provider component
+ * (`<App>`, `<WorkflowEditor>`, `<Playground>`, `<PlaygroundStudio>`).
+ *
+ * Must be called during component initialisation. Resolution order:
+ * 1. An explicitly passed instance (from a mount function or consumer)
+ * 2. An instance already in context (provider nested inside another provider)
+ * 3. Browser: the page-default instance (legacy single-instance behavior)
+ *    Server: a fresh per-render instance (no cross-request leakage)
+ *
+ * The resolved instance is (re-)provided via context for all children.
+ */
+export function provideInstance(explicit) {
+    const instance = explicit ??
+        getContext(FLOWDROP_INSTANCE_KEY) ??
+        (typeof window === 'undefined' ? createFlowDropInstance() : getDefaultInstance());
+    setContext(FLOWDROP_INSTANCE_KEY, instance);
+    return instance;
+}

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';