browserscale-ts 1.4.0 → 1.7.0

package/dist/index.js

@@ -9,6 +9,11 @@ export { Locator, css, js, node, at, AllFrames } from "./locator.js";
 export { DefaultWaitTimeoutMs, DefaultVisible, DefaultSteadyMs, } from "./defaults.js";
 // Errors — base class plus the typed semantic-failure subclasses
 export { BrowserScaleError, ClickError, FillError, DragError, ScrollError, MoveError, SelectOptionError, WaitError, } from "./errors.js";
+// Scripts (automation running inside the browser process)
+export { ScriptRun, ScriptFollow, } from "./scripts.js";
+// Network capture (traffic log)
+export { NetworkCapture } from "./network-capture.js";
+export { DomMirror, } from "./dom-mirror.js";
 // Rent / stop ──────────────────────────────────────────────────────────
 let apiEndpoint = "https://api.browserscale.cloud";
 /**
@@ -106,6 +111,62 @@ export function connectSession(grpcUrl, apiKey, sessionId) {
 export async function stopBrowser(apiKey, sessionId) {
     await callStopApi(apiKey, sessionId);
 }
+/**
+ * Reports the sessions an API key currently holds.
+ *
+ * Use it to recover session ids the process lost — after a restart, or from a
+ * different machine entirely. Without it a rental is only reachable through the
+ * handle that created it, so a crash between rent and stop leaves a paid session
+ * running with nothing able to name it.
+ *
+ * Each entry carries the `grpcUrl` it is driven from, so a listed session can be
+ * handed straight to {@link connectSession}. Only live sessions are listed; a
+ * stopped one is gone, not reported as ended.
+ *
+ * @param apiKey - API key whose sessions to list
+ *
+ * @returns the running sessions, oldest first; empty when the key holds none
+ *
+ * @throws UNKNOWN_ERROR - the list API rejected the request
+ *
+ * @example
+ * const browsers = await listBrowsers(apiKey);
+ * for (const b of browsers) console.log(b.sessionId, b.countryCode);
+ *
+ * // and to drive one of them
+ * const browser = connectSession(browsers[0].grpcUrl, apiKey, browsers[0].sessionId);
+ */
+export async function listBrowsers(apiKey) {
+    const resp = await fetch(`${apiEndpoint}/sessions`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ apiKey }),
+    });
+    // Named explicitly, because this is the one endpoint a caller can reach on a
+    // deployment that does not have it: listing came after rent and stop. Letting
+    // it fall through would report a JSON parse failure against an error page,
+    // which says nothing about the actual problem.
+    if (resp.status === 404) {
+        throw new Error(`the API at ${apiEndpoint} does not support listing sessions`);
+    }
+    const data = await resp.json();
+    if (!resp.ok || !data.success) {
+        throw new Error(`list failed: ${data.error ?? resp.statusText}`);
+    }
+    const sessions = (data.sessions ?? []);
+    return sessions.map((s) => ({
+        sessionId: s.sessionId,
+        grpcUrl: s.grpcUrl ?? "",
+        startTime: s.startTime ?? 0,
+        rentDuration: s.rentDuration ?? 0,
+        remainingSeconds: s.remainingSeconds,
+        countryCode: s.countryCode ?? "",
+        timezone: s.timezone ?? "",
+        proxyHost: s.proxyHost ?? "",
+        publicIp: s.publicIp ?? "",
+        gpuIndex: s.gpuIndex,
+    }));
+}
 // Maps the rent response's gRPC URL to a transport base URL. The scheme
 // signals transport security: grpcs:// dials TLS, grpc:// (or no scheme,
 // for older servers) dials plaintext.

package/dist/internal/convert.d.ts

