browserscale-ts 1.2.1 → 1.4.0

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import type { Transport } from "@connectrpc/connect";
 import type { Locator } from "./locator.ts";
-import type { DOMResult, DragResult, ElementResult, EvaluateResult, InterceptedRequest, InterceptedResponse, InspectResult, NavigateResult, ObservationResult, PageInfo, ScreenshotResult, ReadCanvasResult, SelectOptionResult, WaitResult } from "./types.ts";
-import type { ClickOpts, FillOpts, GetDOMOpts, GetObservationOpts, LoadHTMLOpts, NavigateOpts, ScreenshotOpts, ReadCanvasOpts, SelectOpts, WaitOpts } from "./options.ts";
+import type { DOMResult, DragResult, ElementResult, EvaluateResult, InterceptedRequest, InterceptedResponse, InspectResult, NavigateResult, PageInfo, ScreenshotResult, ReadCanvasResult, SelectOptionResult, WaitResult, IceServer, ReactionInfo } from "./types.ts";
+import type { ClickOpts, FillOpts, GetDOMOpts, GetObservationOpts, LoadHTMLOpts, NavigateOpts, ReactionOpts, ScreenshotOpts, ReadCanvasOpts, SelectOpts, WaitOpts } from "./options.ts";
 import type { HeaderModification, RequestPattern } from "./network.ts";
 import type { CookieParam } from "./cookies.ts";
 import type { StorageOriginEntry } from "./storage.ts";
