@enricai/barnacle 1.6.12 → 1.6.13

package/dist/scraper/deep-locator-candidates.d.ts

@@ -9,12 +9,31 @@
  * when the step is scoped to a child frame.
  */
 import type { Page } from "@browserbasehq/stagehand";
+import { type FrameTarget } from "../scraper/frame-target";
 /** Overrides for the watchdog timeouts this module applies to every `deepLocator()` await; tests pass small values so cases don't burn wall-clock. */
 export interface DeepLocatorTimeoutOptions {
     /** Per-call watchdog timeout for `count()`/`textContent()`/`click()`. Defaults to {@link DEFAULT_DEEP_LOCATOR_CALL_TIMEOUT_MS}. */
     callTimeoutMs?: number;
-    /** Total budget for {@link resolveDeepLocatorCandidates}'s enumeration loop. Defaults to {@link DEFAULT_DEEP_LOCATOR_ENUMERATION_BUDGET_MS}. */
+    /** Total budget for {@link resolveDeepLocatorCandidates}'s legacy enumeration loop. Defaults to {@link DEFAULT_DEEP_LOCATOR_ENUMERATION_BUDGET_MS}. */
     enumerationBudgetMs?: number;
+    /**
+     * Pre-resolved `FrameTarget` to scan via one batched
+     * `evaluate(buildScanFrameCandidatesExpr(innerSelector))` round-trip
+     * instead of the legacy `count()` + per-candidate `textContent()` loop.
+     * When omitted, a single non-polling `probeAttachedFrameTarget(page,
+     * frameSelector)` pass (`frame-target.ts`) is attempted internally so
+     * existing call sites get the batched fast path for free. Unlike a bare
+     * `resolveFrameTarget(page, frameSelector, { timeoutMs: 0 })` pass — which
+     * always loses the race against genuine CDP latency — this probe carries a
+     * real per-probe budget (`config.scraper.framePresenceProbeFloorMs`), so it
+     * can actually land against an already-attached frame under live latency.
+     * If the probe doesn't land a resolved child frame (not yet attached, or
+     * `frameSelector` is null/undefined), the legacy loop runs unchanged. A
+     * caller that already resolved a `FrameTarget` (e.g. `flow-runner.ts`'s
+     * per-step resolution) should pass it here to skip the redundant internal
+     * probe.
+     */
+    frameTarget?: FrameTarget;
 }
 /**
  * One candidate element `page.deepLocator()` resolved inside a scoped frame.
@@ -33,9 +52,48 @@ export interface DeepLocatorCandidate {
     index: number;
     /** `deeplocator=`-prefixed selector identifying this candidate for downstream `resolvedAction` synthesis; deliberately not `xpath=` (see {@link DeepLocatorCandidate} docs). */
     selector: string;
-    /** Accessible text read via the delegate's `textContent()`. */
+    /**
+     * Accessible text for this candidate: the derived accessible name (see
+     * {@link buildScanFrameCandidatesExpr}) on the batched-scan fast path,
+     * or the delegate's raw `textContent()` on the legacy per-candidate
+     * enumeration fallback.
+     */
     accessibleText: string;
 }
