@flowdrop/flowdrop 2.0.1 → 2.1.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 (35) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/dist/commands/executor.js +4 -1
  3. package/dist/commands/types.d.ts +4 -0
  4. package/dist/components/App.svelte +122 -12
  5. package/dist/components/WorkflowInterfaceEditor.svelte +941 -0
  6. package/dist/components/WorkflowInterfaceEditor.svelte.d.ts +14 -0
  7. package/dist/components/form/FormPorts.svelte +34 -2
  8. package/dist/components/nodes/GatewayNode.svelte +13 -1
  9. package/dist/components/nodes/SimpleNode.svelte +11 -0
  10. package/dist/components/nodes/SquareNode.svelte +11 -0
  11. package/dist/components/nodes/TerminalNode.svelte +11 -0
  12. package/dist/components/nodes/WorkflowNode.svelte +11 -2
  13. package/dist/core/index.d.ts +1 -1
  14. package/dist/messages/defaults.d.ts +42 -0
  15. package/dist/messages/defaults.js +34 -0
  16. package/dist/openapi/v1/openapi.yaml +105 -0
  17. package/dist/schemas/v1/workflow.schema.json +109 -0
  18. package/dist/services/globalSave.js +9 -2
  19. package/dist/services/workflowLaunchService.d.ts +13 -1
  20. package/dist/services/workflowLaunchService.js +8 -0
  21. package/dist/stores/workflowStore.svelte.d.ts +22 -0
  22. package/dist/stores/workflowStore.svelte.js +18 -0
  23. package/dist/styles/base.css +10 -0
  24. package/dist/types/index.d.ts +58 -4
  25. package/dist/utils/colors.d.ts +1 -2
  26. package/dist/utils/colors.js +1 -2
  27. package/dist/utils/connections.d.ts +5 -0
  28. package/dist/utils/connections.js +1 -1
  29. package/dist/utils/nodeSwap.d.ts +9 -0
  30. package/dist/utils/nodeSwap.js +50 -2
  31. package/dist/utils/portUtils.d.ts +0 -2
  32. package/dist/utils/portUtils.js +0 -2
  33. package/dist/utils/workflowInterface.d.ts +208 -0
  34. package/dist/utils/workflowInterface.js +391 -0
  35. package/package.json +1 -1
@@ -41,6 +41,16 @@
41
41
  "type": "object",
42
42
  "description": "Custom workflow-level configuration values. Populated when a workflowSettingsSchema is provided to the editor.",
43
43
  "additionalProperties": true
44
+ },
45
+ "interface": {
46
+ "allOf": [
47
+ {
48
+ "$ref": "#/$defs/WorkflowInterface"
49
+ },
50
+ {
51
+ "description": "Public contract for callers. Absent = the workflow declares no interface."
52
+ }
53
+ ]
44
54
  }
45
55
  },
46
56
  "required": [
@@ -784,6 +794,25 @@
784
794
  "const"
785
795
  ]
786
796
  },
797
+ "PortBinding": {
798
+ "type": "object",
799
+ "description": "A resolved pointer to one inner node port, used by `WorkflowInterfaceEntry.bindings`.\n",
800
+ "properties": {
801
+ "nodeId": {
802
+ "type": "string",
803
+ "format": "uuid",
804
+ "description": "Node instance UUID (references `WorkflowNode.id`)"
805
+ },
806
+ "portId": {
807
+ "type": "string",
808
+ "description": "Port ID on that node (references a `NodePort.id` in the node's metadata)"
809
+ }
810
+ },
811
+ "required": [
812
+ "nodeId",
813
+ "portId"
814
+ ]
815
+ },
787
816
  "PortDataSchema": {
788
817
  "type": "object",
789
818
  "description": "JSON Schema describing the structure of data on an output port.\nFollows JSON Schema draft-07 specification.\n\n## Purpose\n\nEnables template variable autocomplete in downstream nodes by describing\nthe shape of data that flows through the port.\n\n## Supported Features\n\n- **Objects**: Define `properties` to enable dot notation drilling\n- **Arrays**: Define `items` to enable index access and item property drilling\n- **Nested structures**: Combine objects and arrays for deep drilling\n- **Metadata**: Use `title` and `description` for autocomplete tooltips\n\n## Example\n\nA schema describing an API response with user data and orders:\n\n```yaml\ntype: object\nproperties:\n user:\n type: object\n title: User\n description: The authenticated user\n properties:\n id: { type: integer }\n name: { type: string, description: \"User's full name\" }\n email: { type: string }\n address:\n type: object\n properties:\n city: { type: string }\n country: { type: string }\n orders:\n type: array\n title: Orders\n description: User's order history\n items:\n type: object\n properties:\n order_id: { type: string }\n total: { type: number }\n status: { type: string }\n```\n\nThis enables template patterns like:\n- `{{ user.name }}` - Access user's name\n- `{{ user.address.city }}` - Nested property access\n- `{{ orders[0].total }}` - First order's total\n- `{{ orders[0].status }}` - First order's status\n",
@@ -1056,6 +1085,86 @@
1056
1085
  "target"
1057
1086
  ]
