@flowdrop/flowdrop 1.15.0 → 2.0.0-beta.1

package/dist/registry/{BaseRegistry.js → BaseRegistry.svelte.js}

@@ -5,7 +5,15 @@
  * mechanics: Map storage, subscribe/notify, onClear callbacks, and size tracking.
  *
  * Subclasses define their own `register()` method with domain-appropriate
- * signatures, using `this.items` and `this.notifyListeners()` directly.
+ * signatures, using `this.items`, `this.touch()`, and `this.notifyListeners()`.
+ *
+ * Reactivity: a `.svelte.ts` module so it can hold a `$state` version counter
+ * (`#version`). Every mutating path bumps it via `touch()`; every read method
+ * components derive from reads it once at the top. This makes the plain `Map`
+ * backing store observable to `$derived`/`$effect`, so registrations made
+ * AFTER a component mounts (e.g. `fd.nodes.registerCustom(...)`) invalidate the
+ * derived and trigger a re-render. Mirrors WorkflowStore's `#editVersion`
+ * monotonic-counter precedent (workflowStore.svelte.ts).
  *
  * @example
  * ```typescript
@@ -15,6 +23,7 @@
  *       throw new Error(`Already registered: ${item.id}`);
  *     }
  *     this.items.set(item.id, item);
+ *     this.touch();
  *     this.notifyListeners();
  *   }
  * }
@@ -23,10 +32,30 @@
 export class BaseRegistry {
     /** Internal storage map */
     items = new Map();
+    /**
+     * Reactive version counter. Bumped by `touch()` on every mutation; read by
+     * every observable read method so Svelte tracks the plain Map as a dependency.
+     */
+    #version = $state(0);
     /** Change listeners */
     listeners = new Set();
     /** Callbacks invoked when the registry is cleared (for resetting flags) */
     clearCallbacks = new Set();
+    /**
+     * Bump the reactive version counter. Subclasses MUST call this after any
+     * mutation of `this.items` so derived reads invalidate.
+     */
+    touch() {
+        this.#version++;
+    }
+    /**
+     * Read the reactive version counter. Subclasses that read `this.items`
+     * directly (instead of via `get`/`getAll`/etc.) MUST call this so the access
+     * is tracked as a reactive dependency.
+     */
+    trackVersion() {
+        void this.#version; // reactive dependency
+    }
     /**
      * Unregister an item by key.
      *
@@ -36,6 +65,7 @@ export class BaseRegistry {
     unregister(key) {
         const result = this.items.delete(key);
         if (result) {
+            this.touch();
             this.notifyListeners();
         }
         return result;
@@ -47,6 +77,7 @@ export class BaseRegistry {
      * @returns The item if found, undefined otherwise
      */
     get(key) {
+        this.trackVersion(); // reactive dependency
         return this.items.get(key);
     }
     /**
@@ -56,6 +87,7 @@ export class BaseRegistry {
      * @returns true if the key is registered
      */
     has(key) {
+        this.trackVersion(); // reactive dependency
         return this.items.has(key);
     }
     /**
@@ -64,6 +96,7 @@ export class BaseRegistry {
      * @returns Array of registered keys
      */
     getKeys() {
+        this.trackVersion(); // reactive dependency
         return Array.from(this.items.keys());
     }
     /**
@@ -72,6 +105,7 @@ export class BaseRegistry {
      * @returns Array of all registered items
      */
     getAll() {
+        this.trackVersion(); // reactive dependency
         return Array.from(this.items.values());
     }
     /**
@@ -102,6 +136,7 @@ export class BaseRegistry {
      */
     clear() {
         this.items.clear();
+        this.touch();
         for (const cb of this.clearCallbacks) {
             cb();
         }
@@ -111,6 +146,7 @@ export class BaseRegistry {
      * Get the count of registered items.
      */
     get size() {
+        this.trackVersion(); // reactive dependency
         return this.items.size;
     }
     /**

package/dist/registry/builtinFormats.d.ts

@@ -1,23 +1,14 @@
 /**
- * Built-in Workflow Format Registration
+ * Built-in Workflow Format Adapters
  *
- * Registers the default FlowDrop and Agent Spec format adapters
- * with the workflow format registry.
- *
- * This module is automatically loaded when imported,
- * ensuring built-in formats are available without user action.
- */
-/**
- * Register all built-in workflow format adapters.
- * Safe to call multiple times — will only register once.
+ * Provides the default FlowDrop and Agent Spec format adapters. These are used
+ * to seed each instance's `WorkflowFormatRegistry` (see `instanceContainer`).
  */
-export declare function registerBuiltinFormats(): void;
+import type { WorkflowFormatAdapter } from './workflowFormatRegistry.js';
 /**
- * Check if built-in formats have been registered.
- */
-export declare function areBuiltinFormatsRegistered(): boolean;
-/**
- * Reset the registration state.
- * Primarily useful for testing.
+ * Build the built-in workflow format adapters (FlowDrop native + Agent Spec).
+ *
+ * Returns a fresh array on each call so every instance owns independent
+ * adapter objects (the Agent Spec adapter holds per-conversion state).
  */
-export declare function resetBuiltinFormatRegistration(): void;
+export declare function getBuiltinFormatAdapters(): WorkflowFormatAdapter[];

package/dist/registry/builtinFormats.js

@@ -1,27 +1,18 @@
 /**
- * Built-in Workflow Format Registration
+ * Built-in Workflow Format Adapters
  *
- * Registers the default FlowDrop and Agent Spec format adapters
- * with the workflow format registry.
- *
- * This module is automatically loaded when imported,
- * ensuring built-in formats are available without user action.
+ * Provides the default FlowDrop and Agent Spec format adapters. These are used
+ * to seed each instance's `WorkflowFormatRegistry` (see `instanceContainer`).
  */
-import { workflowFormatRegistry } from './workflowFormatRegistry.js';
 import { AgentSpecAdapter } from '../adapters/agentspec/AgentSpecAdapter.js';
 import { validateForAgentSpecExport } from '../adapters/agentspec/validator.js';
 /**
- * Track whether built-in formats have been registered.
- * Prevents duplicate registration on hot reload.
- */
-let registered = false;
-/**
- * Register all built-in workflow format adapters.
- * Safe to call multiple times — will only register once.
+ * Build the built-in workflow format adapters (FlowDrop native + Agent Spec).
+ *
+ * Returns a fresh array on each call so every instance owns independent
+ * adapter objects (the Agent Spec adapter holds per-conversion state).
  */
-export function registerBuiltinFormats() {
-    if (registered)
-        return;
+export function getBuiltinFormatAdapters() {
     // FlowDrop native — passthrough (StandardWorkflow ↔ JSON)
     const flowdropAdapter = {
         id: 'flowdrop',
@@ -32,7 +23,6 @@ export function registerBuiltinFormats() {
         export: (workflow) => JSON.stringify(workflow, null, 2),
         import: (data) => JSON.parse(data)
     };
-    workflowFormatRegistry.register(flowdropAdapter);
     // Agent Spec — wraps existing AgentSpecAdapter
     // No bundled nodes — Agent Spec node types are user-provided via
     // getDefaultAgentSpecNodeTypes() or custom definitions passed to mountFlowDropApp()
@@ -46,25 +36,5 @@ export function registerBuiltinFormats() {
         import: (data) => agentSpecAdapter.importJSON(data),
         validate: (workflow) => validateForAgentSpecExport(workflow)
     };
-    workflowFormatRegistry.register(agentSpecFormatAdapter);
-    registered = true;
-}
-/**
- * Check if built-in formats have been registered.
- */
-export function areBuiltinFormatsRegistered() {
-    return registered;
-}
-/**
- * Reset the registration state.
- * Primarily useful for testing.
- */
-export function resetBuiltinFormatRegistration() {
-    registered = false;
+    return [flowdropAdapter, agentSpecFormatAdapter];
 }
-// Sync registration flag with registry.clear() for test isolation
-workflowFormatRegistry.onClear(() => {
-    registered = false;
-});
-// Auto-register built-in formats when this module is imported
-registerBuiltinFormats();

package/dist/registry/builtinNodes.d.ts

@@ -20,31 +20,6 @@ export declare const BUILTIN_NODE_COMPONENTS: NodeComponentRegistration[];
  * Maps alternative type names to their canonical registration.
  */
 export declare const BUILTIN_TYPE_ALIASES: Record<string, string>;
-/**
- * Initialize the registry with built-in components.
- * This is called automatically when the library loads.
- *
- * Safe to call multiple times - will only register once.
- *
- * @example
- * ```typescript
- * // Usually not needed - called automatically
- * // But can be called manually if needed
- * registerBuiltinNodes();
- * ```
- */
-export declare function registerBuiltinNodes(): void;
-/**
- * Check if built-in nodes have been registered.
- *
- * @returns true if registerBuiltinNodes() has been called
- */
-export declare function areBuiltinsRegistered(): boolean;
-/**
- * Reset the registration state.
- * Primarily useful for testing.
- */
-export declare function resetBuiltinRegistration(): void;
 /**
  * Get the canonical type for a given type string.
  * Handles aliases like "default" -> "workflowNode".

package/dist/registry/builtinNodes.js

@@ -5,7 +5,7 @@
  * This module is automatically loaded when the library initializes,
  * ensuring all built-in node types are available without user action.
  */
-import { nodeComponentRegistry } from './nodeComponentRegistry.js';
+import {} from './nodeComponentRegistry.js';
 import WorkflowNode from '../components/nodes/WorkflowNode.svelte';
 import SimpleNode from '../components/nodes/SimpleNode.svelte';
 import SquareNode from '../components/nodes/SquareNode.svelte';
@@ -131,49 +131,6 @@ export const BUILTIN_NODE_COMPONENTS = [
 export const BUILTIN_TYPE_ALIASES = {
     default: 'workflowNode'
 };
-/**
- * Track whether built-in nodes have been registered.
- * Prevents duplicate registration on hot reload.
- */
-let builtinsRegistered = false;
-/**
- * Initialize the registry with built-in components.
- * This is called automatically when the library loads.
- *
- * Safe to call multiple times - will only register once.
- *
- * @example
- * ```typescript
- * // Usually not needed - called automatically
- * // But can be called manually if needed
- * registerBuiltinNodes();
- * ```
- */
-export function registerBuiltinNodes() {
-    if (builtinsRegistered) {
-        return;
-    }
-    // Register all built-in components
-    nodeComponentRegistry.registerAll(BUILTIN_NODE_COMPONENTS, true);
-    // Set the default type
-    nodeComponentRegistry.setDefaultType('workflowNode');
-    builtinsRegistered = true;
-}
-/**
- * Check if built-in nodes have been registered.
- *
- * @returns true if registerBuiltinNodes() has been called
- */
-export function areBuiltinsRegistered() {
-    return builtinsRegistered;
-}
-/**
- * Reset the registration state.
- * Primarily useful for testing.
- */
-export function resetBuiltinRegistration() {
-    builtinsRegistered = false;
-}
 /**
  * Get the canonical type for a given type string.
  * Handles aliases like "default" -> "workflowNode".
@@ -216,9 +173,3 @@ export const BUILTIN_NODE_TYPES = [
     'terminal',
     'idea'
 ];
-// Sync registration flag with registry.clear() for test isolation
-nodeComponentRegistry.onClear(() => {
-    builtinsRegistered = false;
-});
-// Auto-register built-ins when this module is imported
-registerBuiltinNodes();

package/dist/registry/index.d.ts

@@ -2,7 +2,6 @@
  * Node Component Registry Module
  * Exports all registry-related functionality.
  */
-export { BaseRegistry } from './BaseRegistry.js';
-export { nodeComponentRegistry, createNamespacedType, parseNamespacedType, type NodeComponentProps, type NodeTypeInfo, type NodeComponentRegistration, type NodeComponentCategory, type StatusPosition, type StatusSize, type NodeRegistrationFilter } from './nodeComponentRegistry.js';
-export { BUILTIN_NODE_COMPONENTS, BUILTIN_NODE_TYPES, FLOWDROP_SOURCE, registerBuiltinNodes, areBuiltinsRegistered, resetBuiltinRegistration, resolveBuiltinAlias, isBuiltinType, getBuiltinTypes, type BuiltinNodeType } from './builtinNodes.js';
-export { registerFlowDropPlugin, unregisterFlowDropPlugin, registerCustomNode, createPlugin, isValidNamespace, getRegisteredPlugins, getPluginNodeCount, type FlowDropPluginConfig, type PluginNodeDefinition, type PluginRegistrationResult } from './plugin.js';
+export { BaseRegistry } from './BaseRegistry.svelte.js';
+export { NodeComponentRegistry, createNamespacedType, parseNamespacedType, createPlugin, isValidNamespace, type NodeComponentProps, type NodeTypeInfo, type NodeComponentRegistration, type NodeComponentCategory, type StatusPosition, type StatusSize, type NodeRegistrationFilter, type FlowDropPluginConfig, type PluginNodeDefinition, type PluginRegistrationResult } from './nodeComponentRegistry.js';
+export { BUILTIN_NODE_COMPONENTS, BUILTIN_NODE_TYPES, FLOWDROP_SOURCE, resolveBuiltinAlias, isBuiltinType, getBuiltinTypes, type BuiltinNodeType } from './builtinNodes.js';

package/dist/registry/index.js

@@ -3,10 +3,8 @@
  * Exports all registry-related functionality.
  */
 // Base registry
-export { BaseRegistry } from './BaseRegistry.js';
-// Core registry
-export { nodeComponentRegistry, createNamespacedType, parseNamespacedType } from './nodeComponentRegistry.js';
+export { BaseRegistry } from './BaseRegistry.svelte.js';
+// Core registry (the class — instances live on `fd.nodes`)
+export { NodeComponentRegistry, createNamespacedType, parseNamespacedType, createPlugin, isValidNamespace } from './nodeComponentRegistry.js';
 // Built-in nodes
-export { BUILTIN_NODE_COMPONENTS, BUILTIN_NODE_TYPES, FLOWDROP_SOURCE, registerBuiltinNodes, areBuiltinsRegistered, resetBuiltinRegistration, resolveBuiltinAlias, isBuiltinType, getBuiltinTypes } from './builtinNodes.js';
-// Plugin system
-export { registerFlowDropPlugin, unregisterFlowDropPlugin, registerCustomNode, createPlugin, isValidNamespace, getRegisteredPlugins, getPluginNodeCount } from './plugin.js';
+export { BUILTIN_NODE_COMPONENTS, BUILTIN_NODE_TYPES, FLOWDROP_SOURCE, resolveBuiltinAlias, isBuiltinType, getBuiltinTypes } from './builtinNodes.js';

package/dist/registry/nodeComponentRegistry.d.ts

@@ -10,7 +10,7 @@
  */
 import type { Component } from 'svelte';
 import type { WorkflowNode } from '../types/index.js';
-import { BaseRegistry } from './BaseRegistry.js';
+import { BaseRegistry } from './BaseRegistry.svelte.js';
 /**
  * Props interface that all node components must accept.
  * Any component registered in the registry must be compatible with these props.
@@ -86,6 +86,73 @@ export interface NodeRegistrationFilter {
     /** Custom filter function */
     predicate?: (registration: NodeComponentRegistration) => boolean;
 }
+/**
+ * Plugin configuration for external libraries.
+ * Use this to register multiple node types from a library.
+ */
+export interface FlowDropPluginConfig {
+    /**
+     * Unique namespace for this plugin.
+     * Used to prefix all node types (e.g., "mylib" -> "mylib:nodename").
+     * Should be lowercase, alphanumeric with optional hyphens.
+     */
+    namespace: string;
+    /** Display name for the plugin (for UI/debugging purposes) */
+    name: string;
+    /** Plugin version (optional, for debugging) */
+    version?: string;
+    /** Description of what this plugin provides */
+    description?: string;
+    /** Node components to register */
+    nodes: PluginNodeDefinition[];
+}
+/**
+ * Simplified node definition for plugins.
+ * Provides a cleaner API than full NodeComponentRegistration.
+ */
+export interface PluginNodeDefinition {
+    /**
+     * Type identifier for this node.
+     * Will be prefixed with the plugin namespace (e.g., "fancy" -> "mylib:fancy").
+     */
+    type: string;
+    /** Display name shown in UI */
+    displayName: string;
+    /** Description of what this node does */
+    description?: string;
+    /** The Svelte component to render */
+    component: Component<NodeComponentProps>;
+    /** Icon in iconify format (e.g., "mdi:star") */
+    icon?: string;
+    /** Category for organizing in UI */
+    category?: NodeComponentCategory;
+    /** Status overlay position */
+    statusPosition?: StatusPosition;
+    /** Status overlay size */
+    statusSize?: StatusSize;
+}
+/**
+ * Result of plugin registration.
+ * Contains information about what was registered and any errors.
+ */
+export interface PluginRegistrationResult {
+    /** Whether all nodes were registered successfully */
+    success: boolean;
+    /** The plugin namespace */
+    namespace: string;
+    /** Array of successfully registered type identifiers (namespaced) */
+    registeredTypes: string[];
+    /** Array of error messages for failed registrations */
+    errors: string[];
+}
+/**
+ * Check if a namespace is valid.
+ * Must be lowercase alphanumeric with optional hyphens.
+ *
+ * @param namespace - The namespace to validate
+ * @returns true if valid
+ */
+export declare function isValidNamespace(namespace: string): boolean;
 /**
  * Central registry for node component types.
  * Allows built-in and third-party components to be registered and resolved.
@@ -95,7 +162,7 @@ export interface NodeRegistrationFilter {
  * @example
  * ```typescript
  * // Register a custom node
