@jobshimo/browser-link 0.22.0 → 0.23.0

package/README.md

@@ -118,6 +118,11 @@ browser-link map import map.json            # restore it (merge by default, --re
   the same bridge and map. `browser-link multi-agent` shows the current
   state; see [Multi-agent mode](https://github.com/jobshimo/browser-link#multi-agent-mode)
   for how it works.
+- **cdp-direct mode** (off by default): an extension-free transport gated
+  behind `browser-link config set cdp-direct.enabled true` PLUS a
+  time-boxed `browser-link cdp allow` grant — see
+  [cdp-direct mode](https://github.com/jobshimo/browser-link#cdp-direct-mode-no-extension)
+  for the security tradeoff and the v1 tool-support table.
 
 ## Where the data lives
 

package/dist/agent-instructions/content.js

@@ -74,6 +74,17 @@ function body() {
         '→ `browser.claim_tab` before operating on a tab so other agents see it',
         'in use. `browser.release_tab` when done.',
         '',
+        'A `list_tabs` entry has `tab_id` starting with `cdp:` (`transport: "cdp"`):',
+        '→ that tab is reached via cdp-direct, not the extension — every tool',
+        'works the same EXCEPT drag/console/network/network_body/',
+        'canvas_screenshot/dialog_respond/set_permission/wait_for_tab (clear',
+        'error naming the extension as the fallback). cdp-direct only appears',
+        'when the user has both enabled it AND granted access — you cannot',
+        'enable or grant it yourself. A "cdp-direct is disabled" or "requires an',
+        'active grant" error means relay the suggested command to the user',
+        '(`browser-link config set cdp-direct.enabled true` or',
+        '`browser-link cdp allow`) — there is no workaround from here.',
+        '',
         '### SELF-CHECK after each user message',
         '',
         '"Is the user talking about a web page, UI, or anything visible in a browser?',

package/dist/agent-instructions/content.js.map

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

package/dist/cdp/client.d.ts

@@ -0,0 +1,35 @@
+type CdpEventHandler = (params: unknown) => void;
+export interface CdpClientOptions {
+    /** How long `connect()` waits for the WS handshake before giving up.
+     * Default 5s — a local loopback connection should be near-instant; a
+     * long default here would make a dead/stale target hang tool calls. */
+    connectTimeoutMs?: number;
+}
+export declare class CdpClient {
+    private readonly url;
+    private readonly options;
+    private ws;
+    private nextId;
+    private readonly pending;
+    private readonly eventHandlers;
+    private closed;
+    constructor(url: string, options?: CdpClientOptions);
+    /** Open the WebSocket and wait for it to be ready. Rejects on a bind
+     * failure or on timeout — never leaves the caller waiting forever on a
+     * target that vanished between discovery and connect. */
+    connect(): Promise<void>;
+    private handleMessage;
+    private handleClose;
+    /** Whether the underlying WebSocket is open and this client has not been
+     * explicitly closed. Used by the transport's connection cache to decide
+     * whether a cached client is still worth reusing. */
+    get isOpen(): boolean;
+    /** Send one CDP command and wait for its matching response. */
+    send<T = unknown>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+    /** Subscribe to a CDP event by method name (e.g. `Page.loadEventFired`).
+     * Returns an unsubscribe function. Multiple handlers for the same method
+     * may be registered independently. */
+    on(method: string, handler: CdpEventHandler): () => void;
+    close(): void;
+}
+export {};

package/dist/cdp/client.js

@@ -0,0 +1,149 @@
+import { WebSocket } from 'ws';
+function frameToText(raw) {
+    if (typeof raw === 'string')
+        return raw;
+    if (Buffer.isBuffer(raw))
+        return raw.toString('utf8');
+    if (Array.isArray(raw))
+        return Buffer.concat(raw).toString('utf8');
+    return Buffer.from(raw).toString('utf8');
+}
+export class CdpClient {
+    url;
+    options;
+    ws = null;
+    nextId = 1;
+    pending = new Map();
+    eventHandlers = new Map();
+    closed = false;
+    constructor(url, options = {}) {
+        this.url = url;
+        this.options = options;
+    }
+    /** Open the WebSocket and wait for it to be ready. Rejects on a bind
+     * failure or on timeout — never leaves the caller waiting forever on a
+     * target that vanished between discovery and connect. */
+    connect() {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const ws = new WebSocket(this.url);
+            const timeoutMs = this.options.connectTimeoutMs ?? 5_000;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                ws.terminate();
+                reject(new Error(`cdp-direct: connection to ${this.url} timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            ws.once('open', () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.ws = ws;
+                resolve();
+            });
+            ws.once('error', (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(err instanceof Error ? err : new Error(String(err)));
+            });
+            ws.on('message', (raw) => {
+                this.handleMessage(raw);
+            });
+            ws.on('close', () => {
+                this.handleClose();
+            });
+        });
+    }
+    handleMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(frameToText(raw));
+        }
+        catch {
+            return;
+        }
+        if (typeof msg.id === 'number') {
+            const pending = this.pending.get(msg.id);
+            if (!pending)
+                return;
+            this.pending.delete(msg.id);
+            if (msg.error) {
+                pending.reject(new Error(msg.error.message ?? 'CDP command failed'));
+            }
+            else {
+                pending.resolve(msg.result);
+            }
+            return;
+        }
+        if (typeof msg.method === 'string') {
+            const handlers = this.eventHandlers.get(msg.method);
+            if (handlers)
+                for (const handler of handlers)
+                    handler(msg.params);
+        }
+    }
+    handleClose() {
+        this.closed = true;
+        const err = new Error('cdp-direct: connection closed');
+        for (const pending of this.pending.values())
+            pending.reject(err);
+        this.pending.clear();
+    }
+    /** Whether the underlying WebSocket is open and this client has not been
+     * explicitly closed. Used by the transport's connection cache to decide
+     * whether a cached client is still worth reusing. */
+    get isOpen() {
+        return !this.closed && this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+    }
+    /** Send one CDP command and wait for its matching response. */
+    send(method, params = {}, timeoutMs = 15_000) {
+        if (!this.ws || this.closed) {
+            return Promise.reject(new Error('cdp-direct: client is not connected'));
+        }
+        const id = this.nextId++;
+        const ws = this.ws;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`cdp-direct: command "${method}" timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: (value) => {
+                    clearTimeout(timer);
+                    resolve(value);
+                },
+                reject: (err) => {
+                    clearTimeout(timer);
+                    reject(err);
+                },
+            });
+            ws.send(JSON.stringify({ id, method, params }));
+        });
+    }
+    /** Subscribe to a CDP event by method name (e.g. `Page.loadEventFired`).
+     * Returns an unsubscribe function. Multiple handlers for the same method
+     * may be registered independently. */
+    on(method, handler) {
+        let set = this.eventHandlers.get(method);
+        if (!set) {
+            set = new Set();
+            this.eventHandlers.set(method, set);
+        }
+        set.add(handler);
+        return () => set.delete(handler);
+    }
+    close() {
+        this.closed = true;
+        try {
+            this.ws?.close();
+        }
+        catch {
+            /* best effort */
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/cdp/client.js.map

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

package/dist/cdp/flow.d.ts

@@ -0,0 +1,178 @@
+/**
+ * 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.
+ */
+/** Structured success/failure outcome shared by every perform* function in
+ * `cdp/transport.ts`. `ok:false` carries the exact same error string the
+ * standalone tool.response would have returned for that failure — both the
+ * thin case wrappers and this module's step executor consume this shape,
+ * so the two call paths can never drift. */
+export type ActionOutcome<T> = {
+    ok: true;
+    result: T;
+} | {
+    ok: false;
+    error: string;
+};
+/** 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 declare const MAX_FLOW_STEPS = 20;
+export interface FindStepParams {
+    text: string;
+    role?: string;
+    exact?: boolean;
+}
+export interface FindStepResult {
+    matched: boolean;
+    reason?: string;
+    candidates?: {
+        selector: string;
+        text: string;
+        tag: string;
+    }[];
+    /** Up to 3 near-miss candidates on a `not-found` result — see
+     * `buildFindJs` in `inpage/builders.ts` for the ranking rules. Not
+     * consumed by `runFlow` today (the flow failure message stays as-is);
+     * carried through so a future caller of the raw `performFind` outcome
+     * (or a richer flow error message) can use it without a shape change. */
+    near_misses?: {
+        text: string;
+        selector: string;
+        role?: string;
+    }[];
+    /** Human-readable detail on a `not-found` result — currently only set
+     * when `role` excluded matches that existed under a broader scan. */
+    error?: string;
+    selector?: string;
+    ambiguous?: boolean;
+    tag?: string;
+    text?: string;
+    coords?: {
+        x: number;
+        y: number;
+    };
+    frame?: string;
+}
+export interface ClickStepParams {
+    selector?: string;
+    force?: boolean;
+    settle_ms?: number;
+}
+export interface ClickStepResult {
+    clicked: string;
+    tag: string;
+    settle?: Record<string, unknown>;
+}
+export interface TypeStepParams {
+    selector?: string;
+    text: string;
+    clear?: boolean;
+    settle_ms?: number;
+}
+export interface TypeStepResult {
+    typed: number;
+    selector?: string;
+    settle?: Record<string, unknown>;
+}
+export interface PressStepParams {
+    key: string;
+    modifiers?: string[];
+    selector?: string;
+    settle_ms?: number;
+}
+export interface PressStepResult {
+    key: string;
+    modifiers: string[];
+    settle?: Record<string, unknown>;
+}
+export interface WaitForStepParams {
+    selector?: string;
+    expression?: string;
+    network_url?: string;
+    condition?: string;
+    timeout_ms?: number;
+    poll_interval_ms?: number;
+}
+export interface WaitForStepResult {
+    matched: boolean;
+    elapsed_ms: number;
+    checks: number;
+    reason?: string;
+}
+export type FlowStep = {
+    find: FindStepParams;
+} | {
+    click: ClickStepParams;
+} | {
+    type: TypeStepParams;
+} | {
+    press: PressStepParams;
+} | {
+    wait_for: WaitForStepParams;
+};
+/** Everything the step executor needs from the outside world. `cdp/transport.ts`
+ * binds each method to the real perform* function; tests bind fakes.
+ * `buildRecoverySnapshot` is called only on failure, and always renders the
+ * same focused view (`only_interactive:true, max_interactive:40`) via the
+ * shared `buildSnapshotJs` builder — same DOM walk `browser.snapshot` uses,
+ * just pre-filtered so the agent sees where the flow stopped without a
+ * follow-up round trip. */
+export interface FlowDeps {
+    performFind(params: FindStepParams): Promise<ActionOutcome<FindStepResult>>;
+    performClick(params: ClickStepParams & {
+        selector: string;
+    }): Promise<ActionOutcome<ClickStepResult>>;
+    performType(params: TypeStepParams): Promise<ActionOutcome<TypeStepResult>>;
+    performPress(params: PressStepParams): Promise<ActionOutcome<PressStepResult>>;
+    performWaitFor(params: WaitForStepParams): Promise<ActionOutcome<WaitForStepResult>>;
+    buildRecoverySnapshot(): Promise<unknown>;
+}
+export interface FlowSuccess {
+    ok: true;
+    steps_completed: number;
+    results: unknown[];
+}
+export interface FlowFailure {
+    ok: false;
+    failed_step: number;
+    step_kind: string;
+    error: string;
+    steps_completed: number;
+    recovery_snapshot: unknown;
+}
+export type FlowResult = FlowSuccess | FlowFailure;
+/**
+ * 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 declare function runFlow(steps: readonly FlowStep[], deps: FlowDeps): Promise<FlowResult>;

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