@flowdrop/flowdrop 2.0.0-beta.4 → 2.0.0-beta.6

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 (59) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/dist/adapters/WorkflowAdapter.js +4 -5
  3. package/dist/adapters/agentspec/AgentSpecAdapter.js +3 -3
  4. package/dist/adapters/agentspec/defaultNodeTypes.js +9 -9
  5. package/dist/commands/executor.js +5 -6
  6. package/dist/commands/types.js +5 -5
  7. package/dist/components/App.svelte +5 -14
  8. package/dist/components/ConfigForm.svelte +6 -505
  9. package/dist/components/ConfigForm.svelte.d.ts +4 -6
  10. package/dist/components/ConfigModal.svelte +0 -1
  11. package/dist/components/NodeSidebar.svelte +4 -4
  12. package/dist/components/NodeSwapPicker.svelte +2 -2
  13. package/dist/components/UniversalNode.svelte +5 -4
  14. package/dist/components/UniversalNode.svelte.d.ts +1 -1
  15. package/dist/components/console/ConsoleInput.svelte +3 -3
  16. package/dist/components/form/FormField.svelte +15 -0
  17. package/dist/components/form/FormFieldLight.svelte +14 -0
  18. package/dist/components/form/FormPorts.svelte +262 -0
  19. package/dist/components/form/FormPorts.svelte.d.ts +13 -0
  20. package/dist/components/nodes/AtomNode.svelte +16 -42
  21. package/dist/components/nodes/AtomNode.svelte.d.ts +1 -1
  22. package/dist/components/nodes/GatewayNode.svelte +26 -65
  23. package/dist/components/nodes/GatewayNode.svelte.d.ts +1 -1
  24. package/dist/components/nodes/IdeaNode.svelte +10 -8
  25. package/dist/components/nodes/IdeaNode.svelte.d.ts +8 -4
  26. package/dist/components/nodes/NotesNode.svelte +6 -4
  27. package/dist/components/nodes/NotesNode.svelte.d.ts +8 -4
  28. package/dist/components/nodes/SimpleNode.svelte +31 -55
  29. package/dist/components/nodes/SimpleNode.svelte.d.ts +4 -4
  30. package/dist/components/nodes/SquareNode.svelte +31 -55
  31. package/dist/components/nodes/SquareNode.svelte.d.ts +4 -4
  32. package/dist/components/nodes/TerminalNode.svelte +34 -38
  33. package/dist/components/nodes/TerminalNode.svelte.d.ts +4 -4
  34. package/dist/components/nodes/ToolNode.svelte +10 -8
  35. package/dist/components/nodes/ToolNode.svelte.d.ts +6 -6
  36. package/dist/components/nodes/WorkflowNode.svelte +43 -93
  37. package/dist/components/nodes/WorkflowNode.svelte.d.ts +1 -1
  38. package/dist/components/playground/PipelineKanbanView.svelte +2 -2
  39. package/dist/components/playground/PipelineTableView.svelte +2 -2
  40. package/dist/core/index.d.ts +1 -1
  41. package/dist/helpers/workflowEditorHelper.js +4 -5
  42. package/dist/openapi/v1/openapi.yaml +33 -21
  43. package/dist/registry/nodeComponentRegistry.d.ts +2 -1
  44. package/dist/schemas/v1/workflow.schema.json +16 -14
  45. package/dist/services/dynamicSchemaService.d.ts +2 -2
  46. package/dist/services/dynamicSchemaService.js +8 -8
  47. package/dist/stores/playgroundStore.svelte.js +1 -1
  48. package/dist/stores/workflowStore.svelte.d.ts +1 -1
  49. package/dist/stores/workflowStore.svelte.js +1 -19
  50. package/dist/types/index.d.ts +51 -27
  51. package/dist/utils/colors.d.ts +27 -0
  52. package/dist/utils/colors.js +23 -0
  53. package/dist/utils/connections.js +6 -6
  54. package/dist/utils/nodeIds.d.ts +1 -1
  55. package/dist/utils/nodeIds.js +1 -1
  56. package/dist/utils/nodeSwap.js +3 -6
  57. package/dist/utils/portUtils.d.ts +47 -11
  58. package/dist/utils/portUtils.js +67 -14
  59. package/package.json +1 -1
