@uipath/maestro-builder-sdk 6.31.8 → 6.32.0

package/dist/check.js

@@ -10,7 +10,7 @@ import { FlowNode } from './core/node-classes.js';
 import { planContributionBindings } from './core/contribution-bindings.js';
 import { definitionHasErrorPort, errorPortRefusal } from './core/error-port.js';
 import { actionVersion, bundledActionNodeType, bundledContainerDefinition, bundledDefinition, perCallDefinition, resolveContributionDefinition } from './serialize.js';
-import { FORM_FIELD_TYPES, formFieldTypeHint, formFieldTypeWhy, validFormFieldTypesText } from './core/form-field-type.js';
+import { FORM_FIELD_TYPES, formFieldOptionsProblem, formFieldOptionsWhy, formFieldTypeHint, formFieldTypeWhy, validFormFieldTypesText } from './core/form-field-type.js';
 import { AGENTIC_PROCESS_FORMS } from './core/agentic-process-forms.js';
 import { checkEventResolution, checkEventSubscription, eventParamsFor, } from './core/event-checks.js';
 import { checkCookedEscapes } from './flow-expr-check.js';
@@ -3418,6 +3418,16 @@ function checkInlineAgent(step, inputs, diags, opts = {}) {
                         + `${JSON.stringify(f?.type)}, ${formFieldTypeWhy(f?.type, `which the form does not recognize — it would `
                             + `be published as a plain string`)}. Valid: ${validFormFieldTypesText()}.`, formFieldTypeHint(f?.type));
                 }
+                const optionsProblem = formFieldOptionsProblem(f?.type, f?.options);
+                if (optionsProblem !== undefined) {
+                    const message = `Inline agent step "${step}"'s quick-form escalation field "${String(f?.id ?? '?')}" `
+                        + `${formFieldOptionsWhy(optionsProblem, f?.type)}.`;
+                    if (optionsProblem === 'ignored')
+                        warn('INLINE_AGENT_ESCALATION_FIELD_OPTIONS_IGNORED', message);
+                    else {
+                        at('INLINE_AGENT_ESCALATION_FIELD_OPTIONS', message, `options: [{ id: 'opt-1', value: 'high', label: 'High' }, { id: 'opt-2', value: 'low', label: 'Low' }]`);
+                    }
+                }
             }
             continue;
         }