@@ -1,7 +1,8 @@
-import { type Rect as ProtoRect, type ClickResult as ProtoClickResult, type FillResult as ProtoFillResult, type MoveResult as ProtoMoveResult, type ScrollResult as ProtoScrollResult, type DragResult as ProtoDragResult, type SelectOptionResult as ProtoSelectOptionResult, type WaitResult as ProtoWaitResult, type FrameInfo as ProtoFrameInfo, type PageInfo as ProtoPageInfo, type Header as ProtoHeader, type InterceptedRequest as ProtoInterceptedRequest, type InterceptedResponse as ProtoInterceptedResponse, type HeaderModification as ProtoHeaderModification, type CookieParam as ProtoCookieParam, type StorageOriginEntry as ProtoStorageOriginEntry } from "../gen/wrc_pb.ts";
-import type { DragResult, ElementResult, FrameInfo, Header, InterceptedRequest, InterceptedResponse, PageInfo, Rect, SelectOptionResult, WaitResult } from "../types.ts";
+import { type Rect as ProtoRect, type ClickResult as ProtoClickResult, type FillResult as ProtoFillResult, type MoveResult as ProtoMoveResult, type ScrollResult as ProtoScrollResult, type DragResult as ProtoDragResult, type SelectOptionResult as ProtoSelectOptionResult, type WaitResult as ProtoWaitResult, type FrameInfo as ProtoFrameInfo, type PageInfo as ProtoPageInfo, type Header as ProtoHeader, type InterceptedRequest as ProtoInterceptedRequest, type InterceptedResponse as ProtoInterceptedResponse, type NetworkExchange as ProtoNetworkExchange, type HeaderModification as ProtoHeaderModification, type CookieParam as ProtoCookieParam, type StorageOriginEntry as ProtoStorageOriginEntry, type AuthSession as ProtoAuthSession } from "../gen/wrc_pb.ts";
+import type { DragResult, ElementResult, FrameInfo, Header, InterceptedRequest, InterceptedResponse, NetworkExchange, PageInfo, Rect, SelectOptionResult, WaitResult } from "../types.ts";
 import type { CookieParam } from "../cookies.ts";
 import type { StorageOriginEntry } from "../storage.ts";
+import type { AuthSession } from "../auth-session.ts";
 import type { HeaderModification, RequestPattern } from "../network.ts";
 import { type Locator } from "../locator.ts";
 /**
@@ -38,11 +39,19 @@ export declare function pageInfoFromProto(p: ProtoPageInfo): PageInfo;
 export declare function headerFromProto(h: ProtoHeader): Header;
 export declare function headersToProto(headers: Header[] | undefined): ProtoHeader[];
 export declare function interceptedRequestFromProto(r: ProtoInterceptedRequest | undefined): InterceptedRequest | null;
+/**
+ * The int64/uint64 fields arrive as bigint. Byte counts stay far below
+ * Number.MAX_SAFE_INTEGER, so they are narrowed to number to keep the SDK
+ * surface free of bigint.
+ */
+export declare function networkExchangeFromProto(e: ProtoNetworkExchange): NetworkExchange;
 export declare function interceptedResponseFromProto(r: ProtoInterceptedResponse | undefined): InterceptedResponse | null;
 export declare function cookieParamFromProto(c: ProtoCookieParam): CookieParam;
 export declare function cookieParamsToProto(cookies: CookieParam[]): ProtoCookieParam[];
 export declare function storageEntryFromProto(e: ProtoStorageOriginEntry): StorageOriginEntry;
 export declare function storageEntriesToProto(storage: StorageOriginEntry[]): ProtoStorageOriginEntry[];
+export declare function authSessionFromProto(s: ProtoAuthSession): AuthSession;
+export declare function authSessionToProto(s: AuthSession): ProtoAuthSession;
 /**
  * splitRequestPatterns turns a RequestPattern[] into the proto's parallel
  * URL + abort-flag slices. When no pattern has abort set, the aborts

package/dist/internal/convert.js

@@ -1,7 +1,7 @@
 // Internal proto ↔ TS helpers used by client.ts. Anything in here is
 // implementation detail and is NOT exported from the package entrypoints.
 import { create } from "@bufbuild/protobuf";
-import { HeaderModificationSchema, CookiePartitionKeySchema, CookieParamSchema, HeaderSchema, StorageItemSchema, StorageOriginEntrySchema, } from "../gen/wrc_pb.js";
+import { HeaderModificationSchema, CookiePartitionKeySchema, CookieParamSchema, HeaderSchema, StorageItemSchema, StorageOriginEntrySchema, AuthSessionSchema, DbscSessionSchema, } from "../gen/wrc_pb.js";
 import { ClickError, DragError, FillError, MoveError, ScrollError, SelectOptionError, WaitError, } from "../errors.js";
 import { pickFrame } from "../locator.js";
 export function elementFields(target, optsInFrame) {
@@ -257,6 +257,45 @@ export function interceptedRequestFromProto(r) {
         resourceType: r.resourceType,
     };
 }
+// ──────────────────────────────────────────────────────────────────────
+// Network capture
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * The int64/uint64 fields arrive as bigint. Byte counts stay far below
+ * Number.MAX_SAFE_INTEGER, so they are narrowed to number to keep the SDK
+ * surface free of bigint.
+ */
+export function networkExchangeFromProto(e) {
+    return {
+        requestId: e.requestId,
+        chainId: e.chainId,
+        redirectIndex: e.redirectIndex,
+        frameId: e.frameId,
+        isOopif: e.isOopif,
+        resourceType: e.resourceType,
+        method: e.method,
+        url: e.url,
+        initiatorUrl: e.initiatorUrl,
+        requestHeaders: e.requestHeaders.map(headerFromProto),
+        requestHeadersAreWire: e.requestHeadersAreWire,
+        requestBody: e.requestBody,
+        requestBodyTruncated: e.requestBodyTruncated,
+        hasResponse: e.hasResponse,
+        statusCode: e.statusCode,
+        statusText: e.statusText,
+        mimeType: e.mimeType,
+        protocol: e.protocol,
+        remoteAddress: e.remoteAddress,
+        servedFrom: e.servedFrom,
+        responseHeaders: e.responseHeaders.map(headerFromProto),
+        responseHeadersAreWire: e.responseHeadersAreWire,
+        responseBody: e.responseBody,
+        responseBodyTruncated: e.responseBodyTruncated,
+        responseBodyCaptured: e.responseBodyCaptured,
+        encodedDataLength: Number(e.encodedDataLength),
+        error: e.error,
+    };
+}
 export function interceptedResponseFromProto(r) {
     if (!r)
         return null;
@@ -346,6 +385,50 @@ export function storageEntriesToProto(storage) {
     });
 }
 // ──────────────────────────────────────────────────────────────────────
