@flowdrop/flowdrop 1.15.0 → 2.0.0-beta.1

package/dist/index.js

@@ -1,64 +1,41 @@
 /**
  * FlowDrop - Visual Workflow Editor Library
  *
- * A Svelte 5 component library built on @xyflow/svelte for creating node-based workflow editors.
+ * A Svelte 5 component library built on @xyflow/svelte for creating node-based
+ * workflow editors.
  *
- * ## Module Structure (Tree-Shakable)
+ * ## The main entry is a minimal front door
  *
- * For optimal bundle size, import from specific sub-modules:
+ * This entry point intentionally exposes only the small surface most apps need
+ * to get started: the `App` component, the `mountFlowDropApp` / `unmountFlowDropApp`
+ * mount helpers, instance plumbing (`createFlowDropInstance` / `getInstance` /
+ * `provideInstance`), endpoint + auth helpers, and the core public types. It does
+ * NOT re-export the entire library.
  *
- * - `@flowdrop/flowdrop/core` - Types and utilities only (no heavy deps)
- * - `@flowdrop/flowdrop/editor` - WorkflowEditor with @xyflow/svelte
+ * Everything else lives in focused sub-modules — import from the one you need:
+ *
+ * - `@flowdrop/flowdrop/core` - Types, utilities, theme/skin, messages helpers (no heavy deps)
+ * - `@flowdrop/flowdrop/editor` - WorkflowEditor, registries, stores, services (adds @xyflow/svelte)
  * - `@flowdrop/flowdrop/form` - SchemaForm with basic fields
- * - `@flowdrop/flowdrop/form/code` - Code editor support (adds CodeMirror)
- * - `@flowdrop/flowdrop/form/markdown` - Markdown editor support (CodeMirror 6)
+ * - `@flowdrop/flowdrop/form/code` - Code editor field (adds CodeMirror)
+ * - `@flowdrop/flowdrop/form/markdown` - Markdown editor field (CodeMirror 6)
  * - `@flowdrop/flowdrop/display` - MarkdownDisplay (adds marked)
  * - `@flowdrop/flowdrop/playground` - Playground for interactive workflow testing
+ * - `@flowdrop/flowdrop/settings` - Settings stores, services, components
  * - `@flowdrop/flowdrop/styles` - CSS styles
  *
- * ## Legacy Import (Full Bundle)
- *
- * Importing from the main entry point includes everything:
- *
- * ```typescript
- * import { WorkflowEditor, SchemaForm } from "@flowdrop/flowdrop";
- * ```
- *
- * **Note**: This will bundle ALL dependencies including @xyflow/svelte,
- * CodeMirror and marked. For smaller bundles, use sub-modules.
- *
  * @module flowdrop
  */
 // ============================================================================
-// IMPORTANT: This module re-exports from sub-modules for backward compatibility.
-// New code should import directly from sub-modules for better tree-shaking.
-//
-// The wildcard re-exports below are intentional: each sub-module barrel uses
-// explicit named exports, so the public API surface is fully controlled there.
-// ============================================================================
-// ============================================================================
-// Core Exports (Types & Utilities - No Heavy Dependencies)
-// ============================================================================
-export * from './core/index.js';
-// ============================================================================
-// Form Exports
-// ============================================================================
-export * from './form/index.js';
-// Note: Heavy form fields (code, markdown) are NOT auto-registered.
-// Users must import from form/code or form/markdown and register explicitly.
-// ============================================================================
-// Display Exports
-// ============================================================================
-export * from './display/index.js';
-// ============================================================================
-// Playground Exports
-// ============================================================================
-export * from './playground/index.js';
-// ============================================================================
-// Editor Exports (includes @xyflow/svelte and auto-registers builtin nodes)
-// ============================================================================
-export * from './editor/index.js';
-// ============================================================================
-// Settings Exports (stores, services, components, types)
-// ============================================================================
-export * from './settings/index.js';
+// Values
+// ============================================================================
+// App component + vanilla-JS mount lifecycle.
+export { default as App } from './components/App.svelte';
+export { mountFlowDropApp, unmountFlowDropApp } from './svelte-app.js';
+// Instance plumbing — per-instance state container + Svelte context helpers.
+export { createFlowDropInstance } from './stores/instanceContainer.svelte.js';
+export { getInstance, provideInstance } from './stores/getInstance.svelte.js';
+// Endpoint configuration helpers.
+export { createEndpointConfig, defaultEndpointConfig } from './config/endpoints.js';
+// Authentication providers.
+export { NoAuthProvider, StaticAuthProvider, CallbackAuthProvider } from './types/auth.js';

