@monoes/monobrowse 1.0.25 → 1.0.27

package/dist/src/browser/browser.js

@@ -1,795 +1,10 @@
-import { execSync, spawn } from 'node:child_process';
-import { existsSync, readFileSync, rmSync } from 'node:fs';
-import { connect } from 'node:net';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { CdpClient, fetchNewTarget, fetchTargets } from './cdp.js';
-import { enableConsoleCapture, setupConsoleCapture } from './console-log.js';
-import { setupDialogAutoHandling } from './dialog.js';
-import { listSessionRecords, loadSessionRecord, removeSessionRecord, } from './ref-cache.js';
-import { CHROME_EXECUTABLES } from './types.js';
-const DEFAULT_PORT = 9222;
-const LAUNCH_TIMEOUT = 10_000;
-const POLL_INTERVAL = 200;
-const BROWSER_CLOSE_TIMEOUT_MS = 3000;
-// How long closeBrowser() waits for the process to actually disappear before
-// forcing it, and again after forcing. Bounded so a wedged Chrome cannot hang
-// a caller indefinitely.
-const PROCESS_EXIT_TIMEOUT_MS = 5000;
-const PROCESS_EXIT_POLL_MS = 50;
-// A cross-process persisted PID older than this is not trusted for the
-// SIGKILL fallback in closeBrowser() — see the call site for why.
-const PERSISTED_PID_MAX_AGE_MS = 24 * 60 * 60 * 1000;
-// A browser WE launched that has had no targets for longer than this is
-// reaped at the next launch/attach — see reapIdleLaunchedBrowser().
-const IDLE_REAP_AFTER_MS = 30 * 60 * 1000;
-const REAP_CONNECT_TIMEOUT_MS = 3000;
-// Tracks the PID of Chrome instances *we* spawned, keyed by CDP port, so
-// closeBrowser() has a kill fallback when the graceful `Browser.close` CDP
-// command fails or times out (e.g. a hung renderer). Ports we merely attached
-// to (already-running browser) are never recorded here — we only ever kill
-// processes we launched ourselves.
-const launchedPids = new Map();
-// userDataDir per launched port — informational, persisted alongside the pid
-// so a later process could clean up the temp profile dir too if ever needed.
-const launchedUserDataDirs = new Map();
-/** PID of the Chrome instance *this process* launched on `port`, if any. */
-export function getLaunchedPid(port) {
-    return launchedPids.get(port);
-}
-/** userDataDir of the Chrome instance *this process* launched on `port`, if any. */
-export function getLaunchedUserDataDir(port) {
-    return launchedUserDataDirs.get(port);
-}
-function findChrome(executablePath) {
-    if (executablePath) {
-        if (existsSync(executablePath))
-            return executablePath;
-        throw new Error(`Chrome executable not found: ${executablePath}`);
-    }
-    for (const candidate of CHROME_EXECUTABLES) {
-        if (existsSync(candidate))
-            return candidate;
-    }
-    // Try PATH
-    try {
-        const result = execSync('which google-chrome chromium-browser chromium microsoft-edge microsoft-edge-stable 2>/dev/null', { encoding: 'utf8' }).trim();
-        const first = result.split('\n')[0];
-        if (first)
-            return first;
-    }
-    catch {
-        // ignore
-    }
-    throw new Error('No supported browser found. Install Google Chrome, Microsoft Edge, or Chromium — or pass executablePath in BrowserConfig.');
-}
-export async function isPortOpen(port) {
-    try {
-        await fetchTargets(port);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Confirm the CDP endpoint on `port` actually identifies as Chrome/Chromium
- * via `/json/version`'s `Browser` field, rather than assuming any CDP-speaking
- * responder is "ours". Reduces (does not eliminate) the risk of silently
- * attaching to an unrelated real browser that happens to be listening there.
- */
-async function isChromeIdentity(port) {
-    return (await chromeIdentity(port)) === 'chrome';
-}
-/** isChromeIdentity, telling "answered as something else" apart from "did
- *  not answer in time" ('unknown': a timeout, a refused or reset connection,
- *  a non-OK status or an unparseable body). */
-async function chromeIdentity(port) {
-    try {
-        const res = await fetch(`http://127.0.0.1:${port}/json/version`, {
-            signal: AbortSignal.timeout(1000),
-        });
-        if (!res.ok)
-            return 'unknown';
-        const info = (await res.json());
-        // Edge's Browser field is "Edg/<version>" with no "chrome"/"chromium"
-        // substring, even though it's Chromium-based and CDP-compatible —
-        // accept it alongside Chrome/Chromium rather than rejecting a valid target.
-        return typeof info.Browser === 'string' && /chrom(e|ium)|edg/i.test(info.Browser)
-            ? 'chrome'
-            : 'other';
-    }
-    catch {
-        return 'unknown';
-    }
-}
-/** Raw TCP connect probe — distinguishes "nothing listening" from "something listening that isn't CDP". */
-function isTcpPortOpen(port, timeoutMs = 1000) {
-    return new Promise((resolve) => {
-        const socket = connect({ host: '127.0.0.1', port, timeout: timeoutMs });
-        const done = (result) => {
-            socket.removeAllListeners();
-            socket.destroy();
-            resolve(result);
-        };
-        socket.once('connect', () => done(true));
-        socket.once('timeout', () => done(false));
-        socket.once('error', () => done(false));
-    });
-}
-/** Ports scanned when the requested one is occupied by a non-Chrome process
- *  (e.g. another local tool that happens to reuse Chrome's conventional CDP
- *  default, 9222 — mirrors the auto-increment convention this monorepo's own
- *  dashboard server uses in bindServer/server.mjs). Only occupied-by-a-
- *  DIFFERENT-process is worked around; an already-attachable Chrome on the
- *  requested port is still returned as-is (existing "attach, don't relaunch"
- *  behavior). */
-const LAUNCH_PORT_SCAN_TRIES = 10;
-export async function launchBrowser(config = {}) {
-    const rawPort = config.port ?? DEFAULT_PORT;
-    // Port 0 means "let Chrome bind a free port and tell us which" — see
-    // launchOnFreePort. Otherwise validate port is in a safe range for
-    // localhost CDP debugging.
-    if (rawPort === 0) {
-        if (!config.userDataDir) {
-            throw new Error('port 0 requires a dedicated userDataDir (Chrome reports the port it bound inside it).');
-        }
-    }
-    else if (!Number.isInteger(rawPort) || rawPort < 1024 || rawPort > 65535) {
-        throw new Error(`Invalid port: ${rawPort}. Must be 0 or an integer between 1024 and 65535.`);
-    }
-    // Every launch/attach is this tool's only chance to notice that a previous
-    // session abandoned a browser on a CDP port and never gave it back — there
-    // is no daemon to do it on a timer. Bounded and non-throwing; a stale
-    // instance on the port we are about to use is freed before we probe it.
-    await reapIdleLaunchedBrowser();
-    if (rawPort === 0)
-        return launchOnFreePort(config, 0);
-    // strictPort: fail fast on the exact requested port, matching the old
-    // behavior (Vite has the same escape hatch for the same reason) — for
-    // callers that treat the error as a signal ("this port is taken by
-    // something else, bail") rather than consuming the returned port.
-    if (config.strictPort) {
-        if (await isTcpPortOpen(rawPort)) {
-            if (await isChromeIdentity(rawPort))
-                return rawPort;
-            throw new Error(`Port ${rawPort} is occupied by a process that does not identify as Chrome/Chromium. ` +
-                `Refusing to attach — pass a different port or free port ${rawPort}.`);
-        }
-        return launchOnFreePort(config, rawPort);
-    }
-    const candidates = [];
-    for (let i = 0; i < LAUNCH_PORT_SCAN_TRIES && rawPort + i <= 65535; i++)
-        candidates.push(rawPort + i);
-    for (const candidate of candidates) {
-        // TCP-level check for "is anything at all listening" — isPortOpen()
-        // does a full CDP /json fetch, which returns false BOTH for a genuinely
-        // free port and for one occupied by a non-CDP process (that ambiguity is
-        // exactly what the post-spawn isTcpPortOpen fallback below exists to
-        // resolve, the hard way, after a 10s launch timeout). Checking the raw
-        // socket first tells free and occupied apart up front, so the scan can
-        // skip an occupied candidate instead of trying to spawn Chrome on top of
-        // it and only discovering the conflict after a timeout.
-        if (await isTcpPortOpen(candidate)) {
-            // Attach-if-already-Chrome only applies to the EXACT requested port —
-            // the original, deliberate, single-port risk ("don't silently take
-            // over an unrelated real browser that happens to be on this port").
-            // Scanning past an occupied default must not let that same shortcut
-            // attach to a DIFFERENT Chrome instance the caller never named;
-            // forward candidates are launch-only (skip if anything is there,
-            // Chrome or not).
-            if (candidate === rawPort && (await isChromeIdentity(candidate)))
-                return candidate;
-            // Occupied (by anything — not just non-Chrome, per the note above) —
-            // try the next candidate instead of failing outright, same as a
-            // normal EADDRINUSE retry would.
-            continue;
-        }
-        try {
-            return await launchOnFreePort(config, candidate);
-        }
-        catch (err) {
-            const isLastCandidate = candidate === candidates[candidates.length - 1];
-            // isTcpPortOpen() above is a connect() probe, not an atomic claim: two
-            // concurrent launchBrowser() calls with no explicit --port can both
-            // observe the same candidate as free and both spawn Chrome on it
-            // before either binds. One wins; the other's Chrome exits before its
-            // CDP endpoint opens ("Chrome exited before the CDP endpoint opened
-            // ... code=21"). Something is listening on the candidate NOW that
-            // was not a moment ago — a losing race, not a broken Chrome install —
-            // so try the next candidate exactly like an already-occupied one,
-            // instead of failing the whole launch outright. A candidate that
-            // fails with nothing now listening (a real launch failure — bad
-            // executable, sandbox refusal, etc.) is not a race: retrying the
-            // next candidate would only fail the same way, so surface it as-is.
-            if (!isLastCandidate && (await isTcpPortOpen(candidate)))
-                continue;
-            throw err;
-        }
-    }
-    throw new Error(`Ports ${candidates[0]}-${candidates[candidates.length - 1]} are all occupied and port ${candidates[0]} ` +
-        `isn't a Chrome/Chromium instance to attach to. Pass a different --port.`);
-}
-/** The port Chrome wrote to `<userDataDir>/DevToolsActivePort` once its
- *  DevTools server was listening, or null if it has not (yet). */
-function readDevToolsActivePort(file) {
-    try {
-        const port = Number.parseInt(readFileSync(file, 'utf8').split('\n')[0], 10);
-        return Number.isInteger(port) && port > 0 && port <= 65535 ? port : null;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Spawn Chrome and wait for its CDP endpoint.
- *
- * With a fixed `port`, "our Chrome is up" is inferred from *some* Chrome
- * answering on 127.0.0.1:<port> — which is not necessarily ours. When the port
- * is already bound on 127.0.0.1 (a concurrent launch picked the same "free"
- * port between its probe and Chrome's bind), Chrome does not fail: it logs
- * `bind() failed: Address already in use` and listens on [::1]:<port>
- * instead. The poll then accepts the OTHER launcher's browser, both callers
- * drive one Chrome, and whichever closes first kills the other's connections
- * ("CDP connection closed") while this launch's own Chrome is orphaned.
- *
- * `port: 0` removes the race instead of narrowing it: Chrome asks the kernel
- * for a free port at bind time — atomic, nothing to collide on — and writes
- * the port it got to DevToolsActivePort in its own (caller-dedicated) profile
- * directory, which is proof the endpoint is the process we spawned.
- */
-async function launchOnFreePort(config, port) {
-    const chromePath = findChrome(config.executablePath);
-    // Suffixed with our own pid: two concurrent launches that both probe the
-    // same candidate port as free (the race this function exists to survive —
-    // see the retry-on-collision caller above) briefly run Chrome with
-    // *identical* --user-data-dir values if it were derived from the port
-    // alone, sharing a profile directory (lock files, preferences, the
-    // DevToolsActivePort file itself) between two unrelated Chrome processes
-    // for as long as the loser stays alive. Different processes always have
-    // different pids, so this can never collide even when the port does.
-    const userDataDir = config.userDataDir ?? join(tmpdir(), `monomind-browser-${port}-${process.pid}`);
-    const activePortFile = join(userDataDir, 'DevToolsActivePort');
-    // A reused profile dir may hold a previous run's file naming a port some
-    // other process now owns.
-    if (port === 0)
-        rmSync(activePortFile, { force: true });
-    const defaultArgs = [
-        `--remote-debugging-port=${port}`,
-        `--user-data-dir=${userDataDir}`,
-        '--no-first-run',
-        '--no-default-browser-check',
-        '--disable-background-networking',
-        '--disable-client-side-phishing-detection',
-        '--disable-default-apps',
-        '--disable-extensions',
-        '--disable-hang-monitor',
-        '--disable-popup-blocking',
-        '--disable-prompt-on-repost',
-        '--disable-sync',
-        '--disable-translate',
-        '--metrics-recording-only',
-        '--safebrowsing-disable-auto-update',
-        '--password-store=basic',
-        '--use-mock-keychain',
-    ];
-    if (config.headless !== false) {
-        defaultArgs.push('--headless=new');
-    }
-    // Chrome's setuid sandbox cannot initialise on most CI runners and
-    // containers, so the process dies during startup and the CDP endpoint never
-    // opens. The launch below then burns its whole timeout before reporting a
-    // generic failure, which reads as a hang rather than "Chrome could not
-    // start". Disabling the sandbox is the standard remedy and is scoped to CI
-    // so a real user's browser keeps it. --disable-dev-shm-usage goes with it:
-    // a container's default /dev/shm is 64MB, which Chrome exhausts and then
-    // crashes the same way.
-    if (process.env.CI) {
-        defaultArgs.push('--no-sandbox', '--disable-dev-shm-usage');
-    }
-    // Cap caller-supplied args to prevent memory exhaustion via huge argument arrays
-    const callerArgs = (config.args ?? []).slice(0, 50);
-    const args = [...defaultArgs, ...callerArgs];
-    const child = spawn(chromePath, args, {
-        detached: true,
-        stdio: 'ignore',
-    });
-    // Without this, a spawn failure (e.g. EACCES/ENOENT — chromePath exists per
-    // findChrome()'s existsSync check but isn't actually executable, or is
-    // removed between the check and exec) fires Node's 'error' event on the
-    // next tick. With no listener, Node throws it as an uncaught exception and
-    // the whole process goes down — which strands this function's promise
-    // forever pending rather than rejecting it (issue #314: node:test reports
-    // that as "cancelledByParent" / "still pending" because nothing here ever
-    // got the chance to settle it). Recording the failure and having the poll
-    // loop below notice it turns that crash into a normal rejection. 'exit'
-    // covers the twin case: Chrome execs fine but the process itself dies
-    // immediately (missing shared libraries, a container's sandbox refusing
-    // it, etc.) — that fires 'exit', not 'error', and without this the poll
-    // loop would just burn its whole timeout probing a port nothing will ever
-    // open on.
-    let earlyFailure = null;
-    child.on('error', (err) => {
-        earlyFailure ??= new Error(`Chrome failed to start on port ${port}: ${err.message}`);
-    });
-    child.on('exit', (code, signal) => {
-        earlyFailure ??= new Error(`Chrome exited before the CDP endpoint opened on port ${port} ` +
-            `(code=${code ?? 'null'}, signal=${signal ?? 'null'})`);
-    });
-    child.unref();
-    const track = (boundPort) => {
-        if (!child.pid)
-            return;
-        launchedPids.set(boundPort, child.pid);
-        launchedUserDataDirs.set(boundPort, userDataDir);
-    };
-    // Tracked only once Chrome is CONFIRMED up on `boundPort`, not right after
-    // spawn(). For port !== 0 this used to track(port) unconditionally the
-    // moment the child was spawned, before knowing whether it would actually
-    // win the port — when a racing launchBrowser() call retries a candidate
-    // that a concurrent process also spawned Chrome on (see the retry loop in
-    // launchBrowser), BOTH child processes called track() for the SAME
-    // candidate, and whichever call's spawn happened to run last clobbered the
-    // map entry with its own pid — including the LOSING, about-to-exit
-    // process's pid overwriting the real winner's, corrupting the very map
-    // closeBrowser()'s kill fallback depends on.
-    // With port 0 a refused or timed-out launch is not tracked under any port,
-    // so no closeBrowser() could ever reach it — stop it rather than leave it
-    // running.
-    const killUntracked = () => {
-        try {
-            if (child.pid)
-                process.kill(child.pid, 'SIGKILL');
-        }
-        catch {
-            /* already gone */
-        }
-    };
-    const launchTimeout = config.launchTimeoutMs ?? LAUNCH_TIMEOUT;
-    const deadline = Date.now() + launchTimeout;
-    while (Date.now() < deadline) {
-        if (earlyFailure)
-            throw earlyFailure;
-        await sleep(POLL_INTERVAL);
-        if (earlyFailure)
-            throw earlyFailure;
-        const boundPort = port === 0 ? readDevToolsActivePort(activePortFile) : port;
-        if (boundPort !== null && (await isPortOpen(boundPort))) {
-            const identity = await chromeIdentity(boundPort);
-            if (identity === 'chrome') {
-                track(boundPort);
-                return boundPort;
-            }
-            // A Chrome that has only just opened its endpoint, on a loaded
-            // machine, can answer /json/list (no timeout) yet miss the identity
-            // check's 1 s timeout on /json/version. That says nothing about who is
-            // listening — keep polling rather than refuse our own Chrome.
-            if (identity === 'unknown')
-                continue;
-            if (port === 0)
-                killUntracked();
-            throw new Error(`Port ${boundPort} is occupied by a CDP-speaking process that does not identify as Chrome/Chromium. ` +
-                `Refusing to attach — pass a different port or free port ${boundPort}.`);
-        }
-    }
-    if (earlyFailure)
-        throw earlyFailure;
-    if (port === 0) {
-        killUntracked();
-        throw new Error(`Chrome did not report a CDP port in ${activePortFile} within ${launchTimeout}ms`);
-    }
-    // Timed out waiting for our Chrome to come up on the port. Distinguish
-    // "nothing is listening" (real launch failure) from "something non-CDP is
-    // squatting the port" (confusing generic timeout otherwise) via a raw TCP probe.
-    if (await isTcpPortOpen(port)) {
-        throw new Error(`Port ${port} is occupied by a non-Chrome process (TCP connection succeeds but no CDP response within ${launchTimeout}ms). ` +
-            `Free the port or pass a different one.`);
-    }
-    throw new Error(`Chrome failed to start on port ${port} within ${launchTimeout}ms`);
-}
-export async function enableSessionDomains(client, sessionId) {
-    await Promise.all([
-        client.send('Page.enable', {}, sessionId),
-        client.send('Runtime.enable', {}, sessionId),
-        client.send('Network.enable', {}, sessionId),
-        client.send('DOM.enable', {}, sessionId),
-        client.send('Accessibility.enable', {}, sessionId),
-    ]);
-    setupConsoleCapture(client, sessionId);
-    await enableConsoleCapture(client, sessionId);
-    setupDialogAutoHandling(client, sessionId);
-}
-export async function connectToTarget(port, targetId) {
-    const targets = await fetchTargets(port);
-    const pageTargets = targets.filter((t) => t.type === 'page');
-    let target;
-    if (targetId) {
-        const found = pageTargets.find((t) => t.id === targetId);
-        if (!found)
-            throw new Error(`Target ${targetId} not found`);
-        target = found;
-    }
-    else if (pageTargets.length > 0) {
-        target = pageTargets[0];
-    }
-    else {
-        target = await fetchNewTarget(port, 'about:blank');
-    }
-    const wsUrl = target.webSocketDebuggerUrl ?? `ws://127.0.0.1:${port}/devtools/page/${target.id}`;
-    const client = new CdpClient();
-    await client.connect(wsUrl);
-    const { sessionId } = await client.send('Target.attachToTarget', {
-        targetId: target.id,
-        flatten: true,
-    });
-    await enableSessionDomains(client, sessionId);
-    return { client, target, sessionId };
-}
-/**
- * Cleanly terminate a Chrome/Chromium instance we launched on `port`.
- * Sends the `Browser.close` CDP command (the correct graceful shutdown —
- * closes all tabs and exits the process cleanly) over `client`'s connection.
- * If that command fails, times out, or the connection is already gone,
- * falls back to killing the tracked PID directly so a headed/interactive
- * browser window (e.g. one spawned for a login/CAPTCHA flow) never lingers
- * as a visible, authenticated, still-debuggable orphan process.
- *
- * On the graceful path this resolves only once the process is actually gone,
- * or after force-killing it when it outlasts PROCESS_EXIT_TIMEOUT_MS. Chrome
- * acknowledges `Browser.close` well before it exits, and this used to return
- * on the ack with an unref'd 1s timer as the only force-kill — so it resolved
- * while Chrome was still running and holding its port and its profile's
- * singleton lock, and if the caller's process exited first the kill never
- * happened at all. Callers reasonably read a resolved close() as "that
- * browser is gone"; on the graceful path it now means that.
- */
-export async function closeBrowser(client, port) {
-    let gracefullyClosed = false;
-    let closeTimer;
-    try {
-        await Promise.race([
-            client.send('Browser.close', {}),
-            // Deliberately NOT unref'd, for the same reason waitForProcessExit()'s
-            // poll below is not. This timer is the only thing that settles the race
-            // when Chrome's socket dies without ever acknowledging the close, and
-            // closeBrowser() is actively awaited by callers. An unref'd timer does
-            // not hold the event loop open, so Node would consider the loop drained
-            // and exit — status 0, before the caller's verdict was ever printed.
-            // Cleared in the finally so a close that IS acknowledged does not pin
-            // the loop for the rest of BROWSER_CLOSE_TIMEOUT_MS.
-            new Promise((_, reject) => {
-                closeTimer = setTimeout(() => reject(new Error('Browser.close timed out')), BROWSER_CLOSE_TIMEOUT_MS);
-            }),
-        ]);
-        gracefullyClosed = true;
-    }
-    catch {
-        // fall through to PID-kill fallback below
-    }
-    finally {
-        clearTimeout(closeTimer);
-    }
-    let pid = launchedPids.get(port);
-    if (pid === undefined) {
-        // Fresh process (each CLI invocation is its own node process — see
-        // module header) — launchedPids is per-process and empty here even
-        // though a prior `open` in a DIFFERENT process launched this Chrome.
-        // Fall back to the PID that process persisted via saveSessionRecord().
-        try {
-            const persisted = await loadSessionRecord(port);
-            if (persisted?.launched && persisted.pid) {
-                // Bound how far we trust a cross-process PID: if the Chrome we
-                // launched died outside this flow (OOM-killed, host slept, etc.)
-                // without its session record ever being cleared, the OS can recycle
-                // that PID for an unrelated process. There is no cmdline/start-time
-                // check available portably, so a coarse age bound is the practical
-                // guard — a PID persisted more than a day ago is far more likely to
-                // be stale/reused than to still be the same live Chrome.
-                const age = persisted.savedAt !== undefined ? Date.now() - persisted.savedAt : undefined;
-                if (age === undefined || age <= PERSISTED_PID_MAX_AGE_MS) {
-                    pid = persisted.pid;
-                }
-            }
-        }
-        catch {
-            // best-effort — fall through to "nothing to kill" below
-        }
-    }
-    if (pid === undefined)
-        return; // not a process we launched, or too stale to trust — nothing to kill
-    launchedPids.delete(port);
-    // Liveness-check before every SIGKILL (not just the safety-net path below)
-    // — process.kill(pid, 0) throws ESRCH if the PID is no longer running,
-    // which also catches the case where the PID has already been recycled by
-    // an unrelated process that happens to have exited too.
-    if (!gracefullyClosed) {
-        try {
-            process.kill(pid, 0);
-            process.kill(pid, 'SIGKILL');
-        }
-        catch {
-            /* already exited, or never was — nothing to do */
-        }
-        return;
-    }
-    // Browser.close was acknowledged — wait for the process to actually go away,
-    // then force-kill as a safety net in case it hung.
-    if (await waitForProcessExit(pid))
-        return;
-    try {
-        process.kill(pid, 'SIGKILL');
-    }
-    catch {
-        /* raced us to exit — expected */
-    }
-}
-/** Poll until `pid` is gone or PROCESS_EXIT_TIMEOUT_MS elapses. Returns
- *  whether it exited. `process.kill(pid, 0)` throws once the process is no
- *  longer there, on Windows as well as POSIX.
- *
- *  This timer is deliberately NOT unref'd. closeBrowser() awaits this poll
- *  as part of its own return value — a caller that awaits closeBrowser() is
- *  actively blocked on it, not doing other work in the background. Once
- *  Chrome's CDP websocket closes (which happens right around here, as part
- *  of it shutting down), nothing else may be left holding the event loop
- *  open; an unref'd timer at that point never fires because Node considers
- *  the loop drained and exits without running it, leaving this promise (and
- *  closeBrowser()'s) pending forever — reproduced locally by closing a real
- *  launched browser with nothing else scheduled. Bounded by
- *  PROCESS_EXIT_TIMEOUT_MS (5s) either way, so keeping it ref'd only ever
- *  costs a caller a few seconds, never a hang. */
-async function waitForProcessExit(pid) {
-    const deadline = Date.now() + PROCESS_EXIT_TIMEOUT_MS;
-    for (;;) {
-        try {
-            process.kill(pid, 0);
-        }
-        catch {
-            return true;
-        }
-        if (Date.now() >= deadline)
-            return false;
-        await new Promise((resolve) => {
-            setTimeout(resolve, PROCESS_EXIT_POLL_MS);
-        });
-    }
-}
-/**
- * Give back the CDP port of a browser we launched that nothing is using any
- * more. A launched Chrome is deliberately detached and unref'd so it outlives
- * the command that spawned it and later commands can reattach — but nothing
- * reaped it afterwards, so an abandoned session kept listening on its port
- * (9222 by convention, which other local tools want) indefinitely. A foreign
- * CDP server *answers* there rather than refusing the connection, so those
- * tools retry the wrong port and report misleading errors instead of moving on.
- *
- * Nothing long-lived exists to run this on a timer — every CLI command is its
- * own short-lived process — so it runs at the next launch/attach instead
- * (see launchBrowser). A browser is reaped only when ALL of these hold:
- *   - the persisted session says WE launched it — `connect` records
- *     launched:false for a browser that belongs to the user, never touched;
- *   - that session is older than IDLE_REAP_AFTER_MS;
- *   - the CDP endpoint still answers and reports ZERO targets. An open tab,
- *     or a client attached to one (Chrome drops webSocketDebuggerUrl from an
- *     attached target but still lists it), means the session is live and
- *     reattach-across-commands must keep working.
- *
- * Shutdown goes through closeBrowser() on the browser-level websocket — the
- * only connection left once every target is gone — so a recycled PID can
- * never be signaled by mistake: graceful `Browser.close` reaches whatever is
- * actually listening on that port, at any age, and the persisted PID is only
- * ever used for closeBrowser's own age-bounded force-kill.
- *
- * Never throws: a failed reap must not stop a launch. Returns the reaped
- * port, or null when there was nothing to reap. Sessions are per-port
- * (#318), so every recorded one is considered, not just the newest.
- */
-export async function reapIdleLaunchedBrowser() {
-    let reaped = null;
-    for (const session of await listSessionRecords().catch(() => [])) {
-        const port = await reapSession(session);
-        reaped ??= port;
-    }
-    return reaped;
-}
-async function reapSession(session) {
-    try {
-        if (!session.launched || session.savedAt === undefined)
-            return null;
-        if (Date.now() - session.savedAt < IDLE_REAP_AFTER_MS)
-            return null;
-        const wsUrl = await fetchBrowserWebSocketUrl(session.port);
-        if (!wsUrl)
-            return null;
-        if ((await fetchTargets(session.port)).length > 0)
-            return null;
-        const client = new CdpClient();
-        let reapTimer;
-        try {
-            // CdpClient.connect() has no timeout of its own — a socket that never
-            // opens (and never errors) would hang the launch this reap is running
-            // inside of, which is strictly worse than leaving the port squatted.
-            // Not unref'd (see closeBrowser): a socket that never opens and never
-            // errors leaves this timer as the only thing that can settle the race,
-            // and the reap is awaited inside launch/attach. Cleared in the finally
-            // below so a connect that succeeds does not pin the event loop.
-            await Promise.race([
-                client.connect(wsUrl),
-                new Promise((_, reject) => {
-                    reapTimer = setTimeout(() => reject(new Error('Reap: CDP connect timed out')), REAP_CONNECT_TIMEOUT_MS);
-                }),
-            ]);
-            await closeBrowser(client, session.port);
-        }
-        finally {
-            clearTimeout(reapTimer);
-            try {
-                client.close();
-            }
-            catch {
-                /* already gone */
-            }
-        }
-        launchedPids.delete(session.port);
-        launchedUserDataDirs.delete(session.port);
-        await removeSessionRecord(session.port);
-        return session.port;
-    }
-    catch {
-        return null;
-    }
-}
-/** Chrome's browser-level debugger endpoint, from /json/version — the
- *  connection `Browser.close` belongs on. Null if the port isn't answering as
- *  a Chrome/Chromium CDP endpoint (same identity check as isChromeIdentity). */
-async function fetchBrowserWebSocketUrl(port) {
-    const res = await fetch(`http://127.0.0.1:${port}/json/version`, {
-        signal: AbortSignal.timeout(1000),
-    });
-    if (!res.ok)
-        return null;
-    const info = (await res.json());
-    if (typeof info.Browser !== 'string' || !/chrom(e|ium)|edg/i.test(info.Browser))
-        return null;
-    return typeof info.webSocketDebuggerUrl === 'string' ? info.webSocketDebuggerUrl : null;
-}
-export async function openUrl(client, sessionId, url) {
-    // Cap to 2 MB to prevent OOM in CDP message serializer (e.g. data: URI attacks)
-    if (url.length > 2_097_152)
-        throw new Error('URL exceeds 2 MB limit');
-    // Page.navigate reports a protocol-level failure (e.g. a refused connection)
-    // via errorText in its own response, before Chrome ever settles on the
-    // chrome-error://chromewebdata/ page — without this check a refused
-    // connection previously reported success against that error page.
-    const nav = await client.send('Page.navigate', { url }, sessionId);
-    if (nav.errorText)
-        throw new Error(`Navigation to ${url} failed: ${nav.errorText}`);
-    await waitForNetworkIdle(client, sessionId, 500, 30_000);
-}
-export async function waitForLoad(client, sessionId, condition = 'load', timeout = 30_000) {
-    if (condition === 'load' || condition === 'domcontentloaded') {
-        // Guard against race where the page loads before the listener is registered
-        const readyExpr = condition === 'load'
-            ? 'document.readyState === "complete"'
-            : 'document.readyState !== "loading"';
-        const readyCheck = await client
-            .send('Runtime.evaluate', {
-            expression: readyExpr,
-            returnByValue: true,
-        }, sessionId)
-            .catch(() => ({ result: { value: false } }));
-        if (readyCheck.result?.value)
-            return;
-        const event = condition === 'load' ? 'Page.loadEventFired' : 'Page.domContentEventFired';
-        const [eventPromise, cancelOnce] = client.onceWithOff(event, sessionId);
-        let timedOut = false;
-        let timeoutHandle;
-        const timeoutPromise = new Promise((resolve) => {
-            timeoutHandle = setTimeout(() => {
-                timedOut = true;
-                resolve();
-            }, timeout);
-        });
-        try {
-            await Promise.race([eventPromise, timeoutPromise]);
-            if (timedOut)
-                throw new Error(`Timeout waiting for ${condition}`);
-        }
-        finally {
-            cancelOnce();
-            clearTimeout(timeoutHandle);
-        }
-        return;
-    }
-    // networkidle: no network requests for 500ms
-    await waitForNetworkIdle(client, sessionId, 500, timeout);
-}
-async function waitForNetworkIdle(client, sessionId, idleMs, timeout) {
-    return new Promise((resolve, reject) => {
-        let pending = 0;
-        const inflight = new Set();
-        let idleTimer = null;
-        const killTimer = setTimeout(() => {
-            cleanup();
-            reject(new Error('Timeout waiting for networkidle'));
-        }, timeout);
-        const cleanup = () => {
-            if (idleTimer) {
-                clearTimeout(idleTimer);
-                idleTimer = null;
-            }
-            clearTimeout(killTimer);
-            offReq();
-            offResp();
-            offFail();
-            offCache();
-            offResp2();
-        };
-        const settle = () => {
-            cleanup();
-            resolve();
-        };
-        const check = () => {
-            if (pending === 0) {
-                if (idleTimer)
-                    clearTimeout(idleTimer);
-                idleTimer = setTimeout(settle, idleMs);
-            }
-            else {
-                if (idleTimer) {
-                    clearTimeout(idleTimer);
-                    idleTimer = null;
-                }
-            }
-        };
-        const offReq = client.on('Network.requestWillBeSent', (params, sid) => {
-            if (sid !== sessionId)
-                return;
-            const id = params.requestId;
-            if (!inflight.has(id)) {
-                inflight.add(id);
-                pending++;
-                check();
-            }
-        });
-        const decrement = (params, sid) => {
-            if (sid !== sessionId)
-                return;
-            const id = params.requestId;
-            if (inflight.delete(id)) {
-                pending = Math.max(0, pending - 1);
-                check();
-            }
-        };
-        const offResp = client.on('Network.loadingFinished', decrement);
-        const offFail = client.on('Network.loadingFailed', decrement);
-        const offCache = client.on('Network.requestServedFromCache', decrement);
-        // Guard against requests that never fire loadingFinished/loadingFailed (e.g. data: URLs)
-        // Skip 3xx redirect responses — the request continues under the same requestId
-        const offResp2 = client.on('Network.responseReceived', (params, sid) => {
-            const p = params;
-            if (p.response.status >= 300 && p.response.status < 400)
-                return;
-            decrement(params, sid);
-        });
-        check();
-    });
-}
-export async function getCurrentUrl(client, sessionId) {
-    const result = await client.send('Runtime.evaluate', {
-        expression: 'location.href',
-        returnByValue: true,
-    }, sessionId);
-    return result.result?.value ?? '';
-}
-export async function getCurrentTitle(client, sessionId) {
-    const result = await client.send('Runtime.evaluate', {
-        expression: 'document.title',
-        returnByValue: true,
-    }, sessionId);
-    return result.result?.value ?? '';
-}
-function sleep(ms) {
-    return new Promise((r) => setTimeout(r, ms));
-}
+// File-size sweep: split into sibling modules (browser-state, browser-discovery,
+// browser-launch, browser-lifecycle, browser-page). Pure move — this file now
+// re-exports everything it used to define, so every existing import path
+// keeps working.
+export { isPortOpen } from './browser-discovery.js';
+export { launchBrowser } from './browser-launch.js';
+export { closeBrowser, reapIdleLaunchedBrowser } from './browser-lifecycle.js';
+export { connectToTarget, enableSessionDomains, getCurrentTitle, getCurrentUrl, openUrl, waitForLoad, } from './browser-page.js';
+export { getLaunchedPid, getLaunchedUserDataDir } from './browser-state.js';
 //# sourceMappingURL=browser.js.map