1058
1087
  },
1088
+ "WorkflowInterface": {
1089
+ "type": "object",
1090
+ "description": "A workflow's public contract: named inputs/outputs that external callers supply\nor receive, each pointing at an inner node port via a binding. Array order is\nthe caller-facing order. Absent on a `Workflow` means the workflow declares no\ninterface, not an empty one.\n",
1091
+ "properties": {
1092
+ "inputs": {
1093
+ "type": "array",
1094
+ "items": {
1095
+ "$ref": "#/$defs/WorkflowInterfaceEntry"
1096
+ },
1097
+ "description": "Named inputs external callers supply."
1098
+ },
1099
+ "outputs": {
1100
+ "type": "array",
1101
+ "items": {
1102
+ "$ref": "#/$defs/WorkflowInterfaceEntry"
1103
+ },
1104
+ "description": "Named outputs external callers receive."
1105
+ }
1106
+ }
1107
+ },
1108
+ "WorkflowInterfaceEntry": {
1109
+ "type": "object",
1110
+ "description": "One entry in a workflow's public contract (see `WorkflowInterface`). Owns its own\nidentity: `id` is stable and unique within its direction (inputs and outputs are\nscoped separately), independent of whichever inner port it currently binds to —\nswapping or renaming a node does not silently break callers.\n\nOn export toward a server manifest the entry's `id` maps to the manifest's `name`\n— the server's wire identity. Renaming an `id` is therefore a breaking change for\ncallers, not a cosmetic one.\n\nEvery entry — input or output — must resolve to exactly one binding; more than\none is reported as `over-bound`. An empty `bindings` list is a valid *draft*\nstate, reported as `unbound`.\n",
1111
+ "properties": {
1112
+ "id": {
1113
+ "type": "string",
1114
+ "description": "Stable public name. Unique within its direction (inputs vs outputs)."
1115
+ },
1116
+ "name": {
1117
+ "type": "string",
1118
+ "description": "Display label for callers and UI. Defaults to `id` when absent."
1119
+ },
1120
+ "description": {
1121
+ "type": "string",
1122
+ "description": "Help text describing what this entry represents to external callers."
1123
+ },
1124
+ "dataType": {
1125
+ "$ref": "#/$defs/NodeDataType"
1126
+ },
1127
+ "required": {
1128
+ "type": "boolean",
1129
+ "description": "Whether callers must supply a value. Inputs only; ignored on outputs."
1130
+ },
1131
+ "defaultValue": {
1132
+ "description": "Default value used when no external value is supplied. Inputs only."
1133
+ },
1134
+ "examples": {
1135
+ "type": "array",
1136
+ "items": {},
1137
+ "description": "Example values a caller could supply — author metadata for documentation\nand launch forms, mirroring the server manifest's `examples`. Inputs\nonly; ignored on outputs. Never validated against `schema`.\n"
1138
+ },
1139
+ "schema": {
1140
+ "allOf": [
1141
+ {
1142
+ "$ref": "#/$defs/PortDataSchema"
1143
+ },
1144
+ {
1145
+ "description": "JSON Schema describing the structure of data carried by this entry."
1146
+ }
1147
+ ]
1148
+ },
1149
+ "bindings": {
1150
+ "type": "array",
1151
+ "items": {
1152
+ "$ref": "#/$defs/PortBinding"
1153
+ },
1154
+ "description": "Inner ports this entry maps to. Every entry must resolve to exactly one\nbinding; more than one is reported as `over-bound` (the list shape is kept\nso input fan-out can become additive later). An empty list is a valid\ndraft state, reported as `unbound`. The bound port must also be\ncanvas-exposed (see `NodePort.exposedByDefault` / `config.ports`) — a\nbound-but-hidden port is reported as `hidden`.\n"
1155
+ },
1156
+ "meta": {
1157
+ "type": "object",
1158
+ "additionalProperties": true,
1159
+ "description": "Opaque consumer metadata. The library never reads or interprets this field\n— it round-trips verbatim on every read/write. Servers use it to say what\n\"external\" means for them, e.g. `{\"http\": {\"in\": \"query\"}}` or\n`{\"mcp\": {\"toolParam\": true}}`.\n\nKeys under the `fd.` prefix are reserved for future library use — consumers\nmust not write keys starting with `fd.`.\n"
1160
+ }
1161
+ },
1162
+ "required": [
1163
+ "id",
1164
+ "dataType",
1165
+ "bindings"
1166
+ ]
1167
+ },
1059
1168
  "WorkflowMetadata": {
1060
1169
  "type": "object",
1061
1170
  "properties": {
@@ -120,7 +120,11 @@ export async function globalSaveWorkflow(options = {}) {
120
120
  format: currentWorkflow.metadata?.format || DEFAULT_WORKFLOW_FORMAT,
121
121
  createdAt: currentWorkflow.metadata?.createdAt || new Date().toISOString(),
122
122
  updatedAt: new Date().toISOString()
123
- }
123
+ },
124
+ // Explicit key list, so every contract field must be named here:
125
+ // omitting `interface` silently strips the declared contract on save
126
+ // (absent means "declares no interface" to the server).
127
+ ...(currentWorkflow.interface !== undefined && { interface: currentWorkflow.interface })
124
128
  };
