@jobshimo/browser-link 0.22.0 → 0.23.1

package/dist/cdp/flow.js

@@ -0,0 +1,217 @@
+/**
+ * Independent copy of `packages/extension/src/flow.ts` — see
+ * `inpage/deep-query.ts`'s header comment for why this package duplicates
+ * rather than imports extension-side modules. Byte-identical logic, so
+ * `browser.flow` behaves identically whether the target tab is reached
+ * through the extension or through cdp-direct. Kept transport-agnostic ON
+ * PURPOSE — it does NOT re-check the cdp-direct gate per step; a mid-flow
+ * `cdp revoke` is grandfathered until the flow finishes (bounded ≤60s by
+ * the flow budget), documented in the README's cdp-direct section.
+ * `cdp/drift.test.ts` asserts `MAX_FLOW_STEPS` stays in lockstep with the
+ * sibling at `packages/extension/src/flow.ts`.
+ *
+ * browser.flow step sequencing — the logic behind the composite action
+ * tool. Runs a short, declarative list of find/click/type/press/wait_for
+ * steps strictly in order, fails fast on the first step that does not
+ * succeed, and threads an "implicit target" from a `find` step into the
+ * very next click/type/press step that omits its own `selector`.
+ *
+ * Deliberately decoupled from any transport: every side effect goes
+ * through the `FlowDeps` the caller injects. `cdp/transport.ts` wires the
+ * real perform* functions (already closed over the CDP client); tests wire
+ * fakes. This is what makes the sequencing logic — step-shape validation,
+ * implicit-target threading, fail-fast, result shaping — unit-testable
+ * without a real Chrome target.
+ */
+/** Hard cap on steps per flow — mirrors the `maxItems: 20` on the MCP
+ * schema (`browser-definitions.ts`) and the server-side validation
+ * (`browser-dispatch.ts`). Enforced again here so cdp-direct never runs an
+ * oversized flow even if a future caller bypasses the server's own check. */
+export const MAX_FLOW_STEPS = 20;
+const STEP_KINDS = ['find', 'click', 'type', 'press', 'wait_for'];
+function isStepKind(key) {
+    return STEP_KINDS.includes(key);
+}
+/** Identify which of the 5 step kinds a raw (untrusted) step object is.
+ * Returns `null` unless the object has EXACTLY ONE key and that key is a
+ * recognized kind — extra keys (`{find: {...}, mystery: 1}`) reject, in
+ * line with the MCP schema's `additionalProperties: false`. The caller
+ * treats `null` as an "unknown step shape" flow failure. */
+function stepKind(step) {
+    if (typeof step !== 'object' || step === null)
+        return null;
+    const keys = Object.keys(step);
+    if (keys.length !== 1)
+        return null;
+    return isStepKind(keys[0]) ? keys[0] : null;
+}
+/** Drop the noisy fields of a click/type/press result down to `{ ok, settle? }`
+ * for the flow's per-step result — the agent already knows what it asked
+ * for (the selector, the text length, the key); echoing that back N times
+ * in a row is not worth the tokens. `settle` is kept because it carries
+ * NEW information (did the page go quiet, did focus/URL drift). */
+function compactActionResult(result) {
+    return result.settle ? { ok: true, settle: result.settle } : { ok: true };
+}
+async function withRecoverySnapshot(deps, index, kind, error, stepsCompleted) {
+    let recovery_snapshot = null;
+    try {
+        recovery_snapshot = await deps.buildRecoverySnapshot();
+    }
+    catch {
+        // Best-effort: if the tab is gone or CDP throws on the recovery
+        // snapshot too, still report the original step failure rather than
+        // masking it behind a secondary snapshot error.
+    }
+    return {
+        ok: false,
+        failed_step: index,
+        step_kind: kind,
+        error,
+        steps_completed: stepsCompleted,
+        recovery_snapshot,
+    };
+}
+/** Resolve a click/type/press step's target: an explicit `selector` always
+ * wins; otherwise fall back to the implicit target left by a preceding
+ * `find` step. `consumed` is true only when the implicit target was the
+ * one actually used — a step providing its own selector leaves the
+ * implicit target untouched for a LATER step to pick up. */
+function resolveTarget(explicit, implicit) {
+    if (explicit !== undefined)
+        return { resolved: explicit, consumed: false };
+    return { resolved: implicit, consumed: implicit !== undefined };
+}
+/** Appended to a step failure when the PREVIOUS step's settle wait reported
+ * `context-destroyed` — that reason means the page navigated during or right
+ * after that step, so the failing step almost certainly raced the loading
+ * document rather than genuinely missing its target. */
+const NAVIGATION_RACE_HINT = " (previous step's settle reported context-destroyed — the page likely navigated;" +
+    ' insert a wait_for step after the navigating action so this step does not race the page load)';
+/**
+ * Run a declarative sequence of steps strictly in order, stopping at the
+ * first failure. See the module doc comment for the implicit-target and
+ * result-shaping rules.
+ *
+ * `steps` is typed as `FlowStep[]` for ergonomic test-writing, but every
+ * element is re-validated at runtime via `stepKind()` before use — the
+ * array may originate from an untrusted JSON payload cast at the wire
+ * boundary in `cdp/transport.ts`, and a malformed entry must fail the flow
+ * cleanly rather than throw.
+ */
+export async function runFlow(steps, deps) {
+    if (!Array.isArray(steps) || steps.length === 0) {
+        return withRecoverySnapshot(deps, 0, 'none', 'flow: steps must be a non-empty array', 0);
+    }
+    if (steps.length > MAX_FLOW_STEPS) {
+        return withRecoverySnapshot(deps, 0, 'none', `flow: at most ${MAX_FLOW_STEPS} steps allowed, got ${steps.length}`, 0);
+    }
+    const results = [];
+    let implicitTarget;
+    /** `settle.reason` from the most recent SUCCESSFUL action step. When it
+     * is 'context-destroyed', the next step failure gets the page-load-race
+     * hint appended. Reset by any successful find/wait_for step — those
+     * prove the page is reachable again. */
+    let lastSettleReason;
+    const raceHint = () => lastSettleReason === 'context-destroyed' ? NAVIGATION_RACE_HINT : '';
+    for (let i = 0; i < steps.length; i++) {
+        const raw = steps[i];
+        const kind = stepKind(raw);
+        if (!kind) {
+            return withRecoverySnapshot(deps, i, 'unknown', 'flow: each step must be exactly one of find | click | type | press | wait_for', results.length);
+        }
+        const stepRecord = raw;
+        if (kind === 'find') {
+            const params = stepRecord.find;
+            const outcome = await deps.performFind(params);
+            if (!outcome.ok) {
+                return withRecoverySnapshot(deps, i, kind, outcome.error + raceHint(), results.length);
+            }
+            const r = outcome.result;
+            if (!r.matched) {
+                const candidateNote = r.reason === 'multiple-matches' && r.candidates
+                    ? ` — candidates: ${JSON.stringify(r.candidates)}`
+                    : '';
+                return withRecoverySnapshot(deps, i, kind, `find: ${r.reason ?? 'not-found'}${candidateNote}${raceHint()}`, results.length);
+            }
+            if (r.ambiguous) {
+                return withRecoverySnapshot(deps, i, kind, `find: selector "${r.selector ?? ''}" is ambiguous across shadow roots/iframes — refine text/role for a unique match`, results.length);
+            }
+            implicitTarget = r.selector;
+            lastSettleReason = undefined;
+            results.push({ selector: r.selector });
+            continue;
+        }
+        if (kind === 'wait_for') {
+            const params = stepRecord.wait_for;
+            const outcome = await deps.performWaitFor(params);
+            if (!outcome.ok) {
+                return withRecoverySnapshot(deps, i, kind, outcome.error + raceHint(), results.length);
+            }
+            if (!outcome.result.matched) {
+                // No race hint here: a wait_for step IS the recommended remedy for
+                // a navigation race — a plain timeout is a genuine non-match.
+                return withRecoverySnapshot(deps, i, kind, `wait_for: condition not met within timeout (${outcome.result.elapsed_ms}ms, ${outcome.result.checks} checks)`, results.length);
+            }
+            lastSettleReason = undefined;
+            results.push({ ok: true });
+            continue;
+        }
+        if (kind === 'click') {
+            const params = stepRecord.click;
+            const { resolved, consumed } = resolveTarget(params.selector, implicitTarget);
+            if (consumed)
+                implicitTarget = undefined;
+            if (resolved === undefined) {
+                return withRecoverySnapshot(deps, i, kind, 'click: no selector provided and no implicit target from a preceding find', results.length);
+            }
+            const outcome = await deps.performClick({
+                force: params.force,
+                settle_ms: params.settle_ms,
+                selector: resolved,
+            });
+            if (!outcome.ok) {
+                return withRecoverySnapshot(deps, i, kind, outcome.error + raceHint(), results.length);
+            }
+            lastSettleReason = outcome.result.settle?.reason;
+            results.push(compactActionResult(outcome.result));
+            continue;
+        }
+        if (kind === 'type') {
+            const params = stepRecord.type;
+            const { resolved, consumed } = resolveTarget(params.selector, implicitTarget);
+            if (consumed)
+                implicitTarget = undefined;
+            const outcome = await deps.performType({
+                text: params.text,
+                clear: params.clear,
+                settle_ms: params.settle_ms,
+                selector: resolved,
+            });
+            if (!outcome.ok) {
+                return withRecoverySnapshot(deps, i, kind, outcome.error + raceHint(), results.length);
+            }
+            lastSettleReason = outcome.result.settle?.reason;
+            results.push(compactActionResult(outcome.result));
+            continue;
+        }
+        // press — the only kind left after the checks above.
+        const params = stepRecord.press;
+        const { resolved, consumed } = resolveTarget(params.selector, implicitTarget);
+        if (consumed)
+            implicitTarget = undefined;
+        const outcome = await deps.performPress({
+            key: params.key,
+            modifiers: params.modifiers,
+            settle_ms: params.settle_ms,
+            selector: resolved,
+        });
+        if (!outcome.ok) {
+            return withRecoverySnapshot(deps, i, kind, outcome.error + raceHint(), results.length);
+        }
+        lastSettleReason = outcome.result.settle?.reason;
+        results.push(compactActionResult(outcome.result));
+    }
+    return { ok: true, steps_completed: results.length, results };
+}
+//# sourceMappingURL=flow.js.map