package/dist/messages/defaults.d.ts

@@ -279,12 +279,8 @@ export declare const defaultMessages: {
             readonly predefinedRun: "Run workflow";
         };
         readonly states: {
-            readonly viewOnlyTitle: "View only";
-            readonly viewOnlyText: "This playground is in view-only mode. No inputs are available.";
             readonly newSessionTitle: "New session";
             readonly newSessionText: "Test your flow with a prompt";
-            readonly readyTitle: "Ready to run";
-            readonly readyText: "Click Run to execute your workflow";
             readonly processing: "Processing...";
             readonly viewOnlyHelp: "View-only mode. Workflow execution is controlled externally.";
         };
@@ -342,7 +338,7 @@ export declare const defaultMessages: {
             readonly newSession: "New session";
         };
         readonly controlPanel: {
-            readonly sessionsLabel: "Sessions";
+            readonly sessionsLabel: "Session";
             readonly noSession: "No session";
             readonly switchSession: "Switch session";
             readonly newSession: "New session";
@@ -420,6 +416,7 @@ export declare const defaultMessages: {
             readonly lastRunLabel: "Last Run:";
             readonly durationLabel: "Duration:";
             readonly errorLabel: "Error:";
+            readonly historyLabel: "Runs:";
         };
     };
 };

package/dist/messages/defaults.js

@@ -258,12 +258,8 @@ export const defaultMessages = {
             predefinedRun: 'Run workflow'
         },
         states: {
-            viewOnlyTitle: 'View only',
-            viewOnlyText: 'This playground is in view-only mode. No inputs are available.',
             newSessionTitle: 'New session',
             newSessionText: 'Test your flow with a prompt',
-            readyTitle: 'Ready to run',
-            readyText: 'Click Run to execute your workflow',
             processing: 'Processing...',
             viewOnlyHelp: 'View-only mode. Workflow execution is controlled externally.'
         },
@@ -316,7 +312,7 @@ export const defaultMessages = {
             newSession: 'New session'
         },
         controlPanel: {
-            sessionsLabel: 'Sessions',
+            sessionsLabel: 'Session',
             noSession: 'No session',
             switchSession: 'Switch session',
             newSession: 'New session',
@@ -380,7 +376,8 @@ export const defaultMessages = {
             executionsLabel: 'Executions:',
             lastRunLabel: 'Last Run:',
             durationLabel: 'Duration:',
-            errorLabel: 'Error:'
+            errorLabel: 'Error:',
+            historyLabel: 'Runs:'
         }
     }
 };

package/dist/messages/index.d.ts

@@ -7,5 +7,4 @@
 export { defaultMessages } from './defaults.js';
 export { mergeMessages } from './merge.js';
 export { setMessages, getMessages, m } from './context.js';
-export { warnDeprecatedProp, __resetDeprecationWarningsForTests } from './deprecation.js';
 export type { Messages, MessagesOverride, DeepPartial } from './types.js';

package/dist/messages/index.js

@@ -7,4 +7,3 @@
 export { defaultMessages } from './defaults.js';
 export { mergeMessages } from './merge.js';
 export { setMessages, getMessages, m } from './context.js';
-export { warnDeprecatedProp, __resetDeprecationWarningsForTests } from './deprecation.js';

package/dist/mocks/app-forms.d.ts

