@uipath/maestro-builder-sdk 6.16.8 → 6.16.9

package/dist/api-index.md

@@ -166,7 +166,7 @@ could hand you spans for a version you do not have.
 | `ixpExtract` | function | `dist/core/actions.d.ts:2670-2724` | Actions | Extract fields from a document with a published IxP project — the platform's **Extract** node (`uipath.ixp.*`, service… |
 | `IxpExtractInputs` | interface | `dist/core/actions.d.ts:879-953` | Option shapes | 9 field(s) |
 | `IxpToolRef` | interface | `dist/core/actions.d.ts:1891-1929` | Supporting types | A published IxP (Intelligent eXtraction Platform) project as a tool — the agent decides when to extract a document and… |
-| `js` | function | `dist/core/expr.d.ts:241-252` | Expressions and types | Build a raw JS *expression* (a condition or computation). |
+| `js` | function | `dist/core/expr.d.ts:241-276` | Expressions and types | Build a raw JS *expression* (a condition or computation). |
 | `lit` | function | `dist/core/expr.d.ts:22-28` | Expressions and types | A constant value baked directly into a node input. |
 | `lookup` | function | `dist/core/lookups.d.ts:95-102` | Generated descriptors | Begin resolving a lookup field on a generated descriptor. |
 | `lookup` | function | `dist/core/lookups.d.ts:103-122` | Generated descriptors | Begin resolving a lookup field addressed by connector key and action. |
