@flowdrop/flowdrop 1.0.0

package/dist/playground/mount.js

@@ -0,0 +1,235 @@
+/**
+ * Playground Mount Functions
+ *
+ * Provides mount/unmount functions for integrating the Playground component
+ * into any web application. Particularly useful for integration with
+ * vanilla JS, Drupal, WordPress, or other frameworks.
+ *
+ * @module playground/mount
+ *
+ * @example Basic usage in vanilla JavaScript:
+ * ```javascript
+ * const app = await FlowDrop.mountPlayground(
+ *   document.getElementById("playground-container"),
+ *   {
+ *     workflowId: "wf-123",
+ *     endpointConfig: FlowDrop.createEndpointConfig("/api/flowdrop"),
+ *     mode: "standalone"
+ *   }
+ * );
+ *
+ * // Later, to cleanup:
+ * app.destroy();
+ * ```
+ *
+ * @example Drupal integration:
+ * ```javascript
+ * (function (Drupal, FlowDrop) {
+ *   Drupal.behaviors.flowdropPlayground = {
+ *     attach: function (context, settings) {
+ *       const container = document.getElementById("playground-container");
+ *       if (!container || container.dataset.initialized) return;
+ *       container.dataset.initialized = "true";
+ *
+ *       FlowDrop.mountPlayground(container, {
+ *         workflowId: settings.flowdrop.workflowId,
+ *         endpointConfig: FlowDrop.createEndpointConfig(settings.flowdrop.apiBaseUrl),
+ *         mode: "standalone"
+ *       }).then(function (app) {
+ *         container._flowdropApp = app;
+ *       });
+ *     }
+ *   };
+ * })(Drupal, window.FlowDrop);
+ * ```
+ */
+import { mount, unmount } from 'svelte';
+import Playground from '../components/playground/Playground.svelte';
+import PlaygroundModal from '../components/playground/PlaygroundModal.svelte';
+import { setEndpointConfig } from '../services/api.js';
+import { playgroundService } from '../services/playgroundService.js';
+import { getCurrentSession, getSessions, getMessages, playgroundActions, createPollingCallback, subscribeToSessionStatus } from '../stores/playgroundStore.svelte.js';
+/**
+ * Mount the Playground component in a container
+ *
+ * This function mounts the Playground Svelte component into a DOM container,
+ * enabling interactive workflow testing with a chat interface.
+ *
+ * @param container - DOM element to mount the playground into
+ * @param options - Configuration options for the playground
+ * @returns Promise resolving to a MountedPlayground instance
+ *
+ * @example
+ * ```typescript
+ * import { mountPlayground, createEndpointConfig } from "@flowdrop/flowdrop/playground";
+ *
+ * const app = await mountPlayground(
+ *   document.getElementById("playground"),
+ *   {
+ *     workflowId: "wf-123",
+ *     endpointConfig: createEndpointConfig("/api/flowdrop"),
+ *     mode: "standalone",
+ *     config: {
+ *       showTimestamps: true,
+ *       autoScroll: true,
+ *       pollingInterval: 1500
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export async function mountPlayground(container, options) {
+    const { workflowId, workflow, mode = 'standalone', initialSessionId, endpointConfig, config = {}, height = '100%', width = '100%', onClose, onSessionStatusChange } = options;
+    // Validate required parameters
+    if (!workflowId) {
+        throw new Error('workflowId is required for mountPlayground()');
+    }
+    if (!container) {
+        throw new Error('container element is required for mountPlayground()');
+    }
+    // Validate onClose for modal mode
+    if (mode === 'modal' && !onClose) {
+        throw new Error('onClose callback is required for modal mode');
+    }
+    // Set endpoint configuration if provided
+    let finalEndpointConfig;
+    if (endpointConfig) {
+        // Merge with default configuration to ensure all required endpoints are present
+        const { defaultEndpointConfig } = await import('../config/endpoints.js');
+        finalEndpointConfig = {
+            ...defaultEndpointConfig,
+            ...endpointConfig,
+            endpoints: {
+                ...defaultEndpointConfig.endpoints,
+                ...endpointConfig.endpoints
+            }
+        };
+        setEndpointConfig(finalEndpointConfig);
+    }
+    // Handle modal mode differently
+    // For modal mode, PlaygroundModal creates its own backdrop, so we mount directly to body
+    // For other modes, use the provided container
+    let targetContainer = container;
+    if (mode === 'modal') {
+        // For modal mode, create a container in the body
+        // PlaygroundModal will handle the backdrop itself
+        targetContainer = document.body;
+    }
+    else {
+        // Apply container styling for non-modal modes
+        container.style.height = height;
+        container.style.width = width;
+    }
+    // Mount the appropriate component
+    // Separate the mount calls to avoid TypeScript inference issues with different props types
+    let svelteApp;
+    if (mode === 'modal') {
+        svelteApp = mount(PlaygroundModal, {
+            target: targetContainer,
+            props: {
+                isOpen: true,
+                workflowId,
+                workflow,
+                initialSessionId,
+                endpointConfig: finalEndpointConfig,
+                config,
+                onClose: () => {
+                    if (onClose) {
+                        onClose();
+                    }
+                }
+            }
+        });
+    }
+    else {
+        svelteApp = mount(Playground, {
+            target: targetContainer,
+            props: {
+                workflowId,
+                workflow,
+                mode,
+                initialSessionId,
+                endpointConfig: finalEndpointConfig,
+                config,
+                onClose
+            }
+        });
+    }
+    // Store state for cleanup
+    const state = {
+        svelteApp,
+        container: targetContainer,
+        originalContainer: mode === 'modal' ? container : undefined,
+        workflowId
+    };
+    // Create shared polling callback using lifecycle hooks from config
+    const pollingCallback = createPollingCallback(config.isTerminalStatus);
+    const pollingInterval = config.pollingInterval ?? 1500;
+    // Subscribe to session status changes if callback provided
+    let unsubscribeStatus;
+    if (onSessionStatusChange) {
+        unsubscribeStatus = subscribeToSessionStatus(onSessionStatusChange);
+    }
+    // Create the mounted playground interface
+    const mountedPlayground = {
+        destroy: () => {
+            // Unsubscribe from status changes
+            unsubscribeStatus?.();
+            // Stop any active polling
+            playgroundService.stopPolling();
+            // Reset playground state
+            playgroundActions.reset();
+            // Unmount Svelte component
+            unmount(state.svelteApp);
+        },
+        getCurrentSession: () => {
+            return getCurrentSession();
+        },
+        getSessions: () => {
+            return getSessions();
+        },
+        getMessageCount: () => {
+            return getMessages().length;
+        },
+        isExecuting: () => {
+            return playgroundService.isPolling();
+        },
+        stopPolling: () => {
+            playgroundService.stopPolling();
+        },
+        startPolling: () => {
+            const session = getCurrentSession();
+            if (session) {
+                playgroundService.startPolling(session.id, pollingCallback, pollingInterval, config.shouldStopPolling);
+            }
+        },
+        pushMessages: (response) => {
+            pollingCallback(response);
+        },
+        reset: () => {
+            playgroundService.stopPolling();
+            playgroundActions.reset();
+        }
+    };
+    return mountedPlayground;
+}
+/**
+ * Unmount a Playground instance
+ *
+ * Convenience function for destroying a mounted playground.
+ * Equivalent to calling `app.destroy()`.
+ *
+ * @param app - The mounted playground to unmount
+ *
+ * @example
+ * ```typescript
+ * const app = await mountPlayground(container, options);
+ * // ... later
+ * unmountPlayground(app);
+ * ```
+ */
+export function unmountPlayground(app) {
+    if (app && typeof app.destroy === 'function') {
+        app.destroy();
+    }
+}

