@flowdrop/flowdrop 2.2.2 → 2.4.0

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.
@@ -64,17 +64,42 @@ function propertyToTemplateVariable(name, property, sourcePort, sourceNode) {
64
64
  }
65
65
  return variable;
66
66
  }
67
+ /**
68
+ * The schema in force for a port: its own if it has one, else its lane's.
69
+ *
70
+ * A port's own schema is the refinement — narrower, and specific to this port —
71
+ * so it wins. The lane's schema is what a port shape declares, served once on
72
+ * the lane entry for every port that declares the lane, which is how the
73
+ * `error` port comes to know it carries `{message, code, node_id, retryable}`.
74
+ *
75
+ * Resolved through the checker rather than a private lookup, for the reason
76
+ * `portShape()` is: a table of its own cannot follow an alias, so the same
77
+ * lane could come back styled and schemaless at once.
78
+ *
79
+ * @param port - The port to resolve a schema for
80
+ * @param checker - The instance's compatibility checker, when one is available
81
+ * @returns The schema in force, or undefined when neither declares one
82
+ */
83
+ function resolvePortSchema(port, checker) {
84
+ if (port.schema)
85
+ return port.schema;
86
+ if (!checker || !port.dataType)
87
+ return undefined;
88
+ return checker.getDataTypeConfig(port.dataType)?.schema;
89
+ }
67
90
  /**
68
91
  * Creates a TemplateVariable from a NodePort.
69
- * Uses the port's schema if available, otherwise creates a basic variable.
92
+ * Uses the schema in force for the port if there is one, otherwise creates a
93
+ * basic variable from the port's lane.
70
94
  *
71
95
  * @param port - The output port to convert
72
96
  * @param sourceNode - The source node ID
97
+ * @param schema - The schema in force, from {@link resolvePortSchema}
73
98
  * @returns A TemplateVariable representing the port's data
74
99
  */