125
129
  // Step 4 — Persist via this instance's API client.
126
130
  // id-presence (computed above) decides update vs create — never UUID-regex.
@@ -216,7 +220,10 @@ export async function globalExportWorkflow(options = {}) {
216
220
  format: currentWorkflow.metadata?.format || DEFAULT_WORKFLOW_FORMAT,
217
221
  createdAt: currentWorkflow.metadata?.createdAt || new Date().toISOString(),
218
222
  updatedAt: new Date().toISOString()
219
- }
223
+ },
224
+ // Same rule as the save path: the export must carry the declared
225
+ // contract, or a re-import round-trip loses `interface`.
226
+ ...(currentWorkflow.interface !== undefined && { interface: currentWorkflow.interface })
220
227
  };
221
228
  // Trigger browser download
222
229
  const dataStr = JSON.stringify(finalWorkflow, null, 2);
@@ -17,6 +17,7 @@
17
17
  */
18
18
  import type { EndpointConfig } from '../config/endpoints.js';
19
19
  import type { AuthProvider } from '../types/auth.js';
20
+ import type { Workflow } from '../types/index.js';
20
21
  /** A single per-input validation failure reported by the backend. */
21
22
  export interface LaunchInputError {
22
23
  /** Machine-readable error code. */
@@ -54,10 +55,21 @@ export type LaunchResult =
54
55
  status: 'unsupported';
55
56
  };
56
57
  export interface LaunchOptions {
57
- /** Named inputs, resolved server-side against the workflow's declared manifest. */
58
+ /**
59
+ * Named inputs, resolved server-side against the workflow's declared
60
+ * manifest. Keys are `WorkflowInterfaceEntry.id`s — the same identity the
61
+ * server matches on as the manifest's `name`.
62
+ */
58
63
  inputs?: Record<string, unknown>;
59
64
  /** Attribute the run to a session, so its messages land in that conversation. */
60
65
  sessionId?: string;
66
+ /**
67
+ * The workflow being launched. When it declares an `interface`, inputs are
68
+ * pre-validated against it client-side — unknown keys and missing required
69
+ * inputs return `invalid-input` without a network round-trip, mirroring the
70
+ * server's own refusal. Value type/schema checking stays with the server.
71
+ */
72
+ workflow?: Workflow;
61
73
  }
