@flowdrop/flowdrop 2.14.0 → 2.15.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.
@@ -24,7 +24,8 @@
24
24
  -->
25
25
 
26
26
  <script lang="ts">
27
- import { getContext, onMount } from 'svelte';
27
+ import { getContext, onMount, untrack } from 'svelte';
28
+ import { SvelteMap } from 'svelte/reactivity';
28
29
  import Icon from '@iconify/svelte';
29
30
  import type { AutocompleteConfig, AuthProvider } from '../../types/index.js';
30
31
  import type { FieldOption } from './types.js';
@@ -102,12 +103,19 @@
102
103
  let highlightedIndex = $state(-1);
103
104
  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
104
105
  let abortController: AbortController | null = null;
106
+ // The label lookup's own request, and the key of the last one sent (see
107
+ // lookupLabels and the effect that calls it).
108
+ let labelController: AbortController | null = null;
109
+ let labelLookupKey = '';
110
+ // Values typed into this field rather than loaded from outside; no endpoint
111
+ // has a label for them, so the label lookup skips them.
112
+ const typed = new Set<string>();
105
113
 
106
114
  // Popover positioning style
107
115
  let popoverStyle = $state('');
108
116
 
109
117
  // Cache of value-to-label mappings for selected items
110
- let labelCache = $state<Map<string, string>>(new Map());
118
+ const labelCache = new SvelteMap<string, string>();
111
119
 
112
120
  // Resolved values for each param dependency: { paramName -> currentFieldValue }
113
121
  // Used both in buildUrl (appending to query) and in the dep-change effect.
@@ -170,18 +178,8 @@
170
178
  * Get display label for a selected value
171
179
  */
172
180
  function getDisplayLabel(val: string): string {
173
- // Check cache first
174
- if (labelCache.has(val)) {
175
- return labelCache.get(val) ?? val;
176
- }
177
- // Check current suggestions
178
- const match = suggestions.find((s) => s.value === val);
179
- if (match) {
180
- labelCache.set(val, match.label);
181
- return match.label;
182
- }
183
- // Return value as fallback
184
- return val;
181
+ // Every fetched suggestion and every pick lands in the cache.
182
+ return labelCache.get(val) ?? val;
185
183
  }
186
184
 
