@flowdrop/flowdrop 1.13.0 → 1.14.0

package/dist/schemas/v1/workflow.schema.json

@@ -279,6 +279,42 @@
               "description": "Configuration for autocomplete fields (when format is \"autocomplete\")"
             }
           ]
+        },
+        "readOnly": {
+          "type": "boolean",
+          "description": "JSON Schema `readOnly` keyword. When true, the field is displayed but\ncannot be edited (rendered in a disabled state).\n"
+        },
+        "height": {
+          "type": "string",
+          "description": "Editor height as a CSS value (e.g. `200px`).\nApplies to editor fields: `json`/`code`, `markdown`, and `template`.\nDefaults: `200px` (code), `300px` (markdown), `250px` (template).\n"
+        },
+        "darkTheme": {
+          "type": "boolean",
+          "description": "Force the editor's dark theme on or off.\nApplies to `json`/`code` and `template` fields.\nWhen omitted, the editor follows the resolved app theme.\n"
+        },
+        "autoFormat": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether to auto-format JSON on blur.\nApplies to `json`/`code` editor fields.\n"
+        },
+        "showToolbar": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether to show the editor toolbar.\nApplies to `markdown` editor fields.\n"
+        },
+        "showStatusBar": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether to show the editor status bar.\nApplies to `markdown` editor fields.\n"
+        },
+        "spellChecker": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether to enable spell checking.\nApplies to `markdown` editor fields.\n"
+        },
+        "placeholderExample": {
+          "type": "string",
+          "description": "Example template string shown as a placeholder hint.\nApplies to `template` fields.\n"
         }
       },
       "required": [

package/dist/services/playgroundService.d.ts

@@ -7,6 +7,20 @@
  * @module services/playgroundService
  */
 import type { PlaygroundSession, PlaygroundMessage, PlaygroundMessagesApiResponse, PlaygroundSessionStatus } from '../types/playground.js';
+/**
+ * Pagination options for {@link PlaygroundService.getMessages}.
+ * `since`, `before`, and `latest` are mutually exclusive.
+ */
+export interface GetMessagesOptions {
+    /** Forward cursor — only messages with sequenceNumber greater than this value */
+    since?: number;
+    /** Backward cursor — the page of messages immediately older than this sequence number */
+    before?: number;
+    /** Return the most recent `limit` messages (conversation tail) */
+    latest?: boolean;
+    /** Maximum number of messages to return */
+    limit?: number;
+}
 /**
  * Playground Service class
  *
@@ -75,14 +89,19 @@ export declare class PlaygroundService {
      */
     deleteSession(sessionId: string): Promise<void>;
     /**
-     * Get messages from a playground session
+     * Get messages from a playground session.
+     *
+     * Three pagination modes (see the OpenAPI spec for the contract):
+     *  - `since`: forward cursor, returns messages with sequenceNumber > value (polling the live tail)
+     *  - `before`: backward cursor, returns the page immediately older than the value (scroll-up)
+     *  - `latest`: returns the most recent `limit` messages (initial load)
+     * `since`, `before`, and `latest` are mutually exclusive.
      *
      * @param sessionId - The session UUID
-     * @param afterSequence - Optional sequence number cursor — returns only messages with sequenceNumber > this value
-     * @param limit - Maximum number of messages to return
+     * @param options - Pagination options
      * @returns Messages and session status
      */
-    getMessages(sessionId: string, afterSequence?: number, limit?: number): Promise<PlaygroundMessagesApiResponse>;
+    getMessages(sessionId: string, options?: GetMessagesOptions): Promise<PlaygroundMessagesApiResponse>;
     /**
      * Send a message to a playground session
      *

package/dist/services/playgroundService.js

@@ -168,24 +168,35 @@ export class PlaygroundService {
     // Message Handling
     // =========================================================================
     /**
-     * Get messages from a playground session
+     * Get messages from a playground session.
+     *
+     * Three pagination modes (see the OpenAPI spec for the contract):
+     *  - `since`: forward cursor, returns messages with sequenceNumber > value (polling the live tail)
+     *  - `before`: backward cursor, returns the page immediately older than the value (scroll-up)
+     *  - `latest`: returns the most recent `limit` messages (initial load)
+     * `since`, `before`, and `latest` are mutually exclusive.
      *
      * @param sessionId - The session UUID
-     * @param afterSequence - Optional sequence number cursor — returns only messages with sequenceNumber > this value
-     * @param limit - Maximum number of messages to return
+     * @param options - Pagination options
      * @returns Messages and session status
      */
-    async getMessages(sessionId, afterSequence, limit) {
+    async getMessages(sessionId, options = {}) {
         const config = this.getConfig();
         let url = buildEndpointUrl(config, config.endpoints.playground.getMessages, {
             sessionId
         });
         const params = new URLSearchParams();
-        if (afterSequence !== undefined) {
-            params.append('since', afterSequence.toString());
+        if (options.since !== undefined) {
+            params.append('since', options.since.toString());
+        }
+        if (options.before !== undefined) {
+            params.append('before', options.before.toString());
         }
-        if (limit !== undefined) {
-            params.append('limit', limit.toString());
+        if (options.latest) {
+            params.append('latest', 'true');
+        }
+        if (options.limit !== undefined) {
+            params.append('limit', options.limit.toString());
         }
         const queryString = params.toString();
         if (queryString) {
@@ -257,7 +268,9 @@ export class PlaygroundService {
                 return;
             }
             try {
-                const response = await this.getMessages(sessionId, this.lastSequenceNumber ?? undefined);
+                const response = await this.getMessages(sessionId, {
+                    since: this.lastSequenceNumber ?? undefined
+                });
                 // Update last sequence number cursor
                 if (response.data && response.data.length > 0) {
                     const lastMessage = response.data[response.data.length - 1];

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

@@ -6,7 +6,7 @@
  *
  * @module stores/playgroundStore
  */
-import type { PlaygroundSession, PlaygroundMessage, PlaygroundInputField, PlaygroundSessionStatus, PlaygroundMessagesApiResponse } from '../types/playground.js';
+import type { PlaygroundSession, PlaygroundMessage, PlaygroundInputField, PlaygroundSessionStatus, PlaygroundMessagesApiResponse, PlaygroundExecution } from '../types/playground.js';
 import type { Workflow } from '../types/index.js';
 /**
  * Get the current session
@@ -83,6 +83,11 @@ export declare function getSessionCount(): number;
 export declare function getPinnedExecutionId(): string | null;
 export declare function getLatestExecutionId(): string | null;
 export declare function getActiveExecutionId(): string | null;
+/**
+ * Main pipeline runs for the run-switcher. Excludes sub-flow runs, which can't
+ * render their own graph and so aren't user-selectable.
+ */
+export declare function getSelectableExecutions(): PlaygroundExecution[];
 /**
  * Counter that increments whenever new messages arrive and the pipeline display
  * should re-fetch — i.e. when following latest or pinned to the latest execution.
@@ -221,6 +226,22 @@ export declare function getMessagesSnapshot(): PlaygroundMessage[];
  * @returns Sequence number of the last message, or null
  */
 export declare function getLatestSequenceNumber(): number | null;
+/**
+ * Get the sequence number of the oldest loaded message, used as the cursor
+ * for backward "load older" pagination.
+ *
+ * @returns Sequence number of the first message, or null
+ */
+export declare function getOldestSequenceNumber(): number | null;
+/**
+ * Whether older messages exist before the oldest one currently loaded.
+ */
+export declare function getHasOlder(): boolean;
+/**
+ * Set whether older messages remain to be loaded, derived from a
+ * backward-pagination response.
+ */
+export declare function setHasOlder(hasOlder: boolean): void;
 /**
  * Subscribe to session status changes using $effect.root.
  * This is designed for use in non-component contexts (e.g., mount.ts).

package/dist/stores/playgroundStore.svelte.js

@@ -23,6 +23,12 @@ let _sessions = $state([]);
  * Messages in the current session
  */
 let _messages = $state([]);
+/**
+ * Whether older messages exist before the oldest one currently loaded.
+ * Drives the scroll-up "load older" affordance. Reset whenever the message
+ * set is replaced (session switch / clear).
+ */
+let _hasOlder = $state(false);
 /**
  * Whether we are currently loading data
  */
@@ -45,8 +51,19 @@ let _pinnedExecutionId = $state(null);
 let _pipelineRefreshTrigger = $state(0);
 /** Whether log messages are visible in the execution console */
 let _showLogs = $state(true);
-/** Latest execution ID derived from current session's executions list */
-const _latestExecutionId = $derived(_currentSession?.executions?.at(-1)?.id ?? null);
+/**
+ * The main pipeline runs — the single source of truth for "what's selectable".
+ * Sub-flow runs are tracked for classification but excluded here: selecting one
+ * can't show its own graph (the panel renders the main pipeline regardless), so
+ * listing them would be dead UI. Feeds both the run-switcher and "latest".
+ */
+const _selectableExecutions = $derived((_currentSession?.executions ?? []).filter((e) => !e.isSubflow));
+/**
+ * Latest execution ID: the most recent main run, so the sidebar keeps the main
+ * pipeline in focus and never auto-follows a sub-flow. Null when no main run is
+ * known yet — better an empty panel for a poll than the wrong graph.
+ */
+const _latestExecutionId = $derived(_selectableExecutions.at(-1)?.id ?? null);
 /** Active execution: pinned if set, otherwise latest */
 const _activeExecutionId = $derived(_pinnedExecutionId ?? _latestExecutionId);
 // Derived from server status — never manually set.
@@ -231,6 +248,13 @@ export function getLatestExecutionId() {
 export function getActiveExecutionId() {
     return _activeExecutionId;
 }
+/**
+ * Main pipeline runs for the run-switcher. Excludes sub-flow runs, which can't
+ * render their own graph and so aren't user-selectable.
+ */
+export function getSelectableExecutions() {
+    return _selectableExecutions;
+}
 /**
  * Counter that increments whenever new messages arrive and the pipeline display
  * should re-fetch — i.e. when following latest or pinned to the latest execution.
@@ -279,33 +303,57 @@ function sortMessagesChronologically(messageList) {
         return a.id.localeCompare(b.id);
     });
 }
+/**
+ * Whether a message was produced by a nested sub-flow (vs the main pipeline).
+ * `parentPipelineId` is the authoritative signal — non-null means a parent run
+ * triggered this one. Legacy runs that predate the field carry no nesting info,
+ * so they're treated as main runs (by design — we don't reclassify history).
+ */
+function isSubflowMessage(msg) {
+    return msg.parentPipelineId != null;
+}
 /**
  * Syncs the current session's executions list from incoming messages.
- * When a message has a new executionId not yet tracked, adds it as a new execution entry.
+ *
+ * Each message's `executionId` identifies the run that produced it, and
+ * `parentPipelineId` says whether that run is the main pipeline or a nested
+ * sub-flow (see {@link isSubflowMessage}). A run's classification is fixed by
+ * its first sighting — every message from a run reports the same parent — so we
+ * only act on executionIds we haven't seen before. Sub-flows are tracked but
+ * hidden from the run-switcher; a new *main* run clears the pin so the panel
+ * auto-follows it, while sub-flow runs never take focus.
+ *
+ * Executions are appended in arrival order; new runs land at the tail, which is
+ * why "latest" reads the last main run.
  */
 function syncExecutionsFromMessages(messages) {
     if (!_currentSession)
         return;
-    const existingIds = new Set((_currentSession.executions ?? []).map((e) => e.id));
-    const newExecutions = [];
+    const executions = [...(_currentSession.executions ?? [])];
+    const seenIds = new Set(executions.map((e) => e.id));
+    let added = false;
+    let gainedMainRun = false;
     for (const msg of messages) {
-        if (msg.executionId && !existingIds.has(msg.executionId)) {
-            existingIds.add(msg.executionId);
-            newExecutions.push({
-                id: msg.executionId,
-                startedAt: msg.timestamp,
-                status: 'running'
-            });
-        }
+        if (!msg.executionId || seenIds.has(msg.executionId))
+            continue;
+        seenIds.add(msg.executionId);
+        const isSubflow = isSubflowMessage(msg);
+        executions.push({
+            id: msg.executionId,
+            startedAt: msg.timestamp,
+            status: 'running',
+            isSubflow
+        });
+        added = true;
+        if (!isSubflow)
+            gainedMainRun = true;
     }
-    if (newExecutions.length > 0) {
-        _currentSession = {
-            ..._currentSession,
-            executions: [...(_currentSession.executions ?? []), ...newExecutions]
-        };
-        // Clear any manual pin so the panel automatically follows the new run.
+    if (!added)
+        return;
+    _currentSession = { ..._currentSession, executions };
+    // Auto-follow the new main run by dropping any manual pin.
+    if (gainedMainRun)
         _pinnedExecutionId = null;
-    }
 }
 // =========================================================================
 // Actions
@@ -348,22 +396,23 @@ export const playgroundActions = {
                 updatedAt: new Date().toISOString()
             };
         }
-        // Update the latest execution status when the session reaches a terminal state.
-        // Only the last execution can be running at any time (sessions are single-pipeline),
-        // so we only need to check and update the tail entry.
+        // When the session reaches a terminal state, the whole run is finished —
+        // including any sub-flow executions, which may sit anywhere in the list
+        // (not just the tail), so mark every still-running execution terminal.
         // 'idle' means the run finished normally (server returns 'idle' post-completion,
-        // not 'completed'), so map it to 'completed' for the execution entry.
+        // not 'completed'), so map it to 'completed' for the execution entries.
         const terminalExecutionStatus = status === 'failed'
             ? 'failed'
             : status === 'completed' || status === 'idle'
                 ? 'completed'
                 : null;
         if (terminalExecutionStatus && _currentSession?.executions?.length) {
-            const execs = [..._currentSession.executions];
-            const last = execs[execs.length - 1];
-            if (last.status === 'running') {
-                execs[execs.length - 1] = { ...last, status: terminalExecutionStatus };
-                _currentSession = { ..._currentSession, executions: execs };
+            const hasRunning = _currentSession.executions.some((e) => e.status === 'running');
+            if (hasRunning) {
+                _currentSession = {
+                    ..._currentSession,
+                    executions: _currentSession.executions.map((e) => e.status === 'running' ? { ...e, status: terminalExecutionStatus } : e)
+                };
             }
         }
         // Also update in sessions list
@@ -417,7 +466,7 @@ export const playgroundActions = {
      * @param message - The message to add
      */
     addMessage: (message) => {
-        if (_messages.some(m => m.id === message.id))
+        if (_messages.some((m) => m.id === message.id))
             return;
         const seq = message.sequenceNumber ?? 0;
         let lo = 0, hi = _messages.length;
@@ -460,6 +509,7 @@ export const playgroundActions = {
     clearMessages: () => {
         _messages = [];
         _lastPollSequenceNumber = null;
+        _hasOlder = false;
     },
     /**
      * Set the loading state
@@ -533,8 +583,8 @@ export const playgroundActions = {
 export function applyServerResponse(response) {
     if (response.data && response.data.length > 0) {
         playgroundActions.addMessages(response.data);
-        // Refresh pipeline when following latest or pinned to the latest execution.
-        // Skip only when the user is viewing a historical run.
+        // Refresh the pipeline panel when following latest or pinned to the latest
+        // run. Skip when pinned to an older run — a historical view that won't change.
         if (_pinnedExecutionId === null || _pinnedExecutionId === _latestExecutionId) {
             _pipelineRefreshTrigger++;
         }
@@ -584,6 +634,33 @@ export function getLatestSequenceNumber() {
     }
     return null;
 }
+/**
+ * Get the sequence number of the oldest loaded message, used as the cursor
+ * for backward "load older" pagination.
+ *
+ * @returns Sequence number of the first message, or null
+ */
+export function getOldestSequenceNumber() {
+    for (let i = 0; i < _messages.length; i++) {
+        if (_messages[i].sequenceNumber !== undefined) {
+            return _messages[i].sequenceNumber;
+        }
+    }
+    return null;
+}
+/**
+ * Whether older messages exist before the oldest one currently loaded.
+ */
+export function getHasOlder() {
+    return _hasOlder;
+}
+/**
+ * Set whether older messages remain to be loaded, derived from a
+ * backward-pagination response.
+ */
+export function setHasOlder(hasOlder) {
+    _hasOlder = hasOlder;
+}
 /**
  * Subscribe to session status changes using $effect.root.
  * This is designed for use in non-component contexts (e.g., mount.ts).

package/dist/types/playground.d.ts

@@ -62,6 +62,14 @@ export interface PlaygroundExecution {
     id: string;
     startedAt: string;
     status: 'running' | 'completed' | 'failed';
+    /**
+     * Client-derived flag: true when this run is a nested sub-flow rather than a
+     * main pipeline run. Inferred from its messages' `parentPipelineId` (with a
+     * `hierarchy` depth ≥ 2 fallback for legacy runs predating that field). Used
+     * to keep the sidebar on the main pipeline and hide sub-flows from the
+     * run-switcher. Not part of the wire contract — the server never sets this.
+     */
+    isSubflow?: boolean;
 }
 /**
  * Playground session representing a test conversation
@@ -94,7 +102,12 @@ export interface PlaygroundSession {
     createdAt: string;
     /** Last activity timestamp (ISO 8601) */
     updatedAt: string;
-    /** Pipeline executions triggered within this session, ordered oldest-first */
+    /**
+     * Main pipeline runs triggered within this session, ordered oldest-first.
+     * Sub-flow (nested) runs are excluded — they're surfaced only on individual
+     * messages via `parentPipelineId`. The run-switcher relies on this being
+     * main-runs-only; runs added from messages are classified client-side.
+     */
     executions?: PlaygroundExecution[];
     /** Custom session metadata */
     metadata?: Record<string, unknown>;
@@ -216,6 +229,19 @@ export interface PlaygroundMessage {
     parentMessageId?: string;
     /** Pipeline/execution ID that generated this message */
     executionId?: string | null;
+    /**
+     * Execution ID of the parent pipeline when this message came from a nested
+     * sub-flow; `null`/absent for top-level (main pipeline) messages. Authoritative
+     * nesting signal (unlike the display-only `hierarchy`) — used to keep the main
+     * pipeline in focus and hide sub-flow runs from the run-switcher.
+     */
+    parentPipelineId?: string | null;
+    /**
+     * Execution ID of the top-level pipeline this message ultimately belongs to.
+     * Equals `executionId` for main-pipeline messages; for sub-flow messages it
+     * points to the main run that triggered the sub-flow.
+     */
+    rootPipelineId?: string | null;
     /** Associated node ID (for log/assistant messages) */
     nodeId?: string | null;
     /**
@@ -301,6 +327,12 @@ export interface PlaygroundConfig {
     pollingInterval?: number;
     /** Maximum number of messages to display (default: 500) */
     maxMessages?: number;
+    /**
+     * Number of messages to fetch per page (default: 50).
+     * The initial load fetches the most recent page; scrolling up loads
+     * older pages of this size on demand.
+     */
+    messagePageSize?: number;
     /** Auto-scroll to bottom on new messages (default: true) */
     autoScroll?: boolean;
     /** Show timestamps on messages (default: true) */
@@ -433,8 +465,10 @@ export type PlaygroundMessageResponse = PlaygroundApiResponse<PlaygroundMessage>
  * Type alias for messages list response with polling metadata
  */
 export interface PlaygroundMessagesApiResponse extends PlaygroundApiResponse<PlaygroundMessage[]> {
-    /** Whether there are more messages to fetch */
+    /** Whether more recent messages remain after this page (forward pagination via `since`) */
     hasMore?: boolean;
+    /** Whether older messages exist before the first message in this page (backward pagination via `latest`/`before`) */
+    hasOlder?: boolean;
     /** Current session status */
     sessionStatus?: PlaygroundSessionStatus;
 }

package/package.json

@@ -3,7 +3,7 @@
   "description": "A drop-in visual workflow editor for any web application. You own the backend. You own the data. You own the orchestration.",
   "license": "MIT",
   "private": false,
-  "version": "1.13.0",
+  "version": "1.14.0",
   "author": "Shibin Das (D34dMan)",
   "bugs": {
     "url": "https://github.com/flowdrop-io/flowdrop/issues"
@@ -125,6 +125,12 @@
     },
     "./schema/v1": {
       "default": "./dist/schemas/v1/workflow.schema.json"
+    },
+    "./openapi": {
+      "default": "./dist/openapi/v1/openapi.yaml"
+    },
+    "./openapi/v1": {
+      "default": "./dist/openapi/v1/openapi.yaml"
     }
   },
   "peerDependencies": {