@@ -4548,17 +4558,36 @@ function checkStepRefs(built, diags) {
     const scopeOf = new Map();
     /** Step name → the parallel arm it lives in, as `<parallel>#<index>`. */
     const armOf = new Map();
+    /**
+     * How many nodes answer to each NAMED End's name (`.return({}, { name })`), and
+     * how many of those are steps. A named End is a ref target too (#1223): a side
+     * path that runs into the main path's End is one End with two incoming edges,
+     * which the product accepts and the canvas draws. Counted so a ref to a name
+     * two nodes share is refused rather than wired to whichever came first.
+     */
+    const endNames = new Map();
+    const stepNamesSeen = new Set();
     let seq = 0;
     const index = (steps, portList, scope, arm) => {
         for (const s of steps) {
-            if ('name' in s && s.kind !== 'return') {
-                if (!order.has(s.name))
-                    order.set(s.name, seq);
-                if (portList)
-                    inPortList.add(s.name);
-                scopeOf.set(s.name, scope);
-                if (arm)
-                    armOf.set(s.name, arm);
+            // A `return`'s own `name` is synthetic; its End is named by `options.name`.
+            const name = s.kind === 'return' ? s.options?.name : 'name' in s ? s.name : undefined;
+            if (name !== undefined) {
+                if (s.kind === 'return')
+                    endNames.set(name, (endNames.get(name) ?? 0) + 1);
+                else
+                    stepNamesSeen.add(name);
+                // Exactly the step rule from before, for steps. A named End only fills a
+                // name nothing has claimed; a clash is REF_AMBIGUOUS_TARGET below.
+                if (s.kind !== 'return' || !order.has(name)) {
+                    if (!order.has(name))
+                        order.set(name, seq);
+                    if (portList)
+                        inPortList.add(name);
+                    scopeOf.set(name, scope);
+                    if (arm)
+                        armOf.set(name, arm);
+                }
             }
             seq++;
             if (s.kind === 'stepToList')
@@ -4620,7 +4649,15 @@ function checkStepRefs(built, diags) {
         if (!order.has(target)) {
             const near = [...order.keys()].find((n) => n.toLowerCase() === target.toLowerCase());
             say('error', 'REF_UNKNOWN_TARGET', `.stepToRef('${target}') ${where} names a step this flow does not have`
-                + `${near ? ` (did you mean "${near}"?)` : ''}. It takes the same name you passed to .step().`, near ? `.stepToRef('${near}')` : undefined);
+                + `${near ? ` (did you mean "${near}"?)` : ''}. It takes the same name you passed to .step(), or the `
+                + `\`name\` of a \`.return({}, { name })\` End.`, near ? `.stepToRef('${near}')` : undefined);
+            continue;
+        }
+        const ends = endNames.get(target) ?? 0;
+        if (ends > 0 && ends + (stepNamesSeen.has(target) ? 1 : 0) > 1) {
+            say('error', 'REF_AMBIGUOUS_TARGET', `.stepToRef('${target}') ${where} names ${stepNamesSeen.has(target) ? 'both a step and an End' : `${ends} Ends`} `
+                + `called "${target}", so it is not clear which one the path should go to. Give each \`.return({}, { name })\` `
+                + `a name no other step or End uses.`);
             continue;
         }
         // A ref to a container the path is INSIDE names it as a step, so the edge

package/dist/core/actions.d.ts

@@ -62,15 +62,46 @@ export interface ConnectorOpts {
  */
 export type CanonicalFormFieldType = 'string' | 'number' | 'integer' | 'float' | 'double' | 'boolean' | 'date' | 'datetime' | 'file' | 'object' | 'array';
 /**
- * A form field's type: one of the platform's canonical types, or `'text'` /
+ * The platform's choice-control spellings of a field type. Each names the data
+ * the field holds AND how it renders (`@uipath/hitl-schema-types`
+ * `resolveFieldType` + `controlForDeclaredType`): `singleSelect` is a `string`
+ * shown as a dropdown, `multiSelect` an `array` shown as a multi-select, and
+ * `enum` (what the designer's variable picker writes for a closed set) a
+ * `string` shown as a dropdown. The choices are the field's `options`.
+ */
+export type ControlFormFieldType = 'singleSelect' | 'multiSelect' | 'enum';
+/**
+ * A form field's type: one of the platform's canonical types; `'text'` /
  * `'date-time'`, the SDK's older spellings of `'string'` / `'datetime'` (the
- * platform resolves both). A quick form with any other type fails the
- * platform's validation, which is why `check` rejects it.
+ * platform resolves both); or a choice-control spelling (`'singleSelect'`,
+ * `'multiSelect'`, `'enum'`), which the form renders as a picker over the
+ * field's `options`. A quick form with any other type fails the platform's
+ * validation, which is why `check` rejects it.
  *
  * @example
  * hitl({ fields: [{ id: 'dueOn', type: 'date', direction: 'output' }], outcomes: ['Done'] })
+ * hitl({
+ *   fields: [{
+ *     id: 'priority', type: 'singleSelect', direction: 'output',
+ *     options: [{ id: 'opt-1', value: 'high', label: 'High' }, { id: 'opt-2', value: 'low', label: 'Low' }],
+ *   }],
+ *   outcomes: ['Done'],
+ * })
+ */
+export type FormFieldType = CanonicalFormFieldType | 'text' | 'date-time' | ControlFormFieldType;
+/**
+ * One choice of a picker field (`@uipath/hitl-schema-types` `optionShape`):
+ * `value` is what the answer holds, `label` what the reviewer sees, and `id`
+ * the option's own stable id. All three are required by the platform.
  */
-export type FormFieldType = CanonicalFormFieldType | 'text' | 'date-time';
+export interface FormFieldOption {
+    /** The option's own stable id, e.g. `'opt-1'`. */
+    id: string;
+    /** What the answer holds when the reviewer picks it, e.g. `'high'`. */
+    value: string;
+    /** What the reviewer sees, e.g. `'High'`. */
+    label: string;
+}
 /** A value the reviewer READS: shown on the form, filled in from the flow. */
 export interface ShownField {
     /** Field id — the key the answer object uses. Must be unique on the form. */
@@ -79,6 +110,11 @@ export interface ShownField {
     label?: string;
     type: FormFieldType;
     direction: 'input';
+    /**
+     * The choices of a picker field — a `singleSelect` / `enum` dropdown or a
+     * `multiSelect`. Written to the form verbatim, in order.
+     */
+    options?: FormFieldOption[];
     /**
      * What to show — a reference, e.g. `input('amount')` or
      * `out('fetchInvoice', 'body.total')`. Required: a shown field with nothing
@@ -95,6 +131,11 @@ export interface AskedField {
     label?: string;
     type: FormFieldType;
     direction: 'output';
+    /**
+     * The choices of a picker field — a `singleSelect` / `enum` dropdown or a
+     * `multiSelect`. Written to the form verbatim, in order.
+     */
+    options?: FormFieldOption[];
     /** Reviewer must fill it in before the task can be completed. */
     required?: boolean;
 }
@@ -111,6 +152,11 @@ export interface InOutField {
     label?: string;
     type: FormFieldType;
     direction: 'inOut';
+    /**
+     * The choices of a picker field — a `singleSelect` / `enum` dropdown or a
+     * `multiSelect`. Written to the form verbatim, in order.
+     */
+    options?: FormFieldOption[];
     /** What to pre-fill — a reference, e.g. `out('fetchInvoice', 'body.total')`. */
     value: Expr;
     /** Reviewer must confirm/fill it before the task can be completed. */

package/dist/core/form-field-type.d.ts

@@ -14,35 +14,59 @@
  * on it at runtime. This module is a transcription, and
  * `tests/hitl-field-type-contract.test.ts` runs the real package against it:
  * the canonical set, each type's JSON Schema, and every alias below must agree
- * with the pinned `@uipath/hitl-schema-types`. A canonical-set or JSON Schema
- * change upstream fails there; a new alias does not. The test also pins how the
- * package resolves the spellings this module leaves out, so a change in those
- * shows up.
+ * with the pinned `@uipath/hitl-schema-types`. A canonical-set, JSON Schema or
+ * control-spelling change upstream fails there; a new data alias does not.
+ *
+ * Besides data types, the product accepts three CHOICE-CONTROL spellings —
+ * `singleSelect`, `multiSelect`, `enum` — which name both the data the field
+ * holds and the control it renders with (#1235). The SDK accepts them in
+ * source and writes them as written, so a canvas dropdown stays a dropdown.
  *
  * Every SDK path reads field types from here: `check` (human tasks and inline
  * agent quick-form escalations), decompile, and the serializers' output
  * schemas.
  */
-import type { CanonicalFormFieldType } from './actions.js';
+import type { CanonicalFormFieldType, ControlFormFieldType, FormFieldOption } from './actions.js';
 /** The product's 11 canonical quick-form field types, in its own order. */
 export declare const CANONICAL_FORM_FIELD_TYPES: CanonicalFormFieldType[];
 /** The SDK's legacy spellings (`text`, `date-time`), for diagnostics that list them. */
 export declare const LEGACY_FORM_FIELD_TYPES: string[];
-/** Every form-field type the SDK accepts in source: the 11 canonical ones and the SDK's legacy aliases. */
+/** The choice-control spellings, for `check`'s messages and the contract test. */
+export declare const CONTROL_FORM_FIELD_TYPES: ControlFormFieldType[];
+/**
+ * Every form-field type the SDK accepts in source: the 11 canonical ones, the
+ * SDK's legacy aliases, and the three choice-control spellings.
+ */
 export declare const FORM_FIELD_TYPES: string[];
 /**
  * The tail of a "Valid: …" diagnostic: the canonical types, then the legacy
- * spellings in parentheses.
+ * spellings and the choice controls in parentheses.
  *
  * @example
- * validFormFieldTypesText() // 'string, number, …, array (or the older text, date-time)'
+ * validFormFieldTypesText() // 'string, …, array (or the older text, date-time; or a choice control: singleSelect, …)'
  */
 export declare function validFormFieldTypesText(): string;
+/**
+ * The data type and control a choice-control spelling names, or `undefined`
+ * for any other type.
+ *
+ * @example
+ * controlFormFieldType('singleSelect') // { data: 'string', control: 'dropdown' }
+ * controlFormFieldType('multiSelect')  // { data: 'array', control: 'multiSelect' }
+ * controlFormFieldType('string')       // undefined
+ */
+export declare function controlFormFieldType(type: unknown): {
+    data: CanonicalFormFieldType;
+    control: string;
+} | undefined;
 /** The product aliases, for the contract test. */
 export declare const FORM_FIELD_TYPE_ALIASES: Readonly<Record<string, CanonicalFormFieldType>>;
 /**
  * The canonical type a wire or source spelling names, or `undefined` when it
- * names none the SDK models.
+ * names none the SDK models. A choice-control spelling is its own wire
+ * spelling, so it is `undefined` here too — its data type is
+ * `controlFormFieldType(t).data`; resolving it here would let a caller write
+ * `string` for a dropdown.
  *
  * @example
  * canonicalFormFieldType('integer')      // 'integer'
@@ -71,11 +95,9 @@ export declare function canonicalFormFieldType(type: unknown): CanonicalFormFiel
 export declare function sourceFormFieldType(wire: unknown): string;
 /**
  * Why a form-field type is refused: a product alias the SDK does not accept in
- * source (`"System.Int32"` is the platform's .NET name for `integer`), a control
- * spelling the platform accepts but the SDK does not model yet
- * (`"singleSelect"`), or a type the product does not recognize at all.
- * `unknownWhy` is the caller's reason for the last case; the default is a human
- * task's.
+ * source (`"System.Int32"` is the platform's .NET name for `integer`), or a type
+ * the product does not recognize at all. `unknownWhy` is the caller's reason for
+ * the second case; the default is a human task's.
  */
 export declare function formFieldTypeWhy(type: unknown, unknownWhy?: string): string;
 /** The `suggestion` for an unknown form-field type: its canonical type, the nearest valid one, else `type: 'string'`. */
@@ -87,8 +109,52 @@ export declare function formFieldTypeHint(type: unknown): string;
  * @example
  * formFieldJsonSchema('date') // { type: 'string', format: 'date' }
  * formFieldJsonSchema('text') // { type: 'string' }
+ * formFieldJsonSchema('multiSelect') // { type: 'array' }
  */
 export declare function formFieldJsonSchema(type: unknown): {
     type: string;
     format?: string;
 } | undefined;
+/**
+ * A picker field's choices as the form row carries them (`options`, each
+ * `{ id, value, label }` — the product's `optionShape`), copied so the wire
+ * never aliases the author's array. `undefined` when the field has none.
+ * Both serializers (human task, quick-form escalation) write through this.
+ */
+export declare function formFieldOptionsWire(options: readonly FormFieldOption[] | undefined): FormFieldOption[] | undefined;
+/**
+ * A form row's `options` read back for source: the well-formed choices
+ * (string `id`, `value`, `label` — all three the product requires), or
+ * `undefined` when the row has no `options` array. A malformed entry is left
+ * out, not coerced: `{ id: 'o1', value: 1 }` is not rewritten to
+ * `value: '1', label: ''`. Decompile (human task and quick-form escalation)
+ * reads through this, so a canvas dropdown's choices survive an edit.
+ *
+ * @example
+ * liftFormFieldOptions([{ id: 'o1', value: 'a', label: 'A' }, { id: 'o2', value: 2 }])
+ * // [{ id: 'o1', value: 'a', label: 'A' }]
+ */
+export declare function liftFormFieldOptions(raw: unknown): FormFieldOption[] | undefined;
+/**
+ * What is wrong with a form field's `options`, or `undefined` when nothing is.
+ * `check` reports each (human task and quick-form escalation):
+ *
+ * - `'malformed'`: `options` is there but is not an array of `{ id, value,
+ *   label }` strings. Serialize would throw or write rows the platform refuses.
+ * - `'missing'`: a choice-control type (`singleSelect`, `multiSelect`, `enum`)
+ *   with no choices. The form publishes an empty picker.
+ * - `'ignored'`: choices on a type that is not a choice control. The form
+ *   renders a plain input and never shows them.
+ *
+ * @example
+ * formFieldOptionsProblem('singleSelect', undefined)                         // 'missing'
+ * formFieldOptionsProblem('singleSelect', {})                                // 'malformed'
+ * formFieldOptionsProblem('string', [{ id: 'o1', value: 'a', label: 'A' }]) // 'ignored'
+ * formFieldOptionsProblem('enum', [{ id: 'o1', value: 'a', label: 'A' }])   // undefined
+ */
+export declare function formFieldOptionsProblem(type: unknown, options: unknown): 'malformed' | 'missing' | 'ignored' | undefined;
+/**
+ * The reason text for a `formFieldOptionsProblem`, worded for a diagnostic
+ * that starts "… the field "<id>" …".
+ */
+export declare function formFieldOptionsWhy(problem: 'malformed' | 'missing' | 'ignored', type: unknown): string;

package/dist/core/form-field-type.js

@@ -32,17 +32,53 @@ const SDK_ALIASES = {
 };
 /** The SDK's legacy spellings (`text`, `date-time`), for diagnostics that list them. */
 export const LEGACY_FORM_FIELD_TYPES = Object.keys(SDK_ALIASES);
-/** Every form-field type the SDK accepts in source: the 11 canonical ones and the SDK's legacy aliases. */
-export const FORM_FIELD_TYPES = [...CANONICAL_FORM_FIELD_TYPES, ...LEGACY_FORM_FIELD_TYPES];
+/**
+ * The product's choice-control spellings (#1235): the data type each holds
+ * (`resolveFieldType`) and the control the form renders it with
+ * (`controlForDeclaredType`, which sets the field's `controlType` when the row
+ * has none). The output schema is the data type's; the choices ride on the
+ * field's `options`, never in the schema.
+ *
+ * Kept as written on the wire — NOT resolved to the data type, which would
+ * drop the control: a `singleSelect` written as `string` renders as a text box.
+ */
+const CONTROL_TYPES = {
+    singleSelect: { data: 'string', control: 'dropdown' },
+    multiSelect: { data: 'array', control: 'multiSelect' },
+    enum: { data: 'string', control: 'dropdown' },
+};
+/** The choice-control spellings, for `check`'s messages and the contract test. */
+export const CONTROL_FORM_FIELD_TYPES = Object.keys(CONTROL_TYPES);
+/**
+ * Every form-field type the SDK accepts in source: the 11 canonical ones, the
+ * SDK's legacy aliases, and the three choice-control spellings.
+ */
+export const FORM_FIELD_TYPES = [
+    ...CANONICAL_FORM_FIELD_TYPES, ...LEGACY_FORM_FIELD_TYPES, ...CONTROL_FORM_FIELD_TYPES,
+];
 /**
  * The tail of a "Valid: …" diagnostic: the canonical types, then the legacy
- * spellings in parentheses.
+ * spellings and the choice controls in parentheses.
  *
  * @example
- * validFormFieldTypesText() // 'string, number, …, array (or the older text, date-time)'
+ * validFormFieldTypesText() // 'string, …, array (or the older text, date-time; or a choice control: singleSelect, …)'
  */
 export function validFormFieldTypesText() {
-    return `${CANONICAL_FORM_FIELD_TYPES.join(', ')} (or the older ${LEGACY_FORM_FIELD_TYPES.join(', ')})`;
+    return `${CANONICAL_FORM_FIELD_TYPES.join(', ')} (or the older ${LEGACY_FORM_FIELD_TYPES.join(', ')}; `
+        + `or a choice control: ${CONTROL_FORM_FIELD_TYPES.join(', ')})`;
+}
+/**
+ * The data type and control a choice-control spelling names, or `undefined`
+ * for any other type.
+ *
+ * @example
+ * controlFormFieldType('singleSelect') // { data: 'string', control: 'dropdown' }
+ * controlFormFieldType('multiSelect')  // { data: 'array', control: 'multiSelect' }
+ * controlFormFieldType('string')       // undefined
+ */
+export function controlFormFieldType(type) {
+    const entry = typeof type === 'string' ? ownEntry(CONTROL_TYPES, type) : undefined;
+    return entry === undefined ? undefined : { ...entry };
 }
 /**
  * The product's other data-type spellings, each with the canonical type it
@@ -53,10 +89,9 @@ export function validFormFieldTypesText() {
  * resolve to `string`. `T[]` and `a | b` are matched by pattern in
  * `canonicalFormFieldType`.
  *
- * Deliberately left out: the CONTROL spellings `singleSelect`, `multiSelect`
- * and `enum` (`CONTROL_FORM_FIELD_TYPES`). The product infers a `controlType`
- * from those, so rewriting one to its data type would change how the form
- * renders. Decompile keeps them as written, and `check` reports them.
+ * Deliberately left out: the choice-control spellings (`singleSelect`,
+ * `multiSelect`, `enum` — `CONTROL_TYPES` above, kept as written because the
+ * product infers a `controlType` from them).
  */
 const PRODUCT_ALIASES = {
     ...SDK_ALIASES,
@@ -104,18 +139,15 @@ const PRODUCT_ALIASES = {
     ref: 'string',
     any: 'string',
 };
-/**
- * The product's control spellings: it accepts them as a field `type` and infers
- * a picker control from them (`CONTROL_FOR_DECLARED_TYPE`). The SDK does not
- * model them yet.
- */
-const CONTROL_FORM_FIELD_TYPES = ['singleSelect', 'multiSelect', 'enum'];
 /** The product aliases, for the contract test. */
 export const FORM_FIELD_TYPE_ALIASES = PRODUCT_ALIASES;
 const isCanonical = (t) => typeof t === 'string' && Object.hasOwn(CANONICAL_JSON_SCHEMA, t);
 /**
  * The canonical type a wire or source spelling names, or `undefined` when it
- * names none the SDK models.
+ * names none the SDK models. A choice-control spelling is its own wire
+ * spelling, so it is `undefined` here too — its data type is
+ * `controlFormFieldType(t).data`; resolving it here would let a caller write
+ * `string` for a dropdown.
  *
  * @example
  * canonicalFormFieldType('integer')      // 'integer'
@@ -159,20 +191,15 @@ export function sourceFormFieldType(wire) {
 }
 /**
  * Why a form-field type is refused: a product alias the SDK does not accept in
- * source (`"System.Int32"` is the platform's .NET name for `integer`), a control
- * spelling the platform accepts but the SDK does not model yet
- * (`"singleSelect"`), or a type the product does not recognize at all.
- * `unknownWhy` is the caller's reason for the last case; the default is a human
- * task's.
+ * source (`"System.Int32"` is the platform's .NET name for `integer`), or a type
+ * the product does not recognize at all. `unknownWhy` is the caller's reason for
+ * the second case; the default is a human task's.
  */
 export function formFieldTypeWhy(type, unknownWhy = `which is not a quick-form field type: the platform rejects the form`) {
     const canonical = canonicalFormFieldType(type);
-    if (canonical !== undefined)
-        return `which is the platform's alias of '${canonical}' — the SDK writes '${canonical}'`;
-    if (typeof type === 'string' && CONTROL_FORM_FIELD_TYPES.includes(type)) {
-        return `which the platform accepts as a picker control but the SDK does not model yet`;
-    }
-    return unknownWhy;
+    return canonical !== undefined
+        ? `which is the platform's alias of '${canonical}' — the SDK writes '${canonical}'`
+        : unknownWhy;
 }
 /** The `suggestion` for an unknown form-field type: its canonical type, the nearest valid one, else `type: 'string'`. */
 export function formFieldTypeHint(type) {
@@ -189,9 +216,86 @@ export function formFieldTypeHint(type) {
  * @example
  * formFieldJsonSchema('date') // { type: 'string', format: 'date' }
  * formFieldJsonSchema('text') // { type: 'string' }
+ * formFieldJsonSchema('multiSelect') // { type: 'array' }
  */
 export function formFieldJsonSchema(type) {
-    const canonical = canonicalFormFieldType(type);
+    const canonical = canonicalFormFieldType(type) ?? controlFormFieldType(type)?.data;
     const schema = canonical === undefined ? undefined : ownEntry(CANONICAL_JSON_SCHEMA, canonical);
     return schema === undefined ? undefined : { ...schema };
 }
+/**
+ * A picker field's choices as the form row carries them (`options`, each
+ * `{ id, value, label }` — the product's `optionShape`), copied so the wire
+ * never aliases the author's array. `undefined` when the field has none.
+ * Both serializers (human task, quick-form escalation) write through this.
+ */
+export function formFieldOptionsWire(options) {
+    return options === undefined ? undefined : options.map((o) => ({ id: o.id, value: o.value, label: o.label }));
+}
+/** Whether a value is one well-formed choice: string `id`, `value` and `label`, all three the product requires. */
+function isFormFieldOption(o) {
+    if (o === null || typeof o !== 'object')
+        return false;
+    const r = o;
+    return typeof r.id === 'string' && typeof r.value === 'string' && typeof r.label === 'string';
+}
+/**
+ * A form row's `options` read back for source: the well-formed choices
+ * (string `id`, `value`, `label` — all three the product requires), or
+ * `undefined` when the row has no `options` array. A malformed entry is left
+ * out, not coerced: `{ id: 'o1', value: 1 }` is not rewritten to
+ * `value: '1', label: ''`. Decompile (human task and quick-form escalation)
+ * reads through this, so a canvas dropdown's choices survive an edit.
+ *
+ * @example
+ * liftFormFieldOptions([{ id: 'o1', value: 'a', label: 'A' }, { id: 'o2', value: 2 }])
+ * // [{ id: 'o1', value: 'a', label: 'A' }]
+ */
+export function liftFormFieldOptions(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    return raw.filter(isFormFieldOption).map((o) => ({ id: o.id, value: o.value, label: o.label }));
+}
+/**
+ * What is wrong with a form field's `options`, or `undefined` when nothing is.
+ * `check` reports each (human task and quick-form escalation):
+ *
+ * - `'malformed'`: `options` is there but is not an array of `{ id, value,
+ *   label }` strings. Serialize would throw or write rows the platform refuses.
+ * - `'missing'`: a choice-control type (`singleSelect`, `multiSelect`, `enum`)
+ *   with no choices. The form publishes an empty picker.
+ * - `'ignored'`: choices on a type that is not a choice control. The form
+ *   renders a plain input and never shows them.
+ *
+ * @example
+ * formFieldOptionsProblem('singleSelect', undefined)                         // 'missing'
+ * formFieldOptionsProblem('singleSelect', {})                                // 'malformed'
+ * formFieldOptionsProblem('string', [{ id: 'o1', value: 'a', label: 'A' }]) // 'ignored'
+ * formFieldOptionsProblem('enum', [{ id: 'o1', value: 'a', label: 'A' }])   // undefined
+ */
+export function formFieldOptionsProblem(type, options) {
+    if (options !== undefined && (!Array.isArray(options) || !options.every(isFormFieldOption)))
+        return 'malformed';
+    const isControl = controlFormFieldType(type) !== undefined;
+    if (isControl && (options === undefined || options.length === 0))
+        return 'missing';
+    if (!isControl && options !== undefined && options.length > 0)
+        return 'ignored';
+    return undefined;
+}
+/**
+ * The reason text for a `formFieldOptionsProblem`, worded for a diagnostic
+ * that starts "… the field "<id>" …".
+ */
+export function formFieldOptionsWhy(problem, type) {
+    switch (problem) {
+        case 'malformed':
+            return `has \`options\` that are not a list of { id, value, label } strings. Serialize cannot write them, `
+                + `and the platform requires all three on every choice`;
+        case 'missing':
+            return `is a ${JSON.stringify(type)} picker with no \`options\`, so the form publishes an empty picker`;
+        case 'ignored':
+            return `has \`options\` but its type ${JSON.stringify(type)} is not a choice control, so the form renders a `
+                + `plain input and never shows them. Use 'singleSelect' or 'enum' (a dropdown) or 'multiSelect'`;
+    }
+}

package/dist/decompile.js

@@ -50,7 +50,7 @@ import { OUTCOME_HANDLE_NODE_TYPES } from './core/hitl-routing.js';
 import { contributionPort, forwardFanOut } from './core/definition-handles.js';
 import { STICKY_NOTE_TYPE } from './core/definitionless-node-types.js';
 import { eventFilterFromTreeLeaf } from './core/event-filters.js';
-import { sourceFormFieldType } from './core/form-field-type.js';
+import { liftFormFieldOptions, sourceFormFieldType } from './core/form-field-type.js';
 /**
  * The trigger id of the flow currently being decompiled, so a reference through a
  * RENAMED trigger is still recognized as `input('x')` rather than falling back to
@@ -1306,6 +1306,12 @@ function emitAgentCluster(node, imp, inputNames, graph) {
                     ['id', tsText(f.id)],
                     ['type', tsLiteral(sourceFormFieldType(f.type ?? 'string'))],
                     ['direction', tsLiteral(String(f.direction ?? 'output'))],
+                    ['options', (() => {
+                            const options = liftFormFieldOptions(f.options);
+                            return options === undefined ? undefined : `[${options.map((o) => opts([
+                                ['id', tsLiteral(o.id)], ['value', tsLiteral(o.value)], ['label', tsLiteral(o.label)],
+                            ])).join(', ')}]`;
+                        })()],
                 ])).join(', ')}]` : undefined],
             ['app', app === undefined ? undefined : opts([
                     ['key', tsText(app.key)],
@@ -2276,7 +2282,7 @@ function armCb(param, segs) {
 function returnSeg(node, ctx) {
     const updates = ctx.flow.variables?.variableUpdates?.[node.id] ?? [];
     const outputIds = new Set(readFlowGlobals(ctx.flow.variables).filter((g) => g.direction === 'out').map((g) => g.id));
-    const opts = returnOptsArg(node);
+    const opts = returnOptsArg(node, ctx.refTargets?.has(node.id) ?? false);
     const entries = updates.map((u) => `${key(u.variableId)}: ${emitVal(u.expression, ctx.imp, ctx.inputNames)}`);
     const written = new Set(updates.map((u) => u.variableId));
     for (const [name, out] of Object.entries(node.outputs ?? {})) {
@@ -2317,9 +2323,10 @@ function isIdentityEndSource(raw, name, isOutput = false) {
  * it — compile then refused its own decompiled source with `layout: "endNiceDay"
  * names no step or node in this flow`.
  */
-function returnOptsArg(node) {
+function returnOptsArg(node, referenced = false) {
     const parts = [];
-    if (node.id !== 'end')
+    // A `.stepToRef` into this End needs it named, `end` included (#1223).
+    if (node.id !== 'end' || referenced)
         parts.push(`name: ${tsLiteral(node.id)}`);
     const ver = verClause(node);
     if (ver)
@@ -2365,7 +2372,12 @@ function region(cursor, stop, scope, ipdom, ctx, refInto) {
     const segs = [];
     while (cursor !== undefined && cursor !== stop && cursor !== EXIT) {
         // A ref forward: this path re-enters a step the main path reaches later.
+        // That includes the main path's End: one End with several incoming edges is
+        // a valid flow (the canvas draws it, `edge add` writes it), and a named End is
+        // a ref target, so the side path joins it instead of minting a second End
+        // (#1223). The main path's `.return(...)` then carries the End's `name`.
         if (refInto?.has(cursor)) {
+            (ctx.refTargets ??= new Set()).add(cursor);
             segs.push(`.stepToRef(${tsLiteral(cursor)})`);
             return segs;
         }
@@ -2375,8 +2387,9 @@ function region(cursor, stop, scope, ipdom, ctx, refInto) {
         // A ref backward or sideways: this path has arrived somewhere already emitted.
         // Before, the walk simply stopped here — which silently dropped the rest of a
         // cycle, and a backward edge is now something the builder can author. Ends and
-        // terminates are excluded: they are not named steps, so there is nothing a ref
-        // could resolve against, and each path emitting its own is already correct.
+        // terminates are excluded: each path emitting its own is a valid flow. (A
+        // side path into the MAIN path's End is the lookahead above, #1223; an End
+        // emitted earlier may be unnamed, so it is not a ref target here.)
         if (ctx.emitted.has(cursor) && node.type !== T.end && node.type !== T.terminate) {
             segs.push(`.stepToRef(${tsLiteral(cursor)})`);
             return segs;

package/dist/flow-sdk.d.ts

@@ -467,6 +467,10 @@ export interface ReturnOptions extends NodeOptions {
      * same values, label and version are one End reached from both paths; Ends that
      * differ are de-duplicated to `done` and `done2`.
      *
+     * A named End is also a {@link StepList.stepToRef} target: another path can
+     * end at this End rather than at one of its own. `check` refuses the ref
+     * (REF_AMBIGUOUS_TARGET) when the name is shared by another End or a step.
+     *
      * ```ts
      * .branch('checkTemperature', js`${input('tempF')} > 60`,
      *   (t) => t.return({}, { name: 'endNiceDay', label: 'Nice Day' }),
@@ -1196,7 +1200,19 @@ declare class StepList {
      * can prove it refuses; what depends on the runtime it warns about and leaves to
      * `uip maestro flow validate`.
      *
-     * @param target - The step to continue at, named as it was in `.step(...)`.
+     * The target may also be a NAMED End, `.return({…}, { name })`: the path then
+     * ends at that End node instead of one of its own, so one End has several
+     * incoming edges, as the canvas draws it.
+     *
+     * ```ts
+     * .step('fetch', http({ …, branches: [{ name: 'missing', condition: … }] }))
+     * .stepToList('branch-missing', (b) => b.step('log', script({ … })).stepToRef('done'))
+     * .step('use', script({ … }))
+     * .return({}, { name: 'done' })        // both paths end at this one End
+     * ```
+     *
+     * @param target - The step to continue at, named as it was in `.step(...)`, or
+     * the `name` of a `.return(...)` End.
      * @returns This builder. Nothing may follow: the path has been handed off.
      * @see stepToList
      */
@@ -1216,7 +1232,8 @@ declare class StepList {
      * ```
      *
      * @param port - The port of this step to leave, e.g. `'error'`.
-     * @param target - The step to continue at, named as it was in `.step(...)`.
+     * @param target - The step to continue at, named as it was in `.step(...)`, or
+     * the `name` of a `.return(...)` End.
      * @returns This builder, so calls chain — a side exit ends nothing.
      * @see stepToList
      */

package/dist/flow-sdk.js

@@ -840,7 +840,7 @@ class StepList {
         const target = maybeTarget === undefined ? portOrTarget : maybeTarget;
         if (typeof target !== 'string' || target.length === 0) {
             throw new TypeError(`.stepToRef() takes the NAME of the step to continue at — .stepToRef('priceIt') — and got ${JSON.stringify(target)}. `
-                + `It is the same name you passed to .step(), so the edge can be wired after the whole flow is built.`);
+                + `It is the same name you passed to .step() (or a .return() End's \`name\`), so the edge can be wired after the whole flow is built.`);
         }
         // A non-default port leaves the PRECEDING step, so it is guarded the same way
         // `.stepToList()` is; the default port continues the list and needs no source.