@flowdrop/flowdrop 1.14.0 → 2.0.0-beta.1

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 {};

package/dist/registry/nodeComponentRegistry.js

@@ -8,7 +8,17 @@
  * - External libraries to contribute node types via plugins
  * - Runtime switching between different node visualizations
  */
-import { BaseRegistry } from './BaseRegistry.js';
+import { BaseRegistry } from './BaseRegistry.svelte.js';
+/**
+ * Check if a namespace is valid.
+ * Must be lowercase alphanumeric with optional hyphens.
+ *
+ * @param namespace - The namespace to validate
+ * @returns true if valid
+ */
+export function isValidNamespace(namespace) {
+    return /^[a-z][a-z0-9-]*$/.test(namespace);
+}
 /**
  * Central registry for node component types.
  * Allows built-in and third-party components to be registered and resolved.
@@ -18,7 +28,7 @@ import { BaseRegistry } from './BaseRegistry.js';
  * @example
  * ```typescript
  * // Register a custom node
- * nodeComponentRegistry.register({
+ * fd.nodes.register({
  *     type: "myCustomNode",
  *     displayName: "My Custom Node",
  *     component: MyCustomNodeComponent,
@@ -27,14 +37,37 @@ import { BaseRegistry } from './BaseRegistry.js';
  * });
  *
  * // Get a component
- * const component = nodeComponentRegistry.getComponent("myCustomNode");
+ * const component = fd.nodes.getComponent("myCustomNode");
  * ```
  */
