@uipath/maestro-builder-sdk 6.20.5 → 6.21.0

package/dist/core/js-code-spans.js

@@ -0,0 +1,148 @@
+/**
+ * The parts of a JavaScript expression or script body that are code.
+ *
+ * Short version: `$vars.summary` inside a quoted string is text, not a read.
+ * A rewrite that renames `$vars.<name>` (a step's node id, an output's backing
+ * Variable, #1092) must leave string literals, comments and regex literals
+ * alone, or it changes what the flow does:
+ *
+ * ```js
+ * return "$vars.summary" + $vars.summary;
+ * //     ^^^^^^^^^^^^^^^ text: kept    ^^^^^^^^^^^^^ code: renamed
+ * ```
+ *
+ * A template literal's text is kept too, and its `${…}` holes are code.
+ *
+ * This is a scanner, not a parser. It tells a regex literal from a division by
+ * the character before the `/` (the usual heuristic), so `return /"/` is read
+ * as a division. Nothing in a flow's expressions depends on that case.
+ */
+/** Characters after which a `/` starts a regex literal, not a division. */
+const REGEX_AFTER = new Set('(,=:[!&|?{};+-*%<>~^'.split(''));
+/**
+ * `text` with `fn` applied to each run of code, and every string, template
+ * text, comment and regex literal copied as written.
+ */
+export function mapJsCode(text, fn) {
+    let out = '';
+    const n = text.length;
+    const flushCode = (from, to) => { if (to > from)
+        out += fn(text.slice(from, to)); };
+    /** Index just past the quoted string that opens at `i`. */
+    const endQuoted = (i, q) => {
+        let j = i + 1;
+        while (j < n && text[j] !== q && text[j] !== '\n')
+            j += text[j] === '\\' ? 2 : 1;
+        return Math.min(j + 1, n);
+    };
+    /** Index just past the regex literal that opens at `i`. */
+    const endRegex = (i) => {
+        let j = i + 1;
+        let inClass = false;
+        while (j < n && text[j] !== '\n') {
+            const c = text[j];
+            if (c === '\\') {
+                j += 2;
+                continue;
+            }
+            if (c === '[')
+                inClass = true;
+            else if (c === ']')
+                inClass = false;
+            else if (c === '/' && !inClass) {
+                j++;
+                break;
+            }
+            j++;
+        }
+        while (j < n && /[A-Za-z]/.test(text[j]))
+            j++;
+        return Math.min(j, n);
+    };
+    /**
+     * Scan code from `i`. Inside a template hole, stop at its closing `}` and
+     * return that index; otherwise run to the end.
+     */
+    const scanCode = (i, inHole) => {
+        let start = i;
+        let depth = 0;
+        let prev = '';
+        while (i < n) {
+            const c = text[i];
+            if (c === '"' || c === "'") {
+                flushCode(start, i);
+                const j = endQuoted(i, c);
+                out += text.slice(i, j);
+                i = start = j;
+                prev = c;
+                continue;
+            }
+            if (c === '`') {
+                flushCode(start, i);
+                i = start = scanTemplate(i);
+                prev = c;
+                continue;
+            }
+            if (c === '/' && (text[i + 1] === '/' || text[i + 1] === '*')) {
+                flushCode(start, i);
+                const close = text[i + 1] === '/' ? text.indexOf('\n', i) : text.indexOf('*/', i + 2);
+                const j = close < 0 ? n : text[i + 1] === '/' ? close : close + 2;
+                out += text.slice(i, j);
+                i = start = j;
+                continue;
+            }
+            if (c === '/' && (prev === '' || REGEX_AFTER.has(prev))) {
+                flushCode(start, i);
+                const j = endRegex(i);
+                out += text.slice(i, j);
+                i = start = j;
+                prev = '/';
+                continue;
+            }
+            if (inHole) {
+                if (c === '{')
+                    depth++;
+                else if (c === '}') {
+                    if (depth === 0) {
+                        flushCode(start, i);
+                        return i;
+                    }
+                    depth--;
+                }
+            }
+            if (!/\s/.test(c))
+                prev = c;
+            i++;
+        }
+        flushCode(start, i);
+        return i;
+    };
+    /** Copy the template literal that opens at `i`, mapping its holes; return the index past it. */
+    const scanTemplate = (i) => {
+        let start = i;
+        let j = i + 1;
+        while (j < n) {
+            const c = text[j];
+            if (c === '\\') {
+                j += 2;
+                continue;
+            }
+            if (c === '`') {
+                out += text.slice(start, j + 1);
+                return j + 1;
+            }
+            if (c === '$' && text[j + 1] === '{') {
+                out += text.slice(start, j + 2);
+                j = scanCode(j + 2, true);
+                start = j; // the hole's `}` opens the next verbatim run
+                j++;
+                continue;
+            }
+            j++;
+        }
+        out += text.slice(start, n);
+        return n;
+    };
+    scanCode(0, false);
+    return out;
+}

