@pcamarajr/scout 0.13.0 → 0.15.0

package/dist/runner/browser.js

@@ -1,6 +1,12 @@
 import path from "node:path";
-import { chromium } from "playwright";
+import { chromium, selectors } from "playwright";
+import { resolveDeviceOptions } from "../device.js";
+import { assembleTarget, buildLadderCandidates, runWithFallback } from "./selector-ladder.js";
 import { findConsoleErrors, globToRegex, matchNetwork, } from "./network-match.js";
+/** Default testid attribute, when `scout.config.json` sets none. */
+export const DEFAULT_TESTID_ATTR = "data-testid";
+/** How many ancestors a click may borrow a testid from (self is checked first). */
+const TESTID_ANCESTOR_HOPS = 2;
 /**
  * Builds an init-script that denies the permissions that would otherwise pop a
  * native prompt (geolocation, notifications, camera, microphone), stubbing the
@@ -88,6 +94,84 @@ export function demoCursorStub() {
     };
   })();`;
 }
+/**
+ * Pool of shared Chromium Browser processes, keyed by the launch-time options
+ * that cannot be changed per-context: `${headless}|${slowMoMs}`. A full
+ * `chromium.launch()` is the expensive part; within one process (the CLI `go`
+ * loop over scenarios/viewports, or the long-lived MCP server across tool
+ * calls) we launch once per key and reuse the process, opening a fresh isolated
+ * BrowserContext per BrowserSession — the context is the isolation boundary.
+ *
+ * slowMo is a launch-time option: the paced demo replay needs its own pooled
+ * browser, and both demo attempts (paced + fallback share the same slowMo=0 for
+ * the fallback / the paced value for the first) plus subsequent scenarios reuse
+ * whichever they key into.
+ *
+ * The map stores the launch PROMISE (not the resolved Browser) so two
+ * concurrent launch() calls with the same key share one launch instead of
+ * racing into two Chromium processes.
+ */
+const browserPool = new Map();
+function poolKey(headless, slowMoMs) {
+    return `${headless}|${slowMoMs ?? 0}`;
+}
+/**
+ * Returns a shared Browser for the given launch options, launching one on first
+ * use and reusing it thereafter. If a pooled browser has since disconnected
+ * (crash, or an external close), its entry is dropped and a fresh browser is
+ * launched.
+ */
+async function acquireBrowser(headless, slowMoMs) {
+    const key = poolKey(headless, slowMoMs);
+    // Reuse a live pooled entry; drop a stale/failed one and launch a fresh
+    // browser. The map is only ever written synchronously (no await between the
+    // decision to claim `key` and the set below), so two concurrent callers that
+    // both find the same stale entry can't both launch: the first to resume
+    // claims the key, the second re-reads the map and awaits that fresh launch.
+    for (;;) {
+        const existing = browserPool.get(key);
+        if (!existing)
+            break;
+        let browser;
+        try {
+            browser = await existing;
+        }
+        catch {
+            browser = undefined; // a prior pooled launch failed — relaunch below
+        }
+        if (browser?.isConnected())
+            return browser;
+        // Stale/failed. Evict by identity: only drop it if it's still the mapped
+        // entry, so we never discard a fresh browser a concurrent caller just
+        // installed under this key. If the map already changed, loop to re-read it.
+        if (browserPool.get(key) === existing) {
+            browserPool.delete(key);
+            break;
+        }
+    }
+    const launched = chromium.launch({ headless, slowMo: slowMoMs });
+    browserPool.set(key, launched);
+    // If the launch itself rejects, don't leave a rejected promise cached — the
+    // next call should get a clean retry. Delete by identity so a rejecting
+    // orphaned launch can't evict a healthy replacement mapped under the same key.
+    launched.catch(() => {
+        if (browserPool.get(key) === launched)
+            browserPool.delete(key);
+    });
+    return launched;
+}
+/**
+ * Closes every pooled Browser process and clears the pool. Call this before a
+ * process that ran scenarios exits (the CLI `go` command, a library consumer
+ * looping runScenario) — otherwise the live browser keeps the Node event loop
+ * alive and the process never exits. Errors are tolerated: a browser that is
+ * already gone is not a failure to close.
+ */
+export async function closeBrowsers() {
+    const pending = Array.from(browserPool.values());
+    browserPool.clear();
+    await Promise.all(pending.map((p) => p.then((b) => b.close()).catch(() => { })));
+}
 const STEP_TIMEOUT = 10_000;
 /**
  * Cap on the "let the page settle" wait of one-shot presence checks. Network
@@ -103,7 +187,6 @@ const CONSOLE_LOG_CAP = 500;
  * Owns ref→element resolution, tracing and screenshots.
  */
 export class BrowserSession {
-    browser;
     context;
     opts;
     videoEpoch;
@@ -121,33 +204,59 @@ export class BrowserSession {
     activePage;
     /** The first page — it owns the recorded video for the whole context. */
     firstPage;
-    constructor(browser, context, page, opts, 
+    /** Testid attribute the selector ladder reads and `getByTestId` matches. */
+    testIdAttr;
+    constructor(context, page, opts, 
     /** Date.now() at video start (context creation); undefined when not recording */
     videoEpoch, refs = new Map()) {
-        this.browser = browser;
         this.context = context;
         this.opts = opts;
         this.videoEpoch = videoEpoch;
         this.refs = refs;
         this.activePage = page;
         this.firstPage = page;
+        this.testIdAttr = opts.testIdAttribute ?? DEFAULT_TESTID_ATTR;
     }
     /** The tab currently under control. Switching tabs reassigns it. */
     get page() {
         return this.activePage;
     }
     static async launch(opts) {
-        const browser = await chromium.launch({ headless: opts.headless, slowMo: opts.slowMoMs });
+        // Align Playwright's global testid attribute with the ladder's, so a
+        // recorded `testId` target resolves via getByTestId to the same attribute
+        // the ladder read at record time. Idempotent; safe to set every launch.
+        const testIdAttr = opts.testIdAttribute ?? DEFAULT_TESTID_ATTR;
+        if (testIdAttr !== DEFAULT_TESTID_ATTR) {
+            try {
+                selectors.setTestIdAttribute(testIdAttr);
+            }
+            catch {
+                // Older Playwright without the setter — getByTestId keeps the default.
+            }
+        }
+        // Reuse a pooled Chromium process (launched once per headless|slowMo key);
+        // isolation is provided by the fresh context created below, not by a new
+        // browser process.
+        const browser = await acquireBrowser(opts.headless, opts.slowMoMs);
         const perm = opts.permissions;
         const vp = opts.viewport;
-        const size = { width: vp.width, height: vp.height };
+        // Device emulation composes OVER the viewport: an explicit device field wins
+        // over the viewport's value; whatever the device doesn't set falls back to
+        // the viewport. This is how a scenario emulates a UA-gated environment (e.g.
+        // an iOS-Safari-only sheet) without changing which viewport it fans out in.
+        const dev = opts.device ? resolveDeviceOptions(opts.device) : undefined;
+        const size = dev?.viewport ?? { width: vp.width, height: vp.height };
+        const deviceScaleFactor = dev?.deviceScaleFactor ?? vp.deviceScaleFactor;
+        const isMobile = dev?.isMobile ?? vp.isMobile;
+        const hasTouch = dev?.hasTouch ?? vp.hasTouch;
+        const userAgent = dev?.userAgent ?? vp.userAgent;
         const context = await browser.newContext({
             locale: opts.locale ?? "pt-BR",
             viewport: size,
-            ...(vp.deviceScaleFactor != null ? { deviceScaleFactor: vp.deviceScaleFactor } : {}),
-            ...(vp.isMobile != null ? { isMobile: vp.isMobile } : {}),
-            ...(vp.hasTouch != null ? { hasTouch: vp.hasTouch } : {}),
-            ...(vp.userAgent != null ? { userAgent: vp.userAgent } : {}),
+            ...(deviceScaleFactor != null ? { deviceScaleFactor } : {}),
+            ...(isMobile != null ? { isMobile } : {}),
+            ...(hasTouch != null ? { hasTouch } : {}),
+            ...(userAgent != null ? { userAgent } : {}),
             storageState: opts.storageState,
             ...(opts.extraHeaders ? { extraHTTPHeaders: opts.extraHeaders } : {}),
             ...(perm?.grant?.length ? { permissions: perm.grant } : {}),
@@ -179,7 +288,7 @@ export class BrowserSession {
         const videoEpoch = opts.recordVideo ? Date.now() : undefined;
         await context.tracing.start({ screenshots: true, snapshots: true, sources: false });
         const page = await context.newPage();
-        const session = new BrowserSession(browser, context, page, opts, videoEpoch);
+        const session = new BrowserSession(context, page, opts, videoEpoch);
         session.trackPage(page); // first page: registered before context.on("page")
         context.on("page", (p) => session.trackPage(p)); // popups/new tabs
         return session;
@@ -316,7 +425,7 @@ export class BrowserSession {
      */
     async snapshot() {
         await this.page.waitForLoadState("domcontentloaded").catch(() => { });
-        const raw = (await this.page.evaluate(snapshotScript));
+        const raw = (await this.page.evaluate(buildSnapshotScript(this.testIdAttr, TESTID_ANCESTOR_HOPS)));
         this.refs.clear();
         for (const el of raw.elements)
             this.refs.set(el.ref, el);
@@ -342,37 +451,146 @@ export class BrowserSession {
     }
     /**
      * Resolves a snapshot ref to a locator AND the durable Target recorded for
-     * replay: role+name when unique on the page, CSS path otherwise.
+     * replay, walking the selector preference ladder (testid → id → role+name →
+     * text → positional CSS) against the live page and recording the most stable
+     * rung that uniquely matches — with the other unique rungs kept as ordered
+     * fallbacks. `action` gates the ancestor-testid rung: a click may borrow a
+     * close ancestor's testid, an input (fill/select) may not (it must act on the
+     * field itself, not a wrapping container).
      */
-    async resolveRef(ref) {
+    async resolveRef(ref, action) {
         const info = this.refs.get(ref);
         if (!info) {
             throw new Error(`Ref [${ref}] unknown — take a new browser_snapshot, the page changed.`);
         }
-        const description = `${info.role} "${info.name}"`;
-        if (info.role && info.name) {
-            const byRole = this.page.getByRole(info.role, {
-                name: info.name,
-                exact: true,
-            });
-            if ((await byRole.count()) === 1) {
-                return { locator: byRole, target: { role: info.role, name: info.name, description } };
+        const ladderInfo = {
+            role: info.role || undefined,
+            name: info.name || undefined,
+            css: info.css,
+            testId: info.testId,
+            ancestorTestId: info.ancestorTestId,
+            id: info.id,
+            text: info.text,
+        };
+        const target = await this.resolveTarget(ladderInfo, { allowAncestorTestId: action === "click" });
+        return { locator: this.targetLocator(target), target };
+    }
+    /**
+     * Walks the selector ladder against the live page: builds the ordered
+     * candidates, keeps those that match EXACTLY one element (so a recorded
+     * selector is never ambiguous), and assembles the primary + fallbacks + the
+     * fragile flag. Shared by ref-based interactions and selector-based clicks.
+     */
+    async resolveTarget(info, opts = {}) {
+        const candidates = buildLadderCandidates(info, {
+            allowAncestorTestId: opts.allowAncestorTestId,
+            testIdAttr: this.testIdAttr,
+        });
+        const unique = [];
+        for (const candidate of candidates) {
+            // A locator for an unsupported ARIA role (a tag used as a role fallback)
+            // may throw; treat any failure to count as "no match".
+            let count = 0;
+            try {
+                count = await this.rawLocator(candidate.target).count();
+            }
+            catch {
+                count = 0;
             }
+            if (count === 1)
+                unique.push(candidate);
         }
-        return { locator: this.page.locator(info.css), target: { css: info.css, description } };
+        return assembleTarget(candidates, unique);
     }
     async click(ref) {
-        const { locator, target } = await this.resolveRef(ref);
+        const { locator, target } = await this.resolveRef(ref, "click");
         await locator.click();
         return target;
     }
+    /**
+     * Clicks an element located directly by data-testid or CSS — no snapshot ref
+     * involved. This is the escape hatch for elements OUTSIDE the accessibility
+     * tree (a gesture layer, an overlay `<div>` with only a data-testid): they
+     * never get a numbered [ref], so ref-based click can't reach them. Returns the
+     * durable Target so the caller records a deterministic `click` step (the same
+     * kind as a ref click — one replay path, testId/css resolved by targetLocator).
+     */
+    async clickSelector(sel) {
+        const base = buildSelectorTarget(sel);
+        // Upgrade the AI-supplied selector through the ladder: read the live
+        // element's signals and record the most stable rung (+ fallbacks). A
+        // role-less overlay with only a positional CSS still bottoms out as fragile,
+        // which is the signal to add a data-testid — surfaced as a warning.
+        const info = await this.ladderInfoFor(base);
+        const target = info
+            ? await this.resolveTarget(info, { allowAncestorTestId: true })
+            : base;
+        await this.targetLocator(target).click();
+        return target;
+    }
+    /**
+     * Reads the selector-ladder signals from the FIRST element the given
+     * testid/css target resolves to, in-page. Returns undefined when the element
+     * isn't found (the click below then fails on the base target, as before).
+     */
+    async ladderInfoFor(target) {
+        const selector = target.testId
+            ? `[${cssAttrEscape(this.testIdAttr)}="${cssValueEscape(target.testId)}"]`
+            : target.css;
+        if (!selector)
+            return undefined;
+        const raw = (await this.page.evaluate(buildExtractScript(selector, this.testIdAttr, TESTID_ANCESTOR_HOPS)));
+        return raw ?? undefined;
+    }
+    /**
+     * Asserts an element's VISUAL/structural state (class token, attribute,
+     * computed style) — the check text/URL assertions can't express. Polls until
+     * every provided condition holds or `timeout` elapses, so it is deterministic
+     * on replay. The canonical use is the opacity toggle: a control kept in the DOM
+     * but hidden with `opacity:0` (which Playwright still reports as "visible", so
+     * assertNotVisible would false-pass) — assert `opacity-0`/computed opacity
+     * instead. The element must at least be attached; a missing element fails.
+     */
+    async assertState(target, checks, timeout = STEP_TIMEOUT) {
+        if (checks.hasClass === undefined &&
+            checks.notHasClass === undefined &&
+            checks.attribute === undefined &&
+            checks.computedStyle === undefined) {
+            throw new Error("assertState needs at least one of hasClass/notHasClass/attribute/computedStyle.");
+        }
+        const locator = this.targetLocator(target);
+        await locator.waitFor({ state: "attached", timeout }).catch(() => {
+            throw new Error(`Element ${target.description} not found within ${timeout}ms.`);
+        });
+        const styleProp = checks.computedStyle?.property ?? null;
+        const deadline = Date.now() + timeout;
+        let lastReason = "";
+        for (;;) {
+            const observed = await locator
+                .evaluate((el, prop) => ({
+                classes: Array.from(el.classList),
+                attrs: Object.fromEntries(Array.from(el.attributes).map((a) => [a.name, a.value])),
+                styleValue: prop ? getComputedStyle(el).getPropertyValue(prop).trim() : null,
+            }), styleProp)
+                .catch(() => null);
+            if (observed) {
+                lastReason = describeStateMismatch(target, checks, observed);
+                if (!lastReason)
+                    return; // every provided check holds
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(lastReason || `Could not read the state of ${target.description} within ${timeout}ms.`);
+            }
+            await this.page.waitForTimeout(100);
+        }
+    }
     async fill(ref, value) {
-        const { locator, target } = await this.resolveRef(ref);
+        const { locator, target } = await this.resolveRef(ref, "input");
         await locator.fill(value);
         return target;
     }
     async select(ref, value) {
-        const { locator, target } = await this.resolveRef(ref);
+        const { locator, target } = await this.resolveRef(ref, "input");
         await locator.selectOption(value);
         return target;
     }
@@ -535,17 +753,23 @@ export class BrowserSession {
         this.screenshots.push(file);
         return file;
     }
-    /** Replays one recorded step (used by the deterministic runner). */
-    async executeStep(step) {
+    /**
+     * Replays one recorded step (used by the deterministic runner). For the
+     * interaction steps (click/fill/select) the action is tried on the primary
+     * selector and, if it fails, on each recorded fallback in order — a purely
+     * deterministic retry (no LLM, `--no-heal` intact). `onFallback` is notified
+     * when a fallback resolved, so the runner can log which selector rescued it.
+     */
+    async executeStep(step, onFallback) {
         switch (step.kind) {
             case "navigate":
                 return this.navigate(step.url);
             case "click":
-                return void (await this.targetLocator(step.target).click());
+                return this.actWithFallback(step.target, (loc) => loc.click(), onFallback);
             case "fill":
-                return void (await this.targetLocator(step.target).fill(resolveEnvValue(step.value)));
+                return this.actWithFallback(step.target, (loc) => loc.fill(resolveEnvValue(step.value)), onFallback);
             case "select":
-                return void (await this.targetLocator(step.target).selectOption(resolveEnvValue(step.value)));
+                return this.actWithFallback(step.target, (loc) => loc.selectOption(resolveEnvValue(step.value)), onFallback);
             case "press":
                 return this.press(step.key);
             case "wheel":
@@ -560,6 +784,13 @@ export class BrowserSession {
                 return this.assertVisible(step.text, { timeout: step.timeout, oneShot: step.oneShot });
             case "assertNotVisible":
                 return this.assertNotVisible(step.text, step.timeout);
+            case "assertState":
+                return this.assertState(step.target, {
+                    hasClass: step.hasClass,
+                    notHasClass: step.notHasClass,
+                    attribute: step.attribute,
+                    computedStyle: step.computedStyle,
+                }, step.timeout);
             case "assertUrl":
                 return this.assertUrl(step.pattern, step.timeout);
             case "assertNetwork":
@@ -574,15 +805,36 @@ export class BrowserSession {
                 return void (await this.screenshot(step.label));
         }
     }
+    /**
+     * Attempts an action on the target's primary selector, then on each recorded
+     * fallback in order until one succeeds. The primary's own auto-wait runs
+     * first (unchanged happy path); only on failure are fallbacks tried, each with
+     * their own auto-wait. If every candidate fails, the PRIMARY's error is thrown
+     * — the most relevant one to debug. No LLM, so `--no-heal` semantics hold.
+     */
+    actWithFallback(target, act, onFallback) {
+        return runWithFallback(target, (t) => this.targetLocator(t), act, onFallback);
+    }
+    /** The replay locator: the primary strategy, narrowed to the first match. */
     targetLocator(target) {
+        return this.rawLocator(target).first();
+    }
+    /**
+     * The unnarrowed locator for a target's primary strategy — used for the record
+     * -time uniqueness check (its `count()` must reflect ALL matches, so no
+     * `.first()` here). testId → role+name → text → css, mirroring the ladder.
+     */
+    rawLocator(target) {
+        if (target.testId)
+            return this.page.getByTestId(target.testId);
         if (target.role && target.name) {
-            return this.page
-                .getByRole(target.role, {
+            return this.page.getByRole(target.role, {
                 name: target.name,
                 exact: true,
-            })
-                .first();
+            });
         }
+        if (target.text)
+            return this.page.getByText(target.text, { exact: true });
         if (target.css)
             return this.page.locator(target.css);
         throw new Error(`Target has no location strategy: ${target.description}`);
@@ -635,8 +887,9 @@ export class BrowserSession {
         // finalized once the context is closed (hence close() is awaited). The
         // first page owns the context recording, even after switching tabs.
         const video = this.firstPage.video();
+        // Close ONLY the context — the Browser process is shared (pooled) and reused
+        // by later sessions. closeBrowsers() tears the process down at process exit.
         await this.context.close().catch(() => { });
-        await this.browser.close().catch(() => { });
         let videoPath;
         if (video) {
             try {
@@ -715,6 +968,57 @@ export function buildStorageInitScript(storage) {
     } catch (e) {}
   })();`;
 }
+/**
+ * Builds a durable Target for an element located directly by data-testid or CSS
+ * (no snapshot ref). testId wins when both are given — it is the stabler handle
+ * for elements outside the a11y tree. Throws when neither is provided, so a
+ * selector click/assert can never silently target nothing.
+ */
+export function buildSelectorTarget(sel) {
+    if (sel.testId)
+        return { testId: sel.testId, description: `[data-testid="${sel.testId}"]` };
+    if (sel.css)
+        return { css: sel.css, description: sel.css };
+    throw new Error("A selector click/assert needs testId or css.");
+}
+/** Escapes a CSS attribute NAME for an attribute selector (identifier subset). */
+function cssAttrEscape(name) {
+    return name.replace(/[^a-zA-Z0-9_-]/g, "\\$&");
+}
+/** Escapes a value for a double-quoted CSS attribute selector. */
+function cssValueEscape(value) {
+    return value.replace(/(["\\])/g, "\\$1");
+}
+/**
+ * Compares an observed element state against a matcher, returning "" when every
+ * provided check holds or a human-readable reason for the FIRST failing one.
+ * Pure, so it is unit-testable without a browser and shared by the live poll.
+ */
+export function describeStateMismatch(target, checks, observed) {
+    const where = ` on ${target.description}`;
+    if (checks.hasClass !== undefined && !observed.classes.includes(checks.hasClass)) {
+        return `Expected class "${checks.hasClass}"${where}, but classes are [${observed.classes.join(", ")}].`;
+    }
+    if (checks.notHasClass !== undefined && observed.classes.includes(checks.notHasClass)) {
+        return `Class "${checks.notHasClass}" must be absent${where}, but it is present [${observed.classes.join(", ")}].`;
+    }
+    if (checks.attribute !== undefined) {
+        const { name, value } = checks.attribute;
+        const has = Object.prototype.hasOwnProperty.call(observed.attrs, name);
+        if (!has)
+            return `Expected attribute "${name}"${where}, but it is absent.`;
+        if (value !== undefined && observed.attrs[name] !== value) {
+            return `Expected attribute "${name}"="${value}"${where}, but it is "${observed.attrs[name]}".`;
+        }
+    }
+    if (checks.computedStyle !== undefined) {
+        const { property, value } = checks.computedStyle;
+        if (observed.styleValue !== value) {
+            return `Expected computed ${property}="${value}"${where}, but it is "${observed.styleValue ?? "(unread)"}".`;
+        }
+    }
+    return "";
+}
 /** Replaces $ENV:VAR_NAME placeholders so secrets never live in committed scripts. */
 export function resolveEnvValue(value) {
     return value.replace(/\$ENV:([A-Z0-9_]+)/g, (_, name) => {
@@ -724,8 +1028,16 @@ export function resolveEnvValue(value) {
         return v;
     });
 }
-/** Runs inside the page: collects visible interactive elements + text excerpt. */
-const snapshotScript = `(() => {
+/**
+ * In-page helper library, shared by the snapshot script and the single-element
+ * ladder extractor. Kept as one string so the accessible-name / role / css-path
+ * logic lives in exactly one place. `ATTR` (the testid attribute) and `HOPS`
+ * (ancestor testid reach) are interpolated by the builders below.
+ */
+function inPageHelpers(attr, hops) {
+    return `
+  const TESTID_ATTR = ${JSON.stringify(attr)};
+  const TESTID_HOPS = ${JSON.stringify(hops)};
   const ROLE_BY_TAG = {
     a: "link", button: "button", select: "combobox", textarea: "textbox",
     summary: "button", option: "option",
@@ -800,6 +1112,55 @@ const snapshotScript = `(() => {
     return parts.join(" > ");
   }
 
+  // The element's OWN testid — the top rung of the selector ladder.
+  function testIdOf(el) {
+    const v = el.getAttribute(TESTID_ATTR);
+    return v || undefined;
+  }
+
+  // The nearest ANCESTOR testid within TESTID_HOPS (a click may borrow it).
+  function ancestorTestIdOf(el) {
+    let node = el.parentElement;
+    let hops = 0;
+    while (node && hops < TESTID_HOPS) {
+      const v = node.getAttribute(TESTID_ATTR);
+      if (v) return v;
+      node = node.parentElement;
+      hops += 1;
+    }
+    return undefined;
+  }
+
+  // Visible text for a text anchor — only when short and stable enough, and not
+  // for form controls (their "text" is the value, not a stable label).
+  function textOf(el) {
+    const tag = el.tagName;
+    if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return undefined;
+    const t = (el.textContent || "").replace(/\\s+/g, " ").trim();
+    if (!t || t.length > 50) return undefined;
+    return t;
+  }
+
+  // The full ladder signal set for one element (role/name are COMPUTED here,
+  // from the live DOM, never guessed from a visible label).
+  function extractLadder(el) {
+    return {
+      role: roleOf(el) || undefined,
+      name: nameOf(el) || undefined,
+      css: cssPath(el),
+      testId: testIdOf(el),
+      ancestorTestId: ancestorTestIdOf(el),
+      id: el.id || undefined,
+      text: textOf(el),
+    };
+  }
+`;
+}
+/** Runs inside the page: collects visible interactive elements + text excerpt. */
+function buildSnapshotScript(attr, hops) {
+    return `(() => {
+  ${inPageHelpers(attr, hops)}
+
   const selector = 'a[href], button, input, select, textarea, summary, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="checkbox"], [role="switch"], [role="option"], [onclick], [tabindex]:not([tabindex="-1"])';
   const nodes = Array.from(document.querySelectorAll(selector)).filter(isVisible);
   const seen = new Set();
@@ -811,7 +1172,12 @@ const snapshotScript = `(() => {
     const role = roleOf(el);
     const name = nameOf(el);
     if (!role && !name) continue;
-    const info = { ref: ref++, role: role || el.tagName.toLowerCase(), name, css: cssPath(el), tag: el.tagName.toLowerCase() };
+    const ladder = extractLadder(el);
+    const info = { ref: ref++, role: role || el.tagName.toLowerCase(), name, css: ladder.css, tag: el.tagName.toLowerCase() };
+    if (ladder.testId) info.testId = ladder.testId;
+    if (ladder.ancestorTestId) info.ancestorTestId = ladder.ancestorTestId;
+    if (ladder.id) info.id = ladder.id;
+    if (ladder.text) info.text = ladder.text;
     if (el.tagName === "INPUT" && el.type !== "password" && el.value) info.value = String(el.value).slice(0, 40);
     if (el.tagName === "A") {
       const href = el.getAttribute("href");
@@ -824,4 +1190,18 @@ const snapshotScript = `(() => {
   const text = (document.body.innerText || "").replace(/\\n{3,}/g, "\\n\\n").slice(0, 2500);
   return { elements, text };
 })()`;
+}
+/**
+ * Runs inside the page: extracts the ladder signals for the FIRST element that
+ * matches `selector`, or returns null when nothing matches. Used to upgrade an
+ * AI-supplied selector click through the ladder.
+ */
+function buildExtractScript(selector, attr, hops) {
+    return `(() => {
+  ${inPageHelpers(attr, hops)}
+  const el = document.querySelector(${JSON.stringify(selector)});
+  if (!el) return null;
+  return extractLadder(el);
+})()`;
+}
 //# sourceMappingURL=browser.js.map