-class NodeComponentRegistry extends BaseRegistry {
+export class NodeComponentRegistry extends BaseRegistry {
     /** Default type to use when requested type is not found */
     defaultType = 'workflowNode';
     /** Initial default type, restored on clear() */
     static INITIAL_DEFAULT_TYPE = 'workflowNode';
+    /**
+     * @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) {
+        super();
+        if (seed?.registrations) {
+            this.registerAll(seed.registrations, true);
+        }
+        if (seed?.defaultType) {
+            this.defaultType = seed.defaultType;
+        }
+    }
+    /**
+     * Clear all registrations and reset default type.
+     */
+    clear() {
+        super.clear();
+        this.defaultType = NodeComponentRegistry.INITIAL_DEFAULT_TYPE;
+        this.touch(); // defaultType changed — invalidate getComponent/getDefaultType reads
+    }
     /**
      * Register a node component type.
      *
@@ -44,7 +77,7 @@ class NodeComponentRegistry extends BaseRegistry {
      *
      * @example
      * ```typescript
-     * nodeComponentRegistry.register({
+     * fd.nodes.register({
      *     type: "fancy",
      *     displayName: "Fancy Node",
      *     component: FancyNode,
@@ -52,19 +85,13 @@ class NodeComponentRegistry extends BaseRegistry {
      * });
      * ```
      */
-    /**
-     * Clear all registrations and reset default type.
-     */
-    clear() {
-        super.clear();
-        this.defaultType = NodeComponentRegistry.INITIAL_DEFAULT_TYPE;
-    }
     register(registration, overwrite = false) {
         if (this.items.has(registration.type) && !overwrite) {
             throw new Error(`Node type "${registration.type}" is already registered. ` +
                 `Use overwrite: true to replace it, or use a namespaced type like "mylib:${registration.type}".`);
         }
         this.items.set(registration.type, registration);
+        this.touch();
         this.notifyListeners();
     }
     /**
@@ -86,6 +113,7 @@ class NodeComponentRegistry extends BaseRegistry {
      * @returns The component if found, or the default component
      */
     getComponent(type) {
+        this.trackVersion(); // reactive dependency (reads items + defaultType directly)
         const registration = this.items.get(type) ?? this.items.get(this.defaultType);
         return registration?.component;
     }
@@ -96,6 +124,7 @@ class NodeComponentRegistry extends BaseRegistry {
      * @returns The metadata if found, undefined otherwise
      */
     getMetadata(type) {
+        this.trackVersion(); // reactive dependency (reads items directly)
         const reg = this.items.get(type);
         if (!reg)
             return undefined;
@@ -119,10 +148,10 @@ class NodeComponentRegistry extends BaseRegistry {
      * @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) {
@@ -168,6 +197,7 @@ class NodeComponentRegistry extends BaseRegistry {
             throw new Error(`Cannot set default to unregistered type: ${type}`);
         }
         this.defaultType = type;
+        this.touch(); // defaultType changed — invalidate getComponent/getDefaultType reads
     }
     /**
      * Get the current default type.
@@ -175,6 +205,7 @@ class NodeComponentRegistry extends BaseRegistry {
      * @returns The default type identifier
      */
     getDefaultType() {
+        this.trackVersion(); // reactive dependency (reads defaultType directly)
         return this.defaultType;
     }
     /**
@@ -186,7 +217,7 @@ class NodeComponentRegistry extends BaseRegistry {
      *
      * @example
      * ```typescript
-     * const oneOf = nodeComponentRegistry.getOneOfOptions();
+     * const oneOf = fd.nodes.getOneOfOptions();
      * // Use in configSchema: { type: "string", oneOf }
      * ```
      */
@@ -204,6 +235,7 @@ class NodeComponentRegistry extends BaseRegistry {
      * @returns The status position, or default "top-right"
      */
     getStatusPosition(type) {
+        this.trackVersion(); // reactive dependency (reads items directly)
         return this.items.get(type)?.statusPosition ?? 'top-right';
     }
     /**
@@ -213,11 +245,197 @@ class NodeComponentRegistry extends BaseRegistry {
      * @returns The status size, or default "md"
      */
     getStatusSize(type) {
+        this.trackVersion(); // reactive dependency (reads items directly)
         return this.items.get(type)?.statusSize ?? 'md';
     }
+    // ==========================================================================
+    // Plugin system
+    // ==========================================================================
+    /**
+     * 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, displayName, component, options = {}) {
+        this.register({
+            type,
+            displayName,
+            component,
+            description: options.description,
+            icon: options.icon,
+            category: options.category ?? 'custom',
+            source: options.source ?? 'custom',
+            statusPosition: options.statusPosition,
+            statusSize: options.statusSize
+        });
+    }
+    /**
+     * 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) {
+        const result = {
+            success: true,
+            namespace: config.namespace,
+            registeredTypes: [],
+            errors: []
+        };
+        // Validate namespace
+        if (!isValidNamespace(config.namespace)) {
+            result.success = false;
+            result.errors.push(`Invalid namespace "${config.namespace}". ` +
+                `Namespace must be lowercase alphanumeric with optional hyphens.`);
+            return result;
+        }
+        // Register each node
+        for (const nodeDef of config.nodes) {
+            try {
+                const namespacedType = createNamespacedType(config.namespace, nodeDef.type);
+                const registration = {
+                    type: namespacedType,
+                    displayName: nodeDef.displayName,
+                    description: nodeDef.description,
+                    component: nodeDef.component,
+                    icon: nodeDef.icon,
+                    category: nodeDef.category ?? 'custom',
+                    source: config.namespace,
+                    statusPosition: nodeDef.statusPosition,
+                    statusSize: nodeDef.statusSize
+                };
+                this.register(registration);
+                result.registeredTypes.push(namespacedType);
+            }
+            catch (error) {
+                result.success = false;
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                result.errors.push(`Failed to register ${config.namespace}:${nodeDef.type}: ${errorMessage}`);
+            }
+        }
+        return result;
+    }
+    /**
+     * Unregister all nodes from a plugin by namespace.
+     *
+     * @param namespace - The plugin namespace to unregister
+     * @returns Array of unregistered type identifiers
+     */
+    unregisterPlugin(namespace) {
+        const unregistered = [];
+        const types = this.getTypes();
+        for (const type of types) {
+            if (type.startsWith(`${namespace}:`)) {
+                if (this.unregister(type)) {
+                    unregistered.push(type);
+                }
+            }
+        }
+        return unregistered;
+    }
+    /**
+     * Get all registered plugins (unique namespaces).
+     *
+     * @returns Array of namespace strings
+     */
+    getRegisteredPlugins() {
+        const sources = new Set();
+        for (const reg of this.getAll()) {
+            if (reg.source && reg.source !== 'flowdrop') {
+                sources.add(reg.source);
+            }
+        }
+        return Array.from(sources);
+    }
+    /**
+     * Get the count of nodes registered by a plugin.
+     *
+     * @param namespace - The plugin namespace
+     * @returns Number of nodes registered by this plugin
+     */
+    getPluginNodeCount(namespace) {
+        return this.getBySource(namespace).length;
+    }
+}
+/**
+ * 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 function createPlugin(namespace, name) {
+    const config = {
+        namespace,
+        name,
+        nodes: []
+    };
+    const builder = {
+        /**
+         * Set plugin version
+         */
+        version(v) {
+            config.version = v;
+            return builder;
+        },
+        /**
+         * Set plugin description
+         */
+        description(desc) {
+            config.description = desc;
+            return builder;
+        },
+        /**
+         * Add a node to the plugin
+         */
+        node(type, displayName, component, options = {}) {
+            config.nodes.push({
+                type,
+                displayName,
+                component,
+                ...options
+            });
+            return builder;
+        },
+        /**
+         * Register the plugin into a node component registry (e.g. `fd.nodes`).
+         */
+        register(registry) {
+            return registry.registerPlugin(config);
+        },
+        /**
+         * Get the config without registering (for testing/inspection)
+         */
+        getConfig() {
+            return { ...config };
+        }
+    };
+    return builder;
 }
-/** Singleton instance of the node component registry */
-export const nodeComponentRegistry = new NodeComponentRegistry();
 /**
  * Helper function to create a namespaced type identifier.
  * Use this to avoid conflicts when registering custom nodes.

package/dist/registry/workflowFormatRegistry.d.ts

@@ -13,7 +13,7 @@
  */
 import type { StandardWorkflow } from '../adapters/WorkflowAdapter.js';
 import type { NodeMetadata, WorkflowFormat } from '../types/index.js';
-import { BaseRegistry } from './BaseRegistry.js';
+import { BaseRegistry } from './BaseRegistry.svelte.js';
 /**
  * Validation result returned by format adapters.
  */
@@ -60,13 +60,15 @@ export interface WorkflowFormatAdapter {
     validate?(workflow: StandardWorkflow): FormatValidationResult;
 }
 /**
- * Central registry for workflow format adapters.
- * Singleton — extends BaseRegistry for shared mechanics.
+ * Per-instance registry for workflow format adapters.
+ * Extends BaseRegistry for shared mechanics; seeded with the built-in
+ * adapters at construction (see `createFlowDropInstance`). Reach it via
+ * `fd.formats`, or supply adapters through the `formatAdapters` mount option.
  *
  * @example
  * ```typescript
  * // Register a custom format
- * workflowFormatRegistry.register({
+ * fd.formats.register({
  *   id: 'n8n',
  *   name: 'n8n Workflow',
  *   export: (workflow) => JSON.stringify(convertToN8n(workflow)),
@@ -74,10 +76,16 @@ export interface WorkflowFormatAdapter {
  * });
  *
  * // Get an adapter
- * const adapter = workflowFormatRegistry.get('n8n');
+ * const adapter = fd.formats.get('n8n');
  * ```
  */
-declare class WorkflowFormatRegistry extends BaseRegistry<string, WorkflowFormatAdapter> {
+export declare class WorkflowFormatRegistry extends BaseRegistry<string, WorkflowFormatAdapter> {
+    /**
+     * @param seed - Optional initial format adapters. When omitted the registry
+     *   starts empty; instances created via `createFlowDropInstance` pass the
+     *   built-in flowdrop + agentspec adapters (see `builtinFormats.ts`).
+     */
+    constructor(seed?: WorkflowFormatAdapter[]);
     /**
      * Register a workflow format adapter.
      *
@@ -117,6 +125,3 @@ declare class WorkflowFormatRegistry extends BaseRegistry<string, WorkflowFormat
         title: string;
     }>;
 }
-/** Singleton instance of the workflow format registry */
-export declare const workflowFormatRegistry: WorkflowFormatRegistry;
-export {};