package/dist/registry/BaseRegistry.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Base Registry
+ *
+ * Generic base class for all FlowDrop registries. Provides the shared
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * class MyRegistry extends BaseRegistry<string, MyItem> {
+ *   register(item: MyItem, overwrite = false): void {
+ *     if (this.items.has(item.id) && !overwrite) {
+ *       throw new Error(`Already registered: ${item.id}`);
+ *     }
+ *     this.items.set(item.id, item);
+ *     this.notifyListeners();
+ *   }
+ * }
+ * ```
+ */
+export declare class BaseRegistry<K, V> {
+    /** Internal storage map */
+    protected items: Map<K, V>;
+    /** Change listeners */
+    private listeners;
+    /** Callbacks invoked when the registry is cleared (for resetting flags) */
+    private clearCallbacks;
+    /**
+     * Unregister an item by key.
+     *
+     * @param key - The key to remove
+     * @returns true if the key was found and removed, false otherwise
+     */
+    unregister(key: K): boolean;
+    /**
+     * Get an item by key.
+     *
+     * @param key - The key to look up
+     * @returns The item if found, undefined otherwise
+     */
+    get(key: K): V | undefined;
+    /**
+     * Check if a key is registered.
+     *
+     * @param key - The key to check
+     * @returns true if the key is registered
+     */
+    has(key: K): boolean;
+    /**
+     * Get all registered keys.
+     *
+     * @returns Array of registered keys
+     */
+    getKeys(): K[];
+    /**
+     * Get all registered values.
+     *
+     * @returns Array of all registered items
+     */
+    getAll(): V[];
+    /**
+     * Subscribe to registry changes.
+     * Called whenever items are registered, unregistered, or cleared.
+     *
+     * @param listener - Callback to invoke on changes
+     * @returns Unsubscribe function
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Register a callback invoked when the registry is cleared.
+     * Useful for resetting module-level registration flags in tests.
+     *
+     * @param callback - Function to call on clear
+     * @returns Unsubscribe function
+     */
+    onClear(callback: () => void): () => void;
+    /**
+     * Clear all registrations.
+     * Invokes onClear callbacks first, then notifies listeners.
+     */
+    clear(): void;
+    /**
+     * Get the count of registered items.
+     */
+    get size(): number;
+    /**
+     * Notify all change listeners.
+     */
+    protected notifyListeners(): void;
+}

package/dist/registry/BaseRegistry.js

@@ -0,0 +1,124 @@
+/**
+ * Base Registry
+ *
+ * Generic base class for all FlowDrop registries. Provides the shared
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * class MyRegistry extends BaseRegistry<string, MyItem> {
+ *   register(item: MyItem, overwrite = false): void {
+ *     if (this.items.has(item.id) && !overwrite) {
+ *       throw new Error(`Already registered: ${item.id}`);
+ *     }
+ *     this.items.set(item.id, item);
+ *     this.notifyListeners();
+ *   }
+ * }
+ * ```
+ */
+export class BaseRegistry {
+    /** Internal storage map */
+    items = new Map();
+    /** Change listeners */
+    listeners = new Set();
+    /** Callbacks invoked when the registry is cleared (for resetting flags) */
+    clearCallbacks = new Set();
+    /**
+     * Unregister an item by key.
+     *
+     * @param key - The key to remove
+     * @returns true if the key was found and removed, false otherwise
+     */
+    unregister(key) {
+        const result = this.items.delete(key);
+        if (result) {
+            this.notifyListeners();
+        }
+        return result;
+    }
+    /**
+     * Get an item by key.
+     *
+     * @param key - The key to look up
+     * @returns The item if found, undefined otherwise
+     */
+    get(key) {
+        return this.items.get(key);
+    }
+    /**
+     * Check if a key is registered.
+     *
+     * @param key - The key to check
+     * @returns true if the key is registered
+     */
+    has(key) {
+        return this.items.has(key);
+    }
+    /**
+     * Get all registered keys.
+     *
+     * @returns Array of registered keys
+     */
+    getKeys() {
+        return Array.from(this.items.keys());
+    }
+    /**
+     * Get all registered values.
+     *
+     * @returns Array of all registered items
+     */
+    getAll() {
+        return Array.from(this.items.values());
+    }
+    /**
+     * Subscribe to registry changes.
+     * Called whenever items are registered, unregistered, or cleared.
+     *
+     * @param listener - Callback to invoke on changes
+     * @returns Unsubscribe function
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /**
+     * Register a callback invoked when the registry is cleared.
+     * Useful for resetting module-level registration flags in tests.
+     *
+     * @param callback - Function to call on clear
+     * @returns Unsubscribe function
+     */
+    onClear(callback) {
+        this.clearCallbacks.add(callback);
+        return () => this.clearCallbacks.delete(callback);
+    }
+    /**
+     * Clear all registrations.
+     * Invokes onClear callbacks first, then notifies listeners.
+     */
+    clear() {
+        this.items.clear();
+        for (const cb of this.clearCallbacks) {
+            cb();
+        }
+        this.notifyListeners();
+    }
+    /**
+     * Get the count of registered items.
+     */
+    get size() {
+        return this.items.size;
+    }
+    /**
+     * Notify all change listeners.
+     */
+    notifyListeners() {
+        for (const listener of this.listeners) {
+            listener();
+        }
+    }
+}