@@ -232,7 +232,7 @@ could hand you spans for a version you do not have.
 | `summarize` | function | `dist/core/actions.d.ts:2594-2634` | Actions | Summarize a document with citations — the platform's **Summarize** node. |
 | `SummarizeInputs` | interface | `dist/core/actions.d.ts:806-838` | Option shapes | 3 field(s) |
 | `SwitchArm` | interface | `dist/flow-sdk.d.ts:329-334` | Supporting types | One arm of a built `.switch` (the serializer's view: body already collected). |
-| `tmpl` | function | `dist/core/expr.d.ts:253-263` | Expressions and types | Build a JS *string template* (for URLs, messages, etc.). |
+| `tmpl` | function | `dist/core/expr.d.ts:277-287` | Expressions and types | Build a JS *string template* (for URLs, messages, etc.). |
 | `ToolRef` | type | `dist/core/actions.d.ts:1657-1666` | Supporting types | One tool on an inline agent — a discriminated union over the kinds the tenant's registry actually serves… |
 | `transform` | function | `dist/core/actions.d.ts:2496-2541` | Actions | Declare a Transform action — a chain of declarative operations over a collection. |
 | `Transformation` | type | `dist/core/actions.d.ts:248-249` | Supporting types | What a map does to a field's value. |
@@ -244,8 +244,8 @@ could hand you spans for a version you do not have.
 | `TriggerMeta` | interface | `dist/core/connectors.d.ts:120-129` | Generated descriptors | Runtime metadata a generated trigger descriptor carries. |
 | `TriggerOptions` | interface | `dist/core/actions.d.ts:3410-3457` | Option shapes | The typed `onEvent`/`waitForEvent` options — everything an EventSubscription carries except `connector`/`event`, which… |
 | `TriggerSpec` | type | `dist/flow-sdk.d.ts:150-168` | Supporting types | What starts the flow. |
-| `TypeDesc` | type | `dist/core/expr.d.ts:328` | Supporting types |  |
-| `types` | const | `dist/core/expr.d.ts:312-327` | Expressions and types | Variable type descriptors (map to Flow variable `type` values). |
+| `TypeDesc` | type | `dist/core/expr.d.ts:379` | Supporting types |  |
+| `types` | const | `dist/core/expr.d.ts:363-378` | Expressions and types | Variable type descriptors (map to Flow variable `type` values). |
 | `unresolvedLookupMessage` | function | `dist/core/lookups.d.ts:180-189` | Generated descriptors | The message for a lookup nothing has resolved — the command that fixes it. |
 | `v` | function | `dist/core/expr.d.ts:29-41` | Expressions and types | Reference a flow variable or output by name → `$vars.<name>`. |
 | `VarDecl` | interface | `dist/flow-sdk.d.ts:47-59` | Supporting types | 7 field(s) |
@@ -337,7 +337,7 @@ could hand you spans for a version you do not have.
 | `TriggerDescriptor` | type | `dist/core/connectors.d.ts:130-138` | Supporting types | A generated, typed connector-trigger descriptor: TriggerMeta branded with phantom `where`/output types. |
 | `TriggerMeta` | interface | `dist/core/connectors.d.ts:120-129` | Supporting types | Runtime metadata a generated trigger descriptor carries. |
 | `TriggerOptions` | interface | `dist/core/actions.d.ts:3410-3457` | Option shapes | The typed `onEvent`/`waitForEvent` options — everything an EventSubscription carries except `connector`/`event`, which… |
-| `TypeDesc` | type | `dist/core/expr.d.ts:328` | Supporting types |  |
+| `TypeDesc` | type | `dist/core/expr.d.ts:379` | Supporting types |  |
 | `UnresolvedReferenceTaskKind` | type | `dist/case/case-sdk.d.ts:358-359` | Supporting types | Published-resource task kinds that the Case schema permits as unresolved skeletons. |
 | `WaitConnectorPlaceholderSpec` | interface | `dist/case/case-sdk.d.ts:360-370` | Supporting types | A `wait-for-connector` subscription: suspend on an Integration Service event. |
 | `WaitConnectorSpec` | type | `dist/case/case-sdk.d.ts:371-375` | Supporting types | A placeholder connector/operation pair, or a library-resolved event subscription using the same symbolic shape as Flow… |
@@ -436,7 +436,7 @@ could hand you spans for a version you do not have.
 | `TimerLike` | type | `dist/bpmn/bpmn-sdk.d.ts:40-41` | Supporting types | A timer as an ISO-8601 duration string (shorthand for `{ duration }`) or a full spec. |
 | `TimerSpec` | interface | `dist/bpmn/bpmn-sdk.d.ts:31-39` | Supporting types | ISO-8601 timer specification (one of duration / date / cycle). |
 | `TypedContextRow` | interface | `dist/bpmn/typed-node.d.ts:155-186` | Supporting types | One `uipath:context` input row, spelled out. |
-| `TypeDesc` | type | `dist/core/expr.d.ts:328` | Supporting types |  |
+| `TypeDesc` | type | `dist/core/expr.d.ts:379` | Supporting types |  |
 | `TypedInputRow` | interface | `dist/bpmn/typed-node.d.ts:187-209` | Supporting types | One `uipath:input` payload row spelled out — the `separateInputs` counterpart of TypedContextRow. |
 | `TypedOutputRow` | interface | `dist/bpmn/typed-node.d.ts:246-285` | Supporting types | 9 field(s) |
 | `VarDirection` | type | `dist/bpmn/bpmn-sdk.d.ts:361-365` | Supporting types | How a variable is exposed: `'input'` (read-only entry input), `'output'` (a return value), or `'inputOutput'` (a mutable… |

package/dist/check.js

@@ -9,6 +9,7 @@ import { Expr, SCHEDULE_PRESETS, DELAY_PRESETS, VARIANT_OPERATION, parseIxpProje
 import { FlowNode } from './core/node-classes.js';
 import { QUEUE_ITEM_RECORD_SCHEMA } from './core/queue-record.js';
 import { checkEventResolution, checkEventSubscription, eventParamsFor, } from './core/event-checks.js';
+import { checkCookedEscapes } from './flow-expr-check.js';
 import { FLOW_EXPR_DIALECT, checkBindingLabels, checkBindingPresence, checkConnectorContract as coreCheckConnectorContract, checkConnectorLookups as coreCheckConnectorLookups, checkConnectorSchema as coreCheckConnectorSchema, collectConnectionUses, connectionConnectorConflicts, } from './core/connector-checks.js';
 import { prepareCommand } from './core/cli-spelling.js';
 import { editDistance } from './core/edit-distance.js';
@@ -25,6 +26,15 @@ export function check(built, opts = {}) {
     for (const { id, message } of connectionConnectorConflicts(uses, opts)) {
         diags.push({ level: 'error', code: 'CONNECTION_CONNECTOR_CONFLICT', step: id, message });
     }
+    // Once, from the top: the walk reaches child flows itself, so running it per
+    // `checkFlow` would report a child's escape twice.
+    for (const d of checkCookedEscapes(built)) {
+        diags.push({
+            level: d.level, code: d.code, message: `In ${d.where}: ${d.message}`,
+            ...(d.step !== undefined ? { step: d.step } : {}),
+            ...(d.suggestion ? { suggestion: d.suggestion } : {}),
+        });
+    }
     return diags;
 }
 /**

package/dist/core/expr-check.d.ts

@@ -29,6 +29,37 @@
  * and gets back diagnostics with no location. The caller stamps the location
  * (which node / task / field) it came from.
  */
+import type { CookedEscape } from './expr.js';
+/** What one cooked escape did to an expression. */
+export interface CookedEscapeEffect {
+    /** The escape as written, e.g. `\d`. */
+    escape: string;
+    /** What TypeScript turned it into. */
+    cooked: string;
+    /** `meaning`: the expression parses but means something else. `syntax`: it no longer parses. */
+    effect: 'meaning' | 'syntax';
+    /** The escape was invalid, so `js` wrote `undefined` for its whole part. */
+    invalid?: true;
+}
+/**
+ * Which of an expression's cooked escapes changed it, and how. Harmless ones are
+ * left out. See the block comment above for the rule.
+ */
+export declare function cookedEscapeEffects(expr: string, escapes: readonly CookedEscape[]): CookedEscapeEffect[];
+/** The escape spelled so it survives: one more backslash. */
+export declare function keptEscape(escape: string): string;
+/** The sentence that explains one cooked escape, shared by the warning and EXPR_SYNTAX. */
+export declare function cookedEscapeSentence(e: CookedEscapeEffect): string;
+/**
+ * A diagnostic per escape that changed what an expression means. Location is
+ * stamped by the caller.
+ *
+ *  * JS_ESCAPE_COOKED (warning) — a valid escape cooked to another character:
+ *    `/\d+/` became `/d+/`. The expression may still be what the author wants.
+ *  * JS_ESCAPE_INVALID (error) — an invalid escape (`\1`, `\x4`): the whole part
+ *    of the template became the word `undefined`, which is never what was meant.
+ */
+export declare function cookedEscapeDiagnostics(expr: string, escapes: readonly CookedEscape[]): ExprDiagnostic[];
 /** A `$vars.*` reference found in an expression. */
 export interface ExprRef {
     /** The first segment after `$vars.` — the name the reference is rooted at. */
@@ -90,4 +121,4 @@ export declare function extractRefs(expr: string, namespace?: string): ExprRef[]
  * message). An empty result means "nothing this check is sure is wrong" — never
  * "fully valid"; the `validate` CLI is what proves the rest.
  */
-export declare function checkExpression(expr: string, scope: ExprScope): ExprDiagnostic[];
+export declare function checkExpression(expr: string, scope: ExprScope, escapes?: readonly CookedEscape[]): ExprDiagnostic[];

package/dist/core/expr-check.js

@@ -50,16 +50,129 @@ const JSONPATH_WILDCARD = /\[\s*(?:\*|\?|'[^']*'|"[^"]*")\s*\]|\.\.[A-Za-z_$]/;
  * this adds no dependency.
  */
 function syntaxError(expr) {
+    const problems = parseExpression(expr).problems;
+    if (problems.length === 0)
+        return undefined;
+    return ts.flattenDiagnosticMessageText(problems[0].messageText, ' ');
+}
+function parseExpression(expr) {
     const source = ts.createSourceFile('expression.ts', `(${expr}\n)`, ts.ScriptTarget.ES2020, 
     /* setParentNodes */ false);
     // `parseDiagnostics` is where the scanner records syntax problems. It is not on
     // the public `SourceFile` type, hence the cast; there is no public API that
     // parses a fragment and hands back its syntax diagnostics without also running
     // a full program's type-check.
-    const problems = source.parseDiagnostics;
-    if (!problems || problems.length === 0)
-        return undefined;
-    return ts.flattenDiagnosticMessageText(problems[0].messageText, ' ');
+    const problems = source.parseDiagnostics ?? [];
+    return { source, problems };
+}
+/** Replace each chosen escape's cooked text with what was typed. Escapes are disjoint and in order. */
+function retype(expr, escapes, keepCooked) {
+    let out = '';
+    let pos = 0;
+    for (const e of escapes) {
+        out += expr.slice(pos, e.at) + (e === keepCooked ? e.cooked : e.typed);
+        pos = e.at + e.cooked.length;
+    }
+    return out + expr.slice(pos);
+}
+/** The value a leaf denotes — a name, or a literal's value (a regular expression's is its source). */
+function leafValue(node) {
+    if (ts.isIdentifier(node) || ts.isPrivateIdentifier(node))
+        return node.text;
+    // NumericLiteral … TemplateTail: every literal and template piece carries `.text`.
+    if (node.kind >= ts.SyntaxKind.FirstLiteralToken && node.kind <= ts.SyntaxKind.LastTemplateToken) {
+        return node.text;
+    }
+    return undefined;
+}
+function children(node) {
+    const out = [];
+    ts.forEachChild(node, (c) => { out.push(c); });
+    return out;
+}
+function sameTree(a, b) {
+    if (a.kind !== b.kind || leafValue(a) !== leafValue(b))
+        return false;
+    const ca = children(a);
+    const cb = children(b);
+    return ca.length === cb.length && ca.every((c, i) => sameTree(c, cb[i]));
+}
+/**
+ * Which of an expression's cooked escapes changed it, and how. Harmless ones are
+ * left out. See the block comment above for the rule.
+ */
+export function cookedEscapeEffects(expr, escapes) {
+    if (escapes.length === 0)
+        return [];
+    const sorted = [...escapes].sort((a, b) => a.at - b.at);
+    const typed = parseExpression(retype(expr, sorted));
+    if (typed.problems.length)
+        return [];
+    const effects = [];
+    const seen = new Set();
+    for (const e of sorted) {
+        const one = parseExpression(retype(expr, sorted, e));
+        const effect = one.problems.length ? 'syntax' : sameTree(typed.source, one.source) ? undefined : 'meaning';
+        if (!effect || seen.has(`${effect} ${e.escape}`))
+            continue;
+        seen.add(`${effect} ${e.escape}`);
+        effects.push({ escape: e.escape, cooked: e.cooked, effect, ...(e.invalid ? { invalid: true } : {}) });
+    }
+    return effects;
+}
+const CHARACTER_NAMES = {
+    '\b': 'backspace', '\f': 'form feed', '\n': 'line feed', '\r': 'carriage return',
+    '\t': 'tab', '\v': 'vertical tab', '\0': 'NUL', '\u2028': 'line separator', '\u2029': 'paragraph separator',
+};
+/** How to say what an escape became, in a message. */
+function describeCooked(cooked) {
+    if (cooked === '')
+        return 'nothing (a line continuation)';
+    const name = CHARACTER_NAMES[cooked];
+    if (name)
+        return `U+${cooked.codePointAt(0).toString(16).toUpperCase().padStart(4, '0')} (${name})`;
+    return `\`${cooked}\``;
+}
+/** The escape spelled so it survives: one more backslash. */
+export function keptEscape(escape) {
+    return '\\' + escape;
+}
+/** The sentence that explains one cooked escape, shared by the warning and EXPR_SYNTAX. */
+export function cookedEscapeSentence(e) {
+    const fix = `write \`${keptEscape(e.escape)}\` to keep the backslash.`;
+    if (e.invalid) {
+        return `\`${e.escape}\` is not a valid escape in a js\`\` template, so TypeScript drops that whole part of `
+            + `the template and the expression holds the word \`undefined\` in its place; ${fix}`;
+    }
+    return `\`${e.escape}\` in a js\`\` template is read by TypeScript as ${describeCooked(e.cooked)} before the `
+        + `SDK sees it; ${fix}`;
+}
+/**
+ * A diagnostic per escape that changed what an expression means. Location is
+ * stamped by the caller.
+ *
+ *  * JS_ESCAPE_COOKED (warning) — a valid escape cooked to another character:
+ *    `/\d+/` became `/d+/`. The expression may still be what the author wants.
+ *  * JS_ESCAPE_INVALID (error) — an invalid escape (`\1`, `\x4`): the whole part
+ *    of the template became the word `undefined`, which is never what was meant.
+ */
+export function cookedEscapeDiagnostics(expr, escapes) {
+    return cookedEscapeEffects(expr, escapes)
+        .filter((e) => e.effect === 'meaning')
+        .map((e) => e.invalid
+        ? {
+            level: 'error',
+            code: 'JS_ESCAPE_INVALID',
+            message: cookedEscapeSentence(e),
+            suggestion: keptEscape(e.escape),
+        }
+        : {
+            level: 'warning',
+            code: 'JS_ESCAPE_COOKED',
+            message: `${cookedEscapeSentence(e)} The expression parses, so nothing else reports it, but it no longer `
+                + `means what was typed.`,
+            suggestion: keptEscape(e.escape),
+        });
 }
 const DEFAULT_NAMESPACE = '$vars';
 /**
@@ -149,7 +262,7 @@ function nearMiss(name, roots) {
  * message). An empty result means "nothing this check is sure is wrong" — never
  * "fully valid"; the `validate` CLI is what proves the rest.
  */
-export function checkExpression(expr, scope) {
+export function checkExpression(expr, scope, escapes = []) {
     const namespace = scope.namespace ?? DEFAULT_NAMESPACE;
     const noun = scope.noun ?? 'input, variable, or step';
     const diags = [];
@@ -158,11 +271,16 @@ export function checkExpression(expr, scope) {
     // references, and reporting both would just be noise on one root cause.
     const syntax = scope.syntax === 'javascript' ? syntaxError(expr) : undefined;
     if (syntax) {
+        // A `js` template whose escape broke the parse: say which one, or the author
+        // goes looking for an unterminated string they never wrote.
+        const cause = cookedEscapeEffects(expr, escapes).filter((e) => e.effect === 'syntax');
         return [{
                 level: 'error',
                 code: 'EXPR_SYNTAX',
-                message: `Expression is not valid JavaScript: ${syntax}`,
-                ...(JSONPATH_WILDCARD.test(expr)
+                message: `Expression is not valid JavaScript: ${syntax}`
+                    + cause.map((e) => ` ${cookedEscapeSentence(e)}`).join(''),
+                ...(cause.length ? { suggestion: keptEscape(cause[0].escape) } : {}),
+                ...(!cause.length && JSONPATH_WILDCARD.test(expr)
                     ? {
                         suggestion: 'This looks like JSONPath. The runtime evaluates JavaScript, so index or map '
                             + 'explicitly — `…issues` for the whole array, `…issues.map(i => i.key)` for one field.',

package/dist/core/expr.d.ts

@@ -243,11 +243,35 @@ export declare function err(step: string, field?: ErrorEnvelopeField): Expr;
  * Interpolated `Expr`s contribute their reference; other values are JSON-encoded.
  * e.g. js`${input('from')} !== ${input('to')}` → `$vars.from !== $vars.to`
  *
+ * @remarks
+ * **Backslashes are read by TypeScript first.** The expression is the template's
+ * COOKED text: TypeScript applies every backslash escape before `js` sees it, the
+ * same as in any template literal. So a regular expression typed with one
+ * backslash loses it — `` js`/\d+/.test(${x})` `` emits `/d+/.test(…)`, which
+ * matches the letter `d`, and `\b` becomes the backspace character, not a word
+ * boundary. Write the backslash twice to keep it: `` js`/\\d+/.test(${x})` ``
+ * emits `/\d+/.test(…)`. Likewise `` \` `` is a backtick, and `\${` keeps `${` from
+ * starting an interpolation.
+ * This is the spelling `decompile` writes.
+ *
+ * `check` reports an escape that changed what the expression means
+ * (JS_ESCAPE_COOKED), and an `EXPR_SYNTAX` error names the escape when one broke
+ * the parse (`'\n'` in a string literal becomes a real line break). An escape
+ * that is not valid in a template at all (`\1`, `\x4`) leaves TypeScript no text
+ * for that part, so the expression would hold the word `undefined`: `check`
+ * refuses it (JS_ESCAPE_INVALID).
+ *
  * @param strings - The template's literal parts, supplied by the tag call.
  * @param vals - Interpolated values. An {@link Expr} contributes its reference;
  * anything else is JSON-encoded.
  * @returns An {@link Expr} carrying the composed JavaScript expression.
  * @see tmpl
+ * @example
+ * ```ts
+ * .return({ hasDigit: js`/\\d+/.test(${input('text')})` })
+ * ```
+ * @enforcedBy JS_ESCAPE_COOKED Write a backslash twice inside `js`: TypeScript
+ * reads `\d` as `d` before the SDK sees it.
  */
 export declare function js(strings: TemplateStringsArray, ...vals: unknown[]): Expr;
 /**
@@ -261,6 +285,33 @@ export declare function js(strings: TemplateStringsArray, ...vals: unknown[]): E
  * @see js
  */
 export declare function tmpl(strings: TemplateStringsArray, ...vals: unknown[]): Expr;
+/**
+ * One backslash escape TypeScript applied inside a `js` template.
+ *
+ * @internal Recorded by `js`, read by `check`; not an authoring value.
+ */
+export interface CookedEscape {
+    /** Offset in `Expr.js` where the cooked text starts. */
+    readonly at: number;
+    /** The text TypeScript produced, as it sits in `Expr.js` (`d`, U+0008, `undefined`). */
+    readonly cooked: string;
+    /** What the author typed in its place, read as JavaScript (`\d`). */
+    readonly typed: string;
+    /** The escape as written, for messages (`\d`). */
+    readonly escape: string;
+    /**
+     * An INVALID template escape (`\1`, `\x4`): TypeScript gives the whole part no
+     * cooked value, and `js` writes the word `undefined` in its place.
+     */
+    readonly invalid?: true;
+}
+/**
+ * The backslash escapes TypeScript cooked away inside this expression's `js`
+ * templates, nested ones included. Empty for anything else.
+ *
+ * @internal Read by `check`; not an authoring factory.
+ */
+export declare function cookedEscapesOf(val: unknown): readonly CookedEscape[];
 /**
  * Coerce a raw value or Expr into an Expr.
  *

package/dist/core/expr.js

@@ -260,20 +260,60 @@ export function err(step, field) {
  * Interpolated `Expr`s contribute their reference; other values are JSON-encoded.
  * e.g. js`${input('from')} !== ${input('to')}` → `$vars.from !== $vars.to`
  *
+ * @remarks
+ * **Backslashes are read by TypeScript first.** The expression is the template's
+ * COOKED text: TypeScript applies every backslash escape before `js` sees it, the
+ * same as in any template literal. So a regular expression typed with one
+ * backslash loses it — `` js`/\d+/.test(${x})` `` emits `/d+/.test(…)`, which
+ * matches the letter `d`, and `\b` becomes the backspace character, not a word
+ * boundary. Write the backslash twice to keep it: `` js`/\\d+/.test(${x})` ``
+ * emits `/\d+/.test(…)`. Likewise `` \` `` is a backtick, and `\${` keeps `${` from
+ * starting an interpolation.
+ * This is the spelling `decompile` writes.
+ *
+ * `check` reports an escape that changed what the expression means
+ * (JS_ESCAPE_COOKED), and an `EXPR_SYNTAX` error names the escape when one broke
+ * the parse (`'\n'` in a string literal becomes a real line break). An escape
+ * that is not valid in a template at all (`\1`, `\x4`) leaves TypeScript no text
+ * for that part, so the expression would hold the word `undefined`: `check`
+ * refuses it (JS_ESCAPE_INVALID).
+ *
  * @param strings - The template's literal parts, supplied by the tag call.
  * @param vals - Interpolated values. An {@link Expr} contributes its reference;
  * anything else is JSON-encoded.
  * @returns An {@link Expr} carrying the composed JavaScript expression.
  * @see tmpl
+ * @example
+ * ```ts
+ * .return({ hasDigit: js`/\\d+/.test(${input('text')})` })
+ * ```
+ * @enforcedBy JS_ESCAPE_COOKED Write a backslash twice inside `js`: TypeScript
+ * reads `\d` as `d` before the SDK sees it.
  */
 export function js(strings, ...vals) {
     let out = '';
+    const escapes = [];
     strings.forEach((s, i) => {
+        // Recorded BEFORE `out` grows, so each offset is where the cooked text lands.
+        const raw = strings.raw?.[i];
+        if (raw !== undefined)
+            for (const e of segmentEscapes(raw, s))
+                escapes.push({ ...e, at: out.length + e.at });
         out += s;
-        if (i < vals.length)
+        if (i < vals.length) {
+            const at = out.length;
             out += exprText(vals[i]);
+            for (const e of cookedEscapesOf(vals[i]))
+                escapes.push({ ...e, at: at + e.at });
+        }
     });
-    return new Expr(out.trim());
+    const lead = out.length - out.trimStart().length;
+    const text = out.trim();
+    // An escape cooked into whitespace the trim removed is gone from the expression.
+    const kept = escapes
+        .filter((e) => e.at >= lead && e.at + e.cooked.length <= lead + text.length)
+        .map((e) => ({ ...e, at: e.at - lead }));
+    return withCookedEscapes(new Expr(text), kept);
 }
 /**
  * Build a JS *string template* (for URLs, messages, etc.).
@@ -287,16 +327,129 @@ export function js(strings, ...vals) {
  */
 export function tmpl(strings, ...vals) {
     let body = '';
+    const escapes = [];
     strings.forEach((s, i) => {
         body += s.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
-        if (i < vals.length)
+        if (i < vals.length) {
+            // tmpl's OWN escapes are cooked on purpose (`tmpl`a\nb`` is a line break,
+            // as in a template literal). Only an interpolated js`…`'s lost escapes
+            // travel on, so `check` still sees them once the Expr is nested.
+            const at = 1 + body.length + 2; // past the opening backtick and `${`
             body += '${' + exprText(vals[i]) + '}';
+            for (const e of cookedEscapesOf(vals[i]))
+                escapes.push({ ...e, at: at + e.at });
+        }
     });
-    return new Expr('`' + body + '`');
+    return withCookedEscapes(new Expr('`' + body + '`'), escapes);
 }
 function exprText(val) {
     return val instanceof Expr ? val.js : JSON.stringify(val);
 }
+const COOKED_ESCAPES = Symbol.for('@uipath/maestro-builder-sdk/cookedEscapes');
+/**
+ * The backslash escapes TypeScript cooked away inside this expression's `js`
+ * templates, nested ones included. Empty for anything else.
+ *
+ * @internal Read by `check`; not an authoring factory.
+ */
+export function cookedEscapesOf(val) {
+    if (val === null || typeof val !== 'object')
+        return [];
+    return val[COOKED_ESCAPES] ?? [];
+}
+function withCookedEscapes(e, escapes) {
+    if (escapes.length)
+        Object.defineProperty(e, COOKED_ESCAPES, { value: Object.freeze(escapes), enumerable: false });
+    return e;
+}
+/**
+ * The three escapes a `js` template needs to say what it means — and exactly the
+ * three `decompile` writes: `\\` (one backslash), `` \` `` (a backtick) and `\${`
+ * (so `${` is not an interpolation). A `\$` NOT before `{` is not one of them: a
+ * template needs no escape there, and `` js`/\$/` `` cooks a literal-dollar regex
+ * into `/$/`, an end anchor. Every other escape is TypeScript's, not the author's
+ * JavaScript.
+ */
+function isTemplateEscape(raw, i) {
+    const next = raw[i + 1];
+    return next === '\\' || next === '`' || (next === '$' && raw[i + 2] === '{');
+}
+const SINGLE_ESCAPES = { b: '\b', f: '\f', n: '\n', r: '\r', t: '\t', v: '\v' };
+/**
+ * The escapes in one template part, at offsets in its cooked text. `raw` is the
+ * part as typed (`strings.raw[i]`), `cooked` what TypeScript made of it — or
+ * `undefined` when an escape is not valid in a template (`\1`, `\x4`): the
+ * whole part is then lost, and `js` appends the word `undefined` in its place.
+ *
+ * The cooking rules are ECMAScript's TemplateCharacter grammar. The rebuilt text
+ * must equal `cooked`; if it ever does not, nothing is recorded rather than
+ * something wrong.
+ */
+function segmentEscapes(raw, cooked) {
+    const found = [];
+    let built = '';
+    let typed = '';
+    let invalid;
+    for (let i = 0; i < raw.length; i++) {
+        const ch = raw[i];
+        if (ch !== '\\' || i + 1 >= raw.length) {
+            built += ch;
+            typed += ch;
+            continue;
+        }
+        const next = raw[i + 1];
+        if (isTemplateEscape(raw, i)) {
+            built += next;
+            typed += next;
+            i++;
+            continue;
+        }
+        let len = 2;
+        let value;
+        if (next === '\n' || next === '\u2028' || next === '\u2029')
+            value = ''; // line continuation
+        else if (next in SINGLE_ESCAPES)
+            value = SINGLE_ESCAPES[next];
+        else if (next === '0' && !/[0-9]/.test(raw[i + 2] ?? ''))
+            value = '\0';
+        else if (/[0-9]/.test(next))
+            value = undefined;
+        else if (next === 'x') {
+            const hex = /^[0-9a-fA-F]{2}/.exec(raw.slice(i + 2));
+            if (hex) {
+                value = String.fromCharCode(parseInt(hex[0], 16));
+                len = 4;
+            }
+        }
+        else if (next === 'u') {
+            const m = /^(?:\{([0-9a-fA-F]+)\}|([0-9a-fA-F]{4}))/.exec(raw.slice(i + 2));
+            const cp = m ? parseInt(m[1] ?? m[2], 16) : NaN;
+            if (m && cp <= 0x10ffff) {
+                value = String.fromCodePoint(cp);
+                len = 2 + m[0].length;
+            }
+        }
+        else {
+            // Any other character escapes to itself: `\d` → `d`, `\.` → `.`.
+            value = String.fromCodePoint(raw.codePointAt(i + 1));
+            len = 1 + value.length;
+        }
+        const escape = raw.slice(i, i + len);
+        if (value === undefined)
+            invalid ??= escape;
+        else {
+            found.push({ at: built.length, cooked: value, typed: escape, escape });
+            built += value;
+        }
+        typed += escape;
+        i += len - 1;
+    }
+    if (cooked === undefined) {
+        // `out += undefined` writes the word itself — that is what the expression holds.
+        return invalid === undefined ? [] : [{ at: 0, cooked: 'undefined', typed, escape: invalid, invalid: true }];
+    }
+    return built === cooked ? found : [];
+}
 /**
  * Coerce a raw value or Expr into an Expr.
  *

package/dist/flow-expr-check.d.ts

@@ -6,6 +6,23 @@ export interface LocatedDiagnostic extends ExprDiagnostic {
 }
 /** Every first-level expression problem in a built flow, each stamped with its location. */
 export declare function checkFlowExpressions(built: BuiltFlow): LocatedDiagnostic[];
+/**
+ * Every `js` template escape that changed what its expression means
+ * (JS_ESCAPE_COOKED), each stamped with where it sits.
+ *
+ * WHY A GENERIC WALK. The two per-site walks (`walk` above and `check.ts`'s
+ * expression collection) each enumerate the positions an expression can sit in,
+ * and neither covers all of them — HTTP branch conditions, trigger filters and
+ * error-handler bodies each live in only one, or none. This warning is about the
+ * `Expr` itself, not about the field it fills, so it visits every `Expr` reachable
+ * from the built flow, child flows included: a new position cannot be missed.
+ *
+ * Only `meaning` effects are reported here. An escape that breaks the parse is
+ * named by EXPR_SYNTAX, which already stops `build()`.
+ */
+export declare function checkCookedEscapes(built: BuiltFlow): (LocatedDiagnostic & {
+    step?: string;
+})[];
 /**
  * Thrown by `build()` when the first-level expression check finds errors. Its
  * `message` lists every problem (so a runner that prints `err.message` shows them

package/dist/flow-expr-check.js

@@ -27,8 +27,8 @@
  * body is a plain string carrying its own `$vars.*` references; checking those is
  * the same mechanism and a natural next step, deliberately out of this first cut.
  */
-import { Expr } from './core/expr.js';
-import { checkExpression } from './core/expr-check.js';
+import { Expr, cookedEscapesOf } from './core/expr.js';
+import { checkExpression, cookedEscapeDiagnostics } from './core/expr-check.js';
 const NOUN = 'input, variable, or step';
 /**
  * Every `$vars` root a reference may legitimately resolve to, across the WHOLE
@@ -108,16 +108,18 @@ function addStepNames(steps, roots) {
         }
     }
 }
-function pushExpr(js, literal, where, roots, out) {
-    if (literal)
+function pushExpr(e, where, roots, out) {
+    if (e.literal)
         return; // a literal carries no reference to resolve
-    for (const d of checkExpression(js, { roots, noun: NOUN, syntax: 'javascript' }))
+    // The cooked escapes ride along so an EXPR_SYNTAX error can name the one that broke the parse.
+    for (const d of checkExpression(e.js, { roots, noun: NOUN, syntax: 'javascript' }, cookedEscapesOf(e))) {
         out.push({ ...d, where });
+    }
 }
 /** Reach `Expr`s nested anywhere in an action's inputs (connector/http/… inputs can be structured). */
 function deepExprs(val, where, roots, out) {
     if (val instanceof Expr)
-        return pushExpr(val.js, val.literal, where, roots, out);
+        return pushExpr(val, where, roots, out);
     if (Array.isArray(val)) {
         for (const v of val)
             deepExprs(v, where, roots, out);
@@ -140,12 +142,12 @@ function walk(steps, roots, out) {
                 walk(s.body, roots, out);
                 break;
             case 'branch':
-                pushExpr(s.cond.js, s.cond.literal, s.name, roots, out);
+                pushExpr(s.cond, s.name, roots, out);
                 walk(s.then, roots, out);
                 walk(s.otherwise, roots, out);
                 break;
             case 'switch': {
-                pushExpr(s.on.js, s.on.literal, s.name, roots, out);
+                pushExpr(s.on, s.name, roots, out);
                 // Inside a case (or default) body the discriminant is bound to
                 // `$vars.value`, so it is a valid root only there.
                 const caseRoots = new Set(roots).add('value');
@@ -163,14 +165,14 @@ function walk(steps, roots, out) {
                     walk(c.body, roots, out);
                 break;
             case 'loop':
-                pushExpr(s.collection.js, s.collection.literal, s.name, roots, out);
+                pushExpr(s.collection, s.name, roots, out);
                 if (s.options?.completionCondition) {
-                    pushExpr(s.options.completionCondition.js, s.options.completionCondition.literal, s.name, roots, out);
+                    pushExpr(s.options.completionCondition, s.name, roots, out);
                 }
                 walk(s.body, roots, out);
                 break;
             case 'doWhile':
-                pushExpr(s.condition.js, s.condition.literal, s.name, roots, out);
+                pushExpr(s.condition, s.name, roots, out);
                 walk(s.body, roots, out);
                 break;
             case 'parallel':
@@ -179,7 +181,7 @@ function walk(steps, roots, out) {
                 break;
             case 'return':
                 for (const [k, v] of Object.entries(s.values))
-                    pushExpr(v.js, v.literal, `return "${k}"`, roots, out);
+                    pushExpr(v, `return "${k}"`, roots, out);
                 break;
         }
     }
@@ -193,6 +195,65 @@ export function checkFlowExpressions(built) {
         walk(ep.steps, roots, out);
     return out;
 }
+/**
+ * Every `js` template escape that changed what its expression means
+ * (JS_ESCAPE_COOKED), each stamped with where it sits.
+ *
+ * WHY A GENERIC WALK. The two per-site walks (`walk` above and `check.ts`'s
+ * expression collection) each enumerate the positions an expression can sit in,
+ * and neither covers all of them — HTTP branch conditions, trigger filters and
+ * error-handler bodies each live in only one, or none. This warning is about the
+ * `Expr` itself, not about the field it fills, so it visits every `Expr` reachable
+ * from the built flow, child flows included: a new position cannot be missed.
+ *
+ * Only `meaning` effects are reported here. An escape that breaks the parse is
+ * named by EXPR_SYNTAX, which already stops `build()`.
+ */
+export function checkCookedEscapes(built) {
+    const out = [];
+    const seen = new WeakSet();
+    const root = built;
+    const visit = (val, at) => {
+        if (val === null || typeof val !== 'object')
+            return;
+        const escapes = cookedEscapesOf(val);
+        if (escapes.length) {
+            for (const d of cookedEscapeDiagnostics(val.js, escapes)) {
+                out.push({ ...d, where: at.where, ...(at.step !== undefined ? { step: at.step } : {}) });
+            }
+            return;
+        }
+        if (val instanceof Expr || seen.has(val))
+            return;
+        seen.add(val);
+        if (Array.isArray(val)) {
+            for (const v of val)
+                visit(v, at);
+            return;
+        }
+        const o = val;
+        if (o === root) {
+            for (const [k, v] of Object.entries(o))
+                visit(v, { where: k, prefix: '' });
+            return;
+        }
+        // A child flow under a step (a subflow's `spec.child`): its steps are named in its own scope.
+        if (at.step !== undefined && Array.isArray(o.steps) && Array.isArray(o.inputs))
+            at = { ...at, prefix: `${at.where} › ` };
+        if (o.kind === 'return' && o.values && typeof o.values === 'object') {
+            for (const [k, v] of Object.entries(o.values))
+                visit(v, { ...at, where: `${at.prefix}return "${k}"` });
+            return;
+        }
+        if (typeof o.kind === 'string' && typeof o.name === 'string') {
+            at = { ...at, where: `${at.prefix}step "${o.name}"`, step: at.step ?? o.name };
+        }
+        for (const v of Object.values(o))
+            visit(v, at);
+    };
+    visit(built, { where: 'flow', prefix: '' });
+    return out;
+}
 /**
  * Thrown by `build()` when the first-level expression check finds errors. Its
  * `message` lists every problem (so a runner that prints `err.message` shows them

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.16.8",
+  "version": "6.16.9",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -92,5 +92,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "77b292a40160cde6e025bbeb534397e5e930bae1"
+  "gitref": "dd5b33d6640e176c10be173688ee2767cdd3f251"
 }