@enricai/barnacle 1.6.12 → 1.6.14

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

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Fill/select actuation seam over `deepLocator`, mirroring
+ * `clickDeepLocatorCandidate`'s contract (`deep-locator-candidates.ts`) for
+ * the two other primitives a cross-origin OOPIF form's text/select steps
+ * need. Stagehand `act`/`observe` are measured blind inside that OOPIF, and
+ * `verifyDomEffect` (`flow-runner.ts`) can't locate a `deeplocator=` selector
+ * to confirm the write, so both actuators here read the written value back
+ * through the same delegate before reporting success — the caller gets a
+ * trustworthy boolean instead of a downstream verifier that can never fire.
+ *
+ * Both actuators prefer one batched `frameTarget.evaluate(buildFillFrameCandidateExpr(...) |
+ * buildSelectFrameCandidateExpr(...))` round-trip (`deep-locator-scan.ts`) over
+ * the legacy `deepLocator(hop).nth(index).fill()`/`.selectOption()` +
+ * `.inputValue()` pair, which pays Stagehand's `index + 1` serial
+ * `resolveAtIndex` round-trips per call — the same cost
+ * `clickDeepLocatorCandidate` already batches away. The legacy fallback's
+ * watchdog budget scales with `index` using
+ * {@link DEEP_LOCATOR_CLICK_INDEX_ROUND_TRIP_MS} — the same per-round-trip
+ * constant `clickDeepLocatorCandidate` uses — so a legitimately-reachable
+ * candidate deep in a dense OOPIF form isn't killed by a budget sized for one
+ * round-trip.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fillDeepLocatorCandidate = fillDeepLocatorCandidate;
+exports.selectDeepLocatorCandidateOption = selectDeepLocatorCandidateOption;
+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-actuate" });
+/**
+ * Per-CDP-call watchdog default: bounds a single `fill()`/`selectOption()`/
+ * `inputValue()` round-trip. Owned locally (not imported from
+ * `deep-locator-candidates.ts` or `flow-runner.ts`) so this module stays a
+ * self-contained leaf, matching how `deep-locator-candidates.ts` already
+ * avoids the `flow-runner.ts` import cycle by owning its own timeout
+ * constant.
+ */
+const DEFAULT_DEEP_LOCATOR_CALL_TIMEOUT_MS = 10_000;
+/**
+ * Runs `write`, then `readBack`, and reports whether the read-back matches
+ * `expected` — the shared write/verify shape `fillDeepLocatorCandidate` and
+ * `selectDeepLocatorCandidateOption` both need, differing only in which
+ * delegate method performs the write. A {@link WatchdogTimeoutError} from
+ * either await (a wedged CDP round-trip) propagates so the caller can tell a
+ * genuine hang apart from an ordinary failed write — everything else (the
+ * delegate rejecting, or a read-back that disagrees with `expected`) resolves
+ * to `false` instead of throwing.
+ */
+async function writeAndVerify(write, readBack, expected) {
+    try {
+        await write();
+    }
+    catch (error) {
+        if (error instanceof watchdog_1.WatchdogTimeoutError)
+            throw error;
+        return false;
+    }
+    try {
+        return (await readBack()) === expected;
+    }
+    catch (error) {
+        if (error instanceof watchdog_1.WatchdogTimeoutError)
+            throw error;
+        return false;
+    }
+}
+/**
+ * Resolves the `FrameTarget` a batched actuation evaluate should run
+ * 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 — 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 delegate path. Mirrors
+ * `deep-locator-candidates.ts`'s `resolveScanFrameTarget` exactly; duplicated
+ * (not imported) so this module stays a leaf that never depends on
+ * `deep-locator-candidates.ts`.
+ */
+async function resolveActuateFrameTarget(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 fill/select evaluate result to {@link FrameCandidateWriteResult}'s shape, guarding against a non-conforming payload (the same degrade-to-legacy contract `deep-locator-candidates.ts`'s `isFrameCandidateScanResult`/`isFrameCandidateClickResult` enforce). */
+function isFrameCandidateWriteResult(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return false;
+    const result = entry;
+    if (typeof result.written !== "boolean")
+        return false;
+    if (result.written)
+        return typeof result.readBack === "string";
+    return result.reason === "out-of-range" || result.reason === "not-actionable";
+}
+/**
+ * Batched fill/select fast path: one `frameTarget.evaluate(expression)`
+ * round-trip replaces the legacy `nth(index).fill()`/`.selectOption()` +
+ * `.inputValue()` pair. Returns `null` (never throws) when no frame seam is
+ * available, the evaluate call rejects, or the resolved payload doesn't
+ * conform to {@link FrameCandidateWriteResult} — every one of those degrades
+ * the caller to the legacy delegate path instead of losing the write,
+ * mirroring `clickCandidateBatched`'s degrade contract
+ * (`deep-locator-candidates.ts`).
+ */
+async function actuateCandidateBatched(page, frameSelector, hopSelector, index, timeoutOptions, expression, actionLabel) {
+    const frameTarget = await resolveActuateFrameTarget(page, frameSelector, timeoutOptions);
+    if (!frameTarget)
+        return null;
+    let result;
+    try {
+        result = await frameTarget.evaluate(expression);
+    }
+    catch (err) {
+        logger.warn(`deepLocator batched ${actionLabel} for ${hopSelector} nth=${index} failed, degrading to delegate ${actionLabel}: ${(0, errors_1.toErrorMessage)(err)}`);
+        return null;
+    }
+    if (!isFrameCandidateWriteResult(result)) {
+        logger.warn(`deepLocator batched ${actionLabel} for ${hopSelector} nth=${index} returned a non-conforming payload, degrading to delegate ${actionLabel}`);
+        return null;
+    }
+    return result;
+}
+/**
+ * Fills the candidate at `index` inside the frame scoped by `frameSelector`
+ * with `value`, re-deriving the same hop selector
+ * `resolveDeepLocatorCandidates` used (`deep-locator-candidates.ts`) rather
+ * than trusting a candidate's display `selector` (`deeplocator=`-prefixed,
+ * deliberately not an xpath).
+ *
+ * Prefers the one-round-trip {@link actuateCandidateBatched} fast path when a
+ * frame seam is available: a `written: true` result whose inline `readBack`
+ * already matches `value` resolves `true` immediately (no second round-trip
+ * needed); a `reason: "not-actionable"` result (the matched element has no
+ * layout box) resolves `false` immediately — no delegate write against that
+ * same node could succeed either. Every other batched outcome — no frame
+ * seam, a rejecting or non-conforming evaluate, `reason: "out-of-range"`, or
+ * a `written: true` result whose inline `readBack` disagrees with `value`
+ * (e.g. a controlled component's `onChange` reverted the write on a tick the
+ * single synchronous evaluate call couldn't observe) — degrades to the
+ * legacy `deepLocator(hop).nth(index).fill()` + `.inputValue()` pair rather
+ * than trusting the batched call's verdict outright: returns `true` only
+ * when that separate read-back equals `value`, and `false` — never a throw —
+ * when the delegate rejects the fill/read-back or the read-back disagrees.
+ * The legacy path's watchdog budget scales with `index`
+ * ({@link DEEP_LOCATOR_CLICK_INDEX_ROUND_TRIP_MS}, the same per-round-trip
+ * cost `clickDeepLocatorCandidate`'s legacy fallback charges), so a candidate
+ * deep in a dense OOPIF form isn't killed by a budget sized for a single
+ * round-trip. A wedged `fill()`/`inputValue()` call that still exceeds that
+ * scaled budget rejects with a `WatchdogTimeoutError` instead of hanging the
+ * caller, the same "rejects on a genuine hang" contract
+ * `clickDeepLocatorCandidate` uses.
+ */
+async function fillDeepLocatorCandidate(page, frameSelector, innerSelector, index, value, timeoutOptions = {}) {
+    const callTimeoutMs = timeoutOptions.callTimeoutMs ?? DEFAULT_DEEP_LOCATOR_CALL_TIMEOUT_MS;
+    const hopSelector = (0, frame_target_1.buildHopSelector)(frameSelector, innerSelector);
+    const batchedResult = await actuateCandidateBatched(page, frameSelector, hopSelector, index, timeoutOptions, (0, deep_locator_scan_1.buildFillFrameCandidateExpr)(innerSelector, index, value), "fill");
+    if (batchedResult?.written && batchedResult.readBack === value)
+        return true;
+    if (batchedResult?.reason === "not-actionable")
+        return false;
+    const scaledCallTimeoutMs = callTimeoutMs + index * deep_locator_scan_1.DEEP_LOCATOR_CLICK_INDEX_ROUND_TRIP_MS;
+    return writeAndVerify(() => (0, watchdog_1.withWatchdog)(() => page.deepLocator(hopSelector).nth(index).fill(value), {
+        timeoutMs: scaledCallTimeoutMs,
+        label: `deepLocator fill() for ${hopSelector} nth=${index}`,
+    }), () => (0, watchdog_1.withWatchdog)(() => page.deepLocator(hopSelector).nth(index).inputValue(), {
+        timeoutMs: scaledCallTimeoutMs,
+        label: `deepLocator inputValue() for ${hopSelector} nth=${index}`,
+    }), value);
+}
+/**
+ * Selects `value` on the `<select>`-shaped candidate at `index` inside the
+ * frame scoped by `frameSelector`, under the same re-derived-hop,
+ * batched-first, index-scaled-watchdog-guarded contract as
+ * {@link fillDeepLocatorCandidate} — `selectOption()` is the legacy write,
+ * and `inputValue()` (which reads a `<select>`'s selected value the same as
+ * any other form control) is the legacy confirmation. Differs from
+ * `fillDeepLocatorCandidate` in one respect: a batched `written: true` result
+ * resolves `true` on its own, without comparing `readBack` to `value` —
+ * {@link buildSelectFrameCandidateExpr} matches an option by value OR trimmed
+ * label, so `readBack` (the MATCHED option's value) can legitimately differ
+ * from a caller-supplied label string even on a successful write.
+ */
+async function selectDeepLocatorCandidateOption(page, frameSelector, innerSelector, index, value, timeoutOptions = {}) {
+    const callTimeoutMs = timeoutOptions.callTimeoutMs ?? DEFAULT_DEEP_LOCATOR_CALL_TIMEOUT_MS;
+    const hopSelector = (0, frame_target_1.buildHopSelector)(frameSelector, innerSelector);
+    const batchedResult = await actuateCandidateBatched(page, frameSelector, hopSelector, index, timeoutOptions, (0, deep_locator_scan_1.buildSelectFrameCandidateExpr)(innerSelector, index, value), "select");
+    if (batchedResult?.written)
+        return true;
+    if (batchedResult?.reason === "not-actionable")
+        return false;
+    const scaledCallTimeoutMs = callTimeoutMs + index * deep_locator_scan_1.DEEP_LOCATOR_CLICK_INDEX_ROUND_TRIP_MS;
+    return writeAndVerify(() => (0, watchdog_1.withWatchdog)(() => page.deepLocator(hopSelector).nth(index).selectOption(value), {
+        timeoutMs: scaledCallTimeoutMs,
+        label: `deepLocator selectOption() for ${hopSelector} nth=${index}`,
+    }), () => (0, watchdog_1.withWatchdog)(() => page.deepLocator(hopSelector).nth(index).inputValue(), {
+        timeoutMs: scaledCallTimeoutMs,
+        label: `deepLocator inputValue() for ${hopSelector} nth=${index}`,
+    }), value);
+}
+//# sourceMappingURL=deep-locator-actuate.js.map

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

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

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"}