@@ -1,2 +1,6 @@
-export function enhance(form: any, options?: {}): (event: any) => void;
-export function applyAction(action: any): any;
+export function enhance(_form: HTMLFormElement, options?: {
+    onResult?: (result: {
+        type: string;
+    }) => void;
+}): (event: SubmitEvent) => void;
+export function applyAction(action: unknown): unknown;

package/dist/mocks/app-forms.js

@@ -1,11 +1,15 @@
-// @ts-nocheck
 /**
  * Mock for $app/forms
  * Provides minimal implementations for SvelteKit forms in library context
  */
 
-// Mock enhance function
-export const enhance = (form, options = {}) => {
+/**
+ * Mock enhance function
+ * @param {HTMLFormElement} _form
+ * @param {{ onResult?: (result: { type: string }) => void }} [options]
+ */
+export const enhance = (_form, options = {}) => {
+  /** @param {SubmitEvent} event */
   return (event) => {
     event.preventDefault();
     // Basic form handling for library context
@@ -15,7 +19,10 @@ export const enhance = (form, options = {}) => {
   };
 };
 
-// Mock applyAction function
+/**
+ * Mock applyAction function
+ * @param {unknown} action
+ */
 export const applyAction = (action) => {
   // No-op for library context
   return action;

package/dist/openapi/v1/openapi.yaml

@@ -3923,9 +3923,9 @@ components:
     WorkflowMetadata:
       type: object
       properties:
-        version:
+        schemaVersion:
           type: string
-          description: Workflow version
+          description: Workflow schema format version — identifies the document format, not the workflow's own revision.
           example: 1.0.0
         createdAt:
           type: string
@@ -3963,7 +3963,7 @@ components:
           example: flowdrop
           default: flowdrop
       required:
-        - version
+        - schemaVersion
         - createdAt
         - updatedAt
     Workflow:

package/dist/playground/index.d.ts

@@ -128,13 +128,12 @@ export { default as MessageBubble } from '../components/playground/MessageBubble
 export { InterruptBubble, ConfirmationPrompt, ChoicePrompt, TextInputPrompt, FormPrompt, ReviewPrompt } from '../components/interrupt/index.js';
 export { PlaygroundService, playgroundService } from '../services/playgroundService.js';
 export { InterruptService, interruptService } from '../services/interruptService.js';
-export { getCurrentSession, getSessions, getMessages, getIsExecuting, getCanSendMessage, getIsLoading, getError as getPlaygroundError, getCurrentWorkflow, getLastPollSequenceNumber, getSessionStatus, getMessageCount, getChatMessages, getLogMessages, getLatestMessage, getInputFields, getHasChatInput, getSessionCount, getActiveExecutionId, getPinnedExecutionId, getLatestExecutionId, getShowLogs, playgroundActions, applyServerResponse, subscribeToSessionStatus, getCurrentSessionId, isSessionSelected, getMessagesSnapshot, getLatestSequenceNumber } from '../stores/playgroundStore.svelte.js';
-export { getPipelinePanelOpen, pipelinePanelActions } from '../stores/pipelinePanelStore.svelte.js';
+export { PlaygroundStore } from '../stores/playgroundStore.svelte.js';
 export type { PlaygroundSession, PlaygroundMessage, PlaygroundInputField, PlaygroundMessageRequest, PlaygroundMessagesResult, PlaygroundConfig, PlaygroundMode, PlaygroundSessionStatus, PlaygroundMessageRole, PlaygroundMessageLevel, PlaygroundMessageMetadata, PlaygroundApiResponse, PlaygroundSessionsResponse, PlaygroundSessionResponse, PlaygroundMessageResponse, PlaygroundMessagesApiResponse, PlaygroundExecution } from '../types/playground.js';
 export { isChatInputNode, CHAT_INPUT_PATTERNS, defaultShouldStopPolling, defaultIsTerminalStatus, DEFAULT_STOP_POLLING_STATUSES, DEFAULT_TERMINAL_STATUSES } from '../types/playground.js';
 export type { InterruptType, InterruptStatus, Interrupt, InterruptChoice, InterruptConfig, ConfirmationConfig, ChoiceConfig, TextConfig, FormConfig, ReviewConfig, ReviewChange, ReviewFieldDecision, ReviewResolution, InterruptResolution, InterruptApiResponse, InterruptListResponse, InterruptResponse, InterruptMessageMetadata, InterruptPollingConfig } from '../types/interrupt.js';
 export { isInterruptMetadata, extractInterruptMetadata, metadataToInterrupt, defaultInterruptPollingConfig } from '../types/interrupt.js';
-export { getInterruptsMap, getPendingInterruptIds, getPendingInterrupts, getPendingInterruptCount, getResolvedInterrupts, getIsAnySubmitting, interruptActions, getInterrupt, isInterruptPending, isInterruptSubmitting, getInterruptError, getInterruptByMessageId, interruptHasError } from '../stores/interruptStore.svelte.js';
+export { InterruptStore } from '../stores/interruptStore.svelte.js';
 export type { InterruptWithState } from '../stores/interruptStore.svelte.js';
 export { mountPlayground, unmountPlayground, mountPlaygroundStudio, mountPlaygroundApp, type PlaygroundMountOptions, type PlaygroundStudioMountOptions, type PlaygroundAppMountOptions, type MountedPlayground } from './mount.js';
 export type { PipelineViewDef, PipelineViewProps } from '../types/index.js';

package/dist/playground/index.js

@@ -143,41 +143,13 @@ export { InterruptService, interruptService } from '../services/interruptService
 // ============================================================================
 // Playground Store
 // ============================================================================
-export { 
-// Core state getters
-getCurrentSession, getSessions, getMessages, getIsExecuting, getCanSendMessage, getIsLoading, getError as getPlaygroundError, getCurrentWorkflow, getLastPollSequenceNumber, 
-// Derived getters
-getSessionStatus, getMessageCount, getChatMessages, getLogMessages, getLatestMessage, getInputFields, getHasChatInput, getSessionCount, 
-// Execution getters (used with PipelinePanel / PlaygroundSplit)
-getActiveExecutionId, getPinnedExecutionId, getLatestExecutionId, 
-// UI state
-getShowLogs, 
-// Actions
-playgroundActions, 
-// Server response application (single update path)
-applyServerResponse, 
-// Subscription utility
-subscribeToSessionStatus, 
-// Utilities
-getCurrentSessionId, isSessionSelected, getMessagesSnapshot, getLatestSequenceNumber } from '../stores/playgroundStore.svelte.js';
-// ============================================================================
-// Pipeline Panel Store (open/close state, persisted to localStorage)
-// ============================================================================
-export { getPipelinePanelOpen, pipelinePanelActions } from '../stores/pipelinePanelStore.svelte.js';
+export { PlaygroundStore } from '../stores/playgroundStore.svelte.js';
 export { isChatInputNode, CHAT_INPUT_PATTERNS, defaultShouldStopPolling, defaultIsTerminalStatus, DEFAULT_STOP_POLLING_STATUSES, DEFAULT_TERMINAL_STATUSES } from '../types/playground.js';
 export { isInterruptMetadata, extractInterruptMetadata, metadataToInterrupt, defaultInterruptPollingConfig } from '../types/interrupt.js';
 // ============================================================================
 // Interrupt Store (Human-in-the-Loop)
 // ============================================================================
-export { 
-// Core state accessor
-getInterruptsMap, 
-// Getter functions (replace derived stores)
-getPendingInterruptIds, getPendingInterrupts, getPendingInterruptCount, getResolvedInterrupts, getIsAnySubmitting, 
-// Actions
-interruptActions, 
-// Utilities
-getInterrupt, isInterruptPending, isInterruptSubmitting, getInterruptError, getInterruptByMessageId, interruptHasError } from '../stores/interruptStore.svelte.js';
+export { InterruptStore } from '../stores/interruptStore.svelte.js';
 // ============================================================================
 // Playground Mount Functions (for vanilla JS / Drupal / IIFE integration)
 // ============================================================================

package/dist/playground/mount.d.ts

@@ -114,6 +114,21 @@ export interface PlaygroundMountOptions {
      * `settings` option.
      */
     settings?: PartialSettings;
+    /**
+     * Identifier for this playground's FlowDrop instance.
+     *
+     * When omitted, the playground uses the page-default instance — matching
+     * the legacy behavior where all playground mounts (and the editor's
+     * built-in playground) shared one session/message store. Pass an explicit
+     * id to isolate this playground's session/message *state* from other
+     * FlowDrop instances on the page.
+     *
+     * Note: live polling is NOT isolated — `playgroundService` keeps one
+     * page-global polling timer, so only one playground can actively poll at
+     * a time regardless of instance. Use `pushMessages()` with your own
+     * transport if two playgrounds need concurrent live updates.
+     */
+    instanceId?: string;
 }
 /**
  * Return type for mounted Playground instance

package/dist/playground/mount.js

@@ -49,9 +49,8 @@ import PlaygroundModal from '../components/playground/PlaygroundModal.svelte';
 import PlaygroundStudio from '../components/playground/PlaygroundStudio.svelte';
 import PlaygroundApp from '../components/playground/PlaygroundApp.svelte';
 import { initializeSettings } from '../stores/settingsStore.svelte.js';
-import { setEndpointConfig } from '../services/api.js';
 import { playgroundService } from '../services/playgroundService.js';
-import { getCurrentSession, getSessions, getMessages, getIsExecuting, playgroundActions, applyServerResponse, subscribeToSessionStatus } from '../stores/playgroundStore.svelte.js';
+import { createFlowDropInstance, getDefaultInstance } from '../stores/instanceContainer.svelte.js';
 async function resolveEndpointConfig(endpointConfig) {
     if (!endpointConfig)
         return undefined;
@@ -61,7 +60,8 @@ async function resolveEndpointConfig(endpointConfig) {
         ...endpointConfig,
         endpoints: { ...defaultEndpointConfig.endpoints, ...endpointConfig.endpoints }
     };
-    setEndpointConfig(resolved);
+    // The resolved config is passed to the Playground component, which configures
+    // its instance's ApiContext (fd.api) — no module-level state to set here.
     return resolved;
 }
 /**
@@ -86,33 +86,52 @@ function sizeContainer(container, height, width) {
     if (width !== undefined)
         container.style.width = width;
 }
-function buildMountedPlayground(svelteApp, workflowId, config, onSessionStatusChange) {
+/**
+ * Resolve the FlowDrop instance for a playground mount. No `instanceId` →
+ * the page-default instance (legacy shared-store behavior); an explicit id →
+ * a fresh isolated instance owned (and destroyed) by this mount.
+ */
+function acquirePlaygroundInstance(instanceId) {
+    if (instanceId) {
+        return { fd: createFlowDropInstance({ id: instanceId }), ownsInstance: true };
+    }
+    return { fd: getDefaultInstance(), ownsInstance: false };
+}
+function buildMountedPlayground(svelteApp, workflowId, config, fd, ownsInstance, onSessionStatusChange) {
     const pollingInterval = config.pollingInterval ?? 1500;
     const unsubscribeStatus = onSessionStatusChange
-        ? subscribeToSessionStatus(onSessionStatusChange)
+        ? fd.playground.subscribeToSessionStatus(onSessionStatusChange)
         : undefined;
     return {
         destroy: () => {
             unsubscribeStatus?.();
+            // Caution (shared default instance): stopPolling is page-global and
+            // reset() clears state other default-mounted playgrounds rely on —
+            // pass `instanceId` to isolate. Preserved legacy behavior.
             playgroundService.stopPolling();
-            playgroundActions.reset();
+            fd.playground.reset();
+            // Fully dispose instances created for this mount; the shared default
+            // instance only gets the reset above (legacy behavior).
+            if (ownsInstance) {
+                fd.destroy();
+            }
             unmount(svelteApp);
         },
-        getCurrentSession: () => getCurrentSession(),
-        getSessions: () => getSessions(),
-        getMessageCount: () => getMessages().length,
-        isExecuting: () => getIsExecuting(),
+        getCurrentSession: () => fd.playground.currentSession,
+        getSessions: () => fd.playground.sessions,
+        getMessageCount: () => fd.playground.messageCount,
+        isExecuting: () => fd.playground.isExecuting,
         stopPolling: () => playgroundService.stopPolling(),
         startPolling: () => {
-            const session = getCurrentSession();
+            const session = fd.playground.currentSession;
             if (session) {
-                playgroundService.startPolling(session.id, (response) => applyServerResponse(response, session.id), pollingInterval, config.shouldStopPolling, playgroundService.getLastSequenceNumber());
+                playgroundService.startPolling(fd.api.config, session.id, (response) => fd.playground.applyServerResponse(response, session.id), pollingInterval, config.shouldStopPolling, playgroundService.getLastSequenceNumber());
             }
         },
-        pushMessages: (response) => applyServerResponse(response, null),
+        pushMessages: (response) => fd.playground.applyServerResponse(response, null),
         reset: () => {
             playgroundService.stopPolling();
-            playgroundActions.reset();
+            fd.playground.reset();
         }
     };
 }
@@ -146,7 +165,7 @@ function buildMountedPlayground(svelteApp, workflowId, config, onSessionStatusCh
  * ```
  */
 export async function mountPlayground(container, options) {
-    const { workflowId, workflow, mode = 'standalone', initialSessionId, endpointConfig, config = {}, height, width, settings: initialSettings, onClose, onSessionStatusChange } = options;
+    const { workflowId, workflow, mode = 'standalone', initialSessionId, endpointConfig, config = {}, height, width, settings: initialSettings, onClose, onSessionStatusChange, instanceId } = options;
     // Validate required parameters
     if (!workflowId) {
         throw new Error('workflowId is required for mountPlayground()');
@@ -162,6 +181,7 @@ export async function mountPlayground(container, options) {
         endpointConfig,
         settings: initialSettings
     });
+    const { fd, ownsInstance } = acquirePlaygroundInstance(instanceId);
     let targetContainer = container;
     if (mode === 'modal') {
         targetContainer = document.body;
@@ -175,6 +195,7 @@ export async function mountPlayground(container, options) {
             target: targetContainer,
             props: {
                 isOpen: true,
+                instance: fd,
                 workflowId,
                 workflow,
                 initialSessionId,
@@ -192,6 +213,7 @@ export async function mountPlayground(container, options) {
         svelteApp = mount(Playground, {
             target: targetContainer,
             props: {
+                instance: fd,
                 workflowId,
                 workflow,
                 mode,
@@ -202,7 +224,7 @@ export async function mountPlayground(container, options) {
             }
         });
     }
-    return buildMountedPlayground(svelteApp, workflowId, config, onSessionStatusChange);
+    return buildMountedPlayground(svelteApp, workflowId, config, fd, ownsInstance, onSessionStatusChange);
 }
 /**
  * Unmount a Playground instance
@@ -225,7 +247,7 @@ export function unmountPlayground(app) {
     }
 }
 export async function mountPlaygroundStudio(container, options) {
-    const { workflowId, workflow, mode = 'standalone', initialSessionId, endpointConfig, config = {}, height, width, initialPipelineOpen, minChatWidth, initialPipelineWidth, settings: initialSettings, onClose, onSessionNavigate, onSessionStatusChange, pipelineViews } = options;
+    const { workflowId, workflow, mode = 'standalone', initialSessionId, endpointConfig, config = {}, height, width, initialPipelineOpen, minChatWidth, initialPipelineWidth, settings: initialSettings, onClose, onSessionNavigate, onSessionStatusChange, pipelineViews, instanceId } = options;
     if (!workflowId) {
         throw new Error('workflowId is required for mountPlaygroundStudio()');
     }
@@ -239,10 +261,12 @@ export async function mountPlaygroundStudio(container, options) {
         endpointConfig,
         settings: initialSettings
     });
+    const { fd, ownsInstance } = acquirePlaygroundInstance(instanceId);
     sizeContainer(container, height, width);
     const svelteApp = mount(PlaygroundStudio, {
         target: container,
         props: {
+            instance: fd,
             workflowId,
             workflow,
             mode,
@@ -257,7 +281,7 @@ export async function mountPlaygroundStudio(container, options) {
             extraPipelineViews: pipelineViews
         }
     });
-    return buildMountedPlayground(svelteApp, workflowId, config, onSessionStatusChange);
+    return buildMountedPlayground(svelteApp, workflowId, config, fd, ownsInstance, onSessionStatusChange);
 }
 /**
  * Mount the full-page PlaygroundApp (Navbar + PlaygroundStudio) into a container.
@@ -280,7 +304,7 @@ export async function mountPlaygroundStudio(container, options) {
  * ```
  */
 export async function mountPlaygroundApp(container, options) {
-    const { workflowId, workflow, mode = 'standalone', initialSessionId, endpointConfig, config = {}, height, width, showNavbar = true, navbarTitle, primaryActions, showSettings = true, settingsCategories, showSettingsSyncButton, showSettingsResetButton, initialPipelineOpen, minChatWidth, initialPipelineWidth, settings: initialSettings, onClose, onSessionNavigate, onSessionStatusChange } = options;
+    const { workflowId, workflow, mode = 'standalone', initialSessionId, endpointConfig, config = {}, height, width, showNavbar = true, navbarTitle, primaryActions, showSettings = true, settingsCategories, showSettingsSyncButton, showSettingsResetButton, initialPipelineOpen, minChatWidth, initialPipelineWidth, settings: initialSettings, onClose, onSessionNavigate, onSessionStatusChange, instanceId } = options;
     if (!workflowId) {
         throw new Error('workflowId is required for mountPlaygroundApp()');
     }
@@ -297,10 +321,12 @@ export async function mountPlaygroundApp(container, options) {
         endpointConfig,
         settings: initialSettings
     });
+    const { fd, ownsInstance } = acquirePlaygroundInstance(instanceId);
     sizeContainer(container, height, width);
     const svelteApp = mount(PlaygroundApp, {
         target: container,
         props: {
+            instance: fd,
             workflowId,
             workflow,
             mode,
@@ -321,5 +347,5 @@ export async function mountPlaygroundApp(container, options) {
             onSessionNavigate
         }
     });
-    return buildMountedPlayground(svelteApp, workflowId, config, onSessionStatusChange);
+    return buildMountedPlayground(svelteApp, workflowId, config, fd, ownsInstance, onSessionStatusChange);
 }

package/dist/registry/{BaseRegistry.d.ts → BaseRegistry.svelte.d.ts}

@@ -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,18 +23,31 @@
  *       throw new Error(`Already registered: ${item.id}`);
  *     }
  *     this.items.set(item.id, item);
+ *     this.touch();
  *     this.notifyListeners();
  *   }
  * }
  * ```
  */
 export declare class BaseRegistry<K, V> {
+    #private;
     /** Internal storage map */
     protected items: Map<K, V>;
     /** Change listeners */
     private listeners;
     /** Callbacks invoked when the registry is cleared (for resetting flags) */
     private clearCallbacks;
+    /**
+     * Bump the reactive version counter. Subclasses MUST call this after any
+     * mutation of `this.items` so derived reads invalidate.
+     */
+    protected touch(): void;
+    /**
+     * 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.
+     */
+    protected trackVersion(): void;
     /**
      * Unregister an item by key.
      *