package/dist/cdp/flow.js.map

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

package/dist/cdp/gate.d.ts

@@ -0,0 +1,31 @@
+export type CdpDirectGate = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** Exact wording agents receive when cdp-direct is off entirely. Agents get
+ * this string and NOTHING else — there is no bypass, no partial access, no
+ * alternate path to a `cdp:` tab while this check fails. */
+export declare const CDP_DIRECT_DISABLED_ERROR = "cdp-direct is disabled. The user can enable it with: browser-link config set cdp-direct.enabled true";
+/** Exact wording agents receive when cdp-direct is enabled but no live
+ * grant exists (never granted, revoked, or expired). */
+export declare const CDP_DIRECT_NO_GRANT_ERROR = "cdp-direct requires an active grant. Ask the user to run: browser-link cdp allow";
+/**
+ * The ONE gate every cdp-direct code path runs through, in the exact order
+ * the feature's permission model requires: (1) is cdp-direct enabled at
+ * all, (2) is there a live, unexpired grant. Re-evaluated on every call —
+ * never cached — because either condition can flip mid-session (the user
+ * disables the setting, or a time-boxed grant simply expires) and the very
+ * next tool call must see that.
+ *
+ * Called from two places by design: `tools/browser-dispatch.ts`'s routing
+ * layer (so an agent gets the exact error text above before any cdp-direct
+ * code runs at all) AND `cdp/transport.ts` itself (defense in depth, so the
+ * transport module is never safe to call without this check even if a
+ * future caller reaches it directly). `cdp/targets.ts`'s `browser.list_tabs`
+ * discovery also gates on this, but treats a failing gate as "show nothing"
+ * rather than an error — an agent that has never heard of cdp-direct should
+ * not see it mentioned in a routine list_tabs call.
+ */
+export declare function checkCdpDirectGate(now?: number): CdpDirectGate;

