@flowdrop/flowdrop 2.9.0 → 2.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/CHANGELOG.md +200 -0
  2. package/dist/commands/executor.js +52 -8
  3. package/dist/commands/types.d.ts +3 -0
  4. package/dist/components/App.svelte +8 -0
  5. package/dist/components/App.svelte.d.ts +6 -0
  6. package/dist/components/CanvasContextMenu.stories.svelte +63 -0
  7. package/dist/components/CanvasContextMenu.stories.svelte.d.ts +19 -0
  8. package/dist/components/CanvasContextMenu.svelte +259 -0
  9. package/dist/components/CanvasContextMenu.svelte.d.ts +16 -0
  10. package/dist/components/CanvasController.svelte +24 -2
  11. package/dist/components/CanvasController.svelte.d.ts +16 -0
  12. package/dist/components/EdgeRefresher.svelte +1 -1
  13. package/dist/components/FlowDropZone.svelte +11 -7
  14. package/dist/components/FlowDropZone.svelte.d.ts +12 -0
  15. package/dist/components/PortCoordinateTracker.svelte +1 -1
  16. package/dist/components/UniversalNode.svelte +12 -13
  17. package/dist/components/WorkflowEditor.svelte +486 -149
  18. package/dist/components/WorkflowEditor.svelte.d.ts +7 -0
  19. package/dist/components/WorkflowInterfaceEditor.svelte +28 -3
  20. package/dist/components/WorkflowInterfaceEntryCard.svelte +112 -2
  21. package/dist/components/WorkflowInterfaceEntryCard.svelte.d.ts +3 -1
  22. package/dist/components/nodes/CaptionNode.stories.svelte +65 -0
  23. package/dist/components/nodes/CaptionNode.stories.svelte.d.ts +18 -0
  24. package/dist/components/nodes/CaptionNode.svelte +313 -0
  25. package/dist/components/nodes/CaptionNode.svelte.d.ts +16 -0
  26. package/dist/components/nodes/NotesNode.svelte +6 -0
  27. package/dist/components/playground/ChatBubble.svelte +2 -0
  28. package/dist/components/playground/ChatInput.svelte +18 -34
  29. package/dist/components/playground/ChatInput.svelte.d.ts +7 -0
  30. package/dist/components/playground/ControlPanel.svelte +27 -0
  31. package/dist/components/playground/ControlPanel.svelte.d.ts +12 -0
  32. package/dist/components/playground/ExecutionLogs.svelte +11 -8
  33. package/dist/components/playground/InterfaceInputForm.svelte +74 -0
  34. package/dist/components/playground/InterfaceInputForm.svelte.d.ts +14 -0
  35. package/dist/components/playground/LogRow.svelte +2 -0
  36. package/dist/components/playground/MessageCard.svelte +15 -3
  37. package/dist/components/playground/MessageNotice.svelte +2 -0
  38. package/dist/components/playground/MessageStream.svelte +87 -23
  39. package/dist/components/playground/OriginBadge.svelte +48 -0
  40. package/dist/components/playground/OriginBadge.svelte.d.ts +7 -0
  41. package/dist/components/playground/Playground.svelte +155 -38
  42. package/dist/components/playground/messageDisplay.d.ts +23 -1
  43. package/dist/components/playground/messageDisplay.js +49 -0
  44. package/dist/config/endpoints.d.ts +65 -0
  45. package/dist/config/endpoints.js +39 -0
  46. package/dist/core/index.d.ts +6 -3
  47. package/dist/core/index.js +2 -1
  48. package/dist/editor/contextMenu.d.ts +107 -0
  49. package/dist/editor/contextMenu.js +134 -0
  50. package/dist/editor/index.d.ts +2 -0
  51. package/dist/editor/index.js +1 -0
  52. package/dist/index.d.ts +1 -1
  53. package/dist/index.js +1 -1
  54. package/dist/messages/defaults.d.ts +63 -0
  55. package/dist/messages/defaults.js +59 -0
  56. package/dist/openapi/v1/openapi.yaml +356 -7
  57. package/dist/playground/commands/registry.js +4 -2
  58. package/dist/playground/index.d.ts +3 -2
  59. package/dist/playground/index.js +2 -1
  60. package/dist/registry/builtinNodeTypes.d.ts +1 -1
  61. package/dist/registry/builtinNodeTypes.js +1 -0
  62. package/dist/registry/builtinNodes.js +13 -0
  63. package/dist/registry/nodeComponentRegistry.d.ts +18 -0
  64. package/dist/registry/nodeComponentRegistry.js +14 -2
  65. package/dist/schemas/v1/workflow.schema.json +22 -1
  66. package/dist/services/historyService.d.ts +1 -1
  67. package/dist/services/historyService.js +2 -2
  68. package/dist/services/playgroundService.d.ts +35 -1
  69. package/dist/services/playgroundService.js +82 -36
  70. package/dist/stores/inlineEditStore.svelte.d.ts +35 -0
  71. package/dist/stores/inlineEditStore.svelte.js +63 -0
  72. package/dist/stores/instanceContainer.svelte.d.ts +6 -0
  73. package/dist/stores/instanceContainer.svelte.js +2 -0
  74. package/dist/stores/playgroundStore.svelte.d.ts +59 -2
  75. package/dist/stores/playgroundStore.svelte.js +128 -2
  76. package/dist/styles/base.css +8 -0
  77. package/dist/styles/tokens.css +8 -0
  78. package/dist/svelte-app.d.ts +15 -0
  79. package/dist/svelte-app.js +6 -4
  80. package/dist/types/index.d.ts +34 -1
  81. package/dist/types/index.js +11 -0
  82. package/dist/types/playground.d.ts +90 -9
  83. package/dist/types/playground.js +12 -4
  84. package/dist/utils/captionText.d.ts +43 -0
  85. package/dist/utils/captionText.js +49 -0
  86. package/dist/utils/focus.d.ts +16 -0
  87. package/dist/utils/focus.js +40 -0
  88. package/dist/utils/nodeTypes.js +1 -0
  89. package/dist/utils/nodeWrapper.js +2 -0
  90. package/dist/utils/workflowInterface.d.ts +83 -1
  91. package/dist/utils/workflowInterface.js +192 -1
  92. package/package.json +2 -2