+// Auth / DBSC
+// ──────────────────────────────────────────────────────────────────────
+export function authSessionFromProto(s) {
+    const out = {};
+    if (s.gaiaId !== undefined)
+        out.gaiaId = s.gaiaId;
+    if (s.email !== undefined)
+        out.email = s.email;
+    if (s.refreshToken !== undefined)
+        out.refreshToken = s.refreshToken;
+    if (s.wrappedBindingKey !== undefined)
+        out.wrappedBindingKey = s.wrappedBindingKey;
+    if (s.signinScopedDeviceId !== undefined)
+        out.signinScopedDeviceId = s.signinScopedDeviceId;
+    if (s.syncConsent !== undefined)
+        out.syncConsent = s.syncConsent;
+    if (s.dbscSessions.length > 0) {
+        out.dbscSessions = s.dbscSessions.map(d => ({ site: d.site, session: d.session }));
+    }
+    return out;
+}
+export function authSessionToProto(s) {
+    const msg = create(AuthSessionSchema);
+    if (s.gaiaId !== undefined)
+        msg.gaiaId = s.gaiaId;
+    if (s.email !== undefined)
+        msg.email = s.email;
+    if (s.refreshToken !== undefined)
+        msg.refreshToken = s.refreshToken;
+    if (s.wrappedBindingKey !== undefined)
+        msg.wrappedBindingKey = s.wrappedBindingKey;
+    if (s.signinScopedDeviceId !== undefined)
+        msg.signinScopedDeviceId = s.signinScopedDeviceId;
+    if (s.syncConsent !== undefined)
+        msg.syncConsent = s.syncConsent;
+    msg.dbscSessions = (s.dbscSessions ?? []).map(d => {
+        const item = create(DbscSessionSchema);
+        item.site = d.site;
+        item.session = d.session;
+        return item;
+    });
+    return msg;
+}
+// ──────────────────────────────────────────────────────────────────────
 // Network — patterns + header modifications
 // ──────────────────────────────────────────────────────────────────────
 /**

package/dist/network-capture.d.ts

@@ -0,0 +1,84 @@
+import type { NetworkExchangeEvent } from "./gen/wrc_pb.ts";
+import type { NetworkExchange } from "./types.ts";
+/**
+ * NetworkExchangeHandler is called once per completed exchange.
+ *
+ * Calls are sequential and in the order the browser finished the requests, so
+ * the hops of a redirect chain arrive in order.
+ *
+ * Blocking here stalls the capture: awaiting something slow means the server
+ * keeps buffering, and once its per-reader bound is reached it drops the oldest
+ * entries, which {@link NetworkCapture.dropped} reports. Hand slow work
+ * (uploads, IndexedDB) to a queue of your own instead of awaiting it here.
+ */
+export type NetworkExchangeHandler = (exchange: NetworkExchange) => void;
+/**
+ * NetworkCapture is a running capture, returned by
+ * {@link CloudBrowser.captureNetwork}. Exchanges are delivered to the handler
+ * passed there; this handle only exists to stop the capture and to report how
+ * it went.
+ */
+export declare class NetworkCapture {
+    private readonly abort;
+    private readonly disarm;
+    private readonly finished;
+    private armed;
+    private stopped;
+    private failure;
+    private droppedCount;
+    /** @internal Constructed by CloudBrowser; not part of the public API. */
+    constructor(init: {
+        stream: AsyncIterable<NetworkExchangeEvent>;
+        onExchange: NetworkExchangeHandler;
+        disarm: () => Promise<unknown>;
+        abort: AbortController;
+    });
+    /**
+     * @internal Marks the capture as armed by this handle, so stop() disarms it
+     * server-side. Views that only attached to someone else's capture stay
+     * unarmed and merely detach.
+     */
+    arm(): void;
+    /**
+     * Reads the stream and calls the handler for each exchange. It never rejects:
+     * a failure is recorded for {@link NetworkCapture.error} instead, so nothing
+     * surfaces as an unhandled rejection.
+     */
+    private pump;
+    /**
+     * Why the capture ended: null while it is still running, and after a clean
+     * stop or the session ending normally.
+     */
+    get error(): Error | null;
+    /**
+     * How many exchanges the server discarded because this reader fell behind.
+     * Anything above zero means the log has holes: make the handler cheaper,
+     * narrow `patterns`, or stop capturing bodies.
+     */
+    get dropped(): number;
+    /**
+     * Resolves once the capture ends — {@link NetworkCapture.stop}, a dead
+     * session or a transport failure.
+     *
+     * Use it to capture for as long as the session lives. It is not needed when
+     * you drive the browser yourself and call stop when done.
+     *
+     * @throws the transport failure that ended the capture, if any
+     */
+    wait(): Promise<void>;
+    /**
+     * Ends the capture. Idempotent, and safe to call from a `finally`.
+     *
+     * Once it resolves the handler is no longer running, so data it collected is
+     * complete. Views from {@link CloudBrowser.streamNetworkExchanges} only
+     * detach — they never disarm a capture other readers may share.
+     *
+     * To stop from inside the handler, call
+     * {@link CloudBrowser.stopNetworkCapture} instead: stop awaits the reader,
+     * which cannot finish while the handler it called is still running.
+     *
+     * @throws UNKNOWN_ERROR - the capture could not be disarmed; the local reader
+     *   is shut down regardless
+     */
+    stop(): Promise<void>;
+}