package/dist/registry/builtinFormats.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Built-in Workflow Format Registration
+ *
+ * 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.
+ */
+export declare function registerBuiltinFormats(): void;
+/**
+ * Check if built-in formats have been registered.
+ */
+export declare function areBuiltinFormatsRegistered(): boolean;
+/**
+ * Reset the registration state.
+ * Primarily useful for testing.
+ */
+export declare function resetBuiltinFormatRegistration(): void;

package/dist/registry/builtinFormats.js

@@ -0,0 +1,70 @@
+/**
+ * Built-in Workflow Format Registration
+ *
+ * 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.
+ */
+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.
+ */
+export function registerBuiltinFormats() {
+    if (registered)
+        return;
+    // FlowDrop native — passthrough (StandardWorkflow ↔ JSON)
+    const flowdropAdapter = {
+        id: 'flowdrop',
+        name: 'FlowDrop',
+        description: 'FlowDrop native workflow format',
+        version: '1.0.0',
+        // No nodes — FlowDrop nodes are universal (no formats restriction)
+        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()
+    const agentSpecAdapter = new AgentSpecAdapter();
+    const agentSpecFormatAdapter = {
+        id: 'agentspec',
+        name: 'Agent Spec (Oracle)',
+        description: 'Oracle Open Agent Spec format',
+        version: '1.0.0',
+        export: (workflow) => agentSpecAdapter.exportJSON(workflow),
+        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;
+}
+// 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

@@ -0,0 +1,77 @@
+/**
+ * Built-in Node Components Registration
+ * Registers all default FlowDrop node components with the registry.
+ *
+ * This module is automatically loaded when the library initializes,
+ * ensuring all built-in node types are available without user action.
+ */
+import { type NodeComponentRegistration } from './nodeComponentRegistry.js';
+/**
+ * Source identifier for built-in FlowDrop components
+ */
+export declare const FLOWDROP_SOURCE = "flowdrop";
+/**
+ * Built-in FlowDrop node component registrations.
+ * These are the default node types that ship with FlowDrop.
+ */
+export declare const BUILTIN_NODE_COMPONENTS: NodeComponentRegistration[];
+/**
+ * Alias mapping for type resolution.
+ * 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".
+ *
+ * @param type - The type string to resolve
+ * @returns The canonical type string
+ */
+export declare function resolveBuiltinAlias(type: string): string;
+/**
+ * Check if a type is a built-in FlowDrop type.
+ *
+ * @param type - The type to check
+ * @returns true if this is a built-in type
+ */
+export declare function isBuiltinType(type: string): boolean;
+/**
+ * Get all built-in type identifiers.
+ *
+ * @returns Array of built-in type strings
+ */
+export declare function getBuiltinTypes(): string[];
+/**
+ * Type for built-in node types.
+ * Use this when you specifically need a built-in type.
+ */
+export type BuiltinNodeType = 'workflowNode' | 'simple' | 'square' | 'tool' | 'gateway' | 'note' | 'terminal' | 'idea';
+/**
+ * Array of built-in type strings for runtime validation.
+ */
+export declare const BUILTIN_NODE_TYPES: BuiltinNodeType[];