62
74
  declare class WorkflowLaunchService {
63
75
  /** True when this configuration exposes an explicit launch verb. */
@@ -17,6 +17,7 @@
17
17
  */
18
18
  import { buildEndpointUrl } from '../config/endpoints.js';
19
19
  import { authenticatedFetch } from '../utils/fetchWithAuth.js';
20
+ import { validateLaunchInputs } from '../utils/workflowInterface.js';
20
21
  import { logger } from '../utils/logger.js';
21
22
  class WorkflowLaunchService {
22
23
  /** True when this configuration exposes an explicit launch verb. */
@@ -33,6 +34,13 @@ class WorkflowLaunchService {
33
34
  const endpoint = config?.endpoints?.workflows?.run;
34
35
  if (!config || !endpoint)
35
36
  return { status: 'unsupported' };
37
+ const preflight = validateLaunchInputs(options.workflow?.interface, options.inputs ?? {});
38
+ if (preflight.length > 0) {
39
+ return {
40
+ status: 'invalid-input',
41
+ message: preflight.map((issue) => issue.message).join(' ')
42
+ };
43
+ }
36
44
  const url = buildEndpointUrl(config, endpoint, { workflowId });
37
45
  const body = {};
38
46
  if (options.inputs && Object.keys(options.inputs).length > 0)
@@ -13,6 +13,8 @@
13
13
  import type { Workflow, WorkflowNode, WorkflowEdge } from '../types';
14
14
  import type { WorkflowChangeType } from '../types/events.js';
15
15
  import type { HistoryService } from '../services/historyService.js';
16
+ import type { PortMapping } from '../utils/nodeSwap.js';
17
+ import type { WorkflowInterfaceEntry } from '../types/index.js';
16
18
  type WorkflowMetadata = Workflow['metadata'];
17
19
  /**
18
20
  * Loosely-typed shape a workflow may arrive in before healing — a 1.x document
@@ -68,11 +70,19 @@ export interface WorkflowStoreActions {
68
70
  description?: string;
69
71
  metadata?: Partial<Workflow['metadata']>;
70
72
  config?: Record<string, unknown>;
73
+ /** The workflow's public contract. Omit to leave it untouched. */
74
+ interface?: Workflow['interface'];
71
75
  }) => void;
72
76
  swapNode: (updates: {
73
77
  nodes: WorkflowNode[];
74
78
  edges: WorkflowEdge[];
75
79
  description?: string;
80
+ /** The swapped-out node's id and its replacement — together with
81
+ * `portMappings`, drives the `workflow.interface` binding rewrite. Omit
82
+ * either to leave `interface` untouched. */
83
+ oldNodeId?: string;
84
+ newNodeId?: string;
85
+ portMappings?: PortMapping[];
76
86
  }) => void;
77
87
  pushHistory: (description?: string, workflow?: Workflow) => void;
78
88
  }