@@ -462,27 +462,43 @@ export declare class CloudBrowser {
      */
     getDOMHash(frameId?: string): Promise<string>;
     /**
-     * Returns a compact, agent-friendly description of every interactable
-     * element currently visible on the page, together with a truncated view
-     * of the surrounding text.
+     * Returns a compact, frame-aware view of the visible page — the first thing
+     * to reach for on an unfamiliar page, and the cheapest way to re-read the
+     * current state afterwards.
      *
-     * Intended as input for LLM/agent loops where a full DOM dump would be
-     * too large; the server filters down to elements that are actually
-     * visible and interactable.
+     * Each frame opens with header lines carrying the URL, the title and the
+     * scroll position, then one line per visible element:
      *
-     * @param opts - optional caps: `maxElementsPerFrame`, `maxTextLength`;
-     *   omit either to use the server default
+     * ```
+     * input#email[47] type="email" name="loginId" value="a@b.com" required click "E-Mail"
+     * ```
      *
-     * @returns ObservationResult with both a human-readable `text` rendering
-     *   and a `json` payload of the structured observation
+     * It spans every frame, pierces open and closed shadow roots, enumerates
+     * `<select>` options, and reports live form state: `value=` is what is typed
+     * in right now (passwords as a length), `checked=` for boxes. The trailing
+     * quoted string is always the label or text, never the value, so an empty and
+     * a prefilled field stay distinguishable. Because the headers already carry
+     * URL, title and scroll offset, this replaces the usual handful of
+     * {@link evaluate} probes after each step.
+     *
+     * On what to do with the result: backendNodeId (the `47` above) is a handle
+     * for this session and can be passed straight to click/fill via
+     * {@link node}. It does not survive a new document, so for anything you write
+     * into a script, target with {@link css} or {@link js} instead — those calls
+     * return the backendNodeId they resolved to, which lets you confirm the
+     * durable anchor hits the element you saw.
+     *
+     * @param opts - optional format and budget overrides; see {@link GetObservationOpts}
+     *
+     * @returns the observation in the requested format, ready to hand to a model
      *
      * @throws UNKNOWN_ERROR - the observation could not be produced
      *
      * @example
-     * const obs = await browser.getObservation({ maxElementsPerFrame: 200 });
-     * console.log(obs.text);
+     * const obs = await browser.getObservation();
+     * console.log(obs);
      */
-    getObservation(opts?: GetObservationOpts): Promise<ObservationResult>;
+    getObservation(opts?: GetObservationOpts): Promise<string>;
     /**
      * Captures a single image of the page's current frame and returns it as
      * base64-encoded image bytes.
@@ -818,6 +834,36 @@ export declare class CloudBrowser {
      * await browser.insertText("hello world");
      */
     insertText(text: string): Promise<void>;
+    /**
+     * Types `text` into the currently focused element as a per-key stream of real
+     * keyboard events (keyDown/char/keyUp with the context's QWERTZ/QWERTY layout
+     * and human cadence) — unlike {@link insertText}, a single IME-style commit
+     * with no key events.
+     *
+     * `type` is intentionally UNtargeted and loose: it does not locate or focus
+     * any element and does NOT pin focus, so the page is free to route keys and
+     * move focus between fields mid-stream — ideal for one-time-code / OTP inputs
+     * that auto-advance to the next box on each digit. To type one specific field
+     * that must stay focused for the whole value, use {@link fill} instead
+     * (strict, target-bound, per-key focus-verified).
+     *
+     * Nothing is focused for you: {@link click} (or {@link fill}) the field first,
+     * or otherwise ensure focus, before calling `type`.
+     *
+     * @param text - the text to type as real key events
+     * @param opts - optional: `clearFirst` clears the focused field (Ctrl+A,
+     *   Delete) before typing
+     *
+     * @throws UNKNOWN_ERROR - the page/context was torn down mid-stream
+     *
+     * @example
+     * // OTP field that auto-advances across boxes.
+     * await browser.click(css("input.otp-0"));
+     * await browser.type("123456");
+     */
+    type(text: string, opts?: {
+        clearFirst?: boolean;
+    }): Promise<void>;
     /**
      * Fires a single key-down event.
      *
@@ -901,4 +947,113 @@ export declare class CloudBrowser {
         timeoutMs?: number;
         retryAmount?: number;
     }): Promise<string>;
+    /**
+     * Returns the ICE servers (TURN URL + short-lived credentials) to put in
+     * your `RTCPeerConnection` BEFORE creating the offer, so it can gather relay
+     * candidates.
+     *
+     * Live streaming is a two-step, client-offerer handshake: call
+     * `getStreamConfig`, build your peer with the returned servers, create an
+     * offer, then pass its SDP to {@link startStream} and apply the answer.
+     *
+     * @returns the ICE servers for the client `RTCPeerConnection`
+     *
+     * @throws UNKNOWN_ERROR - TURN is not configured on the server
+     *
+     * @example
+     * const ice = await browser.getStreamConfig();
+     * const pc = new RTCPeerConnection({ iceServers: ice });
+     */
+    getStreamConfig(): Promise<IceServer[]>;
+    /**
+     * Answers your WebRTC SDP offer and starts streaming the page as a video
+     * track, returning the SDP answer to set as your peer's remote description.
+     * The browser is the answerer; you are the offerer (see
+     * {@link getStreamConfig} for the credentials to build the offer).
+     *
+     * @param offerSdp - your `RTCPeerConnection`'s SDP offer
+     *
+     * @returns the SDP answer to apply as the remote description
+     *
+     * @throws UNKNOWN_ERROR - the offer was empty, TURN is unconfigured, or the
+     *   browser could not negotiate the stream
+     *
+     * @example
+     * const answer = await browser.startStream(offer.sdp);
+     * await pc.setRemoteDescription({ type: "answer", sdp: answer });
+     */
+    startStream(offerSdp: string): Promise<string>;
+    /**
+     * Tears down the live video stream for the session's page. Safe to call even
+     * if no stream is running.
+     *
+     * @throws UNKNOWN_ERROR - the stream could not be stopped
+     *
+     * @example
+     * await browser.stopStream();
+     */
+    stopStream(): Promise<void>;
+    /**
+     * Registers a one-shot "reaction": a background poller (one shared loop per
+     * page) watches for the `match` locator and, as soon as it matches, clicks it
+     * with the full smart-click machinery (scroll, human path, occlusion gate,
+     * evade) — then removes itself. The poller yields to any in-flight input
+     * action and only fires while the pointer is idle, so a reaction naturally
+     * slots into the gaps of a retrying foreground action (e.g. it dismisses a
+     * newsletter modal blocking a {@link CloudBrowser.click}, after which the
+     * click's own retry succeeds). Reactions are scoped to the page and torn
+     * down automatically when the page/session ends.
+     *
+     * `match` must be a `css()` or `js()` {@link Locator} — `node()`/`at()` are
+     * rejected. Use `.inAllFrames()` to watch every frame and `.visible(false)`
+     * to opt out of the default visibility gate. Pass a `ReactionOpts` to click a
+     * different target (`on`), change the button/click count, or the poll cadence.
+     *
+     * @param match - the css()/js() locator to watch for
+     * @param opts - optional reaction customization; see {@link ReactionOpts}
+     *
+     * @returns the reactionId (pass to {@link CloudBrowser.removeReaction})
+     *
+     * @throws {@link BrowserScaleError} - `match` (or `opts.on`) is not a css()/js()
+     *   locator, or a server/transport error
+     *
+     * @example
+     * // Auto-dismiss a consent button whenever it appears, in any frame.
+     * const id = await browser.addReaction(css("button#accept").inAllFrames());
+     *
+     * @example
+     * // Watch for a newsletter modal, but click its close "X" instead.
+     * const id = await browser.addReaction(css("#newsletter-modal"), {
+     *   on: css(".modal-close"),
+     * });
+     */
+    addReaction(match: Locator, opts?: ReactionOpts): Promise<string>;
+    /**
+     * Removes a pending reaction by id. Returns `false` if the reaction had
+     * already fired (one-shot) or was never registered.
+     *
+     * @param reactionId - id returned by {@link CloudBrowser.addReaction}
+     *
+     * @returns true if a pending reaction with this id existed and was removed
+     *
+     * @example
+     * const removed = await browser.removeReaction(id);
+     */
+    removeReaction(reactionId: string): Promise<boolean>;
+    /**
+     * Returns the still-pending reactions registered for the current page.
+     * Reactions that have already fired (one-shot) are not included.
+     *
+     * @returns the pending reactions for the page
+     *
+     * @example
+     * const pending = await browser.listReactions();
+     * for (const r of pending) console.log(r.reactionId, r.matchSelector);
+     */
+    listReactions(): Promise<ReactionInfo[]>;
+    /**
+     * @internal — a reaction match/action must be a css()/js() locator: node()
+     * and at() are rejected (a reaction watches for a condition, like a wait).
+     */
+    private assertReactionLocator;
 }