75
- function portToTemplateVariable(port, sourceNode) {
76
- // If the port has a schema, use it to build a detailed variable
77
- if (port.schema && port.schema.properties) {
100
+ function portToTemplateVariable(port, sourceNode, schema) {
101
+ // If a schema is in force, use it to build a detailed variable
102
+ if (schema && schema.properties) {
78
103
  const variable = {
79
104
  name: port.id,
80
105
  label: port.name,
@@ -84,7 +109,7 @@ function portToTemplateVariable(port, sourceNode) {
84
109
  sourceNode,
85
110
  properties: {}
86
111
  };
87
- for (const [propName, propValue] of Object.entries(port.schema.properties)) {
112
+ for (const [propName, propValue] of Object.entries(schema.properties)) {
88
113
  variable.properties[propName] = propertyToTemplateVariable(propName, propValue, port.id, sourceNode);
89
114
  }
90
115
  return variable;
@@ -181,7 +206,7 @@ function findUpstreamConnections(node, nodes, edges) {
181
206
  */
182
207
  export function getAvailableVariables(node, nodes, edges, options) {
183
208
  const variables = {};
184
- const { targetPortIds, includePortName } = options ?? {};
209
+ const { targetPortIds, includePortName, portCompatibility } = options ?? {};
185
210
  // Find all upstream connections
186
211
  const connections = findUpstreamConnections(node, nodes, edges);
187
212
  for (const connection of connections) {
@@ -200,11 +225,14 @@ export function getAvailableVariables(node, nodes, edges, options) {
200
225
  }
201
226
  if (!sourcePort)
202
227
  continue;
203
- // If the source port has a schema with top-level properties,
204
- // unpack them as top-level variables (unless includePortName is true)
205
- if (sourcePort.schema?.properties && !includePortName) {
228
+ // The schema in force for this port: its own, else the one its lane
229
+ // declares. Resolved once, because both branches below read it.
230
+ const sourceSchema = resolvePortSchema(sourcePort, portCompatibility);
231
+ // If the schema has top-level properties, unpack them as top-level
232
+ // variables (unless includePortName is true)
233
+ if (sourceSchema?.properties && !includePortName) {
206
234
  // Unpack schema properties as top-level variables
207
- for (const [propName, propValue] of Object.entries(sourcePort.schema.properties)) {
235
+ for (const [propName, propValue] of Object.entries(sourceSchema.properties)) {
208
236
  // Skip if we already have a variable with this name
209
237
  if (variables[propName])
210
238
  continue;
@@ -217,7 +245,7 @@ export function getAvailableVariables(node, nodes, edges, options) {
217
245
  // Skip if we already have a variable with this name
218
246
  if (variables[variableName])
219
247
  continue;
220
- const variable = portToTemplateVariable(sourcePort, sourceNode.id);
248
+ const variable = portToTemplateVariable(sourcePort, sourceNode.id, sourceSchema);
221
249
  variable.name = variableName;
222
250
  variable.label = targetPort?.name ?? sourcePort.name;
223
251
  variables[variableName] = variable;
@@ -379,33 +407,42 @@ export function mergeVariableSchemas(primary, secondary) {
379
407
  * This is the main orchestration function that determines how to fetch variables
380
408
  * based on the configuration.
381
409
  *
410
+ * @param endpointConfig - API endpoint configuration, or null when there is none
382
411
  * @param node - The current node being configured
383
412
  * @param nodes - All nodes in the workflow
384
413
  * @param edges - All edges in the workflow
385
414
  * @param config - Template variables configuration
386
- * @param workflowId - Optional workflow ID for API context
387
- * @param authProvider - Optional auth provider for API requests
415
+ * @param context - Optional resolution context: workflow id, auth provider, and
416
+ * the port compatibility checker
388
417
  * @returns A promise that resolves to the variable schema
389
418
  *
390
419
  * @example
391
420
  * ```typescript
392
421
  * // Schema-based mode (existing behavior)
393
422
  * const config = { ports: ["data"], schema: {...} };
394
- * const schema = await getVariableSchema(node, nodes, edges, config);
423
+ * const schema = await getVariableSchema(null, node, nodes, edges, config);
395
424
  *
396
425
  * // API mode
397
426
  * const config = { api: { endpoint: { url: "/api/variables/{workflowId}/{nodeId}" } } };
398
- * const schema = await getVariableSchema(node, nodes, edges, config, workflowId, authProvider);
427
+ * const schema = await getVariableSchema(endpointConfig, node, nodes, edges, config, {
428
+ * workflowId,
429
+ * authProvider
430
+ * });
399
431
  *
400
- * // Hybrid mode (API + static schema)
432
+ * // Hybrid mode (API + static schema), drilling into each port's lane schema
401
433
  * const config = {
402
434
  * schema: {...},
403
435
  * api: { endpoint: {...}, mergeWithSchema: true }
404
436
  * };
405
- * const schema = await getVariableSchema(node, nodes, edges, config, workflowId, authProvider);
437
+ * const schema = await getVariableSchema(endpointConfig, node, nodes, edges, config, {
438
+ * workflowId,
439
+ * authProvider,
440
+ * portCompatibility: fd.portCompatibility
441
+ * });
406
442
  * ```
407
443
  */
408
- export async function getVariableSchema(endpointConfig, node, nodes, edges, config, workflowId, authProvider) {
444
+ export async function getVariableSchema(endpointConfig, node, nodes, edges, config, context) {
445
+ const { workflowId, authProvider, portCompatibility } = context ?? {};
409
446
  let resultSchema = { variables: {} };
410
447
  // Try API mode first (if configured)
411
448
  if (config.api) {
@@ -423,7 +460,8 @@ export async function getVariableSchema(endpointConfig, node, nodes, edges, conf
423
460
  if (config.api.mergeWithPorts) {
424
461
  const portSchema = getAvailableVariables(node, nodes, edges, {
425
462
  targetPortIds: config.ports,
426
- includePortName: config.includePortName
463
+ includePortName: config.includePortName,
464
+ portCompatibility
427
465
  });
428
466
  resultSchema = mergeVariableSchemas(resultSchema, portSchema);
429
467
  }
@@ -451,7 +489,8 @@ export async function getVariableSchema(endpointConfig, node, nodes, edges, conf
451
489
  if (config.ports !== undefined || !config.api) {
452
490
  const portSchema = getAvailableVariables(node, nodes, edges, {
453
491
  targetPortIds: config.ports,
454
- includePortName: config.includePortName
492
+ includePortName: config.includePortName,
493
+ portCompatibility
455
494
  });
456
495
  resultSchema = portSchema;
457
496
  }
@@ -571,6 +571,62 @@ p {
571
571
  color: var(--fd-error-hover);
572
572
  }
573
573
 
574
+ /* Small badge — the node/port scale. */
575
+ .flowdrop-badge--sm {
576
+ font-size: 10px;
577
+ padding: 2px 4px;
578
+ }
579
+
580
+ /* Outlined badge: readable, copyable, and not competing for attention. Used by
581
+ the port lane chip, where the row's one saturated mark is the shape symbol
582
+ beside it — so the two sit side by side and must agree on box metrics. */
583
+ .flowdrop-badge--outline {
584
+ box-sizing: border-box;
585
+ height: 17px;
586
+ padding: 0 4px;
587
+ border: 1px solid var(--fd-border);
588
+ border-radius: var(--fd-radius-sm);
589
+ background-color: transparent;
590
+ color: var(--fd-muted-foreground);
591
+ line-height: 1;
592
+ }
593
+
594
+ /* Port shape symbol: the glyph chip that says what SHAPE a port carries
595
+ (`S` text, `#` number, `[]` list, `{}` object, `?` unknown, `T` trigger,
596
+ `()` callable). See components/ports/PortShapeSymbol.svelte.
597
+
598
+ The component sets only `--fd-port-symbol-color`, the port's lane colour, so
599
+ everything else here — including the tint ratios — stays overridable by a
600
+ consumer stylesheet instead of being locked behind an inline declaration.
601
+ `--fd-port-skin-color` is the same per-instance override the handles honour.
602
+
603
+ 19x17 is one glyph of the 10px mono face plus its padding: wide enough that
604
+ the two-character glyphs (`[]`, `{}`, `()`) do not set a wider box than the
605
+ one-character ones, so the chips form an even column down a dense node. */
606
+ .flowdrop-port-symbol {
607
+ --_fd-symbol-color: var(--fd-port-skin-color, var(--fd-port-symbol-color, var(--fd-node-slate)));
608
+
609
+ display: inline-flex;
610
+ align-items: center;
611
+ justify-content: center;
612
+ flex: none;
613
+ box-sizing: border-box;
614
+ min-width: 19px;
615
+ height: 17px;
616
+ padding: 0 3px;
617
+ border: 1px solid color-mix(in srgb, var(--_fd-symbol-color) 30%, transparent);
618
+ border-radius: var(--fd-radius-sm);
619
+ background-color: color-mix(in srgb, var(--_fd-symbol-color) 15%, transparent);
620
+ color: var(--_fd-symbol-color);
621
+ font-family: var(--fd-font-mono);
622
+ font-size: 10px;
623
+ font-weight: 600;
624
+ line-height: 1;
625
+ letter-spacing: -0.02em;
626
+ white-space: nowrap;
627
+ user-select: none;
628
+ }
629
+
574
630
  /* Navbar styles */
575
631
  .flowdrop-navbar {
576
632
  display: flex;
@@ -970,37 +1026,6 @@ p {
970
1026
  opacity: 0.6;
971
1027
  }
972
1028
 
973
- /* Responsive utilities */
974
- @media (min-width: 640px) {
975
- .flowdrop-sm\\:flex {
976
- display: flex;
977
- }
978
-
979
- .flowdrop-sm\\:hidden {
980
- display: none;
981
- }
982
- }
983
-
984
- @media (min-width: 768px) {
985
- .flowdrop-md\\:flex {
986
- display: flex;
987
- }
988
-
989
- .flowdrop-md\\:hidden {
990
- display: none;
991
- }
992
- }
993
-
994
- @media (min-width: 1024px) {
995
- .flowdrop-lg\\:flex {
996
- display: flex;
997
- }
998
-
999
- .flowdrop-lg\\:hidden {
1000
- display: none;
1001
- }
1002
- }
1003
-
1004
1029
  /* Color system - Category colors */
1005
1030
  .flowdrop-color--primary {
1006
1031
  background-color: var(--fd-primary);
@@ -321,6 +321,7 @@
321
321
  --fd-node-lime: #84cc16; /* @public */
322
322
  --fd-node-slate: #64748b; /* @public */
323
323
  --fd-node-purple: #9333ea; /* @public */
324
+ --fd-node-fuchsia: #d946ef; /* @public */
324
325
 
325
326
  /** Icon on node squircle: dark in light theme, white in dark theme */
326
327
  --fd-node-icon: var(--_gray-9); /* @public */
@@ -466,6 +467,7 @@
466
467
  --fd-node-lime: #a3e635;
467
468
  --fd-node-slate: #94a3b8;
468
469
  --fd-node-purple: #c084fc;
470
+ --fd-node-fuchsia: #e879f9;
469
471
 
470
472
  /** Icon on node squircle: white in dark theme */
471
473
  --fd-node-icon: #ffffff;
@@ -75,6 +75,38 @@ export interface PortDataTypeConfig {
75
75
  aliases?: string[];
76
76
  /** Whether this data type is enabled */
77
77
  enabled?: boolean;
78
+ /**
79
+ * The JSON Schema this lane promises, when a port shape declares one.
80
+ *
81
+ * This is what lets template autocomplete offer `error.message` rather than
82
+ * only `error`: the lane says what fields travel on it, once, for every port
83
+ * that declares the lane. Absent — not empty — when the lane promises
84
+ * nothing beyond its name, so "no promise" stays distinguishable from
85
+ * "an object with no properties".
86
+ *
87
+ * Authoring information only. Nothing validates a value against it, and a
88
+ * port may still carry a NARROWER {@link NodePort.schema} of its own, which
89
+ * wins.
90
+ */
91
+ schema?: PortSchema;
92
+ }
93
+ /**
94
+ * A JSON Schema as served on a lane entry or a port.
95
+ *
96
+ * Deliberately looser than {@link OutputSchema}: a lane may promise something
97
+ * that is not an object at all (the `messages` lane is a top-level `array`),
98
+ * and a JSON Schema's keyword space is not ours to enumerate — the backend
99
+ * stores it untyped for exactly that reason. Readers take `properties` when
100
+ * there is one and fall back to the port itself when there is not.
101
+ */
102
+ export interface PortSchema {
103
+ type?: string;
104
+ title?: string;
105
+ description?: string;
106
+ required?: string[];
107
+ properties?: Record<string, BaseProperty>;
108
+ items?: BaseProperty;
109
+ [key: string]: unknown;
78
110
  }
79
111
  /**
80
112
  * Port compatibility rule configuration
@@ -136,6 +168,13 @@ export interface NodePort {
136
168
  /**
137
169
  * Optional JSON Schema describing the structure of data on this port.
138
170
  * Used for template variable autocomplete to drill into nested properties.
171
+ *
172
+ * This is the per-port REFINEMENT slot, and it wins over the schema the
173
+ * port's lane declares ({@link PortDataTypeConfig.schema}), which is where a
174
+ * shape's own field list travels. It is left for the narrower thing: a
175
+ * schema that applies to this port on this node in this workflow rather than
176
+ * to the lane in general — a lane promising `object` whose values turn out
177
+ * to carry `{title, description}`. Nothing populates it yet.
139
178
  */
140
179
  schema?: OutputSchema | InputSchema;
141
180
  }
@@ -12,6 +12,22 @@ import type { CategoriesStore } from '../stores/categoriesStore.svelte.js';
12
12
  * These serve as static defaults; the categories store provides dynamic overrides.
13
13
  */
14
14
  export declare const CATEGORY_COLOR_TOKENS: Record<string, string>;
15
+ /**
16
+ * Legacy data-type spellings that were never lane ids: alternative words older
17
+ * workflows and third-party payloads use. Kept as an alias layer so they still
18
+ * colour, but they are NOT part of the shipped vocabulary — that comes from
19
+ * DEFAULT_PORT_CONFIG below.
20
+ *
21
+ * **This list is closed.** It is the last hand-maintained colour list in the
22
+ * library and it has no upstream source to drift from, which is exactly why
23
+ * nothing new goes in it: a new lane belongs in the port config, and a new
24
+ * spelling of an existing lane belongs in that lane's `aliases`.
25
+ *
26
+ * Exported for the test suite only (not re-exported from any entry point): it
27
+ * is what `portShape.test.ts` asserts the lane→shape table is total over, so a
28
+ * spelling can never have a colour and no shape.
29
+ */
30
+ export declare const LEGACY_DATA_TYPE_COLORS: Record<string, string>;
15
31
  /**
16
32
  * Get the design token for a category color.
17
33
  * Checks the categories store first (which includes API overrides),
@@ -248,14 +264,14 @@ export declare function getPortBorderColor(checker: PortCompatibilityChecker, da
248
264
  * read as an error affordance (red) wherever it surfaces.
249
265
  */
250
266
  export declare function isErrorPort(port: {
251
- id: string;
267
+ id?: string;
252
268
  type?: string;
253
269
  }): boolean;
254
270
  /**
255
271
  * Port colour token: red for the reserved error output, else its data type.
256
272
  */
257
273
  export declare function getPortColorToken(checker: PortCompatibilityChecker, port: {
258
- id: string;
274
+ id?: string;
259
275
  type?: string;
260
276
  dataType: string;
261
277
  }): string;
@@ -263,7 +279,7 @@ export declare function getPortColorToken(checker: PortCompatibilityChecker, por
263
279
  * Port background tint, honouring the reserved error port's red affordance.
264
280
  */
265
281
  export declare function getPortBackgroundColorForPort(checker: PortCompatibilityChecker, port: {
266
- id: string;
282
+ id?: string;
267
283
  type?: string;
268
284
  dataType: string;
269
285
  }, opacity?: number): string;
@@ -3,6 +3,7 @@
3
3
  * Ensures consistent category colors across sidebar and canvas
4
4
  * Uses BEM syntax for CSS classes
5
5
  */
6
+ import { DEFAULT_PORT_CONFIG } from '../config/defaultPortConfig.js';
6
7
  /**
7
8
  * Category color mapping to design tokens (CSS variables)
8
9
  * Uses --fd-node-* tokens from tokens.css
@@ -28,38 +29,47 @@ export const CATEGORY_COLOR_TOKENS = {
28
29
  bundles: 'var(--fd-node-slate)'
29
30
  };
30
31
  /**
31
- * Default data type colors for fallback when port configuration is not available
32
- * Uses --fd-node-* tokens from tokens.css
32
+ * Legacy data-type spellings that were never lane ids: alternative words older
33
+ * workflows and third-party payloads use. Kept as an alias layer so they still
34
+ * colour, but they are NOT part of the shipped vocabulary — that comes from
35
+ * DEFAULT_PORT_CONFIG below.
36
+ *
37
+ * **This list is closed.** It is the last hand-maintained colour list in the
38
+ * library and it has no upstream source to drift from, which is exactly why
39
+ * nothing new goes in it: a new lane belongs in the port config, and a new
40
+ * spelling of an existing lane belongs in that lane's `aliases`.
41
+ *
42
+ * Exported for the test suite only (not re-exported from any entry point): it
43
+ * is what `portShape.test.ts` asserts the lane→shape table is total over, so a
44
+ * spelling can never have a colour and no shape.
33
45
  */
34
- const DEFAULT_DATA_TYPE_COLORS = {
35
- string: 'var(--fd-node-emerald)',
46
+ export const LEGACY_DATA_TYPE_COLORS = {
36
47
  text: 'var(--fd-node-emerald)',
37
- number: 'var(--fd-node-blue)',
38
48
  integer: 'var(--fd-node-blue)',
39
49
  float: 'var(--fd-node-blue)',
40
- boolean: 'var(--fd-node-purple)',
41
- array: 'var(--fd-node-amber)',
42
50
  list: 'var(--fd-node-amber)',
43
51
  object: 'var(--fd-node-orange)',
44
- json: 'var(--fd-node-orange)',
45
- mixed: 'var(--fd-node-orange)',
46
- file: 'var(--fd-node-red)',
47
52
  document: 'var(--fd-node-red)',
48
- image: 'var(--fd-node-pink)',
49
53
  picture: 'var(--fd-node-pink)',
50
- audio: 'var(--fd-node-indigo)',
51
54
  sound: 'var(--fd-node-indigo)',
52
- video: 'var(--fd-node-teal)',
53
55
  movie: 'var(--fd-node-teal)',
54
- url: 'var(--fd-node-cyan)',
55
- email: 'var(--fd-node-cyan)',
56
- date: 'var(--fd-node-lime)',
57
- datetime: 'var(--fd-node-lime)',
58
- time: 'var(--fd-node-lime)',
59
- tool: 'var(--fd-node-amber)',
60
- trigger: 'var(--fd-edge-trigger)',
61
56
  branch: 'var(--fd-node-purple)'
62
57
  };
58
+ /**
59
+ * Fallback lane colours for when no port configuration has loaded yet — which
60
+ * is exactly when the first render happens, so these are seen.
61
+ *
62
+ * Derived from DEFAULT_PORT_CONFIG rather than hand-written. It used to be a
63
+ * third, independently maintained colour list, and it had drifted: `mixed` was
64
+ * orange against the payload's teal, and the typed-array lanes (`string[]`,
65
+ * `json[]`, …) and `messages` were missing entirely, so a first render painted
66
+ * them slate. Deriving makes that class of drift unrepresentable — a lane added
67
+ * to the shipped config is coloured here by construction.
68
+ */
69
+ const DEFAULT_DATA_TYPE_COLORS = {
70
+ ...LEGACY_DATA_TYPE_COLORS,
71
+ ...Object.fromEntries(DEFAULT_PORT_CONFIG.dataTypes.map((dataType) => [dataType.id.toLowerCase(), dataType.color]))
72
+ };
63
73
  /**
64
74
  * Get the design token for a category color.
65
75
  * Checks the categories store first (which includes API overrides),
@@ -1,6 +1,7 @@
1
1
  /**
2
2
  * Configuration utilities for FlowDrop Editor
3
3
  */
4
+ import { DEFAULT_PORT_CONFIG } from '../config/defaultPortConfig.js';
4
5
  import { createEndpointConfig } from '../config/endpoints.js';
5
6
  /**
6
7
  * Create default editor features configuration
@@ -108,11 +109,13 @@ export function createDefaultConfig(endpointConfig) {
108
109
  ...createDefaultAPIConfig(),
109
110
  endpoints: endpointConfig || createEndpointConfig('/api/flowdrop')
110
111
  },
111
- ports: {
112
- dataTypes: [],
113
- compatibilityRules: [],
114
- defaultDataType: 'mixed'
115
- },
112
+ // Not `{dataTypes: [], compatibilityRules: [], defaultDataType: 'mixed'}`:
113
+ // an empty type list is not a permissive default, it is a config in which
114
+ // NOTHING is compatible with anything — buildCompatibilityMap() seeds
115
+ // itself from `dataTypes`, so a `mixed` default naming a lane the list
116
+ // never declares leaves every port refusing every edge. The shipped
117
+ // defaults are the default.
118
+ ports: DEFAULT_PORT_CONFIG,
116
119
  execution: createDefaultExecutionConfig(),
117
120
  storage: createDefaultStorageConfig()
118
121
  };
@@ -0,0 +1,113 @@
1
+ /**
2
+ * Port shape symbols — what shape a port carries, said separately from which
3
+ * lane it belongs to.
4
+ *
5
+ * A port row shows two independent facts: its JSON-Schema **shape** (is this a
6
+ * string, a list, an object?) and its semantic **lane** (`messages`, `url`,
7
+ * `tool`). Colour used to carry both, so it carried neither well. The shape
8
+ * moves to a small glyph; the lane keeps its id in a quiet outlined chip and
9
+ * keeps the colour.
10
+ *
11
+ * ## Where the shape comes from
12
+ *
13
+ * Two sources, in this order:
14
+ *
15
+ * 1. **The lane's served schema** (`PortDataTypeConfig.schema`) — a JSON Schema
16
+ * the backend's shape registry declares for the lane. Its `type` IS the
17
+ * shape, said by the side that knows: fddo's `error` shape declares
18
+ * `type: object`, `messages` declares `type: array`, and a site's own
19
+ * `Order` shape answers for itself without the client having heard of it.
20
+ * 2. **The lane table below**, when no schema is served — which is every lane
21
+ * on an older fddo, on a third-party server implementing only the
22
+ * port-config endpoint, and on the library's offline defaults (which stay
23
+ * presentation-only on purpose and carry no schemas).
24
+ *
25
+ * The table was the whole answer before shapes reached the wire, and the
26
+ * ordering above is why the fallback stays: it is what draws a glyph when
27
+ * nothing declares one, not a second opinion competing with a served answer.
28
+ *
29
+ * Two things the fallback cannot do, both known and accepted:
30
+ * - **`integer` vs `number` collapse.** The server already maps both onto lane
31
+ * `number`, so nothing is lost that the client ever had. A served schema
32
+ * saying `integer` collapses the same way, for the same reason.
33
+ * - **A site-defined lane with no shape resolves to `unknown` (`?`).** A lane
34
+ * added through the `port_config` overlay alone has nothing to read. `?` is
35
+ * the honest answer, and declaring a shape for the lane is how a site
36
+ * improves it.
37
+ *
38
+ * {@link portShape} is the one function either source is read in, which is what
39
+ * kept adding the first source to a single place.
40
+ *
41
+ * It takes the **checker** for exactly that reason. Colour has always asked the
42
+ * checker, which resolves an alias to its canonical lane and sees whatever the
43
+ * backend served; a private lookup table cannot do either, so the same port got
44
+ * a lane colour and a shapeless `?` at the same time. Routing shape through the
45
+ * same source makes that class of disagreement unrepresentable, and means a
46
+ * served shape lands here without touching a call site.
47
+ */
48
+ import type { PortCompatibilityChecker } from './connections.js';
49
+ /**
50
+ * The closed shape vocabulary. One glyph each, and every lane resolves to
51
+ * exactly one of these.
52
+ *
53
+ * `trigger` and `callable` are not JSON-Schema shapes — they are the two
54
+ * control lanes, whose payload is a signal and a callable respectively. They
55
+ * get their own marks because rendering either as `?` would hide the one thing
56
+ * a reader needs to know about them.
57
+ */
58
+ export type PortShape = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'unknown' | 'trigger' | 'callable';
59
+ /**
60
+ * The glyph shown for each shape. Deliberately tiny and ASCII: `{}` and `[]`
61
+ * are the notation a developer already reads as object and array, and the
62
+ * bracket idiom extends to `()` for a callable.
63
+ *
64
+ * `number` is `#` and not `I`, because the lane it renders covers floats —
65
+ * `I` would be a lie on `Temperature: 0.7`. If a future release splits
66
+ * `integer` out, `I` joins the set and `#` keeps meaning "number".
67
+ */
68
+ export declare const SHAPE_GLYPH: Record<PortShape, string>;
69
+ /**
70
+ * A human-readable name per shape, for the symbol's tooltip. The glyph is a
71
+ * compression for the eye; this is what it decompresses to.
72
+ */
73
+ export declare const SHAPE_LABEL: Record<PortShape, string>;
74
+ /**
75
+ * Read-only view of the lane table. Not part of the package's public exports —
76
+ * it exists so the test suite can assert the table is total over the shipped
77
+ * port config, which is what stops a new lane shipping without a glyph.
78
+ */
79
+ export declare const LANE_SHAPES: Readonly<Record<string, PortShape>>;
80
+ /** The port fields shape derivation reads. */
81
+ interface ShapedPort {
82
+ dataType?: string;
83
+ }
84
+ /**
85
+ * The shape a lane id implies, straight from the table. `unknown` for any lane
86
+ * not in it, including every site-defined one.
87
+ *
88
+ * Case-insensitive, because `getDataTypeColorToken` is: a backend that spells
89
+ * its lane `String` gets a colour, and must not then get a shapeless `?`.
90
+ *
91
+ * This is the offline half. Prefer {@link portShape}, which consults the served
92
+ * vocabulary first.
93
+ */
94
+ export declare function laneShape(dataType: string | undefined): PortShape;
95
+ /**
96
+ * The shape to draw for a port — both sources, in the order the top of this
97
+ * file states: the lane's served schema, then the table.
98
+ *
99
+ * The lane is resolved through the checker either way, so an alias (`text`
100
+ * declared as an alias of `string`) reads the schema and the table of the lane
101
+ * it aliases rather than answering as an unknown of its own.
102
+ */
103
+ export declare function portShape(checker: PortCompatibilityChecker, port: ShapedPort): PortShape;
104
+ /**
105
+ * The glyph to draw for a port.
106
+ *
107
+ * @deprecated since 2.4.0 — `SHAPE_GLYPH[portShape(checker, port)]`, which is
108
+ * what this is. Both it and the map went out in 2.3.0's public surface and only
109
+ * one of them needs to be there: the map is the vocabulary, and composing it is
110
+ * a lookup. Kept until 3.0.0 because removing a released export is not a minor.
111
+ */
112
+ export declare function portGlyph(checker: PortCompatibilityChecker, port: ShapedPort): string;
113
+ export {};