187
185
  /**
@@ -222,6 +220,14 @@
222
220
  }));
223
221
  }
224
222
 
223
+ /**
224
+ * Abort reason for a request that ran out of time. Unlike a plain abort
225
+ * (superseded or unmounted), it is a failure the field reports.
226
+ */
227
+ function timeoutError(): DOMException {
228
+ return new DOMException('Request timed out', 'TimeoutError');
229
+ }
230
+
225
231
  /**
226
232
  * Fetch suggestions from the callback URL
227
233
  * @param query - The search query
@@ -248,7 +254,7 @@
248
254
 
249
255
  let timeoutId: ReturnType<typeof setTimeout> | null = null;
250
256
  try {
251
- timeoutId = setTimeout(() => controller.abort(), 5000);
257
+ timeoutId = setTimeout(() => controller.abort(timeoutError()), 5000);
252
258
 
253
259
  // authenticatedFetch merges auth headers (call getter for current value)
254
260
  // and applies the 401/403 lifecycle consistently with the rest of the lib.
@@ -263,6 +269,8 @@
263
269
  }
264
270
 
265
271
  const data = await response.json();
272
+ // A newer request (or a dependency change) superseded this one.
273
+ if (controller.signal.aborted) return;
266
274
  const mapped = mapResponse(data);
267
275
 
268
276
  // Update label cache with fetched suggestions
@@ -278,12 +286,21 @@
278
286
  return;
279
287
  }
280
288
  logger.error('[FormAutocomplete] Fetch error:', err);
281
- error = err instanceof Error ? err.message : 'Failed to fetch suggestions';
289
+ error =
290
+ err instanceof Error
291
+ ? err.name === 'TimeoutError'
292
+ ? t.timedOut
293
+ : err.message
294
+ : 'Failed to fetch suggestions';
282
295
  suggestions = [];
283
296
  } finally {
284
297
  if (timeoutId !== null) clearTimeout(timeoutId);
285
- isLoading = false;
286
- abortController = null;
298
+ // An aborted request settles after its replacement started; the loading
299
+ // state and controller belong to that replacement then.
300
+ if (abortController === controller) {
301
+ isLoading = false;
302
+ abortController = null;
303
+ }
287
304
  }
288
305
  }
289
306
 
@@ -363,14 +380,26 @@
363
380
  // Backspace-on-empty. Replaces the per-keystroke commit dropped from
364
381
  // handleInput; see issue #32.
365
382
  if (allowFreeText && !multiple && inputValue !== '') {
366
- const currentSingle = selectedValues[0] ?? '';
367
- if (inputValue !== currentSingle) {
368
- onChange(inputValue);
369
- }
383
+ commitFreeText(inputValue);
370
384
  }
371
385
  }, 200);
372
386
  }
373
387
 
388
+ /**
389
+ * Commit text the user typed as a value (free-text mode). Adds it in
390
+ * multiple mode unless already selected; replaces the value in single mode
391
+ * unless unchanged.
392
+ * @param text - The typed text
393
+ */
394
+ function commitFreeText(text: string): void {
395
+ typed.add(text);
396
+ if (multiple) {
397
+ if (!selectedValues.includes(text)) onChange([...selectedValues, text]);
398
+ } else if (text !== (selectedValues[0] ?? '')) {
399
+ onChange(text);
400
+ }
401
+ }
402
+
374
403
  /**
375
404
  * Handle option selection
376
405
  * @param option - Selected option
@@ -464,14 +493,10 @@
464
493
  if (highlightedIndex >= 0 && highlightedIndex < suggestions.length) {
465
494
  selectOption(suggestions[highlightedIndex]);
466
495
  } else if (allowFreeText && inputValue !== '') {
496
+ commitFreeText(inputValue);
467
497
  if (multiple) {
468
- const current = selectedValues;
469
- if (!current.includes(inputValue)) {
470
- onChange([...current, inputValue]);
471
- }
472
498
  inputValue = '';
473
499
  } else {
474
- onChange(inputValue);
475
500
  hideDropdown();
476
501
  }
477
502
  }
@@ -508,22 +533,6 @@
508
533
  inputElement?.focus();
509
534
  }
510
535
 
511
- /**
512
- * Sync label cache when value prop changes externally
513
- */
514
- $effect(() => {
515
- // When value changes, try to find labels from suggestions
516
- const vals = selectedValues;
517
- vals.forEach((val) => {
518
- if (!labelCache.has(val)) {
519
- const match = suggestions.find((s) => s.value === val);
520
- if (match) {
521
- labelCache.set(val, match.label);
522
- }
523
- }
524
- });
525
- });
526
-
527
536
  /**
528
537
  * Calculate popover position relative to viewport
529
538
  * Popover API renders in top layer, bypassing all stacking contexts
@@ -613,8 +622,60 @@
613
622
  // parent form's handleFieldChange so it only fires on user-driven changes,
614
623
  // not on undo/redo, programmatic resets, or collaborative edits (#33).
615
624
  abortController?.abort();
625
+ labelController?.abort();
616
626
  suggestions = [];
617
- labelCache = new Map();
627
+ labelCache.clear();
628
+ // The cleared labels need a new lookup, even for a key looked up before.
629
+ labelLookupKey = '';
630
+ });
631
+
632
+ /**
633
+ * Look up labels for values the cache does not know, with the empty query
634
+ * the field would send on focus. Its own request: it never touches the
635
+ * suggestions, the loading state or the error, so it cannot disturb a
636
+ * search the user is running, and a search cannot cancel it.
637
+ */
638
+ async function lookupLabels(): Promise<void> {
639
+ labelController?.abort();
640
+ const controller = new AbortController();
641
+ labelController = controller;
642
+ const fingerprint = depFingerprint;
643
+ const timeoutId = setTimeout(() => controller.abort(timeoutError()), 5000);
644
+ try {
645
+ const response = await authenticatedFetch(
646
+ buildUrl(''),
647
+ { method: 'GET', signal: controller.signal },
648
+ { authProvider: getAuthProvider?.() }
649
+ );
650
+ if (!response.ok) {
651
+ throw new Error(`HTTP ${response.status}: ${response.statusText}`);
652
+ }
653
+ const mapped = mapResponse(await response.json());
654
+ // Labels fetched for other dependency values would be wrong now.
655
+ if (controller.signal.aborted || fingerprint !== depFingerprint) return;
656
+ for (const opt of mapped) labelCache.set(opt.value, opt.label);
657
+ } catch (err) {
658
+ if (err instanceof Error && err.name === 'AbortError') return;
659
+ logger.warn('[FormAutocomplete] Label lookup failed:', err);
660
+ } finally {
661
+ clearTimeout(timeoutId);
662
+ if (labelController === controller) labelController = null;
663
+ }
664
+ }
665
+
666
+ // Labels are otherwise only learned from suggestions, so a preloaded value
667
+ // (form open, undo, external edit) would show its raw value until the user
668
+ // focuses the field. When the config allows an empty query, look the labels
669
+ // up once per set of unknown values and dependency values, so a value the
670
+ // endpoint does not return is not retried in a loop.
671
+ $effect(() => {
672
+ if (!fetchOnFocus || minChars > 0) return;
673
+ const missing = selectedValues.filter((val) => !labelCache.has(val) && !typed.has(val));
674
+ if (missing.length === 0) return;
675
+ const key = `${depFingerprint}|${missing.join('\u0000')}`;
676
+ if (key === labelLookupKey) return;
677
+ labelLookupKey = key;
678
+ untrack(() => lookupLabels());
618
679
  });
