@rynx-ai/daemon 0.1.0 → 0.1.9

package/dist/headless-browser-host.js

@@ -0,0 +1,2156 @@
+import { createHash, randomBytes } from "node:crypto";
+import { execFile, spawn } from "node:child_process";
+import { accessSync, chmodSync, closeSync, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync, } from "node:fs";
+import { constants as fsConstants } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { rynxHome } from "@rynx-ai/core";
+import { RUNTIME_BROWSER_MAX_PAGES, RUNTIME_BROWSER_MAX_TITLE_CHARS, RUNTIME_BROWSER_MAX_URL_CHARS, } from "@rynx-ai/protocol/runtime-browser";
+import { RUNTIME_BROWSER_SURFACE_MAX_ENCODED_FRAME_BYTES, RUNTIME_BROWSER_SURFACE_MAX_FRAME_RATE, RUNTIME_BROWSER_SURFACE_MAX_VIEWPORT_HEIGHT, RUNTIME_BROWSER_SURFACE_MAX_VIEWPORT_PIXELS, RUNTIME_BROWSER_SURFACE_MAX_VIEWPORT_WIDTH, } from "@rynx-ai/protocol/runtime-browser-surface";
+import { SessionBrowserHostError, } from "@rynx-ai/server";
+import WebSocket from "ws";
+import { createChromeForTestingArtifactStore, } from "./chrome-for-testing-store.js";
+import { cdpKeyboardEventParams } from "./cdp-keyboard-input.js";
+const PROFILE_OWNER_FILE = ".rynx-headless-browser-profile.json";
+const PROCESS_LEASE_FILE = ".rynx-headless-browser-process.json";
+const DEVTOOLS_ACTIVE_PORT_FILE = "DevToolsActivePort";
+const MAX_PROFILE_METADATA_BYTES = 4 * 1_024;
+const MAX_PROCESS_COMMAND_BYTES = 64 * 1_024;
+const MAX_ACTIVE_PORT_BYTES = 1_024;
+const MAX_CDP_MESSAGE_BYTES = 4 * 1_024 * 1_024;
+const DEFAULT_STARTUP_TIMEOUT_MS = 15_000;
+const DEFAULT_CDP_COMMAND_TIMEOUT_MS = 10_000;
+const DEFAULT_TERMINATION_GRACE_MS = 2_500;
+const DEFAULT_ACTIVE_PORT_POLL_MS = 25;
+const STARTUP_PAGE_CLEANUP_ATTEMPTS = 40;
+const STARTUP_PAGE_CLEANUP_POLL_MS = 25;
+const PAGE_SNAPSHOT_TRANSITION_ATTEMPTS = 5;
+const PAGE_SNAPSHOT_TRANSITION_POLL_MS = 25;
+const BROWSER_CAPABILITIES = ["navigation", "pages", "runtime-local-cdp", "surface"];
+const MIN_SURFACE_QUALITY = 1;
+const MAX_SURFACE_QUALITY = 100;
+const MIN_SURFACE_FALLBACK_INTERVAL_MS = 200;
+const MIN_SURFACE_SCREENCAST_IDLE_MS = 250;
+const DEVTOOLS_BROWSER_PATH = /^\/devtools\/browser\/[A-Za-z0-9._~-]+$/;
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/;
+const CONTROL_CHARACTER_GLOBAL_PATTERN = /[\u0000-\u001f\u007f]/g;
+export function createHeadlessBrowserHost(options = {}) {
+    return new HeadlessBrowserHost(options);
+}
+export function headlessBrowserProfilePath(profileRoot, sessionId) {
+    const digest = createHash("sha256").update(sessionId, "utf8").digest("hex");
+    return join(resolve(profileRoot), `session-${digest}`);
+}
+class HeadlessBrowserHost {
+    artifactStore;
+    profileRoot;
+    startupTimeoutMs;
+    cdpCommandTimeoutMs;
+    terminationGraceMs;
+    activePortPollMs;
+    active = new Map();
+    creating = new Set();
+    recovery;
+    constructor(options) {
+        // Resolve the currently supported host only when Browser creation is
+        // requested, so an unsupported platform can still run the rest of Rynx.
+        this.artifactStore = options.artifactStore;
+        this.profileRoot = resolve(options.profileRoot ?? join(rynxHome(), "browser", "profiles", "headless-chromium"));
+        this.startupTimeoutMs = positiveDuration(options.startupTimeoutMs, DEFAULT_STARTUP_TIMEOUT_MS, "startupTimeoutMs");
+        this.cdpCommandTimeoutMs = positiveDuration(options.cdpCommandTimeoutMs, DEFAULT_CDP_COMMAND_TIMEOUT_MS, "cdpCommandTimeoutMs");
+        this.terminationGraceMs = positiveDuration(options.terminationGraceMs, DEFAULT_TERMINATION_GRACE_MS, "terminationGraceMs");
+        this.activePortPollMs = positiveDuration(options.activePortPollMs, DEFAULT_ACTIVE_PORT_POLL_MS, "activePortPollMs");
+        // A newly constructed Host represents the current daemon incarnation.
+        // Start fenced orphan recovery immediately instead of waiting for the next
+        // Browser mutation; retain the same promise so create/delete still observe
+        // and surface a recovery failure.
+        this.recovery = recoverOwnedProfileProcesses(this.profileRoot, this.terminationGraceMs);
+        void this.recovery.catch(() => undefined);
+    }
+    async createBrowser(input) {
+        await this.recoverOrphanedProcesses();
+        if (this.active.has(input.sessionId) || this.creating.has(input.sessionId)) {
+            throw new SessionBrowserHostError("capacity", "A Headless Browser process already owns this Session profile");
+        }
+        this.creating.add(input.sessionId);
+        try {
+            return await this.createBrowserGeneration(input);
+        }
+        finally {
+            this.creating.delete(input.sessionId);
+        }
+    }
+    async createBrowserGeneration(input) {
+        const reservation = await this.reserveActiveBuildForLaunch();
+        const build = reservation.build;
+        let profileDir;
+        try {
+            validateActiveExecutable(build);
+            profileDir = ensureOwnedProfile(this.profileRoot, input.sessionId);
+            assertProfileProcessLeaseClear(profileDir);
+            removeStaleActivePort(profileDir);
+        }
+        catch (error) {
+            reservation.release();
+            throw error;
+        }
+        const ownerToken = randomBytes(32).toString("hex");
+        const args = chromeArguments(profileDir, ownerToken, input.url ?? "about:blank");
+        let child;
+        try {
+            child = spawn(build.executablePath, args, {
+                detached: true,
+                stdio: ["ignore", "ignore", "pipe"],
+            });
+        }
+        catch (error) {
+            reservation.release();
+            throw unavailable("Managed Chrome for Testing could not be launched", error);
+        }
+        const observed = observeProcess(child);
+        const diagnostics = boundedStderr(child);
+        let connection;
+        let handle;
+        let lease;
+        try {
+            await observed.spawned;
+            lease = writeProcessLease(profileDir, build.executablePath, child, ownerToken);
+            // pruneBuilds shares this store lock. Release it only after the live
+            // process has a visible owned lease that pruning will retain.
+            reservation.release();
+            const endpoint = await waitForDevToolsActivePort({
+                profileDir,
+                exit: observed.exit,
+                timeoutMs: this.startupTimeoutMs,
+                pollMs: this.activePortPollMs,
+                diagnostics,
+            });
+            connection = await CdpConnection.connect(endpoint, this.cdpCommandTimeoutMs);
+            const version = await connection.command("Browser.getVersion");
+            const engineVersion = boundedEngineVersion(version.product);
+            handle = new HeadlessBrowserHandle({
+                input,
+                endpoint,
+                engineVersion,
+                child,
+                exit: observed.exit,
+                profileDir,
+                ownerToken,
+                connection,
+                terminationGraceMs: this.terminationGraceMs,
+                release: () => {
+                    if (this.active.get(input.sessionId) === handle)
+                        this.active.delete(input.sessionId);
+                },
+            });
+            await handle.initialize();
+            this.active.set(input.sessionId, handle);
+            return handle;
+        }
+        catch (error) {
+            connection?.close();
+            await terminateProcessGroup(child, observed.exit, this.terminationGraceMs).catch(() => undefined);
+            if (lease)
+                removeMatchingProcessLease(profileDir, ownerToken);
+            throw error instanceof SessionBrowserHostError
+                ? error
+                : unavailable(`Managed Chrome for Testing did not become ready${diagnostics() ? `: ${diagnostics()}` : ""}`, error);
+        }
+        finally {
+            reservation.release();
+        }
+    }
+    async deleteSessionData(sessionId) {
+        await this.recoverOrphanedProcesses();
+        if (this.creating.has(sessionId)) {
+            throw new SessionBrowserHostError("unavailable", "Headless Browser Session data cannot be deleted while its process is starting");
+        }
+        const live = this.active.get(sessionId);
+        if (live)
+            await live.close();
+        removeOwnedProfile(this.profileRoot, sessionId);
+    }
+    recoverOrphanedProcesses() {
+        return this.recovery ??= recoverOwnedProfileProcesses(this.profileRoot, this.terminationGraceMs);
+    }
+    async reserveActiveBuildForLaunch() {
+        let reservation;
+        try {
+            this.artifactStore ??= createChromeForTestingArtifactStore();
+            reservation = await this.artifactStore.reserveActiveForLaunch();
+        }
+        catch (error) {
+            throw unavailable("The active Chrome for Testing build is invalid", error);
+        }
+        if (!reservation) {
+            throw new SessionBrowserHostError("unavailable", "No managed Chrome for Testing build is installed");
+        }
+        return reservation;
+    }
+}
+class HeadlessBrowserHandle {
+    host;
+    executionBackend = "headless-chromium";
+    capabilities = BROWSER_CAPABILITIES;
+    events;
+    eventQueue = new BrowserHostEventQueue();
+    targets = new Map();
+    closingTargetIds = new Set();
+    pageSessions = new Map();
+    targetBySession = new Map();
+    surfaceSources = new Map();
+    loadingTargets = new Set();
+    activeTargetId = null;
+    unavailableReason;
+    closing = false;
+    closePromise;
+    operations = Promise.resolve();
+    constructor(host) {
+        this.host = host;
+        this.events = this.eventQueue;
+        this.host.connection.setEventHandler((event) => this.onCdpEvent(event));
+        this.host.connection.setDisconnectHandler((reason) => this.markUnavailable(reason));
+        void this.host.exit.then((result) => {
+            removeMatchingProcessLease(this.host.profileDir, this.host.ownerToken);
+            if (!this.closing) {
+                const reason = `Chrome for Testing exited (${result.code ?? result.signal ?? "unknown"})`;
+                this.markUnavailable(reason);
+            }
+        });
+    }
+    get browserGeneration() {
+        return this.host.input.browserGeneration;
+    }
+    async initialize() {
+        await this.host.connection.command("Target.setDiscoverTargets", { discover: true });
+        await this.replaceRestoredStartupPages(this.host.input.url ?? "about:blank");
+        await this.refreshTargets();
+        const requestedUrl = this.host.input.url;
+        if (requestedUrl) {
+            let requestedTarget;
+            for (const target of this.targets.values()) {
+                if (target.url === requestedUrl)
+                    requestedTarget = target;
+            }
+            if (requestedTarget) {
+                await this.host.connection.command("Target.activateTarget", {
+                    targetId: requestedTarget.targetId,
+                });
+                this.activeTargetId = requestedTarget.targetId;
+            }
+        }
+    }
+    async getCdpEndpoint() {
+        this.ensureAvailable();
+        return { endpoint: this.host.endpoint, engineVersion: this.host.engineVersion };
+    }
+    openSurface(input) {
+        return this.exclusive(async () => {
+            this.ensureAvailable();
+            validateSurfaceOpenInput(input);
+            if (input.browserGeneration !== this.browserGeneration) {
+                throw new SessionBrowserHostError("unavailable", "Browser Surface generation is stale");
+            }
+            this.requireTarget(input.hostPageId);
+            if (input.signal?.aborted) {
+                throw new SessionBrowserHostError("unavailable", "Browser Surface open was cancelled");
+            }
+            if (this.surfaceSources.has(input.hostPageId)) {
+                throw new SessionBrowserHostError("capacity", "A Browser Surface already owns this physical Page source");
+            }
+            const pageSessionId = await this.pageSession(input.hostPageId);
+            let source;
+            source = new HeadlessBrowserSurfaceSource({
+                input,
+                pageSessionId,
+                connection: this.host.connection,
+                ensureCurrent: () => {
+                    this.ensureAvailable();
+                    this.requireTarget(input.hostPageId);
+                    if (this.surfaceSources.get(input.hostPageId) !== source) {
+                        throw new SessionBrowserHostError("unavailable", "Browser Surface is closed");
+                    }
+                },
+                mapError: (error) => this.mapOperationError(error),
+                release: () => {
+                    if (this.surfaceSources.get(input.hostPageId) === source) {
+                        this.surfaceSources.delete(input.hostPageId);
+                    }
+                },
+            });
+            this.surfaceSources.set(input.hostPageId, source);
+            try {
+                await source.initialize();
+                return source;
+            }
+            catch (error) {
+                await source.close().catch(() => undefined);
+                throw this.mapOperationError(error);
+            }
+        });
+    }
+    snapshot() {
+        return this.exclusive(async () => {
+            this.ensureAvailable();
+            await this.refreshTargets();
+            const pages = [];
+            for (const target of this.targets.values()) {
+                try {
+                    pages.push(await this.snapshotPage(target));
+                }
+                catch (error) {
+                    if (isMissingPageError(error)) {
+                        this.dropTarget(target.targetId);
+                        continue;
+                    }
+                    throw this.mapOperationError(error);
+                }
+            }
+            if (this.activeTargetId !== null && !pages.some((page) => page.hostPageId === this.activeTargetId)) {
+                this.activeTargetId = pages.at(-1)?.hostPageId ?? null;
+            }
+            return { pages, activeHostPageId: this.activeTargetId };
+        });
+    }
+    createPage(url = "about:blank") {
+        return this.exclusive(async () => {
+            this.ensureAvailable();
+            try {
+                await this.refreshTargets();
+                if (this.targets.size >= RUNTIME_BROWSER_MAX_PAGES) {
+                    throw new SessionBrowserHostError("capacity", "Headless Browser Page capacity was reached");
+                }
+                const result = await this.host.connection.command("Target.createTarget", { url });
+                const targetId = requiredCdpId(result.targetId, "Target.createTarget targetId");
+                this.activeTargetId = targetId;
+                await this.refreshTargets();
+                this.eventQueue.changed(this.browserGeneration);
+            }
+            catch (error) {
+                throw this.mapOperationError(error);
+            }
+        });
+    }
+    closePage(hostPageId) {
+        return this.exclusive(async () => {
+            this.ensureAvailable();
+            try {
+                this.requireTarget(hostPageId);
+                const result = await this.host.connection.command("Target.closeTarget", {
+                    targetId: hostPageId,
+                });
+                if (result.success !== true)
+                    throw missingPage();
+                this.closingTargetIds.add(hostPageId);
+                this.dropTarget(hostPageId);
+                if (this.activeTargetId === hostPageId) {
+                    this.activeTargetId = [...this.targets.keys()].at(-1) ?? null;
+                }
+                this.eventQueue.changed(this.browserGeneration);
+            }
+            catch (error) {
+                throw this.mapOperationError(error);
+            }
+        });
+    }
+    activatePage(hostPageId) {
+        return this.exclusive(async () => {
+            this.ensureAvailable();
+            this.requireTarget(hostPageId);
+            try {
+                await this.host.connection.command("Target.activateTarget", { targetId: hostPageId });
+            }
+            catch (error) {
+                throw this.mapOperationError(error);
+            }
+            this.activeTargetId = hostPageId;
+            this.eventQueue.changed(this.browserGeneration);
+        });
+    }
+    navigatePage(hostPageId, url) {
+        return this.pageCommand(hostPageId, "Page.navigate", { url });
+    }
+    goBack(hostPageId) {
+        return this.navigateHistory(hostPageId, -1);
+    }
+    goForward(hostPageId) {
+        return this.navigateHistory(hostPageId, 1);
+    }
+    reload(hostPageId) {
+        return this.pageCommand(hostPageId, "Page.reload", {});
+    }
+    close() {
+        if (this.closePromise)
+            return this.closePromise;
+        this.closing = true;
+        this.closePromise = (async () => {
+            await Promise.allSettled([...this.surfaceSources.values()].map((source) => source.close()));
+            this.host.connection.close();
+            let terminated = false;
+            try {
+                await terminateProcessGroup(this.host.child, this.host.exit, this.host.terminationGraceMs);
+                removeMatchingProcessLease(this.host.profileDir, this.host.ownerToken);
+                terminated = true;
+            }
+            finally {
+                if (terminated)
+                    this.host.release();
+                this.eventQueue.end();
+            }
+        })();
+        return this.closePromise;
+    }
+    navigateHistory(hostPageId, delta) {
+        return this.exclusive(async () => {
+            this.ensureAvailable();
+            try {
+                const sessionId = await this.pageSession(hostPageId);
+                const history = await this.host.connection.command("Page.getNavigationHistory", {}, sessionId);
+                const parsed = parseNavigationHistory(history);
+                const next = parsed.entries[parsed.currentIndex + delta];
+                if (!next)
+                    return;
+                await this.host.connection.command("Page.navigateToHistoryEntry", { entryId: next.id }, sessionId);
+                this.eventQueue.changed(this.browserGeneration);
+            }
+            catch (error) {
+                throw this.mapOperationError(error);
+            }
+        });
+    }
+    pageCommand(hostPageId, method, params) {
+        return this.exclusive(async () => {
+            this.ensureAvailable();
+            try {
+                const sessionId = await this.pageSession(hostPageId);
+                await this.host.connection.command(method, params, sessionId);
+                this.eventQueue.changed(this.browserGeneration);
+            }
+            catch (error) {
+                throw this.mapOperationError(error);
+            }
+        });
+    }
+    async refreshTargets() {
+        try {
+            const targets = await this.readPageTargets();
+            const next = new Map();
+            for (const target of targets) {
+                if (next.size >= RUNTIME_BROWSER_MAX_PAGES) {
+                    throw new SessionBrowserHostError("capacity", "Headless Browser has too many Pages");
+                }
+                next.set(target.targetId, target);
+            }
+            for (const targetId of this.targets.keys()) {
+                if (!next.has(targetId))
+                    this.dropTarget(targetId);
+            }
+            this.targets.clear();
+            for (const [targetId, target] of next)
+                this.targets.set(targetId, target);
+            if (this.activeTargetId === null || !this.targets.has(this.activeTargetId)) {
+                this.activeTargetId = [...this.targets.keys()].at(-1) ?? null;
+            }
+            await Promise.all([...this.targets.keys()].map(async (targetId) => {
+                try {
+                    await this.pageSession(targetId);
+                }
+                catch (error) {
+                    // Target.getTargets is only a point-in-time snapshot. A Page may be
+                    // destroyed before its CDP session is attached, especially directly
+                    // after Target.closeTarget succeeds. That is normal Page convergence,
+                    // not a Browser-level failure.
+                    if (isMissingPageError(error)) {
+                        this.dropTarget(targetId);
+                        return;
+                    }
+                    throw error;
+                }
+            }));
+            if (this.activeTargetId !== null && !this.targets.has(this.activeTargetId)) {
+                this.activeTargetId = [...this.targets.keys()].at(-1) ?? null;
+            }
+        }
+        catch (error) {
+            throw this.mapOperationError(error);
+        }
+    }
+    async replaceRestoredStartupPages(url) {
+        const initialPages = await this.readPageTargets();
+        if (initialPages.length <= 1)
+            return;
+        const created = await this.host.connection.command("Target.createTarget", { url });
+        const freshTargetId = requiredCdpId(created.targetId, "Target.createTarget targetId");
+        this.activeTargetId = freshTargetId;
+        for (let attempt = 0; attempt < STARTUP_PAGE_CLEANUP_ATTEMPTS; attempt += 1) {
+            const pages = await this.readPageTargets();
+            if (!pages.some((page) => page.targetId === freshTargetId)) {
+                throw new Error("Headless Browser fresh startup Page disappeared");
+            }
+            const restoredPages = pages.filter((page) => page.targetId !== freshTargetId);
+            if (restoredPages.length === 0)
+                return;
+            for (const page of restoredPages) {
+                try {
+                    await this.host.connection.command("Target.closeTarget", { targetId: page.targetId });
+                }
+                catch (error) {
+                    if (!isMissingPageError(error))
+                        throw error;
+                }
+            }
+            await delay(STARTUP_PAGE_CLEANUP_POLL_MS);
+        }
+        throw new Error("Headless Browser restored Pages did not close during startup");
+    }
+    async readPageTargets() {
+        const result = await this.host.connection.command("Target.getTargets");
+        if (!Array.isArray(result.targetInfos)) {
+            throw new Error("CDP Target.getTargets omitted targetInfos");
+        }
+        const pages = result.targetInfos
+            .map((value) => parseTargetInfo(value))
+            .filter((target) => target.type === "page");
+        const observedIds = new Set(pages.map((target) => target.targetId));
+        for (const targetId of this.closingTargetIds) {
+            if (!observedIds.has(targetId))
+                this.closingTargetIds.delete(targetId);
+        }
+        return pages.filter((target) => !this.closingTargetIds.has(target.targetId));
+    }
+    async snapshotPage(target) {
+        const sessionId = await this.pageSession(target.targetId);
+        for (let attempt = 0; attempt < PAGE_SNAPSHOT_TRANSITION_ATTEMPTS; attempt += 1) {
+            let history;
+            try {
+                history = parseNavigationHistory(await this.host.connection.command("Page.getNavigationHistory", {}, sessionId));
+            }
+            catch (error) {
+                if (!isTransientPageTransitionError(error))
+                    throw error;
+                if (attempt < PAGE_SNAPSHOT_TRANSITION_ATTEMPTS - 1) {
+                    await delay(PAGE_SNAPSHOT_TRANSITION_POLL_MS);
+                }
+                continue;
+            }
+            let ready = "loading";
+            try {
+                ready = parseReadyState(await this.host.connection.command("Runtime.evaluate", { expression: "document.readyState", returnByValue: true }, sessionId));
+            }
+            catch (error) {
+                if (!isTransientPageTransitionError(error))
+                    throw error;
+            }
+            const current = history.entries[history.currentIndex];
+            const currentTarget = this.targets.get(target.targetId) ?? target;
+            return {
+                hostPageId: target.targetId,
+                url: displayUrl(current?.url ?? currentTarget.url),
+                title: displayTitle(currentTarget.title),
+                loading: this.loadingTargets.has(target.targetId) || ready !== "complete",
+                canGoBack: history.currentIndex > 0,
+                canGoForward: history.currentIndex >= 0 && history.currentIndex < history.entries.length - 1,
+            };
+        }
+        // Chrome briefly reports an attached Page as inactive while a cross-site
+        // navigation swaps renderers. Target.getTargets already proved the Page is
+        // still present, so expose a conservative loading snapshot instead of
+        // escalating a renderer transition into a Browser-level failure.
+        return {
+            hostPageId: target.targetId,
+            url: displayUrl((this.targets.get(target.targetId) ?? target).url),
+            title: displayTitle((this.targets.get(target.targetId) ?? target).title),
+            loading: true,
+            canGoBack: false,
+            canGoForward: false,
+        };
+    }
+    async pageSession(targetId) {
+        this.requireTarget(targetId);
+        const existing = this.pageSessions.get(targetId);
+        if (existing)
+            return existing;
+        const pending = (async () => {
+            const result = await this.host.connection.command("Target.attachToTarget", {
+                targetId,
+                flatten: true,
+            });
+            const sessionId = requiredCdpId(result.sessionId, "Target.attachToTarget sessionId");
+            this.targetBySession.set(sessionId, targetId);
+            await this.host.connection.command("Page.enable", {}, sessionId);
+            return sessionId;
+        })();
+        this.pageSessions.set(targetId, pending);
+        try {
+            return await pending;
+        }
+        catch (error) {
+            this.pageSessions.delete(targetId);
+            throw error;
+        }
+    }
+    onCdpEvent(event) {
+        if (this.closing || this.unavailableReason)
+            return;
+        if (event.method === "Target.targetCreated" || event.method === "Target.targetInfoChanged") {
+            const target = parseTargetInfo(event.params.targetInfo);
+            if (target.type !== "page")
+                return;
+            this.targets.set(target.targetId, target);
+            if (event.method === "Target.targetCreated")
+                this.activeTargetId = target.targetId;
+            this.eventQueue.changed(this.browserGeneration);
+            return;
+        }
+        if (event.method === "Target.targetDestroyed") {
+            const targetId = optionalCdpId(event.params.targetId);
+            if (!targetId)
+                return;
+            this.closingTargetIds.delete(targetId);
+            this.dropTarget(targetId);
+            if (this.activeTargetId === targetId) {
+                this.activeTargetId = [...this.targets.keys()].at(-1) ?? null;
+            }
+            this.eventQueue.changed(this.browserGeneration);
+            return;
+        }
+        if (event.method === "Target.targetCrashed") {
+            const targetId = optionalCdpId(event.params.targetId);
+            if (targetId && this.targets.has(targetId)) {
+                this.markUnavailable("A Headless Browser Page renderer crashed");
+            }
+            return;
+        }
+        if (event.method === "Target.detachedFromTarget") {
+            const sessionId = optionalCdpId(event.params.sessionId);
+            if (sessionId)
+                this.dropPageSession(sessionId);
+            return;
+        }
+        const targetId = event.sessionId ? this.targetBySession.get(event.sessionId) : undefined;
+        if (!targetId)
+            return;
+        if (event.method === "Inspector.detached") {
+            this.dropPageSession(event.sessionId);
+            return;
+        }
+        if (event.method === "Page.screencastFrame") {
+            this.surfaceSources.get(targetId)?.acceptScreencastFrame(event.params);
+            return;
+        }
+        if (event.method === "Page.frameResized") {
+            this.surfaceSources.get(targetId)?.refreshViewport();
+        }
+        if (event.method === "Page.frameStartedLoading")
+            this.loadingTargets.add(targetId);
+        if (event.method === "Page.frameStoppedLoading" || event.method === "Page.loadEventFired") {
+            this.loadingTargets.delete(targetId);
+        }
+        if (event.method.startsWith("Page."))
+            this.eventQueue.changed(this.browserGeneration);
+    }
+    requireTarget(targetId) {
+        const target = this.targets.get(targetId);
+        if (!target)
+            throw missingPage();
+        return target;
+    }
+    dropTarget(targetId) {
+        const surface = this.surfaceSources.get(targetId);
+        if (surface) {
+            // Stop routing renderer events immediately; close remains best-effort
+            // because the physical target may already have disappeared.
+            this.surfaceSources.delete(targetId);
+            void surface.close();
+        }
+        this.targets.delete(targetId);
+        this.loadingTargets.delete(targetId);
+        const session = this.pageSessions.get(targetId);
+        this.pageSessions.delete(targetId);
+        if (session)
+            void session.then((id) => this.targetBySession.delete(id), () => undefined);
+    }
+    dropPageSession(sessionId) {
+        const targetId = this.targetBySession.get(sessionId);
+        if (!targetId)
+            return;
+        this.targetBySession.delete(sessionId);
+        this.pageSessions.delete(targetId);
+        const surface = this.surfaceSources.get(targetId);
+        if (surface) {
+            this.surfaceSources.delete(targetId);
+            surface.closeAfterSourceLoss();
+        }
+        this.eventQueue.changed(this.browserGeneration);
+    }
+    ensureAvailable() {
+        if (this.unavailableReason || this.closing || !this.host.connection.connected) {
+            throw new SessionBrowserHostError("unavailable", "Headless Browser is unavailable");
+        }
+    }
+    markUnavailable(reason) {
+        if (this.closing || this.unavailableReason)
+            return;
+        this.unavailableReason = reason;
+        for (const source of this.surfaceSources.values())
+            source.closeAfterSourceLoss();
+        this.host.connection.close();
+        this.eventQueue.unavailable(this.browserGeneration, reason);
+    }
+    mapOperationError(error) {
+        if (error instanceof SessionBrowserHostError)
+            return error;
+        if (isMissingTargetError(error))
+            return missingPage(error);
+        if (!this.host.connection.connected || error instanceof CdpDisconnectedError) {
+            this.markUnavailable("The native CDP observer disconnected");
+            return unavailable("Headless Browser is unavailable", error);
+        }
+        return unavailable("Headless Browser rejected the CDP operation", error);
+    }
+    exclusive(operation) {
+        const result = this.operations.then(operation, operation);
+        this.operations = result.then(() => undefined, () => undefined);
+        return result;
+    }
+}
+class HeadlessBrowserSurfaceSource {
+    source;
+    frames;
+    frameQueue = new LatestSurfaceFrameQueue();
+    viewport = {
+        revision: 0,
+        width: 1,
+        height: 1,
+        deviceScaleFactor: 1,
+    };
+    started = false;
+    closed = false;
+    closePromise;
+    inputOperations = Promise.resolve();
+    pressedKeys = new Map();
+    pressedButtons = new Set();
+    lastPointer = { x: 0, y: 0 };
+    viewportRefresh;
+    lastAcceptedFrameAt = Number.NEGATIVE_INFINITY;
+    lastScreencastFrameAt = Number.NEGATIVE_INFINITY;
+    lastFrameSignature;
+    fallbackTimer;
+    fallbackCapture;
+    consecutiveDiscreteInputTimeouts = 0;
+    minimumFrameIntervalMs;
+    abortHandler;
+    constructor(source) {
+        this.source = source;
+        this.frames = {
+            [Symbol.asyncIterator]: () => {
+                const iterator = this.frameQueue[Symbol.asyncIterator]();
+                return {
+                    next: () => iterator.next(),
+                    return: async () => {
+                        await this.close();
+                        return { done: true, value: undefined };
+                    },
+                };
+            },
+        };
+        this.minimumFrameIntervalMs = 1_000 / source.input.maximumFrameRate;
+        if (source.input.signal) {
+            this.abortHandler = () => void this.close();
+            source.input.signal.addEventListener("abort", this.abortHandler, { once: true });
+        }
+    }
+    get browserGeneration() {
+        return this.source.input.browserGeneration;
+    }
+    get hostPageId() {
+        return this.source.input.hostPageId;
+    }
+    get format() {
+        return this.source.input.format;
+    }
+    async initialize() {
+        this.ensureCurrent();
+        this.viewport = await readSurfaceViewport(this.source.connection, this.source.pageSessionId, 0);
+        this.ensureCurrent();
+        const capture = await this.source.connection.command("Page.captureScreenshot", {
+            format: this.format,
+            ...(this.format === "jpeg" ? { quality: this.source.input.quality } : {}),
+            fromSurface: true,
+            captureBeyondViewport: false,
+        }, this.source.pageSessionId);
+        const capturedAt = Date.now();
+        this.pushFrameIfChanged(decodeSurfaceImage(capture.data, this.format), capturedAt, async () => undefined);
+        this.lastAcceptedFrameAt = capturedAt;
+        this.lastScreencastFrameAt = capturedAt;
+        this.ensureCurrent();
+        this.started = true;
+        await this.source.connection.command("Page.startScreencast", {
+            format: this.format,
+            quality: this.source.input.quality,
+            everyNthFrame: 1,
+        }, this.source.pageSessionId);
+        this.ensureCurrent();
+        this.scheduleFallbackCapture();
+    }
+    getViewport() {
+        return { ...this.viewport };
+    }
+    dispatchTrustedInput(input) {
+        const result = this.inputOperations.then(() => this.dispatchTrustedInputNow(input), () => this.dispatchTrustedInputNow(input));
+        this.inputOperations = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    resetTrustedInput() {
+        const result = this.inputOperations.then(() => this.resetTrustedInputNow(), () => this.resetTrustedInputNow());
+        this.inputOperations = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    acceptScreencastFrame(params) {
+        const screencastSessionId = surfaceFrameSessionId(params.sessionId);
+        const acknowledge = onceAsync(async () => {
+            await this.source.connection.command("Page.screencastFrameAck", { sessionId: screencastSessionId }, this.source.pageSessionId);
+        });
+        // Chrome may have queued a final frame before stopScreencast takes effect.
+        // It still owns a capture slot, so ACK it, but never let an expected close
+        // race invalidate the Browser's shared CDP connection.
+        if (this.closed) {
+            void acknowledge().catch(() => undefined);
+            return;
+        }
+        this.ensureCurrent();
+        const receivedAt = Date.now();
+        this.lastScreencastFrameAt = receivedAt;
+        if (receivedAt - this.lastAcceptedFrameAt < this.minimumFrameIntervalMs) {
+            void acknowledge().catch(() => undefined);
+            return;
+        }
+        try {
+            this.updateViewportFromScreencastMetadata(params.metadata);
+            const timestampMilliseconds = surfaceFrameTimestamp(params.metadata, receivedAt);
+            this.lastAcceptedFrameAt = receivedAt;
+            // CDP ACK means the bounded local capture slot accepted (or replaced)
+            // the frame. The downstream viewer ACK controls only this queue; it must
+            // never extend across network RTT back into Chrome capture.
+            this.pushFrameIfChanged(decodeSurfaceImage(params.data, this.format), timestampMilliseconds, async () => undefined);
+        }
+        finally {
+            void acknowledge().catch(() => undefined);
+        }
+    }
+    refreshViewport() {
+        if (this.closed || this.viewportRefresh)
+            return;
+        this.viewportRefresh = (async () => {
+            try {
+                this.ensureCurrent();
+                const next = await readSurfaceViewport(this.source.connection, this.source.pageSessionId, this.viewport.revision);
+                if (!sameSurfaceViewport(this.viewport, next)) {
+                    this.viewport = { ...next, revision: this.viewport.revision + 1 };
+                }
+            }
+            catch {
+                // The authoritative Page/Host lifecycle closes this source separately.
+            }
+            finally {
+                this.viewportRefresh = undefined;
+            }
+        })();
+    }
+    closeAfterSourceLoss() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.cancelFallbackCapture();
+        this.removeAbortHandler();
+        void this.frameQueue.close();
+        this.source.release();
+        this.closePromise = Promise.resolve();
+    }
+    close() {
+        if (this.closePromise)
+            return this.closePromise;
+        this.closed = true;
+        this.cancelFallbackCapture();
+        this.removeAbortHandler();
+        this.closePromise = (async () => {
+            try {
+                await this.frameQueue.close();
+                await this.inputOperations;
+                await this.resetTrustedInputNow().catch(() => undefined);
+                if (this.started && this.source.connection.connected) {
+                    await this.source.connection.command("Page.stopScreencast", {}, this.source.pageSessionId).catch(() => undefined);
+                }
+            }
+            finally {
+                this.source.release();
+            }
+        })();
+        return this.closePromise;
+    }
+    async dispatchTrustedInputNow(input) {
+        this.ensureCurrent();
+        if (input.browserGeneration !== this.browserGeneration) {
+            throw new SessionBrowserHostError("unavailable", "Browser Surface generation is stale");
+        }
+        if (input.viewportRevision !== this.viewport.revision) {
+            throw new SessionBrowserHostError("unavailable", "Browser Surface viewport is stale");
+        }
+        validateSurfaceInputCoordinates(input.event, this.viewport);
+        this.recordTrustedInputBeforeDispatch(input.event);
+        try {
+            const command = cdpTrustedInputCommand(input.event, pressedButtonMask(this.pressedButtons));
+            await this.source.connection.command(command.method, command.params, this.source.pageSessionId);
+            this.consecutiveDiscreteInputTimeouts = 0;
+            this.recordTrustedInputAfterDispatch(input.event);
+        }
+        catch (error) {
+            if (error instanceof CdpCommandTimeoutError) {
+                if (input.event.type === "pointer.move" || input.event.type === "wheel")
+                    return;
+                this.consecutiveDiscreteInputTimeouts += 1;
+                if (this.consecutiveDiscreteInputTimeouts < 3)
+                    return;
+                this.consecutiveDiscreteInputTimeouts = 0;
+                try {
+                    await this.source.connection.command("Browser.getVersion");
+                    return;
+                }
+                catch (probeError) {
+                    throw this.source.mapError(probeError);
+                }
+            }
+            throw this.source.mapError(error);
+        }
+    }
+    recordTrustedInputBeforeDispatch(event) {
+        if (event.type === "pointer.move" ||
+            event.type === "pointer.down" ||
+            event.type === "pointer.up" ||
+            event.type === "wheel") {
+            this.lastPointer = { x: event.x, y: event.y };
+        }
+        if (event.type === "pointer.down")
+            this.pressedButtons.add(event.button);
+        if (event.type === "key.down") {
+            this.pressedKeys.set(event.code, { key: event.key, code: event.code });
+        }
+    }
+    recordTrustedInputAfterDispatch(event) {
+        if (event.type === "pointer.up")
+            this.pressedButtons.delete(event.button);
+        if (event.type === "key.up")
+            this.pressedKeys.delete(event.code);
+    }
+    async resetTrustedInputNow() {
+        if (!this.source.connection.connected)
+            return;
+        let failure;
+        for (const [code, key] of [...this.pressedKeys]) {
+            try {
+                await this.source.connection.command("Input.dispatchKeyEvent", cdpKeyboardEventParams({
+                    type: "key.up",
+                    key: key.key,
+                    code: key.code,
+                    repeat: false,
+                    modifiers: [],
+                }, process.platform), this.source.pageSessionId);
+                if (this.pressedKeys.get(code) === key)
+                    this.pressedKeys.delete(code);
+            }
+            catch (error) {
+                failure ??= error;
+            }
+        }
+        for (const button of SURFACE_MOUSE_BUTTONS) {
+            if (!this.pressedButtons.has(button))
+                continue;
+            const buttonsAfterRelease = new Set(this.pressedButtons);
+            buttonsAfterRelease.delete(button);
+            try {
+                await this.source.connection.command("Input.dispatchMouseEvent", {
+                    type: "mouseReleased",
+                    x: Math.max(0, Math.min(this.viewport.width, this.lastPointer.x)),
+                    y: Math.max(0, Math.min(this.viewport.height, this.lastPointer.y)),
+                    button,
+                    buttons: pressedButtonMask(buttonsAfterRelease),
+                    clickCount: 1,
+                    modifiers: 0,
+                }, this.source.pageSessionId);
+                this.pressedButtons.delete(button);
+            }
+            catch (error) {
+                failure ??= error;
+            }
+        }
+        if (failure)
+            throw this.source.mapError(failure);
+    }
+    createFrame(encodedBytes, timestampMilliseconds, acknowledge) {
+        const viewport = this.viewport;
+        return {
+            browserGeneration: this.browserGeneration,
+            viewportRevision: viewport.revision,
+            timestampMilliseconds,
+            width: viewport.width,
+            height: viewport.height,
+            deviceScaleFactor: viewport.deviceScaleFactor,
+            format: this.format,
+            encodedBytes,
+            acknowledge: onceAsync(acknowledge),
+        };
+    }
+    pushFrameIfChanged(encodedBytes, timestampMilliseconds, acknowledge) {
+        const signature = surfaceFrameSignature(encodedBytes, this.viewport.revision);
+        if (signature === this.lastFrameSignature) {
+            void acknowledge().catch(() => undefined);
+            return false;
+        }
+        this.lastFrameSignature = signature;
+        this.frameQueue.push(this.createFrame(encodedBytes, timestampMilliseconds, acknowledge));
+        return true;
+    }
+    /**
+     * Chrome's headless screencast can legitimately emit an initial frame and
+     * then stay silent for small DOM-only paints. Polling bounded snapshots only
+     * after that stream is idle keeps the viewer live without replacing CDP
+     * screencast when it is producing frames.
+     */
+    scheduleFallbackCapture() {
+        if (this.closed || this.fallbackTimer || this.fallbackCapture)
+            return;
+        const intervalMs = Math.max(this.minimumFrameIntervalMs, MIN_SURFACE_FALLBACK_INTERVAL_MS);
+        this.fallbackTimer = setTimeout(() => {
+            this.fallbackTimer = undefined;
+            if (this.closed)
+                return;
+            this.fallbackCapture = this.captureFallbackFrame()
+                .catch(() => undefined)
+                .finally(() => {
+                this.fallbackCapture = undefined;
+                this.scheduleFallbackCapture();
+            });
+        }, intervalMs);
+        this.fallbackTimer.unref?.();
+    }
+    async captureFallbackFrame() {
+        const screencastIdleMs = Math.max(this.minimumFrameIntervalMs * 2, MIN_SURFACE_SCREENCAST_IDLE_MS);
+        if (Date.now() - this.lastScreencastFrameAt < screencastIdleMs)
+            return;
+        this.ensureCurrent();
+        const capture = await this.source.connection.command("Page.captureScreenshot", {
+            format: this.format,
+            ...(this.format === "jpeg" ? { quality: this.source.input.quality } : {}),
+            fromSurface: true,
+            captureBeyondViewport: false,
+        }, this.source.pageSessionId);
+        if (this.closed)
+            return;
+        this.ensureCurrent();
+        const capturedAt = Date.now();
+        this.lastAcceptedFrameAt = capturedAt;
+        this.pushFrameIfChanged(decodeSurfaceImage(capture.data, this.format), capturedAt, async () => undefined);
+    }
+    cancelFallbackCapture() {
+        if (!this.fallbackTimer)
+            return;
+        clearTimeout(this.fallbackTimer);
+        this.fallbackTimer = undefined;
+    }
+    updateViewportFromScreencastMetadata(value) {
+        if (!isRecord(value))
+            return;
+        const width = value.deviceWidth;
+        const height = value.deviceHeight;
+        if (!validSurfaceDimensions(width, height))
+            return;
+        const parsedHeight = height;
+        if (width === this.viewport.width && parsedHeight === this.viewport.height)
+            return;
+        this.viewport = {
+            ...this.viewport,
+            revision: this.viewport.revision + 1,
+            width,
+            height: parsedHeight,
+        };
+    }
+    ensureCurrent() {
+        if (this.closed) {
+            throw new SessionBrowserHostError("unavailable", "Browser Surface is closed");
+        }
+        this.source.ensureCurrent();
+    }
+    removeAbortHandler() {
+        if (this.abortHandler && this.source.input.signal) {
+            this.source.input.signal.removeEventListener("abort", this.abortHandler);
+        }
+    }
+}
+function surfaceFrameSignature(encodedBytes, viewportRevision) {
+    return createHash("sha256")
+        .update(String(viewportRevision))
+        .update("\0")
+        .update(encodedBytes)
+        .digest("base64url");
+}
+/** One current frame plus one replaceable latest frame, never an unbounded queue. */
+class LatestSurfaceFrameQueue {
+    current;
+    latest;
+    currentDelivered = false;
+    waiter;
+    closed = false;
+    push(frame) {
+        const entry = this.wrap(frame);
+        if (this.closed) {
+            void this.acknowledge(entry);
+            return;
+        }
+        if (!this.current) {
+            this.current = entry;
+            this.deliverCurrent();
+            return;
+        }
+        const replaced = this.latest;
+        this.latest = entry;
+        if (replaced)
+            void this.acknowledge(replaced);
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const frames = [this.current, this.latest].filter((entry) => entry !== undefined);
+        this.current = undefined;
+        this.latest = undefined;
+        this.waiter?.({ done: true, value: undefined });
+        this.waiter = undefined;
+        await Promise.allSettled(frames.map((entry) => this.acknowledge(entry)));
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => this.next(),
+            return: async () => {
+                await this.close();
+                return { done: true, value: undefined };
+            },
+        };
+    }
+    next() {
+        if (this.closed)
+            return Promise.resolve({ done: true, value: undefined });
+        if (this.current && !this.currentDelivered) {
+            this.currentDelivered = true;
+            return Promise.resolve({ done: false, value: this.current.frame });
+        }
+        if (this.waiter)
+            return Promise.reject(new Error("Browser Surface frame read is already pending"));
+        return new Promise((resolveFrame) => {
+            this.waiter = resolveFrame;
+        });
+    }
+    wrap(frame) {
+        let entry;
+        const upstreamAcknowledge = frame.acknowledge;
+        const exposed = {
+            ...frame,
+            acknowledge: () => this.acknowledge(entry),
+        };
+        entry = { frame: exposed, upstreamAcknowledge };
+        return entry;
+    }
+    acknowledge(entry) {
+        entry.acknowledgePromise ??= (async () => {
+            try {
+                await entry.upstreamAcknowledge();
+            }
+            finally {
+                this.release(entry);
+            }
+        })();
+        return entry.acknowledgePromise;
+    }
+    release(entry) {
+        if (this.current === entry) {
+            this.current = this.latest;
+            this.latest = undefined;
+            this.currentDelivered = false;
+            this.deliverCurrent();
+            return;
+        }
+        if (this.latest === entry)
+            this.latest = undefined;
+    }
+    deliverCurrent() {
+        if (!this.waiter || !this.current || this.currentDelivered)
+            return;
+        const resolveFrame = this.waiter;
+        this.waiter = undefined;
+        this.currentDelivered = true;
+        resolveFrame({ done: false, value: this.current.frame });
+    }
+}
+const SURFACE_MOUSE_BUTTONS = [
+    "left",
+    "middle",
+    "right",
+    "back",
+    "forward",
+];
+function cdpTrustedInputCommand(event, pressedButtons = 0) {
+    const modifiers = cdpModifierMask("modifiers" in event ? event.modifiers : []);
+    switch (event.type) {
+        case "pointer.move":
+            return {
+                method: "Input.dispatchMouseEvent",
+                params: { type: "mouseMoved", x: event.x, y: event.y, buttons: pressedButtons, modifiers },
+            };
+        case "pointer.down":
+        case "pointer.up":
+            pressedButtons = event.type === "pointer.down"
+                ? pressedButtons | surfaceMouseButtonMask(event.button)
+                : pressedButtons & ~surfaceMouseButtonMask(event.button);
+            return {
+                method: "Input.dispatchMouseEvent",
+                params: {
+                    type: event.type === "pointer.down" ? "mousePressed" : "mouseReleased",
+                    x: event.x,
+                    y: event.y,
+                    button: event.button,
+                    buttons: pressedButtons,
+                    clickCount: 1,
+                    modifiers,
+                },
+            };
+        case "wheel":
+            return {
+                method: "Input.dispatchMouseEvent",
+                params: {
+                    type: "mouseWheel",
+                    x: event.x,
+                    y: event.y,
+                    deltaX: event.deltaX,
+                    deltaY: event.deltaY,
+                    buttons: pressedButtons,
+                    modifiers,
+                },
+            };
+        case "key.down":
+        case "key.up":
+            return {
+                method: "Input.dispatchKeyEvent",
+                params: cdpKeyboardEventParams(event, process.platform),
+            };
+        case "text.insert":
+            return { method: "Input.insertText", params: { text: event.text } };
+    }
+}
+function pressedButtonMask(buttons) {
+    let mask = 0;
+    for (const button of buttons)
+        mask |= surfaceMouseButtonMask(button);
+    return mask;
+}
+function surfaceMouseButtonMask(button) {
+    if (button === "left")
+        return 1;
+    if (button === "right")
+        return 2;
+    if (button === "middle")
+        return 4;
+    if (button === "back")
+        return 8;
+    return 16;
+}
+function cdpModifierMask(modifiers) {
+    let mask = 0;
+    for (const modifier of modifiers) {
+        if (modifier === "alt")
+            mask |= 1;
+        if (modifier === "control")
+            mask |= 2;
+        if (modifier === "meta")
+            mask |= 4;
+        if (modifier === "shift")
+            mask |= 8;
+    }
+    return mask;
+}
+function validateSurfaceOpenInput(input) {
+    if (!Number.isSafeInteger(input.browserGeneration) ||
+        input.browserGeneration < 1 ||
+        (input.format !== "jpeg" && input.format !== "png") ||
+        !Number.isInteger(input.quality) ||
+        input.quality < MIN_SURFACE_QUALITY ||
+        input.quality > MAX_SURFACE_QUALITY ||
+        !Number.isInteger(input.maximumFrameRate) ||
+        input.maximumFrameRate < 1 ||
+        input.maximumFrameRate > RUNTIME_BROWSER_SURFACE_MAX_FRAME_RATE) {
+        throw new SessionBrowserHostError("unavailable", "Browser Surface options are invalid");
+    }
+}
+async function readSurfaceViewport(connection, pageSessionId, revision) {
+    const result = await connection.command("Runtime.evaluate", {
+        expression: "({width: Math.round(window.innerWidth), height: Math.round(window.innerHeight), deviceScaleFactor: window.devicePixelRatio})",
+        returnByValue: true,
+    }, pageSessionId);
+    if (!isRecord(result) || !isRecord(result.result) || !isRecord(result.result.value)) {
+        throw new Error("CDP omitted the Browser Surface viewport");
+    }
+    const value = result.result.value;
+    if (!validSurfaceDimensions(value.width, value.height)) {
+        throw new Error("CDP returned an invalid Browser Surface viewport");
+    }
+    const height = value.height;
+    if (typeof value.deviceScaleFactor !== "number" ||
+        !Number.isFinite(value.deviceScaleFactor) ||
+        value.deviceScaleFactor < 0.25 ||
+        value.deviceScaleFactor > 8) {
+        throw new Error("CDP returned an invalid Browser Surface device scale factor");
+    }
+    return {
+        revision,
+        width: value.width,
+        height,
+        deviceScaleFactor: value.deviceScaleFactor,
+    };
+}
+function validSurfaceDimensions(width, height) {
+    return Number.isInteger(width) && Number.isInteger(height) &&
+        width >= 1 && width <= RUNTIME_BROWSER_SURFACE_MAX_VIEWPORT_WIDTH &&
+        height >= 1 && height <= RUNTIME_BROWSER_SURFACE_MAX_VIEWPORT_HEIGHT &&
+        width * height <= RUNTIME_BROWSER_SURFACE_MAX_VIEWPORT_PIXELS;
+}
+function sameSurfaceViewport(left, right) {
+    return left.width === right.width && left.height === right.height &&
+        left.deviceScaleFactor === right.deviceScaleFactor;
+}
+function decodeSurfaceImage(value, format) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > RUNTIME_BROWSER_SURFACE_MAX_ENCODED_FRAME_BYTES * 2 ||
+        !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) {
+        throw new Error("CDP returned an invalid Browser Surface image");
+    }
+    const bytes = Buffer.from(value, "base64");
+    if (bytes.byteLength === 0 ||
+        bytes.byteLength > RUNTIME_BROWSER_SURFACE_MAX_ENCODED_FRAME_BYTES ||
+        Buffer.from(bytes).toString("base64").replace(/=+$/, "") !== value.replace(/=+$/, "")) {
+        throw new Error("CDP returned an invalid Browser Surface image");
+    }
+    const validMagic = format === "jpeg"
+        ? bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff
+        : bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));
+    if (!validMagic)
+        throw new Error(`CDP returned bytes that are not ${format}`);
+    return new Uint8Array(bytes);
+}
+function surfaceFrameSessionId(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error("CDP screencast frame omitted its session ID");
+    }
+    return value;
+}
+function surfaceFrameTimestamp(metadata, fallback) {
+    if (!isRecord(metadata))
+        return fallback;
+    const timestamp = metadata.timestamp;
+    if (typeof timestamp !== "number" || !Number.isFinite(timestamp) || timestamp < 0) {
+        return fallback;
+    }
+    const milliseconds = Math.round(timestamp * 1_000);
+    return Number.isSafeInteger(milliseconds) ? milliseconds : fallback;
+}
+function validateSurfaceInputCoordinates(event, viewport) {
+    if (!("x" in event))
+        return;
+    if (!Number.isFinite(event.x) ||
+        !Number.isFinite(event.y) ||
+        event.x < 0 ||
+        event.y < 0 ||
+        event.x > viewport.width ||
+        event.y > viewport.height) {
+        throw new SessionBrowserHostError("unavailable", "Browser Surface input is outside its viewport");
+    }
+}
+function onceAsync(operation) {
+    let result;
+    return () => result ??= operation();
+}
+class CdpProtocolError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "CdpProtocolError";
+    }
+}
+class CdpDisconnectedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CdpDisconnectedError";
+    }
+}
+class CdpCommandTimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CdpCommandTimeoutError";
+    }
+}
+class CdpConnection {
+    socket;
+    commandTimeoutMs;
+    nextId = 1;
+    pending = new Map();
+    eventHandler = () => undefined;
+    disconnectHandler = () => undefined;
+    didDisconnect = false;
+    constructor(socket, commandTimeoutMs) {
+        this.socket = socket;
+        this.commandTimeoutMs = commandTimeoutMs;
+        socket.on("message", (data, isBinary) => this.onMessage(data, isBinary));
+        socket.on("close", () => this.disconnect("Native CDP WebSocket closed"));
+        socket.on("error", (error) => this.disconnect(`Native CDP WebSocket error: ${error.message}`));
+    }
+    static async connect(endpoint, commandTimeoutMs) {
+        validateCdpEndpoint(endpoint);
+        const socket = new WebSocket(endpoint, {
+            maxPayload: MAX_CDP_MESSAGE_BYTES,
+            perMessageDeflate: false,
+        });
+        await new Promise((resolveOpen, rejectOpen) => {
+            const timer = setTimeout(() => {
+                cleanup();
+                socket.terminate();
+                rejectOpen(new Error("Native CDP WebSocket connection timed out"));
+            }, commandTimeoutMs);
+            const onOpen = () => {
+                cleanup();
+                resolveOpen();
+            };
+            const onError = (error) => {
+                cleanup();
+                rejectOpen(error);
+            };
+            const cleanup = () => {
+                clearTimeout(timer);
+                socket.off("open", onOpen);
+                socket.off("error", onError);
+            };
+            socket.once("open", onOpen);
+            socket.once("error", onError);
+        });
+        return new CdpConnection(socket, commandTimeoutMs);
+    }
+    get connected() {
+        return !this.didDisconnect && this.socket.readyState === WebSocket.OPEN;
+    }
+    setEventHandler(handler) {
+        this.eventHandler = handler;
+    }
+    setDisconnectHandler(handler) {
+        this.disconnectHandler = handler;
+    }
+    command(method, params = {}, sessionId) {
+        if (!this.connected)
+            return Promise.reject(new CdpDisconnectedError("Native CDP is disconnected"));
+        const id = this.nextId++;
+        return new Promise((resolveCommand, rejectCommand) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                rejectCommand(new CdpCommandTimeoutError(`Native CDP command ${method} timed out`));
+            }, this.commandTimeoutMs);
+            this.pending.set(id, { resolve: resolveCommand, reject: rejectCommand, timer });
+            try {
+                this.socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+            }
+            catch (error) {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                rejectCommand(error);
+            }
+        });
+    }
+    close() {
+        if (this.socket.readyState === WebSocket.OPEN || this.socket.readyState === WebSocket.CONNECTING) {
+            this.socket.close();
+        }
+        this.disconnect("Native CDP connection closed");
+    }
+    onMessage(data, isBinary) {
+        const bytes = rawDataBytes(data);
+        if (isBinary || bytes.byteLength > MAX_CDP_MESSAGE_BYTES) {
+            this.socket.terminate();
+            this.disconnect("Native CDP sent an invalid message");
+            return;
+        }
+        let value;
+        try {
+            value = JSON.parse(bytes.toString("utf8"));
+        }
+        catch {
+            this.socket.terminate();
+            this.disconnect("Native CDP sent invalid JSON");
+            return;
+        }
+        if (!isRecord(value))
+            return;
+        if (Number.isSafeInteger(value.id)) {
+            const pending = this.pending.get(value.id);
+            if (!pending)
+                return;
+            this.pending.delete(value.id);
+            clearTimeout(pending.timer);
+            if (isRecord(value.error)) {
+                pending.reject(new CdpProtocolError(typeof value.error.code === "number" ? value.error.code : -1, typeof value.error.message === "string" ? value.error.message : "Native CDP command failed"));
+            }
+            else {
+                pending.resolve(value.result ?? {});
+            }
+            return;
+        }
+        if (typeof value.method !== "string")
+            return;
+        try {
+            this.eventHandler({
+                method: value.method,
+                params: isRecord(value.params) ? value.params : {},
+                ...(typeof value.sessionId === "string" ? { sessionId: value.sessionId } : {}),
+            });
+        }
+        catch {
+            this.socket.terminate();
+            this.disconnect("Native CDP sent an invalid event");
+        }
+    }
+    disconnect(reason) {
+        if (this.didDisconnect)
+            return;
+        this.didDisconnect = true;
+        const error = new CdpDisconnectedError(reason);
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+        this.disconnectHandler(reason);
+    }
+}
+class BrowserHostEventQueue {
+    changedEvent;
+    terminalEvent;
+    ended = false;
+    waiter;
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    next() {
+        if (this.changedEvent) {
+            const value = this.changedEvent;
+            this.changedEvent = undefined;
+            return Promise.resolve({ value, done: false });
+        }
+        if (this.terminalEvent) {
+            const value = this.terminalEvent;
+            this.terminalEvent = undefined;
+            this.ended = true;
+            return Promise.resolve({ value, done: false });
+        }
+        if (this.ended)
+            return Promise.resolve({ value: undefined, done: true });
+        return new Promise((resolveNext) => {
+            this.waiter = resolveNext;
+        });
+    }
+    changed(browserGeneration) {
+        if (this.ended || this.terminalEvent)
+            return;
+        const event = { type: "changed", browserGeneration };
+        if (this.waiter) {
+            const waiter = this.waiter;
+            this.waiter = undefined;
+            waiter({ value: event, done: false });
+        }
+        else {
+            this.changedEvent = event;
+        }
+    }
+    unavailable(browserGeneration, reason) {
+        if (this.ended || this.terminalEvent)
+            return;
+        this.changedEvent = undefined;
+        const event = { type: "unavailable", browserGeneration, reason };
+        if (this.waiter) {
+            const waiter = this.waiter;
+            this.waiter = undefined;
+            this.ended = true;
+            waiter({ value: event, done: false });
+        }
+        else {
+            this.terminalEvent = event;
+        }
+    }
+    end() {
+        if (this.ended)
+            return;
+        this.changedEvent = undefined;
+        this.ended = true;
+        if (this.waiter) {
+            const waiter = this.waiter;
+            this.waiter = undefined;
+            waiter({ value: undefined, done: true });
+        }
+    }
+}
+function ensureOwnedProfile(profileRoot, sessionId) {
+    ensureDirectDirectory(profileRoot, profileRoot);
+    const profileDir = headlessBrowserProfilePath(profileRoot, sessionId);
+    if (!existsSync(profileDir)) {
+        mkdirSync(profileDir, { mode: 0o700 });
+        chmodSync(profileDir, 0o700);
+        writeFileSync(join(profileDir, PROFILE_OWNER_FILE), `${JSON.stringify(profileMarker(sessionId))}\n`, { flag: "wx", mode: 0o600 });
+    }
+    validateOwnedProfile(profileRoot, profileDir, sessionId);
+    return profileDir;
+}
+function ensureDirectDirectory(path, containmentRoot) {
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error(`Headless Browser storage path is not a direct directory: ${path}`);
+    }
+    chmodSync(path, 0o700);
+    if (!isWithin(realpathSync(containmentRoot), realpathSync(path))) {
+        throw new Error(`Headless Browser storage path escapes its root: ${path}`);
+    }
+}
+function validateOwnedProfile(profileRoot, profileDir, sessionId) {
+    const stat = lstatSync(profileDir);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error("Headless Browser profile is not an owned direct directory");
+    }
+    if (resolve(profileDir).startsWith(`${resolve(profileRoot)}${sep}`) === false ||
+        !isWithin(realpathSync(profileRoot), realpathSync(profileDir))) {
+        throw new Error("Headless Browser profile escapes its owned root");
+    }
+    const marker = readSmallRegularJson(join(profileDir, PROFILE_OWNER_FILE), MAX_PROFILE_METADATA_BYTES, "Headless Browser profile ownership marker");
+    const expected = profileMarker(sessionId);
+    if (!isRecord(marker) ||
+        marker.schemaVersion !== expected.schemaVersion ||
+        marker.kind !== expected.kind ||
+        marker.executionBackend !== expected.executionBackend ||
+        marker.sessionId !== expected.sessionId) {
+        throw new Error("Headless Browser profile ownership marker does not match the Session");
+    }
+}
+function removeOwnedProfile(profileRoot, sessionId) {
+    if (!existsSync(profileRoot))
+        return;
+    const rootStat = lstatSync(profileRoot);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+        throw new Error("Headless Browser profile root is not an owned direct directory");
+    }
+    const profileDir = headlessBrowserProfilePath(profileRoot, sessionId);
+    if (!existsSync(profileDir))
+        return;
+    validateOwnedProfile(profileRoot, profileDir, sessionId);
+    rmSync(profileDir, { recursive: true });
+}
+function profileMarker(sessionId) {
+    return {
+        schemaVersion: 1,
+        kind: "rynx-headless-browser-profile",
+        executionBackend: "headless-chromium",
+        sessionId,
+    };
+}
+async function recoverOwnedProfileProcesses(profileRoot, graceMs) {
+    if (!existsSync(profileRoot))
+        return;
+    const rootStat = lstatSync(profileRoot);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+        throw new Error("Headless Browser profile root is not an owned direct directory");
+    }
+    for (const entry of readdirSync(profileRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.isSymbolicLink() || !entry.name.startsWith("session-"))
+            continue;
+        const profileDir = join(profileRoot, entry.name);
+        let marker;
+        try {
+            marker = readSmallRegularJson(join(profileDir, PROFILE_OWNER_FILE), MAX_PROFILE_METADATA_BYTES, "Headless Browser profile ownership marker");
+        }
+        catch {
+            continue;
+        }
+        if (!isHeadlessBrowserProfileMarker(marker))
+            continue;
+        if (headlessBrowserProfilePath(profileRoot, marker.sessionId) !== profileDir)
+            continue;
+        await recoverProfileProcess(profileRoot, profileDir, marker.sessionId, graceMs);
+    }
+}
+async function recoverProfileProcess(profileRoot, profileDir, sessionId, graceMs) {
+    const leasePath = join(profileDir, PROCESS_LEASE_FILE);
+    if (!existsSync(leasePath)) {
+        removeStaleActivePort(profileDir);
+        return;
+    }
+    validateOwnedProfile(profileRoot, profileDir, sessionId);
+    let lease;
+    try {
+        lease = parseProcessLease(readSmallRegularJson(leasePath, MAX_PROFILE_METADATA_BYTES, "Headless Browser process lease"));
+    }
+    catch {
+        // A malformed or replaced lease cannot authorize a signal.
+        return;
+    }
+    if (lease.profileDir !== resolve(profileDir))
+        return;
+    if (!processExists(lease.pid)) {
+        removeMatchingProcessLease(profileDir, lease.ownerToken);
+        removeStaleActivePort(profileDir);
+        return;
+    }
+    if (!await processMatchesLease(lease))
+        return;
+    signalVerifiedProcessGroup(lease.processGroupId, "SIGTERM");
+    if (!await waitForPidExit(lease.pid, graceMs)) {
+        // Re-verify immediately before escalation so PID reuse cannot turn the
+        // persisted lease into authority over a different process.
+        if (!await processMatchesLease(lease))
+            return;
+        signalVerifiedProcessGroup(lease.processGroupId, "SIGKILL");
+        if (!await waitForPidExit(lease.pid, Math.max(graceMs, 250)))
+            return;
+    }
+    removeMatchingProcessLease(profileDir, lease.ownerToken);
+    removeStaleActivePort(profileDir);
+}
+function isHeadlessBrowserProfileMarker(value) {
+    return isRecord(value) &&
+        value.schemaVersion === 1 &&
+        value.kind === "rynx-headless-browser-profile" &&
+        value.executionBackend === "headless-chromium" &&
+        typeof value.sessionId === "string" &&
+        value.sessionId.length > 0;
+}
+function writeProcessLease(profileDir, executablePath, child, ownerToken) {
+    const pid = child.pid;
+    if (!pid || pid < 2)
+        throw new Error("Chrome for Testing did not publish a process ID");
+    const lease = {
+        schemaVersion: 1,
+        kind: "rynx-headless-browser-process",
+        pid,
+        processGroupId: pid,
+        ownerToken,
+        executablePath: resolve(executablePath),
+        profileDir: resolve(profileDir),
+        startedAt: new Date().toISOString(),
+    };
+    writeFileSync(join(profileDir, PROCESS_LEASE_FILE), `${JSON.stringify(lease)}\n`, { flag: "wx", mode: 0o600 });
+    return lease;
+}
+function parseProcessLease(value) {
+    if (!isRecord(value) ||
+        value.schemaVersion !== 1 ||
+        value.kind !== "rynx-headless-browser-process" ||
+        !Number.isSafeInteger(value.pid) ||
+        value.pid < 2 ||
+        value.processGroupId !== value.pid ||
+        typeof value.ownerToken !== "string" ||
+        !/^[a-f0-9]{64}$/.test(value.ownerToken) ||
+        typeof value.executablePath !== "string" ||
+        !isAbsolute(value.executablePath) ||
+        typeof value.profileDir !== "string" ||
+        !isAbsolute(value.profileDir) ||
+        typeof value.startedAt !== "string" ||
+        !Number.isFinite(Date.parse(value.startedAt))) {
+        throw new Error("Headless Browser process lease is invalid");
+    }
+    return value;
+}
+function assertProfileProcessLeaseClear(profileDir) {
+    if (existsSync(join(profileDir, PROCESS_LEASE_FILE))) {
+        throw new SessionBrowserHostError("capacity", "A process lease still owns this Headless Browser Session profile");
+    }
+}
+function removeMatchingProcessLease(profileDir, ownerToken) {
+    const leasePath = join(profileDir, PROCESS_LEASE_FILE);
+    if (!existsSync(leasePath))
+        return;
+    try {
+        const lease = parseProcessLease(readSmallRegularJson(leasePath, MAX_PROFILE_METADATA_BYTES, "Headless Browser process lease"));
+        if (lease.ownerToken === ownerToken)
+            rmSync(leasePath, { force: true });
+    }
+    catch {
+        // Never remove a lease that cannot be proven to be ours.
+    }
+}
+async function processMatchesLease(lease) {
+    let command;
+    try {
+        command = await readProcessCommand(lease.pid);
+    }
+    catch {
+        return false;
+    }
+    return command.includes(lease.executablePath) &&
+        command.includes(`--user-data-dir=${lease.profileDir}`) &&
+        command.includes(`--rynx-browser-owner=${lease.ownerToken}`);
+}
+async function readProcessCommand(pid) {
+    if (process.platform === "linux") {
+        const value = readFileSync(`/proc/${pid}/cmdline`);
+        if (value.byteLength === 0 || value.byteLength > MAX_PROCESS_COMMAND_BYTES) {
+            throw new Error("Process command line is not bounded");
+        }
+        return value.toString("utf8").replaceAll("\0", "\n");
+    }
+    if (process.platform === "darwin") {
+        return await new Promise((resolveCommand, rejectCommand) => {
+            execFile("/bin/ps", ["-ww", "-p", String(pid), "-o", "command="], { encoding: "utf8", maxBuffer: MAX_PROCESS_COMMAND_BYTES, timeout: 1_000 }, (error, stdout) => {
+                if (error)
+                    rejectCommand(error);
+                else if (!stdout.trim())
+                    rejectCommand(new Error("Process command line is empty"));
+                else
+                    resolveCommand(stdout);
+            });
+        });
+    }
+    throw new Error("Safe orphan process verification is unsupported on this platform");
+}
+function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !isNoSuchProcess(error);
+    }
+}
+async function waitForPidExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!processExists(pid))
+            return true;
+        await delay(Math.min(25, Math.max(1, deadline - Date.now())));
+    }
+    return !processExists(pid);
+}
+function signalVerifiedProcessGroup(processGroupId, signal) {
+    try {
+        process.kill(-processGroupId, signal);
+    }
+    catch (error) {
+        if (!isNoSuchProcess(error))
+            throw error;
+    }
+}
+function removeStaleActivePort(profileDir) {
+    rmSync(join(profileDir, DEVTOOLS_ACTIVE_PORT_FILE), { force: true });
+}
+function readSmallRegularJson(path, maxBytes, label) {
+    const descriptor = openNoFollow(path);
+    try {
+        const stat = fstatSync(descriptor);
+        if (!stat.isFile() || stat.size > maxBytes) {
+            throw new Error(`${label} is not a bounded regular file`);
+        }
+        const contents = readFileSync(descriptor, "utf8");
+        try {
+            return JSON.parse(contents);
+        }
+        catch {
+            throw new Error(`${label} is invalid JSON`);
+        }
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function chromeArguments(profileDir, ownerToken, url) {
+    return [
+        "--headless=new",
+        "--use-mock-keychain",
+        "--password-store=basic",
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--keep-alive-for-test",
+        `--rynx-browser-owner=${ownerToken}`,
+        `--user-data-dir=${profileDir}`,
+        "--remote-debugging-address=127.0.0.1",
+        "--remote-debugging-port=0",
+        "--disable-background-networking",
+        "--disable-component-update",
+        "--disable-sync",
+        "--metrics-recording-only",
+        "--no-report-upload",
+        "--window-size=1280,800",
+        url,
+    ];
+}
+function validateActiveExecutable(build) {
+    const install = lstatSync(build.installPath);
+    const executable = lstatSync(build.executablePath);
+    if (!install.isDirectory() || install.isSymbolicLink()) {
+        throw new SessionBrowserHostError("unavailable", "Active Chrome for Testing build is invalid");
+    }
+    if (!executable.isFile() || executable.isSymbolicLink()) {
+        throw new SessionBrowserHostError("unavailable", "Active Chrome for Testing executable is invalid");
+    }
+    if (!isWithin(realpathSync(build.installPath), realpathSync(build.executablePath))) {
+        throw new SessionBrowserHostError("unavailable", "Active Chrome for Testing executable escapes its build");
+    }
+    try {
+        accessSync(build.executablePath, fsConstants.X_OK);
+    }
+    catch (error) {
+        throw unavailable("Active Chrome for Testing executable is not executable", error);
+    }
+}
+async function waitForDevToolsActivePort(options) {
+    const path = join(options.profileDir, DEVTOOLS_ACTIVE_PORT_FILE);
+    const deadline = Date.now() + options.timeoutMs;
+    let lastError;
+    while (Date.now() < deadline) {
+        const exited = await Promise.race([
+            options.exit.then((value) => value),
+            delay(options.pollMs).then(() => undefined),
+        ]);
+        if (exited) {
+            throw new Error(`Chrome for Testing exited before native CDP was ready${options.diagnostics() ? `: ${options.diagnostics()}` : ""}`, { cause: exited });
+        }
+        try {
+            const contents = readSmallRegularFile(path, MAX_ACTIVE_PORT_BYTES, "DevToolsActivePort");
+            const lines = contents.trim().split(/\r?\n/);
+            if (lines.length !== 2)
+                throw new Error("DevToolsActivePort must contain exactly two lines");
+            const port = Number(lines[0]);
+            const webSocketPath = lines[1];
+            if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+                throw new Error("DevToolsActivePort contains an invalid loopback port");
+            }
+            if (!webSocketPath || !DEVTOOLS_BROWSER_PATH.test(webSocketPath)) {
+                throw new Error("DevToolsActivePort contains an invalid Browser WebSocket path");
+            }
+            const endpoint = `ws://127.0.0.1:${port}${webSocketPath}`;
+            validateCdpEndpoint(endpoint);
+            return endpoint;
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw new Error("Timed out waiting for a valid loopback DevToolsActivePort", { cause: lastError });
+}
+function validateCdpEndpoint(endpoint) {
+    const url = new URL(endpoint);
+    if (url.protocol !== "ws:" ||
+        url.hostname !== "127.0.0.1" ||
+        url.username ||
+        url.password ||
+        !DEVTOOLS_BROWSER_PATH.test(url.pathname) ||
+        url.search ||
+        url.hash) {
+        throw new Error("Native CDP endpoint is not an exact loopback Browser endpoint");
+    }
+}
+function observeProcess(child) {
+    let didSpawn = false;
+    const spawned = new Promise((resolveSpawn, rejectSpawn) => {
+        child.once("spawn", () => {
+            didSpawn = true;
+            resolveSpawn();
+        });
+        // A ChildProcess "error" only proves that spawn failed before "spawn".
+        // Later operational errors are not process exits and must not settle exit.
+        child.on("error", (error) => {
+            if (!didSpawn)
+                rejectSpawn(error);
+        });
+    });
+    const exit = new Promise((resolveExit) => {
+        child.once("exit", (code, signal) => resolveExit({ code, signal }));
+    });
+    return { spawned, exit };
+}
+function boundedStderr(child) {
+    let value = "";
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk) => {
+        value = `${value}${chunk}`.slice(-16_000);
+    });
+    return () => value.trim();
+}
+async function terminateProcessGroup(child, exit, graceMs) {
+    if (!child.pid)
+        return;
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    signalProcessGroup(child, "SIGTERM");
+    const exited = await Promise.race([
+        exit.then(() => true),
+        delay(graceMs).then(() => false),
+    ]);
+    if (exited || child.exitCode !== null || child.signalCode !== null)
+        return;
+    signalProcessGroup(child, "SIGKILL");
+    const killed = await Promise.race([
+        exit.then(() => true),
+        delay(Math.max(graceMs, 250)).then(() => false),
+    ]);
+    if (!killed && child.exitCode === null && child.signalCode === null) {
+        throw new Error("Chrome for Testing process group did not exit after SIGKILL");
+    }
+}
+function signalProcessGroup(child, signal) {
+    const pid = child.pid;
+    if (!pid || pid < 2)
+        return;
+    try {
+        process.kill(-pid, signal);
+    }
+    catch (error) {
+        if (isNoSuchProcess(error))
+            return;
+        try {
+            child.kill(signal);
+        }
+        catch (fallbackError) {
+            if (!isNoSuchProcess(fallbackError))
+                throw fallbackError;
+        }
+    }
+}
+function parseTargetInfo(value) {
+    if (!isRecord(value))
+        throw new Error("CDP targetInfo is invalid");
+    return {
+        targetId: requiredCdpId(value.targetId, "targetInfo targetId"),
+        type: typeof value.type === "string" ? value.type : "",
+        title: typeof value.title === "string" ? value.title : "",
+        url: typeof value.url === "string" ? value.url : "about:blank",
+    };
+}
+function parseNavigationHistory(value) {
+    if (!isRecord(value) || !Number.isSafeInteger(value.currentIndex) || !Array.isArray(value.entries)) {
+        throw new Error("CDP navigation history is invalid");
+    }
+    const entries = value.entries.map((entry) => {
+        if (!isRecord(entry) || !Number.isSafeInteger(entry.id) || typeof entry.url !== "string") {
+            throw new Error("CDP navigation history entry is invalid");
+        }
+        return { id: entry.id, url: entry.url };
+    });
+    const currentIndex = value.currentIndex;
+    if (currentIndex < -1 || currentIndex >= entries.length) {
+        throw new Error("CDP navigation history index is invalid");
+    }
+    return { currentIndex, entries };
+}
+function parseReadyState(value) {
+    if (!isRecord(value) || !isRecord(value.result) || typeof value.result.value !== "string") {
+        return "loading";
+    }
+    return value.result.value;
+}
+function displayUrl(value) {
+    if (value === "about:blank")
+        return value;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return "about:blank";
+        return url.href.length <= RUNTIME_BROWSER_MAX_URL_CHARS ? url.href : "about:blank";
+    }
+    catch {
+        return "about:blank";
+    }
+}
+function displayTitle(value) {
+    return value.replace(CONTROL_CHARACTER_GLOBAL_PATTERN, "").slice(0, RUNTIME_BROWSER_MAX_TITLE_CHARS);
+}
+function boundedEngineVersion(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 256 || CONTROL_CHARACTER_PATTERN.test(value)) {
+        throw new Error("CDP Browser version is invalid");
+    }
+    return value;
+}
+function requiredCdpId(value, label) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 2_048 || CONTROL_CHARACTER_PATTERN.test(value)) {
+        throw new Error(`CDP ${label} is invalid`);
+    }
+    return value;
+}
+function optionalCdpId(value) {
+    try {
+        return requiredCdpId(value, "identifier");
+    }
+    catch {
+        return undefined;
+    }
+}
+function isMissingTargetError(error) {
+    return error instanceof CdpProtocolError && /target|session/i.test(error.message) && /no|closed|found/i.test(error.message);
+}
+function isTransientPageTransitionError(error) {
+    return error instanceof CdpProtocolError && error.code === -32_000 && (/not attached to an active page/i.test(error.message) ||
+        /execution context (?:was )?destroyed/i.test(error.message) ||
+        /cannot find (?:an )?execution context/i.test(error.message) ||
+        /cannot find context with specified id/i.test(error.message));
+}
+function isMissingPageError(error) {
+    return (error instanceof SessionBrowserHostError && error.code === "page_not_found") || isMissingTargetError(error);
+}
+function missingPage(cause) {
+    return new SessionBrowserHostError("page_not_found", "Headless Browser Page was not found", {
+        cause,
+    });
+}
+function unavailable(message, cause) {
+    return new SessionBrowserHostError("unavailable", message, { cause });
+}
+function positiveDuration(value, fallback, label) {
+    const parsed = value ?? fallback;
+    if (!Number.isSafeInteger(parsed) || parsed <= 0)
+        throw new Error(`${label} must be positive`);
+    return parsed;
+}
+function delay(milliseconds) {
+    return new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds));
+}
+function isNoSuchProcess(error) {
+    return isRecord(error) && error.code === "ESRCH";
+}
+function rawDataBytes(data) {
+    if (Array.isArray(data))
+        return Buffer.concat(data);
+    if (data instanceof ArrayBuffer)
+        return Buffer.from(data);
+    return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+}
+function openNoFollow(path) {
+    return openSync(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+}
+function readSmallRegularFile(path, maxBytes, label) {
+    const descriptor = openNoFollow(path);
+    try {
+        const stat = fstatSync(descriptor);
+        if (!stat.isFile() || stat.size > maxBytes) {
+            throw new Error(`${label} is not a bounded regular file`);
+        }
+        return readFileSync(descriptor, "utf8");
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function isWithin(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}