+/** One quoted phrase from an instruction, tagged with whether a negation marker (`NEGATION_MARKERS`) governs it. See {@link extractTaggedPhrases}. */
+export interface TaggedPhrase {
+    text: string;
+    negated: boolean;
+}
+/**
+ * Extracts every single-quoted phrase from `instruction`, tagging each as
+ * negated when a negation marker (`NEGATION_MARKERS`) precedes it within the
+ * same sentence — flow instructions keep each "Do NOT click 'X', 'Y', ..."
+ * clause as one sentence listing every negated phrase, so a sentence
+ * boundary (`.`/`;`) between the marker and the phrase ends the negation's
+ * reach. Mirrors the quoted-phrase extraction convention in
+ * `parseSelectStep`/`parseRadioStep` (`flow-runner.ts`) — same
+ * `/'([^']+)'/g` shape — but here we need ALL quoted phrases plus their
+ * polarity, not just one option/label pair. Exported so `flow-runner.ts` can
+ * re-derive the exact same ranking {@link scoreCandidate} used to sort
+ * `deepLocatorCandidates`, to detect a tie for the top rank rather than
+ * duplicating this logic.
+ */
+export declare function extractTaggedPhrases(instruction: string): TaggedPhrase[];
+/**
+ * Scores one candidate's relevance to `instruction`'s tagged phrases, higher
+ * is more relevant. Mirrors `submit-control.ts`'s tiered-ranking shape:
+ * negative signal is checked first and wins outright (a candidate matching
+ * ANY negated phrase is actively demoted below "no match" — a decoy sibling
+ * button is worse than an unrelated structural node), then positive
+ * exact/substring match tiers, falling through to 0 for empty or
+ * unrelated text so a structural container with no accessible text can
+ * never outrank a candidate whose text actually matches the instruction.
+ * Exported so `flow-runner.ts` can detect a tie for the top rank among
+ * `resolveDeepLocatorCandidates`'s already-sorted output (see
+ * {@link extractTaggedPhrases}'s docblock).
+ */
+export declare function scoreCandidate(accessibleText: string, phrases: TaggedPhrase[]): number;
 /**
  * Enumerates every element `page.deepLocator()` matches inside the frame
  * scoped by `frameSelector`, ranked by relevance to `instruction` (highest
@@ -50,20 +108,25 @@ export interface DeepLocatorCandidate {
  * cascading through candidate sources can move on to the next technique
  * instead of hanging the step forever.
  *
+ * Prefers a single batched `evaluate` round-trip over the frame
+ * (see {@link scanFrameCandidatesBatched}) — collapsing the O(n) per-candidate
+ * `textContent()` round-trips that made a dense OOPIF form (371 candidates
+ * measured live) unresolvable inside any reasonable budget — and falls back
+ * to the legacy `count()` + per-candidate loop (see
+ * {@link enumerateCandidatesViaLegacyLoop}) when no frame seam is available,
+ * the batched scan fails, or the batched scan resolves to zero candidates —
+ * the batched expression's light-DOM `querySelectorAll` can't see into a
+ * shadow root the way `page.deepLocator()` can, so a zero-length scan is
+ * treated as inconclusive rather than authoritative. Pass an already-resolved
+ * {@link DeepLocatorTimeoutOptions.frameTarget} to use the fast path without
+ * paying for an internal re-resolution.
+ *
  * Ranking exists because a hop like `"*"` matches every element inside a
  * wizard iframe (html, body, every div, ...) — DOM order alone almost always
  * puts a structural container first, not the control the step instruction
  * actually names. Pass `instruction` as `null`/`undefined` (or omit it) to
  * skip ranking and get delegate order — e.g. for pre-cascade reachability
  * probes that only care whether the frame has ANY candidates.
- *
- * `count()` and each per-candidate `textContent()` are individually bounded
- * by `timeoutOptions.callTimeoutMs` via {@link withWatchdog}; the enumeration
- * loop as a whole is additionally bounded by `timeoutOptions.enumerationBudgetMs`
- * so a hop with dozens of slow-but-settling elements (e.g. 65 candidates
- * matched against a live OOPIF) can't rack up an unbounded total cost even
- * when no single call hangs — the loop aborts early and returns whatever
- * candidates it already resolved.
  */
 export declare function resolveDeepLocatorCandidates(page: Page, frameSelector: string | null | undefined, innerSelector: string, instruction?: string | null, timeoutOptions?: DeepLocatorTimeoutOptions): Promise<DeepLocatorCandidate[]>;
 /**
@@ -71,14 +134,38 @@ export declare function resolveDeepLocatorCandidates(page: Page, frameSelector:
  * re-deriving the same hop selector `resolveDeepLocatorCandidates` used
  * rather than trusting a caller-supplied `xpath=` string, so the two stay in
  * lockstep even if a candidate's `selector` field is only ever used for
- * display/logging. `DeepLocatorDelegate.click()` resolves `Promise<void>` on
- * success and rejects on failure — it never reports success via a return
- * value — so callers must infer the outcome from whether this call throws
- * plus their own downstream DOM verification, not from a returned boolean.
- * A `click()` that exceeds `timeoutOptions.callTimeoutMs` (a wedged CDP
- * round-trip against a racy OOPIF frame) rejects with a `WatchdogTimeoutError`
- * the same as any other failure, preserving the "rejects on failure" contract
- * instead of hanging the caller forever.
+ * display/logging. Resolves on success and rejects on failure — the caller
+ * must infer the outcome from whether this call throws plus their own
+ * downstream DOM verification, not from a returned boolean.
+ *
+ * Prefers the one-round-trip {@link clickCandidateBatched} fast path when a
+ * frame seam is available (`timeoutOptions.frameTarget`, or one resolved
+ * internally the same way {@link scanFrameCandidatesBatched} does), falling
+ * back to the legacy `DeepLocatorDelegate.click()` — which never reports
+ * success via a return value, only via not rejecting — when no seam is
+ * available, the batched call fails/degrades, or it reports the index
+ * stale (`reason: "out-of-range"`). A batched `reason: "not-actionable"`
+ * result throws an error {@link isNodeNotActionableError} classifies, the
+ * same contract a real click against an unrendered node rejects with via the
+ * CDP `-32000 Node does not have a layout object` error, so a caller
+ * cascading through candidates treats both paths identically.
+ *
+ * The legacy fallback's watchdog scales with `index` (see
+ * {@link DEEP_LOCATOR_CLICK_INDEX_ROUND_TRIP_MS}) so a legitimately-reachable
+ * candidate isn't killed by a budget sized for a single round-trip. A
+ * `click()` that still exceeds that scaled budget (a wedged CDP round-trip
+ * against a racy OOPIF frame) rejects with a `WatchdogTimeoutError` the same
+ * as any other failure, preserving the "rejects on failure" contract instead
+ * of hanging the caller forever.
  */
 export declare function clickDeepLocatorCandidate(page: Page, frameSelector: string | null | undefined, innerSelector: string, index: number, timeoutOptions?: DeepLocatorTimeoutOptions): Promise<void>;