package/dist/core/nodes/node-type.d.ts

@@ -45,12 +45,26 @@ export interface OutputRead {
     /** The step whose expression contains the read. */
     reader: string;
 }
+/**
+ * How the artifact words a read of a `fields` output: the code prefix its read
+ * diagnostics share (`<PREFIX>_READ_NOT_OUTPUT`, `_READ_WITHOUT_RETURNS`,
+ * `_READ_UNKNOWN_FIELD`, each in the family's catalog), how a message names the
+ * node (`'Queue item'`), and what to tell an author who declared no fields.
+ */
+export interface FieldsRead {
+    readonly codePrefix: string;
+    readonly label: string;
+    readonly whenUndeclared: string;
+}
 /**
  * What reading a node's output yields at run time.
  *
  * `none` keeps the diagnostic code of the rule it replaces
  * (`DATAFABRIC_DELETE_HAS_NO_OUTPUT`, `MOCK_HAS_NO_OUTPUT`, …) and builds the
- * message itself, so a port changes no diagnostic an author sees.
+ * message itself, so a port changes no diagnostic an author sees. `fields`
+ * states the fields a read may name — `undefined` when the author declared none,
+ * which makes any field read its own mistake — and `read` keeps the wording of
+ * the read rule it replaces, for the same reason. `open` admits any field.
  */
 export type OutputContract = {
     readonly kind: 'none';
@@ -58,8 +72,9 @@ export type OutputContract = {
     message(read: OutputRead): string;
 } | {
     readonly kind: 'fields';
-    readonly fields: Readonly<Record<string, TypeDesc>>;
+    readonly fields: Readonly<Record<string, TypeDesc>> | undefined;
     readonly open?: boolean;
+    readonly read: FieldsRead;
 } | {
     readonly kind: 'opaque';
 };

package/dist/core/typed-raw-node.js

@@ -23,8 +23,6 @@ import { ownEntry } from './own-entry.js';
 export const TYPED_FACTORIES = {
     'core.action.http': { factory: 'http({ managed: false })' },
     'core.action.http.v2': { factory: 'http({ managed: true })' },
-    'core.action.queue.create': { factory: 'queueItem()' },
-    'core.action.queue.create-and-wait': { factory: 'queueItem({ wait: true })' },
     'core.control.end': { factory: '.return()' },
     'core.logic.decision': { factory: '.branch()' },
     'core.logic.dowhile': { factory: '.doWhile(name, condition, body, { limit, breakEnabled })' },

package/dist/decompile.js

@@ -40,6 +40,8 @@ import { contextIndexSlug, parseContextIndexType } from './core/context-index.js
 import { wireExprBody } from './core/wire-expr.js';
 import { parseIxpProjectType } from './core/actions.js';
 import { readFlowGlobals } from './flow-variables.js';
+import { outputBackingGlobal, outputBackingName } from './flow-output-backing.js';
+import { mapJsCode } from './core/js-code-spans.js';
 import { missingBindingLabels } from './core/binding-messages.js';
 import { prepareCommand } from './core/cli-spelling.js';
 import { OUTCOME_HANDLE_NODE_TYPES, outcomeSlug } from './core/hitl-routing.js';
@@ -226,8 +228,6 @@ const T = {
     hitlQuickForm: 'uipath.human-in-the-loop.quick-form',
     hitlActionApp: 'uipath.human-in-the-loop.coded-action-app',
     hitlDocValidation: 'uipath.human-in-the-loop.document-validation',
-    queueCreate: 'core.action.queue.create',
-    queueCreateAndWait: 'core.action.queue.create-and-wait',
     summarize: 'uipath.pattern.deep-rag',
     batchTransform: 'uipath.pattern.batch-transform',
     sendMessage: 'uipath.conversational.send-message',
@@ -642,35 +642,6 @@ function emitStepSpec(node, imp, inputNames, o, graph) {
         case T.hitlActionApp:
         case T.hitlDocValidation:
             return emitHitl(node, imp, inputNames, graph);
-        case T.queueCreate:
-        case T.queueCreateAndWait: {
-            // `itemData` is the node's name for the surface's `item` (the reference
-            // documents the mapping); `queue` carries the three identity fields.
-            const q = (inputs.queue ?? {});
-            const rows = Object.entries((inputs.itemData ?? {}))
-                .map(([k, v]) => [k, emitVal(v, imp, inputNames)]);
-            const optStr = (key) => {
-                const raw = unwrapSource(inputs[key]);
-                // serialize writes '' for an omitted optional — that is not an authored
-                // value, so it must not come back as one.
-                if (raw === undefined || raw === '')
-                    return undefined;
-                return raw.startsWith('=js:') ? emitBareExpr(raw.slice(4), imp, inputNames) : tsLiteral(raw);
-            };
-            const priority = unwrapPlain(inputs.priority);
-            return `${imp.use('queueItem')}(${opts([
-                ['queue', tsText(q.name)],
-                ['folderPath', tsText(q.folderPath)],
-                ['key', tsText(q.key)],
-                ['item', rows.length ? objLit(rows) : '{}'],
-                // `Normal` is the definition's default — only a departure was authored.
-                ['priority', typeof priority === 'string' && priority !== 'Normal' ? tsLiteral(priority) : undefined],
-                ['reference', optStr('reference')],
-                ['deferDate', optStr('deferDate')],
-                ['dueDate', optStr('dueDate')],
-                ['wait', node.type === T.queueCreateAndWait ? 'true' : undefined],
-            ])})`;
-        }
         case T.summarize:
         case T.batchTransform: {
             const attachment = emitVal(inputs.attachment, imp, inputNames);
@@ -2342,6 +2313,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 entries = updates.map((u) => `${key(u.variableId)}: ${emitVal(u.expression, ctx.imp, ctx.inputNames)}`);
     const written = new Set(updates.map((u) => u.variableId));
@@ -2350,7 +2322,7 @@ function returnSeg(node, ctx) {
             continue;
         const source = out?.source;
         const raw = unwrapSource(source);
-        if (raw === undefined || isIdentityEndSource(raw, name))
+        if (raw === undefined || isIdentityEndSource(raw, name, outputIds.has(name)))
             continue;
         entries.push(`${key(name)}: ${emitVal(source, ctx.imp, ctx.inputNames)}`);
     }
@@ -2358,10 +2330,15 @@ function returnSeg(node, ctx) {
         return `.return({}${opts})`;
     return `.return({ ${entries.join(', ')} }${opts})`;
 }
-/** The fill-in mapping `endOutputs` writes for an output no `.return` named: `=js:$vars.<name>`. */
-function isIdentityEndSource(raw, name) {
-    const body = raw.startsWith('=js:') ? raw.slice(4) : raw;
-    return body.trim() === `$vars.${name}`;
+/**
+ * The fill-in mapping `endOutputs` writes for a variable no `.return` named:
+ * `=js:$vars.<name>`, read through the backing Variable `foldOutputBacking`
+ * has already folded back. An output with no backing Variable fills in as
+ * `null` (#1092), since nothing but `.return()` sets it.
+ */
+function isIdentityEndSource(raw, name, isOutput = false) {
+    const body = (raw.startsWith('=js:') ? raw.slice(4) : raw).trim();
+    return body === `$vars.${name}` || (isOutput && body === 'null');
 }
 /**
  * The options argument for a `.return(...)` — `version`, plus the End's `name`
@@ -3131,7 +3108,101 @@ function slugId(flow) {
     const slug = base.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
     return slug || 'flow';
 }
+// ─── Output backing Variables (#1092) ─────────────────────────────────────────
+/** Sorted-key JSON, so two globals compare equal whatever their key order. */
+function canonicalJson(v) {
+    if (Array.isArray(v))
+        return `[${v.map(canonicalJson).join(',')}]`;
+    if (v && typeof v === 'object') {
+        const o = v;
+        return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`).join(',')}}`;
+    }
+    return JSON.stringify(v);
+}
+/**
+ * The wire fields whose plain-string value is JavaScript (no `=js:` prefix):
+ * a script body, a decision or switch `expression`, a loop's `condition` and
+ * `completionCondition`, an HTTP branch's `conditionExpression`, a transform's
+ * `collection`. `serialize` renames `$vars` reads in exactly these and in
+ * `=js:` values.
+ */
+const RAW_JS_FIELDS = new Set(['script', 'expression', 'condition', 'completionCondition', 'conditionExpression', 'collection']);
+/**
+ * Every `$vars.<from>` read (the whole root, not a prefix of a longer one) in
+ * `v`'s code, read as `$vars.<to>`. Code is a `=js:` wire value, a plain
+ * `$vars.` path, or a `RAW_JS_FIELDS` value; in each, only the code spans are
+ * rewritten. A label, a literal input, or a quoted `"$vars.<from>"` inside a
+ * script stays as written, the way `serialize` left it (#1092 review).
+ */
+function renameVarRoot(v, from, to) {
+    const re = new RegExp(`\\$vars\\.${from.replace(/[$]/g, '\\$&')}(?![A-Za-z0-9_$])`, 'g');
+    const inCode = (js) => mapJsCode(js, (code) => code.replace(re, `$vars.${to}`));
+    const walk = (x, key) => {
+        if (typeof x === 'string') {
+            if (x.startsWith('=js:'))
+                return '=js:' + inCode(x.slice(4));
+            if (x.startsWith('$vars.') || (key !== undefined && RAW_JS_FIELDS.has(key)))
+                return inCode(x);
+            return x;
+        }
+        if (Array.isArray(x))
+            return x.map((y) => walk(y, key));
+        if (x && typeof x === 'object')
+            return Object.fromEntries(Object.entries(x).map(([k, y]) => [k, walk(y, k)]));
+        return x;
+    };
+    return walk(v);
+}
+/**
+ * Undo the backing-Variable lowering `serialize` applies to an output the flow
+ * sets from inside (`flow-output-backing.ts`): fold the `inout` `<output>Value`
+ * global back into its output, so the source says `{ updates: { summary } }`
+ * and `v('summary')` again and recompiling emits the same bytes.
+ *
+ * A pair is folded only when the Variable is exactly what `serialize` would
+ * emit for that output (`outputBackingGlobal`): same id, type, default,
+ * subType and schema, no description, no trigger. Any other `inout` global,
+ * one a person named `summaryValue` with a description say, stays a `.var()`.
+ * Applied to each subflow body too, against that body's own globals.
+ */
+function foldOutputBacking(flow) {
+    const subflows = flow.subflows
+        ? Object.fromEntries(Object.entries(flow.subflows).map(([k, c]) => [k, foldOutputBacking(c)]))
+        : undefined;
+    let out = subflows ? { ...flow, subflows } : flow;
+    const globals = Array.isArray(flow.variables?.globals) ? flow.variables.globals : [];
+    for (const o of globals.filter((g) => g.direction === 'out')) {
+        const id = outputBackingName(o.id);
+        const b = globals.find((g) => g.id === id && g.direction === 'inout');
+        if (!b)
+            continue;
+        const expected = outputBackingGlobal({ name: o.id, type: o.type, default: o.defaultValue, subType: o.subType, schema: o.schema }, id);
+        if (canonicalJson(b) !== canonicalJson(expected))
+            continue;
+        const vars = out.variables;
+        const updates = Object.fromEntries(Object.entries(vars.variableUpdates ?? {}).map(([node, rows]) => [
+            node, rows.map((r) => (r.variableId === id ? { ...r, variableId: o.id } : r)),
+        ]));
+        const nodes = (out.nodes ?? []).map((n) => {
+            if (n.type !== 'core.control.end' || !n.outputs || !(id in n.outputs))
+                return n;
+            const { [id]: _dropped, ...rest } = n.outputs;
+            return { ...n, outputs: rest };
+        });
+        out = {
+            ...out,
+            nodes: renameVarRoot(nodes, id, o.id),
+            variables: {
+                ...vars,
+                globals: (vars.globals ?? []).filter((g) => g !== b && g.id !== id),
+                variableUpdates: renameVarRoot(updates, id, o.id),
+            },
+        };
+    }
+    return out;
+}
 export function decompile(flow, options = {}) {
+    flow = foldOutputBacking(flow);
     const importSpecifier = options.importSpecifier ?? './flow-sdk.js';
     runStrict = options.bestEffort === false;
     runWarn = options.warn;

package/dist/flow-node-registry.js

@@ -12,8 +12,9 @@ import { dataFabricFlowFamily } from './nodes/data-fabric/flow/family.js';
 import { delayFlowFamily } from './nodes/delay/flow/family.js';
 import { documentFlowFamily } from './nodes/document/flow/family.js';
 import { mockFlowFamily } from './nodes/mock/flow/family.js';
+import { queueFlowFamily } from './nodes/queue/flow/family.js';
 import { scriptFlowFamily } from './nodes/script/flow/family.js';
 import { transformFlowFamily } from './nodes/transform/flow/family.js';
 /** The families, in no significant order. Adding one is the whole of registering it. */
-export const FLOW_NODE_FAMILIES = [dataFabricFlowFamily, delayFlowFamily, documentFlowFamily, mockFlowFamily, scriptFlowFamily, transformFlowFamily];
+export const FLOW_NODE_FAMILIES = [dataFabricFlowFamily, delayFlowFamily, documentFlowFamily, mockFlowFamily, queueFlowFamily, scriptFlowFamily, transformFlowFamily];
 export const FLOW_NODE_TYPES = new NodeTypeRegistry('flow', FLOW_NODE_FAMILIES, { hasBundledDefinition });

package/dist/flow-node-type.d.ts

@@ -75,6 +75,12 @@ export interface FlowSerializeContext {
     } & Readonly<Record<string, unknown>>): void;
     /** The bundled definition `<typeName>@<version>`, or undefined when the SDK does not ship it. */
     definition(typeName: string, version: string): unknown;
+    /**
+     * The flow's bindings so far, by id — read-only. For a type that SHARES a
+     * binding with earlier steps on the same resource (a queue's name + folder
+     * pair) or must pick an id that is not taken; add entries through `bind`.
+     */
+    readonly bindings: ReadonlyMap<string, Readonly<Record<string, unknown>>>;
 }
 /** What `deserialize` may ask of the decompiler, for one serialized node. */
 export interface FlowDeserializeContext {

package/dist/flow-output-backing.d.ts

@@ -0,0 +1,53 @@
+import type { BuiltFlow, Step, VarDecl } from './flow-sdk.js';
+/** The suffix of a backing Variable's id: `summary` → `summaryValue`. */
+export declare const OUTPUT_BACKING_SUFFIX = "Value";
+/** The id of the Variable that backs output `output`. */
+export declare function outputBackingName(output: string): string;
+/** One reason a backing Variable cannot be emitted. */
+export interface OutputBackingProblem {
+    code: 'OUTPUT_BACKING_COLLISION';
+    name: string;
+    message: string;
+    suggestion?: string;
+}
+/** Which outputs get a backing Variable, in output declaration order. */
+export interface OutputBackingPlan {
+    /** Output name → backing Variable id. */
+    backing: Map<string, string>;
+    /**
+     * The same pairs, minus outputs that share their name with a step. Those
+     * `$vars.<name>` reads are the step's output (`out('slug')` with an output
+     * also called `slug`), so only these are redirected to the Variable.
+     */
+    reads: Map<string, string>;
+    problems: OutputBackingProblem[];
+}
+/**
+ * The variable names one scope's steps write with `{ updates }`, the `$vars`
+ * roots its expressions and script bodies read, and its step names. A
+ * subflow's child flow is skipped: its globals are its own.
+ */
+export declare function scopeVariableUse(steps: readonly Step[]): {
+    written: Set<string>;
+    read: Set<string>;
+    stepNames: Set<string>;
+};
+/**
+ * Plan the backing Variables for one scope (the flow, or one subflow body).
+ *
+ * @param built - The scope's flow.
+ * @param outputs - Its outputs after the `.output()` + `.var()` merge (`planFlowGlobals`).
+ * @param vars - The `.var()`s it emits, the SDK-declared `{ shared }` ones included.
+ * @param sharedOutputs - The outputs a `{ shared }` input feeds.
+ */
+export declare function planOutputBacking(built: Pick<BuiltFlow, 'inputs' | 'steps' | 'entryPoints' | 'triggerId'>, outputs: readonly VarDecl[], vars: readonly {
+    name: string;
+}[], sharedOutputs?: ReadonlySet<string>): OutputBackingPlan;
+/** The `inout` global that backs output `o`: its type and value metadata, no description. */
+export declare function outputBackingGlobal(o: {
+    name: string;
+    type: string;
+    default?: unknown;
+    subType?: string;
+    schema?: Record<string, unknown>;
+}, id: string): Record<string, unknown>;

package/dist/flow-output-backing.js

@@ -0,0 +1,200 @@
+/**
+ * Backing variables for flow outputs that a step sets (flow-builder-sdk#1092).
+ *
+ * Short version: in Studio Web an Output (`direction: 'out'`) is set ONLY by an
+ * End node's output mapping. "Update Variable" offers only Variables
+ * (`direction: 'inout'`), and expressions can't read an Output. So when an
+ * author's source sets an output from inside the flow, the SDK emits the shape a
+ * Studio Web user builds by hand: a Variable that holds the running value, and
+ * an End mapping that copies it into the Output.
+ *
+ * ```ts
+ * flow('probe').output({ summary: types.string })
+ *   .step('work', script({ … }), { updates: { summary: out('work') } })
+ * ```
+ *
+ * emits
+ *
+ * ```
+ * globals:          summary (out), summaryValue (inout)
+ * variableUpdates:  work → summaryValue = $vars.work.output
+ * end.outputs:      summary ← $vars.summaryValue, summaryValue ← $vars.summaryValue
+ * ```
+ *
+ * The oracle (flow-workbench `develop`):
+ * - `VariablesContext.tsx` `getWritableVariables` / `useWritableVariables`:
+ *   the Update Variable editor lists `direction === 'inout'` only, and creates
+ *   new rows as `inout` (`VariableUpdateEditor.tsx`).
+ * - `VariablesContext.tsx` `getReadableVariables` / `filterReadableVariables`:
+ *   expression editors drop `direction === 'out'`; the validator's `$vars`
+ *   declarations (`generate-variable-declarations.ts`) hold `in` and `inout`.
+ *   Reading `$vars.<output>` is `EXPRESSION_DIAGNOSTIC: Property '<output>'
+ *   does not exist`.
+ * - `end-node-sets-output.flow` / `end-node-different-branches.flow`: an End
+ *   sets an Output from an expression, `outputs.<id>.source`, and writes no
+ *   variable update.
+ * - The product has no naming rule for the Variable (the dialog checks only
+ *   identifier syntax and uniqueness against `useReservedIds`). The SDK names
+ *   it `<output>Value`, the same suffix its `{ shared }` suggestion uses, and
+ *   refuses a source that already uses that name for something else.
+ *
+ * An output gets a backing Variable when the flow's own source sets or reads it
+ * outside a `.return()` value:
+ * - a step's `{ updates }` (any step kind, `.return(…, { updates })` included);
+ * - a `{ shared }` input that feeds it;
+ * - a declared `default` (including the one a same-named `.var()` gives it,
+ *   flow-builder-sdk#899), because the default is the value an End returns when
+ *   no step set it;
+ * - an expression or script body that reads `$vars.<output>` in code (unless a
+ *   step has the output's name: then `$vars.<name>` is that step's output). A
+ *   label, a literal input, or a quoted `"$vars.<output>"` inside a script is
+ *   text and reads nothing.
+ *
+ * An output that only `.return({ … })` sets needs none: each End maps it from
+ * the returned expression, and an End that does not name it maps `null`, which
+ * is what the old `$vars.<output>` read evaluated to on that path.
+ */
+import { Expr } from './core/expr.js';
+import { mapJsCode } from './core/js-code-spans.js';
+/** The suffix of a backing Variable's id: `summary` → `summaryValue`. */
+export const OUTPUT_BACKING_SUFFIX = 'Value';
+/** The id of the Variable that backs output `output`. */
+export function outputBackingName(output) {
+    return `${output}${OUTPUT_BACKING_SUFFIX}`;
+}
+/** A `$vars.<root>` read: the root identifier, ended by anything that cannot continue it. */
+const VARS_ROOT_RE = /\$vars\.([A-Za-z_$][A-Za-z0-9_$]*)/g;
+/** The `$vars` roots that `js`'s code reads; a quoted `"$vars.x"` is text, not a read. */
+function readsOf(js, into) {
+    mapJsCode(js, (code) => {
+        for (const m of code.matchAll(VARS_ROOT_RE))
+            into.add(m[1]);
+        return code;
+    });
+}
+/** A wire expression (`=js:…`), as a raw node carries one. */
+const WIRE_JS_PREFIX = '=js:';
+/** A child flow (a subflow's body) is its own scope with its own globals. */
+function isBuiltFlow(v) {
+    const o = v;
+    return Array.isArray(o.steps) && Array.isArray(o.outputs) && Array.isArray(o.inputs) && Array.isArray(o.vars);
+}
+/**
+ * The variable names one scope's steps write with `{ updates }`, the `$vars`
+ * roots its expressions and script bodies read, and its step names. A
+ * subflow's child flow is skipped: its globals are its own.
+ */
+export function scopeVariableUse(steps) {
+    const written = new Set();
+    const read = new Set();
+    const stepNames = new Set();
+    const seen = new WeakSet();
+    const visit = (val) => {
+        // A plain string is a label, a prompt or a literal input, never a read;
+        // only a raw node's `=js:` wire expression is code (#1092 review).
+        if (typeof val === 'string') {
+            if (val.startsWith(WIRE_JS_PREFIX))
+                readsOf(val.slice(WIRE_JS_PREFIX.length), read);
+            return;
+        }
+        if (val === null || typeof val !== 'object')
+            return;
+        if (seen.has(val))
+            return;
+        seen.add(val);
+        if (val instanceof Expr) {
+            if (!val.literal)
+                readsOf(val.js, read);
+            return;
+        }
+        if (isBuiltFlow(val))
+            return;
+        if (Array.isArray(val)) {
+            for (const v of val)
+                visit(v);
+            return;
+        }
+        const rec = val;
+        // A script body is a plain string that is code (`script({ code })`).
+        if (rec.kind === 'script' && typeof rec.inputs?.code === 'string') {
+            readsOf(rec.inputs.code, read);
+        }
+        if (typeof rec.kind === 'string') {
+            // A step. Its name is a node id (a `.return()`'s synthetic one is not).
+            if (typeof rec.name === 'string' && rec.kind !== 'return')
+                stepNames.add(rec.name);
+            const updates = rec.options?.updates;
+            if (updates && typeof updates === 'object' && !(updates instanceof Expr)) {
+                for (const k of Object.keys(updates))
+                    written.add(k);
+            }
+        }
+        for (const v of Object.values(rec))
+            visit(v);
+    };
+    for (const s of steps)
+        visit(s);
+    return { written, read, stepNames };
+}
+/**
+ * Plan the backing Variables for one scope (the flow, or one subflow body).
+ *
+ * @param built - The scope's flow.
+ * @param outputs - Its outputs after the `.output()` + `.var()` merge (`planFlowGlobals`).
+ * @param vars - The `.var()`s it emits, the SDK-declared `{ shared }` ones included.
+ * @param sharedOutputs - The outputs a `{ shared }` input feeds.
+ */
+export function planOutputBacking(built, outputs, vars, sharedOutputs = new Set()) {
+    const steps = [...built.steps, ...(built.entryPoints ?? []).flatMap((ep) => ep.steps)];
+    const use = scopeVariableUse(steps);
+    const taken = new Map();
+    const claim = (name, what) => { if (!taken.has(name))
+        taken.set(name, what); };
+    for (const i of built.inputs)
+        claim(i.name, `input "${i.name}"`);
+    for (const ep of built.entryPoints ?? []) {
+        claim(ep.id, `entry point "${ep.id}"`);
+        for (const i of ep.inputs)
+            claim(i.name, `input "${i.name}"`);
+    }
+    for (const o of outputs)
+        claim(o.name, `output "${o.name}"`);
+    for (const v of vars)
+        claim(v.name, `variable "${v.name}"`);
+    for (const s of use.stepNames)
+        claim(s, `step "${s}"`);
+    claim(built.triggerId ?? 'start', `trigger "${built.triggerId ?? 'start'}"`);
+    const backing = new Map();
+    const problems = [];
+    for (const o of outputs) {
+        const readsIt = use.read.has(o.name) && !use.stepNames.has(o.name);
+        const needs = use.written.has(o.name) || readsIt || sharedOutputs.has(o.name) || o.default !== undefined;
+        if (!needs)
+            continue;
+        const id = outputBackingName(o.name);
+        const holder = taken.get(id);
+        if (holder) {
+            problems.push({
+                code: 'OUTPUT_BACKING_COLLISION', name: o.name,
+                message: `Output "${o.name}" is set inside the flow, so compile backs it with a Variable named "${id}": `
+                    + `Studio Web sets an Output only on an End node, and Update Variable writes only Variables. `
+                    + `But "${id}" is already the ${holder}, and the .flow keeps one id per variable or step.`,
+                suggestion: `Rename the ${holder}.`,
+            });
+            continue;
+        }
+        taken.set(id, `backing variable of output "${o.name}"`);
+        backing.set(o.name, id);
+    }
+    const reads = new Map([...backing].filter(([o]) => !use.stepNames.has(o)));
+    return { backing, reads, problems };
+}
+/** The `inout` global that backs output `o`: its type and value metadata, no description. */
+export function outputBackingGlobal(o, id) {
+    return {
+        id, name: id, direction: 'inout', type: o.type,
+        ...(o.default !== undefined ? { defaultValue: o.default } : {}),
+        ...(o.subType !== undefined ? { subType: o.subType } : {}),
+        ...(o.schema !== undefined ? { schema: o.schema } : {}),
+    };
+}