donobu 5.34.0 → 5.35.0

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

@@ -92,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

@@ -172,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/extendPage.js

@@ -408,33 +408,86 @@ Use this information to return an appropriate JSON object.`,
             const useCache = options?.cache !== false;
             const clearCache = sharedState.runtimeDirectives?.clearPageAiCache ?? false;
             const pageUrl = (0, cacheLocator_1.extractCacheKeyHostname)(page.url());
-            // --- Cache lookup (when enabled and not clearing) ---
-            if (useCache && !clearCache) {
-                const cache = getOrInitPageAiCache();
-                const cached = await cache.getLocate({ pageUrl, description });
-                if (cached) {
-                    Logger_1.appLogger.debug(`Locate cache HIT for: "${description}" — rebuilding locator from cache`);
-                    return cached.run({ page });
+            // Distill env var names referenced by the description plus any
+            // explicitly provided names/overrides. Resolve env data locally — locate
+            // does not flow through `runTool`, so we don't mutate sharedState here.
+            const envVarNames = (0, DonobuFlowsManager_1.distillAllowedEnvVariableNames)(description, [
+                ...(options?.envVars ?? []),
+                ...Object.keys(options?.envVals ?? {}),
+            ]);
+            const hasEnvRefs = envVarNames.length > 0;
+            const resolveEnvData = async () => {
+                if (!hasEnvRefs) {
+                    return undefined;
                 }
-            }
-            // --- Cache invalidation (when clearing) ---
-            if (useCache && clearCache) {
-                const cache = getOrInitPageAiCache();
-                await cache.deleteLocate({ pageUrl, description });
-                Logger_1.appLogger.debug(`Locate cache invalidated for: "${description}"`);
-            }
-            // --- Cache miss or cache disabled: run AI locate ---
-            const gptClient = getGptClient(page, options?.gptClient);
-            if (!gptClient) {
-                throw new ToolRequiresGptException_1.ToolRequiresGptException('locate');
-            }
+                const envData = await sharedState.donobuStack.envDataManager.getByNames(envVarNames);
+                if (options?.envVals) {
+                    for (const [k, v] of Object.entries(options.envVals)) {
+                        if (v === undefined) {
+                            delete envData[k];
+                        }
+                        else {
+                            envData[k] = v;
+                        }
+                    }
+                }
+                return envData;
+            };
+            // The user-supplied `timeout` (default 30s) is the budget for the
+            // ENTIRE locate operation — cache-hit hydration wait + AI fallback.
+            // We start the abort timer here so the cache path's `waitFor` and the
+            // AI path share one bounded clock.
             const timeoutMillis = options?.timeout ?? 30_000;
+            const startedAt = Date.now();
             const abortController = new AbortController();
             const timeoutId = setTimeout(() => {
                 abortController.abort(`Locate operation timed out after ${timeoutMillis} milliseconds`);
             }, timeoutMillis);
             try {
-                const { locator, result } = await (0, locateElement_1.locateElement)(page, description, gptClient, { signal: abortController.signal });
+                // --- Cache lookup (when enabled and not clearing) ---
+                if (useCache && !clearCache) {
+                    const cache = getOrInitPageAiCache();
+                    const cached = await cache.getLocate({ pageUrl, description });
+                    if (cached) {
+                        const envData = await resolveEnvData();
+                        const candidate = cached.run({ page, envData });
+                        // Cache replay can outrun page hydration — the no-cache path
+                        // gets an implicit hydration window from the AI round-trip
+                        // latency, but a cache hit fires immediately and may see a
+                        // partially-mounted DOM. Wait (within the operation's overall
+                        // budget) for the locator to attach before validating.
+                        const remaining = Math.max(timeoutMillis - (Date.now() - startedAt), 100);
+                        try {
+                            await candidate.first().waitFor({
+                                state: 'attached',
+                                timeout: remaining,
+                            });
+                            Logger_1.appLogger.debug(`Locate cache HIT for: "${description}" — rebuilt locator from cache`);
+                            return candidate;
+                        }
+                        catch {
+                            // Locator did not attach within the patience window. Either
+                            // the page has drifted or the cache is genuinely stale.
+                            // Invalidate and fall through to the AI path; the AI call
+                            // gets whatever budget remains on the abort timer.
+                            Logger_1.appLogger.debug(`Locate cache STALE for "${description}" (no match within ${remaining}ms) — re-running AI`);
+                            await cache.deleteLocate({ pageUrl, description });
+                        }
+                    }
+                }
+                // --- Cache invalidation (when clearing) ---
+                if (useCache && clearCache) {
+                    const cache = getOrInitPageAiCache();
+                    await cache.deleteLocate({ pageUrl, description });
+                    Logger_1.appLogger.debug(`Locate cache invalidated for: "${description}"`);
+                }
+                // --- Cache miss / cache disabled / stale-cache fallthrough: run AI ---
+                const gptClient = getGptClient(page, options?.gptClient);
+                if (!gptClient) {
+                    throw new ToolRequiresGptException_1.ToolRequiresGptException('locate');
+                }
+                const envData = await resolveEnvData();
+                const { locator, result } = await (0, locateElement_1.locateElement)(page, description, gptClient, { signal: abortController.signal, envData });
                 // --- Cache the result for future runs ---
                 if (useCache) {
                     try {

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

@@ -92,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/lib/ai/cache/assertCache.js

@@ -172,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/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/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/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/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/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/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/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/lib/page/extendPage.js

@@ -408,33 +408,86 @@ Use this information to return an appropriate JSON object.`,
             const useCache = options?.cache !== false;
             const clearCache = sharedState.runtimeDirectives?.clearPageAiCache ?? false;
             const pageUrl = (0, cacheLocator_1.extractCacheKeyHostname)(page.url());