package/dist/client.js

@@ -2,7 +2,7 @@ import { createClient } from "@connectrpc/connect";
 import { create } from "@bufbuild/protobuf";
 import { Browser, 
 // request / response schemas
-SetProxyRequestSchema, GetPagesRequestSchema, NavigateRequestSchema, LoadHTMLRequestSchema, EvaluateRequestSchema, WaitForAnyParamsSchema, WaitConditionSchema, ClickRequestSchema, FillRequestSchema, MoveToRequestSchema, ScrollToRequestSchema, DragRequestSchema, SelectOptionRequestSchema, GetDOMRequestSchema, GetDOMHashRequestSchema, GetObservationRequestSchema, ScreenshotRequestSchema, ReadCanvasRequestSchema, SetBlockListRequestSchema, SetStaticPathsRequestSchema, WaitForAnyRequestRequestSchema, WaitForAnyResponseRequestSchema, ModifyRequestRequestSchema, GetCookiesRequestSchema, SetCookiesRequestSchema, ClearCookiesRequestSchema, GetStorageRequestSchema, SetStorageRequestSchema, ClearStorageRequestSchema, InspectAtPositionRequestSchema, HighlightNodeRequestSchema, InsertTextRequestSchema, PressKeyRequestSchema, ReleaseKeyRequestSchema, GetSelectionRequestSchema, SolveCaptchaRequestSchema, } from "./gen/wrc_pb.js";
+SetProxyRequestSchema, GetPagesRequestSchema, NavigateRequestSchema, LoadHTMLRequestSchema, EvaluateRequestSchema, WaitForAnyParamsSchema, WaitConditionSchema, ClickRequestSchema, FillRequestSchema, MoveToRequestSchema, ScrollToRequestSchema, DragRequestSchema, SelectOptionRequestSchema, GetDOMRequestSchema, GetDOMHashRequestSchema, GetObservationRequestSchema, ScreenshotRequestSchema, ReadCanvasRequestSchema, SetBlockListRequestSchema, SetStaticPathsRequestSchema, WaitForAnyRequestRequestSchema, WaitForAnyResponseRequestSchema, ModifyRequestRequestSchema, GetCookiesRequestSchema, SetCookiesRequestSchema, ClearCookiesRequestSchema, GetStorageRequestSchema, SetStorageRequestSchema, ClearStorageRequestSchema, InspectAtPositionRequestSchema, HighlightNodeRequestSchema, InsertTextRequestSchema, TypeRequestSchema, PressKeyRequestSchema, ReleaseKeyRequestSchema, GetSelectionRequestSchema, SolveCaptchaRequestSchema, GetStreamConfigRequestSchema, StartStreamRequestSchema, StopStreamRequestSchema, AddReactionRequestSchema, RemoveReactionRequestSchema, ListReactionsRequestSchema, } from "./gen/wrc_pb.js";
 import { DefaultWaitTimeoutMs } from "./defaults.js";
 import { BrowserScaleError } from "./errors.js";
 import { cookieParamFromProto, cookieParamsToProto, elementFields, headerModsToProto, headersToProto, interceptedRequestFromProto, interceptedResponseFromProto, pageInfoFromProto, rectFromProto, splitRequestPatterns, storageEntriesToProto, storageEntryFromProto, unwrapClick, unwrapDrag, unwrapFill, unwrapMove, unwrapScroll, unwrapSelect, unwrapWait, } from "./internal/convert.js";