@@ -10,7 +10,8 @@
10
10
  *
11
11
  * @module stores/playgroundStore
12
12
  */
13
- import { isChatInputNode } from '../types/playground.js';
13
+ import { hasEnableRunFlag, isChatInputNode } from '../types/playground.js';
14
+ import { collectInterfaceInputs, interfaceFormEntries, resolvePlaygroundInputMode } from '../utils/workflowInterface.js';
14
15
  import { logger } from '../utils/logger.js';
15
16
  // =========================================================================
16
17
  // Helper Functions (pure, instance-independent)
@@ -81,6 +82,16 @@ export class PlaygroundStore {
81
82
  #error = $state(null);
82
83
  /** Current workflow being tested */
83
84
  #currentWorkflow = $state(null);
85
+ /** Input mode from the workflow interface — see {@link inputMode}. */
86
+ #inputMode = $derived(resolvePlaygroundInputMode(this.#currentWorkflow?.interface));
87
+ /** Form entries from the workflow interface — see {@link interfaceFormEntries}. */
88
+ #interfaceFormEntries = $derived(this.#inputMode === 'legacy' ? [] : interfaceFormEntries(this.#currentWorkflow?.interface));
89
+ /** Values of the interface input form, keyed by entry id. */
90
+ #formValues = $state({});
91
+ /** What a turn would send now — see {@link turnInputs}. */
92
+ #turnInputs = $derived(collectInterfaceInputs(this.#interfaceFormEntries, this.#formValues));
93
+ /** The sessions door's answer to the last turn — see {@link lastTurn}. */
94
+ #lastTurn = $state(null);
84
95
  /** Last polling cursor for incremental message fetching */
85
96
  #lastPollSequenceNumber = $state(null);
86
97
  /** Execution ID explicitly pinned by the user (null = follow latest) */
@@ -108,6 +119,23 @@ export class PlaygroundStore {
108
119
  // Exception: updateSessionStatus('running') in handleSendMessage is an
109
120
  // acknowledged optimistic write, overwritten by the next server response.
110
121
  #isExecuting = $derived(this.#currentSession?.status === 'running');
122
+ /**
123
+ * Whether a turn request is in flight: from the click until the server has
124
+ * answered. The session only turns `running` once the request has been
125
+ * accepted, so this closes the gap in which a second click could post a
126
+ * second turn.
127
+ */
128
+ #turnPending = $state(false);
129
+ /** How many messages so far carry the legacy `enableRun` flag. */
130
+ #enableRunCount = $derived(this.#messages.filter((m) => hasEnableRunFlag(m.metadata)).length);
131
+ /**
132
+ * The `enableRun` count at the moment Run was clicked under the legacy
133
+ * protocol, or `null` when Run is not locked. Run stays locked until a
134
+ * newer `enableRun` message raises the count past this.
135
+ */
136
+ #runLockedAt = $state(null);
137
+ /** Whether Run is waiting for a backend `enableRun` message. */
138
+ #runLocked = $derived(this.#runLockedAt !== null && this.#enableRunCount <= this.#runLockedAt);
111
139
  /** Cleanups for active subscribeToSessionStatus effect roots. */
112
140
  #statusSubscriptions = new Set();
113
141
  /** Bound mutation facade — see {@link PlaygroundStoreActions}. */
@@ -131,7 +159,12 @@ export class PlaygroundStore {
131
159
  switchSession: this.switchSession.bind(this),
132
160
  pinExecution: this.pinExecution.bind(this),
133
161
  setShowLogs: this.setShowLogs.bind(this),
134
- toggleShowLogs: this.toggleShowLogs.bind(this)
162
+ toggleShowLogs: this.toggleShowLogs.bind(this),
163
+ setTurnPending: this.setTurnPending.bind(this),
164
+ lockRunUntilEnabled: this.lockRunUntilEnabled.bind(this),
165
+ releaseRunLock: this.releaseRunLock.bind(this),
166
+ setFormValues: this.setFormValues.bind(this),
167
+ setLastTurn: this.setLastTurn.bind(this)
135
168
  });
136
169
  }
137
170
  // -----------------------------------------------------------------------