package/dist/cdp/gate.js

@@ -0,0 +1,35 @@
+import { loadConfig } from '../config.js';
+import { isGrantLive, loadGrant } from './grant.js';
+/** Exact wording agents receive when cdp-direct is off entirely. Agents get
+ * this string and NOTHING else — there is no bypass, no partial access, no
+ * alternate path to a `cdp:` tab while this check fails. */
+export const CDP_DIRECT_DISABLED_ERROR = 'cdp-direct is disabled. The user can enable it with: browser-link config set cdp-direct.enabled true';
+/** Exact wording agents receive when cdp-direct is enabled but no live
+ * grant exists (never granted, revoked, or expired). */
+export const CDP_DIRECT_NO_GRANT_ERROR = 'cdp-direct requires an active grant. Ask the user to run: browser-link cdp allow';
+/**
+ * The ONE gate every cdp-direct code path runs through, in the exact order
+ * the feature's permission model requires: (1) is cdp-direct enabled at
+ * all, (2) is there a live, unexpired grant. Re-evaluated on every call —
+ * never cached — because either condition can flip mid-session (the user
+ * disables the setting, or a time-boxed grant simply expires) and the very
+ * next tool call must see that.
+ *
+ * Called from two places by design: `tools/browser-dispatch.ts`'s routing
+ * layer (so an agent gets the exact error text above before any cdp-direct
+ * code runs at all) AND `cdp/transport.ts` itself (defense in depth, so the
+ * transport module is never safe to call without this check even if a
+ * future caller reaches it directly). `cdp/targets.ts`'s `browser.list_tabs`
+ * discovery also gates on this, but treats a failing gate as "show nothing"
+ * rather than an error — an agent that has never heard of cdp-direct should
+ * not see it mentioned in a routine list_tabs call.
+ */
+export function checkCdpDirectGate(now = Date.now()) {
+    const cfg = loadConfig();
+    if (cfg.cdpDirectEnabled !== true)
+        return { ok: false, error: CDP_DIRECT_DISABLED_ERROR };
+    if (!isGrantLive(loadGrant(), now))
+        return { ok: false, error: CDP_DIRECT_NO_GRANT_ERROR };
+    return { ok: true };
+}
+//# sourceMappingURL=gate.js.map