@@ -437,6 +437,10 @@ export class CloudBrowser {
         });
         if (opts?.clearFirst)
             req.clearFirst = true;
+        if (opts?.timeoutMs !== undefined)
+            req.timeout = opts.timeoutMs;
+        if (opts?.steadyMs !== undefined)
+            req.steadyTime = opts.steadyMs;
         return unwrapFill(await this.client.fill(req));
     }
     /**
@@ -701,38 +705,70 @@ export class CloudBrowser {
         return resp.hash;
     }
     /**
-     * Returns a compact, agent-friendly description of every interactable
-     * element currently visible on the page, together with a truncated view
-     * of the surrounding text.
+     * Returns a compact, frame-aware view of the visible page — the first thing
+     * to reach for on an unfamiliar page, and the cheapest way to re-read the
+     * current state afterwards.
+     *
+     * Each frame opens with header lines carrying the URL, the title and the
+     * scroll position, then one line per visible element:
+     *
+     * ```
+     * input#email[47] type="email" name="loginId" value="a@b.com" required click "E-Mail"
+     * ```
+     *
+     * It spans every frame, pierces open and closed shadow roots, enumerates
+     * `<select>` options, and reports live form state: `value=` is what is typed
+     * in right now (passwords as a length), `checked=` for boxes. The trailing
+     * quoted string is always the label or text, never the value, so an empty and
+     * a prefilled field stay distinguishable. Because the headers already carry
+     * URL, title and scroll offset, this replaces the usual handful of
+     * {@link evaluate} probes after each step.
      *
-     * Intended as input for LLM/agent loops where a full DOM dump would be
-     * too large; the server filters down to elements that are actually
-     * visible and interactable.
+     * On what to do with the result: backendNodeId (the `47` above) is a handle
+     * for this session and can be passed straight to click/fill via
+     * {@link node}. It does not survive a new document, so for anything you write
+     * into a script, target with {@link css} or {@link js} instead — those calls
+     * return the backendNodeId they resolved to, which lets you confirm the
+     * durable anchor hits the element you saw.
      *
-     * @param opts - optional caps: `maxElementsPerFrame`, `maxTextLength`;
-     *   omit either to use the server default
+     * @param opts - optional format and budget overrides; see {@link GetObservationOpts}
      *
-     * @returns ObservationResult with both a human-readable `text` rendering
-     *   and a `json` payload of the structured observation
+     * @returns the observation in the requested format, ready to hand to a model
      *
      * @throws UNKNOWN_ERROR - the observation could not be produced
      *
      * @example
-     * const obs = await browser.getObservation({ maxElementsPerFrame: 200 });
-     * console.log(obs.text);
+     * const obs = await browser.getObservation();
+     * console.log(obs);
      */
     async getObservation(opts) {
         const req = create(GetObservationRequestSchema, {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
         });
+        if (opts?.format !== undefined)
+            req.format = opts.format;
         if (opts?.maxElementsPerFrame !== undefined) {
             req.maxElementsPerFrame = opts.maxElementsPerFrame;
         }
         if (opts?.maxTextLength !== undefined)
             req.maxTextLength = opts.maxTextLength;
+        if (opts?.maxTotalTokens !== undefined)
+            req.maxTotalTokens = opts.maxTotalTokens;
+        if (opts?.includeBounds !== undefined)
+            req.includeBounds = opts.includeBounds;
+        if (opts?.viewportOnly !== undefined)
+            req.viewportOnly = opts.viewportOnly;
+        if (opts?.backendNodeId !== undefined)
+            req.backendNodeId = opts.backendNodeId;
+        if (opts?.selector !== undefined)
+            req.selector = opts.selector;
+        if (opts?.jsExpression !== undefined)
+            req.jsExpression = opts.jsExpression;
+        if (opts?.frameId !== undefined)
+            req.frameId = opts.frameId;
         const resp = await this.client.getObservation(req);
-        return { text: resp.observationText, json: resp.observationJson };
+        return resp.observation;
     }
     /**
      * Captures a single image of the page's current frame and returns it as
@@ -1243,6 +1279,43 @@ export class CloudBrowser {
             text,
         }));
     }
+    /**
+     * Types `text` into the currently focused element as a per-key stream of real
+     * keyboard events (keyDown/char/keyUp with the context's QWERTZ/QWERTY layout
+     * and human cadence) — unlike {@link insertText}, a single IME-style commit
+     * with no key events.
+     *
+     * `type` is intentionally UNtargeted and loose: it does not locate or focus
+     * any element and does NOT pin focus, so the page is free to route keys and
+     * move focus between fields mid-stream — ideal for one-time-code / OTP inputs
+     * that auto-advance to the next box on each digit. To type one specific field
+     * that must stay focused for the whole value, use {@link fill} instead
+     * (strict, target-bound, per-key focus-verified).
+     *
+     * Nothing is focused for you: {@link click} (or {@link fill}) the field first,
+     * or otherwise ensure focus, before calling `type`.
+     *
+     * @param text - the text to type as real key events
+     * @param opts - optional: `clearFirst` clears the focused field (Ctrl+A,
+     *   Delete) before typing
+     *
+     * @throws UNKNOWN_ERROR - the page/context was torn down mid-stream
+     *
+     * @example
+     * // OTP field that auto-advances across boxes.
+     * await browser.click(css("input.otp-0"));
+     * await browser.type("123456");
+     */
+    async type(text, opts) {
+        const req = create(TypeRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+            text,
+        });
+        if (opts?.clearFirst)
+            req.clearFirst = true;
+        await this.client.type(req);
+    }
     /**
      * Fires a single key-down event.
      *
@@ -1358,4 +1431,198 @@ export class CloudBrowser {
         }));
         return resp.result;
     }
+    // ──────────────────────────────────────────────────────────────────
+    // Live streaming (WebRTC)
+    // ──────────────────────────────────────────────────────────────────
+    /**
+     * Returns the ICE servers (TURN URL + short-lived credentials) to put in
+     * your `RTCPeerConnection` BEFORE creating the offer, so it can gather relay
+     * candidates.
+     *
+     * Live streaming is a two-step, client-offerer handshake: call
+     * `getStreamConfig`, build your peer with the returned servers, create an
+     * offer, then pass its SDP to {@link startStream} and apply the answer.
+     *
+     * @returns the ICE servers for the client `RTCPeerConnection`
+     *
+     * @throws UNKNOWN_ERROR - TURN is not configured on the server
+     *
+     * @example
+     * const ice = await browser.getStreamConfig();
+     * const pc = new RTCPeerConnection({ iceServers: ice });
+     */
+    async getStreamConfig() {
+        const resp = await this.client.getStreamConfig(create(GetStreamConfigRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+        }));
+        return resp.iceServers.map((s) => ({
+            urls: s.urls,
+            username: s.username ?? "",
+            credential: s.credential ?? "",
+        }));
+    }
+    /**
+     * Answers your WebRTC SDP offer and starts streaming the page as a video
+     * track, returning the SDP answer to set as your peer's remote description.
+     * The browser is the answerer; you are the offerer (see
+     * {@link getStreamConfig} for the credentials to build the offer).
+     *
+     * @param offerSdp - your `RTCPeerConnection`'s SDP offer
+     *
+     * @returns the SDP answer to apply as the remote description
+     *
+     * @throws UNKNOWN_ERROR - the offer was empty, TURN is unconfigured, or the
+     *   browser could not negotiate the stream
+     *
+     * @example
+     * const answer = await browser.startStream(offer.sdp);
+     * await pc.setRemoteDescription({ type: "answer", sdp: answer });
+     */
+    async startStream(offerSdp) {
+        const resp = await this.client.startStream(create(StartStreamRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+            offerSdp,
+        }));
+        return resp.answerSdp;
+    }
+    /**
+     * Tears down the live video stream for the session's page. Safe to call even
+     * if no stream is running.
+     *
+     * @throws UNKNOWN_ERROR - the stream could not be stopped
+     *
+     * @example
+     * await browser.stopStream();
+     */
+    async stopStream() {
+        await this.client.stopStream(create(StopStreamRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+        }));
+    }
+    // ──────────────────────────────────────────────────────────────────
+    // Reactions
+    // ──────────────────────────────────────────────────────────────────
+    /**
+     * Registers a one-shot "reaction": a background poller (one shared loop per
+     * page) watches for the `match` locator and, as soon as it matches, clicks it
+     * with the full smart-click machinery (scroll, human path, occlusion gate,
+     * evade) — then removes itself. The poller yields to any in-flight input
+     * action and only fires while the pointer is idle, so a reaction naturally
+     * slots into the gaps of a retrying foreground action (e.g. it dismisses a
+     * newsletter modal blocking a {@link CloudBrowser.click}, after which the
+     * click's own retry succeeds). Reactions are scoped to the page and torn
+     * down automatically when the page/session ends.
+     *
+     * `match` must be a `css()` or `js()` {@link Locator} — `node()`/`at()` are
+     * rejected. Use `.inAllFrames()` to watch every frame and `.visible(false)`
+     * to opt out of the default visibility gate. Pass a `ReactionOpts` to click a
+     * different target (`on`), change the button/click count, or the poll cadence.
+     *
+     * @param match - the css()/js() locator to watch for
+     * @param opts - optional reaction customization; see {@link ReactionOpts}
+     *
+     * @returns the reactionId (pass to {@link CloudBrowser.removeReaction})
+     *
+     * @throws {@link BrowserScaleError} - `match` (or `opts.on`) is not a css()/js()
+     *   locator, or a server/transport error
+     *
+     * @example
+     * // Auto-dismiss a consent button whenever it appears, in any frame.
+     * const id = await browser.addReaction(css("button#accept").inAllFrames());
+     *
+     * @example
+     * // Watch for a newsletter modal, but click its close "X" instead.
+     * const id = await browser.addReaction(css("#newsletter-modal"), {
+     *   on: css(".modal-close"),
+     * });
+     */
+    async addReaction(match, opts) {
+        this.assertReactionLocator("addReaction", match, "match");
+        const req = create(AddReactionRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+        });
+        if (match.selector)
+            req.matchSelector = match.selector;
+        if (match.jsExpression)
+            req.matchJsExpression = match.jsExpression;
+        if (match.frameId)
+            req.frameId = match.frameId;
+        if (match.visibleFlag !== undefined)
+            req.visible = match.visibleFlag;
+        if (opts?.on) {
+            this.assertReactionLocator("addReaction", opts.on, "on");
+            if (opts.on.selector)
+                req.actionSelector = opts.on.selector;
+            if (opts.on.jsExpression)
+                req.actionJsExpression = opts.on.jsExpression;
+        }
+        if (opts?.button)
+            req.button = opts.button;
+        if (opts?.clickCount)
+            req.clickCount = opts.clickCount;
+        if (opts?.intervalMs)
+            req.interval = opts.intervalMs;
+        const resp = await this.client.addReaction(req);
+        return resp.reactionId;
+    }
+    /**
+     * Removes a pending reaction by id. Returns `false` if the reaction had
+     * already fired (one-shot) or was never registered.
+     *
+     * @param reactionId - id returned by {@link CloudBrowser.addReaction}
+     *
+     * @returns true if a pending reaction with this id existed and was removed
+     *
+     * @example
+     * const removed = await browser.removeReaction(id);
+     */
+    async removeReaction(reactionId) {
+        const resp = await this.client.removeReaction(create(RemoveReactionRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+            reactionId,
+        }));
+        return resp.removed;
+    }
+    /**
+     * Returns the still-pending reactions registered for the current page.
+     * Reactions that have already fired (one-shot) are not included.
+     *
+     * @returns the pending reactions for the page
+     *
+     * @example
+     * const pending = await browser.listReactions();
+     * for (const r of pending) console.log(r.reactionId, r.matchSelector);
+     */
+    async listReactions() {
+        const resp = await this.client.listReactions(create(ListReactionsRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+        }));
+        return resp.reactions.map((r) => ({
+            reactionId: r.reactionId,
+            matchSelector: r.matchSelector ?? "",
+            matchJsExpression: r.matchJsExpression ?? "",
+            actionSelector: r.actionSelector ?? "",
+            actionJsExpression: r.actionJsExpression ?? "",
+            frameId: r.frameId,
+            visible: r.visible,
+        }));
+    }
+    /**
+     * @internal — a reaction match/action must be a css()/js() locator: node()
+     * and at() are rejected (a reaction watches for a condition, like a wait).
+     */
+    assertReactionLocator(cmd, l, role) {
+        if (l.backendNodeId !== 0 || l.x !== undefined || l.y !== undefined) {
+            throw new BrowserScaleError(`browserscale.${cmd}: ${role} must be a css()/js() locator (node()/at() are not valid)`);
+        }
+        if (!l.selector && !l.jsExpression) {
+            throw new BrowserScaleError(`browserscale.${cmd}: ${role} must have a CSS selector or JS expression`);
+        }
+    }
 }

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import type { DragResult, ElementResult, OccluderInfo, SelectOptionResult, WaitConditionStatus, WaitResult } from "./types.ts";
+import type { DragResult, ElementRef, ElementResult, OccluderInfo, SelectOptionResult, WaitConditionStatus, WaitResult } from "./types.ts";
 /**
  * BrowserScaleError is the base class for every error thrown by the SDK. It
  * wraps either:
@@ -60,21 +60,48 @@ export declare class ClickError extends BrowserScaleError {
 }
 /**
  * FillError is thrown by {@link CloudBrowser.fill} when the field could not be
- * focused/typed. Fill focuses with the exact same smart click as
- * {@link CloudBrowser.click}, so a pre-typing failure is a click failure:
- * `code` mirrors it and the full click diagnostics live under `clickError`.
+ * focused/typed. The click-phase codes (`"not_found"`,
+ * `"occluded_no_reachable_point"`, `"occluded_after_evade"`) mirror the
+ * underlying focus click, with diagnostics under `clickError`. The focus codes
+ * are `"focus_stolen"` (another element took focus — `focusedElement` names it;
+ * fill is strictly target-bound and will not type into the thief) and
+ * `"focus_lost"` (focus left the target and nothing is focused). For untargeted
+ * stream typing that lets focus move (e.g. OTP), use {@link CloudBrowser.type}.
  */
 export declare class FillError extends BrowserScaleError {
-    /** Mirrored from the underlying click failure. */
+    /** Machine-stable failure code (see the class doc for the full set). */
     readonly code: string;
-    /** The underlying click-core failure that prevented focusing/typing. */
+    /**
+     * The underlying click-core failure that prevented focusing/typing. Present
+     * for the click-phase codes; undefined for `"focus_stolen"`/`"focus_lost"`.
+     */
     readonly clickError?: ClickError;
+    /**
+     * Node that held focus when fill gave up (0 if nothing was focused), for the
+     * `"focus_stolen"`/`"focus_lost"` codes.
+     */
+    readonly focusedBackendNodeId?: number;
+    /**
+     * The element that grabbed focus instead of the target (`"focus_stolen"`), so
+     * you can act on it (e.g. a consent button).
+     */
+    readonly focusedElement?: ElementRef;
+    /**
+     * The fill target's own state at the point of failure (the focus codes):
+     * whether it is still an editable text sink and its current text length.
+     */
+    readonly targetEditable?: boolean;
+    readonly targetValueLength?: number;
     /** Resolved element + coordinates at the failed action (success is false). */
     readonly result: ElementResult;
     constructor(init: {
         code: string;
         message: string;
         clickError?: ClickError;
+        focusedBackendNodeId?: number;
+        focusedElement?: ElementRef;
+        targetEditable?: boolean;
+        targetValueLength?: number;
         result: ElementResult;
     });
 }