+/**
+ * `fillDeepLocatorCandidate`/`selectDeepLocatorCandidateOption` live in
+ * `deep-locator-actuate.ts`, not here — that module's `writeAndVerify` wraps
+ * the same `buildHopSelector`/`withWatchdog` contract this file's
+ * `clickDeepLocatorCandidate` uses, but additionally reads the write back
+ * through `inputValue()` before reporting success (`verifyDomEffect` can't
+ * resolve a `deeplocator=` selector, so the read-back is the only
+ * confirmation a fill/select actually landed).
+ */
 //# sourceMappingURL=deep-locator-candidates.d.ts.map

package/dist/scraper/deep-locator-candidates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deep-locator-candidates.d.ts","sourceRoot":"","sources":["../../src/scraper/deep-locator-candidates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AA2BrD,sJAAsJ;AACtJ,MAAM,WAAW,yBAAyB;IACxC,mIAAmI;IACnI,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gJAAgJ;IAChJ,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,oBAAoB;IACnC,kJAAkJ;IAClJ,KAAK,EAAE,MAAM,CAAC;IACd,gLAAgL;IAChL,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,cAAc,EAAE,MAAM,CAAC;CACxB;AA6ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACxC,aAAa,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,EAC3B,cAAc,GAAE,yBAA8B,GAC7C,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAoDjC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACxC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,EACb,cAAc,GAAE,yBAA8B,GAC7C,OAAO,CAAC,IAAI,CAAC,CAOf"}
+{"version":3,"file":"deep-locator-candidates.d.ts","sourceRoot":"","sources":["../../src/scraper/deep-locator-candidates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAWrD,OAAO,EAEL,KAAK,WAAW,EAEjB,MAAM,wBAAwB,CAAC;AA2BhC,sJAAsJ;AACtJ,MAAM,WAAW,yBAAyB;IACxC,mIAAmI;IACnI,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uJAAuJ;IACvJ,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;;;;;;;;OAgBG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAKD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,oBAAoB;IACnC,kJAAkJ;IAClJ,KAAK,EAAE,MAAM,CAAC;IACd,gLAAgL;IAChL,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;CACxB;AAsBD,sJAAsJ;AACtJ,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,EAAE,CAaxE;AAOD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAStF;AA6JD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACxC,aAAa,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,EAC3B,cAAc,GAAE,yBAA8B,GAC7C,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAuCjC;AAqDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACxC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,EACb,cAAc,GAAE,yBAA8B,GAC7C,OAAO,CAAC,IAAI,CAAC,CAwBf;AAED;;;;;;;;GAQG"}

package/dist/scraper/deep-locator-candidates.js

@@ -10,10 +10,13 @@
  * when the step is scoped to a child frame.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractTaggedPhrases = extractTaggedPhrases;
+exports.scoreCandidate = scoreCandidate;
 exports.resolveDeepLocatorCandidates = resolveDeepLocatorCandidates;
 exports.clickDeepLocatorCandidate = clickDeepLocatorCandidate;
 const errors_1 = require("../lib/errors");
 const logging_1 = require("../lib/logging");
+const deep_locator_scan_1 = require("../scraper/deep-locator-scan");
 const frame_target_1 = require("../scraper/frame-target");
 const watchdog_1 = require("../scraper/watchdog");
 const logger = (0, logging_1.getLogger)({ name: "scraper/deep-locator-candidates" });
@@ -25,12 +28,16 @@ const logger = (0, logging_1.getLogger)({ name: "scraper/deep-locator-candidates
  */
 const DEFAULT_DEEP_LOCATOR_CALL_TIMEOUT_MS = 10_000;
 /**
- * Total wall-clock budget for {@link resolveDeepLocatorCandidates}'s
- * per-candidate `textContent()` enumeration loop. A hop like `"*"` can match
+ * Total wall-clock budget for {@link resolveDeepLocatorCandidates}'s legacy
+ * per-candidate `textContent()` enumeration loop — the fallback path taken
+ * when no batched frame-scoped scan is available (see
+ * {@link DeepLocatorTimeoutOptions.frameTarget}). A hop like `"*"` can match
  * dozens of elements (65 observed against a live OOPIF) — each individually
  * fast but settling, not hanging — so a per-call timeout alone doesn't bound
  * the loop's total cost. Roughly half of `flow-runner.ts`'s
  * `STEP_WATCHDOG_MS` (120s), leaving headroom for the rest of the attempt.
+ * The batched scan path completes in one round-trip and is never gated by
+ * this budget.
  */
 const DEFAULT_DEEP_LOCATOR_ENUMERATION_BUDGET_MS = 60_000;
 /**
@@ -60,7 +67,10 @@ const NEGATION_MARKERS = /\b(?:do\s+not|don't|never|avoid)\b/gi;
  * reach. Mirrors the quoted-phrase extraction convention in
  * `parseSelectStep`/`parseRadioStep` (`flow-runner.ts`) — same
  * `/'([^']+)'/g` shape — but here we need ALL quoted phrases plus their
- * polarity, not just one option/label pair.
+ * polarity, not just one option/label pair. Exported so `flow-runner.ts` can
+ * re-derive the exact same ranking {@link scoreCandidate} used to sort
+ * `deepLocatorCandidates`, to detect a tie for the top rank rather than
+ * duplicating this logic.
  */
 function extractTaggedPhrases(instruction) {
     const negationStarts = [...instruction.matchAll(NEGATION_MARKERS)].map((m) => m.index);
@@ -88,6 +98,9 @@ function normalize(text) {
  * exact/substring match tiers, falling through to 0 for empty or
  * unrelated text so a structural container with no accessible text can
  * never outrank a candidate whose text actually matches the instruction.
+ * Exported so `flow-runner.ts` can detect a tie for the top rank among
+ * `resolveDeepLocatorCandidates`'s already-sorted output (see
+ * {@link extractTaggedPhrases}'s docblock).
  */
 function scoreCandidate(accessibleText, phrases) {
     const normalizedText = normalize(accessibleText);
@@ -103,6 +116,132 @@ function scoreCandidate(accessibleText, phrases) {
         return 2;
     return 0;
 }
+/**
+ * Resolves the `FrameTarget` the batched scan should evaluate against:
+ * `timeoutOptions.frameTarget` when the caller already resolved one, else a
+ * single non-polling `probeAttachedFrameTarget(page, frameSelector)` pass
+ * (`frame-target.ts`) so existing call sites — which pass only a
+ * `frameSelector` string, not a `FrameTarget` — still get the batched fast
+ * path without themselves changing. Unlike a bare `resolveFrameTarget(page,
+ * frameSelector, { timeoutMs: 0 })` pass, the probe carries a real per-probe
+ * budget, so it can land against an already-attached frame under genuine CDP
+ * latency instead of always losing a zero-budget race. Returns `null` (never
+ * throws) when `frameSelector` is unset, the probe rejects (e.g. a fake
+ * `Page` in a legacy-path test lacking `evaluate`/`frames`), or nothing
+ * attaches within the probe's budget — each of those means "no frame seam
+ * available", and the caller degrades to the legacy per-candidate loop.
+ */
+async function resolveScanFrameTarget(page, frameSelector, timeoutOptions) {
+    if (timeoutOptions.frameTarget)
+        return timeoutOptions.frameTarget;
+    if (!frameSelector)
+        return null;
+    try {
+        return await (0, frame_target_1.probeAttachedFrameTarget)(page, frameSelector);
+    }
+    catch {
+        return null;
+    }
+}
+/** Narrows a batched-scan evaluate result to {@link FrameCandidateScanResult}'s shape, guarding against a non-conforming payload (Issue #2's degrade-to-legacy-loop contract). */
+function isFrameCandidateScanResult(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return false;
+    const candidate = entry;
+    return (typeof candidate.index === "number" &&
+        typeof candidate.text === "string" &&
+        typeof candidate.visible === "boolean");
+}
+/**
+ * Batched-scan fast path: one `frameTarget.evaluate(buildScanFrameCandidatesExpr(innerSelector))`
+ * round-trip replaces the legacy `count()` + N × `nth(i).textContent()` loop.
+ * Returns `null` (never throws) when no frame seam is available, the
+ * evaluate call rejects (missing seam, thrown error, or a watchdog timeout —
+ * `frameTarget.evaluate` already carries its own watchdog), the resolved
+ * payload doesn't conform to {@link FrameCandidateScanResult}[], or the raw
+ * scan matched zero elements — every one of those degrades the caller to the
+ * legacy loop instead of losing candidates. A raw zero-match scan is treated
+ * as inconclusive rather than authoritative because the scan expression's
+ * light-DOM `querySelectorAll` can't see into a shadow root the way
+ * `page.deepLocator()` (used by the legacy loop) can, so it must not be
+ * confused with the *visibility* filter below, which legitimately produces
+ * an empty result when the scan *did* match elements but every one of them
+ * is unrendered. Filters out `visible:false` entries (Issue #2: an
+ * unrendered node can never be the target of a real click) before the
+ * caller ranks what's left, logging at `warn` when candidates are dropped
+ * so a frame whose every node reports unrendered doesn't silently look like
+ * an empty frame.
+ */
+async function scanFrameCandidatesBatched(page, frameSelector, innerSelector, hopSelector, timeoutOptions) {
+    const frameTarget = await resolveScanFrameTarget(page, frameSelector, timeoutOptions);
+    if (!frameTarget)
+        return null;
+    let scanResults;
+    try {
+        scanResults = await frameTarget.evaluate((0, deep_locator_scan_1.buildScanFrameCandidatesExpr)(innerSelector));
+    }
+    catch (err) {
+        logger.warn(`deepLocator batched scan for ${hopSelector} failed, degrading to per-candidate enumeration: ${(0, errors_1.toErrorMessage)(err)}`);
+        return null;
+    }
+    if (!Array.isArray(scanResults) || !scanResults.every(isFrameCandidateScanResult)) {
+        logger.warn(`deepLocator batched scan for ${hopSelector} returned a non-conforming payload, degrading to per-candidate enumeration`);
+        return null;
+    }
+    if (scanResults.length === 0) {
+        logger.warn(`deepLocator batched scan for ${hopSelector} matched zero elements, degrading to per-candidate enumeration in case a shadow-DOM control was missed`);
+        return null;
+    }
+    const visibleResults = scanResults.filter((entry) => entry.visible);
+    if (visibleResults.length < scanResults.length) {
+        logger.warn(`deepLocator batched scan for ${hopSelector} dropped ${scanResults.length - visibleResults.length} unrendered candidate(s)`);
+    }
+    return visibleResults.map((entry) => ({
+        index: entry.index,
+        selector: candidateSelector(hopSelector, entry.index),
+        accessibleText: entry.text.trim(),
+    }));
+}
+/**
+ * Legacy fallback: `count()` then one `nth(index).textContent()` round-trip
+ * per candidate, individually bounded by `callTimeoutMs` via
+ * {@link withWatchdog} and collectively bounded by `enumerationBudgetMs` so a
+ * hop with dozens of slow-but-settling elements (e.g. 65 candidates matched
+ * against a live OOPIF) can't rack up an unbounded total cost even when no
+ * single call hangs — the loop aborts early and returns whatever candidates
+ * it already resolved. Never throws: a `count()`/`textContent()` failure
+ * (detached frame, navigated-away element) or either call exceeding its
+ * watchdog budget degrades to `[]`/an empty `accessibleText`.
+ */
+async function enumerateCandidatesViaLegacyLoop(delegate, hopSelector, callTimeoutMs, enumerationBudgetMs) {
+    const count = await (0, watchdog_1.withWatchdog)(() => delegate.count(), {
+        timeoutMs: callTimeoutMs,
+        label: `deepLocator count() for ${hopSelector}`,
+    }).catch((err) => {
+        logger.warn(`deepLocator count() threw for ${hopSelector}: ${(0, errors_1.toErrorMessage)(err)}`);
+        return 0;
+    });
+    if (count === 0)
+        return [];
+    const candidates = [];
+    const enumerationDeadline = Date.now() + enumerationBudgetMs;
+    for (let index = 0; index < count; index++) {
+        if (Date.now() >= enumerationDeadline) {
+            logger.warn(`deepLocator enumeration for ${hopSelector} aborted after exceeding ${enumerationBudgetMs}ms budget at candidate ${index}/${count}`);
+            break;
+        }
+        const accessibleText = await (0, watchdog_1.withWatchdog)(() => delegate.nth(index).textContent(), {
+            timeoutMs: callTimeoutMs,
+            label: `deepLocator textContent() for ${hopSelector} nth=${index}`,
+        }).catch(() => "");
+        candidates.push({
+            index,
+            selector: candidateSelector(hopSelector, index),
+            accessibleText: accessibleText.trim(),
+        });
+    }
+    return candidates;
+}
 /**
  * Enumerates every element `page.deepLocator()` matches inside the frame
  * scoped by `frameSelector`, ranked by relevance to `instruction` (highest
@@ -117,20 +256,25 @@ function scoreCandidate(accessibleText, phrases) {
  * cascading through candidate sources can move on to the next technique
  * instead of hanging the step forever.
  *
+ * Prefers a single batched `evaluate` round-trip over the frame
+ * (see {@link scanFrameCandidatesBatched}) — collapsing the O(n) per-candidate
+ * `textContent()` round-trips that made a dense OOPIF form (371 candidates
+ * measured live) unresolvable inside any reasonable budget — and falls back
+ * to the legacy `count()` + per-candidate loop (see
+ * {@link enumerateCandidatesViaLegacyLoop}) when no frame seam is available,
+ * the batched scan fails, or the batched scan resolves to zero candidates —
+ * the batched expression's light-DOM `querySelectorAll` can't see into a
+ * shadow root the way `page.deepLocator()` can, so a zero-length scan is
+ * treated as inconclusive rather than authoritative. Pass an already-resolved
+ * {@link DeepLocatorTimeoutOptions.frameTarget} to use the fast path without
+ * paying for an internal re-resolution.
+ *
  * Ranking exists because a hop like `"*"` matches every element inside a
  * wizard iframe (html, body, every div, ...) — DOM order alone almost always
  * puts a structural container first, not the control the step instruction
  * actually names. Pass `instruction` as `null`/`undefined` (or omit it) to
  * skip ranking and get delegate order — e.g. for pre-cascade reachability
  * probes that only care whether the frame has ANY candidates.
- *
- * `count()` and each per-candidate `textContent()` are individually bounded
- * by `timeoutOptions.callTimeoutMs` via {@link withWatchdog}; the enumeration
- * loop as a whole is additionally bounded by `timeoutOptions.enumerationBudgetMs`
- * so a hop with dozens of slow-but-settling elements (e.g. 65 candidates
- * matched against a live OOPIF) can't rack up an unbounded total cost even
- * when no single call hangs — the loop aborts early and returns whatever
- * candidates it already resolved.
  */
 async function resolveDeepLocatorCandidates(page, frameSelector, innerSelector, instruction, timeoutOptions = {}) {
     const callTimeoutMs = timeoutOptions.callTimeoutMs ?? DEFAULT_DEEP_LOCATOR_CALL_TIMEOUT_MS;
@@ -141,32 +285,9 @@ async function resolveDeepLocatorCandidates(page, frameSelector, innerSelector,
         logger.warn(`deepLocator() is unavailable on this page for ${hopSelector}`);
         return [];
     }
-    const count = await (0, watchdog_1.withWatchdog)(() => delegate.count(), {
-        timeoutMs: callTimeoutMs,
-        label: `deepLocator count() for ${hopSelector}`,
-    }).catch((err) => {
-        logger.warn(`deepLocator count() threw for ${hopSelector}: ${(0, errors_1.toErrorMessage)(err)}`);
-        return 0;
-    });
-    if (count === 0)
-        return [];
-    const candidates = [];
-    const enumerationDeadline = Date.now() + enumerationBudgetMs;
-    for (let index = 0; index < count; index++) {
-        if (Date.now() >= enumerationDeadline) {
-            logger.warn(`deepLocator enumeration for ${hopSelector} aborted after exceeding ${enumerationBudgetMs}ms budget at candidate ${index}/${count}`);
-            break;
-        }
-        const accessibleText = await (0, watchdog_1.withWatchdog)(() => delegate.nth(index).textContent(), {
-            timeoutMs: callTimeoutMs,
-            label: `deepLocator textContent() for ${hopSelector} nth=${index}`,
-        }).catch(() => "");
-        candidates.push({
-            index,
-            selector: candidateSelector(hopSelector, index),
-            accessibleText: accessibleText.trim(),
-        });
-    }
+    const batchedCandidates = await scanFrameCandidatesBatched(page, frameSelector, innerSelector, hopSelector, timeoutOptions);
+    const candidates = batchedCandidates ??
+        (await enumerateCandidatesViaLegacyLoop(delegate, hopSelector, callTimeoutMs, enumerationBudgetMs));
     if (!instruction)
         return candidates;
     const phrases = extractTaggedPhrases(instruction);
@@ -181,26 +302,97 @@ async function resolveDeepLocatorCandidates(page, frameSelector, innerSelector,
         .sort((a, b) => b.score - a.score || a.originalOrder - b.originalOrder)
         .map(({ candidate }) => candidate);
 }
+/** Narrows a batched-click evaluate result to {@link FrameCandidateClickResult}'s shape, guarding against a non-conforming payload (the same degrade-to-legacy-loop contract {@link isFrameCandidateScanResult} enforces for the scan side). */
+function isFrameCandidateClickResult(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return false;
+    const result = entry;
+    if (typeof result.clicked !== "boolean")
+        return false;
+    if (result.clicked)
+        return true;
+    return result.reason === "out-of-range" || result.reason === "not-actionable";
+}
+/**
+ * Batched-click fast path: one `frameTarget.evaluate(buildClickFrameCandidateExpr(innerSelector, index))`
+ * round-trip replaces the legacy `nth(index).click()`, which (per
+ * {@link DEEP_LOCATOR_CLICK_INDEX_ROUND_TRIP_MS}'s docs) pays `index + 1`
+ * serial CDP round-trips through `resolveAtIndex`. Returns `null` (never
+ * throws) when no frame seam is available, the evaluate call rejects, or the
+ * resolved payload doesn't conform to {@link FrameCandidateClickResult} —
+ * every one of those degrades the caller to the legacy `nth(index).click()`
+ * path instead of losing the click, mirroring {@link scanFrameCandidatesBatched}'s
+ * degrade contract on the enumeration side.
+ */
+async function clickCandidateBatched(page, frameSelector, innerSelector, index, hopSelector, timeoutOptions) {
+    const frameTarget = await resolveScanFrameTarget(page, frameSelector, timeoutOptions);
+    if (!frameTarget)
+        return null;
+    let clickResult;
+    try {
+        clickResult = await frameTarget.evaluate((0, deep_locator_scan_1.buildClickFrameCandidateExpr)(innerSelector, index));
+    }
+    catch (err) {
+        logger.warn(`deepLocator batched click for ${hopSelector} nth=${index} failed, degrading to delegate click: ${(0, errors_1.toErrorMessage)(err)}`);
+        return null;
+    }
+    if (!isFrameCandidateClickResult(clickResult)) {
+        logger.warn(`deepLocator batched click for ${hopSelector} nth=${index} returned a non-conforming payload, degrading to delegate click`);
+        return null;
+    }
+    return clickResult;
+}
 /**
  * Clicks the candidate at `index` inside the frame scoped by `frameSelector`,
  * re-deriving the same hop selector `resolveDeepLocatorCandidates` used
  * rather than trusting a caller-supplied `xpath=` string, so the two stay in
  * lockstep even if a candidate's `selector` field is only ever used for
- * display/logging. `DeepLocatorDelegate.click()` resolves `Promise<void>` on
- * success and rejects on failure — it never reports success via a return
- * value — so callers must infer the outcome from whether this call throws
- * plus their own downstream DOM verification, not from a returned boolean.
- * A `click()` that exceeds `timeoutOptions.callTimeoutMs` (a wedged CDP
- * round-trip against a racy OOPIF frame) rejects with a `WatchdogTimeoutError`
- * the same as any other failure, preserving the "rejects on failure" contract
- * instead of hanging the caller forever.
+ * display/logging. Resolves on success and rejects on failure — the caller
+ * must infer the outcome from whether this call throws plus their own
+ * downstream DOM verification, not from a returned boolean.
+ *
+ * Prefers the one-round-trip {@link clickCandidateBatched} fast path when a
+ * frame seam is available (`timeoutOptions.frameTarget`, or one resolved
+ * internally the same way {@link scanFrameCandidatesBatched} does), falling
+ * back to the legacy `DeepLocatorDelegate.click()` — which never reports
+ * success via a return value, only via not rejecting — when no seam is
+ * available, the batched call fails/degrades, or it reports the index
+ * stale (`reason: "out-of-range"`). A batched `reason: "not-actionable"`
+ * result throws an error {@link isNodeNotActionableError} classifies, the
+ * same contract a real click against an unrendered node rejects with via the
+ * CDP `-32000 Node does not have a layout object` error, so a caller
+ * cascading through candidates treats both paths identically.
+ *
+ * The legacy fallback's watchdog scales with `index` (see
+ * {@link DEEP_LOCATOR_CLICK_INDEX_ROUND_TRIP_MS}) so a legitimately-reachable
+ * candidate isn't killed by a budget sized for a single round-trip. A
+ * `click()` that still exceeds that scaled budget (a wedged CDP round-trip
+ * against a racy OOPIF frame) rejects with a `WatchdogTimeoutError` the same
+ * as any other failure, preserving the "rejects on failure" contract instead
+ * of hanging the caller forever.
  */
 async function clickDeepLocatorCandidate(page, frameSelector, innerSelector, index, timeoutOptions = {}) {
     const callTimeoutMs = timeoutOptions.callTimeoutMs ?? DEFAULT_DEEP_LOCATOR_CALL_TIMEOUT_MS;
     const hopSelector = (0, frame_target_1.buildHopSelector)(frameSelector, innerSelector);
+    const batchedResult = await clickCandidateBatched(page, frameSelector, innerSelector, index, hopSelector, timeoutOptions);
+    if (batchedResult?.clicked)
+        return;
+    if (batchedResult?.reason === "not-actionable") {
+        throw new Error(`deepLocator batched click for ${hopSelector} nth=${index}: node does not have a layout object`);
+    }
+    const scaledCallTimeoutMs = callTimeoutMs + index * deep_locator_scan_1.DEEP_LOCATOR_CLICK_INDEX_ROUND_TRIP_MS;
     await (0, watchdog_1.withWatchdog)(() => page.deepLocator(hopSelector).nth(index).click(), {
-        timeoutMs: callTimeoutMs,
+        timeoutMs: scaledCallTimeoutMs,
         label: `deepLocator click() for ${hopSelector} nth=${index}`,
     });
 }
+/**
+ * `fillDeepLocatorCandidate`/`selectDeepLocatorCandidateOption` live in
+ * `deep-locator-actuate.ts`, not here — that module's `writeAndVerify` wraps
+ * the same `buildHopSelector`/`withWatchdog` contract this file's
+ * `clickDeepLocatorCandidate` uses, but additionally reads the write back
+ * through `inputValue()` before reporting success (`verifyDomEffect` can't
+ * resolve a `deeplocator=` selector, so the read-back is the only
+ * confirmation a fill/select actually landed).
+ */
 //# sourceMappingURL=deep-locator-candidates.js.map

package/dist/scraper/deep-locator-candidates.js.map

@@ -1 +1 @@
-{"version":3,"file":"deep-locator-candidates.js","sourceRoot":"","sources":["../../src/scraper/deep-locator-candidates.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"deep-locator-candidates.js","sourceRoot":"","sources":["../../src/scraper/deep-locator-candidates.ts"],"names":[],"mappings":"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"}

package/dist/scraper/deep-locator-click.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Candidate-click cascade for `deep-locator-candidates.ts`'s ranked
+ * `DeepLocatorCandidate[]`: `flow-runner.ts` used to click only
+ * `deepLocatorCandidates[0]` (see the bug report's Issue #2), so a top pick
+ * that turned out to be unrendered — a click rejecting with the CDP `-32000
+ * Node does not have a layout object` error `isNodeNotActionableError`
+ * classifies — scored the whole attempt as a failed click instead of trying
+ * the next-ranked candidate. {@link clickFirstActionableCandidate} walks the
+ * list instead, so a not-actionable rejection or a caller-supplied deny hit
+ * costs only that one candidate, not the attempt.
+ *
+ * Extracted out of `flow-runner.ts` so the walk is unit-testable against a
+ * stub click function — no fake `Page`, no Stagehand — and so
+ * `flow-runner.ts`'s own edit stays a call swap (see `bugfix-005`).
+ *
+ * NOT IMPLEMENTED: escalating to Stagehand's `Locator.sendClickEvent()` (a
+ * layout-free actuation) as a rescue for a candidate that's genuinely never
+ * going to render. The report asks for skip-and-continue, not a rescue path.
+ */
+import type { DeepLocatorCandidate } from "../scraper/deep-locator-candidates";
+/**
+ * Upper bound on how many candidates a single {@link clickFirstActionableCandidate}
+ * call will actually click. Denied candidates are skipped without a click and
+ * don't count against this cap — only a real `click()` invocation does — so a
+ * dense post-filter list (a handful of controls, per bugfix-002's visibility
+ * filter and bugfix-005's interactive scoping) still resolves in one or two
+ * attempts, while a pathological list (371 candidates, the uchealth-7
+ * measurement) can't spend the whole step budget clicking its way through
+ * every entry.
+ */
+export declare const DEFAULT_CLICK_CANDIDATE_ATTEMPT_CAP = 5;
+/**
+ * Attempts to click one candidate. Resolves on a successful click; rejects on
+ * failure — the same "no boolean return, infer from throw" contract
+ * `clickDeepLocatorCandidate` (`deep-locator-candidates.ts`) already uses, so
+ * a caller can inject that function directly (partially applied over
+ * `page`/`frameSelector`/`innerSelector`) without an adapter.
+ */
+export type ClickCandidateFn = (candidate: DeepLocatorCandidate) => Promise<void>;
+/** Refuses a candidate before it's clicked — e.g. `flow-runner.ts`'s `isWizardExitAction` deny-list, injected so this module stays site-agnostic. */
+export type DenyCandidatePredicate = (candidate: DeepLocatorCandidate) => boolean;
+export interface ClickCandidateCascadeOptions {
+    /** Skips a candidate without clicking it when this returns `true`. Optional — omit to click every non-not-actionable candidate in rank order. */
+    denyCandidate?: DenyCandidatePredicate;
+    /** Overrides {@link DEFAULT_CLICK_CANDIDATE_ATTEMPT_CAP}. */
+    attemptCap?: number;
+}
+/** Outcome of a {@link clickFirstActionableCandidate} walk. */
+export interface ClickCandidateCascadeOutcome {
+    /** `true` only when a candidate's click resolved (didn't reject). */
+    clicked: boolean;
+    /** The candidate that was clicked, or `null` when the walk exhausted the list/cap without a successful click. */
+    candidate: DeepLocatorCandidate | null;
+    /** Selectors of every candidate this walk actually clicked (attempted), in attempt order — denied candidates are excluded since they were never clicked. */
+    triedSelectors: string[];
+}
+/**
+ * Walks `candidates` in rank order, clicking each via `click` until one
+ * succeeds. A candidate refused by `denyCandidate` is skipped without being
+ * clicked and doesn't count against `attemptCap`. A click rejection that
+ * {@link isNodeNotActionableError} classifies as "not actionable" (unrendered
+ * node) is treated as "skip this candidate, try the next"; any other
+ * rejection stops the walk immediately and rethrows, so a caller doesn't
+ * silently burn the remaining candidates on an error that had nothing to do
+ * with actionability (a detached frame, a wedged click's
+ * `WatchdogTimeoutError`). Never throws on exhaustion — an exhausted list
+ * (every candidate denied or not-actionable, or the cap reached) resolves to
+ * `{ clicked: false, candidate: null, triedSelectors }` instead.
+ */
+export declare function clickFirstActionableCandidate(candidates: readonly DeepLocatorCandidate[], click: ClickCandidateFn, options?: ClickCandidateCascadeOptions): Promise<ClickCandidateCascadeOutcome>;
+//# sourceMappingURL=deep-locator-click.d.ts.map