prismcast 1.10.0 → 1.10.2

package/dist/routes/cdp.js

@@ -0,0 +1,702 @@
+import { LOG, formatError, getPackageVersion, isCategoryEnabled } from "../utils/index.js";
+import { WebSocket, WebSocketServer } from "ws";
+import { getBrowserInstance } from "../browser/index.js";
+/* Module-level state. The WebSocketServer is created in `noServer` mode so the HTTP server's upgrade event remains the single dispatch point; we route
+ * /cdp/devtools/* upgrades into the WSS and leave any other upgrade requests untouched so future features can claim them.
+ *
+ * Lifecycle ownership lives one layer down: each CdpProxySession subscribes to its own browser's `disconnected` event in start() and unsubscribes in cleanup().
+ * That replaces the older module-level "track the current browser, broadcast over a Set of active sessions" pattern - which encoded a per-instance concern
+ * (this WS attached to that browser) as shared state and had a latent race when listener registration outran rotation. Discovery endpoints likewise hold no
+ * disconnect subscription: the discoverySessions WeakMap is keyed by Browser identity, so rotation invalidates structurally and the old entry GCs with its
+ * browser.
+ */
+let wss = null;
+/**
+ * Builds the public-facing webSocketDebuggerUrl for a target. Chrome's wire convention puts the host:port of the debugging port at the front and a path
+ * identifying the target underneath /devtools. We mirror that shape so external clients recognize the URL as standard CDP.
+ * @param req - The current Express request, used to derive host + protocol so the URL reflects how the client actually reached us.
+ * @param suffix - The target-specific path under /devtools (e.g., "browser/<id>", "page/<id>").
+ * @returns The ws:// URL.
+ */
+function makeWsUrl(req, suffix) {
+    // Express exposes the Host header at req.headers.host. We fall back to the configured server.host:port only if the request omits it, which should not happen
+    // for HTTP/1.1 clients but is defensive.
+    const host = req.headers.host ?? (req.hostname + ":" + String(req.socket.localPort ?? ""));
+    // The proxy speaks ws (not wss) because PrismCast's HTTP listener is plain HTTP. If a reverse proxy fronts PrismCast with TLS, the operator is responsible for
+    // adjusting tooling that needs wss.
+    return "ws://" + host + "/cdp/devtools/" + suffix;
+}
+/* Per-browser CDPSession cache used by the GET /cdp/json endpoints to query Chrome for the live target list. Keyed by Browser identity so rotation auto-invalidates
+ * - the entry for the previous browser is unreferenced (along with the browser itself) and the next discovery call against the new browser is a structural cache
+ * miss. Each entry is stored as a pending Promise rather than a resolved value so concurrent callers per browser serialize on the same in-flight creation; storing
+ * the resolved value would let two simultaneous requests each create their own session (the slower one overwriting the faster one's reference and leaking the
+ * orphan).
+ */
+const discoverySessions = new WeakMap();
+/**
+ * Returns a working browser-level CDPSession for discovery, lazily creating one per Browser identity and re-creating it after a cached session detaches (e.g.,
+ * a transient CDP error). Concurrent callers against the same browser share the same in-flight Promise; callers against a different browser get their own.
+ * @param browser - The active Puppeteer Browser.
+ * @returns A CDPSession attached to the browser target.
+ */
+async function getDiscoverySession(browser) {
+    const existing = discoverySessions.get(browser);
+    if (existing) {
+        const cached = await existing;
+        if (!cached.detached) {
+            return cached;
+        }
+    }
+    const session = browser.target().createCDPSession();
+    discoverySessions.set(browser, session);
+    return session;
+}
+/**
+ * Sends a CDP command on a given session. Wrapper around CDPSession.send that erases the method generic so we can forward arbitrary methods received over the
+ * wire.
+ * @param session - The CDP session.
+ * @param method - The CDP method name.
+ * @param params - The CDP parameters.
+ * @returns The CDP result.
+ */
+async function sendCdp(session, method, params) {
+    return session.send(method, params);
+}
+/**
+ * Looks up the underlying Connection for a CDPSession. Returns null when the session is detached.
+ * @param session - The CDP session.
+ * @returns The Connection or null.
+ */
+function connectionFor(session) {
+    return session.connection() ?? null;
+}
+/* End of wire helpers. */
+/**
+ * Per-WebSocket CDP proxy state. One instance per attached client. Owns the browser-level CDPSession, the per-target sub-session map, and the lifecycle
+ * subscriptions to the Browser. Cleans up on WS close, target destruction, or browser disconnect. Exported for unit testing - production callers receive
+ * instances via the upgrade handler and do not construct them directly.
+ */
+export class CdpProxySession {
+    /* The active CDPSession attached to the browser target. Handles browser-level commands and serves as the routing channel for events the proxy emits when no
+     * sessionId is present.
+     */
+    browserSession = null;
+    /* The underlying Puppeteer Connection that owns every CDPSession we create. Captured for the Connection.createSession path which lets us mint a Puppeteer
+     * CDPSession from a CDP TargetInfo (the recommended public API for attaching to an arbitrary target by id).
+     */
+    connection = null;
+    /* Maps synthetic sessionId values (opaque to the client; we hand them out via Target.attachToTarget responses and Target.attachedToTarget events) to the
+     * underlying Puppeteer CDPSession for that target. Subsequent client messages with a sessionId route through this map.
+     */
+    sessions = new Map();
+    /* Reverse-map sessionId -> CDP targetId, so the targetdestroyed lifecycle hook can emit Target.detachedFromTarget with the right targetId for the synthetic
+     * sub-session.
+     */
+    sessionToTargetId = new Map();
+    /* Captured original emit functions so we can restore them on detach. Each entry is the EventEmitter prototype-bound original emit for the corresponding
+     * CDPSession.
+     */
+    originalEmits = new Map();
+    /* Counter for synthetic sessionIds. Incremented per attach. The string form looks like an opaque token; we prepend a deterministic prefix so cross-referencing
+     * proxy logs against external client logs is easy when debugging.
+     */
+    nextSessionSerial = 1;
+    /* Whether the client has called Target.setDiscoverTargets({ discover: true }). When true, we emit Target.targetCreated / Target.targetDestroyed events as
+     * browser targets come and go.
+     */
+    discoverTargets = false;
+    /* Whether the client has called Target.setAutoAttach({ autoAttach: true, flatten: true }). When true, every existing and future target is auto-attached, and
+     * Target.attachedToTarget events are emitted with the synthetic sessionId.
+     */
+    autoAttach = false;
+    /* Whether start() completed successfully and the "CDP client attached." log fired. cleanup() consults this so the paired "detached" log only emits when an
+     * "attached" log preceded it - keeping the audit trail honest when setup fails before the proxy is ever usable.
+     */
+    attached = false;
+    /* The bound listener attached to `this.browser`'s "disconnected" event in start(). Held as a field so cleanup() can unsubscribe by reference - using a fresh
+     * arrow function at unsubscribe time would silently fail to remove the original listener because EventEmitter compares listener identity. Cleared back to null
+     * on unsubscribe so the field's presence is a faithful indicator of "are we still listening."
+     */
+    onBrowserDisconnect = null;
+    ws;
+    browser;
+    constructor(ws, browser) {
+        this.ws = ws;
+        this.browser = browser;
+    }
+    /**
+     * Initializes the per-connection CDP plumbing: registers the WebSocket lifecycle handlers, subscribes to the browser's disconnect event, opens a browser-level
+     * CDPSession, captures the underlying Connection, and subscribes to CDP target events. Any failure during async setup is caught by the WS close handler
+     * (registered first), which fires when `closeWith()` closes the socket and routes cleanup through the same path the happy-path teardown takes. This invariant
+     * - lifecycle handlers wired before any async operation that can fail - is what guarantees the session is torn down (including its disconnect listener)
+     * regardless of where setup aborts. Handler bodies are null-safe so an early message arriving before browserSession is set produces a clean error frame rather
+     * than a crash.
+     */
+    async start() {
+        /* Wire the WebSocket lifecycle handlers BEFORE any async setup. closeWith() (used by the failure paths below) closes the socket, which fires the close event,
+         * which runs cleanup() - the handler-first ordering is the invariant that guarantees cleanup runs from any failure path, including the browser-disconnect
+         * subscription registered immediately after this.
+         */
+        this.ws.on("message", (data) => { void this.handleClientMessage(data); });
+        this.ws.on("close", () => { void this.cleanup(); });
+        this.ws.on("error", (err) => {
+            LOG.warn("CDP proxy WebSocket error: %s.", err.message);
+            void this.cleanup();
+        });
+        /* Subscribe to the browser's "disconnected" event so this session tears down cleanly when the browser PrismCast launched goes away (crash, rotation, normal
+         * shutdown). The handler closes our WS with 1001 ("going away"); the WS close handler above then runs cleanup(), which unsubscribes us. Doing this per-session
+         * - rather than a module-level broadcast over a Set - means the lifecycle concern lives on the resource it actually depends on, and a stale subscription from
+         * a previous browser can never fire against a session attached to a new one.
+         */
+        this.onBrowserDisconnect = () => { this.closeWith(1001, "browser disconnected"); };
+        this.browser.on("disconnected", this.onBrowserDisconnect);
+        try {
+            this.browserSession = await this.browser.target().createCDPSession();
+        }
+        catch (error) {
+            LOG.warn("CDP proxy could not open a browser session: %s.", formatError(error));
+            this.closeWith(1011, "browser session creation failed");
+            return;
+        }
+        const connection = connectionFor(this.browserSession);
+        if (!connection) {
+            this.closeWith(1011, "no CDP connection");
+            return;
+        }
+        this.connection = connection;
+        /* Subscribe to CDP Target.* lifecycle events on the browser session so we can drive internal session cleanup and auto-attach. This is CDP-native: the
+         * targetId on these events matches what Chrome reports through Target.getTargets and is the same id clients send back via Target.attachToTarget. Using
+         * Puppeteer's higher-level browser.on("targetcreated") instead would force us to map Puppeteer's opaque Target objects to CDP targetIds, which Puppeteer
+         * doesn't expose. The listeners are registered before we enable discovery so no event slips past during the round-trip.
+         */
+        this.browserSession.on("Target.targetCreated", (event) => { void this.handleCdpTargetCreated(event); });
+        this.browserSession.on("Target.targetDestroyed", (event) => { void this.handleCdpTargetDestroyed(event); });
+        // Capture every event the browser session emits and forward it to the client with no sessionId (it's a browser-level event).
+        this.attachEventListener(this.browserSession, null);
+        /* Enable target discovery on our browser session so Target.targetCreated / targetDestroyed events fire. This is required for our internal session cleanup
+         * regardless of whether the client has called Target.setDiscoverTargets - the wildcard forwarder gates client-facing emission of Target.* events on
+         * `this.discoverTargets`, so the internal subscription doesn't leak events to clients that didn't ask for them.
+         */
+        try {
+            await sendCdp(this.browserSession, "Target.setDiscoverTargets", { discover: true });
+        }
+        catch (error) {
+            LOG.warn("CDP proxy could not enable target discovery: %s.", formatError(error));
+        }
+        this.attached = true;
+        LOG.info("CDP client attached.");
+    }
+    /**
+     * Closes the WS with a code/reason and triggers cleanup. Safe to call when the WS is already closed.
+     * @param code - WebSocket close code (1000 normal, 1001 going-away, 1011 internal-error).
+     * @param reason - Human-readable reason.
+     */
+    closeWith(code, reason) {
+        if (this.ws.readyState === WebSocket.OPEN) {
+            try {
+                this.ws.close(code, reason);
+            }
+            catch {
+                // The ws library may throw if the socket is in an intermediate state. The 'close' event still fires from the underlying socket and runs cleanup() via the
+                // handler registered synchronously at the top of start() - that handler-first ordering is the invariant that guarantees cleanup runs from any failure path.
+            }
+        }
+    }
+    /**
+     * Handles a CDP message received over the WebSocket. Parses the JSON, dispatches to the browser-level or target-level handler, and forwards the response.
+     * Malformed JSON is silently dropped (the wire protocol has no error frame for that case at the client's level).
+     * @param data - The raw WebSocket message data.
+     */
+    async handleClientMessage(data) {
+        let raw;
+        if (typeof data === "string") {
+            raw = data;
+        }
+        else if (Buffer.isBuffer(data)) {
+            raw = data.toString("utf8");
+        }
+        else if (Array.isArray(data)) {
+            raw = Buffer.concat(data).toString("utf8");
+        }
+        else {
+            return;
+        }
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if ((typeof msg.id !== "number") || (typeof msg.method !== "string")) {
+            return;
+        }
+        if (msg.sessionId !== undefined) {
+            await this.handleTargetMessage(msg);
+        }
+        else {
+            await this.handleBrowserMessage(msg);
+        }
+    }
+    /**
+     * Dispatches a browser-level CDP command. Intercepts the Target domain to synthesize its semantics on top of Puppeteer's Browser API; passes everything else
+     * through to the browser session.
+     * @param msg - The parsed CDP request.
+     */
+    async handleBrowserMessage(msg) {
+        switch (msg.method) {
+            case "Target.setDiscoverTargets": {
+                await this.handleSetDiscoverTargets(msg);
+                return;
+            }
+            case "Target.setAutoAttach": {
+                await this.handleSetAutoAttach(msg);
+                return;
+            }
+            case "Target.attachToTarget": {
+                await this.handleAttachToTarget(msg);
+                return;
+            }
+            case "Target.detachFromTarget": {
+                await this.handleDetachFromTarget(msg);
+                return;
+            }
+            case "Target.getTargets":
+            case "Target.getTargetInfo": {
+                // These are pure reads. We pass them through to the browser session which returns Chrome's authoritative answer.
+                await this.passthrough(msg, this.browserSession);
+                return;
+            }
+            default: {
+                await this.passthrough(msg, this.browserSession);
+                return;
+            }
+        }
+    }
+    /**
+     * Dispatches a message addressed to a specific sub-session. Looks up the CDPSession by synthetic sessionId and forwards. Unknown sessionId yields a CDP error
+     * response so the client sees a clean failure rather than silently dropping.
+     * @param msg - The parsed CDP request with a sessionId.
+     */
+    async handleTargetMessage(msg) {
+        const sessionId = msg.sessionId;
+        if (sessionId === undefined) {
+            return;
+        }
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            this.sendResponse({ error: { code: -32602, message: "session not attached: " + sessionId }, id: msg.id, sessionId });
+            return;
+        }
+        await this.passthrough(msg, session);
+    }
+    /**
+     * Forwards a CDP command to a session and sends the response (or error) back to the client. The sessionId on the response is the one the client provided so
+     * the client can correlate.
+     * @param msg - The parsed CDP request.
+     * @param session - The CDP session to forward to.
+     */
+    async passthrough(msg, session) {
+        if (!session) {
+            this.sendResponse({ error: { code: -32603, message: "no session" }, id: msg.id, sessionId: msg.sessionId });
+            return;
+        }
+        try {
+            const result = await sendCdp(session, msg.method, msg.params);
+            this.sendResponse({ id: msg.id, result, sessionId: msg.sessionId });
+        }
+        catch (error) {
+            this.sendResponse({ error: { code: -32603, message: formatError(error) }, id: msg.id, sessionId: msg.sessionId });
+        }
+    }
+    /**
+     * Handles Target.setDiscoverTargets. When enabled, emits Target.targetCreated for every existing target so the client's view of the world matches Chrome's;
+     * targetcreated / targetdestroyed events thereafter flow via the Browser event subscriptions.
+     * @param msg - The parsed CDP request.
+     */
+    async handleSetDiscoverTargets(msg) {
+        const params = (msg.params ?? {});
+        this.discoverTargets = params.discover === true;
+        this.sendResponse({ id: msg.id, result: {} });
+        if (!this.discoverTargets || !this.browserSession) {
+            return;
+        }
+        // Emit Target.targetCreated for every existing target so the client has the full picture as of attach time.
+        try {
+            const info = await sendCdp(this.browserSession, "Target.getTargets", {});
+            for (const targetInfo of info.targetInfos) {
+                this.sendEvent({ method: "Target.targetCreated", params: { targetInfo } });
+            }
+        }
+        catch (error) {
+            LOG.warn("CDP proxy could not enumerate targets for discovery: %s.", formatError(error));
+        }
+    }
+    /**
+     * Handles Target.setAutoAttach. When enabled, creates a per-target CDPSession for every existing target, generates a synthetic sessionId, and emits
+     * Target.attachedToTarget for each. Subsequent new targets attach via the targetcreated lifecycle hook.
+     * @param msg - The parsed CDP request.
+     */
+    async handleSetAutoAttach(msg) {
+        const params = (msg.params ?? {});
+        // We only support flatten:true semantics - the modern mode every contemporary client uses. flatten:false is the legacy hierarchical mode where each session
+        // has its own WebSocket; we have no way to express that.
+        this.autoAttach = (params.autoAttach === true) && (params.flatten !== false);
+        this.sendResponse({ id: msg.id, result: {} });
+        if (!this.autoAttach || !this.browserSession) {
+            return;
+        }
+        try {
+            const info = await sendCdp(this.browserSession, "Target.getTargets", {});
+            // Sequential attach (not Promise.all) so synthetic sessionIds are assigned and emitted in target order. Parallelism would interleave the
+            // Target.attachedToTarget events and complicate any client that asserts on the attachment sequence.
+            for (const targetInfo of info.targetInfos) {
+                // eslint-disable-next-line no-await-in-loop
+                await this.attachToTargetInfo(targetInfo);
+            }
+        }
+        catch (error) {
+            LOG.warn("CDP proxy could not enumerate targets for auto-attach: %s.", formatError(error));
+        }
+    }
+    /**
+     * Handles Target.attachToTarget. Looks up the target's info via the browser session, creates a Puppeteer CDPSession via Connection.createSession (the public
+     * API for attaching to a target by id), generates a synthetic sessionId, and returns it. The client uses that sessionId for subsequent messages.
+     * @param msg - The parsed CDP request.
+     */
+    async handleAttachToTarget(msg) {
+        const params = (msg.params ?? {});
+        if (typeof params.targetId !== "string") {
+            this.sendResponse({ error: { code: -32602, message: "targetId required" }, id: msg.id });
+            return;
+        }
+        if (!this.browserSession || !this.connection) {
+            this.sendResponse({ error: { code: -32603, message: "browser session not ready" }, id: msg.id });
+            return;
+        }
+        try {
+            const info = await sendCdp(this.browserSession, "Target.getTargetInfo", { targetId: params.targetId });
+            const sessionId = await this.attachToTargetInfo(info.targetInfo, { emitEvent: false });
+            this.sendResponse({ id: msg.id, result: { sessionId } });
+        }
+        catch (error) {
+            this.sendResponse({ error: { code: -32603, message: formatError(error) }, id: msg.id });
+        }
+    }
+    /**
+     * Attaches to a target given its TargetInfo: creates a Puppeteer CDPSession via Connection.createSession, generates a synthetic sessionId, wires event
+     * forwarding, and optionally emits Target.attachedToTarget for the client. Returns the sessionId so callers (manual attach via Target.attachToTarget) can
+     * include it in their response.
+     * @param targetInfo - The CDP TargetInfo identifying the target.
+     * @param options - emitEvent: whether to emit Target.attachedToTarget after attach (defaults to true; manual attach sets false and returns the sessionId via
+     *                  the original response).
+     * @returns The synthetic sessionId for the newly-attached session.
+     */
+    async attachToTargetInfo(targetInfo, options = {}) {
+        if (!this.connection) {
+            throw new Error("connection unavailable");
+        }
+        const session = await this.connection.createSession(targetInfo);
+        const sessionId = "cdp-proxy-" + String(this.nextSessionSerial++);
+        this.sessions.set(sessionId, session);
+        this.sessionToTargetId.set(sessionId, targetInfo.targetId);
+        this.attachEventListener(session, sessionId);
+        if (options.emitEvent !== false) {
+            this.sendEvent({
+                method: "Target.attachedToTarget",
+                params: { sessionId, targetInfo, waitingForDebugger: false }
+            });
+        }
+        return sessionId;
+    }
+    /**
+     * Handles Target.detachFromTarget. Looks up the session by sessionId, detaches it, emits Target.detachedFromTarget, and removes from the map.
+     * @param msg - The parsed CDP request.
+     */
+    async handleDetachFromTarget(msg) {
+        const params = (msg.params ?? {});
+        if (typeof params.sessionId !== "string") {
+            this.sendResponse({ error: { code: -32602, message: "sessionId required" }, id: msg.id });
+            return;
+        }
+        await this.detachSessionById(params.sessionId);
+        this.sendResponse({ id: msg.id, result: {} });
+    }
+    /**
+     * Detaches a sub-session by its synthetic sessionId, restoring the patched emit, calling CDPSession.detach() (best-effort - the session may already be gone if
+     * the target closed), and emitting Target.detachedFromTarget so the client's view is consistent.
+     * @param sessionId - The synthetic sessionId.
+     */
+    async detachSessionById(sessionId) {
+        const session = this.sessions.get(sessionId);
+        const targetId = this.sessionToTargetId.get(sessionId);
+        if (session) {
+            this.detachEventListener(session);
+            try {
+                await session.detach();
+            }
+            catch {
+                // Detach is best-effort. A session whose target already closed will throw; the resulting state (session gone) is what we want anyway.
+            }
+        }
+        this.sessions.delete(sessionId);
+        this.sessionToTargetId.delete(sessionId);
+        if (targetId) {
+            this.sendEvent({ method: "Target.detachedFromTarget", params: { sessionId, targetId } });
+        }
+    }
+    /**
+     * Handles the CDP `Target.targetCreated` event emitted by the browser session. When autoAttach is on, mints a Puppeteer CDPSession for the new target and emits
+     * a synthetic Target.attachedToTarget to the client. Whether the client also sees the Target.targetCreated event is decided by the wildcard forwarder (which
+     * gates Target.* events on this.discoverTargets).
+     * @param event - The CDP event payload.
+     */
+    async handleCdpTargetCreated(event) {
+        if (!this.autoAttach) {
+            return;
+        }
+        try {
+            await this.attachToTargetInfo(event.targetInfo);
+        }
+        catch (error) {
+            LOG.warn("CDP proxy auto-attach failed: %s.", formatError(error));
+        }
+    }
+    /**
+     * Handles the CDP `Target.targetDestroyed` event emitted by the browser session. Detaches every sub-session attached to this targetId and emits the
+     * corresponding Target.detachedFromTarget events. The targetId on the CDP event matches exactly what we stored in sessionToTargetId at attach time, so there is
+     * no fuzzy matching - this is the lookup the Puppeteer-level targetdestroyed event could not give us.
+     * @param event - The CDP event payload.
+     */
+    async handleCdpTargetDestroyed(event) {
+        const matching = [];
+        for (const [sessionId, targetId] of this.sessionToTargetId) {
+            if (targetId === event.targetId) {
+                matching.push(sessionId);
+            }
+        }
+        // Sequential detach so the synthesized Target.detachedFromTarget events emit in deterministic order to the client.
+        for (const sessionId of matching) {
+            // eslint-disable-next-line no-await-in-loop
+            await this.detachSessionById(sessionId);
+        }
+    }
+    /**
+     * Attaches a wildcard event listener to a CDPSession. Each CDP-domain event (matched by the "Domain.event" naming pattern - uppercase first letter, dot,
+     * lowercase next letter) is forwarded to the WS client after the session's own listeners have run, so any internal state mutation (e.g. cleanup driven by
+     * Target.targetDestroyed) is settled before the client sees the event. Target.* events are gated on this.discoverTargets so a client that has not subscribed
+     * to the Target domain does not receive its events even though our internal subscription stays on.
+     *
+     * Implementation note. CDPSession exposes no public "subscribe to every event" hook, so we monkey-patch the EventEmitter.emit method. The patch saves the
+     * original so detachEventListener can restore it cleanly. Order of operations inside the patch is: dispatch through original first (specific listeners fire,
+     * including the internal Target.* handlers we registered), then forward to the client. This ordering avoids the race where the client receives an event tied
+     * to state we haven't yet cleaned up.
+     *
+     * @param session - The CDP session to monitor.
+     * @param sessionId - The synthetic sessionId to include in the forwarded events (null for browser-level events).
+     */
+    attachEventListener(session, sessionId) {
+        const original = session.emit.bind(session);
+        this.originalEmits.set(session, original);
+        // We alias `this` to a closure-captured reference because the patched function below is invoked as a method on the CDPSession (so its own `this` would point
+        // at the session, not this CdpProxySession). Arrow functions cannot be used here either, because the underlying EventEmitter contract expects a function whose
+        // `this` binding can be anything - matching the original emit shape we're replacing.
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const proxy = this;
+        const patched = function (event, ...args) {
+            // Dispatch to user-registered listeners first so internal handlers run before the client sees the event.
+            const result = original(event, ...args);
+            if ((typeof event === "string") && (/^[A-Z][a-zA-Z0-9]+\.[a-z]/).test(event)) {
+                // Target.* events are gated: clients only see them when they have opted in via Target.setDiscoverTargets / setAutoAttach. Our internal subscription stays
+                // on regardless so we can drive session cleanup.
+                const isTargetEvent = event.startsWith("Target.");
+                const shouldForward = !isTargetEvent || proxy.discoverTargets;
+                if (shouldForward) {
+                    proxy.sendEvent({ method: event, params: args[0], ...(sessionId === null ? {} : { sessionId }) });
+                }
+            }
+            return result;
+        };
+        session.emit = patched;
+    }
+    /**
+     * Restores the original emit on a session, undoing attachEventListener. Called on detach / cleanup.
+     * @param session - The CDP session whose emit to restore.
+     */
+    detachEventListener(session) {
+        const original = this.originalEmits.get(session);
+        if (original) {
+            session.emit = original;
+            this.originalEmits.delete(session);
+        }
+    }
+    /**
+     * Sends a CDP wire response back to the client.
+     * @param response - The response object.
+     */
+    sendResponse(response) {
+        this.sendRaw(response);
+    }
+    /**
+     * Sends a CDP wire event back to the client.
+     * @param event - The event object.
+     */
+    sendEvent(event) {
+        this.sendRaw(event);
+    }
+    /**
+     * Serializes a frame and writes it to the WS, swallowing errors that arise from a closed socket. We do not retry; if the WS is closed, the proxy session is
+     * already on its way to cleanup.
+     * @param frame - The frame to send.
+     */
+    sendRaw(frame) {
+        if (this.ws.readyState !== WebSocket.OPEN) {
+            return;
+        }
+        try {
+            this.ws.send(JSON.stringify(frame));
+        }
+        catch (error) {
+            LOG.warn("CDP proxy WebSocket write failed: %s.", formatError(error));
+        }
+    }
+    /**
+     * Detaches every sub-session, restores patched emits, and unsubscribes from the browser-disconnect event. Safe to call multiple times: detach of an
+     * already-detached CDPSession is a no-op, and the disconnect-listener field is cleared after the first removal so a repeat call is a no-op too. Triggered by
+     * WS close, WS error, or closeWith().
+     */
+    async cleanup() {
+        // Unsubscribe from browser disconnect first so a disconnect arriving mid-cleanup cannot drive a second closeWith() against an already-closing WS. The
+        // sequencing is conservative - the close handler is idempotent - but unsubscribing here keeps the lifecycle ledger clean.
+        if (this.onBrowserDisconnect) {
+            this.browser.off("disconnected", this.onBrowserDisconnect);
+            this.onBrowserDisconnect = null;
+        }
+        // Sequential detach to keep the final wave of Target.detachedFromTarget events ordered.
+        for (const sessionId of Array.from(this.sessions.keys())) {
+            // eslint-disable-next-line no-await-in-loop
+            await this.detachSessionById(sessionId);
+        }
+        if (this.browserSession) {
+            this.detachEventListener(this.browserSession);
+            try {
+                await this.browserSession.detach();
+            }
+            catch {
+                // Best-effort.
+            }
+            this.browserSession = null;
+        }
+        if (this.attached) {
+            this.attached = false;
+            LOG.info("CDP client detached.");
+        }
+    }
+}
+/* End of CdpProxySession. */
+/**
+ * Configures the /cdp/json/version, /cdp/json, and /cdp/json/list discovery endpoints on the Express app. Each handler checks isCategoryEnabled("cdp") at request
+ * time and returns 404 when CDP is disabled, so the surface appears and disappears in sync with the toggle in /debug without requiring a restart.
+ * @param app - The Express application.
+ */
+export function setupCdpEndpoint(app) {
+    app.get("/cdp/json/version", async (req, res) => {
+        if (!isCategoryEnabled("cdp")) {
+            res.status(404).send("Not Found");
+            return;
+        }
+        const browser = getBrowserInstance();
+        if (!browser) {
+            res.status(503).send("Browser not running");
+            return;
+        }
+        try {
+            const session = await getDiscoverySession(browser);
+            const version = await sendCdp(session, "Browser.getVersion", {});
+            res.json({
+                "Browser": version.product,
+                "Protocol-Version": version.protocolVersion,
+                "User-Agent": version.userAgent,
+                "V8-Version": version.jsVersion,
+                "WebKit-Version": version.product,
+                "prismcastVersion": getPackageVersion(),
+                "webSocketDebuggerUrl": makeWsUrl(req, "browser/prismcast")
+            });
+        }
+        catch (error) {
+            LOG.warn("CDP /cdp/json/version error: %s.", formatError(error));
+            res.status(500).send("Internal error");
+        }
+    });
+    // /cdp/json and /cdp/json/list are aliases - both return the target list.
+    const listHandler = async (req, res) => {
+        if (!isCategoryEnabled("cdp")) {
+            res.status(404).send("Not Found");
+            return;
+        }
+        const browser = getBrowserInstance();
+        if (!browser) {
+            res.status(503).send("Browser not running");
+            return;
+        }
+        try {
+            const session = await getDiscoverySession(browser);
+            const targets = await sendCdp(session, "Target.getTargets", {});
+            const list = targets.targetInfos.map((info) => ({
+                description: "",
+                devtoolsFrontendUrl: "/devtools/inspector.html?ws=" + makeWsUrl(req, "page/" + info.targetId).replace(/^ws:\/\//, ""),
+                id: info.targetId,
+                title: info.title,
+                type: info.type,
+                url: info.url,
+                webSocketDebuggerUrl: makeWsUrl(req, "page/" + info.targetId)
+            }));
+            res.json(list);
+        }
+        catch (error) {
+            LOG.warn("CDP /cdp/json error: %s.", formatError(error));
+            res.status(500).send("Internal error");
+        }
+    };
+    app.get("/cdp/json", (req, res) => { void listHandler(req, res); });
+    app.get("/cdp/json/list", (req, res) => { void listHandler(req, res); });
+}
+/**
+ * Attaches the WebSocket upgrade handler for /cdp/devtools/* paths to the given HTTP server. Called from startServer after app.listen() returns the server.
+ * Upgrades for paths outside /cdp/devtools/ are ignored (left to any other upgrade handler).
+ * @param server - The Node HTTP server.
+ */
+export function attachCdpUpgradeHandler(server) {
+    if (wss) {
+        return;
+    }
+    wss = new WebSocketServer({ noServer: true });
+    server.on("upgrade", (req, socket, head) => {
+        const url = req.url ?? "";
+        if (!url.startsWith("/cdp/devtools/")) {
+            // Not ours - leave the socket for any other upgrade handler. PrismCast doesn't currently install another, but this keeps the surface composable.
+            return;
+        }
+        if (!isCategoryEnabled("cdp")) {
+            socket.write("HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        const browser = getBrowserInstance();
+        if (!browser) {
+            socket.write("HTTP/1.1 503 Service Unavailable\r\nConnection: close\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        if (!wss) {
+            socket.destroy();
+            return;
+        }
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            const proxySession = new CdpProxySession(ws, browser);
+            void proxySession.start();
+        });
+    });
+    LOG.info("CDP proxy listening at /cdp.");
+}
+//# sourceMappingURL=cdp.js.map