package/dist/errors.js

@@ -48,9 +48,13 @@ export class ClickError extends BrowserScaleError {
 }
 /**
  * FillError is thrown by {@link CloudBrowser.fill} when the field could not be
- * focused/typed. Fill focuses with the exact same smart click as
- * {@link CloudBrowser.click}, so a pre-typing failure is a click failure:
- * `code` mirrors it and the full click diagnostics live under `clickError`.
+ * focused/typed. The click-phase codes (`"not_found"`,
+ * `"occluded_no_reachable_point"`, `"occluded_after_evade"`) mirror the
+ * underlying focus click, with diagnostics under `clickError`. The focus codes
+ * are `"focus_stolen"` (another element took focus — `focusedElement` names it;
+ * fill is strictly target-bound and will not type into the thief) and
+ * `"focus_lost"` (focus left the target and nothing is focused). For untargeted
+ * stream typing that lets focus move (e.g. OTP), use {@link CloudBrowser.type}.
  */
 export class FillError extends BrowserScaleError {
     constructor(init) {
@@ -58,6 +62,10 @@ export class FillError extends BrowserScaleError {
         this.name = "FillError";
         this.code = init.code;
         this.clickError = init.clickError;
+        this.focusedBackendNodeId = init.focusedBackendNodeId;
+        this.focusedElement = init.focusedElement;
+        this.targetEditable = init.targetEditable;
+        this.targetValueLength = init.targetValueLength;
         this.result = init.result;
     }
 }