619
680
 
620
681
  /**
@@ -630,6 +691,7 @@
630
691
  if (abortController) {
631
692
  abortController.abort();
632
693
  }
694
+ labelController?.abort();
633
695
  };
634
696
  });
635
697
  </script>
@@ -979,6 +1041,10 @@
979
1041
  /* Popover container - renders in top layer via Popover API */
980
1042
  .form-autocomplete__popover {
981
1043
  position: fixed;
1044
+ /* UA [popover] sets inset: 0; without this reset the inline `bottom`
1045
+ of the flip-above placement loses to top: 0 and the list sticks to
1046
+ the top of the viewport. */
1047
+ inset: auto;
982
1048
  margin: 0;
983
1049
  padding: 0;
984
1050
  border: none;
@@ -38,7 +38,7 @@ export type { NodeStatusScope } from '../stores/playgroundStore.svelte.js';
38
38
  export type { RunController, RunControllerOptions } from '../stores/runController.svelte.js';
39
39
  export type { EditorMode, EditorModeStore } from '../stores/editorModeStore.svelte.js';
40
40
  export type { EndpointConfig } from '../config/endpoints.js';
41
- export type { FlowDropMountOptions, MountedFlowDropApp, NavbarAction, NavbarBranding } from '../svelte-app.js';
41
+ export type { FlowDropMountOptions, MountedFlowDropApp, RunCommandOptions, NavbarAction, NavbarBranding } from '../svelte-app.js';
42
42
  export { StaticAuthProvider, CallbackAuthProvider, NoAuthProvider } from '../types/auth.js';
43
43
  export { DEFAULT_FEATURES, mergeFeatures } from '../types/events.js';
44
44
  export { getStatusColor, getStatusIcon, getStatusLabel, getStatusBackgroundColor, getStatusTextColor, createDefaultExecutionInfo, updateExecutionStart, updateExecutionComplete, updateExecutionFailed, resetExecutionInfo, stripExecutionInfo, formatExecutionDuration, formatLastExecuted } from '../utils/nodeStatus.js';
@@ -92,13 +92,13 @@ export type { PortShape } from '../utils/portShape.js';
92
92
  export { default as PortTypeBadge } from '../components/ports/PortTypeBadge.svelte';
93
93
  export { fetchRuntimeConfig, getRuntimeConfig, clearRuntimeConfigCache, initRuntimeConfig } from '../config/runtimeConfig.js';
94
94
  export type { RuntimeConfig } from '../config/runtimeConfig.js';
95
- export type { Workflow, WorkflowNode, WorkflowEdge, NodeMetadata, NodePort, DynamicPort, Branch, ExecutionStatus, ExecutionResult, FlowDropConfig, PortConfig, ConfigSchema, ConfigProperty, ConfigEditOptions } from '../types/index.js';
95
+ export type { Workflow, WorkflowNode, WorkflowEdge, NodeMetadata, NodePort, DynamicPort, Branch, ExecutionStatus, ExecutionResult, FlowDropConfig, PortConfig, ConfigSchema, ConfigProperty, ConfigEditOptions, ConfigValues, ExternalEditLink } from '../types/index.js';
96
96
  export type { WorkflowEditorConfig, EditorFeatures, UIConfig, APIConfig } from '../types/config.js';
97
97
  export type { AuthProvider, StaticAuthConfig, CallbackAuthConfig } from '../types/auth.js';
98
98
  export type { FlowDropEventHandlers, FlowDropFeatures, WorkflowChangeType } from '../types/events.js';
99
99
  export type { EndpointConfig } from '../config/endpoints.js';
100
- export type { UIAction } from '../commands/types.js';
100
+ export type { UIAction, Command, CommandResult, CommandErrorCode } from '../commands/types.js';
101
101
  export type { EditorPlaygroundConfig } from '../types/playground.js';
102
- export type { FlowDropMountOptions, MountedFlowDropApp, NavbarAction, NavbarBranding } from '../svelte-app.js';
102
+ export type { FlowDropMountOptions, MountedFlowDropApp, RunCommandOptions, NavbarAction, NavbarBranding } from '../svelte-app.js';
103
103
  export type { ContextMenuActions, ContextMenuContext, ContextMenuEntry, ContextMenuOptions, ContextMenuTarget } from './contextMenu.js';
104
104
  export type { NodeComponentProps, NodeComponentRegistration, FlowDropPluginConfig, PluginNodeDefinition } from '../registry/index.js';
package/dist/index.d.ts CHANGED
@@ -32,10 +32,11 @@ export { createFlowDropInstance } from './stores/instanceContainer.svelte.js';
32
32
  export { getInstance, provideInstance } from './stores/getInstance.svelte.js';
33
33
  export { createEndpointConfig, defaultEndpointConfig, sessionsEndpoints } from './config/endpoints.js';
34
34
  export { NoAuthProvider, StaticAuthProvider, CallbackAuthProvider } from './types/auth.js';
35
- export type { Workflow, WorkflowNode, WorkflowEdge, NodeMetadata, ConfigSchema } from './types/index.js';
35
+ export type { Workflow, WorkflowNode, WorkflowEdge, NodeMetadata, ConfigSchema, ConfigValues, ExternalEditLink } from './types/index.js';
36
+ export type { Command, CommandResult, CommandErrorCode } from './commands/types.js';
36
37
  export type { EndpointConfig } from './config/endpoints.js';
37
38
  export type { AuthProvider } from './types/auth.js';
38
39
  export type { FlowDropInstance } from './stores/instanceContainer.svelte.js';
39
- export type { FlowDropMountOptions, MountedFlowDropApp } from './svelte-app.js';
40
+ export type { FlowDropMountOptions, MountedFlowDropApp, RunCommandOptions } from './svelte-app.js';
40
41
  export type { FlowDropEventHandlers } from './types/events.js';
41
42
  export type { Messages, MessagesOverride } from './messages/index.js';
@@ -131,6 +131,7 @@ export declare const defaultMessages: {
131
131
  readonly clearAll: "Clear all selections";
132
132
  readonly suggestions: "Suggestions";
133
133
  readonly retry: "Retry";
134
+ readonly timedOut: "The request timed out";
134
135
  readonly noResults: "No results found";
135
136
  };
136
137
  readonly field: {
@@ -105,6 +105,7 @@ export const defaultMessages = {
105
105
  clearAll: 'Clear all selections',
106
106
  suggestions: 'Suggestions',
107
107
  retry: 'Retry',
108
+ timedOut: 'The request timed out',
108
109
  noResults: 'No results found'
109
110
  },
110
111
  field: {
@@ -194,6 +194,16 @@ export declare class WorkflowStore {
194
194
  revision?: Workflow['revision'];
195
195
  can?: Workflow['can'];
196
196
  }): void;
197
+ /**
198
+ * Stop calling the dirty-state and workflow-change callbacks until the
199
+ * returned release is called, e.g. while a change is made and then taken as
200
+ * the workflow's new clean state, which the host should not hear about.
201
+ *
202
+ * On release the host hears only what is still true: the dirty state when it
203
+ * differs from the one at muting, and one `'metadata'` change when the
204
+ * workflow is dirty and was replaced meanwhile. Release is idempotent.
205
+ */
206
+ muteCallbacks(): () => void;
197
207
  /**
198
208
  * Set the restoring from history flag.
199
209
  *
@@ -128,6 +128,8 @@ export class WorkflowStore {
128
128
  #onDirtyStateChange = null;
129
129
  /** Callback for workflow changes — set by the App component. */
130
130
  #onWorkflowChange = null;
131
+ /** While above 0 the two callbacks above are not called (see {@link muteCallbacks}). */
132
+ #muted = 0;
131
133
  /**
132
134
  * Whether we're currently restoring from history (undo/redo).
133
135
  * When true, prevents pushing to history to avoid recursive loops.
@@ -322,9 +324,8 @@ export class WorkflowStore {
322
324
  markAsSaved() {
323
325
  const wasDirty = this.#editVersion !== this.#savedVersion;
324
326
  this.#savedVersion = this.#editVersion;
325
- if (wasDirty && this.#onDirtyStateChange) {
326
- this.#onDirtyStateChange(false);
327
- }
327
+ if (wasDirty)
328
+ this.#emitDirty(false);
328
329
  }
329
330
  /**
330
331
  * Take the server's word on the workflow's revision and permissions after a
@@ -341,6 +342,34 @@ export class WorkflowStore {
341
342
  ...(state.can !== undefined && { can: state.can })
342
343
  };
343
344
  }
345
+ /**
346
+ * Stop calling the dirty-state and workflow-change callbacks until the
347
+ * returned release is called, e.g. while a change is made and then taken as
348
+ * the workflow's new clean state, which the host should not hear about.
349
+ *
350
+ * On release the host hears only what is still true: the dirty state when it
351
+ * differs from the one at muting, and one `'metadata'` change when the
352
+ * workflow is dirty and was replaced meanwhile. Release is idempotent.
353
+ */
354
+ muteCallbacks() {
355
+ const dirtyBefore = this.isDirty;
356
+ const workflowBefore = this.#workflow;
357
+ this.#muted++;
358
+ let released = false;
359
+ return () => {
360
+ if (released)
361
+ return;
362
+ released = true;
363
+ this.#muted--;
364
+ if (this.#muted > 0)
365
+ return;
366
+ const dirty = this.isDirty;
367
+ if (dirty !== dirtyBefore)
368
+ this.#emitDirty(dirty);
369
+ if (dirty && this.#workflow !== workflowBefore)
370
+ this.#notifyWorkflowChange('metadata');
371
+ };
372
+ }
344
373
  /**
345
374
  * Set the restoring from history flag.
346
375
  *
@@ -360,17 +389,20 @@ export class WorkflowStore {
360
389
  this.#editVersion++;
361
390
  // Dirty state just flipped from clean → dirty
362
391
  if (this.#editVersion - 1 === this.#savedVersion) {
363
- if (this.#onDirtyStateChange) {
364
- this.#onDirtyStateChange(true);
365
- }
392
+ this.#emitDirty(true);
366
393
  }
367
394
  }
395
+ /** Tell the host the dirty state changed, unless the callbacks are muted. */
396
+ #emitDirty(isDirty) {
397
+ if (this.#muted === 0)
398
+ this.#onDirtyStateChange?.(isDirty);
399
+ }
368
400
  /**
369
401
  * Notify external listeners of a workflow change.
370
402
  * Does NOT bump the version — callers that mutate must call #bumpVersion() explicitly.
371
403
  */
372
404
  #notifyWorkflowChange(changeType) {
373
- if (this.#workflow && this.#onWorkflowChange) {
405
+ if (this.#workflow && this.#onWorkflowChange && this.#muted === 0) {
374
406
  this.#onWorkflowChange(this.#workflow, changeType);
375
407
  }
376
408
  }
@@ -425,9 +457,7 @@ export class WorkflowStore {
425
457
  // Reset version counters — workflow is "clean" after initialization
426
458
  this.#editVersion = 0;
427
459
  this.#savedVersion = 0;
428
- if (this.#onDirtyStateChange) {
429
- this.#onDirtyStateChange(false);
430
- }
460
+ this.#emitDirty(false);
431
461
  // Initialize history with the loaded workflow
432
462
  this.#history.initialize(workflow);
433
463
  }
@@ -667,9 +697,7 @@ export class WorkflowStore {
667
697
  this.#editVersion = 0;
668
698
  this.#savedVersion = 0;
669
699
  this.#history.clear();
670
- if (this.#onDirtyStateChange) {
671
- this.#onDirtyStateChange(false);
672
- }
700
+ this.#emitDirty(false);
673
701
  }
674
702
  /** Update workflow metadata. */
675
703
  updateMetadata(metadata) {
@@ -6,7 +6,7 @@
6
6
  *
7
7
  * @module svelte-app
8
8
  */
9
- import type { Workflow, NodeMetadata, PortConfig, CategoryDefinition } from './types/index.js';
9
+ import type { Workflow, NodeMetadata, PortConfig, CategoryDefinition, ConfigSchema } from './types/index.js';
10
10
  import type { EndpointConfig } from './config/endpoints.js';
11
11
  import type { AuthProvider } from './types/auth.js';
12
12
  import type { EditorPlaygroundConfig } from './types/playground.js';
@@ -18,6 +18,7 @@ import { type DraftStorageOption } from './services/draftStorage.js';
18
18
  import type { ColorSchemeOption, PartialSettings, SettingsCategory, SurfacePlacement } from './types/settings.js';
19
19
  import type { NavbarAction, NavbarBranding } from './types/navbar.js';
20
20
  import type { HostHooks, WebMCPHandle, WebMCPMountOptions } from './webmcp/types.js';
21
+ import type { Command, CommandResult } from './commands/types.js';
21
22
  export type { NavbarAction, NavbarBranding };
22
23
  import type { ContextMenuOptions } from './editor/contextMenu.js';
23
24
  export type { HostHooks, WebMCPHandle, WebMCPMountOptions };
@@ -154,6 +155,14 @@ export interface FlowDropMountOptions {
154
155
  * is left untouched. Omit to offer every registered format.
155
156
  */
156
157
  workflowFormats?: string[];
158
+ /**
159
+ * Extra JSON Schema properties for the Workflow Settings panel. Their values
160
+ * are stored in `workflow.config`: loaded from the workflow passed in,
161
+ * returned by `getWorkflow()` and saved with it. The built-in keys (`name`,
162
+ * `description`, `format`, `interface`, `playground`) are reserved: a
163
+ * property using one is ignored with a console warning.
164
+ */
165
+ workflowSettingsSchema?: ConfigSchema;
157
166
  /** Visual theme — named built-in ('graphite' | 'classic' | 'minimal' | 'drafter') or custom theme object */
158
167
  theme?: FlowDropTheme | FlowDropThemeName;
159
168
  /** Which settings tabs to show in the modal (defaults to all) */
@@ -207,6 +216,15 @@ export interface FlowDropMountOptions {
207
216
  */
208
217
  contextMenu?: ContextMenuOptions;
209
218
  }
219
+ /** Options for {@link MountedFlowDropApp.runCommand}. */
220
+ export interface RunCommandOptions {
221
+ /**
222
+ * Make the command's result the workflow's clean starting point: no undo
223
+ * step and not dirty. Refused with `code: 'DIRTY'` when the workflow already
224
+ * has unsaved changes.
225
+ */
226
+ baseline?: boolean;
227
+ }
210
228
  /**
211
229
  * Return type for mounted FlowDrop app
212
230
  */
@@ -257,6 +275,49 @@ export interface MountedFlowDropApp {
257
275
  * @returns The number of entries removed.
258
276
  */
259
277
  clearAllDrafts: () => number;
278
+ /**
279
+ * Run one Command Console command against this mount's workflow, as if it
280
+ * had been typed into the console: `await app.runCommand('layout auto')`.
281
+ *
282
+ * `command` is a console line (parsed with the editing DSL) or an already
283
+ * parsed `Command` object. An object is checked first: an unknown `type`, or
284
+ * a field that is missing or of the wrong kind, resolves with
285
+ * `code: 'INVALID_ARGUMENT'` and runs nothing. Never rejects: failures (a
286
+ * line that does not parse, an unknown node, ...) resolve to
287
+ * `{ ok: false, error, code }`.
288
+ *
289
+ * - **Waits for the workflow.** The mount resolves before the editor has
290
+ * loaded its workflow, so a call made right after mounting waits for it.
291
+ * If the mount is destroyed first, or was already destroyed, the call
292
+ * resolves with `{ ok: false, code: 'NO_WORKFLOW' }`.
293
+ * - **One undo step per call**, the same as typing the command in the
294
+ * console; the workflow becomes dirty.
295
+ * - **Sizes before first paint.** `layout auto` reads node sizes the canvas
296
+ * has measured and `layout beautify` asks the mounted canvas to measure
297
+ * them. A call made before the canvas has rendered falls back to computed
298
+ * geometry, so the result can differ slightly from the same command run
299
+ * later.
300
+ * - **`options.baseline`** makes the command's result the workflow's clean
301
+ * starting point: `isDirty()` is `false` afterwards and the undo history
302
+ * starts over from it (earlier undo steps are cleared too). Useful to
303
+ * tidy a loaded model before the user sees it. It needs a workflow with no
304
+ * unsaved changes: when the workflow is dirty the command is not run and
305
+ * the call resolves with `{ ok: false, code: 'DIRTY' }`. `undo` and `redo`
306
+ * are refused with `code: 'INVALID_ARGUMENT'`. `onDirtyStateChange` and
307
+ * `onWorkflowChange` are not called for a baseline run; a failed command
308
+ * that still left changes is reported once it returns. A failed command,
309
+ * or one that changes nothing (`info`, `list nodes`), keeps the undo
310
+ * history. A draft saved earlier is not overwritten by the re-baselined
311
+ * workflow.
312
+ * - **Read-only mounts** (`mode: 'readonly' | 'locked'`) accept it too, so a
313
+ * host can lay out a model it only displays.
314
+ * - **UI actions** (select a node, open its config panel, fit/zoom/pan) are
315
+ * applied by `mountFlowDropApp`'s editor shell. `mountWorkflowEditor` has
316
+ * no shell, so they are dropped there.
317
+ * - **Session commands** (`session ...`) belong to the console and are not
318
+ * available: they resolve with `{ ok: false, code: 'SESSION_REFUSED' }`.
319
+ */
320
+ runCommand: (command: string | Command, options?: RunCommandOptions) => Promise<CommandResult>;
260
321
  /**
261
322
  * The WebMCP registration when the `webmcp` mount option was set and the
262
323
  * browser has the API; `undefined` otherwise. The adapter attaches in the