package/dist/cdp/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/cdp/gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAIpD;;4DAE4D;AAC5D,MAAM,CAAC,MAAM,yBAAyB,GACpC,sGAAsG,CAAC;AAEzG;wDACwD;AACxD,MAAM,CAAC,MAAM,yBAAyB,GACpC,kFAAkF,CAAC;AAErF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc,IAAI,CAAC,GAAG,EAAE;IACzD,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;IACzB,IAAI,GAAG,CAAC,gBAAgB,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,yBAAyB,EAAE,CAAC;IAC1F,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,EAAE,GAAG,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,yBAAyB,EAAE,CAAC;IAC3F,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC"}

package/dist/cdp/grant.d.ts

@@ -0,0 +1,45 @@
+/**
+ * On-disk record of a `browser-link cdp allow` grant — the time-boxed human
+ * consent that, together with `cdp-direct.enabled`, is required before any
+ * tool may address a `cdp:` tab (see `gate.ts`). Lives in its own small JSON
+ * file in the data dir, never in the repo, never in `config.json` (a grant
+ * is a momentary permission, not a persistent preference).
+ */
+export interface CdpGrant {
+    grantedAt: number;
+    /** `null` means the grant never expires ("never" / `--minutes 0`) —
+     * documented in the CLI help and README as reducing the security
+     * posture, not a default anyone should reach for casually. */
+    expiresAt: number | null;
+}
+/** Absolute path of the grant file — exported so the CLI can name it in an
+ * honest "could not remove" error (see `commands/cdp.ts`) rather than
+ * leaving the user guessing which file to delete by hand. */
+export declare function grantFilePath(): string;
+/** Read the current grant, or `null` when none exists or the file is
+ * corrupt/unreadable — corruption degrades to "no grant" (the safer
+ * failure mode for a permission file) rather than throwing. */
+export declare function loadGrant(): CdpGrant | null;
+/** Record a fresh grant. `ttlMinutes: 0` means "never expires"
+ * (`expiresAt: null`); any other value is the grant's lifetime in minutes
+ * from `now`. `now` is a parameter so tests do not need to mock the clock. */
+export declare function saveGrant(ttlMinutes: number, now?: number): CdpGrant;
+/** Revoke the current grant, if any. Idempotent — revoking with no grant
+ * present is not an error and is a no-op.
+ *
+ * Deliberately does NOT swallow an unlink failure: this is a SECURITY
+ * operation, and a grant file that survives a "revoke" (a transient
+ * Windows lock, an EPERM, a read-only dir) is still honoured by the gate
+ * on the very next tool call — so reporting success while the door stays
+ * open would be a lie. The error propagates; the CLI (`revokeCdpDirect` in
+ * `commands/cdp.ts`) catches it and tells the user the grant may still be
+ * active and to remove the file by hand. */
+export declare function clearGrant(): void;
+/** Whether `grant` is currently live: present, and either non-expiring or
+ * not yet past its `expiresAt`. */
+export declare function isGrantLive(grant: CdpGrant | null, now?: number): boolean;
+/** Milliseconds remaining on `grant`, or `null` when it never expires or
+ * does not exist (callers distinguish "no grant" from "never expires" by
+ * checking `grant` itself first). Never negative — an expired grant reads
+ * as `0` remaining, not a negative number. */
+export declare function remainingMs(grant: CdpGrant | null, now?: number): number | null;