-            // --- Cache lookup (when enabled and not clearing) ---
-            if (useCache && !clearCache) {
-                const cache = getOrInitPageAiCache();
-                const cached = await cache.getLocate({ pageUrl, description });
-                if (cached) {
-                    Logger_1.appLogger.debug(`Locate cache HIT for: "${description}" — rebuilding locator from cache`);
-                    return cached.run({ page });
+            // Distill env var names referenced by the description plus any
+            // explicitly provided names/overrides. Resolve env data locally — locate
+            // does not flow through `runTool`, so we don't mutate sharedState here.
+            const envVarNames = (0, DonobuFlowsManager_1.distillAllowedEnvVariableNames)(description, [
+                ...(options?.envVars ?? []),
+                ...Object.keys(options?.envVals ?? {}),
+            ]);
+            const hasEnvRefs = envVarNames.length > 0;
+            const resolveEnvData = async () => {
+                if (!hasEnvRefs) {
+                    return undefined;
                 }
-            }
-            // --- Cache invalidation (when clearing) ---
-            if (useCache && clearCache) {
-                const cache = getOrInitPageAiCache();
-                await cache.deleteLocate({ pageUrl, description });
-                Logger_1.appLogger.debug(`Locate cache invalidated for: "${description}"`);
-            }
-            // --- Cache miss or cache disabled: run AI locate ---
-            const gptClient = getGptClient(page, options?.gptClient);
-            if (!gptClient) {
-                throw new ToolRequiresGptException_1.ToolRequiresGptException('locate');
-            }
+                const envData = await sharedState.donobuStack.envDataManager.getByNames(envVarNames);
+                if (options?.envVals) {
+                    for (const [k, v] of Object.entries(options.envVals)) {
+                        if (v === undefined) {
+                            delete envData[k];
+                        }
+                        else {
+                            envData[k] = v;
+                        }
+                    }
+                }
+                return envData;
+            };
+            // The user-supplied `timeout` (default 30s) is the budget for the
+            // ENTIRE locate operation — cache-hit hydration wait + AI fallback.
+            // We start the abort timer here so the cache path's `waitFor` and the
+            // AI path share one bounded clock.
             const timeoutMillis = options?.timeout ?? 30_000;
+            const startedAt = Date.now();
             const abortController = new AbortController();
             const timeoutId = setTimeout(() => {
                 abortController.abort(`Locate operation timed out after ${timeoutMillis} milliseconds`);
             }, timeoutMillis);
             try {
-                const { locator, result } = await (0, locateElement_1.locateElement)(page, description, gptClient, { signal: abortController.signal });
+                // --- Cache lookup (when enabled and not clearing) ---
+                if (useCache && !clearCache) {
+                    const cache = getOrInitPageAiCache();
+                    const cached = await cache.getLocate({ pageUrl, description });
+                    if (cached) {
+                        const envData = await resolveEnvData();
+                        const candidate = cached.run({ page, envData });
+                        // Cache replay can outrun page hydration — the no-cache path
+                        // gets an implicit hydration window from the AI round-trip
+                        // latency, but a cache hit fires immediately and may see a
+                        // partially-mounted DOM. Wait (within the operation's overall
+                        // budget) for the locator to attach before validating.
+                        const remaining = Math.max(timeoutMillis - (Date.now() - startedAt), 100);
+                        try {
+                            await candidate.first().waitFor({
+                                state: 'attached',
+                                timeout: remaining,
+                            });
+                            Logger_1.appLogger.debug(`Locate cache HIT for: "${description}" — rebuilt locator from cache`);
+                            return candidate;
+                        }
+                        catch {
+                            // Locator did not attach within the patience window. Either
+                            // the page has drifted or the cache is genuinely stale.
+                            // Invalidate and fall through to the AI path; the AI call
+                            // gets whatever budget remains on the abort timer.
+                            Logger_1.appLogger.debug(`Locate cache STALE for "${description}" (no match within ${remaining}ms) — re-running AI`);
+                            await cache.deleteLocate({ pageUrl, description });
+                        }
+                    }
+                }
+                // --- Cache invalidation (when clearing) ---
+                if (useCache && clearCache) {
+                    const cache = getOrInitPageAiCache();
+                    await cache.deleteLocate({ pageUrl, description });
+                    Logger_1.appLogger.debug(`Locate cache invalidated for: "${description}"`);
+                }
+                // --- Cache miss / cache disabled / stale-cache fallthrough: run AI ---
+                const gptClient = getGptClient(page, options?.gptClient);
+                if (!gptClient) {
+                    throw new ToolRequiresGptException_1.ToolRequiresGptException('locate');
+                }
+                const envData = await resolveEnvData();
+                const { locator, result } = await (0, locateElement_1.locateElement)(page, description, gptClient, { signal: abortController.signal, envData });
                 // --- Cache the result for future runs ---
                 if (useCache) {
                     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "donobu",
-  "version": "5.34.0",
+  "version": "5.35.0",
   "description": "Create browser automations with an LLM agent and replay them as Playwright scripts.",
   "main": "dist/main.js",
   "module": "dist/esm/main.js",