/** * Chrome launcher for the TeamShare debug browser. * * Spawns a Chrome/Chromium process with --remote-debugging-port for CDP * access. Used by BrowserSession/`browse` when autoLaunch is enabled. * * Lifecycle rule (2026-09, two browsers): the launcher always spawns Chrome * DETACHED, so the browser survives the session process being killed and is * never taken down by a tree kill (libuv would otherwise put it in a Windows * Job Object with KILL_ON_JOB_CLOSE). Ownership is decided by `surviveStop`: * * - `true` (default) - the human's window: `kill()` is a deliberate no-op. * Used by `browser start` and the AUTO-ANSWER browser, which the bridge * must never close. * - `false` - a throwaway instance the bridge created and owns * (the DEBUG browser). `BrowserSession` passes false and closes it itself * through `killChromeOnPort` (graceful → forced → verified), because this * signal only reaches the launcher process and cannot be trusted to end * the real browser. * * The auto-answer browser (port 9222, `DEFAULT_BROWSER_PROFILE_DIR`) and the * debug browser (port 9333, `DEBUG_PROFILE_DIR`) are separate processes on * separate ports, so closing one can never close the other. */ import { type ChildProcess } from 'node:child_process'; export interface ChromeInstance { port: number; process: ChildProcess; userDataDir: string; /** * True when the bridge must NEVER terminate this browser - the auto-answer * browser and any window the human started. False means the bridge launched * it and may close it (see the header). */ surviveStop: boolean; kill: () => void; } export interface LaunchOptions { /** Port for CDP (default 9222). */ port?: number; /** Run in headless mode (default false: real persistent profile window). */ headless?: boolean; /** Custom user data dir (default: auto-generated temp dir). */ userDataDir?: string; /** * Keep the browser alive when the launching session ends (default true). * * The debug browser is a normal window the human may still be using - and * with `--auto-launch` it is a CHILD of the run process, so a plain session * teardown killed it. Pass `false` only for a throwaway instance the bridge * created for itself and genuinely owns. */ surviveStop?: boolean; /** * Startup page. Defaults to `about:blank` so the first tab is a real, * attachable `page` target - Chrome's default New Tab Page (`chrome://newtab`) * is excluded by the CDP tab picker and refuses to render in a scripted * profile, which made a freshly launched browser impossible to attach to. */ startUrl?: string; /** Extra Chrome CLI args. */ args?: string[]; /** * OPT-IN (2026-10): reduce the automation fingerprint. Drops the * Puppeteer-style flags (`--disable-extensions`, `--disable-sync`, …) that * sites use as automation tells. The session also injects the pre-document * shims (webdriver/chrome/plugins) - that shim, NOT a `--disable-blink- * features` switch, is what removes `navigator.webdriver` (see the launch * flags below for why the switch was removed). * Off by default: a deterministic QA browser is intentionally boring, and * aggressive spoofing can break a site that expects a normal Chrome. */ stealth?: boolean; /** Timeout to wait for Chrome to become reachable (ms, default 15000). */ timeoutMs?: number; } /** * Launch Chrome with CDP enabled. */ export declare function launchChrome(options?: LaunchOptions): Promise;