jumpy-lion 0.1.6-beta.7 → 1.0.0-beta.0

package/dist/connection/cdp-reconnection.d.ts

@@ -0,0 +1,50 @@
+/**
+ * CdpReconnection - the single home for CDP connection retry machinery.
+ *
+ * Three call sites used to hand-roll their own loops (CdpPage.reconnectSession,
+ * CDPBrowserController.initialize, CDPBrowserController._attemptReconnect),
+ * each with its own backoff policy and its own fd hygiene - and the fd-leak
+ * fix (old client closed before swap) had landed in only one of them.
+ *
+ * The retry loop, backoff policies, and old-client disposal live here once. The
+ * BINDING strategies stay distinct at the call sites - they differ for
+ * documented anti-detect reasons (the browser socket reconnects over its ws
+ * endpoint; a page re-attaches a flat session and re-enables only previously-
+ * enabled domains).
+ */
+/** Sentinel an attempt returns to stop retrying without a result (e.g. "no page target"). */
+export declare const STOP: unique symbol;
+export interface RetryPolicy {
+    maxAttempts: number;
+    /** Delay before attempt `n` (1-based). Return 0 for no wait. */
+    delayBeforeMs: (attempt: number) => number;
+    /** 'throw' rethrows the last error on exhaustion; 'give-up' resolves undefined. */
+    onExhaustion: 'throw' | 'give-up';
+}
+/** Page re-bind policy: no wait before the first try, then 2^n s capped at 10 s. */
+export declare const exponentialBackoff: (maxAttempts: number) => RetryPolicy;
+/** Root-reconnect policy: fixed pause between attempts, give up silently. */
+export declare const fixedBackoff: (maxAttempts: number, pauseMs: number) => RetryPolicy;
+export interface RunRetriesOptions<T> {
+    /** One bind attempt (1-based attempt number). Return STOP to give up early. */
+    attempt: (attempt: number) => Promise<T | typeof STOP>;
+    policy: RetryPolicy;
+    /** Logged context label, e.g. 'page session' / 'browser root'. */
+    label: string;
+    onAttemptError?: (error: unknown, attempt: number) => void;
+    /** Injectable for tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * The one retry loop. Resolves with the bind result, or undefined when the
+ * attempt asked to STOP or a 'give-up' policy is exhausted.
+ */
+export declare function runWithRetries<T>(options: RunRetriesOptions<T>): Promise<T | undefined>;
+/**
+ * Old-client disposal: close the replaced client tolerantly. Without this the
+ * old websocket lingers until GC and leaks an fd per reconnect.
+ */
+export declare function disposeClient(client: {
+    close?: () => Promise<unknown>;
+} | undefined): Promise<void>;
+//# sourceMappingURL=cdp-reconnection.d.ts.map

package/dist/connection/cdp-reconnection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp-reconnection.d.ts","sourceRoot":"","sources":["../../src/connection/cdp-reconnection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,6FAA6F;AAC7F,eAAO,MAAM,IAAI,eAAkC,CAAC;AAEpD,MAAM,WAAW,WAAW;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3C,mFAAmF;IACnF,YAAY,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC;AAED,oFAAoF;AACpF,eAAO,MAAM,kBAAkB,gBAAiB,MAAM,KAAG,WAIvD,CAAC;AAEH,6EAA6E;AAC7E,eAAO,MAAM,YAAY,gBAAiB,MAAM,WAAW,MAAM,KAAG,WAIlE,CAAC;AAEH,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAChC,+EAA+E;IAC/E,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;IACvD,MAAM,EAAE,WAAW,CAAC;IACpB,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,4BAA4B;IAC5B,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAMD;;;GAGG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAyB7F;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAMzG"}

package/dist/connection/cdp-reconnection.js

@@ -0,0 +1,75 @@
+/**
+ * CdpReconnection - the single home for CDP connection retry machinery.
+ *
+ * Three call sites used to hand-roll their own loops (CdpPage.reconnectSession,
+ * CDPBrowserController.initialize, CDPBrowserController._attemptReconnect),
+ * each with its own backoff policy and its own fd hygiene - and the fd-leak
+ * fix (old client closed before swap) had landed in only one of them.
+ *
+ * The retry loop, backoff policies, and old-client disposal live here once. The
+ * BINDING strategies stay distinct at the call sites - they differ for
+ * documented anti-detect reasons (the browser socket reconnects over its ws
+ * endpoint; a page re-attaches a flat session and re-enables only previously-
+ * enabled domains).
+ */
+import { log } from 'crawlee';
+/** Sentinel an attempt returns to stop retrying without a result (e.g. "no page target"). */
+export const STOP = Symbol('cdp-reconnection-stop');
+/** Page re-bind policy: no wait before the first try, then 2^n s capped at 10 s. */
+export const exponentialBackoff = (maxAttempts) => ({
+    maxAttempts,
+    delayBeforeMs: (attempt) => (attempt === 1 ? 0 : Math.min(1000 * 2 ** (attempt - 1), 10000)),
+    onExhaustion: 'give-up',
+});
+/** Root-reconnect policy: fixed pause between attempts, give up silently. */
+export const fixedBackoff = (maxAttempts, pauseMs) => ({
+    maxAttempts,
+    delayBeforeMs: (attempt) => (attempt === 1 ? 0 : pauseMs),
+    onExhaustion: 'give-up',
+});
+const defaultSleep = async (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+/**
+ * The one retry loop. Resolves with the bind result, or undefined when the
+ * attempt asked to STOP or a 'give-up' policy is exhausted.
+ */
+export async function runWithRetries(options) {
+    const { attempt, policy, label } = options;
+    const sleep = options.sleep ?? defaultSleep;
+    let lastError;
+    for (let n = 1; n <= policy.maxAttempts; n++) {
+        const delay = policy.delayBeforeMs(n);
+        if (delay > 0) {
+            log.debug(`Waiting ${delay}ms before ${label} attempt ${n}/${policy.maxAttempts}`);
+            await sleep(delay);
+        }
+        try {
+            const result = await attempt(n);
+            if (result === STOP)
+                return undefined;
+            return result;
+        }
+        catch (error) {
+            lastError = error;
+            (options.onAttemptError ?? ((err, at) => log.error(`Failed ${label} attempt ${at}/${policy.maxAttempts}`, { error: err })))(error, n);
+        }
+    }
+    if (policy.onExhaustion === 'throw')
+        throw lastError;
+    log.debug(`${label}: max retries reached, giving up`);
+    return undefined;
+}
+/**
+ * Old-client disposal: close the replaced client tolerantly. Without this the
+ * old websocket lingers until GC and leaks an fd per reconnect.
+ */
+export async function disposeClient(client) {
+    try {
+        await client?.close?.();
+    }
+    catch {
+        // tolerate already-closed
+    }
+}
+//# sourceMappingURL=cdp-reconnection.js.map

package/dist/connection/cdp-reconnection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp-reconnection.js","sourceRoot":"","sources":["../../src/connection/cdp-reconnection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAE9B,6FAA6F;AAC7F,MAAM,CAAC,MAAM,IAAI,GAAG,MAAM,CAAC,uBAAuB,CAAC,CAAC;AAUpD,oFAAoF;AACpF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,WAAmB,EAAe,EAAE,CAAC,CAAC;IACrE,WAAW;IACX,aAAa,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,KAAM,CAAC,CAAC;IAC7F,YAAY,EAAE,SAAS;CAC1B,CAAC,CAAC;AAEH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,WAAmB,EAAE,OAAe,EAAe,EAAE,CAAC,CAAC;IAChF,WAAW;IACX,aAAa,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IACzD,YAAY,EAAE,SAAS;CAC1B,CAAC,CAAC;AAaH,MAAM,YAAY,GAAG,KAAK,EAAE,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;IACrE,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAC5B,CAAC,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAI,OAA6B;IACjE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAC3C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC;IAC5C,IAAI,SAAkB,CAAC;IAEvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,KAAK,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;QACtC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACZ,GAAG,CAAC,KAAK,CAAC,WAAW,KAAK,aAAa,KAAK,YAAY,CAAC,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;YACnF,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;QAED,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;YAChC,IAAI,MAAM,KAAK,IAAI;gBAAE,OAAO,SAAS,CAAC;YACtC,OAAO,MAAW,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,SAAS,GAAG,KAAK,CAAC;YAClB,CAAC,OAAO,CAAC,cAAc,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,KAAK,YAAY,EAAE,IAAI,MAAM,CAAC,WAAW,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC1I,CAAC;IACL,CAAC;IAED,IAAI,MAAM,CAAC,YAAY,KAAK,OAAO;QAAE,MAAM,SAAS,CAAC;IACrD,GAAG,CAAC,KAAK,CAAC,GAAG,KAAK,kCAAkC,CAAC,CAAC;IACtD,OAAO,SAAS,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAsD;IACtF,IAAI,CAAC;QACD,MAAM,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACL,0BAA0B;IAC9B,CAAC;AACL,CAAC"}

package/dist/connection/page-session.d.ts

@@ -0,0 +1,114 @@
+/**
+ * PageSession - the live CDP session for one page, flatten-mode transport.
+ *
+ * A page is a CDP *session* (a `sessionId`) multiplexed over the single browser
+ * websocket (ADR 0003), not its own socket. `CdpPage` holds the session-scoped
+ * {@link createSessionClient} proxy and routes every CDP-touching method through
+ * `run(op)`; consumers read the current client through `client()`.
+ *
+ * PageSession owns the page-level connection-liveness *policy*: the reconnect +
+ * `isReconnecting` latch, and re-enabling the previously-enabled domains after a
+ * re-attach. It sits on top of the already-tested CdpReconnection *mechanism*
+ * (`runWithRetries`); the backoff loop is not re-implemented here. The keep-alive
+ * heartbeat is NOT here - with one shared browser socket a single controller-owned
+ * ping loop covers every page, instead of N loops + N ws 'error' listeners.
+ *
+ * Reconnect is a **re-attach**, not a new socket: the injected `reattach()` opens
+ * a fresh session on the (possibly freshly reconnected) browser client and points
+ * the proxy's sessionId at it. The proxy object is stable - there is no client
+ * swap and therefore no fd to dispose.
+ *
+ * Preserved observable behaviour:
+ * - reconnect is skipped while one is already in progress or the page is closed,
+ * - a gone page target stops retrying (the STOP sentinel),
+ * - only the domains that were previously enabled are re-enabled after re-attach,
+ * - there is NO eager Network.enable/Page.enable on any path
+ *   (an anti-detect requirement - domains are enabled lazily by the caller).
+ */
+import type CDP from 'chrome-remote-interface';
+export interface PageSessionOptions {
+    /** The page's session-scoped CDP client (the {@link createSessionClient} proxy). */
+    initialClient: CDP.Client;
+    /**
+     * Re-establish this page's session on the current browser client: attach a
+     * fresh flat session to the page target and point the proxy's sessionId at
+     * it. Throws on a transport error (retried) or when the target is gone
+     * (classified as STOP via {@link isTargetGone}). Omitted in unit tests that
+     * don't exercise reconnect.
+     */
+    reattach?: () => Promise<void>;
+    /** Injectable delay between reconnect attempts (tests pass a no-op). */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Recognises the transport-level errors that a reconnect can recover from. */
+export declare function isConnectionError(error: unknown): boolean;
+/**
+ * Recognises "this sessionId is no longer valid" - the shared browser socket was
+ * reconnected under us and every page's old session died with it, but the target
+ * itself still exists. The socket now reads OPEN, so this is NOT a connection
+ * error; it is nonetheless recoverable by re-attaching a fresh flat session.
+ *
+ * Matches Chrome's actual "session is gone" messages ONLY. A bare `sessionId`
+ * alternative used to be included, which also matched ordinary parameter
+ * validation errors ("Invalid parameters: sessionId: string value expected") -
+ * those are permanent caller bugs, so `run()` burned a pointless re-attach and
+ * retried an operation guaranteed to fail again.
+ */
+export declare function isSessionStale(error: unknown): boolean;
+/**
+ * Recognises "the page target no longer exists" - a re-attach can never succeed,
+ * so stop. This is strictly the *target* being gone (tab closed / crashed); a
+ * merely-stale session (see {@link isSessionStale}) is recoverable and must NOT
+ * match here, or a browser-socket reconnect would wrongly abandon live pages.
+ */
+export declare function isTargetGone(error: unknown): boolean;
+export declare class PageSession {
+    private readonly rawClient;
+    private readonly reattachFn?;
+    private readonly sleep?;
+    /** True while a reconnect is in flight - the latch the call sites coordinate on. */
+    isReconnecting: boolean;
+    private closed;
+    /**
+     * CDP domains the caller has lazily enabled on this session. PageSession
+     * tracks them ONLY so a re-attach re-enables exactly this set on the fresh
+     * session - it never enables a domain on its own.
+     */
+    private readonly enabledDomains;
+    constructor(options: PageSessionOptions);
+    /** The current CDP client - the stable session proxy (auto-follows re-attach). */
+    client(): CDP.Client;
+    /** Record that the page is closed so healing stops. */
+    markClosed(): void;
+    /**
+     * Enable a CDP domain at most once, tracking it for re-enable on re-attach.
+     * No-op if already enabled or the client has no such domain.
+     */
+    enableDomain(domain: string): Promise<void>;
+    /** True when the underlying (shared) CDP WebSocket is open and usable. */
+    private wsOpen;
+    /**
+     * Run a CDP-touching operation with transparent reconnect: pre-heal a
+     * dropped socket, and if the call still fails with a transport error,
+     * reconnect once and retry. Operations on an intentionally-closed page
+     * resolve to `undefined` (callers treat a closed page as a silent no-op).
+     */
+    run<T>(op: () => Promise<T>): Promise<T | undefined>;
+    /**
+     * Heal the CDP session before an operation if the shared socket has dropped.
+     * No-op once the page is intentionally closed or while another reconnect is
+     * already running.
+     */
+    private ensureConnected;
+    /**
+     * Re-bind the page session by re-attaching a fresh flat session to the page
+     * target (via the injected `reattach`) and re-enabling only the
+     * previously-enabled domains. Skipped while another reconnect is in progress
+     * or the page is closed. A gone target stops retrying.
+     *
+     * The retry/backoff machinery lives in CdpReconnection - not re-implemented
+     * here. There is no client swap and no probe socket in flatten mode.
+     */
+    reconnect(retries?: number): Promise<void>;
+}
+//# sourceMappingURL=page-session.d.ts.map

package/dist/connection/page-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-session.d.ts","sourceRoot":"","sources":["../../src/connection/page-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,GAAG,MAAM,yBAAyB,CAAC;AAK/C,MAAM,WAAW,kBAAkB;IAC/B,oFAAoF;IACpF,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,wEAAwE;IACxE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGzD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGtD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGpD;AAED,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAsB;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAgC;IAEvD,oFAAoF;IACpF,cAAc,UAAS;IACvB,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;gBAExC,OAAO,EAAE,kBAAkB;IAMvC,kFAAkF;IAClF,MAAM,IAAI,GAAG,CAAC,MAAM;IAIpB,uDAAuD;IACvD,UAAU,IAAI,IAAI;IAIlB;;;OAGG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUjD,0EAA0E;IAC1E,OAAO,CAAC,MAAM;IAKd;;;;;OAKG;IACG,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IA0B1D;;;;OAIG;YACW,eAAe;IAQ7B;;;;;;;;OAQG;IACG,SAAS,CAAC,OAAO,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAgD9C"}

package/dist/connection/page-session.js

@@ -0,0 +1,237 @@
+/**
+ * PageSession - the live CDP session for one page, flatten-mode transport.
+ *
+ * A page is a CDP *session* (a `sessionId`) multiplexed over the single browser
+ * websocket (ADR 0003), not its own socket. `CdpPage` holds the session-scoped
+ * {@link createSessionClient} proxy and routes every CDP-touching method through
+ * `run(op)`; consumers read the current client through `client()`.
+ *
+ * PageSession owns the page-level connection-liveness *policy*: the reconnect +
+ * `isReconnecting` latch, and re-enabling the previously-enabled domains after a
+ * re-attach. It sits on top of the already-tested CdpReconnection *mechanism*
+ * (`runWithRetries`); the backoff loop is not re-implemented here. The keep-alive
+ * heartbeat is NOT here - with one shared browser socket a single controller-owned
+ * ping loop covers every page, instead of N loops + N ws 'error' listeners.
+ *
+ * Reconnect is a **re-attach**, not a new socket: the injected `reattach()` opens
+ * a fresh session on the (possibly freshly reconnected) browser client and points
+ * the proxy's sessionId at it. The proxy object is stable - there is no client
+ * swap and therefore no fd to dispose.
+ *
+ * Preserved observable behaviour:
+ * - reconnect is skipped while one is already in progress or the page is closed,
+ * - a gone page target stops retrying (the STOP sentinel),
+ * - only the domains that were previously enabled are re-enabled after re-attach,
+ * - there is NO eager Network.enable/Page.enable on any path
+ *   (an anti-detect requirement - domains are enabled lazily by the caller).
+ */
+import { log } from 'crawlee';
+import { runWithRetries, exponentialBackoff, STOP } from './cdp-reconnection.js';
+/** Recognises the transport-level errors that a reconnect can recover from. */
+export function isConnectionError(error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return /WebSocket is not open|WebSocket connection closed|connection closed|readyState/i.test(msg);
+}
+/**
+ * Recognises "this sessionId is no longer valid" - the shared browser socket was
+ * reconnected under us and every page's old session died with it, but the target
+ * itself still exists. The socket now reads OPEN, so this is NOT a connection
+ * error; it is nonetheless recoverable by re-attaching a fresh flat session.
+ *
+ * Matches Chrome's actual "session is gone" messages ONLY. A bare `sessionId`
+ * alternative used to be included, which also matched ordinary parameter
+ * validation errors ("Invalid parameters: sessionId: string value expected") -
+ * those are permanent caller bugs, so `run()` burned a pointless re-attach and
+ * retried an operation guaranteed to fail again.
+ */
+export function isSessionStale(error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return /No session with given id|Session with given id not found|Session not found|sessionId (?:is )?(?:no longer valid|not found)/i.test(msg);
+}
+/**
+ * Recognises "the page target no longer exists" - a re-attach can never succeed,
+ * so stop. This is strictly the *target* being gone (tab closed / crashed); a
+ * merely-stale session (see {@link isSessionStale}) is recoverable and must NOT
+ * match here, or a browser-socket reconnect would wrongly abandon live pages.
+ */
+export function isTargetGone(error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return /No target with given id|Target closed|target closed/i.test(msg);
+}
+export class PageSession {
+    constructor(options) {
+        Object.defineProperty(this, "rawClient", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "reattachFn", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "sleep", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** True while a reconnect is in flight - the latch the call sites coordinate on. */
+        Object.defineProperty(this, "isReconnecting", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "closed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        /**
+         * CDP domains the caller has lazily enabled on this session. PageSession
+         * tracks them ONLY so a re-attach re-enables exactly this set on the fresh
+         * session - it never enables a domain on its own.
+         */
+        Object.defineProperty(this, "enabledDomains", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        this.rawClient = options.initialClient;
+        this.reattachFn = options.reattach;
+        this.sleep = options.sleep;
+    }
+    /** The current CDP client - the stable session proxy (auto-follows re-attach). */
+    client() {
+        return this.rawClient;
+    }
+    /** Record that the page is closed so healing stops. */
+    markClosed() {
+        this.closed = true;
+    }
+    /**
+     * Enable a CDP domain at most once, tracking it for re-enable on re-attach.
+     * No-op if already enabled or the client has no such domain.
+     */
+    async enableDomain(domain) {
+        if (this.enabledDomains.has(domain))
+            return;
+        const api = this.rawClient[domain];
+        if (api?.enable) {
+            await api.enable();
+            this.enabledDomains.add(domain);
+            log.debug(`Enabled ${domain} domain`);
+        }
+    }
+    /** True when the underlying (shared) CDP WebSocket is open and usable. */
+    wsOpen() {
+        const ws = this.rawClient?._ws;
+        return !!ws && ws.readyState === ws.OPEN;
+    }
+    /**
+     * Run a CDP-touching operation with transparent reconnect: pre-heal a
+     * dropped socket, and if the call still fails with a transport error,
+     * reconnect once and retry. Operations on an intentionally-closed page
+     * resolve to `undefined` (callers treat a closed page as a silent no-op).
+     */
+    async run(op) {
+        if (this.closed) {
+            log.debug('Operation skipped - page is closed');
+            return undefined;
+        }
+        await this.ensureConnected();
+        try {
+            return await op();
+        }
+        catch (error) {
+            // A dropped socket (isConnectionError) OR a stale session left behind
+            // by a browser-socket reconnect (isSessionStale) is both healed by a
+            // re-attach + one retry. A stale session does NOT trip isConnectionError
+            // (the new socket reads OPEN), so it must be classified explicitly or
+            // the page would be permanently broken after a browser reconnect.
+            if ((isConnectionError(error) || isSessionStale(error)) && !this.closed) {
+                log.info('Recoverable CDP error during operation, re-attaching and retrying once', {
+                    error: error.message,
+                });
+                await this.reconnect();
+                if (this.closed)
+                    return undefined;
+                return await op();
+            }
+            throw error;
+        }
+    }
+    /**
+     * Heal the CDP session before an operation if the shared socket has dropped.
+     * No-op once the page is intentionally closed or while another reconnect is
+     * already running.
+     */
+    async ensureConnected() {
+        if (this.closed || this.isReconnecting)
+            return;
+        if (!this.wsOpen()) {
+            log.debug('CDP socket not open before operation, re-attaching…');
+            await this.reconnect();
+        }
+    }
+    /**
+     * Re-bind the page session by re-attaching a fresh flat session to the page
+     * target (via the injected `reattach`) and re-enabling only the
+     * previously-enabled domains. Skipped while another reconnect is in progress
+     * or the page is closed. A gone target stops retrying.
+     *
+     * The retry/backoff machinery lives in CdpReconnection - not re-implemented
+     * here. There is no client swap and no probe socket in flatten mode.
+     */
+    async reconnect(retries = 3) {
+        if (this.isReconnecting) {
+            log.debug('Reconnection skipped - already in progress');
+            return;
+        }
+        if (this.closed) {
+            log.debug('Reconnection skipped - page is closed');
+            return;
+        }
+        if (!this.reattachFn) {
+            log.debug('Reconnection skipped - no reattach configured');
+            return;
+        }
+        this.isReconnecting = true;
+        try {
+            await runWithRetries({
+                label: 'page session re-attach',
+                policy: exponentialBackoff(retries),
+                sleep: this.sleep,
+                attempt: async (attempt) => {
+                    try {
+                        await this.reattachFn();
+                    }
+                    catch (error) {
+                        if (isTargetGone(error)) {
+                            log.debug('Page target gone, stopping re-attach');
+                            return STOP;
+                        }
+                        throw error;
+                    }
+                    // Re-enable only the domains that were previously enabled, on
+                    // the fresh session (the proxy now points at the new sessionId).
+                    await Promise.all(Array.from(this.enabledDomains).map(async (domain) => this.rawClient[domain].enable()));
+                    log.info(`Page session re-attached successfully on attempt ${attempt}`);
+                    return true;
+                },
+                onAttemptError: (error) => {
+                    log.error('Failed to re-attach page session', { error });
+                },
+            });
+        }
+        finally {
+            this.isReconnecting = false;
+        }
+    }
+}
+//# sourceMappingURL=page-session.js.map

package/dist/connection/page-session.js.map

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

package/dist/connection/session-client.d.ts

@@ -0,0 +1,34 @@
+/**
+ * SessionClient - a session-scoped view of the single browser CDP client.
+ *
+ * In flatten-mode transport (ADR 0003) there is ONE websocket to the browser
+ * target; every page is a CDP *session* multiplexed over it, addressed by a
+ * `sessionId`. This proxy presents the familiar `CDP.Client` shape to `CdpPage`
+ * and its sub-modules while injecting the page's `sessionId` into every command
+ * and event subscription. That keeps the ~10 `this.client.Domain.method()` call
+ * sites in `page.ts` (and the input transport / injector / inject-hook) exactly
+ * as written - the proxy is the single seam where sessionId enters.
+ *
+ * How `chrome-remote-interface` (0.33.2) exposes things, which this mirrors:
+ * - a command is `Domain.method(params, sessionId, callback)` (decorated
+ *   `.category === 'command'`); we bind arg 2 to the current sessionId.
+ * - an event is `Domain.event(sessionId, handler)` (`.category === 'event'`);
+ *   we bind arg 1 to the current sessionId. It returns an unsubscribe fn.
+ * - the connection also emits every session event under `${Domain.event}.${sessionId}`
+ *   (chrome.js), so raw `client.on('Domain.event', h)` must be rewritten to the
+ *   session-scoped name or it would fire for *every* page's events.
+ *
+ * `browser()` and `sessionId()` are read at call time, so a browser-socket
+ * reconnect (new underlying client) or a session re-attach (new sessionId) is
+ * picked up transparently - the proxy object itself is stable and never needs
+ * to be recreated.
+ */
+import type CDP from 'chrome-remote-interface';
+export interface SessionClientDeps {
+    /** The current shared browser-level CDP client (re-read each call for reconnect safety). */
+    browser: () => CDP.Client;
+    /** The current sessionId for this page (re-read each call; changes on re-attach). */
+    sessionId: () => string;
+}
+export declare function createSessionClient(deps: SessionClientDeps): CDP.Client;
+//# sourceMappingURL=session-client.d.ts.map

package/dist/connection/session-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-client.d.ts","sourceRoot":"","sources":["../../src/connection/session-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,GAAG,MAAM,yBAAyB,CAAC;AAE/C,MAAM,WAAW,iBAAiB;IAC9B,4FAA4F;IAC5F,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,CAAC;IAC1B,qFAAqF;IACrF,SAAS,EAAE,MAAM,MAAM,CAAC;CAC3B;AAuBD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,GAAG,CAAC,MAAM,CAmGvE"}