package/dist/cdp/grant.js

@@ -0,0 +1,81 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { getDataDir } from '../map/paths.js';
+function grantFile() {
+    return join(getDataDir(), 'cdp-grant.json');
+}
+/** Absolute path of the grant file — exported so the CLI can name it in an
+ * honest "could not remove" error (see `commands/cdp.ts`) rather than
+ * leaving the user guessing which file to delete by hand. */
+export function grantFilePath() {
+    return grantFile();
+}
+function isCdpGrant(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return (typeof v.grantedAt === 'number' && (v.expiresAt === null || typeof v.expiresAt === 'number'));
+}
+/** Read the current grant, or `null` when none exists or the file is
+ * corrupt/unreadable — corruption degrades to "no grant" (the safer
+ * failure mode for a permission file) rather than throwing. */
+export function loadGrant() {
+    const path = grantFile();
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return isCdpGrant(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Record a fresh grant. `ttlMinutes: 0` means "never expires"
+ * (`expiresAt: null`); any other value is the grant's lifetime in minutes
+ * from `now`. `now` is a parameter so tests do not need to mock the clock. */
+export function saveGrant(ttlMinutes, now = Date.now()) {
+    const path = grantFile();
+    mkdirSync(dirname(path), { recursive: true });
+    const grant = {
+        grantedAt: now,
+        expiresAt: ttlMinutes === 0 ? null : now + ttlMinutes * 60_000,
+    };
+    writeFileSync(path, JSON.stringify(grant, null, 2) + '\n', 'utf8');
+    return grant;
+}
+/** Revoke the current grant, if any. Idempotent — revoking with no grant
+ * present is not an error and is a no-op.
+ *
+ * Deliberately does NOT swallow an unlink failure: this is a SECURITY
+ * operation, and a grant file that survives a "revoke" (a transient
+ * Windows lock, an EPERM, a read-only dir) is still honoured by the gate
+ * on the very next tool call — so reporting success while the door stays
+ * open would be a lie. The error propagates; the CLI (`revokeCdpDirect` in
+ * `commands/cdp.ts`) catches it and tells the user the grant may still be
+ * active and to remove the file by hand. */
+export function clearGrant() {
+    const path = grantFile();
+    if (!existsSync(path))
+        return;
+    unlinkSync(path);
+}
+/** Whether `grant` is currently live: present, and either non-expiring or
+ * not yet past its `expiresAt`. */
+export function isGrantLive(grant, now = Date.now()) {
+    if (!grant)
+        return false;
+    if (grant.expiresAt === null)
+        return true;
+    return grant.expiresAt > now;
+}
+/** Milliseconds remaining on `grant`, or `null` when it never expires or
+ * does not exist (callers distinguish "no grant" from "never expires" by
+ * checking `grant` itself first). Never negative — an expired grant reads
+ * as `0` remaining, not a negative number. */
+export function remainingMs(grant, now = Date.now()) {
+    if (!grant || grant.expiresAt === null)
+        return null;
+    return Math.max(0, grant.expiresAt - now);
+}
+//# sourceMappingURL=grant.js.map

package/dist/cdp/grant.js.map

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

package/dist/cdp/inpage/builders.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Build the snapshot expression. Filters are applied INSIDE the page so the
+ * server never receives the dropped material at all — that's where the token
+ * win for `within_selector` / `only_interactive` / `exclude` actually lives.
+ * The serializer omits empty-string fields per entry (token win that applies
+ * unconditionally on every snapshot).
+ *
+ * The scan pierces open Shadow DOM roots and same-origin iframes via
+ * `deepQueryAll` (see `deep-query.ts`). `within_selector` itself is resolved
+ * with `deepQueryFirst`, so a subtree inside a shadow root or iframe can be
+ * targeted too. Matched entries that live inside an iframe carry an
+ * optional `frame` field with the innermost hosting iframe's selector, and
+ * entries whose generated selector could not be made unique across the deep
+ * search scope carry `ambiguous: true` (see `genSelectorInfo`).
+ */
+export interface SnapshotOpts {
+    within_selector?: string;
+    only_interactive?: boolean;
+    exclude?: string[];
+    max_interactive?: number;
+}
+export declare function buildSnapshotJs(opts?: SnapshotOpts): string;
+/** Build the find-by-text expression. Returns one of:
+ *   { matched: true, selector, coords:{x,y}, tag, text, frame?, ambiguous? }
+ *   { matched: false, reason: 'not-found', error?, near_misses?: [{text,selector,role?}] }
+ *   { matched: false, reason: 'multiple-matches', candidates: [{selector,text,tag}] }
+ *
+ * Role-aware: when `role` is provided, only elements whose explicit ARIA
+ * role or implicit role match are considered. When omitted, the search
+ * scans a broad set of interactive + clickable elements.
+ *
+ * The scan pierces open Shadow DOM roots and same-origin iframes via
+ * `deepQueryAll`. `coords` are mapped to TOP-LEVEL viewport coordinates
+ * (accounting for ancestor iframe offsets) so they are directly usable by
+ * `browser.drag` and other coordinate-based tools.
+ *
+ * `not-found` carries up to 3 `near_misses` — VISIBLE interactive-ish
+ * elements ranked by (1) case-insensitive substring containment of the
+ * query in the candidate's accessible text/name, then (2) token overlap —
+ * so the agent gets a "did you mean" instead of a bare miss. Omitted
+ * entirely when nothing scores (no junk suggestions). When `role` narrowed
+ * the scan and the text DOES exist outside that role, `error` names the
+ * exclusion explicitly (e.g. `text matched 2 elements but none with role
+ * "button" — closest: <div onclick> "GIF picker"`) and `near_misses` is
+ * populated from that broader, role-agnostic match set instead.
+ *
+ * Near-miss entries use `genSelector` (not `genSelectorInfo`), so the
+ * `ambiguous` flag is intentionally NOT carried — a near-miss selector
+ * that collides with structurally-identical twins in other roots resolves
+ * first-match-wins silently. Documented on the tool as: hints for the
+ * next `find`, never click targets.
+ */
+export interface FindOpts {
+    text: string;
+    role?: string;
+    exact?: boolean;
+}
+export declare function buildFindJs(opts: FindOpts): string;
+/**
+ * Build the click-resolution expression: resolves the selector across the
+ * deep search scope, scrolls the element (and every ancestor iframe) into
+ * view, computes the TOP-LEVEL viewport click point, and — unless `force`
+ * is set — hit-tests that point before returning it, so a covering overlay
+ * is caught before dispatching CDP mouse events. Returns:
+ *   { ok: true, x, y, tag }
+ *   { ok: false, reason: 'invalid-selector', error }
+ *   { ok: false, reason: 'not-found' }
+ *   { ok: false, reason: 'occluded', blocker }
+ *
+ * The `invalid-selector` check runs BEFORE `deepQueryFirst` — a malformed
+ * CSS selector throws the identical `SyntaxError` from every root's own
+ * `querySelector`, which `deepQueryFirst`'s per-root try/catch otherwise
+ * swallows into an indistinguishable "not-found". Checking once against
+ * `document` up front separates "the selector text is broken" from "the
+ * selector is valid but nothing on the page matches it".
+ */
+export interface ClickResolveOpts {
+    selector: string;
+    force: boolean;
+}
+export declare function buildClickResolveJs(opts: ClickResolveOpts): string;
+/**
+ * Build the type-resolution expression: resolves the selector across the
+ * deep search scope, focuses it, optionally clears its value, and reports
+ * success so the caller can follow up with CDP `Input.insertText` (which
+ * types into whatever currently has focus at the browser level — works the
+ * same whether that focus target lives in the top document, a shadow root,
+ * or a same-origin iframe). Returns:
+ *   { ok: true }
+ *   { ok: false, reason: 'invalid-selector', error }
+ *   { ok: false, reason: 'not-found' }
+ *
+ * Same invalid-selector pre-check as `buildClickResolveJs` — see its doc
+ * comment for why the check has to run before `deepQueryFirst`.
+ */
+export interface TypeResolveOpts {
+    selector: string;
+    clear: boolean;
+}
+export declare function buildTypeResolveJs(opts: TypeResolveOpts): string;
+/**
+ * Build the focus-resolution expression for `browser.press`'s optional
+ * `selector`: resolves the selector across the deep search scope and
+ * focuses it, reporting success so the caller can follow up with the CDP
+ * key event sequence (which — like `Input.insertText` — targets whatever
+ * currently has focus at the browser level). Intentionally separate from
+ * `buildTypeResolveJs`: press never clears a value, and naming it
+ * distinctly keeps the press code path readable on its own.
+ */
+export interface FocusResolveOpts {
+    selector: string;
+}
+export declare function buildFocusJs(opts: FocusResolveOpts): string;
+/**
+ * Build the settle-await expression shared by `browser.click`, `.type` and
+ * `.press`. Called AFTER the action's CDP input events have been
+ * dispatched: installs one `MutationObserver` on `document` (subtree,
+ * childList, attributes, characterData) and resolves once no mutation has
+ * landed for `settle_ms` consecutive milliseconds, or once `settle_timeout_ms`
+ * total has elapsed — whichever comes first. Returned as a Promise so the
+ * caller's `evaluateInTab` (CDP `Runtime.evaluate` with `awaitPromise: true`)
+ * waits for it naturally.
+ *
+ * Baseline `url`/`activeElement` are captured at the TOP of this
+ * expression — i.e. right after the action's own focus/navigation side
+ * effects have already landed (dispatch already happened by the time this
+ * runs), so `focus_moved`/`url_changed` report drift that happened DURING
+ * the settle window, not the action's own expected effect.
+ *
+ * The result omits `url_changed` / `focus_moved` when they did not change
+ * — token-lean by construction, no post-filtering needed.
+ */
+export interface SettleOpts {
+    /** Quiet-period length in ms. Caller is expected to have already
+     * clamped this to (0, 2000] — 0 means "don't call this builder at all". */
+    settle_ms: number;
+    /** Overall cap in ms. Caller is expected to have already clamped this
+     * to [0, 10000]. */
+    settle_timeout_ms: number;
+}
+export declare function buildSettleJs(opts: SettleOpts): string;
+/**
+ * Build the `browser.state` expression: a compact orientation snapshot —
+ * current url/title, the deep-resolved focused element, visible dialog-role
+ * elements, scroll position, and viewport size. Cheaper than a full
+ * `browser.snapshot` when the agent only needs "where am I right now".
+ *
+ * `focused` descends through `document.activeElement` past shadow-root and
+ * same-origin-iframe boundaries to the real innermost focused element (a
+ * shadow host or an <iframe> being "active" at one level is not the actual
+ * focus target the agent cares about). Its `selector` goes through the same
+ * `genSelectorInfo` uniqueness check `snapshot`/`find` use, so it carries
+ * `ambiguous: true` under the same structurally-identical-twins condition.
+ *
+ * `dialogs` matches visible `[role=dialog]`, `[role=alertdialog]` and open
+ * `<dialog>` elements found via the same deep walk, with a best-effort
+ * `label` resolved from aria-label / aria-labelledby / the first heading
+ * inside the dialog.
+ *
+ * Every optional field is omitted when there is nothing to report: no
+ * `focused` beyond `<body>`, no `dialogs` when none are open, and no
+ * `scroll` when the page is at its default (0,0) position — token-lean by
+ * construction, matching the omit-falsy convention the other builders use.
+ */
+export declare function buildStateJs(): string;