@@ -212,7 +212,7 @@ export class PlaygroundStore {
212
212
  // Find input nodes in the workflow
213
213
  workflow.nodes.forEach((node) => {
214
214
  const category = node.data.metadata?.category;
215
- const nodeTypeId = node.data.metadata?.id ?? node.type;
215
+ const nodeTypeId = node.data.metadata?.node_type_id ?? node.type;
216
216
  // Check if this is an input-type node
217
217
  // The category can be "inputs" (standard) or variations like "input"
218
218
  const categoryStr = String(category || '');
@@ -129,7 +129,7 @@ export declare class WorkflowStore {
129
129
  /**
130
130
  * Set of all handle IDs currently connected to edges.
131
131
  *
132
- * Used by node components to implement hideUnconnectedHandles.
132
+ * Handle IDs are formatted `{nodeId}-{direction}-{portId}`.
133
133
  */
134
134
  get connectedHandles(): Set<string>;
135
135
  /**
@@ -94,23 +94,6 @@ function hasWorkflowDataChanged(currentWorkflow, newNodes, newEdges) {
94
94
  }
95
95
  return false;
96
96
  }
97
- /**
98
- * Heal nodes that are missing `data.nodeId`.
99
- *
100
- * Node components derive their handle IDs from `data.nodeId` — a node without
101
- * it renders with zero handles and SvelteFlow silently drops every edge
102
- * anchored to it, making an intact graph look corrupted on the canvas.
103
- * `data.nodeId` always equals the node's own `id`, so it is safe to restore.
104
- */
105
- function healMissingNodeIds(workflow) {
106
- if (!workflow.nodes?.some((node) => !node.data.nodeId)) {
107
- return workflow;
108
- }
109
- return {
110
- ...workflow,
111
- nodes: workflow.nodes.map((node) => node.data.nodeId ? node : { ...node, data: { ...node.data, nodeId: node.id } })
112
- };
113
- }
114
97
  // =========================================================================
115
98
  // WorkflowStore (per-instance reactive state)
116
99
  // =========================================================================
@@ -254,7 +237,7 @@ export class WorkflowStore {
254
237
  /**
255
238
  * Set of all handle IDs currently connected to edges.
256
239
  *
257
- * Used by node components to implement hideUnconnectedHandles.
240
+ * Handle IDs are formatted `{nodeId}-{direction}-{portId}`.
258
241
  */
259
242
  get connectedHandles() {
260
243
  const handles = new Set();
@@ -373,7 +356,6 @@ export class WorkflowStore {
373
356
  */
374
357
  initialize(workflow) {
375
358
  workflow = normalizeWorkflowMetadata(workflow);
376
- workflow = healMissingNodeIds(workflow);
377
359
  this.#workflow = workflow;
378
360
  // Reset version counters — workflow is "clean" after initialization
379
361
  this.#editVersion = 0;
@@ -117,12 +117,57 @@ export interface NodePort {
117
117
  required?: boolean;
118
118
  description?: string;
119
119
  defaultValue?: unknown;
120
+ /**
121
+ * Whether this port is exposed when the instance sets no explicit exposure
122
+ * for it. Defaults to `true` (a missing flag reads as exposed). Reserved ports
123
+ * that ship hidden until an author opts in (e.g. the `error` output) carry
124
+ * `false`. The instance's `ports` config can override it per port. See
125
+ * `.claude/plans/exposed-ports.md`.
126
+ */
127
+ exposedByDefault?: boolean;
128
+ /**
129
+ * Default sort weight for the port's render position, ascending; ties break
130
+ * on declaration order. Author-declared ports default to `0`. Reserved ports
131
+ * (the `error` output and `trigger`/`tool` control ports) need no value — the
132
+ * library sinks them to the bottom automatically (see
133
+ * `RESERVED_PORT_DISPLAY_ORDER`); set this only to override that. Cosmetic
134
+ * only. The instance's `ports` config order overrides it.
135
+ */
136
+ displayOrder?: number;
120
137
  /**
121
138
  * Optional JSON Schema describing the structure of data on this port.
122
139
  * Used for template variable autocomplete to drill into nested properties.
123
140
  */
124
141
  schema?: OutputSchema | InputSchema;
125
142
  }
143
+ /**
144
+ * One entry in a {@link PortsConfig} direction list: a port id, with display
145
+ * order encoded by its position and an optional exposure override.
146
+ */
147
+ export interface PortConfigEntry {
148
+ id: string;
149
+ /**
150
+ * Explicit exposure for this port. Stored only when it diverges from the
151
+ * port's metadata `exposedByDefault`. In v2 exposure is semantic: a
152
+ * not-exposed port is hidden on the canvas, not wireable, and not
153
+ * runtime-overridable.
154
+ */
155
+ exposed?: boolean;
156
+ }
157
+ /**
158
+ * Per-instance port order + exposure, stored in `data.config.ports`.
159
+ *
160
+ * A per-direction ordered list of the node's ports: array index encodes display
161
+ * order relative to the metadata default, and the optional `exposed` flag
162
+ * overrides the port's `exposedByDefault`. A port the author never touched is
163
+ * absent from the list; an untouched node stores no `ports` key at all. Order
164
+ * is cosmetic (the engine ignores it); exposure is semantic. See
165
+ * `.claude/plans/exposed-ports.md`.
166
+ */
167
+ export interface PortsConfig {
168
+ inputs?: PortConfigEntry[];
169
+ outputs?: PortConfigEntry[];
170
+ }
126
171
  /**
127
172
  * Absolute position of a port handle in canvas space.
128
173
  * Used by proximity connect and other features that need port positions.
@@ -327,7 +372,7 @@ export interface AutocompleteConfig {
327
372
  * method: "GET",
328
373
  * headers: { "X-Custom-Header": "value" },
329
374
  * parameterMapping: {
330
- * nodeTypeId: "metadata.id",
375
+ * nodeTypeId: "metadata.node_type_id",
331
376
  * instanceId: "id"
332
377
  * }
333
378
  * };
@@ -352,7 +397,7 @@ export interface DynamicSchemaEndpoint {
352
397
  /**
353
398
  * Maps template variables to their source paths.
354
399
  * Keys are variable names used in the URL, values are dot-notation paths
355
- * to resolve from the node context (e.g., "metadata.id", "config.apiKey", "id")
400
+ * to resolve from the node context (e.g., "metadata.node_type_id", "config.apiKey", "id")
356
401
  */
357
402
  parameterMapping?: Record<string, string>;
358
403
  /**
@@ -381,7 +426,7 @@ export interface DynamicSchemaEndpoint {
381
426
  * url: "https://admin.example.com/nodes/{nodeTypeId}/edit/{instanceId}",
382
427
  * label: "Configure in Admin Panel",
383
428
  * parameterMapping: {
384
- * nodeTypeId: "metadata.id",
429
+ * nodeTypeId: "metadata.node_type_id",
385
430
  * instanceId: "id"
386
431
  * },
387
432
  * openInNewTab: true
@@ -408,7 +453,7 @@ export interface ExternalEditLink {
408
453
  /**
409
454
  * Maps template variables to their source paths.
410
455
  * Keys are variable names used in the URL, values are dot-notation paths
411
- * to resolve from the node context (e.g., "metadata.id", "config.apiKey", "id")
456
+ * to resolve from the node context (e.g., "metadata.node_type_id", "config.apiKey", "id")
412
457
  */
413
458
  parameterMapping?: Record<string, string>;
414
459
  /**
@@ -529,27 +574,8 @@ export interface AtomUIConfig {
529
574
  maxWidth?: number;
530
575
  }
531
576
  export interface NodeUIExtensions {
532
- /** Show/hide unconnected handles (ports) to reduce visual noise */
533
- hideUnconnectedHandles?: boolean;
534
577
  /** Display/behavior config for minimalist atom nodes (Constant, Cast, …) */
535
578
  atom?: AtomUIConfig;
536
- /**
537
- * Visual-only port display order (no effect on execution).
538
- * Arrays of port IDs in the desired render order.
539
- * Ports not listed appear at the end in metadata order.
540
- */
541
- portOrder?: {
542
- inputs?: string[];
543
- outputs?: string[];
544
- };
545
- /**
546
- * Manually hidden ports (visual only, no effect on execution).
547
- * Required ports cannot be added here — enforced in the UI.
548
- */
549
- hiddenPorts?: {
550
- inputs?: string[];
551
- outputs?: string[];
552
- };
553
579
  /** Custom styles or theme overrides */
554
580
  style?: Record<string, unknown>;
555
581
  /** Any other UI-specific settings */
@@ -563,7 +589,6 @@ export interface NodeUIExtensions {
563
589
  * ```typescript
564
590
  * const extensions: NodeExtensions = {
565
591
  * ui: {
566
- * hideUnconnectedHandles: true,
567
592
  * style: { opacity: 0.8 }
568
593
  * },
569
594
  * "myapp:analytics": {
@@ -602,7 +627,8 @@ export interface NodeExtensions {
602
627
  * Node configuration metadata
603
628
  */
604
629
  export interface NodeMetadata {
605
- id: string;
630
+ /** The node type entity id — the runtime's resolution anchor. */
631
+ node_type_id: string;
606
632
  name: string;
607
633
  type?: NodeType;
608
634
  /**
@@ -1132,8 +1158,6 @@ export interface WorkflowNode extends Node {
1132
1158
  isProcessing?: boolean;
1133
1159
  /** Error message if the node execution failed */
1134
1160
  error?: string;
1135
- /** Alternative node identifier */
1136
- nodeId?: string;
1137
1161
  /** Node execution tracking information */
1138
1162
  executionInfo?: NodeExecutionInfo;
1139
1163
  /**
@@ -241,6 +241,33 @@ export declare function getPortBackgroundColor(checker: PortCompatibilityChecker
241
241
  * @returns CSS color value for the port border
242
242
  */
243
243
  export declare function getPortBorderColor(checker: PortCompatibilityChecker, dataType: string): string;
244
+ /**
245
+ * Whether a port is the reserved `error` output port.
246
+ *
247
+ * The reserved error output carries an arbitrary data type (json) but should
248
+ * read as an error affordance (red) wherever it surfaces. See
249
+ * `.claude/plans/exposed-ports.md`.
250
+ */
251
+ export declare function isErrorPort(port: {
252
+ id: string;
253
+ type?: string;
254
+ }): boolean;
255
+ /**
256
+ * Port colour token: red for the reserved error output, else its data type.
257
+ */
258
+ export declare function getPortColorToken(checker: PortCompatibilityChecker, port: {
259
+ id: string;
260
+ type?: string;
261
+ dataType: string;
262
+ }): string;
263
+ /**
264
+ * Port background tint, honouring the reserved error port's red affordance.
265
+ */
266
+ export declare function getPortBackgroundColorForPort(checker: PortCompatibilityChecker, port: {
267
+ id: string;
268
+ type?: string;
269
+ dataType: string;
270
+ }, opacity?: number): string;
244
271
  /**
245
272
  * Convert RGB components to hex color string
246
273
  * @param r - Red component (0-255)
@@ -429,6 +429,29 @@ export function getPortBackgroundColor(checker, dataType, opacity = 25) {
429
429
  export function getPortBorderColor(checker, dataType) {
430
430
  return getDataTypeColorToken(checker, dataType);
431
431
  }
432
+ /**
433
+ * Whether a port is the reserved `error` output port.
434
+ *
435
+ * The reserved error output carries an arbitrary data type (json) but should
436
+ * read as an error affordance (red) wherever it surfaces. See
437
+ * `.claude/plans/exposed-ports.md`.
438
+ */
439
+ export function isErrorPort(port) {
440
+ return port.id === 'error' && port.type !== 'input';
441
+ }
442
+ /**
443
+ * Port colour token: red for the reserved error output, else its data type.
444
+ */
445
+ export function getPortColorToken(checker, port) {
446
+ return isErrorPort(port) ? 'var(--fd-node-red)' : getDataTypeColorToken(checker, port.dataType);
447
+ }
448
+ /**
449
+ * Port background tint, honouring the reserved error port's red affordance.
450
+ */
451
+ export function getPortBackgroundColorForPort(checker, port, opacity = 25) {
452
+ const colorToken = getPortColorToken(checker, port);
453
+ return `color-mix(in srgb, ${colorToken} ${opacity}%, transparent)`;
454
+ }
432
455
  /**
433
456
  * Convert RGB components to hex color string
434
457
  * @param r - Red component (0-255)
@@ -119,7 +119,7 @@ export class PortCompatibilityChecker {
119
119
  * Get all possible connections from a source node to target nodes
120
120
  */
121
121
  export function getPossibleConnections(checker, sourceNode, targetNodes, nodeTypes) {
122
- const sourceMetadata = nodeTypes.find((nt) => nt.id === sourceNode.data.metadata.id);
122
+ const sourceMetadata = nodeTypes.find((nt) => nt.node_type_id === sourceNode.data.metadata.node_type_id);
123
123
  if (!sourceMetadata)
124
124
  return [];
125
125
  const possibleConnections = [];
@@ -129,7 +129,7 @@ export function getPossibleConnections(checker, sourceNode, targetNodes, nodeTyp
129
129
  for (const targetNode of targetNodes) {
130
130
  if (targetNode.id === sourceNode.id)
131
131
  continue; // Skip self-connection
132
- const targetMetadata = nodeTypes.find((nt) => nt.id === targetNode.data.metadata.id);
132
+ const targetMetadata = nodeTypes.find((nt) => nt.node_type_id === targetNode.data.metadata.node_type_id);
133
133
  if (!targetMetadata)
134
134
  continue;
135
135
  // Get all input ports from target node
@@ -170,8 +170,8 @@ export function validateConnection(checker, sourceNodeId, sourcePortId, targetNo
170
170
  return { valid: false, error: 'Cannot connect node to itself' };
171
171
  }
172
172
  // Get node metadata
173
- const sourceMetadata = nodeTypes.find((nt) => nt.id === sourceNode.data.metadata.id);
174
- const targetMetadata = nodeTypes.find((nt) => nt.id === targetNode.data.metadata.id);
173
+ const sourceMetadata = nodeTypes.find((nt) => nt.node_type_id === sourceNode.data.metadata.node_type_id);
174
+ const targetMetadata = nodeTypes.find((nt) => nt.node_type_id === targetNode.data.metadata.node_type_id);
175
175
  if (!sourceMetadata || !targetMetadata) {
176
176
  return { valid: false, error: 'Node metadata not found' };
177
177
  }
@@ -200,14 +200,14 @@ export function getConnectionSuggestions(checker, nodeId, nodes, nodeTypes) {
200
200
  const node = nodes.find((n) => n.id === nodeId);
201
201
  if (!node)
202
202
  return [];
203
- const metadata = nodeTypes.find((nt) => nt.id === node.data.metadata.id);
203
+ const metadata = nodeTypes.find((nt) => nt.node_type_id === node.data.metadata.node_type_id);
204
204
  if (!metadata)
205
205
  return [];
206
206
  const suggestions = [];
207
207
  // Get all other nodes
208
208
  const otherNodes = nodes.filter((n) => n.id !== nodeId);
209
209
  for (const otherNode of otherNodes) {
210
- const otherMetadata = nodeTypes.find((nt) => nt.id === otherNode.data.metadata.id);
210
+ const otherMetadata = nodeTypes.find((nt) => nt.node_type_id === otherNode.data.metadata.node_type_id);
211
211
  if (!otherMetadata)
212
212
  continue;
213
213
  // Check outputs from other nodes to inputs of current node
@@ -12,7 +12,7 @@ interface NodeWithMetadata {
12
12
  id: string;
13
13
  data?: {
14
14
  metadata?: {
15
- id?: string;
15
+ node_type_id?: string;
16
16
  };
17
17
  };
18
18
  }
@@ -11,7 +11,7 @@
11
11
  export function generateNodeId(nodeTypeId, existingNodes) {
12
12
  // Count how many nodes of this type already exist
13
13
  const existingNodeIds = existingNodes
14
- .filter((node) => node.data?.metadata?.id === nodeTypeId)
14
+ .filter((node) => node.data?.metadata?.node_type_id === nodeTypeId)
15
15
  .map((node) => node.id);
16
16
  // Extract the numbers from existing IDs with the same prefix
17
17
  const existingNumbers = existingNodeIds
@@ -176,9 +176,6 @@ export function executeSwap(oldNode, newMetadata, preview, allNodes, allEdges) {
176
176
  label: newMetadata.name,
177
177
  config: mappedConfig,
178
178
  metadata: newMetadata,
179
- // Node components derive their handle IDs from data.nodeId — without it
180
- // every edge anchored to this node silently disappears from the canvas.
181
- nodeId: newNodeId,
182
179
  extensions
183
180
  }
184
181
  };
@@ -218,7 +215,7 @@ export function executeSwap(oldNode, newMetadata, preview, allNodes, allEdges) {
218
215
  * @returns The newer NodeMetadata if an upgrade is available, null otherwise
219
216
  */
220
217
  export function getVersionUpgrade(currentMetadata, allNodeTypes) {
221
- const available = allNodeTypes.find((n) => n.id === currentMetadata.id);
218
+ const available = allNodeTypes.find((n) => n.node_type_id === currentMetadata.node_type_id);
222
219
  if (!available)
223
220
  return null;
224
221
  if (compareSemver(available.version, currentMetadata.version) > 0) {
@@ -253,7 +250,7 @@ function classifyMatch(oldPort, matchedPort) {
253
250
  export function computeSwapPreviewWithOptions(oldNode, newMetadata, edges, allNodes, options) {
254
251
  const checker = options.checker ?? null;
255
252
  const oldNodeId = oldNode.id;
256
- const newNodeId = generateNodeId(newMetadata.id, allNodes);
253
+ const newNodeId = generateNodeId(newMetadata.node_type_id, allNodes);
257
254
  // Collect connected edges
258
255
  const connectedEdges = edges.filter((e) => e.source === oldNodeId || e.target === oldNodeId);
259
256
  // Try strategy-based port mapping
@@ -420,7 +417,7 @@ export function computeSwapPreviewWithOptions(oldNode, newMetadata, edges, allNo
420
417
  */
421
418
  export function computeInteractiveState(oldNode, newMetadata, edges, allNodes, options = {}) {
422
419
  const oldNodeId = oldNode.id;
423
- const newNodeId = generateNodeId(newMetadata.id, allNodes);
420
+ const newNodeId = generateNodeId(newMetadata.node_type_id, allNodes);
424
421
  const connectedEdges = edges.filter((e) => e.source === oldNodeId || e.target === oldNodeId);
425
422
  // Compute the base preview to get auto-matched ports
426
423
  const preview = computeSwapPreviewWithOptions(oldNode, newMetadata, edges, allNodes, options);
@@ -1,9 +1,46 @@
1
- import type { NodePort } from '../types/index.js';
1
+ import type { NodePort, PortConfigEntry, PortsConfig } from '../types/index.js';
2
+ /**
3
+ * Default sort weight applied to reserved ports (the `error` output and the
4
+ * `trigger`/`tool` control-flow ports) that don't set an explicit
5
+ * `displayOrder`. High enough to sink them below author-declared ports, which
6
+ * default to `0`. The single home for the "high weight" the docs refer to — an
7
+ * explicit `displayOrder` on the port still overrides it.
8
+ */
9
+ export declare const RESERVED_PORT_DISPLAY_ORDER = 100;
10
+ /**
11
+ * Whether a port is a reserved one that should default to the bottom of its
12
+ * direction: the reserved `error` output, or a `trigger`/`tool` control-flow
13
+ * port (identified by data type, mirroring the port config's control types).
14
+ */
15
+ export declare function isReservedPort(port: {
16
+ id: string;
17
+ type?: string;
18
+ dataType?: string;
19
+ }): boolean;
2
20
  /**
3
21
  * Sort ports by an ordered array of port IDs.
4
22
  * Ports not listed appear at the end in their original order.
5
23
  */
6
24
  export declare function applyPortOrder(ports: NodePort[], orderedIds: string[] | undefined): NodePort[];
25
+ /**
26
+ * Sort ports by their effective `displayOrder` weight (ascending), breaking ties
27
+ * on declaration order (stable). This is the default order before any
28
+ * instance-level reordering — reserved ports (trigger/tool/error) carry a high
29
+ * default weight so they land at the bottom without authors hand-setting it.
30
+ */
31
+ export declare function byDefaultOrder(ports: NodePort[]): NodePort[];
32
+ /**
33
+ * Effective render order for a direction: the metadata default order, then the
34
+ * instance's `ports` config override (listed ports first in their stored order,
35
+ * the rest following in default order).
36
+ */
37
+ export declare function orderPortsFor(ports: NodePort[], entries: PortConfigEntry[] | undefined): NodePort[];
38
+ /**
39
+ * Effective exposure for a port: the instance's explicit `exposed` override if
40
+ * present, else the port's metadata `exposedByDefault` (which itself defaults to
41
+ * exposed).
42
+ */
43
+ export declare function isPortExposed(port: NodePort, entries: PortConfigEntry[] | undefined): boolean;
7
44
  /**
8
45
  * Compute the CSS `top` offset (px) for a port handle.
9
46
  * - 1 port: centered at 40px
@@ -11,14 +48,13 @@ export declare function applyPortOrder(ports: NodePort[], orderedIds: string[] |
11
48
  */
12
49
  export declare function getPortTop(index: number, count: number): number;
13
50
  /**
14
- * Determine whether a port should be rendered.
51
+ * Whether a port is exposed, and so rendered on the canvas.
52
+ *
53
+ * In v2 exposure is semantic, not cosmetic: a not-exposed port is hidden, not
54
+ * wireable, and not runtime-overridable. Effective exposure is the instance's
55
+ * explicit `data.config.ports` override for the port, falling back to the port's
56
+ * metadata `exposedByDefault` (which itself defaults to exposed).
15
57
  *
16
- * Priority:
17
- * 1. Manual hide (`hiddenPorts`) — always wins, regardless of connections
18
- * 2. `hideUnconnectedHandles` — hide if not present in the connected handles set
19
- * 3. Default — visible
20
- */
21
- export declare function isPortVisible(port: NodePort, direction: 'input' | 'output', hiddenPorts: {
22
- inputs?: string[];
23
- outputs?: string[];
24
- }, hideUnconnectedHandles: boolean, connectedHandles: Set<string>, nodeId: string | undefined): boolean;
58
+ * @see .claude/plans/exposed-ports.md
59
+ */
60
+ export declare function isPortVisible(port: NodePort, direction: 'input' | 'output', ports: PortsConfig | undefined): boolean;
@@ -1,3 +1,27 @@
1
+ import { isErrorPort } from './colors.js';
2
+ /**
3
+ * Default sort weight applied to reserved ports (the `error` output and the
4
+ * `trigger`/`tool` control-flow ports) that don't set an explicit
5
+ * `displayOrder`. High enough to sink them below author-declared ports, which
6
+ * default to `0`. The single home for the "high weight" the docs refer to — an
7
+ * explicit `displayOrder` on the port still overrides it.
8
+ */
9
+ export const RESERVED_PORT_DISPLAY_ORDER = 100;
10
+ /**
11
+ * Whether a port is a reserved one that should default to the bottom of its
12
+ * direction: the reserved `error` output, or a `trigger`/`tool` control-flow
13
+ * port (identified by data type, mirroring the port config's control types).
14
+ */
15
+ export function isReservedPort(port) {
16
+ return isErrorPort(port) || port.dataType === 'trigger' || port.dataType === 'tool';
17
+ }
18
+ /**
19
+ * The port's effective default sort weight: its explicit `displayOrder` if set,
20
+ * else a high weight for reserved ports, else `0`.
21
+ */
22
+ function defaultWeight(port) {
23
+ return port.displayOrder ?? (isReservedPort(port) ? RESERVED_PORT_DISPLAY_ORDER : 0);
24
+ }
1
25
  /**
2
26
  * Sort ports by an ordered array of port IDs.
3
27
  * Ports not listed appear at the end in their original order.
@@ -13,6 +37,38 @@ export function applyPortOrder(ports, orderedIds) {
13
37
  return aIdx === bIdx ? 0 : aIdx - bIdx;
14
38
  });
15
39
  }
40
+ /**
41
+ * Sort ports by their effective `displayOrder` weight (ascending), breaking ties
42
+ * on declaration order (stable). This is the default order before any
43
+ * instance-level reordering — reserved ports (trigger/tool/error) carry a high
44
+ * default weight so they land at the bottom without authors hand-setting it.
45
+ */
46
+ export function byDefaultOrder(ports) {
47
+ return ports
48
+ .map((port, index) => ({ port, index }))
49
+ .sort((a, b) => defaultWeight(a.port) - defaultWeight(b.port) || a.index - b.index)
50
+ .map(({ port }) => port);
51
+ }
52
+ /**
53
+ * Effective render order for a direction: the metadata default order, then the
54
+ * instance's `ports` config override (listed ports first in their stored order,
55
+ * the rest following in default order).
56
+ */
57
+ export function orderPortsFor(ports, entries) {
58
+ const base = byDefaultOrder(ports);
59
+ return applyPortOrder(base, entries?.map((entry) => entry.id));
60
+ }
61
+ /**
62
+ * Effective exposure for a port: the instance's explicit `exposed` override if
63
+ * present, else the port's metadata `exposedByDefault` (which itself defaults to
64
+ * exposed).
65
+ */
66
+ export function isPortExposed(port, entries) {
67
+ const entry = entries?.find((candidate) => candidate.id === port.id);
68
+ if (entry && entry.exposed !== undefined)
69
+ return entry.exposed;
70
+ return port.exposedByDefault ?? true;
71
+ }
16
72
  /**
17
73
  * Compute the CSS `top` offset (px) for a port handle.
18
74
  * - 1 port: centered at 40px
@@ -24,19 +80,16 @@ export function getPortTop(index, count) {
24
80
  return 20 + index * 40;
25
81
  }
26
82
  /**
27
- * Determine whether a port should be rendered.
83
+ * Whether a port is exposed, and so rendered on the canvas.
28
84
  *
29
- * Priority:
30
- * 1. Manual hide (`hiddenPorts`) — always wins, regardless of connections
31
- * 2. `hideUnconnectedHandles` — hide if not present in the connected handles set
32
- * 3. Default — visible
33
- */
34
- export function isPortVisible(port, direction, hiddenPorts, hideUnconnectedHandles, connectedHandles, nodeId) {
35
- const hiddenList = direction === 'input' ? hiddenPorts.inputs : hiddenPorts.outputs;
36
- if (hiddenList?.includes(port.id))
37
- return false;
38
- if (hideUnconnectedHandles) {
39
- return connectedHandles.has(`${nodeId}-${direction}-${port.id}`);
40
- }
41
- return true;
85
+ * In v2 exposure is semantic, not cosmetic: a not-exposed port is hidden, not
86
+ * wireable, and not runtime-overridable. Effective exposure is the instance's
87
+ * explicit `data.config.ports` override for the port, falling back to the port's
88
+ * metadata `exposedByDefault` (which itself defaults to exposed).
89
+ *
90
+ * @see .claude/plans/exposed-ports.md
91
+ */
92
+ export function isPortVisible(port, direction, ports) {
93
+ const entries = direction === 'input' ? ports?.inputs : ports?.outputs;
94
+ return isPortExposed(port, entries);
42
95
  }
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "description": "A drop-in visual workflow editor for any web application. You own the backend. You own the data. You own the orchestration.",
4
4
  "license": "MIT",
5
5
  "private": false,
6
- "version": "2.0.0-beta.4",
6
+ "version": "2.0.0-beta.6",
7
7
  "author": "Shibin Das (D34dMan)",
8
8
  "bugs": {
9
9
  "url": "https://github.com/flowdrop-io/flowdrop/issues"