- * nodeComponentRegistry.register({
+ * fd.nodes.register({
  *     type: "myCustomNode",
  *     displayName: "My Custom Node",
  *     component: MyCustomNodeComponent,
@@ -104,14 +171,28 @@ export interface NodeRegistrationFilter {
  * });
  *
  * // Get a component
- * const component = nodeComponentRegistry.getComponent("myCustomNode");
+ * const component = fd.nodes.getComponent("myCustomNode");
  * ```
  */
-declare class NodeComponentRegistry extends BaseRegistry<string, NodeComponentRegistration> {
+export declare class NodeComponentRegistry extends BaseRegistry<string, NodeComponentRegistration> {
     /** Default type to use when requested type is not found */
     private defaultType;
     /** Initial default type, restored on clear() */
     private static readonly INITIAL_DEFAULT_TYPE;
+    /**
+     * @param seed - Optional initial registrations and default type. When
+     *   omitted the registry starts empty; instances created via
+     *   `createFlowDropInstance` pass the built-in node components (see
+     *   `builtinNodes.ts`).
+     */
+    constructor(seed?: {
+        registrations?: NodeComponentRegistration[];
+        defaultType?: string;
+    });
+    /**
+     * Clear all registrations and reset default type.
+     */
+    clear(): void;
     /**
      * Register a node component type.
      *
@@ -121,7 +202,7 @@ declare class NodeComponentRegistry extends BaseRegistry<string, NodeComponentRe
      *
      * @example
      * ```typescript
-     * nodeComponentRegistry.register({
+     * fd.nodes.register({
      *     type: "fancy",
      *     displayName: "Fancy Node",
      *     component: FancyNode,
@@ -129,10 +210,6 @@ declare class NodeComponentRegistry extends BaseRegistry<string, NodeComponentRe
      * });
      * ```
      */
-    /**
-     * Clear all registrations and reset default type.
-     */
-    clear(): void;
     register(registration: NodeComponentRegistration, overwrite?: boolean): void;
     /**
      * Register multiple components at once.
@@ -171,10 +248,10 @@ declare class NodeComponentRegistry extends BaseRegistry<string, NodeComponentRe
      * @example
      * ```typescript
      * // Get all visual nodes
-     * const visualNodes = nodeComponentRegistry.filter({ category: "visual" });
+     * const visualNodes = fd.nodes.filter({ category: "visual" });
      *
      * // Get nodes from a specific library
-     * const libNodes = nodeComponentRegistry.filter({ source: "mylib" });
+     * const libNodes = fd.nodes.filter({ source: "mylib" });
      * ```
      */
     filter(filter: NodeRegistrationFilter): NodeComponentRegistration[];
@@ -214,7 +291,7 @@ declare class NodeComponentRegistry extends BaseRegistry<string, NodeComponentRe
      *
      * @example
      * ```typescript
-     * const oneOf = nodeComponentRegistry.getOneOfOptions();
+     * const oneOf = fd.nodes.getOneOfOptions();
      * // Use in configSchema: { type: "string", oneOf }
      * ```
      */
@@ -236,9 +313,100 @@ declare class NodeComponentRegistry extends BaseRegistry<string, NodeComponentRe
      * @returns The status size, or default "md"
      */
     getStatusSize(type: string): StatusSize;
+    /**
+     * Register a single custom node without a full plugin.
+     * Useful for project-specific custom nodes.
+     *
+     * @param type - Type identifier (can be namespaced or plain)
+     * @param displayName - Display name for UI
+     * @param component - Svelte component
+     * @param options - Additional options
+     *
+     * @example
+     * ```typescript
+     * fd.nodes.registerCustom("myproject:special", "Special Node", MyNode, {
+     *     icon: "mdi:star",
+     *     description: "A special node for my project"
+     * });
+     * ```
+     */
+    registerCustom(type: string, displayName: string, component: Component<NodeComponentProps>, options?: {
+        description?: string;
+        icon?: string;
+        category?: NodeComponentCategory;
+        source?: string;
+        statusPosition?: StatusPosition;
+        statusSize?: StatusSize;
+    }): void;
+    /**
+     * Register a FlowDrop plugin with custom node components.
+     * All node types are automatically namespaced with the plugin namespace.
+     *
+     * @param config - Plugin configuration with namespace and node definitions
+     * @returns Result object with registered types and any errors
+     */
+    registerPlugin(config: FlowDropPluginConfig): PluginRegistrationResult;
+    /**
+     * Unregister all nodes from a plugin by namespace.
+     *
+     * @param namespace - The plugin namespace to unregister
+     * @returns Array of unregistered type identifiers
+     */
+    unregisterPlugin(namespace: string): string[];
+    /**
+     * Get all registered plugins (unique namespaces).
+     *
+     * @returns Array of namespace strings
+     */
+    getRegisteredPlugins(): string[];
+    /**
+     * Get the count of nodes registered by a plugin.
+     *
+     * @param namespace - The plugin namespace
+     * @returns Number of nodes registered by this plugin
+     */
+    getPluginNodeCount(namespace: string): number;
 }
-/** Singleton instance of the node component registry */
-export declare const nodeComponentRegistry: NodeComponentRegistry;
+/**
+ * Create a plugin builder for a fluent API experience.
+ *
+ * @param namespace - Plugin namespace
+ * @param name - Plugin name
+ * @returns Plugin builder with chainable methods
+ *
+ * @example
+ * ```typescript
+ * import { createPlugin } from "@flowdrop/flowdrop/editor";
+ *
+ * createPlugin("awesome", "Awesome Nodes")
+ *     .version("1.0.0")
+ *     .node("fancy", "Fancy Node", FancyNode)
+ *     .node("glow", "Glowing Node", GlowNode, { icon: "mdi:lightbulb" })
+ *     .register(fd.nodes);
+ * ```
+ */
+export declare function createPlugin(namespace: string, name: string): {
+    /**
+     * Set plugin version
+     */
+    version(v: string): /*elided*/ any;
+    /**
+     * Set plugin description
+     */
+    description(desc: string): /*elided*/ any;
+    /**
+     * Add a node to the plugin
+     */
+    node(type: string, displayName: string, component: Component<NodeComponentProps>, options?: Partial<Omit<PluginNodeDefinition, "type" | "displayName" | "component">>): /*elided*/ any;
+    /**
+     * Register the plugin into a node component registry (e.g. `fd.nodes`).
+     */
+    register(registry: NodeComponentRegistry): PluginRegistrationResult;
+    /**
+     * Get the config without registering (for testing/inspection)
+     */
+    getConfig(): FlowDropPluginConfig;
+};
 /**
  * Helper function to create a namespaced type identifier.
  * Use this to avoid conflicts when registering custom nodes.
@@ -273,4 +441,3 @@ export declare function parseNamespacedType(namespacedType: string): {
     namespace: string;
     type: string;
 } | null;
-export {};