@@ -153,6 +186,23 @@ export class PlaygroundStore {
153
186
  get isExecuting() {
154
187
  return this.#isExecuting;
155
188
  }
189
+ /** Whether a turn request is in flight (see `setTurnPending`). */
190
+ get turnPending() {
191
+ return this.#turnPending;
192
+ }
193
+ /** Whether Run is locked until the backend posts an `enableRun` message. */
194
+ get runLocked() {
195
+ return this.#runLocked;
196
+ }
197
+ /**
198
+ * Whether a Run control may start a turn now. The one gate any Run control
199
+ * reads (the Playground's button today, a canvas run bar later), so they
200
+ * cannot disagree: nothing is running, no request is in flight and the
201
+ * legacy `enableRun` lock is not holding Run back.
202
+ */
203
+ get canRun() {
204
+ return !this.#isExecuting && !this.#turnPending && !this.#runLocked;
205
+ }
156
206
  /** Loading state. */
157
207
  get isLoading() {
158
208
  return this.#isLoading;
@@ -261,6 +311,42 @@ export class PlaygroundStore {
261
311
  });
262
312
  return fields;
263
313
  }
314
+ /**
315
+ * How a turn is collected, read from the workflow interface's turn ports
316
+ * (see {@link PlaygroundInputMode}). `legacy` while no workflow is set or
317
+ * its interface declares no `turn`.
318
+ */
319
+ get inputMode() {
320
+ return this.#inputMode;
321
+ }
322
+ /**
323
+ * The interface inputs a person fills in (inputs without a `turn`), in
324
+ * interface order. Empty in `legacy` mode: there the node-based
325
+ * {@link inputFields} apply.
326
+ */
327
+ get interfaceFormEntries() {
328
+ return this.#interfaceFormEntries;
329
+ }
330
+ /** Values of the interface input form, keyed by entry id. */
331
+ get formValues() {
332
+ return this.#formValues;
333
+ }
334
+ /**
335
+ * What a turn would send now: the form's inputs, or which required inputs
336
+ * are still missing. A Run control can open the form on `missing` instead
337
+ * of failing the request.
338
+ */
339
+ get turnInputs() {
340
+ return this.#turnInputs;
341
+ }
342
+ /**
343
+ * The sessions door's answer (pipelineId, status, userMessageId) for the
344
+ * turn just taken; `null` before any turn, and on the legacy door, which
345
+ * answers with a message row instead.
346
+ */
347
+ get lastTurn() {
348
+ return this.#lastTurn;
349
+ }
264
350
  /** Whether the workflow has a chat input. */
