donobu 5.33.0 → 5.35.0

package/dist/esm/lib/ai/cache/assertCache.d.ts

@@ -33,6 +33,13 @@ export declare const PlaywrightAssertionStepSchema: z.ZodObject<{
 export type PlaywrightAssertionStep = z.infer<typeof PlaywrightAssertionStepSchema>;
 export type AssertCacheExecutor = (context: {
     page: Page;
+    /**
+     * Optional env mapping used to interpolate `{{$.env.X}}` placeholders that
+     * the AI may have embedded into step `value`/`attributeValue` fields. When
+     * absent, steps run unchanged (backwards compatible with cache entries
+     * recorded before env-aware caching).
+     */
+    envData?: Record<string, string>;
 }) => Promise<void>;
 /**
  * Builds an executor function from structured assertion steps.
@@ -85,6 +92,13 @@ export type LocateCacheEntryWithRunner = LocateCacheEntry & {
 };
 export type LocateCacheExecutor = (context: {
     page: DonobuExtendedPage;
+    /**
+     * Optional env mapping used to interpolate `{{$.env.X}}` placeholders that
+     * the AI may have embedded into `LocatorStep.text`/`name`/`testId` fields.
+     * Absent → steps run unchanged (backwards compatible with cache entries
+     * recorded before env-aware caching).
+     */
+    envData?: Record<string, string>;
 }) => Locator;
 /**
  * Builds a cache executor that mechanically reconstructs a Playwright

package/dist/esm/lib/ai/cache/assertCache.js

@@ -5,6 +5,7 @@ exports.buildAssertExecutor = buildAssertExecutor;
 exports.buildLocateExecutor = buildLocateExecutor;
 const test_1 = require("@playwright/test");
 const v4_1 = require("zod/v4");
+const TemplateInterpolator_1 = require("../../../utils/TemplateInterpolator");
 const buildLocator_1 = require("../locate/buildLocator");
 // ---------------------------------------------------------------------------
 // Structured assertion step schema
@@ -84,17 +85,33 @@ Common roles: 'heading', 'button', 'link', 'tab', 'tabpanel', 'dialog', 'navigat
 - toContainText: set to the text substring to match within the element
 - All other assertions: set to null`),
 });
+/**
+ * Resolves any `{{$.env.X}}` placeholders in a step field against the
+ * supplied env data. Returns the input verbatim when no env data is given,
+ * preserving backwards compatibility with cached entries that contain
+ * literal values only.
+ */
+function resolveStepField(value, envData) {
+    if (!envData || !value.includes('{{')) {
+        return value;
+    }
+    return (0, TemplateInterpolator_1.interpolateString)(value, { env: envData, calls: [] });
+}
 /**
  * Builds an executor function from structured assertion steps.
  * Each step maps to exactly one Playwright `expect` call — no string
  * evaluation, no VM contexts.
  */
 function buildAssertExecutor(steps) {
-    return async ({ page }) => {
+    return async ({ page, envData }) => {
         for (const step of steps) {
+            const resolvedValue = resolveStepField(step.value, envData);
+            const resolvedAttrValue = step.attributeValue === null
+                ? null
+                : resolveStepField(step.attributeValue, envData);
             const matcher = step.valueIsRegex
-                ? new RegExp(step.value)
-                : step.value;
+                ? new RegExp(resolvedValue)
+                : resolvedValue;
             // Page-level assertions (no element locator needed)
             if (step.assertion === 'toHaveTitle') {
                 await (0, test_1.expect)(page).toHaveTitle(matcher);
@@ -138,13 +155,13 @@ function buildAssertExecutor(steps) {
                     await (0, test_1.expect)(locator).toBeChecked();
                     break;
                 case 'toHaveValue':
-                    await (0, test_1.expect)(locator).toHaveValue(step.attributeValue ?? '');
+                    await (0, test_1.expect)(locator).toHaveValue(resolvedAttrValue ?? '');
                     break;
                 case 'toContainText':
-                    await (0, test_1.expect)(locator).toContainText(step.attributeValue ?? '');
+                    await (0, test_1.expect)(locator).toContainText(resolvedAttrValue ?? '');
                     break;
                 case 'toHaveAttribute':
-                    await (0, test_1.expect)(locator).toHaveAttribute(step.value, step.attributeValue ?? '');
+                    await (0, test_1.expect)(locator).toHaveAttribute(resolvedValue, resolvedAttrValue ?? '');
                     break;
             }
         }
@@ -155,6 +172,6 @@ function buildAssertExecutor(steps) {
  * {@link Locator} from a cached {@link LocateResult}.
  */
 function buildLocateExecutor(result) {
-    return ({ page }) => (0, buildLocator_1.buildLocator)(page, result);
+    return ({ page, envData }) => (0, buildLocator_1.buildLocator)(page, result, envData);
 }
 //# sourceMappingURL=assertCache.js.map

package/dist/esm/lib/ai/locate/buildLocator.d.ts

@@ -4,6 +4,10 @@ import type { LocateResult } from './locateTypes';
  * Mechanically construct a Playwright {@link Locator} from a structured
  * {@link LocateResult}. No `eval` or string parsing — every branch maps to a
  * direct Playwright API call.
+ *
+ * When `envData` is supplied, `{{$.env.X}}` placeholders inside `text`,
+ * `name`, and `testId` step fields are resolved against it before being
+ * applied. `selector` and `frames[]` are left untouched.
  */
-export declare function buildLocator(page: Page, result: LocateResult): Locator;
+export declare function buildLocator(page: Page, result: LocateResult, envData?: Record<string, string>): Locator;
 //# sourceMappingURL=buildLocator.d.ts.map

package/dist/esm/lib/ai/locate/buildLocator.js

@@ -1,12 +1,54 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildLocator = buildLocator;
+const TemplateInterpolator_1 = require("../../../utils/TemplateInterpolator");
+/**
+ * Resolves any `{{$.env.X}}` placeholders in a step field against the
+ * supplied env data. Returns the input verbatim when no env data is given,
+ * or when the field has no placeholder syntax — backwards compatible with
+ * cached entries that contain literal values only.
+ *
+ * Only applied to `text`, `name`, and `testId` step fields. `selector`
+ * (CSS/XPath) and `frames[]` entries are left literal because raw env
+ * values cannot be safely embedded into a CSS selector without escaping.
+ */
+function resolveStepField(value, envData) {
+    if (!envData || !value.includes('{{')) {
+        return value;
+    }
+    return (0, TemplateInterpolator_1.interpolateString)(value, { env: envData, calls: [] });
+}
+/**
+ * Interpolate env placeholders, then optionally compile the result as a
+ * regex. Mirrors the order used by `buildAssertExecutor` so env-var × regex
+ * semantics stay consistent across cache executors.
+ *
+ * On `new RegExp(...)` failure (invalid pattern) the original string is
+ * returned, letting Playwright apply literal substring matching rather than
+ * throwing inside the cache replay path.
+ */
+function resolveAndCompile(value, isRegex, envData) {
+    const resolved = resolveStepField(value, envData);
+    if (!isRegex) {
+        return resolved;
+    }
+    try {
+        return new RegExp(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
 /**
  * Mechanically construct a Playwright {@link Locator} from a structured
  * {@link LocateResult}. No `eval` or string parsing — every branch maps to a
  * direct Playwright API call.
+ *
+ * When `envData` is supplied, `{{$.env.X}}` placeholders inside `text`,
+ * `name`, and `testId` step fields are resolved against it before being
+ * applied. `selector` and `frames[]` are left untouched.
  */
-function buildLocator(page, result) {
+function buildLocator(page, result, envData) {
     // 1. Resolve frame chain (if any)
     let frameScope;
     if (result.frames && result.frames.length > 0) {
@@ -16,9 +58,9 @@ function buildLocator(page, result) {
     }
     // 2. Apply locator steps
     const base = frameScope ?? page;
-    let locator = applyStep(base, result.steps[0]);
+    let locator = applyStep(base, result.steps[0], envData);
     for (let i = 1; i < result.steps.length; i++) {
-        locator = applyStepToLocator(locator, result.steps[i]);
+        locator = applyStepToLocator(locator, result.steps[i], envData);
     }
     // 3. nth disambiguation
     if (result.nth !== undefined) {
@@ -39,34 +81,41 @@ function applyFrameStep(parent, step) {
             throw new Error(`Unknown frame method: ${step.method}`);
     }
 }
-function applyStep(base, step) {
-    return applyStepTo(base, step);
+function applyStep(base, step, envData) {
+    return applyStepTo(base, step, envData);
 }
-function applyStepToLocator(parent, step) {
-    return applyStepTo(parent, step);
+function applyStepToLocator(parent, step, envData) {
+    return applyStepTo(parent, step, envData);
 }
-function applyStepTo(parent, step) {
+function applyStepTo(parent, step, envData) {
+    // `exact` and `*IsRegex` are mutually exclusive. If the AI emits both
+    // (shouldn't happen — the prompt forbids it), regex wins because passing
+    // `exact: true` with a `RegExp` matcher to Playwright is meaningless.
     const exactOpt = step.exact !== undefined ? { exact: step.exact } : undefined;
     switch (step.method) {
         case 'getByRole': {
             const roleOpts = {};
             if (step.name !== undefined) {
-                roleOpts.name = step.name;
+                roleOpts.name = resolveAndCompile(step.name, step.nameIsRegex, envData);
             }
-            if (step.exact !== undefined) {
+            if (step.exact !== undefined && !step.nameIsRegex) {
                 roleOpts.exact = step.exact;
             }
             return parent.getByRole((step.role ?? 'generic'), Object.keys(roleOpts).length > 0 ? roleOpts : undefined);
         }
         case 'getByText':
-            return parent.getByText(step.text ?? '', exactOpt);
+            return parent.getByText(resolveAndCompile(step.text ?? '', step.textIsRegex, envData), step.textIsRegex ? undefined : exactOpt);
         case 'getByLabel':
-            return parent.getByLabel(step.text ?? '', exactOpt);
+            return parent.getByLabel(resolveAndCompile(step.text ?? '', step.textIsRegex, envData), step.textIsRegex ? undefined : exactOpt);
         case 'getByPlaceholder':
-            return parent.getByPlaceholder(step.text ?? '', exactOpt);
+            return parent.getByPlaceholder(resolveAndCompile(step.text ?? '', step.textIsRegex, envData), step.textIsRegex ? undefined : exactOpt);
         case 'getByTestId':
-            return parent.getByTestId(step.testId ?? '');
+            return parent.getByTestId(resolveStepField(step.testId ?? '', envData));
         case 'locator':
+            // `selector` is a raw CSS/XPath string — interpolating env values into
+            // it can produce invalid syntax silently. The locate prompt steers the
+            // AI toward semantic locators when env values are involved; cached
+            // selectors stay literal.
             return parent.locator(step.selector ?? '*');
         default:
             throw new Error(`Unknown locator method: ${step.method}`);

package/dist/esm/lib/ai/locate/locateElement.d.ts

@@ -17,6 +17,7 @@ import type { LocateResult } from './locateTypes';
  */
 export declare function locateElement(page: Page, description: string, gptClient: GptClient, options?: {
     signal?: AbortSignal;
+    envData?: Record<string, string>;
 }): Promise<{
     locator: Locator;
     result: LocateResult;

package/dist/esm/lib/ai/locate/locateElement.js

@@ -4,6 +4,7 @@ exports.locateElement = locateElement;
 const v4_1 = require("zod/v4");
 const Logger_1 = require("../../../utils/Logger");
 const PlaywrightUtils_1 = require("../../../utils/PlaywrightUtils");
+const TemplateInterpolator_1 = require("../../../utils/TemplateInterpolator");
 const buildLocator_1 = require("./buildLocator");
 const domSnapshot_1 = require("./domSnapshot");
 const LocateException_1 = require("./LocateException");
@@ -27,14 +28,15 @@ const SNIPPET_MAX_CHARS = 200;
  * callers can cache the result for deterministic replay.
  */
 async function locateElement(page, description, gptClient, options) {
+    const envData = options?.envData;
     const screenshot = await PlaywrightUtils_1.PlaywrightUtils.takeViewportScreenshot(page);
     const domSnapshot = await (0, domSnapshot_1.captureDomSnapshot)(page);
     Logger_1.appLogger.debug(`locate: DOM snapshot captured (${domSnapshot.html.length} chars, ${domSnapshot.omittedCount} nodes omitted)`);
-    const systemMessage = buildSystemMessage(page.url(), await page.title());
+    const systemMessage = buildSystemMessage(page.url(), await page.title(), description, envData);
     const userMessage = buildUserMessage(description, screenshot, domSnapshot.html);
     // First attempt
     const firstResult = await callLlm(gptClient, systemMessage, userMessage, options?.signal);
-    const firstLocator = (0, buildLocator_1.buildLocator)(page, firstResult);
+    const firstLocator = (0, buildLocator_1.buildLocator)(page, firstResult, envData);
     const firstCount = await safeCount(firstLocator);
     Logger_1.appLogger.debug(`locate: first attempt matched ${firstCount} element(s)`);
     if (firstCount === 1) {
@@ -42,7 +44,7 @@ async function locateElement(page, description, gptClient, options) {
     }
     // Disambiguation: small number of matches — show snippets and let LLM pick
     if (firstCount > 1 && firstCount <= DISAMBIGUATE_THRESHOLD) {
-        return await disambiguate(page, description, gptClient, firstLocator, firstResult, firstCount, options?.signal);
+        return await disambiguate(page, description, gptClient, firstLocator, firstResult, firstCount, envData, options?.signal);
     }
     // Retry: zero matches or too many
     const previousAttempt = summarizeLocateResult(firstResult);
@@ -58,14 +60,14 @@ async function locateElement(page, description, gptClient, options) {
         : `Your locator matched ${firstCount} elements, which is too many to disambiguate. Your previous attempt was: ${previousAttempt}. Write a more specific locator.`;
     const retryMessage = buildRetryMessage(description, feedback, screenshot, retryDomHtml);
     const retryResult = await callLlm(gptClient, systemMessage, retryMessage, options?.signal);
-    const retryLocator = (0, buildLocator_1.buildLocator)(page, retryResult);
+    const retryLocator = (0, buildLocator_1.buildLocator)(page, retryResult, envData);
     const retryCount = await safeCount(retryLocator);
     Logger_1.appLogger.debug(`locate: retry matched ${retryCount} element(s)`);
     if (retryCount === 1) {
         return { locator: retryLocator, result: retryResult };
     }
     if (retryCount > 1 && retryCount <= DISAMBIGUATE_THRESHOLD) {
-        return await disambiguate(page, description, gptClient, retryLocator, retryResult, retryCount, options?.signal);
+        return await disambiguate(page, description, gptClient, retryLocator, retryResult, retryCount, envData, options?.signal);
     }
     // Give up
     const reason = retryCount === 0 ? 'no_matches' : 'too_many_matches';
@@ -77,7 +79,7 @@ async function locateElement(page, description, gptClient, options) {
  * Show HTML snippets of each match to the LLM and ask it to pick the
  * correct one. Returns the original locator with `.nth(n)` appended.
  */
-async function disambiguate(page, description, gptClient, locator, locateResult, count, signal) {
+async function disambiguate(page, description, gptClient, locator, locateResult, count, envData, signal) {
     const snippets = [];
     for (let i = 0; i < count; i++) {
         const nth = locator.nth(i);
@@ -111,6 +113,12 @@ async function disambiguate(page, description, gptClient, locator, locateResult,
             .max(count - 1)
             .describe('Zero-based index of the element that best matches the description.'),
     });
+    // Disambiguation output is just an index — never cached and never fed back
+    // through `buildLocator`. Show the LLM the resolved description so it can
+    // match candidate HTML directly without doing mental env-var substitution.
+    const resolvedDescription = envData && description.includes('{{')
+        ? (0, TemplateInterpolator_1.interpolateString)(description, { env: envData, calls: [] })
+        : description;
     const systemMsg = {
         type: 'system',
         text: `You are resolving an ambiguous element lookup. The user described an element and your locator matched ${count} candidates. Choose the one that best matches the description.`,
@@ -120,7 +128,7 @@ async function disambiguate(page, description, gptClient, locator, locateResult,
         items: [
             {
                 type: 'text',
-                text: `Description: "${description}"\n\nCandidates:\n${snippetText}\n\nReturn the index of the best match.`,
+                text: `Description: "${resolvedDescription}"\n\nCandidates:\n${snippetText}\n\nReturn the index of the best match.`,
             },
         ],
     };
@@ -131,7 +139,7 @@ async function disambiguate(page, description, gptClient, locator, locateResult,
         nth: resp.output.index,
     };
     return {
-        locator: (0, buildLocator_1.buildLocator)(page, disambiguatedResult),
+        locator: (0, buildLocator_1.buildLocator)(page, disambiguatedResult, envData),
         result: disambiguatedResult,
     };
 }
@@ -139,7 +147,54 @@ async function callLlm(gptClient, systemMessage, userMessage, signal) {
     const resp = await gptClient.getStructuredOutput([systemMessage, userMessage], locateSchema_1.LocateResultSchema, { signal });
     return resp.output;
 }
-function buildSystemMessage(pageUrl, pageTitle) {
+function buildSystemMessage(pageUrl, pageTitle, description, envData) {
+    // Only annotate the prompt with env-var guidance when the raw description
+    // actually references at least one provided env var. Keeps the prompt small
+    // for the common case.
+    const envEntries = Object.entries(envData ?? {});
+    const referencedEnvEntries = envEntries.filter(([name]) => description.includes(`{{$.env.${name}}}`));
+    const envBlock = referencedEnvEntries.length > 0
+        ? `
+
+The user's description contains environment variable references using the syntax
+\`{{$.env.NAME}}\`. To keep cached locators valid across runs with different env
+values, you MUST emit those same placeholders in any LocatorStep \`text\`,
+\`name\`, or \`testId\` field whose contents come from an env var. Do NOT bake
+the literal current value into the step.
+
+Original (uninterpolated) description: "${description}"
+
+Current env mapping (use these to identify which substrings on the page came
+from which env var, then emit the placeholder rather than the literal):
+${referencedEnvEntries.map(([name, value]) => `  - {{$.env.${name}}} = ${JSON.stringify(value)}`).join('\n')}
+
+Hard rules for env-var emission:
+- Use placeholders ONLY in \`text\`, \`name\`, or \`testId\` fields.
+- NEVER emit \`{{$.env.*}}\` inside \`selector\` (CSS/XPath) — interpolating
+  raw values into a CSS selector can produce invalid syntax. Use a semantic
+  locator (getByRole/getByText/getByLabel/getByPlaceholder/getByTestId)
+  instead when an env-derived value is involved.
+- NEVER emit \`{{$.env.*}}\` inside any \`frames[]\` entry (iframe selectors
+  or iframe \`name\` attributes are not env-driven).
+
+Examples:
+- Description "The user row for {{$.env.TEST_EMAIL}}", TEST_EMAIL="alice@x.com",
+  page text shows "alice@x.com" →
+    [{ method: "getByText", text: "{{$.env.TEST_EMAIL}}" }]
+- Description "The {{$.env.PROJECT_NAME}} tab", PROJECT_NAME="Apollo" →
+    [{ method: "getByRole", role: "tab", name: "{{$.env.PROJECT_NAME}}" }]
+- Description "The submit button" (no env vars referenced) → emit literal text
+  as you normally would.
+
+Combining env vars with regex: env interpolation runs BEFORE regex compilation,
+so you can mix them. Prefer this when the env value should be matched alongside
+dynamic page content. Example — description "The row for {{$.env.USER}} with
+their score", USER="alice" →
+    [{ method: "getByText", text: "alice — \\\\d+ pts", textIsRegex: true }]
+  (Here the AI substituted the env value because it's part of a regex pattern;
+  the placeholder syntax also works — \`text: "{{$.env.USER}} — \\\\d+ pts"\` —
+  and is preferred when you want cache stability across env value changes.)`
+        : '';
     return {
         type: 'system',
         text: `You are a Playwright locator expert. Given a viewport screenshot and a pruned DOM snapshot of a webpage, return a structured locator that targets the element matching the user's description.
@@ -151,8 +206,50 @@ Rules:
 - If the element is inside an iframe, specify the frame(s) in the "frames" field.
 - Do NOT set "nth" unless you are certain the chain matches multiple elements and you know which index is correct. When unsure, omit it — the system will handle disambiguation.
 
+Stability rules — locators are CACHED and replayed across runs. The page may
+change between runs (vote counts increment, "3 hours ago" becomes "5 hours ago",
+new posts shift positions, prices fluctuate). Choose locators that survive these
+drifts:
+
+- POSITIONAL DESCRIPTIONS: when the description references position ("first",
+  "third", "fourth from the top", "last"), translate that into a structural
+  chain plus \`nth\` rather than baking position-specific page text into a step.
+  Example — "the fourth comments link" should be a locator over ALL comment
+  links with \`nth: 3\`, not the literal "36 comments" you happen to see today.
+
+- DYNAMIC TEXT: if the value you would put into \`name\` or \`text\` looks
+  dynamic — contains digits, timestamps, "X ago", "$X.XX", counts, scores,
+  vote totals — emit a regex pattern via \`nameIsRegex: true\` (for getByRole)
+  or \`textIsRegex: true\` (for getByText/getByLabel/getByPlaceholder) instead
+  of the literal value. Anchor the pattern with \`^\` / \`$\` when the whole
+  string should match, otherwise it acts as a substring match.
+
+- DO NOT combine \`exact: true\` with \`nameIsRegex\`/\`textIsRegex\`. They are
+  mutually exclusive — set \`exact\` only for literal-string steps with stable
+  fixed labels like "Submit" or "Sign In".
+
+- SAFE LITERALS: keep literal values for genuinely stable strings — fixed UI
+  labels, button text like "Submit"/"Cancel", section headings, unique
+  test-ids. Only escape to regex when stability is at risk.
+
+Examples:
+- "The fourth comments link" →
+    steps: [{ method: "getByRole", role: "link", name: "\\\\d+\\\\s+comments?$", nameIsRegex: true }]
+    nth: 3
+- "The headline of the third story" → structural row selector + nth: 2 (literal name)
+- "The submit button" → literal name: "Submit", optionally exact: true
+- "The price tag for the cart total" →
+    steps: [{ method: "getByText", text: "\\\\$\\\\d+(\\\\.\\\\d+)?", textIsRegex: true }]
+- "The 'posted 5 hours ago' label" →
+    steps: [{ method: "getByText", text: "posted \\\\d+ (minute|hour|day)s? ago", textIsRegex: true }]
+
+Regex format: emit a JS-style regex source string (no leading/trailing slash,
+no flags). Backslashes inside JSON must be doubled (\`\\\\d+\` not \`\\d+\`).
+Invalid patterns silently fall back to literal matching, so prefer simple,
+well-tested patterns.
+
 Page URL: ${pageUrl}
-Page title: ${pageTitle}`,
+Page title: ${pageTitle}${envBlock}`,
     };
 }
 function buildUserMessage(description, screenshot, domHtml) {

package/dist/esm/lib/ai/locate/locateSchema.d.ts

@@ -27,6 +27,8 @@ export declare const LocateResultSchema: z.ZodObject<{
         testId: z.ZodOptional<z.ZodString>;
         selector: z.ZodOptional<z.ZodString>;
         exact: z.ZodOptional<z.ZodBoolean>;
+        nameIsRegex: z.ZodOptional<z.ZodBoolean>;
+        textIsRegex: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     nth: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;

package/dist/esm/lib/ai/locate/locateSchema.js

@@ -46,7 +46,15 @@ const LocatorStepSchema = v4_1.z
     exact: v4_1.z
         .boolean()
         .optional()
-        .describe('Whether text/name matching should be exact. Applies to getByRole (name), getByText, getByLabel, getByPlaceholder.'),
+        .describe('Whether text/name matching should be exact. Applies to getByRole (name), getByText, getByLabel, getByPlaceholder. Mutually exclusive with nameIsRegex / textIsRegex.'),
+    nameIsRegex: v4_1.z
+        .boolean()
+        .optional()
+        .describe('Set true when "name" is a regex pattern (compiled via new RegExp(name)). Use this for dynamic accessible names — e.g. "\\d+ comments" matches any "N comments" link. Used with getByRole. Do not combine with exact:true.'),
+    textIsRegex: v4_1.z
+        .boolean()
+        .optional()
+        .describe('Set true when "text" is a regex pattern (compiled via new RegExp(text)). Use this for dynamic page text — counts, dates, prices, "X ago" timestamps. Used with getByText / getByLabel / getByPlaceholder. Do not combine with exact:true.'),
 })
     .describe('A single Playwright locator step.');
 const FrameStepSchema = v4_1.z

package/dist/esm/lib/ai/locate/locateTypes.d.ts

@@ -20,6 +20,24 @@ export type LocatorStep = {
     selector?: string;
     /** Whether text/name matching should be exact. */
     exact?: boolean;
+    /**
+     * When true, `name` is treated as a regex pattern compiled via
+     * `new RegExp(name)` rather than a literal string. Mutually exclusive
+     * with `exact: true`. Used with `getByRole`.
+     *
+     * Env-var placeholders are interpolated **before** regex compilation, so
+     * `'\\d+ {{$.env.NOUN}}'` with `NOUN='comments'` compiles as
+     * `/\d+ comments/`.
+     */
+    nameIsRegex?: boolean;
+    /**
+     * When true, `text` is treated as a regex pattern compiled via
+     * `new RegExp(text)` rather than a literal string. Mutually exclusive with
+     * `exact: true`. Used with `getByText`, `getByLabel`, `getByPlaceholder`.
+     *
+     * Env-var placeholders are interpolated **before** regex compilation.
+     */
+    textIsRegex?: boolean;
 };
 /**
  * Identifies an iframe to scope into before applying {@link LocatorStep}s.
@@ -49,9 +67,48 @@ export type LocateResult = {
  */
 export type LocateOptions = {
     gptClient?: GptClient | Exclude<LanguageModel, string>;
-    /** Timeout in milliseconds for the entire locate operation (default: 30 000). */
+    /**
+     * Timeout in milliseconds for the entire locate operation (default: 30 000).
+     *
+     * On cache hit this budgets the hydration patience window — the cached
+     * locator gets up to this long to attach to a matching element before the
+     * cache is treated as stale and the AI is re-run. On cache miss (or
+     * stale-cache fallthrough) this budgets the AI call. Whatever the cache
+     * path consumes is deducted from the AI path's remaining budget; the total
+     * never exceeds `timeout`.
+     */
     timeout?: number;
-    /** Whether to use the on-disk cache. Defaults to true. */
+    /**
+     * Whether to use the on-disk cache. Defaults to true.
+     *
+     * Cached `LocateResult` step fields preserve `{{$.env.*}}` placeholders for
+     * any value that came from an env var, so changing an env value between
+     * runs replays the same cached locator with the new value rather than
+     * re-invoking the AI.
+     */
     cache?: boolean;
+    /**
+     * Explicit environment variable names (in addition to the heuristically
+     * derived ones) that the description may read via `{{$.env.*}}`
+     * interpolations.
+     */
+    envVars?: string[];
+    /**
+     * Explicitly supply environment variable values that amend (or override)
+     * the environment observed by this `page.ai.locate` call. Keys are merged
+     * with any names derived from {@link LocateOptions.envVars} and from
+     * `{{$.env.*}}` interpolations in the description.
+     *
+     * - A `string` value sets or overrides the variable for this invocation.
+     * - An `undefined` value *removes* the variable, even if it would
+     *   otherwise be resolved from persistence.
+     *
+     * Only the **names** (keys) influence cache lookup; changing a value
+     * replays the cached locator with the new value via `{{$.env.*}}`
+     * placeholder substitution rather than busting the cache. If a referenced
+     * env var is absent at replay, the placeholder is left literal — the
+     * locator will then match zero elements and fail loudly.
+     */
+    envVals?: Record<string, string | undefined>;
 };
 //# sourceMappingURL=locateTypes.d.ts.map

package/dist/esm/lib/page/DonobuExtendedPage.d.ts

@@ -40,8 +40,32 @@ export type AssertOptions = {
      * and generates equivalent Playwright code which is cached. Subsequent
      * runs execute the cached code directly, skipping the AI call entirely.
      * Defaults to `true`.
+     *
+     * Cached steps preserve `{{$.env.*}}` placeholders for any value that came
+     * from an env var, so changing an env value between runs replays the same
+     * cached steps with the new value rather than re-invoking the AI.
      */
     cache?: boolean;
+    /**
+     * Explicit environment variable names (in addition to the heuristically
+     * derived ones) that the assertion may read via `{{$.env.*}}` interpolations.
+     */
+    envVars?: string[];
+    /**
+     * Explicitly supply environment variable values that amend (or override)
+     * the environment observed by this `page.ai.assert` call. Keys are merged
+     * with any names derived from {@link AssertOptions.envVars} and from
+     * `{{$.env.*}}` interpolations in the assertion text.
+     *
+     * - A `string` value sets or overrides the variable for this invocation.
+     * - An `undefined` value *removes* the variable, even if it would
+     *   otherwise be resolved from persistence.
+     *
+     * Only the **names** (keys) influence cache lookup; changing a value
+     * replays the cached steps with the new value via `{{$.env.*}}` placeholder
+     * substitution rather than busting the cache.
+     */
+    envVals?: Record<string, string | undefined>;
 };
 type PageAiAct = {
     <Schema extends z.ZodObject>(instruction: string, options?: PageAiActWithSchemaOptions<Schema>): Promise<z.infer<Schema>>;