package/dist/network-capture.js

@@ -0,0 +1,107 @@
+import { networkExchangeFromProto } from "./internal/convert.js";
+/**
+ * NetworkCapture is a running capture, returned by
+ * {@link CloudBrowser.captureNetwork}. Exchanges are delivered to the handler
+ * passed there; this handle only exists to stop the capture and to report how
+ * it went.
+ */
+export class NetworkCapture {
+    /** @internal Constructed by CloudBrowser; not part of the public API. */
+    constructor(init) {
+        this.armed = false;
+        this.stopped = false;
+        this.failure = null;
+        this.droppedCount = 0;
+        this.abort = init.abort;
+        this.disarm = init.disarm;
+        this.finished = this.pump(init.stream, init.onExchange);
+    }
+    /**
+     * @internal Marks the capture as armed by this handle, so stop() disarms it
+     * server-side. Views that only attached to someone else's capture stay
+     * unarmed and merely detach.
+     */
+    arm() {
+        this.armed = true;
+    }
+    /**
+     * Reads the stream and calls the handler for each exchange. It never rejects:
+     * a failure is recorded for {@link NetworkCapture.error} instead, so nothing
+     * surfaces as an unhandled rejection.
+     */
+    async pump(stream, onExchange) {
+        try {
+            for await (const event of stream) {
+                if (event.dropped > 0n) {
+                    this.droppedCount = Number(event.dropped);
+                }
+                if (!event.exchange)
+                    continue;
+                onExchange(networkExchangeFromProto(event.exchange));
+            }
+        }
+        catch (err) {
+            // Cancelling is how stop() ends the stream, so the resulting error is
+            // expected rather than a failure worth reporting.
+            if (!this.stopped) {
+                this.failure = err instanceof Error ? err : new Error(String(err));
+            }
+        }
+    }
+    /**
+     * Why the capture ended: null while it is still running, and after a clean
+     * stop or the session ending normally.
+     */
+    get error() {
+        return this.failure;
+    }
+    /**
+     * How many exchanges the server discarded because this reader fell behind.
+     * Anything above zero means the log has holes: make the handler cheaper,
+     * narrow `patterns`, or stop capturing bodies.
+     */
+    get dropped() {
+        return this.droppedCount;
+    }
+    /**
+     * Resolves once the capture ends — {@link NetworkCapture.stop}, a dead
+     * session or a transport failure.
+     *
+     * Use it to capture for as long as the session lives. It is not needed when
+     * you drive the browser yourself and call stop when done.
+     *
+     * @throws the transport failure that ended the capture, if any
+     */
+    async wait() {
+        await this.finished;
+        if (this.failure)
+            throw this.failure;
+    }
+    /**
+     * Ends the capture. Idempotent, and safe to call from a `finally`.
+     *
+     * Once it resolves the handler is no longer running, so data it collected is
+     * complete. Views from {@link CloudBrowser.streamNetworkExchanges} only
+     * detach — they never disarm a capture other readers may share.
+     *
+     * To stop from inside the handler, call
+     * {@link CloudBrowser.stopNetworkCapture} instead: stop awaits the reader,
+     * which cannot finish while the handler it called is still running.
+     *
+     * @throws UNKNOWN_ERROR - the capture could not be disarmed; the local reader
+     *   is shut down regardless
+     */
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        try {
+            if (this.armed)
+                await this.disarm();
+        }
+        finally {
+            this.abort.abort();
+            await this.finished;
+        }
+    }
+}