265
351
  get hasChatInput() {
266
352
  const fields = this.inputFields;
@@ -383,11 +469,19 @@ export class PlaygroundStore {
383
469
  // -----------------------------------------------------------------------
384
470
  /** Set the current workflow. */
385
471
  setWorkflow(workflow) {
472
+ // Values typed for one workflow's inputs mean nothing for another's.
473
+ if (workflow?.id !== this.#currentWorkflow?.id)
474
+ this.#formValues = {};
386
475
  this.#currentWorkflow = workflow;
387
476
  }
388
477
  /** Set the current session. */
389
478
  setCurrentSession(session) {
390
479
  this.#pinnedExecutionId = null;
480
+ // A different session starts with Run free; the same session keeps its lock.
481
+ if (session?.id !== this.#currentSession?.id) {
482
+ this.#runLockedAt = null;
483
+ this.#lastTurn = null;
484
+ }
391
485
  this.#currentSession = session;
392
486
  if (session) {
393
487
  // Update session in the list
@@ -520,12 +614,20 @@ export class PlaygroundStore {
520
614
  this.#currentWorkflow = null;
521
615
  this.#lastPollSequenceNumber = null;
522
616
  this.#pipelineRefreshTrigger = 0;
617
+ this.#turnPending = false;
618
+ this.#runLockedAt = null;
619
+ this.#formValues = {};
620
+ this.#lastTurn = null;
523
621
  }
524
622
  /** Switch to a different session. */
525
623
  switchSession(sessionId) {
526
624
  this.#pinnedExecutionId = null;
527
625
  const session = this.#sessions.find((s) => s.id === sessionId);
528
626
  if (session) {
627
+ if (session.id !== this.#currentSession?.id) {
628
+ this.#runLockedAt = null;
629
+ this.#lastTurn = null;
630
+ }
529
631
  this.#currentSession = session;
530
632
  this.#messages = [];
531
633
  this.#lastPollSequenceNumber = null;
@@ -543,6 +645,30 @@ export class PlaygroundStore {
543
645
  toggleShowLogs() {
544
646
  this.#showLogs = !this.#showLogs;
545
647
  }
648
+ /** Mark a turn request as in flight (or finished). */
649
+ setTurnPending(value) {
650
+ this.#turnPending = value;
651
+ }
652
+ /**
653
+ * Lock Run until the backend posts a message with `enableRun` metadata
654
+ * (the legacy protocol). Locking at the current count means only a
655
+ * *newer* flagged message unlocks it.
656
+ */
657
+ lockRunUntilEnabled() {
658
+ this.#runLockedAt = this.#enableRunCount;
659
+ }
660
+ /** Replace the interface input form's values. */
661
+ setFormValues(values) {
662
+ this.#formValues = values;
663
+ }
664
+ /** Record the sessions door's answer for the turn just taken (`null` clears it). */
665
+ setLastTurn(result) {
666
+ this.#lastTurn = result;
667
+ }
668
+ /** Free Run again, e.g. because the run was refused and no `enableRun` will come. */
669
+ releaseRunLock() {
670
+ this.#runLockedAt = null;
671
+ }
546
672
  // -----------------------------------------------------------------------
547
673
  // Server response application & utilities
548
674
  // -----------------------------------------------------------------------
@@ -1401,6 +1401,14 @@ p {
1401
1401
  --fd-notes-node-max-width: 500px;
1402
1402
  --fd-notes-node-min-height: 200px;
1403
1403
  --fd-notes-node-backdrop-filter: blur(8px);
1404
+
1405
+ /* =========================================================================
1406
+ Caption Node Component Tokens
1407
+ Colours (--fd-caption-node-bg / -fg) live in tokens.css. Width snaps up
1408
+ to the grid between two grid steps and this maximum.
1409
+ ========================================================================= */
1410
+
1411
+ --fd-caption-node-max-width: 500px;
1404
1412
  }
1405
1413
 
1406
1414
  /* Dark mode overrides for interrupt component tokens */
@@ -127,6 +127,10 @@
127
127
  --fd-card: #ffffff; /* @public */
128
128
  --fd-card-foreground: var(--_gray-9); /* @public */
129
129
 
130
+ /* ----- CAPTION NODE (inverted: reads as a label against any canvas) ----- */
131
+ --fd-caption-node-bg: var(--fd-foreground); /* @public */
132
+ --fd-caption-node-fg: var(--fd-background); /* @public */
133
+
130
134
  /* ----- CHROME PANELS (sidebar + config/inspector panel) -----
131
135
  Large editor-shell panels read from these so a theme can make them
132
136
  glassy/translucent without touching every other surface. Default to the
@@ -445,6 +449,10 @@
445
449
  /* ----- SURFACES (Backgrounds) - Softer contrast ----- */
446
450
  --fd-background: #1a1a1e;
447
451
  --fd-foreground: var(--_gray-2);
452
+ /* Re-declared here: a var() reference resolves where it is declared, so a
453
+ data-theme="dark" on a container below :root needs its own copy. */
454
+ --fd-caption-node-bg: var(--fd-foreground);
455
+ --fd-caption-node-fg: var(--fd-background);
448
456
  --fd-muted: #242428;
449
457
  --fd-muted-foreground: var(--_gray-4);
450
458
  --fd-subtle: #2a2a30;
@@ -18,7 +18,9 @@ import type { PartialSettings, SettingsCategory, SurfacePlacement } from './type
18
18
  import type { NavbarAction } from './types/navbar.js';
19
19
  import type { HostHooks, WebMCPHandle, WebMCPMountOptions } from './webmcp/types.js';
20
20
  export type { NavbarAction };
21
+ import type { ContextMenuOptions } from './editor/contextMenu.js';
21
22
  export type { HostHooks, WebMCPHandle, WebMCPMountOptions };
23
+ export type { ContextMenuActions, ContextMenuContext, ContextMenuEntry, ContextMenuOptions, ContextMenuTarget } from './editor/contextMenu.js';
22
24
  /**
23
25
  * Mount options for FlowDrop App
24
26
  */
@@ -151,6 +153,17 @@ export interface FlowDropMountOptions {
151
153
  * assistant must be able to run the workflow even with WebMCP switched off.
152
154
  */
153
155
  host?: HostHooks;
156
+ /**
157
+ * Customise the canvas context menu (right-click on a node, a selection or
158
+ * the empty canvas; Shift+F10 / the Menu key). `items(ctx, defaults)`
159
+ * receives the built-in entries and returns the final list: append, remove,
160
+ * reorder or pass them through. It is synchronous; if it throws or returns a
161
+ * non-array the built-in entries are used. Errors thrown by an entry's `run`
162
+ * are logged, never rethrown. The menu only opens in `mode: 'edit'`.
163
+ * Passed straight to the editor, not published on the instance: unlike
164
+ * {@link host} (agent surfaces), this is purely editor UI.
165
+ */
166
+ contextMenu?: ContextMenuOptions;
154
167
  }
155
168
  /**
156
169
  * Return type for mounted FlowDrop app
@@ -260,6 +273,8 @@ export declare function mountWorkflowEditor(container: HTMLElement, options?: {
260
273
  * @default true
261
274
  */
262
275
  builtinEditors?: boolean;
276
+ /** Customise the canvas context menu — see {@link FlowDropMountOptions.contextMenu}. */
277
+ contextMenu?: ContextMenuOptions;
263
278
  }): Promise<MountedFlowDropApp>;
264
279
  /**
265
280
  * Unmount a FlowDrop app
@@ -157,7 +157,7 @@ function attachWebMCPToMount(fd, options, isDestroyed) {
157
157
  * ```
158
158
  */
159
159
  export async function mountFlowDropApp(container, options = {}) {
160
- const { workflow, nodes, endpointConfig, portConfig, categories, height = '100vh', width = '100%', showNavbar = false, disableSidebar, configPlacement, consolePlacement, mode, pipelineId, navbarTitle, navbarActions, showSettings, showStatus, authProvider, eventHandlers, features: userFeatures, settings: initialSettings, draftStorageKey: customDraftKey, draftStorage, formatAdapters, workflowFormats, theme, settingsCategories, showSettingsSyncButton, showSettingsResetButton, instanceId, webmcp, host } = options;
160
+ const { workflow, nodes, endpointConfig, portConfig, categories, height = '100vh', width = '100%', showNavbar = false, disableSidebar, configPlacement, consolePlacement, mode, pipelineId, navbarTitle, navbarActions, showSettings, showStatus, authProvider, eventHandlers, features: userFeatures, settings: initialSettings, draftStorageKey: customDraftKey, draftStorage, formatAdapters, workflowFormats, theme, settingsCategories, showSettingsSyncButton, showSettingsResetButton, instanceId, webmcp, host, contextMenu } = options;
161
161
  // Per-instance state container — this is what allows multiple FlowDrop
162
162
  // editors to coexist on one page without sharing workflow/history state.
163
163
  const { fd, isDefault } = acquireInstance(instanceId);
@@ -237,7 +237,8 @@ export async function mountFlowDropApp(container, options = {}) {
237
237
  settingsCategories,
238
238
  showSettingsSyncButton,
239
239
  showSettingsResetButton,
240
- workflowFormats
240
+ workflowFormats,
241
+ contextMenu
241
242
  }
242
243
  });
243
244
  // Set up draft auto-save manager
@@ -422,7 +423,7 @@ export async function mountFlowDropApp(container, options = {}) {
422
423
  * @returns Promise resolving to a MountedFlowDropApp instance
423
424
  */
424
425
  export async function mountWorkflowEditor(container, options = {}) {
425
- const { workflow, endpointConfig, portConfig, categories, authProvider, instanceId, builtinEditors } = options;
426
+ const { workflow, endpointConfig, portConfig, categories, authProvider, instanceId, builtinEditors, contextMenu } = options;
426
427
  // Per-instance state container (see mountFlowDropApp)
427
428
  const { fd, isDefault } = acquireInstance(instanceId);
428
429
  // Resolve and apply endpoint config, port config and categories to this
@@ -445,7 +446,8 @@ export async function mountWorkflowEditor(container, options = {}) {
445
446
  instance: fd,
446
447
  endpointConfig: config,
447
448
  authProvider,
448
- builtinEditors
449
+ builtinEditors,
450
+ contextMenu
449
451
  }
450
452
  });
451
453
  // Create the mounted app interface (simpler version)
@@ -284,7 +284,7 @@ export declare function dynamicPortToNodePort(port: DynamicPort, portType: 'inpu
284
284
  * Built-in node types for explicit component rendering.
285
285
  * These are the node types that ship with FlowDrop.
286
286
  */
287
- export type BuiltinNodeType = 'note' | 'simple' | 'square' | 'atom' | 'tool' | 'gateway' | 'terminal' | 'default';
287
+ export type BuiltinNodeType = 'note' | 'caption' | 'simple' | 'square' | 'atom' | 'tool' | 'gateway' | 'terminal' | 'default';
288
288
  /**
289
289
  * Node type for component rendering.
290
290
  * Includes built-in types and allows custom registered types.
@@ -1377,9 +1377,42 @@ export interface WorkflowInterfaceEntry {
1377
1377
  * round-trips verbatim. Servers use it to say what "external" means for them
1378
1378
  * (`{"http": {"in": "query"}}`, `{"mcp": {"toolParam": true}}`, …).
1379
1379
  * Keys under the `fd.` prefix are reserved for future library use.
1380
+ *
1381
+ * One exception, owned by `turn`: when `turn` is `history`, `meta.limit`
1382
+ * (a positive integer, default {@link DEFAULT_HISTORY_TURN_LIMIT}) is how
1383
+ * many past user/assistant rows the session fills the port with. The
1384
+ * interface editor writes that one key and nothing else.
1380
1385
  */
1381
1386
  meta?: Record<string, unknown>;
1387
+ /**
1388
+ * What this port is for in a chat turn (see {@link WorkflowInterfaceTurn}).
1389
+ * Absent means the port plays no part in a turn. Validated by the server
1390
+ * against its vocabulary; a value this library does not know (from a newer
1391
+ * server) round-trips verbatim, which is why the type admits any string
1392
+ * beside the known values. Narrow with `isKnownTurn` before indexing by it.
1393
+ */
1394
+ turn?: WorkflowInterfaceTurn | (string & {});
1382
1395
  }
1396
+ /**
1397
+ * The chat-turn vocabulary of an interface port: what the session fills an
1398
+ * input port with, or which output ports become the assistant's reply.
1399
+ *
1400
+ * Inputs (at most one entry per value):
1401
+ * - `message`: the person's message (the turn's content), a string
1402
+ * - `history`: past user and assistant rows, bounded by `meta.limit`
1403
+ * - `session_id`: the session's id
1404
+ * - `message_id`: the id of the person's message row
1405
+ *
1406
+ * Outputs (any number):
1407
+ * - `reply`: each value becomes one assistant message
1408
+ */
1409
+ export type WorkflowInterfaceTurn = 'message' | 'history' | 'session_id' | 'message_id' | 'reply';
1410
+ /** Turn values valid on an input entry, in selector order. */
1411
+ export declare const WORKFLOW_INTERFACE_INPUT_TURNS: readonly WorkflowInterfaceTurn[];
1412
+ /** Turn values valid on an output entry, in selector order. */
1413
+ export declare const WORKFLOW_INTERFACE_OUTPUT_TURNS: readonly WorkflowInterfaceTurn[];
1414
+ /** `meta.limit` the server assumes for a `history` port that states none. */
1415
+ export declare const DEFAULT_HISTORY_TURN_LIMIT = 10;
1383
1416
  /** A workflow's public contract. Array order is the caller-facing order. */
1384
1417
  export interface WorkflowInterface {
1385
1418
  inputs?: WorkflowInterfaceEntry[];
@@ -21,6 +21,17 @@ export function dynamicPortToNodePort(port, portType) {
21
21
  description: port.description
22
22
  };
23
23
  }
24
+ /** Turn values valid on an input entry, in selector order. */
25
+ export const WORKFLOW_INTERFACE_INPUT_TURNS = [
26
+ 'message',
27
+ 'history',
28
+ 'session_id',
29
+ 'message_id'
30
+ ];
31
+ /** Turn values valid on an output entry, in selector order. */
32
+ export const WORKFLOW_INTERFACE_OUTPUT_TURNS = ['reply'];
33
+ /** `meta.limit` the server assumes for a `history` port that states none. */
34
+ export const DEFAULT_HISTORY_TURN_LIMIT = 10;
24
35
  export { StaticAuthProvider, CallbackAuthProvider, NoAuthProvider } from './auth.js';
25
36
  export { DEFAULT_SETTINGS, DEFAULT_THEME_SETTINGS, DEFAULT_EDITOR_SETTINGS, DEFAULT_UI_SETTINGS, DEFAULT_BEHAVIOR_SETTINGS, DEFAULT_API_SETTINGS, SETTINGS_CATEGORIES, SETTINGS_CATEGORY_LABELS, SETTINGS_CATEGORY_ICONS, SETTINGS_STORAGE_KEY } from './settings.js';
26
37
  export { isUISchemaControl, isUISchemaVerticalLayout, isUISchemaGroup } from './uischema.js';
@@ -173,23 +173,53 @@ export interface MessageTag {
173
173
  /**
174
174
  * Rendering hint the server may set to choose a layout regardless of role.
175
175
  *
176
+ * - `default`: no hint; same as omitting the field (role-based default below)
176
177
  * - `bubble`: chat bubble shape (default for user/assistant)
177
178
  * - `log`: dense one-liner (default for log role)
178
179
  * - `notice`: compact centered notice (default for system role with
179
180
  * compactSystemMessages enabled)
180
181
  * - `card`: vertical layout — breadcrumb (top), body (middle), tags (bottom)
182
+ * - `hidden`: not rendered by default. **Hidden is not private**: the row
183
+ * still reaches the browser with the rest of the session. It hides noise,
184
+ * never secrets.
181
185
  *
182
- * When omitted, the client falls back to the role-based default above.
186
+ * When omitted (or `default`), the client falls back to the role-based
187
+ * default above.
183
188
  */
184
- export type PlaygroundMessageDisplay = 'bubble' | 'log' | 'notice' | 'card';
189
+ export type PlaygroundMessageDisplay = 'default' | 'bubble' | 'log' | 'notice' | 'card' | 'hidden';
185
190
  /**
186
- * Resolve the effective layout for a message. Server-supplied `display` wins;
187
- * otherwise we fall back to a role-based default. Pure function so the
188
- * dispatcher and tests can share it.
191
+ * The layout a message resolves to: never `default` (that is resolved to a
192
+ * role-based layout first).
193
+ */
194
+ export type ResolvedMessageDisplay = Exclude<PlaygroundMessageDisplay, 'default'>;
195
+ /**
196
+ * Which component posted a session message — the third axis beside `role`
197
+ * (who spoke, conversationally) and `display` (how to render it).
198
+ *
199
+ * - `user`: a person typed it.
200
+ * - `workflow`: the workflow produced it (a reply).
201
+ * - `engine`: the run machinery wrote it (trigger rows, failures, recovery,
202
+ * reporting rows).
203
+ * - `playground`: a console observer wrote it for its own viewers.
204
+ * - `interrupt`: the interrupt system posted a question into the session.
205
+ *
206
+ * Servers that predate the field omit it; treat that as unknown.
207
+ */
208
+ export type PlaygroundMessageOrigin = 'user' | 'workflow' | 'engine' | 'playground' | 'interrupt';
209
+ /**
210
+ * Resolve the effective layout for a message. Server-supplied `display` wins
211
+ * (except `default`, which means "no hint"); otherwise we fall back to a
212
+ * role-based default. Pure function so the dispatcher and tests can share it.
189
213
  */
190
214
  export declare function resolveMessageDisplay(message: Pick<PlaygroundMessage, 'role' | 'display'>, options?: {
191
215
  compactSystemMessages?: boolean;
192
- }): PlaygroundMessageDisplay;
216
+ }): ResolvedMessageDisplay;
217
+ /**
218
+ * Whether a message carries the `hidden` display hint. Hidden rows are kept
219
+ * in the store (they still arrive and advance polling cursors) but are not
220
+ * rendered. This only hides noise — it is never a security boundary.
221
+ */
222
+ export declare function isHiddenMessage(message: Pick<PlaygroundMessage, 'display'>): boolean;
193
223
  /**
194
224
  * Message in a playground session
195
225
  *
@@ -259,8 +289,14 @@ export interface PlaygroundMessage {
259
289
  * Layout hint. When omitted, the client picks a default from the role:
260
290
  * - log → 'log', system (when compactSystemMessages) → 'notice',
261
291
  * user/assistant → 'bubble'.
292
+ * `hidden` rows are not rendered (noise, not secrecy).
262
293
  */
263
294
  display?: PlaygroundMessageDisplay;
295
+ /**
296
+ * Which component posted the message. Always present on current servers;
297
+ * absent from older ones (treat as unknown — no origin badge).
298
+ */
299
+ origin?: PlaygroundMessageOrigin;
264
300
  /** Additional message metadata */
265
301
  metadata?: PlaygroundMessageMetadata;
266
302
  }
@@ -303,11 +339,48 @@ export interface PlaygroundInputField {
303
339
  * Request payload for sending a message to the playground
304
340
  */
305
341
  export interface PlaygroundMessageRequest {
306
- /** Message content (typically user input) */
307
- content: string;
308
- /** Additional input values for workflow nodes */
342
+ /**
343
+ * The person's message. Optional: a workflow whose interface declares no
344
+ * `message` turn port runs on `inputs` alone, and its server refuses
345
+ * `content` with a 400.
346
+ */
347
+ content?: string;
348
+ /** Named inputs, keyed by interface entry id (the server's port `name`). */
309
349
  inputs?: Record<string, unknown>;
310
350
  }
351
+ /**
352
+ * What the `sessions.turn` endpoint answers with (`data` of a 202). A
353
+ * snapshot at return time: the user's row, the assistant rows and the status
354
+ * changes arrive through the messages poll like any other turn.
355
+ */
356
+ export interface PlaygroundTurnResult {
357
+ /** The session's id. */
358
+ sessionId: string;
359
+ /** The id of the user's message row (the turn's id). */
360
+ userMessageId: string;
361
+ /** The pipeline running the turn; `null` until it exists (async paths). */
362
+ pipelineId: string | null;
363
+ /** `queued`, `running`, `completed`, `awaiting_input`, `paused` or `failed`. */
364
+ status: string;
365
+ /** Assistant rows written during the turn (filled only when the server waited). */
366
+ assistantMessageIds?: string[];
367
+ finalAssistantMessageId?: string | null;
368
+ finalAssistantMessage?: string | null;
369
+ /** Further keys from newer servers pass through untouched. */
370
+ [key: string]: unknown;
371
+ }
372
+ /**
373
+ * What a turn request returned, by door: the legacy `playground.sendMessage`
374
+ * answers with the user's message row, `sessions.turn` with a
375
+ * {@link PlaygroundTurnResult}.
376
+ */
377
+ export type PlaygroundTurnResponse = {
378
+ kind: 'message';
379
+ message: PlaygroundMessage;
380
+ } | {
381
+ kind: 'turn';
382
+ result: PlaygroundTurnResult;
383
+ };
311
384
  /**
312
385
  * Response from the messages endpoint with polling support
313
386
  */
@@ -344,6 +417,12 @@ export interface PlaygroundConfig {
344
417
  /**
345
418
  * Whether to show the chat text input (default: true)
346
419
  * When false, only the "Run" button is displayed for workflow execution.
420
+ *
421
+ * When the workflow interface declares turn ports, the interface decides:
422
+ * the chat box shows only for a workflow with a `message` port, and this
423
+ * option can still hide it (false) but not add it to a workflow without
424
+ * one, whose server refuses message content. A workflow whose interface
425
+ * declares no turn port follows this option as before.
347
426
  */
348
427
  showChatInput?: boolean;
349
428
  /**
@@ -355,6 +434,8 @@ export interface PlaygroundConfig {
355
434
  /**
356
435
  * Predefined message to send when "Run" button is clicked (default: "Run workflow")
357
436
  * Used when showChatInput is false to provide a default message for workflow execution.
437
+ * Ignored for a workflow whose interface declares turn ports but no
438
+ * `message` port: Run sends its form inputs and no message.
358
439
  */
359
440
  predefinedMessage?: string;
360
441
  /**
@@ -43,12 +43,12 @@ export function defaultIsTerminalStatus(status) {
43
43
  return DEFAULT_TERMINAL_STATUSES.includes(status);
44
44
  }
45
45
  /**
46
- * Resolve the effective layout for a message. Server-supplied `display` wins;
47
- * otherwise we fall back to a role-based default. Pure function so the
48
- * dispatcher and tests can share it.
46
+ * Resolve the effective layout for a message. Server-supplied `display` wins
47
+ * (except `default`, which means "no hint"); otherwise we fall back to a
48
+ * role-based default. Pure function so the dispatcher and tests can share it.
49
49
  */
50
50
  export function resolveMessageDisplay(message, options = {}) {
51
- if (message.display)
51
+ if (message.display && message.display !== 'default')
52
52
  return message.display;
53
53
  if (message.role === 'system' && options.compactSystemMessages !== false)
54
54
  return 'notice';
@@ -56,6 +56,14 @@ export function resolveMessageDisplay(message, options = {}) {
56
56
  return 'log';
57
57
  return 'bubble';
58
58
  }
59
+ /**
60
+ * Whether a message carries the `hidden` display hint. Hidden rows are kept
61
+ * in the store (they still arrive and advance polling cursors) but are not
62
+ * rendered. This only hides noise — it is never a security boundary.
63
+ */
64
+ export function isHiddenMessage(message) {
65
+ return message.display === 'hidden';
66
+ }
59
67
  /**
60
68
  * Metadata field to control Run button state from backend.
61
69
  * When a message contains this field set to true, the Run button becomes enabled.
@@ -0,0 +1,43 @@
1
+ /**
2
+ * Pure helpers for the caption node: text clean-up, width snapping and the
3
+ * commit rules for in-place edits. No DOM, no Svelte, so they unit-test
4
+ * directly.
5
+ *
6
+ * @module utils/captionText
7
+ */
8
+ /** Collapse every run of whitespace (newlines and tabs included) to one space and trim. */
9
+ export declare function collapseCaptionText(text: string): string;
10
+ /**
11
+ * The width a caption takes: the natural width of its text plus padding,
12
+ * rounded up to the next grid step, never below two grid steps (40px on the
13
+ * default 20px grid) and never above `max` (none by default: the node's CSS
14
+ * `max-width` clamps it).
15
+ *
16
+ * @param naturalWidth - width of the text on one line plus horizontal padding, in px
17
+ * @param grid - the editor's grid size in px
18
+ * @param max - the maximum node width in px, if any
19
+ */
20
+ export declare function snapCaptionWidth(naturalWidth: number, grid: number, max?: number): number;
21
+ /** What the editor does with a finished in-place edit. */
22
+ export type InlineCommitOutcome = 'none' | 'remove' | 'add' | 'edit';
23
+ /** The decision for a finished in-place edit, with the text to write. */
24
+ export interface InlineCommitDecision {
25
+ outcome: InlineCommitOutcome;
26
+ /** The collapsed text; empty when the edit was cancelled. */
27
+ label: string;
28
+ }
29
+ /**
30
+ * The commit rules for an in-place edit of a caption. This is the one place
31
+ * the typed text is cleaned (see `collapseCaptionText`); callers write
32
+ * `label` and do not collapse again.
33
+ *
34
+ * - new caption, cancelled or empty: `remove` (no history entry)
35
+ * - new caption, text: `add` (history "Add caption")
36
+ * - existing caption, cancelled, empty or unchanged: `none` (the node restores itself)
37
+ * - existing caption, changed text: `edit` (history "Edit caption")
38
+ *
39
+ * @param text - the text as typed, or `null` when the edit was cancelled
40
+ * @param current - the label the node has now
41
+ * @param isNew - whether the node was just added and has no history entry yet
42
+ */
43
+ export declare function decideInlineCommit(text: string | null, current: string, isNew: boolean): InlineCommitDecision;
@@ -0,0 +1,49 @@
1
+ /**
2
+ * Pure helpers for the caption node: text clean-up, width snapping and the
3
+ * commit rules for in-place edits. No DOM, no Svelte, so they unit-test
4
+ * directly.
5
+ *
6
+ * @module utils/captionText
7
+ */
8
+ /** Collapse every run of whitespace (newlines and tabs included) to one space and trim. */
9
+ export function collapseCaptionText(text) {
10
+ return text.replace(/\s+/g, ' ').trim();
11
+ }
12
+ /**
13
+ * The width a caption takes: the natural width of its text plus padding,
14
+ * rounded up to the next grid step, never below two grid steps (40px on the
15
+ * default 20px grid) and never above `max` (none by default: the node's CSS
16
+ * `max-width` clamps it).
17
+ *
18
+ * @param naturalWidth - width of the text on one line plus horizontal padding, in px
19
+ * @param grid - the editor's grid size in px
20
+ * @param max - the maximum node width in px, if any
21
+ */
22
+ export function snapCaptionWidth(naturalWidth, grid, max = Infinity) {
23
+ const step = grid > 0 ? grid : 20;
24
+ const floor = 2 * step;
25
+ const snapped = Math.ceil(Math.max(0, naturalWidth) / step) * step;
26
+ return Math.min(max, Math.max(floor, snapped));
27
+ }
28
+ /**
29
+ * The commit rules for an in-place edit of a caption. This is the one place
30
+ * the typed text is cleaned (see `collapseCaptionText`); callers write
31
+ * `label` and do not collapse again.
32
+ *
33
+ * - new caption, cancelled or empty: `remove` (no history entry)
34
+ * - new caption, text: `add` (history "Add caption")
35
+ * - existing caption, cancelled, empty or unchanged: `none` (the node restores itself)
36
+ * - existing caption, changed text: `edit` (history "Edit caption")
37
+ *
38
+ * @param text - the text as typed, or `null` when the edit was cancelled
39
+ * @param current - the label the node has now
40
+ * @param isNew - whether the node was just added and has no history entry yet
41
+ */
42
+ export function decideInlineCommit(text, current, isNew) {
43
+ const label = text === null ? '' : collapseCaptionText(text);
44
+ if (isNew)
45
+ return { outcome: label === '' ? 'remove' : 'add', label };
46
+ if (label === '' || label === current)
47
+ return { outcome: 'none', label };
48
+ return { outcome: 'edit', label };
49
+ }