@@ -136,6 +146,14 @@ export declare class WorkflowStore {
136
146
  * Handle IDs are formatted `{nodeId}-{direction}-{portId}`.
137
147
  */
138
148
  get connectedHandles(): Set<string>;
149
+ /**
150
+ * Handle IDs bound to a `workflow.interface` entry, mapped to the entry
151
+ * itself — one memoized pass over `resolveInterface`, shared by every node
152
+ * component and `FormPorts` instead of each re-deriving it per port. See
153
+ * `utils/workflowInterface.ts#interfaceBoundHandles` for what counts as
154
+ * "bound" (only bindings that resolve to a live port).
155
+ */
156
+ get interfaceBoundHandles(): Map<string, WorkflowInterfaceEntry>;
139
157
  /**
140
158
  * The current monotonic edit version.
141
159
  *
@@ -265,6 +283,7 @@ export declare class WorkflowStore {
265
283
  description?: string;
266
284
  metadata?: Partial<Workflow['metadata']>;
267
285
  config?: Record<string, unknown>;
286
+ interface?: Workflow['interface'];
268
287
  }): void;
269
288
  /**
270
289
  * Swap a node — atomically replaces nodes and edges with a descriptive history entry.
@@ -276,6 +295,9 @@ export declare class WorkflowStore {
276
295
  nodes: WorkflowNode[];
277
296
  edges: WorkflowEdge[];
278
297
  description?: string;
298
+ oldNodeId?: string;
299
+ newNodeId?: string;
300
+ portMappings?: PortMapping[];
279
301
  }): void;
280
302
  /**
281
303
  * Push the current (post-change) state to history manually.
@@ -12,6 +12,7 @@
12
12
  */
13
13
  import { DEFAULT_WORKFLOW_FORMAT } from '../types/index.js';
14
14
  import { WORKFLOW_SCHEMA_VERSION } from '../schemas/index.js';
15
+ import { interfaceBoundHandles, rewriteInterfaceBindings } from '../utils/workflowInterface.js';
15
16
  /**
16
17
  * Safely build updated workflow metadata, providing defaults for required fields.
17
18
  *
@@ -268,6 +269,16 @@ export class WorkflowStore {
268
269
  });
269
270
  return handles;
270
271
  }
272
+ /**
273
+ * Handle IDs bound to a `workflow.interface` entry, mapped to the entry
274
+ * itself — one memoized pass over `resolveInterface`, shared by every node
275
+ * component and `FormPorts` instead of each re-deriving it per port. See
276
+ * `utils/workflowInterface.ts#interfaceBoundHandles` for what counts as
277
+ * "bound" (only bindings that resolve to a live port).
278
+ */
279
+ get interfaceBoundHandles() {
280
+ return this.#workflow ? interfaceBoundHandles(this.#workflow) : new Map();
281
+ }
271
282
  /**
272
283
  * The current monotonic edit version.
273
284
  *
@@ -656,6 +667,7 @@ export class WorkflowStore {
656
667
  description: updates.description
657
668
  }),
658
669
  ...(updates.config !== undefined && { config: updates.config }),
670
+ ...(updates.interface !== undefined && { interface: updates.interface }),
659
671
  metadata: buildMetadata(this.#workflow.metadata, updates.metadata ?? undefined)
660
672
  };
661
673
  this.#pushToHistory('Batch update');
@@ -671,10 +683,16 @@ export class WorkflowStore {
671
683
  swapNode(updates) {
672
684
  if (!this.#workflow)
673
685
  return;
686
+ // Node swap is the one mutation that actively moves interface bindings —
687
+ // every other mutation (including delete) leaves them untouched.
688
+ const interfaceAfterSwap = updates.oldNodeId && updates.newNodeId
689
+ ? rewriteInterfaceBindings(this.#workflow.interface, updates.oldNodeId, updates.newNodeId, updates.portMappings ?? [])
690
+ : this.#workflow.interface;
674
691
  this.#workflow = {
675
692
  ...this.#workflow,
676
693
  nodes: updates.nodes,
677
694
  edges: updates.edges,
695
+ interface: interfaceAfterSwap,
678
696
  metadata: buildMetadata(this.#workflow.metadata)
679
697
  };
680
698
  this.#pushToHistory(updates.description ?? 'Swap node');
@@ -130,6 +130,16 @@ p {
130
130
  outline-offset: var(--fd-ring-offset);
131
131
  }
132
132
 
133
+ /* Interface-bound marker: a port bound to a `workflow.interface` entry
134
+ (see utils/workflowInterface.ts#interfaceBoundHandles) gets a subtle ring
135
+ around its visible dot. One shared class, applied by every node component
136
+ that renders a Handle, rather than five per-component styles. Reuses the
137
+ same --fd-ring token as the focus ring so it reads consistently — and
138
+ stays correct automatically — in both light and dark skins. */
139
+ .svelte-flow .svelte-flow__handle.flowdrop-handle--bound::before {
140
+ box-shadow: 0 0 0 var(--fd-ring-width) color-mix(in srgb, var(--fd-ring) 55%, transparent);
141
+ }
142
+
133
143
  /* Centralized handle edge positioning — offset derived from --fd-handle-size */
134
144
  .svelte-flow .svelte-flow__handle-left {
135
145
  left: var(--fd-handle-offset);
@@ -121,8 +121,7 @@ export interface NodePort {
121
121
  * Whether this port is exposed when the instance sets no explicit exposure
122
122
  * for it. Defaults to `true` (a missing flag reads as exposed). Reserved ports
123
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`.
124
+ * `false`. The instance's `ports` config can override it per port.
126
125
  */
127
126
  exposedByDefault?: boolean;
128
127
  /**
@@ -161,8 +160,7 @@ export interface PortConfigEntry {
161
160
  * order relative to the metadata default, and the optional `exposed` flag
162
161
  * overrides the port's `exposedByDefault`. A port the author never touched is
163
162
  * 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`.
163
+ * is cosmetic (the engine ignores it); exposure is semantic.
166
164
  */
167
165
  export interface PortsConfig {
168
166
  inputs?: PortConfigEntry[];
@@ -1232,6 +1230,60 @@ export interface WorkflowEdge extends Edge {
1232
1230
  targetCategory?: string;
1233
1231
  };
1234
1232
  }
1233
+ /**
1234
+ * A resolved pointer to one inner node port. Mirrors the handle-id triple in
1235
+ * `utils/handleIds.ts` without depending on its string encoding.
1236
+ */
1237
+ export interface PortBinding {
1238
+ nodeId: string;
1239
+ portId: string;
1240
+ }
1241
+ /**
1242
+ * One entry in a workflow's public contract. Owns its own identity: `id` is
1243
+ * stable and workflow-scoped, independent of whichever inner port it currently
1244
+ * binds to, so swapping or renaming a node does not silently break callers.
1245
+ *
1246
+ * On export toward a server manifest the entry's `id` maps to the manifest's
1247
+ * `name` — the server's wire identity. Renaming an `id` is therefore a breaking
1248
+ * change for callers, not a cosmetic one.
1249
+ */
1250
+ export interface WorkflowInterfaceEntry {
1251
+ /** Stable public name. Unique within its direction. */
1252
+ id: string;
1253
+ /** Display label for callers and UI. Defaults to `id` when absent. */
1254
+ name?: string;
1255
+ description?: string;
1256
+ dataType: NodeDataType;
1257
+ /** Inputs only; ignored on outputs. */
1258
+ required?: boolean;
1259
+ defaultValue?: unknown;
1260
+ /**
1261
+ * Example values a caller could supply — author metadata for docs and launch
1262
+ * forms, mirroring the server manifest's `examples`. Inputs only; ignored on
1263
+ * outputs. Never validated against `schema`.
1264
+ */
1265
+ examples?: unknown[];
1266
+ schema?: InputSchema | OutputSchema;
1267
+ /**
1268
+ * Inner ports this entry maps to. Every entry — input or output — must
1269
+ * resolve to exactly one binding; more than one is reported as `over-bound`.
1270
+ * (The list shape is kept so input fan-out can become additive later.) An
1271
+ * empty list is a valid *draft* state, reported as `unbound`.
1272
+ */
1273
+ bindings: PortBinding[];
1274
+ /**
1275
+ * Opaque consumer metadata. The library never reads or interprets this — it
1276
+ * round-trips verbatim. Servers use it to say what "external" means for them
1277
+ * (`{"http": {"in": "query"}}`, `{"mcp": {"toolParam": true}}`, …).
1278
+ * Keys under the `fd.` prefix are reserved for future library use.
1279
+ */
1280
+ meta?: Record<string, unknown>;
1281
+ }
1282
+ /** A workflow's public contract. Array order is the caller-facing order. */
1283
+ export interface WorkflowInterface {
1284
+ inputs?: WorkflowInterfaceEntry[];
1285
+ outputs?: WorkflowInterfaceEntry[];
1286
+ }
1235
1287
  /**
1236
1288
  * Complete workflow definition
1237
1289
  */
@@ -1255,6 +1307,8 @@ export interface Workflow {
1255
1307
  };
1256
1308
  /** Custom workflow-level configuration values, populated via workflowSettingsSchema. */
1257
1309
  config?: Record<string, unknown>;
1310
+ /** Public contract for callers. Absent = the workflow declares no interface. */
1311
+ interface?: WorkflowInterface;
1258
1312
  }
1259
1313
  /**
1260
1314
  * API response types
@@ -245,8 +245,7 @@ export declare function getPortBorderColor(checker: PortCompatibilityChecker, da
245
245
  * Whether a port is the reserved `error` output port.
246
246
  *
247
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`.
248
+ * read as an error affordance (red) wherever it surfaces.
250
249
  */
251
250
  export declare function isErrorPort(port: {
252
251
  id: string;
@@ -433,8 +433,7 @@ export function getPortBorderColor(checker, dataType) {
433
433
  * Whether a port is the reserved `error` output port.
434
434
  *
435
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`.
436
+ * read as an error affordance (red) wherever it surfaces.
438
437
  */
439
438
  export function isErrorPort(port) {
440
439
  return port.id === 'error' && port.type !== 'input';
@@ -2,6 +2,11 @@
2
2
  * Connection validation utilities for FlowDrop
3
3
  */
4
4
  import type { NodeMetadata, NodePort, NodeDataType, WorkflowNode, WorkflowEdge, PortConfig, PortDataTypeConfig } from '../types/index.js';
5
+ /**
6
+ * Loopback port name constant
7
+ * This is the standard input port name used for loop iteration triggers
8
+ */
9
+ export declare const LOOPBACK_PORT_NAME = "loop_back";
5
10
  /**
6
11
  * Determines if an edge is a loopback edge.
7
12
  * Loopback edges target the special `loop_back` input port on ForEach nodes.
@@ -5,7 +5,7 @@
5
5
  * Loopback port name constant
6
6
  * This is the standard input port name used for loop iteration triggers
7
7
  */
8
- const LOOPBACK_PORT_NAME = 'loop_back';
8
+ export const LOOPBACK_PORT_NAME = 'loop_back';
9
9
  /**
10
10
  * Determines if an edge is a loopback edge.
11
11
  * Loopback edges target the special `loop_back` input port on ForEach nodes.
@@ -45,6 +45,15 @@ export interface SwapPreview {
45
45
  configCarriedOver: string[];
46
46
  /** Config keys reset to defaults on the new node */
47
47
  configReset: string[];
48
+ /**
49
+ * Old-port → new-port resolution for every declared port on the old node,
50
+ * not just the ones a connected edge happens to touch — an interface
51
+ * binding can point at an exposed-but-unconnected port. Used to rewrite
52
+ * `workflow.interface` bindings through the swap (see
53
+ * `utils/workflowInterface.ts#rewriteInterfaceBindings`). A port the
54
+ * cascade drops has no entry here.
55
+ */
56
+ portMappings: PortMapping[];
48
57
  }
49
58
  /**
50
59
  * Result of executing a node swap.
@@ -355,6 +355,35 @@ export function computeSwapPreviewWithOptions(oldNode, newMetadata, edges, allNo
355
355
  }
356
356
  keptEdges.push({ edge, newEdge });
357
357
  }
358
+ // Resolve every declared port on the old node — not just the ones touched
359
+ // by a connected edge above — through the same override/strategy/matching
360
+ // cascade, reusing cached resolutions so an edge-driven port isn't matched
361
+ // twice. This is what workflow.interface bindings rewrite through; an
362
+ // interface binding may point at a port with no edge at all.
363
+ const portMappings = [];
364
+ for (const direction of ['input', 'output']) {
365
+ const oldPorts = direction === 'input' ? oldNode.data.metadata.inputs : oldNode.data.metadata.outputs;
366
+ const usedPorts = direction === 'input' ? usedInputPortIds : usedOutputPortIds;
367
+ for (const oldPort of oldPorts) {
368
+ const matchKey = `${direction}:${oldPort.id}`;
369
+ let resolved = portResolutions.get(matchKey);
370
+ if (!resolved) {
371
+ resolved = resolveNewPort(oldPort, direction, usedPorts);
372
+ portResolutions.set(matchKey, resolved);
373
+ if (resolved.port)
374
+ usedPorts.add(resolved.port.id);
375
+ }
376
+ if (resolved.port) {
377
+ portMappings.push({
378
+ oldHandleId: buildHandleId(oldNodeId, direction, oldPort.id),
379
+ newHandleId: buildHandleId(newNodeId, direction, resolved.port.id),
380
+ oldPortId: oldPort.id,
381
+ newPortId: resolved.port.id,
382
+ direction
383
+ });
384
+ }
385
+ }
386
+ }
358
387
  // Config mapping — apply strategy then overrides
359
388
  const { carriedOver, reset } = mapConfig(oldNode.data.config, newMetadata.configSchema, newMetadata.config);
360
389
  // Apply strategy config overrides
@@ -406,7 +435,8 @@ export function computeSwapPreviewWithOptions(oldNode, newMetadata, edges, allNo
406
435
  hasDataLoss: droppedEdges.length > 0,
407
436
  newNodeId,
408
437
  configCarriedOver: carriedOver,
409
- configReset: reset
438
+ configReset: reset,
439
+ portMappings
410
440
  };
411
441
  }
412
442
  /**
@@ -537,13 +567,31 @@ export function buildSwapPreviewFromState(state, _allEdges) {
537
567
  configReset.push(cm.key);
538
568
  }
539
569
  }
570
+ // Port mappings for interface-binding rewrite. Unlike
571
+ // computeSwapPreviewWithOptions, this only covers ports the interactive
572
+ // editor surfaced — i.e. ports with a connected edge — since that is the
573
+ // full extent of what the user reviewed; an exposed-but-unconnected bound
574
+ // port isn't part of this state and its binding goes dangling on swap.
575
+ const portMappings = [];
576
+ for (const mapping of state.portMappings) {
577
+ if (!mapping.selectedNewPortId)
578
+ continue;
579
+ portMappings.push({
580
+ oldHandleId: buildHandleId(state.oldNode.id, mapping.direction, mapping.oldPort.id),
581
+ newHandleId: buildHandleId(state.newNodeId, mapping.direction, mapping.selectedNewPortId),
582
+ oldPortId: mapping.oldPort.id,
583
+ newPortId: mapping.selectedNewPortId,
584
+ direction: mapping.direction
585
+ });
586
+ }
540
587
  return {
541
588
  keptEdges,
542
589
  droppedEdges,
543
590
  hasDataLoss: droppedEdges.length > 0,
544
591
  newNodeId: state.newNodeId,
545
592
  configCarriedOver,
546
- configReset
593
+ configReset,
594
+ portMappings
547
595
  };
548
596
  }
549
597
  /**
@@ -54,7 +54,5 @@ export declare function getPortTop(index: number, count: number): number;
54
54
  * wireable, and not runtime-overridable. Effective exposure is the instance's
55
55
  * explicit `data.config.ports` override for the port, falling back to the port's
56
56
  * metadata `exposedByDefault` (which itself defaults to exposed).
57
- *
58
- * @see .claude/plans/exposed-ports.md
59
57
  */
60
58
  export declare function isPortVisible(port: NodePort, direction: 'input' | 'output', ports: PortsConfig | undefined): boolean;
@@ -86,8 +86,6 @@ export function getPortTop(index, count) {
86
86
  * wireable, and not runtime-overridable. Effective exposure is the instance's
87
87
  * explicit `data.config.ports` override for the port, falling back to the port's
88
88
  * metadata `exposedByDefault` (which itself defaults to exposed).
89
- *
90
- * @see .claude/plans/exposed-ports.md
91
89
  */
92
90
  export function isPortVisible(port, direction, ports) {
93
91
  const entries = direction === 'input' ? ports?.inputs : ports?.outputs;