spider-browser 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1223 @@
+import { z } from 'zod';
+
+/** Browser types supported by spider's backend. */
+type BrowserType = 'chrome' | 'chrome-new' | 'chrome-h' | 'firefox' | 'servo' | 'lightpanda' | 'auto';
+/** All events emitted by SpiderBrowser. */
+interface SpiderEvents {
+    /** WebSocket connection opened. */
+    'ws.open': {};
+    /** WebSocket connection closed. */
+    'ws.close': {
+        code: number;
+        reason: string;
+    };
+    /** WebSocket error. */
+    'ws.error': {
+        error: Error;
+    };
+    /** Captcha was detected on the page. */
+    'captcha.detected': {
+        types: string[];
+        url: string;
+    };
+    /** Captcha solver is running. */
+    'captcha.solving': {
+        types: string[];
+        url: string;
+        round: number;
+    };
+    /** Captcha was solved. */
+    'captcha.solved': {
+        url: string;
+    };
+    /** Captcha solving failed. */
+    'captcha.failed': {
+        url: string;
+        reason: string;
+    };
+    /** Smart retry is switching browsers. */
+    'browser.switching': {
+        from: BrowserType;
+        to: BrowserType;
+        reason: string;
+    };
+    /** Browser switched successfully. */
+    'browser.switched': {
+        browser: BrowserType;
+    };
+    /** Retry attempt. */
+    'retry.attempt': {
+        attempt: number;
+        maxRetries: number;
+        error: string;
+    };
+    /** Stealth level escalated (proxy tier upgraded). */
+    'stealth.escalated': {
+        from: number;
+        to: number;
+        reason: string;
+    };
+    /** Metering data from server (credits remaining, cost rate, session cost). */
+    'metering': {
+        credits: number;
+        rate: number;
+        session_credits_used?: number;
+    };
+    /** Page navigation completed. */
+    'page.navigated': {
+        url: string;
+    };
+    /** Page loaded (DOMContentLoaded or load). */
+    'page.loaded': {
+        url: string;
+    };
+    /** Agent step executed. */
+    'agent.step': {
+        round: number;
+        label: string;
+        stepsCount: number;
+    };
+    /** Agent completed. */
+    'agent.done': {
+        rounds: number;
+        result?: unknown;
+    };
+    /** Agent failed. */
+    'agent.error': {
+        error: string;
+        round: number;
+    };
+}
+type SpiderEventName = keyof SpiderEvents;
+
+type Handler<T> = (data: T) => void;
+/** Type-safe event emitter for SpiderBrowser events. */
+declare class SpiderEventEmitter {
+    private handlers;
+    on<K extends SpiderEventName>(event: K, handler: Handler<SpiderEvents[K]>): this;
+    off<K extends SpiderEventName>(event: K, handler: Handler<SpiderEvents[K]>): this;
+    once<K extends SpiderEventName>(event: K, handler: Handler<SpiderEvents[K]>): this;
+    emit<K extends SpiderEventName>(event: K, data: SpiderEvents[K]): void;
+    removeAllListeners(event?: SpiderEventName): void;
+}
+
+interface TransportOptions {
+    apiKey: string;
+    serverUrl: string;
+    browser: BrowserType;
+    url?: string;
+    captcha?: 'off' | 'detect' | 'solve';
+    /** Stealth level (1-3). 0 or undefined = auto. Controls proxy quality tier on server. */
+    stealthLevel?: number;
+    /** WebSocket connect timeout in ms (default: 30000). */
+    connectTimeoutMs?: number;
+    /** CDP/BiDi command timeout in ms (default: 30000). Passed through to sessions. */
+    commandTimeoutMs?: number;
+}
+/**
+ * WebSocket transport to Spider's browser_server.
+ *
+ * Connects to `wss://browser.spider.cloud/v1/browser?token=TOKEN&browser=TYPE`,
+ * handles reconnection on browser switch, and dispatches raw messages.
+ */
+declare class Transport {
+    private ws;
+    private messageHandler;
+    private currentBrowser;
+    private opts;
+    private emitter;
+    private _stealthLevel;
+    /** Generation counter — incremented on each connect. Prevents stale WS messages from being processed. */
+    private generation;
+    /** Credits remaining from last upgrade response (x-sc header). */
+    private _upgradeCredits;
+    /** Stealth tier from last upgrade response (x-sr header). */
+    private _upgradeStealthTier;
+    /** Credits consumed during this session (from Spider.metering event). */
+    private _sessionCreditsUsed;
+    constructor(opts: TransportOptions, emitter: SpiderEventEmitter);
+    get browser(): BrowserType;
+    get connected(): boolean;
+    get stealthLevel(): number;
+    set stealthLevel(level: number);
+    /** Credits remaining from the WebSocket upgrade response. */
+    get upgradeCredits(): number | undefined;
+    /** Active stealth tier from the WebSocket upgrade response. */
+    get upgradeStealthTier(): number | undefined;
+    /** Credits consumed during this session (from server Spider.metering event). */
+    get sessionCreditsUsed(): number | undefined;
+    /**
+     * Request the current session cost from the server via Spider.getMetering.
+     * This is a synchronous CDP-style request/response — no event-loop timing issues.
+     * Returns the credits used so far, or the last known value if the request fails.
+     */
+    requestMetering(timeoutMs?: number): Promise<number>;
+    /** Set the handler that receives raw JSON messages from the WebSocket. */
+    onMessage(handler: (data: string) => void): void;
+    /** Connect to the browser_server WebSocket with retry. */
+    connect(maxAttempts?: number): Promise<void>;
+    /** Reconnect with a different browser type (used by retry engine). */
+    reconnect(browser: BrowserType): Promise<void>;
+    /** Send a raw JSON string through the WebSocket. */
+    send(data: string): void;
+    /** Close the WebSocket connection, removing event listeners to prevent data mixing. */
+    close(): void;
+    private buildUrl;
+    private connectInternal;
+}
+
+/**
+ * Unified protocol interface that wraps either CDPSession or BiDiSession
+ * based on the browser type.
+ *
+ * - chrome, chrome-new, chrome-h, servo, lightpanda → CDP
+ * - firefox → BiDi
+ */
+interface ProtocolAdapterOptions {
+    commandTimeoutMs?: number;
+}
+declare class ProtocolAdapter {
+    private cdp;
+    private bidi;
+    private transport;
+    private emitter;
+    private protocol;
+    private adapterOpts;
+    constructor(transport: Transport, emitter: SpiderEventEmitter, browser: BrowserType, opts?: ProtocolAdapterOptions);
+    /** Whether this adapter uses CDP or BiDi (or 'auto' before init). */
+    get protocolType(): 'cdp' | 'bidi' | 'auto';
+    /** Route incoming WebSocket messages to the right session + spider events. */
+    private routeMessage;
+    /** Handle Spider.* custom events from the browser_server. */
+    private handleSpiderEvent;
+    /**
+     * Initialize the protocol session.
+     *
+     * For CDP (Chrome/Servo/LightPanda): discovers page targets, attaches to one
+     * with flatten:true to get a sessionId, then enables Page + Runtime domains
+     * on that target. This is required because browser_server proxies to Chrome's
+     * browser-level CDP endpoint.
+     *
+     * For BiDi (Firefox): gets or creates a browsing context.
+     *
+     * For "auto" mode: tries CDP first (Target.setDiscoverTargets). If it fails
+     * (e.g. we actually got a BiDi session), falls back to BiDi.
+     */
+    init(): Promise<void>;
+    /**
+     * Auto-detect protocol by trying CDP first, falling back to BiDi.
+     * Used when browser type is "auto" and we don't know what the server gave us.
+     */
+    private autoDetectAndInit;
+    /** Navigate to URL. */
+    navigate(url: string): Promise<void>;
+    /** Get page HTML. */
+    getHTML(): Promise<string>;
+    /** Evaluate JavaScript expression. */
+    evaluate(expression: string): Promise<unknown>;
+    /** Capture screenshot as base64 PNG. */
+    captureScreenshot(): Promise<string>;
+    /** Click at viewport coordinates. */
+    clickPoint(x: number, y: number): Promise<void>;
+    /** Right-click at coordinates. */
+    rightClickPoint(x: number, y: number): Promise<void>;
+    /** Double-click at coordinates. */
+    doubleClickPoint(x: number, y: number): Promise<void>;
+    /** Click and hold at coordinates. */
+    clickHoldPoint(x: number, y: number, holdMs: number): Promise<void>;
+    /** Hover at coordinates. */
+    hoverPoint(x: number, y: number): Promise<void>;
+    /** Smooth drag from point to point. */
+    dragPoint(fromX: number, fromY: number, toX: number, toY: number): Promise<void>;
+    /** Insert text. */
+    insertText(text: string): Promise<void>;
+    /** Press a named key (e.g. "Enter", "Tab"). */
+    pressKey(keyName: string): Promise<void>;
+    /** Send keyDown. */
+    keyDown(keyName: string): Promise<void>;
+    /** Send keyUp. */
+    keyUp(keyName: string): Promise<void>;
+    /** Set viewport dimensions. */
+    setViewport(width: number, height: number, deviceScaleFactor?: number, mobile?: boolean): Promise<void>;
+    /** Subscribe to a CDP domain event (only relevant for CDP). */
+    onProtocolEvent(method: string, handler: (params: Record<string, unknown>) => void): void;
+    /** Clean up resources. Nulls references first to prevent stale message routing. */
+    destroy(): void;
+}
+
+/**
+ * SpiderPage — deterministic browser tab abstraction.
+ *
+ * All standard browser automation methods (no LLM required).
+ * Works over both CDP (Chrome/Servo/LightPanda) and BiDi (Firefox)
+ * through the ProtocolAdapter.
+ */
+declare class SpiderPage {
+    private adapter;
+    /** @internal */
+    constructor(adapter: ProtocolAdapter);
+    /** Navigate to a URL and wait for load. */
+    goto(url: string): Promise<void>;
+    /** Go back in browser history. */
+    goBack(): Promise<void>;
+    /** Go forward in browser history. */
+    goForward(): Promise<void>;
+    /** Reload the page. */
+    reload(): Promise<void>;
+    /**
+     * Get the full page HTML, ensuring the page is ready first.
+     *
+     * Waits for network idle + DOM stability, then checks content quality.
+     * If the content seems incomplete (too short or looks like a loading state),
+     * does incremental waits with exponential backoff before returning.
+     *
+     * @param waitMs Max time to wait for readiness (default: 8000ms).
+     *               Pass 0 to skip readiness checks and return immediately.
+     * @param minLength Minimum content length to consider "good" (default: 1000).
+     */
+    content(waitMs?: number, minLength?: number): Promise<string>;
+    /**
+     * Get the raw page HTML without any readiness waiting.
+     * Use this when you need immediate access or have already waited.
+     */
+    rawContent(): Promise<string>;
+    /** Get the page title. */
+    title(): Promise<string>;
+    /** Get the current page URL. */
+    url(): Promise<string>;
+    /** Capture a screenshot as base64 PNG. */
+    screenshot(): Promise<string>;
+    /** Evaluate arbitrary JavaScript and return the result. */
+    evaluate(expression: string): Promise<unknown>;
+    /** Click an element by CSS selector. */
+    click(selector: string): Promise<void>;
+    /** Click at specific viewport coordinates. */
+    clickAt(x: number, y: number): Promise<void>;
+    /** Double-click an element by CSS selector. */
+    dblclick(selector: string): Promise<void>;
+    /** Right-click an element by CSS selector. */
+    rightClick(selector: string): Promise<void>;
+    /** Click all elements matching a selector. */
+    clickAll(selector: string): Promise<void>;
+    /** Fill a form field — focus, clear existing value, type new value. */
+    fill(selector: string, value: string): Promise<void>;
+    /** Type text into the currently focused element. */
+    type(value: string): Promise<void>;
+    /** Press a named key (e.g. "Enter", "Tab", "Escape"). */
+    press(key: string): Promise<void>;
+    /** Clear an input field. */
+    clear(selector: string): Promise<void>;
+    /** Select an option in a <select> element. */
+    select(selector: string, value: string): Promise<void>;
+    /** Focus an element. */
+    focus(selector: string): Promise<void>;
+    /** Blur (unfocus) an element. */
+    blur(selector: string): Promise<void>;
+    /** Hover over an element. */
+    hover(selector: string): Promise<void>;
+    /** Drag from one element to another. */
+    drag(fromSelector: string, toSelector: string): Promise<void>;
+    /** Scroll vertically by pixels (positive = down). */
+    scrollY(pixels: number): Promise<void>;
+    /** Scroll horizontally by pixels (positive = right). */
+    scrollX(pixels: number): Promise<void>;
+    /** Scroll an element into view. */
+    scrollTo(selector: string): Promise<void>;
+    /** Scroll to absolute page coordinates. */
+    scrollToPoint(x: number, y: number): Promise<void>;
+    /** Wait for a CSS selector to appear in the DOM. */
+    waitForSelector(selector: string, timeoutMs?: number): Promise<void>;
+    /** Wait for navigation/page load (simple delay). */
+    waitForNavigation(timeoutMs?: number): Promise<void>;
+    /**
+     * Wait until the page is fully loaded and DOM is stable.
+     *
+     * Checks:
+     * 1. document.readyState === 'complete'
+     * 2. DOM content length stabilizes (no changes for 500ms)
+     *
+     * Use after goto() for SPAs and dynamic pages to ensure all
+     * content is rendered before extracting HTML.
+     */
+    waitForReady(timeoutMs?: number): Promise<void>;
+    /**
+     * Wait until page content exceeds a minimum length.
+     * Useful for SPAs where content loads asynchronously.
+     */
+    waitForContent(minLength?: number, timeoutMs?: number): Promise<void>;
+    /**
+     * Wait for network idle + DOM stability (cross-platform).
+     *
+     * Uses the Performance/Resource Timing API and MutationObserver
+     * (works in both Chrome/CDP and Firefox/BiDi) to detect when:
+     * 1. document.readyState === 'complete'
+     * 2. No new network resources loading (PerformanceObserver)
+     * 3. DOM mutations have settled
+     *
+     * This is more comprehensive than waitForReady() — it also
+     * catches lazy-loaded images, XHR/fetch requests, and script-injected content.
+     */
+    waitForNetworkIdle(timeoutMs?: number): Promise<void>;
+    /** Set the viewport dimensions. */
+    setViewport(width: number, height: number, deviceScaleFactor?: number, mobile?: boolean): Promise<void>;
+    /** Query a single element and return its outer HTML. */
+    querySelector(selector: string): Promise<string | null>;
+    /** Query all matching elements and return their outer HTML. */
+    querySelectorAll(selector: string): Promise<string[]>;
+    /** Get text content of an element. */
+    textContent(selector: string): Promise<string | null>;
+    /** Get the center coordinates of a DOM element (scrolls into view first). */
+    private getElementCenter;
+    /** @internal Replace the adapter (used during browser switching). */
+    _setAdapter(adapter: ProtocolAdapter): void;
+    /**
+     * Detect challenge interstitials that may auto-resolve (e.g. Cloudflare "Just a moment...").
+     * These pages show briefly before redirecting to the real content.
+     */
+    private isInterstitialContent;
+    /**
+     * Detect site-level rate limiting in page content.
+     * Browser rotation gives a new profile which bypasses per-session rate limits.
+     */
+    private isRateLimitContent;
+}
+
+/** LLM configuration for AI methods. */
+interface LLMConfig {
+    /** Provider: 'openai', 'anthropic', or 'openrouter'. */
+    provider: 'openai' | 'anthropic' | 'openrouter';
+    /** Model name (e.g. 'gpt-4o', 'claude-sonnet-4-5-20250929'). */
+    model: string;
+    /** API key for the provider. */
+    apiKey: string;
+    /** Base URL override (e.g. for OpenRouter or local vLLM). */
+    baseUrl?: string;
+    /** Max tokens (default: 4096). */
+    maxTokens?: number;
+    /** Temperature (default: 0.1). */
+    temperature?: number;
+}
+/** Message format for LLM calls. */
+interface LLMMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string | LLMContentPart[];
+}
+type LLMContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image_url';
+    image_url: {
+        url: string;
+    };
+};
+/** Pluggable LLM provider interface. */
+interface LLMProvider {
+    /** Call the LLM with messages and get a text response. */
+    chat(messages: LLMMessage[], options?: {
+        jsonMode?: boolean;
+    }): Promise<string>;
+    /** Call the LLM with messages and get a parsed JSON response. */
+    chatJSON<T = unknown>(messages: LLMMessage[]): Promise<T>;
+}
+/** Create an LLM provider from config. */
+declare function createProvider(config: LLMConfig): LLMProvider;
+
+/** An observed interactive element on the page. */
+interface ObserveResult {
+    /** CSS selector that can target this element. */
+    selector: string;
+    /** HTML tag name. */
+    tag: string;
+    /** Input type (for input elements). */
+    type: string;
+    /** Visible text content (truncated). */
+    text: string;
+    /** aria-label attribute. */
+    ariaLabel: string;
+    /** Placeholder text. */
+    placeholder: string;
+    /** href attribute (for links). */
+    href: string;
+    /** Current input value (for inputs/textareas). */
+    value: string;
+    /** Bounding rectangle in viewport coordinates. */
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Relevance score (0-1) when LLM ranking is used. */
+    score?: number;
+}
+/**
+ * Discover interactive elements on the page.
+ *
+ * Works WITHOUT an LLM — injects a DOM traversal script to collect
+ * interactive elements (buttons, links, inputs) with selectors, text,
+ * and bounding rects.
+ *
+ * When instruction is provided + LLM is available, adds ranking/filtering.
+ */
+declare function observe(adapter: ProtocolAdapter, instruction?: string, llm?: LLMProvider): Promise<ObserveResult[]>;
+
+/** All possible agent actions — mirrors browser_server/src/ai/actions.rs. */
+type AgentAction = {
+    Click: string;
+} | {
+    ClickAll: string;
+} | {
+    ClickPoint: {
+        x: number;
+        y: number;
+    };
+} | {
+    ClickHold: {
+        selector: string;
+        hold_ms: number;
+    };
+} | {
+    ClickHoldPoint: {
+        x: number;
+        y: number;
+        hold_ms: number;
+    };
+} | {
+    DoubleClick: string;
+} | {
+    DoubleClickPoint: {
+        x: number;
+        y: number;
+    };
+} | {
+    RightClick: string;
+} | {
+    RightClickPoint: {
+        x: number;
+        y: number;
+    };
+} | {
+    WaitForAndClick: string;
+} | {
+    ClickDrag: {
+        from: string;
+        to: string;
+        modifier?: number;
+    };
+} | {
+    ClickDragPoint: {
+        from_x: number;
+        from_y: number;
+        to_x: number;
+        to_y: number;
+        modifier?: number;
+    };
+} | {
+    Type: {
+        value: string;
+    };
+} | {
+    Fill: {
+        selector: string;
+        value: string;
+    };
+} | {
+    Clear: string;
+} | {
+    Press: string;
+} | {
+    KeyDown: string;
+} | {
+    KeyUp: string;
+} | {
+    Select: {
+        selector: string;
+        value: string;
+    };
+} | {
+    Focus: string;
+} | {
+    Blur: string;
+} | {
+    Hover: string;
+} | {
+    HoverPoint: {
+        x: number;
+        y: number;
+    };
+} | {
+    ScrollY: number;
+} | {
+    ScrollX: number;
+} | {
+    ScrollTo: {
+        selector: string;
+    };
+} | {
+    ScrollToPoint: {
+        x: number;
+        y: number;
+    };
+} | {
+    InfiniteScroll: number;
+} | {
+    Wait: number;
+} | {
+    WaitFor: string;
+} | {
+    WaitForWithTimeout: {
+        selector: string;
+        timeout: number;
+    };
+} | {
+    WaitForNavigation: null;
+} | {
+    WaitForDom: {
+        selector?: string;
+        timeout: number;
+    };
+} | {
+    Navigate: string;
+} | {
+    GoBack: null;
+} | {
+    GoForward: null;
+} | {
+    Reload: null;
+} | {
+    SetViewport: {
+        width: number;
+        height: number;
+        device_scale_factor?: number;
+        mobile?: boolean;
+    };
+} | {
+    Evaluate: string;
+} | {
+    Screenshot: null;
+};
+/** Parsed LLM response — mirrors actions.rs AgentPlan. */
+interface AgentPlan {
+    label: string;
+    done: boolean;
+    steps: AgentAction[];
+    extracted?: unknown;
+    memory_ops?: unknown[];
+}
+interface AgentOptions {
+    /** Max automation rounds (default: 30). */
+    maxRounds: number;
+    /** Delay in ms after actions for page settle (default: 1500). */
+    stepDelayMs: number;
+    /** Extra context/instruction for each round. */
+    instruction?: string;
+}
+interface AgentResult {
+    /** Whether the agent completed the task. */
+    done: boolean;
+    /** Number of rounds executed. */
+    rounds: number;
+    /** Extracted data (accumulated across rounds). */
+    extracted?: unknown;
+    /** Final label from the agent. */
+    label: string;
+}
+/**
+ * Autonomous multi-step agent.
+ *
+ * Uses the same action vocabulary and system prompt as Spider's
+ * server-side captcha solver (browser_server/src/ai/agent.rs).
+ *
+ * Loop: screenshot → HTML → LLM → parse plan → execute actions → repeat.
+ */
+declare class Agent {
+    private adapter;
+    private llm;
+    private emitter;
+    private opts;
+    constructor(adapter: ProtocolAdapter, llm: LLMProvider, emitter: SpiderEventEmitter, options?: Partial<AgentOptions>);
+    /**
+     * Execute the agent loop until the task is done or max rounds reached.
+     */
+    execute(instruction: string): Promise<AgentResult>;
+}
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+declare class Logger {
+    private level;
+    constructor(level?: LogLevel);
+    setLevel(level: LogLevel): void;
+    debug(msg: string, data?: Record<string, unknown>): void;
+    info(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    error(msg: string, data?: Record<string, unknown>): void;
+    private log;
+}
+/** Shared default logger instance. */
+declare const logger: Logger;
+
+interface SpiderBrowserOptions {
+    /** Spider API key (required). */
+    apiKey: string;
+    /** WebSocket server URL (default: wss://browser.spider.cloud). */
+    serverUrl?: string;
+    /** Browser to use (default: auto). */
+    browser?: BrowserType;
+    /** Target URL hint for server browser+proxy selection. */
+    url?: string;
+    /** Captcha handling (default: solve). */
+    captcha?: 'off' | 'detect' | 'solve';
+    /** Enable smart retry with browser switching (default: true). */
+    smartRetry?: boolean;
+    /** Max retry attempts across all browsers (default: 3). */
+    maxRetries?: number;
+    /** Stealth level (1-3). Controls proxy quality tier. 0 or undefined = auto-escalate on failure. */
+    stealth?: number;
+    /** Maximum stealth level to auto-escalate to (1-3, default: 3). */
+    maxStealthLevels?: number;
+    /** LLM configuration for AI methods (optional). */
+    llm?: LLMConfig;
+    /** Log level (default: info). */
+    logLevel?: LogLevel;
+    /** WebSocket connect timeout in ms (default: 30000). */
+    connectTimeoutMs?: number;
+    /** CDP/BiDi command timeout in ms (default: 30000). */
+    commandTimeoutMs?: number;
+    /** Timeout for retry attempts — shorter than first try (default: 15000). */
+    retryTimeoutMs?: number;
+}
+/**
+ * SpiderBrowser — main entry point for spider-browser.
+ *
+ * Connects to Spider's pre-warmed browser fleet via WebSocket.
+ * Provides deterministic page control (via SpiderPage) and
+ * AI-powered automation (act, observe, extract, agent).
+ *
+ * Key features:
+ * - Pre-warmed browsers (no cold start)
+ * - Full stealth Chrome & Firefox
+ * - Smart retry with automatic browser switching
+ * - CDP (Chrome/Servo/LightPanda) + BiDi (Firefox) protocol support
+ */
+declare class SpiderBrowser {
+    private opts;
+    private transport;
+    private adapter;
+    private retryEngine;
+    private emitter;
+    private _page;
+    private llmProvider;
+    private currentUrl;
+    constructor(options: SpiderBrowserOptions);
+    /** The active page instance for deterministic browser control. */
+    get page(): SpiderPage;
+    /** Current browser type. */
+    get browser(): BrowserType;
+    /** Whether the WebSocket is connected. */
+    get connected(): boolean;
+    /** Active stealth level (0=auto, 1-3=explicit tiers). */
+    get stealthLevel(): number;
+    /** Credits remaining from last upgrade response. */
+    get credits(): number | undefined;
+    /** Credits consumed during this session (from server Spider.metering event). */
+    get sessionCreditsUsed(): number | undefined;
+    /**
+     * Request the exact session cost from the server.
+     * Unlike `sessionCreditsUsed` (which relies on async event delivery),
+     * this sends a Spider.getMetering command and waits for the response.
+     * Call this before close() for accurate per-session metering.
+     */
+    getSessionCredits(): Promise<number>;
+    /** Subscribe to events. */
+    on<K extends SpiderEventName>(event: K, handler: (data: SpiderEvents[K]) => void): this;
+    /** Unsubscribe from events. */
+    off<K extends SpiderEventName>(event: K, handler: (data: SpiderEvents[K]) => void): this;
+    /** Subscribe to an event once. */
+    once<K extends SpiderEventName>(event: K, handler: (data: SpiderEvents[K]) => void): this;
+    /**
+     * Connect to the browser server WebSocket and initialize the protocol.
+     */
+    init(): Promise<void>;
+    /**
+     * Execute an action with smart retry. On failure, classifies the error and
+     * may switch browsers, reconnect, re-navigate, and retry.
+     */
+    withRetry<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Navigate to a URL with smart retry.
+     *
+     * On ERR_ABORTED: closes the WebSocket, reconnects, and retries.
+     * On bot detection: switches to a different browser and retries.
+     *
+     * Also updates `currentUrl` for subsequent retries on other operations.
+     */
+    goto(url: string): Promise<void>;
+    /**
+     * Execute a single action from natural language.
+     *
+     * Example: `await browser.act('Click the login button')`
+     */
+    act(instruction: string): Promise<void>;
+    /**
+     * Discover interactive elements on the page.
+     *
+     * Works WITHOUT an LLM — injects DOM traversal to collect elements.
+     * When instruction is provided + LLM is configured, adds ranking/filtering.
+     */
+    observe(instruction?: string): Promise<ObserveResult[]>;
+    /**
+     * Extract structured data from the page.
+     *
+     * Example: `await browser.extract('Product name and price', { schema: z.object({...}) })`
+     */
+    extract<T>(instruction: string, options?: {
+        schema?: z.ZodType<T>;
+    }): Promise<T>;
+    /**
+     * Create an autonomous agent that executes multi-step tasks.
+     *
+     * Uses the same action vocabulary and system prompt as Spider's
+     * server-side captcha solver for consistent behavior.
+     */
+    agent(options?: Partial<AgentOptions>): Agent;
+    /**
+     * Close the connection and clean up resources.
+     */
+    close(): Promise<void>;
+    private requireLLM;
+}
+
+/** CDP JSON-RPC response. */
+interface CDPResponse {
+    id: number;
+    result?: Record<string, unknown>;
+    error?: {
+        code: number;
+        message: string;
+        data?: string;
+    };
+    sessionId?: string;
+}
+/** BiDi response. */
+interface BiDiResponse {
+    id: number;
+    type: 'success' | 'error';
+    result?: Record<string, unknown>;
+    error?: string;
+    message?: string;
+}
+
+type EventHandler$1 = (params: Record<string, unknown>) => void;
+/**
+ * CDP JSON-RPC session over the Spider WebSocket transport.
+ *
+ * The browser_server proxies to Chrome's BROWSER-LEVEL CDP target
+ * (/devtools/browser/{id}). This means we must:
+ *   1. Discover/create a page target
+ *   2. Attach to it with flatten: true to get a sessionId
+ *   3. Send all Page/Runtime/Input commands with that sessionId
+ *
+ * Used for Chrome, Chrome-H, Servo, and LightPanda browsers.
+ */
+declare class CDPSession {
+    private nextId;
+    private pending;
+    private eventHandlers;
+    private transport;
+    /** CDP session ID from Target.attachToTarget (required for page-level commands). */
+    private targetSessionId;
+    private commandTimeoutMs;
+    constructor(transport: Transport, opts?: {
+        commandTimeoutMs?: number;
+    });
+    /** Get the attached target session ID. */
+    get sessionId(): string | undefined;
+    /** Process a raw message from the transport. Returns true if handled. */
+    handleMessage(data: string): boolean;
+    /** Send a CDP command and wait for the response. */
+    send(method: string, params?: Record<string, unknown>): Promise<CDPResponse>;
+    /**
+     * Send a CDP command scoped to the attached page session.
+     * This is what you use for Page.*, Runtime.*, Input.* commands.
+     */
+    sendToTarget(method: string, params?: Record<string, unknown>): Promise<CDPResponse>;
+    /** Subscribe to a CDP event. */
+    on(method: string, handler: EventHandler$1): void;
+    /** Unsubscribe from a CDP event. */
+    off(method: string, handler: EventHandler$1): void;
+    /**
+     * Discover page targets, find or create one, attach to it, and enable
+     * the required CDP domains (Page, Runtime).
+     *
+     * This is the key initialization step — without this, Page.navigate and
+     * Runtime.evaluate won't work because we're connected at browser level.
+     */
+    attachToPage(): Promise<string>;
+    /** Capture a screenshot as base64 PNG (10s timeout to avoid blocking on heavy pages). */
+    captureScreenshot(): Promise<string>;
+    /** Get full page HTML. */
+    getHTML(): Promise<string>;
+    /** Evaluate a JavaScript expression and return the value. */
+    evaluate(expression: string): Promise<unknown>;
+    /** Wait for a CDP event to fire, with timeout. Returns true if event fired, false on timeout. */
+    private waitForEvent;
+    /** Navigate to a URL and wait for the page to load. */
+    navigate(url: string): Promise<void>;
+    /** Dispatch a mouse event. */
+    dispatchMouseEvent(type: string, x: number, y: number, button?: string, clickCount?: number): Promise<void>;
+    /** Click at coordinates (mouseMoved -> mousePressed -> mouseReleased). */
+    clickPoint(x: number, y: number): Promise<void>;
+    /** Right-click at coordinates. */
+    rightClickPoint(x: number, y: number): Promise<void>;
+    /** Double-click at coordinates. */
+    doubleClickPoint(x: number, y: number): Promise<void>;
+    /** Click and hold at coordinates for a duration. */
+    clickHoldPoint(x: number, y: number, holdMs: number): Promise<void>;
+    /** Hover (mouseMoved only). */
+    hoverPoint(x: number, y: number): Promise<void>;
+    /** Smooth drag from point to point (10-step interpolation). */
+    dragPoint(fromX: number, fromY: number, toX: number, toY: number): Promise<void>;
+    /** Insert text via Input.insertText. */
+    insertText(text: string): Promise<void>;
+    /** Press a key (keyDown + keyUp). */
+    pressKey(key: string, code: string, keyCode: number): Promise<void>;
+    /** Send keyDown event. */
+    keyDown(key: string, code: string, keyCode: number): Promise<void>;
+    /** Send keyUp event. */
+    keyUp(key: string, code: string, keyCode: number): Promise<void>;
+    /** Set viewport via Emulation.setDeviceMetricsOverride. */
+    setViewport(width: number, height: number, deviceScaleFactor?: number, mobile?: boolean): Promise<void>;
+    /** Clean up all pending commands and event handlers. Rejects in-flight commands. */
+    destroy(): void;
+    private extractEvalValue;
+}
+
+type EventHandler = (params: Record<string, unknown>) => void;
+/**
+ * WebDriver BiDi session over the Spider WebSocket transport.
+ *
+ * Used for Firefox browser connections. Mirrors CDPSession's interface
+ * but speaks the BiDi protocol.
+ */
+declare class BiDiSession {
+    private nextId;
+    private pending;
+    private eventHandlers;
+    private transport;
+    private browsingContext;
+    private commandTimeoutMs;
+    constructor(transport: Transport, opts?: {
+        commandTimeoutMs?: number;
+    });
+    get context(): string | undefined;
+    /** Process a raw message from the transport. Returns true if handled. */
+    handleMessage(data: string): boolean;
+    /** Send a BiDi command and wait for the response. */
+    send(method: string, params: Record<string, unknown>): Promise<BiDiResponse>;
+    /** Subscribe to a BiDi event. */
+    on(method: string, handler: EventHandler): void;
+    /** Unsubscribe from a BiDi event. */
+    off(method: string, handler: EventHandler): void;
+    /**
+     * Get or create a browsing context.
+     *
+     * The browser_server's Firefox relay proxies to geckodriver which already has
+     * a session with a browsing context. We try multiple strategies:
+     * 1. browsingContext.getTree (standard BiDi)
+     * 2. session.status (to get session info, then extract context)
+     * 3. browsingContext.create as last resort
+     *
+     * If all discovery fails, we set a placeholder context that gets replaced
+     * on the first successful navigate response.
+     */
+    getOrCreateContext(): Promise<string>;
+    /** Set the browsing context (called when we discover it from a response). */
+    setContext(contextId: string): void;
+    /** Navigate to a URL. */
+    navigate(url: string): Promise<void>;
+    /** Capture a screenshot as base64 PNG. */
+    captureScreenshot(): Promise<string>;
+    /**
+     * Evaluate JavaScript and return the value.
+     *
+     * BiDi script.evaluate returns results in this format:
+     *   { result: { type: "string", value: "..." } }
+     *   { result: { type: "number", value: 42 } }
+     *   { result: { type: "boolean", value: true } }
+     *   { result: { type: "object", value: [...entries...] } }
+     *   { result: { type: "null" } }
+     *   { result: { type: "undefined" } }
+     *   { result: { type: "array", value: [...] } }
+     */
+    evaluate(expression: string): Promise<unknown>;
+    /** Extract a JS value from a BiDi remote value object. */
+    private extractBiDiValue;
+    /** Get full page HTML. */
+    getHTML(): Promise<string>;
+    /**
+     * Perform actions (BiDi input.performActions).
+     * This is the BiDi way to do mouse/keyboard events.
+     */
+    performActions(actions: unknown[]): Promise<void>;
+    /** Click at coordinates via BiDi input actions. */
+    clickPoint(x: number, y: number): Promise<void>;
+    /** Insert text via BiDi input actions. */
+    insertText(text: string): Promise<void>;
+    /** Clean up all pending commands and event handlers. Rejects in-flight commands. */
+    destroy(): void;
+}
+
+interface RetryOptions {
+    maxRetries: number;
+    transportOpts: TransportOptions;
+    emitter: SpiderEventEmitter;
+    /** Maximum stealth level to escalate to (1-3, default 3). */
+    maxStealthLevel?: number;
+    /** Timeout for retry attempts — shorter than first try (default: 15000ms). */
+    retryTimeoutMs?: number;
+    /** CDP/BiDi command timeout in ms, passed through to new adapters (default: 30000). */
+    commandTimeoutMs?: number;
+}
+interface RetryContext {
+    transport: Transport;
+    adapter: ProtocolAdapter;
+    page: SpiderPage;
+    currentUrl: string | undefined;
+    onAdapterChanged: (adapter: ProtocolAdapter) => void;
+}
+/**
+ * Smart retry engine with stealth-first escalation.
+ *
+ * **Strategy: escalate proxy quality (stealth) FAST, try alternative engines LAST.**
+ *
+ * - **Phase 1 (Stealth escalation)**: For each stealth level [0 → max],
+ *   try PRIMARY browsers [chrome, chrome-new] with transient retries.
+ *   If blocked → skip remaining primary browsers, escalate stealth immediately.
+ *
+ * - **Phase 2 (Extended rotation)**: Only at max stealth, if still blocked,
+ *   try EXTENDED browsers [firefox, lightpanda, servo] for different engine
+ *   fingerprints + best proxies.
+ *
+ * **Retry flow:**
+ * ```
+ * Phase 1 — stealth escalation across primary browsers:
+ *   for each stealth level (initial → maxStealthLevel):
+ *     for each PRIMARY browser [chrome, chrome-new]:
+ *       attempt action
+ *       if transient → reconnect same browser, retry up to 2x
+ *       if blocked   → skip remaining primary, escalate stealth immediately
+ *       if backend_down → mark down, next browser
+ *       if auth      → throw immediately
+ *       if rate_limit → wait, retry same browser
+ *
+ * Phase 2 — extended rotation at max stealth only (if blocked):
+ *   for each EXTENDED browser [firefox, lightpanda, servo]:
+ *     single attempt (no transient retries)
+ * ```
+ *
+ * Error classification (mirrors server hints.rs):
+ *
+ * | Error Pattern              | Classification  | Action                                    |
+ * |----------------------------|-----------------|-------------------------------------------|
+ * | ERR_ABORTED (nav)          | Transient+Disco | Reconnect (new session), retry up to 2x   |
+ * | WS close 1006/1011         | Transient+Disco | Reconnect same browser, retry up to 2x    |
+ * | Timeout                    | Transient       | Retry same browser up to 2x, then switch  |
+ * | blocked / 403 / captcha    | Blocked         | Skip remaining primary, escalate stealth   |
+ * | bot detection              | Blocked         | Skip remaining primary, escalate stealth   |
+ * | 401 / 402                  | Auth            | Throw immediately (no retry)              |
+ * | 429                        | Rate limit      | Wait + retry same browser                 |
+ * | 503 / backend unavailable  | Backend down    | Mark down, switch browser                 |
+ */
+declare class RetryEngine {
+    private opts;
+    private selector;
+    private currentStealthLevel;
+    private maxStealthLevel;
+    private retryTimeoutMs;
+    private commandTimeoutMs;
+    /** Browser backends that returned 503/unavailable — persists across stealth levels. */
+    private downBackends;
+    constructor(opts: RetryOptions);
+    /** Current stealth level (0=auto, 1-3=explicit tiers). */
+    get stealthLevel(): number;
+    /**
+     * Execute an action with stealth-first retry across browsers and stealth levels.
+     *
+     * Phase 1: Escalate stealth across primary browsers (chrome, chrome-new).
+     * Blocked errors skip remaining primary browsers and immediately escalate stealth.
+     *
+     * Phase 2: At max stealth only, try extended browsers (firefox, lightpanda, servo)
+     * for a different engine fingerprint with the best proxy quality.
+     */
+    execute<T>(fn: () => Promise<T>, ctx: RetryContext): Promise<T>;
+    /**
+     * Attempt an action on a specific browser, with optional transient retries.
+     *
+     * @param allowTransientRetries If true, retries up to 2x for transient errors
+     *   (reconnect + retry). If false, a single attempt only (for extended browsers).
+     */
+    private tryBrowser;
+    /** Check if an error indicates the WebSocket/session is dead and needs reconnection. */
+    private isDisconnectionError;
+    /**
+     * Classify an error to determine retry strategy.
+     *
+     * Fast path: typed error instances (instanceof check, no string scan).
+     * Slow path: Aho-Corasick O(n) single-pass keyword matching on error message.
+     */
+    private classifyError;
+    /** Reconnect with a (possibly different) browser, re-navigate to the same URL. */
+    private switchBrowser;
+    /**
+     * Get stealth progression: from current level up to maxStealthLevel.
+     * e.g. start=0, max=3 → [0, 1, 2, 3]
+     * e.g. start=2, max=3 → [2, 3]
+     */
+    private getStealthProgression;
+    /**
+     * Order PRIMARY browsers starting from `start`, then the rest in primary rotation order.
+     * If `start` is not in PRIMARY_ROTATION, returns primary rotation as-is.
+     */
+    private orderedPrimaryBrowsers;
+    private extractDomain;
+}
+
+/**
+ * Per-domain failure tracking (mirrors server hints.rs FailureTracker).
+ *
+ * Tracks (domain, browser_type) failure counts with 10-minute TTL.
+ * Used by BrowserSelector to decide when to rotate browsers.
+ */
+declare class FailureTracker {
+    private failures;
+    private key;
+    /** Record a failure for a domain + browser. */
+    recordFailure(domain: string, browser: BrowserType): void;
+    /** Record a success — clears the failure counter. */
+    recordSuccess(domain: string, browser: BrowserType): void;
+    /** Get failure count (0 if expired or not found). */
+    failureCount(domain: string, browser: BrowserType): number;
+    /** Get total failures across all browsers for a domain. */
+    totalFailureCount(domain: string): number;
+    /** Clear all failure records for a domain (used on stealth escalation). */
+    clear(domain: string): void;
+    /** Clean expired entries. */
+    cleanup(): void;
+}
+
+/**
+ * Full browser rotation order for retry/failover.
+ * Primary (Chrome) browsers are tried first, then extended if blocked.
+ */
+declare const BROWSER_ROTATION: BrowserType[];
+/**
+ * BrowserSelector — picks the next browser in rotation based on failures.
+ *
+ * Follows the server's hints.rs logic:
+ * 1. Try current browser until ROTATE_AFTER_FAILURES consecutive failures
+ * 2. Then move to the next browser in BROWSER_ROTATION order
+ * 3. Skip browsers that have also exceeded the failure threshold
+ */
+declare class BrowserSelector {
+    private tracker;
+    private rotationIndex;
+    constructor(tracker: FailureTracker);
+    /** Get the current failure tracker. */
+    get failureTracker(): FailureTracker;
+    /**
+     * Check if the current browser should be rotated for a domain.
+     */
+    shouldRotate(domain: string, currentBrowser: BrowserType): boolean;
+    /**
+     * Pick the next browser to try, given the current one has failed.
+     * Returns the next browser in rotation that hasn't exceeded the failure threshold.
+     * Returns null if all browsers have been exhausted.
+     */
+    nextBrowser(domain: string, currentBrowser: BrowserType): BrowserType | null;
+    /**
+     * Choose the best browser for a domain (mirrors hints.rs choose_browser_for_domain).
+     * Uses failure history to skip browsers that have been failing.
+     */
+    chooseBrowser(domain: string, fallback: BrowserType): BrowserType;
+}
+
+/**
+ * Execute a single action from natural language.
+ *
+ * Takes a screenshot + HTML, sends to LLM with the instruction,
+ * then executes the returned action steps.
+ *
+ * Example: `await act(adapter, llm, 'Click the login button')`
+ */
+declare function act(adapter: ProtocolAdapter, llm: LLMProvider, instruction: string): Promise<void>;
+
+/**
+ * Extract structured data from the page.
+ *
+ * Takes a screenshot + HTML, sends to LLM with the instruction and optional
+ * Zod schema, returns parsed and validated data.
+ */
+declare function extract<T>(adapter: ProtocolAdapter, llm: LLMProvider, instruction: string, schema?: z.ZodType<T>): Promise<T>;
+
+/**
+ * System prompt for the web automation agent.
+ *
+ * Ported VERBATIM from browser_server/src/ai/llm.rs SYSTEM_PROMPT (lines 30-135)
+ * to ensure identical agent behavior between server-side captcha solver
+ * and client-side agent.
+ */
+declare const SYSTEM_PROMPT = "You are an expert web automation agent. You interact with any webpage to solve challenges, fill forms, navigate sites, extract data, and complete complex multi-step tasks.\n\n## Input\nEach round you receive:\n- Screenshot of current page state\n- URL, title, HTML context\n- Round number and detected challenge types\n\n## Output\nReturn a single JSON object (no prose):\n{\n  \"label\": \"brief action description\",\n  \"done\": true|false,\n  \"steps\": [...]\n}\nSet \"done\": true when the task is fully complete. Set \"done\": false to continue.\n\n## Coordinate System\n**ClickPoint coordinates use CSS pixels** (same as getBoundingClientRect()).\n- Screenshot pixels = viewport x DPR. Divide screenshot coordinates by DPR for CSS pixels.\n- Example: viewport 1280x960 at DPR 2 = screenshot 2560x1920. Visual point (500,400) in screenshot = (250,200) CSS.\n\n## Actions\n\n### Click\n- { \"Click\": \"selector\" } - CSS selector click\n- { \"ClickPoint\": { \"x\": 100, \"y\": 200 } } - CSS pixel coordinates\n- { \"ClickAll\": \"selector\" } - Click all matches\n- { \"DoubleClick\": \"selector\" } / { \"DoubleClickPoint\": { \"x\": 0, \"y\": 0 } }\n- { \"RightClick\": \"selector\" } / { \"RightClickPoint\": { \"x\": 0, \"y\": 0 } }\n- { \"ClickHold\": { \"selector\": \"sel\", \"hold_ms\": 500 } } / { \"ClickHoldPoint\": { \"x\": 0, \"y\": 0, \"hold_ms\": 500 } }\n- { \"WaitForAndClick\": \"selector\" }\n\n### Drag\n- { \"ClickDrag\": { \"from\": \"sel1\", \"to\": \"sel2\" } }\n- { \"ClickDragPoint\": { \"from_x\": 0, \"from_y\": 0, \"to_x\": 100, \"to_y\": 100 } }\n\n### Type & Input\n- { \"Fill\": { \"selector\": \"input\", \"value\": \"text\" } } - Clear and type\n- { \"Type\": { \"value\": \"text\" } } - Type into focused element\n- { \"Clear\": \"selector\" } - Clear input\n- { \"Press\": \"Enter\" } - Press key (Enter, Tab, Escape, ArrowDown, Space, etc.)\n- { \"KeyDown\": \"Shift\" } / { \"KeyUp\": \"Shift\" }\n\n### Select & Focus\n- { \"Select\": { \"selector\": \"select\", \"value\": \"option\" } }\n- { \"Focus\": \"selector\" } / { \"Blur\": \"selector\" }\n- { \"Hover\": \"selector\" } / { \"HoverPoint\": { \"x\": 0, \"y\": 0 } }\n\n### Scroll\n- { \"ScrollY\": 300 } - Scroll down (negative = up)\n- { \"ScrollX\": 200 } - Scroll right (negative = left)\n- { \"ScrollTo\": { \"selector\": \"element\" } } - Scroll element into view\n- { \"ScrollToPoint\": { \"x\": 0, \"y\": 500 } }\n- { \"InfiniteScroll\": 5 } - Scroll to bottom repeatedly\n\n### Wait\n- { \"Wait\": 1000 } - Wait milliseconds\n- { \"WaitFor\": \"selector\" } - Wait for element\n- { \"WaitForWithTimeout\": { \"selector\": \"sel\", \"timeout\": 5000 } }\n- { \"WaitForNavigation\": null } - Wait for page load\n- { \"WaitForDom\": { \"selector\": \"sel\", \"timeout\": 5000 } }\n\n### Navigate\n- { \"Navigate\": \"https://url\" } - Go to URL\n- { \"GoBack\": null } / { \"GoForward\": null } / { \"Reload\": null }\n\n### Viewport\n- { \"SetViewport\": { \"width\": 1920, \"height\": 1080, \"device_scale_factor\": 2.0 } } - Change viewport/DPR at runtime. Follow with { \"Wait\": 500 }.\n\n### JavaScript\n- { \"Evaluate\": \"javascript code\" } - Execute JS on the page\n\n**Evaluate notes:**\n- Return values are NOT sent back. To see results, inject into the page:\n  - Title: document.title = JSON.stringify(data) (visible in PAGE TITLE next round)\n  - DOM: inject a visible overlay div with the info (visible in screenshot)\n- **Do NOT use element.click() in Evaluate** - it does not trigger real browser events (mousedown/pointerdown). Always use real Click/ClickPoint actions for interactions.\n- **Always pair Evaluate with action steps** in the same round. Never submit a round with ONLY Evaluate.\n\n## Core Strategy\n\n1. **Be efficient**: Solve challenges in the fewest rounds possible. Combine Evaluate (read state) + action (click/fill) in the SAME round. Never spend a round only gathering data.\n2. **Batch operations**: When you need to click/select multiple elements, include multiple Click actions in a single step list rather than spreading across multiple rounds.\n3. **Evaluate = READ ONLY**: Use Evaluate to read DOM state, computed styles, coordinates. Set results in document.title. NEVER use el.click() inside Evaluate - it does NOT trigger real browser events. Use real Click/ClickPoint for all interactions.\n4. **Prefer selectors over coordinates**: Use CSS selectors when elements exist in DOM. Reserve ClickPoint for canvas/SVG or when selectors fail.\n5. **Handle stagnation**: If your last actions had no visible effect, try a different approach - different selector, different interaction method, or use Evaluate to understand why.\n6. **Never repeat failures**: If something fails twice, change strategy entirely. If verify/submit doesn't advance, your answer is likely wrong - re-examine.\n7. **Commit and iterate**: Submit your best answer rather than endlessly adjusting. Learn from the result.\n\n## Captcha & Challenge Strategies\n\n- **reCAPTCHA checkbox**: Click the iframe first, then the checkbox inside it.\n- **Cloudflare Turnstile**: The challenge is in an iframe. Look for `iframe[src*=\"challenges.cloudflare.com\"]` and click inside it.\n- **Image selection (reCAPTCHA v2)**: Identify matching images and click them one at a time. After selecting, click the verify button. If incorrect, the grid refreshes - try again.\n- **Slider/puzzle captchas**: Use ClickDragPoint to drag the slider from start to end position.\n- **Text captchas**: Read the distorted text carefully, then Fill the answer input and Press Enter.\n- **Visual puzzles**: Describe what you see, reason about the solution, then act precisely.\n- **PerimeterX (px-captcha)**: This is a press-and-hold captcha. Find the button element inside the #px-captcha container or iframe with [role=\"button\"]. Use ClickHold with hold_ms: 15000 (15 seconds). Wait for the captcha wrapper to disappear after release.\n- **DataDome**: Often shows an iframe from geo.captcha-delivery.com. Click inside the iframe to interact with the challenge. May include slider or image selection.\n- **Arkose Labs / FunCaptcha**: Interactive challenge in an iframe from arkoselabs.com. Follow on-screen instructions \u2014 typically image rotation, matching, or selection puzzles.\n- **Cookie/consent banners**: Click accept/dismiss buttons to clear overlays before solving the actual captcha.\n- **Multiple challenge steps**: Some captchas have multiple rounds (e.g., reCAPTCHA may ask to solve 3 image grids). Keep going until done.\n\n## Output Rules\n- JSON only, no markdown or prose\n- Always include \"label\", \"done\", and \"steps\"\n- \"steps\" array can have multiple actions per round";
+
+/**
+ * Truncate HTML to roughly maxChars, trying to break at a tag boundary.
+ * Mirrors server's truncate_html in llm.rs.
+ */
+declare function truncateHtml(html: string, maxChars?: number): string;
+
+/** Base error for all spider-browser errors. */
+declare class SpiderError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    constructor(message: string, code: string, retryable?: boolean);
+}
+/** WebSocket connection or transport error. */
+declare class ConnectionError extends SpiderError {
+    readonly wsCode?: number | undefined;
+    constructor(message: string, wsCode?: number | undefined);
+}
+/** Authentication failure (401/402). Never retried. */
+declare class AuthError extends SpiderError {
+    constructor(message: string);
+}
+/** Rate limit (429). Retried with delay. */
+declare class RateLimitError extends SpiderError {
+    readonly retryAfterMs?: number | undefined;
+    constructor(message: string, retryAfterMs?: number | undefined);
+}
+/** The browser was blocked by the target site (403, captcha stuck). */
+declare class BlockedError extends SpiderError {
+    constructor(message: string);
+}
+/** The requested backend browser is unavailable. */
+declare class BackendUnavailableError extends SpiderError {
+    constructor(message: string);
+}
+/** Timeout waiting for a response or navigation. */
+declare class TimeoutError extends SpiderError {
+    constructor(message: string);
+}
+/** Protocol-level error (invalid CDP/BiDi response). */
+declare class ProtocolError extends SpiderError {
+    constructor(message: string);
+}
+/** Navigation error that can be retried (ERR_ABORTED, ERR_CONNECTION_RESET, etc.). */
+declare class NavigationError extends SpiderError {
+    constructor(message: string);
+}
+/** LLM call failed or returned unparseable response. */
+declare class LLMError extends SpiderError {
+    constructor(message: string);
+}
+
+export { Agent, type AgentAction, type AgentOptions, type AgentPlan, type AgentResult, AuthError, BROWSER_ROTATION, BackendUnavailableError, BiDiSession, BlockedError, BrowserSelector, type BrowserType, CDPSession, ConnectionError, FailureTracker, type LLMConfig, LLMError, type LLMMessage, type LLMProvider, Logger, NavigationError, type ObserveResult, ProtocolAdapter, ProtocolError, RateLimitError, RetryEngine, type RetryOptions, SYSTEM_PROMPT, SpiderBrowser, type SpiderBrowserOptions, SpiderError, SpiderEventEmitter, type SpiderEventName, type SpiderEvents, SpiderPage, TimeoutError, Transport, type TransportOptions, act, createProvider, extract, logger, observe, truncateHtml };