package/dist/scripts.d.ts

@@ -0,0 +1,205 @@
+import type { ScriptEvent as ScriptEventMessage, ScriptLogEntry as ScriptLogEntryMessage } from "./gen/wrc_pb.ts";
+/** One `console.*` call from a script. */
+export interface ScriptLogEntry {
+    /** `"info"`, `"warning"` or `"error"`, from console.log / .warn / .error. */
+    level: string;
+    /** The logged arguments, already stringified the way console does it. */
+    message: string;
+    /** When the script printed the line, stamped in the browser. */
+    timestamp: Date;
+}
+/** The outcome of a blocking {@link CloudBrowser.runScript}. */
+export interface ScriptResult {
+    /**
+     * False when the script failed to compile or threw; `result` then holds the
+     * message.
+     */
+    success: boolean;
+    /**
+     * The return value as JSON, or `"undefined"` when the script returned
+     * nothing. On failure it is the error message.
+     */
+    result: string;
+    /**
+     * Names the run. It arrives with the reply, so it is only useful after the
+     * fact — to match up log lines a separate follower already saw.
+     */
+    runId: string;
+    /** Everything the script printed, in order. */
+    log: ScriptLogEntry[];
+    /**
+     * True when the script printed more than the reply holds, in which case `log`
+     * is the tail of the output rather than all of it.
+     */
+    truncated: boolean;
+}
+/** How a run ended. */
+export interface ScriptFinished {
+    /**
+     * False when the script failed to compile or threw; `result` then holds the
+     * message.
+     */
+    success: boolean;
+    /** The return value as JSON, or the error message. */
+    result: string;
+    /**
+     * True when the run was cancelled, or the session went away under it, rather
+     * than the script returning on its own.
+     */
+    stopped: boolean;
+}
+/** One run still in flight, as {@link CloudBrowser.listScriptRuns} reports it. */
+export interface ScriptRunInfo {
+    runId: string;
+    /** How long the run has been going, in milliseconds. */
+    runningMs: number;
+}
+/**
+ * One item on a session's script event stream. Exactly one of `log` and
+ * `finished` is set.
+ */
+export interface ScriptEvent {
+    /** The run that produced this event. */
+    runId: string;
+    /** A console line the script printed. */
+    log?: ScriptLogEntry;
+    /** The end of the run. No further event for that run follows. */
+    finished?: ScriptFinished;
+}
+/**
+ * ScriptEventHandler is called once per script event.
+ *
+ * Calls are sequential and in the order the browser produced them, so a run's
+ * last log line always arrives before its `finished`.
+ *
+ * Blocking here stalls delivery: the server buffers a bounded number of events
+ * per reader and then drops its oldest, which {@link ScriptRun.dropped}
+ * reports. Hand slow work to a queue of your own instead of awaiting it here.
+ */
+export type ScriptEventHandler = (event: ScriptEvent) => void;
+/** @internal Converts one log entry off the wire. */
+export declare function scriptLogEntryFromProto(e: ScriptLogEntryMessage): ScriptLogEntry;
+/**
+ * @internal Converts one stream item, or returns null for an event carrying
+ * neither variant — which a newer server could send and an older client should
+ * ignore rather than report as an empty log line.
+ */
+export declare function scriptEventFromProto(event: ScriptEventMessage): ScriptEvent | null;
+/**
+ * ScriptRun is a script running in the background, returned by
+ * {@link CloudBrowser.startScript}. Its output is delivered to the handler
+ * passed there; this handle exists to await the outcome and to cancel the run.
+ */
+export declare class ScriptRun {
+    private readonly abort;
+    private readonly cancel;
+    private readonly finished;
+    private readonly id;
+    private ended;
+    private readonly endedPromise;
+    private detached;
+    private failure;
+    private droppedCount;
+    private result;
+    /** @internal Constructed by CloudBrowser; not part of the public API. */
+    constructor(init: {
+        runId: string;
+        stream: AsyncIterable<ScriptEventMessage>;
+        onEvent: ScriptEventHandler;
+        cancel: (runId: string) => Promise<unknown>;
+        abort: AbortController;
+    });
+    /**
+     * The id the browser gave this run. Pass it to
+     * {@link CloudBrowser.stopScripts} to cancel the run from elsewhere, or to
+     * {@link CloudBrowser.followScript} to watch it from another tab.
+     */
+    get runId(): string;
+    /**
+     * Reads the stream and calls the handler for each event belonging to this
+     * run. Filtering happens here rather than server-side because the
+     * subscription had to exist before the run id did.
+     *
+     * It never rejects: a failure is recorded for {@link ScriptRun.error}
+     * instead, so nothing surfaces as an unhandled rejection.
+     */
+    private pump;
+    /**
+     * Why the stream ended: null while it is still open, and after a clean stop
+     * or the session ending normally.
+     */
+    get error(): Error | null;
+    /**
+     * How many events the server discarded because this reader fell behind.
+     * Anything above zero means the log has holes: make the handler cheaper, or
+     * have the script print less.
+     */
+    get dropped(): number;
+    /**
+     * Resolves once the run ends, with how it ended.
+     *
+     * A script that threw is an outcome, not an error: it resolves with
+     * `success: false`. It rejects when the run's fate is unknown — the stream
+     * broke or the session died before the script finished.
+     *
+     * @returns how the script ended
+     *
+     * @throws UNKNOWN_ERROR - the outcome could not be observed
+     */
+    wait(): Promise<ScriptFinished>;
+    /**
+     * Cancels the run and detaches this reader. Idempotent, and safe to call from
+     * a `finally`.
+     *
+     * A script that is executing is interrupted; one parked on an await unwinds
+     * at its next operation in the page. Either way the handler sees a `finished`
+     * with `stopped` set, unless the local reader is torn down first.
+     *
+     * @throws UNKNOWN_ERROR - the run could not be cancelled server-side; the
+     *   local reader is detached regardless
+     */
+    stop(): Promise<void>;
+    /**
+     * Stops reading this run's output without cancelling the run. The script
+     * keeps going with nobody watching, which is what makes a detached run
+     * outlive the page that started it.
+     */
+    detach(): Promise<void>;
+}
+/**
+ * ScriptFollow is a read-only view of script output, returned by
+ * {@link CloudBrowser.followScript}.
+ */
+export declare class ScriptFollow {
+    private readonly abort;
+    private readonly finished;
+    private stopped;
+    private failure;
+    private droppedCount;
+    /** @internal Constructed by CloudBrowser; not part of the public API. */
+    constructor(init: {
+        stream: AsyncIterable<ScriptEventMessage>;
+        onEvent: ScriptEventHandler;
+        abort: AbortController;
+    });
+    private pump;
+    /**
+     * Why the subscription ended: null while it is still open and after a clean
+     * stop.
+     */
+    get error(): Error | null;
+    /** How many events the server discarded because this reader fell behind. */
+    get dropped(): number;
+    /**
+     * Resolves once the subscription ends — {@link ScriptFollow.stop}, a dead
+     * session or a transport failure.
+     *
+     * @throws the transport failure that ended the subscription, if any
+     */
+    wait(): Promise<void>;
+    /**
+     * Ends the subscription. Idempotent, and safe to call from a `finally`. It
+     * never cancels a run: other readers, and the script itself, are unaffected.
+     */
+    stop(): Promise<void>;
+}