playwriter 0.0.63 → 0.0.89

package/dist/cdp-relay.js

@@ -13,6 +13,7 @@ import { EventEmitter } from 'node:events';
 import { VERSION, EXTENSION_IDS } from './utils.js';
 import { createCdpLogger } from './cdp-log.js';
 import { RecordingRelay } from './recording-relay.js';
+import * as relayState from './relay-state.js';
 /**
  * Checks if a target should be filtered out (not exposed to Playwright).
  * Filters extension pages, service workers, and other restricted targets,
@@ -42,34 +43,64 @@ function isRestrictedTarget(targetInfo) {
 }
 export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.0.0.1', token, logger, cdpLogger, } = {}) {
     const emitter = new EventEmitter();
-    const extensionConnections = new Map();
-    const extensionKeyIndex = new Map();
+    const store = relayState.createRelayStore();
+    const extensionDownloadBehavior = new Map();
     const resolvedCdpLogger = cdpLogger || createCdpLogger();
     const logCdpJson = (entry) => {
         resolvedCdpLogger.log(entry);
     };
-    const playwrightClients = new Map();
     const getDefaultExtensionId = () => {
-        return extensionConnections.keys().next().value || null;
+        return store.getState().extensions.keys().next().value || null;
     };
+    /**
+     * Resolve an extension by ID, stableKey, or fallback.
+     * Returns the unified ExtensionEntry which includes both state and I/O.
+     */
     const getExtensionConnection = (extensionId, options = {}) => {
+        const currentRelayState = store.getState();
+        const { extensions } = currentRelayState;
         if (extensionId) {
-            const direct = extensionConnections.get(extensionId);
-            if (direct) {
+            const direct = extensions.get(extensionId);
+            if (direct?.ws) {
                 return direct;
             }
-            const mappedId = extensionKeyIndex.get(extensionId);
-            if (mappedId) {
-                return extensionConnections.get(mappedId) || null;
+            // Try stableKey lookup.
+            const byKey = relayState.findExtensionByStableKey(currentRelayState, extensionId);
+            if (byKey) {
+                const candidates = Array.from(extensions.values())
+                    .filter((ext) => ext.stableKey === byKey.stableKey)
+                    .reverse();
+                for (const candidate of candidates) {
+                    if (candidate.ws) {
+                        return candidate;
+                    }
+                }
             }
             return null;
         }
         if (!options.allowFallback) {
             return null;
         }
-        const fallbackId = getDefaultExtensionId();
-        if (fallbackId) {
-            return extensionConnections.get(fallbackId) || null;
+        // Single extension — use it directly
+        if (extensions.size === 1) {
+            const fallbackId = getDefaultExtensionId();
+            if (fallbackId) {
+                const ext = extensions.get(fallbackId);
+                if (ext?.ws) {
+                    return ext;
+                }
+            }
+        }
+        // Multiple extensions — auto-select if exactly one has active targets.
+        // This handles the common case of multiple Chrome profiles with the extension
+        // installed, where only one profile has playwriter-enabled tabs. (#52)
+        if (extensions.size > 1) {
+            const activeExtensions = Array.from(extensions.values()).filter((ext) => {
+                return ext.connectedTargets.size > 0;
+            });
+            if (activeExtensions.length === 1 && activeExtensions[0].ws) {
+                return activeExtensions[0];
+            }
         }
         return null;
     };
@@ -92,39 +123,41 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
         const normalized = String(value);
         return normalized ? normalized : null;
     };
-    const getPageTargetForFrameId = ({ connection, frameId }) => {
-        return Array.from(connection.connectedTargets.values()).find((target) => {
+    const getPageTargetForFrameId = ({ extensionState, frameId, }) => {
+        return Array.from(extensionState.connectedTargets.values()).find((target) => {
             return target.targetInfo.type === 'page' && target.frameIds.has(frameId);
         });
     };
     const startExtensionPing = (extensionId) => {
-        const connection = extensionConnections.get(extensionId);
-        if (!connection) {
+        const ext = store.getState().extensions.get(extensionId);
+        if (!ext) {
             return;
         }
-        if (connection.pingInterval) {
-            clearInterval(connection.pingInterval);
+        if (ext.pingInterval) {
+            clearInterval(ext.pingInterval);
         }
-        connection.pingInterval = setInterval(() => {
-            connection.ws.send(JSON.stringify({ method: 'ping' }));
+        const pingInterval = setInterval(() => {
+            const latestExt = store.getState().extensions.get(extensionId);
+            latestExt?.ws?.send(JSON.stringify({ method: 'ping' }));
         }, 5000);
+        store.setState((s) => relayState.updateExtensionIO(s, { extensionId, pingInterval }));
     };
     const stopExtensionPing = (extensionId) => {
-        const connection = extensionConnections.get(extensionId);
-        if (!connection || !connection.pingInterval) {
+        const ext = store.getState().extensions.get(extensionId);
+        if (!ext || !ext.pingInterval) {
             return;
         }
-        clearInterval(connection.pingInterval);
-        connection.pingInterval = null;
+        clearInterval(ext.pingInterval);
+        store.setState((s) => relayState.updateExtensionIO(s, { extensionId, pingInterval: null }));
     };
-    function logCdpMessage({ direction, clientId, method, sessionId, params, id, source }) {
+    function logCdpMessage({ direction, clientId, method, sessionId, params, id, source, }) {
         const noisyEvents = [
             'Network.requestWillBeSentExtraInfo',
             'Network.responseReceived',
             'Network.responseReceivedExtraInfo',
             'Network.dataReceived',
             'Network.requestWillBeSent',
-            'Network.loadingFinished'
+            'Network.loadingFinished',
         ];
         if (noisyEvents.includes(method)) {
             return;
@@ -163,9 +196,7 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
         }
     }
     function sendToPlaywright({ message, clientId, source = 'extension', extensionId, }) {
-        const messageToSend = source === 'server' && 'method' in message
-            ? { ...message, __serverGenerated: true }
-            : message;
+        const messageToSend = source === 'server' && 'method' in message ? { ...message, __serverGenerated: true } : message;
         logCdpJson({
             timestamp: new Date().toISOString(),
             direction: 'to-playwright',
@@ -180,7 +211,7 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                 method: message.method,
                 sessionId: 'sessionId' in message ? message.sessionId : undefined,
                 params: 'params' in message ? message.params : undefined,
-                source
+                source,
             });
         }
         const messageStr = JSON.stringify(messageToSend);
@@ -200,14 +231,14 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
             }
         };
         if (clientId) {
-            const client = playwrightClients.get(clientId);
+            const client = store.getState().playwrightClients.get(clientId);
             if (client) {
                 safeSend(client);
             }
         }
         else {
-            const clients = Array.from(playwrightClients.values());
-            for (const client of clients) {
+            const { playwrightClients } = store.getState();
+            for (const client of playwrightClients.values()) {
                 if (extensionId && client.extensionId !== extensionId) {
                     continue;
                 }
@@ -227,11 +258,25 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
         return { method: record.method, sessionId, params: record.params };
     }
     async function sendToExtension({ extensionId, method, params, timeout = 30000, }) {
-        const connection = getExtensionConnection(extensionId);
-        if (!connection) {
+        const conn = getExtensionConnection(extensionId);
+        if (!conn) {
+            throw new Error('Extension not connected');
+        }
+        const resolvedExtensionId = conn.id;
+        let id = 0;
+        store.setState((s) => {
+            const ext = s.extensions.get(resolvedExtensionId);
+            if (!ext) {
+                return s;
+            }
+            id = ext.messageId + 1;
+            const newExtensions = new Map(s.extensions);
+            newExtensions.set(resolvedExtensionId, { ...ext, messageId: id });
+            return { ...s, extensions: newExtensions };
+        });
+        if (!id) {
             throw new Error('Extension not connected');
         }
-        const id = ++connection.messageId;
         const message = { id, method, params };
         const forwardCdpParams = method === 'forwardCDPCommand' ? getForwardCdpParams(params) : undefined;
         if (forwardCdpParams) {
@@ -245,13 +290,15 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                 },
             });
         }
-        connection.ws.send(JSON.stringify(message));
         return new Promise((resolve, reject) => {
             const timeoutId = setTimeout(() => {
-                connection.pendingRequests.delete(id);
+                store.setState((s) => relayState.removeExtensionPendingRequest(s, {
+                    extensionId: resolvedExtensionId,
+                    requestId: id,
+                }));
                 reject(new Error(`Extension request timeout after ${timeout}ms: ${method}`));
             }, timeout);
-            connection.pendingRequests.set(id, {
+            const pendingRequest = {
                 resolve: (result) => {
                     clearTimeout(timeoutId);
                     resolve(result);
@@ -259,21 +306,63 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                 reject: (error) => {
                     clearTimeout(timeoutId);
                     reject(error);
-                }
-            });
+                },
+            };
+            store.setState((s) => relayState.addExtensionPendingRequest(s, {
+                extensionId: resolvedExtensionId,
+                requestId: id,
+                pendingRequest,
+            }));
+            const latestExt = store.getState().extensions.get(resolvedExtensionId);
+            if (!latestExt?.ws) {
+                clearTimeout(timeoutId);
+                store.setState((s) => relayState.removeExtensionPendingRequest(s, {
+                    extensionId: resolvedExtensionId,
+                    requestId: id,
+                }));
+                reject(new Error('Extension not connected'));
+                return;
+            }
+            try {
+                latestExt.ws.send(JSON.stringify(message));
+            }
+            catch (error) {
+                clearTimeout(timeoutId);
+                store.setState((s) => relayState.removeExtensionPendingRequest(s, {
+                    extensionId: resolvedExtensionId,
+                    requestId: id,
+                }));
+                const sendError = error instanceof Error ? error : new Error(String(error));
+                reject(new Error(`Extension send failed: ${method}`, { cause: sendError }));
+            }
         });
     }
     const recordingRelays = new Map();
+    // Find which extension connection owns a CDP tab session ID (pw-tab-*).
+    // Used by recording routes where sessionId identifies the target tab.
+    // Delegates to the pure derivation function from relay-state.ts.
+    const findExtensionIdByCdpSession = (cdpSessionId) => {
+        return relayState.findExtensionIdByCdpSession(store.getState(), cdpSessionId);
+    };
+    // Resolve recording route session ID (CDP tab session) to extension connection.
+    const resolveRecordingRoute = async ({ sessionId, }) => {
+        if (!sessionId) {
+            return { extensionId: null, sessionId: null };
+        }
+        const extensionId = findExtensionIdByCdpSession(sessionId);
+        return { extensionId, sessionId };
+    };
     const getRecordingRelay = (extensionId) => {
-        const allowDefault = !extensionId && extensionConnections.size === 1;
-        const connection = getExtensionConnection(extensionId, { allowFallback: allowDefault });
-        if (!connection) {
+        const allowDefault = !extensionId && store.getState().extensions.size === 1;
+        const conn = getExtensionConnection(extensionId, { allowFallback: allowDefault });
+        if (!conn) {
             return null;
         }
-        if (!recordingRelays.has(connection.id)) {
-            recordingRelays.set(connection.id, new RecordingRelay((params) => sendToExtension({ extensionId: connection.id, ...params }), () => extensionConnections.has(connection.id), logger));
+        const connId = conn.id;
+        if (!recordingRelays.has(connId)) {
+            recordingRelays.set(connId, new RecordingRelay((params) => sendToExtension({ extensionId: connId, ...params }), () => store.getState().extensions.has(connId), logger));
         }
-        return recordingRelays.get(connection.id) || null;
+        return recordingRelays.get(connId) || null;
     };
     // Auto-create initial tab when PLAYWRITER_AUTO_ENABLE is set and no targets exist.
     // This allows Playwright to connect and immediately have a page to work with.
@@ -281,33 +370,97 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
         if (!process.env.PLAYWRITER_AUTO_ENABLE) {
             return;
         }
-        const connection = getExtensionConnection(extensionId);
-        if (!connection) {
+        const conn = getExtensionConnection(extensionId);
+        if (!conn) {
             return;
         }
-        if (connection.connectedTargets.size > 0) {
+        if (conn.connectedTargets.size > 0) {
             return;
         }
         try {
             logger?.log(pc.blue('Auto-creating initial tab for Playwright client'));
-            const result = await sendToExtension({ extensionId, method: 'createInitialTab', timeout: 10000 });
+            const result = (await sendToExtension({ extensionId, method: 'createInitialTab', timeout: 10000 }));
             if (result.success && result.sessionId && result.targetInfo) {
-                connection.connectedTargets.set(result.sessionId, {
+                store.setState((s) => relayState.addTarget(s, {
+                    extensionId,
                     sessionId: result.sessionId,
                     targetId: result.targetInfo.targetId,
                     targetInfo: result.targetInfo,
-                    frameIds: new Set()
-                });
-                logger?.log(pc.blue(`Auto-created tab, now have ${connection.connectedTargets.size} targets, url: ${result.targetInfo.url}`));
+                }));
+                const updatedTargets = store.getState().extensions.get(extensionId)?.connectedTargets.size || 0;
+                logger?.log(pc.blue(`Auto-created tab, now have ${updatedTargets} targets, url: ${result.targetInfo.url}`));
             }
         }
         catch (e) {
             logger?.error('Failed to auto-create initial tab:', e);
         }
     }
+    function getPageTargetSessionIds({ extensionId }) {
+        const extensionState = store.getState().extensions.get(extensionId);
+        if (!extensionState) {
+            return [];
+        }
+        return Array.from(extensionState.connectedTargets.values())
+            .filter((target) => {
+            return target.targetInfo.type === 'page';
+        })
+            .map((target) => {
+            return target.sessionId;
+        });
+    }
+    function maybeEmitBrowserDownloadCompatEvent({ method, params, extensionId, }) {
+        const browserEventMethod = method === 'Page.downloadWillBegin'
+            ? 'Browser.downloadWillBegin'
+            : method === 'Page.downloadProgress'
+                ? 'Browser.downloadProgress'
+                : null;
+        if (!browserEventMethod) {
+            return;
+        }
+        sendToPlaywright({
+            message: {
+                method: browserEventMethod,
+                params,
+            },
+            source: 'server',
+            extensionId,
+        });
+    }
+    async function applyDownloadBehaviorToTargets({ extensionId, behavior, source, targetSessionIds, }) {
+        const pageBehavior = behavior.behavior === 'allowAndName' ? 'allow' : behavior.behavior;
+        const pageParams = (() => {
+            if (pageBehavior === 'allow' && behavior.downloadPath) {
+                return { behavior: pageBehavior, downloadPath: behavior.downloadPath };
+            }
+            return { behavior: pageBehavior };
+        })();
+        const sessions = targetSessionIds || getPageTargetSessionIds({ extensionId });
+        if (sessions.length === 0) {
+            return;
+        }
+        await Promise.all(sessions.map(async (targetSessionId) => {
+            try {
+                await sendToExtension({
+                    extensionId,
+                    method: 'forwardCDPCommand',
+                    params: {
+                        sessionId: targetSessionId,
+                        method: 'Page.setDownloadBehavior',
+                        params: pageParams,
+                        source,
+                    },
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                logger?.log(pc.yellow(`[Server] Failed to apply Page.setDownloadBehavior to ${targetSessionId}: ${message}`));
+            }
+        }));
+    }
     async function routeCdpCommand({ extensionId, method, params, sessionId, source, }) {
-        const extension = getExtensionConnection(extensionId);
-        const connectedTargets = extension?.connectedTargets || new Map();
+        const conn = getExtensionConnection(extensionId);
+        const connectedTargets = conn?.connectedTargets || new Map();
+        const resolvedExtensionId = conn?.id || extensionId;
         switch (method) {
             case 'Browser.getVersion': {
                 return {
@@ -315,10 +468,22 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                     product: 'Chrome/Extension-Bridge',
                     revision: '1.0.0',
                     userAgent: 'CDP-Bridge-Server/1.0.0',
-                    jsVersion: 'V8'
+                    jsVersion: 'V8',
                 };
             }
             case 'Browser.setDownloadBehavior': {
+                const downloadBehaviorParams = params;
+                if (!downloadBehaviorParams?.behavior) {
+                    throw new Error('behavior is required for Browser.setDownloadBehavior');
+                }
+                if (resolvedExtensionId) {
+                    extensionDownloadBehavior.set(resolvedExtensionId, downloadBehaviorParams);
+                    await applyDownloadBehaviorToTargets({
+                        extensionId: resolvedExtensionId,
+                        behavior: downloadBehaviorParams,
+                        source,
+                    });
+                }
                 return {};
             }
             // Target.setAutoAttach is a CDP command Playwright sends on first connection.
@@ -328,15 +493,15 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                 if (sessionId) {
                     break;
                 }
-                if (extension) {
-                    await maybeAutoCreateInitialTab(extension.id);
+                if (conn) {
+                    await maybeAutoCreateInitialTab(conn.id);
                 }
                 // Forward auto-attach so Chrome emits iframe Target.attachedToTarget events.
                 // Playwright relies on these (with parentFrameId) when reconnecting over CDP.
                 await sendToExtension({
-                    extensionId: extension?.id || extensionId,
+                    extensionId: resolvedExtensionId,
                     method: 'forwardCDPCommand',
-                    params: { method, params, source }
+                    params: { method, params, source },
                 });
                 return {};
             }
@@ -344,19 +509,20 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                 return {};
             }
             case 'Target.attachToTarget': {
-                const targetId = params?.targetId;
-                if (!targetId) {
+                const attachParams = params;
+                if (!attachParams?.targetId) {
                     throw new Error('targetId is required for Target.attachToTarget');
                 }
                 for (const target of connectedTargets.values()) {
-                    if (target.targetId === targetId) {
+                    if (target.targetId === attachParams.targetId) {
                         return { sessionId: target.sessionId };
                     }
                 }
-                throw new Error(`Target ${targetId} not found in connected targets`);
+                throw new Error(`Target ${attachParams.targetId} not found in connected targets`);
             }
             case 'Target.getTargetInfo': {
-                const targetId = params?.targetId;
+                const infoReqParams = params;
+                const targetId = infoReqParams?.targetId;
                 if (targetId) {
                     for (const target of connectedTargets.values()) {
                         if (target.targetId === targetId) {
@@ -379,30 +545,30 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                         .filter((t) => !isRestrictedTarget(t.targetInfo))
                         .map((t) => ({
                         ...t.targetInfo,
-                        attached: true
-                    }))
+                        attached: true,
+                    })),
                 };
             }
             case 'Target.createTarget': {
                 return await sendToExtension({
-                    extensionId: extension?.id || extensionId,
+                    extensionId: resolvedExtensionId,
                     method: 'forwardCDPCommand',
-                    params: { method, params, source }
+                    params: { method, params, source },
                 });
             }
             case 'Target.closeTarget': {
                 return await sendToExtension({
-                    extensionId: extension?.id || extensionId,
+                    extensionId: resolvedExtensionId,
                     method: 'forwardCDPCommand',
-                    params: { method, params, source }
+                    params: { method, params, source },
                 });
             }
             // Ghost Browser API - forward to extension for chrome.ghostPublicAPI/ghostProxies/projects
             case 'ghost-browser': {
                 return await sendToExtension({
-                    extensionId: extension?.id || extensionId,
+                    extensionId: resolvedExtensionId,
                     method: 'ghost-browser',
-                    params
+                    params,
                 });
             }
             case 'Runtime.enable': {
@@ -428,18 +594,18 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                     emitter.on('cdp:event', handler);
                 });
                 const result = await sendToExtension({
-                    extensionId: extension?.id || extensionId,
+                    extensionId: resolvedExtensionId,
                     method: 'forwardCDPCommand',
-                    params: { sessionId, method, params, source }
+                    params: { sessionId, method, params, source },
                 });
                 await contextCreatedPromise;
                 return result;
             }
         }
         return await sendToExtension({
-            extensionId: extension?.id || extensionId,
+            extensionId: resolvedExtensionId,
             method: 'forwardCDPCommand',
-            params: { sessionId, method, params, source }
+            params: { sessionId, method, params, source },
         });
     }
     const app = new Hono();
@@ -472,7 +638,7 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
     });
     app.get('/extension/status', (c) => {
         const defaultExtension = getExtensionConnection(null, { allowFallback: true });
-        const connected = extensionConnections.size > 0;
+        const connected = store.getState().extensions.size > 0;
         const activeTargets = defaultExtension?.connectedTargets.size || 0;
         const info = defaultExtension?.info;
         return c.json({
@@ -484,14 +650,14 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
         });
     });
     app.get('/extensions/status', (c) => {
-        const extensions = Array.from(extensionConnections.values()).map((extension) => {
+        const extensions = Array.from(store.getState().extensions.values()).map((ext) => {
             return {
-                extensionId: extension.id,
-                stableKey: extension.stableKey,
-                browser: extension.info.browser || null,
-                profile: extension.info ? { email: extension.info.email || '', id: extension.info.id || '' } : null,
-                activeTargets: extension.connectedTargets.size,
-                playwriterVersion: extension.info?.version || null,
+                extensionId: ext.id,
+                stableKey: ext.stableKey,
+                browser: ext.info.browser || null,
+                profile: ext.info ? { email: ext.info.email || '', id: ext.info.id || '' } : null,
+                activeTargets: ext.connectedTargets.size,
+                playwriterVersion: ext.info?.version || null,
             };
         });
         return c.json({ extensions });
@@ -502,68 +668,68 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
     app
         .on(['GET', 'PUT'], '/json/version', (c) => {
         return c.json({
-            'Browser': `Playwriter/${VERSION}`,
+            Browser: `Playwriter/${VERSION}`,
             'Protocol-Version': '1.3',
-            'webSocketDebuggerUrl': getCdpWsUrl(c)
+            webSocketDebuggerUrl: getCdpWsUrl(c),
         });
     })
         .on(['GET', 'PUT'], '/json/version/', (c) => {
         return c.json({
-            'Browser': `Playwriter/${VERSION}`,
+            Browser: `Playwriter/${VERSION}`,
             'Protocol-Version': '1.3',
-            'webSocketDebuggerUrl': getCdpWsUrl(c)
+            webSocketDebuggerUrl: getCdpWsUrl(c),
         });
     })
         .on(['GET', 'PUT'], '/json/list', (c) => {
         const wsUrl = getCdpWsUrl(c);
         const defaultTargets = getExtensionConnection(null, { allowFallback: true })?.connectedTargets || new Map();
-        return c.json(Array.from(defaultTargets.values()).map(t => ({
+        return c.json(Array.from(defaultTargets.values()).map((t) => ({
             id: t.targetId,
             type: t.targetInfo.type,
             title: t.targetInfo.title,
             description: t.targetInfo.title,
             url: t.targetInfo.url,
             webSocketDebuggerUrl: wsUrl,
-            devtoolsFrontendUrl: `/devtools/inspector.html?ws=${wsUrl.replace('ws://', '')}`
+            devtoolsFrontendUrl: `/devtools/inspector.html?ws=${wsUrl.replace('ws://', '')}`,
         })));
     })
         .on(['GET', 'PUT'], '/json/list/', (c) => {
         const wsUrl = getCdpWsUrl(c);
         const defaultTargets = getExtensionConnection(null, { allowFallback: true })?.connectedTargets || new Map();
-        return c.json(Array.from(defaultTargets.values()).map(t => ({
+        return c.json(Array.from(defaultTargets.values()).map((t) => ({
             id: t.targetId,
             type: t.targetInfo.type,
             title: t.targetInfo.title,
             description: t.targetInfo.title,
             url: t.targetInfo.url,
             webSocketDebuggerUrl: wsUrl,
-            devtoolsFrontendUrl: `/devtools/inspector.html?ws=${wsUrl.replace('ws://', '')}`
+            devtoolsFrontendUrl: `/devtools/inspector.html?ws=${wsUrl.replace('ws://', '')}`,
         })));
     })
         .on(['GET', 'PUT'], '/json', (c) => {
         const wsUrl = getCdpWsUrl(c);
         const defaultTargets = getExtensionConnection(null, { allowFallback: true })?.connectedTargets || new Map();
-        return c.json(Array.from(defaultTargets.values()).map(t => ({
+        return c.json(Array.from(defaultTargets.values()).map((t) => ({
             id: t.targetId,
             type: t.targetInfo.type,
             title: t.targetInfo.title,
             description: t.targetInfo.title,
             url: t.targetInfo.url,
             webSocketDebuggerUrl: wsUrl,
-            devtoolsFrontendUrl: `/devtools/inspector.html?ws=${wsUrl.replace('ws://', '')}`
+            devtoolsFrontendUrl: `/devtools/inspector.html?ws=${wsUrl.replace('ws://', '')}`,
         })));
     })
         .on(['GET', 'PUT'], '/json/', (c) => {
         const wsUrl = getCdpWsUrl(c);
         const defaultTargets = getExtensionConnection(null, { allowFallback: true })?.connectedTargets || new Map();
-        return c.json(Array.from(defaultTargets.values()).map(t => ({
+        return c.json(Array.from(defaultTargets.values()).map((t) => ({
             id: t.targetId,
             type: t.targetInfo.type,
             title: t.targetInfo.title,
             description: t.targetInfo.title,
             url: t.targetInfo.url,
             webSocketDebuggerUrl: wsUrl,
-            devtoolsFrontendUrl: `/devtools/inspector.html?ws=${wsUrl.replace('ws://', '')}`
+            devtoolsFrontendUrl: `/devtools/inspector.html?ws=${wsUrl.replace('ws://', '')}`,
         })));
     });
     app.post('/mcp-log', async (c) => {
@@ -610,13 +776,19 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
         const clientId = c.req.param('clientId') || 'default';
         const url = new URL(c.req.url, 'http://localhost');
         const requestedExtensionId = url.searchParams.get('extensionId');
-        const resolvedExtension = getExtensionConnection(requestedExtensionId);
-        const allowDefault = !requestedExtensionId && extensionConnections.size === 1;
-        const defaultExtension = allowDefault ? getExtensionConnection(null, { allowFallback: true }) : null;
-        const clientExtensionId = resolvedExtension?.id || defaultExtension?.id || null;
+        // When extensionId is explicit, resolve directly. Otherwise use fallback which
+        // handles single-extension and uniquely-active-extension cases (#52).
+        const resolvedExtension = requestedExtensionId
+            ? getExtensionConnection(requestedExtensionId)
+            : getExtensionConnection(null, { allowFallback: true });
+        const clientExtensionId = resolvedExtension?.id || null;
+        const getBoundExtensionIdForClient = () => {
+            const client = store.getState().playwrightClients.get(clientId);
+            return client?.extensionId || null;
+        };
         return {
             async onOpen(_event, ws) {
-                if (playwrightClients.has(clientId)) {
+                if (store.getState().playwrightClients.has(clientId)) {
                     logger?.log(pc.yellow(`Rejecting duplicate Playwright clientId: ${clientId}`));
                     ws.close(4004, 'Duplicate Playwright clientId');
                     return;
@@ -630,10 +802,12 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                     return;
                 }
                 // Add client first so it can receive Target.attachedToTarget events
-                playwrightClients.set(clientId, { id: clientId, ws, extensionId: clientExtensionId });
+                store.setState((s) => {
+                    return relayState.addPlaywrightClient(s, { id: clientId, extensionId: clientExtensionId, ws });
+                });
                 const extensionConnection = getExtensionConnection(clientExtensionId);
                 const targetCount = extensionConnection?.connectedTargets.size || 0;
-                logger?.log(pc.green(`Playwright client connected: ${clientId} (${playwrightClients.size} total) (extension? ${!!extensionConnection}) (${targetCount} pages)`));
+                logger?.log(pc.green(`Playwright client connected: ${clientId} (${store.getState().playwrightClients.size} total) (extension? ${!!extensionConnection}) (${targetCount} pages)`));
             },
             async onMessage(event, ws) {
                 let message;
@@ -655,25 +829,35 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                     clientId,
                     method,
                     sessionId,
-                    id
+                    id,
                 });
                 emitter.emit('cdp:command', { clientId, command: message });
-                const extensionConnection = getExtensionConnection(clientExtensionId);
-                if (!extensionConnection) {
+                const boundExtensionId = getBoundExtensionIdForClient();
+                const extensionConn = getExtensionConnection(boundExtensionId);
+                if (!extensionConn) {
                     sendToPlaywright({
                         message: {
                             id,
                             sessionId,
-                            error: { message: 'Extension not connected' }
+                            error: { message: 'Extension not connected' },
                         },
-                        clientId
+                        clientId,
                     });
                     return;
                 }
                 try {
-                    const result = await routeCdpCommand({ extensionId: extensionConnection.id, method, params, sessionId, source });
+                    const result = await routeCdpCommand({
+                        extensionId: extensionConn.id,
+                        method,
+                        params,
+                        sessionId,
+                        source,
+                    });
                     if (method === 'Target.setAutoAttach' && !sessionId) {
-                        for (const target of extensionConnection.connectedTargets.values()) {
+                        // Re-read state after async routeCdpCommand — targets may have changed
+                        const freshExt = store.getState().extensions.get(extensionConn.id);
+                        const freshTargets = freshExt?.connectedTargets || new Map();
+                        for (const target of freshTargets.values()) {
                             // Skip restricted targets (extensions, chrome:// URLs, non-page types)
                             if (isRestrictedTarget(target.targetInfo)) {
                                 continue;
@@ -684,10 +868,10 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                                     sessionId: target.sessionId,
                                     targetInfo: {
                                         ...target.targetInfo,
-                                        attached: true
+                                        attached: true,
                                     },
-                                    waitingForDebugger: false
-                                }
+                                    waitingForDebugger: false,
+                                },
                             };
                             if (!target.targetInfo.url) {
                                 logger?.error(pc.red('[Server] WARNING: Target.attachedToTarget sent with empty URL!'), JSON.stringify(attachedPayload));
@@ -696,12 +880,14 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                             sendToPlaywright({
                                 message: attachedPayload,
                                 clientId,
-                                source: 'server'
+                                source: 'server',
                             });
                         }
                     }
                     if (method === 'Target.setDiscoverTargets' && params?.discover) {
-                        for (const target of extensionConnection.connectedTargets.values()) {
+                        const freshExt2 = store.getState().extensions.get(extensionConn.id);
+                        const freshTargets2 = freshExt2?.connectedTargets || new Map();
+                        for (const target of freshTargets2.values()) {
                             // Skip restricted targets (extensions, chrome:// URLs, non-page types)
                             if (isRestrictedTarget(target.targetInfo)) {
                                 continue;
@@ -711,9 +897,9 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                                 params: {
                                     targetInfo: {
                                         ...target.targetInfo,
-                                        attached: true
-                                    }
-                                }
+                                        attached: true,
+                                    },
+                                },
                             };
                             if (!target.targetInfo.url) {
                                 logger?.error(pc.red('[Server] WARNING: Target.targetCreated sent with empty URL!'), JSON.stringify(targetCreatedPayload));
@@ -722,34 +908,41 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                             sendToPlaywright({
                                 message: targetCreatedPayload,
                                 clientId,
-                                source: 'server'
+                                source: 'server',
                             });
                         }
                     }
-                    if (method === 'Target.attachToTarget' && result?.sessionId) {
-                        const targetId = params?.targetId;
-                        const target = Array.from(extensionConnection.connectedTargets.values()).find(t => t.targetId === targetId);
-                        if (target) {
-                            const attachedPayload = {
-                                method: 'Target.attachedToTarget',
-                                params: {
-                                    sessionId: result.sessionId,
-                                    targetInfo: {
-                                        ...target.targetInfo,
-                                        attached: true
+                    if (method === 'Target.attachToTarget') {
+                        const attachResponse = result;
+                        const attachRequestParams = params;
+                        if (attachResponse?.sessionId) {
+                            const freshExt3 = store.getState().extensions.get(extensionConn.id);
+                            const freshTargets3 = freshExt3?.connectedTargets || new Map();
+                            const target = Array.from(freshTargets3.values()).find((t) => {
+                                return t.targetId === attachRequestParams?.targetId;
+                            });
+                            if (target) {
+                                const attachedPayload = {
+                                    method: 'Target.attachedToTarget',
+                                    params: {
+                                        sessionId: attachResponse.sessionId,
+                                        targetInfo: {
+                                            ...target.targetInfo,
+                                            attached: true,
+                                        },
+                                        waitingForDebugger: false,
                                     },
-                                    waitingForDebugger: false
+                                };
+                                if (!target.targetInfo.url) {
+                                    logger?.error(pc.red('[Server] WARNING: Target.attachedToTarget (from attachToTarget) sent with empty URL!'), JSON.stringify(attachedPayload));
                                 }
-                            };
-                            if (!target.targetInfo.url) {
-                                logger?.error(pc.red('[Server] WARNING: Target.attachedToTarget (from attachToTarget) sent with empty URL!'), JSON.stringify(attachedPayload));
+                                logger?.log(pc.magenta('[Server] Target.attachedToTarget (from attachToTarget) payload:'), JSON.stringify(attachedPayload));
+                                sendToPlaywright({
+                                    message: attachedPayload,
+                                    clientId,
+                                    source: 'server',
+                                });
                             }
-                            logger?.log(pc.magenta('[Server] Target.attachedToTarget (from attachToTarget) payload:'), JSON.stringify(attachedPayload));
-                            sendToPlaywright({
-                                message: attachedPayload,
-                                clientId,
-                                source: 'server'
-                            });
                         }
                     }
                     const response = { id, sessionId, result };
@@ -761,19 +954,19 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                     const errorResponse = {
                         id,
                         sessionId,
-                        error: { message: e.message }
+                        error: { message: e.message },
                     };
                     sendToPlaywright({ message: errorResponse, clientId });
                     emitter.emit('cdp:response', { clientId, response: errorResponse, command: message });
                 }
             },
             onClose() {
-                playwrightClients.delete(clientId);
-                logger?.log(pc.yellow(`Playwright client disconnected: ${clientId} (${playwrightClients.size} remaining)`));
+                store.setState((s) => relayState.removePlaywrightClient(s, { clientId }));
+                logger?.log(pc.yellow(`Playwright client disconnected: ${clientId} (${store.getState().playwrightClients.size} remaining)`));
             },
             onError(event) {
                 logger?.error(`Playwright WebSocket error [${clientId}]:`, event);
-            }
+            },
         };
     }));
     const getExtensionInfoFromRequest = (c) => {
@@ -819,32 +1012,25 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
         return {
             onOpen(_event, ws) {
                 const stableKey = buildStableExtensionKey(incomingExtensionInfo, connectionId);
-                const existingId = extensionKeyIndex.get(stableKey);
-                if (existingId && existingId !== connectionId) {
-                    logger?.log(pc.yellow(`Replacing extension connection for ${stableKey} (${existingId} -> ${connectionId})`));
-                    const existingConnection = extensionConnections.get(existingId);
-                    if (existingConnection) {
-                        existingConnection.ws.close(4001, 'Extension Replaced');
+                // Check for existing connection with same stableKey and close it
+                const existingExt = relayState.findExtensionByStableKey(store.getState(), stableKey);
+                if (existingExt && existingExt.id !== connectionId) {
+                    logger?.log(pc.yellow(`Replacing extension connection for ${stableKey} (${existingExt.id} -> ${connectionId})`));
+                    if (existingExt.ws) {
+                        existingExt.ws.close(4001, 'Extension Replaced');
                     }
                 }
-                const connection = {
-                    id: connectionId,
-                    ws,
-                    info: incomingExtensionInfo,
-                    stableKey,
-                    connectedTargets: new Map(),
-                    pendingRequests: new Map(),
-                    messageId: 0,
-                    pingInterval: null,
-                };
-                extensionConnections.set(connectionId, connection);
-                extensionKeyIndex.set(stableKey, connectionId);
+                // State transition: add extension with ws handle included.
+                // Existing same-stableKey entry stays until old socket onClose.
+                store.setState((s) => {
+                    return relayState.addExtension(s, { id: connectionId, info: incomingExtensionInfo, stableKey, ws });
+                });
                 startExtensionPing(connectionId);
                 logger?.log(`Extension connected (${connectionId})`);
             },
             async onMessage(event, ws) {
-                const connection = extensionConnections.get(connectionId);
-                if (!connection) {
+                const ext = store.getState().extensions.get(connectionId);
+                if (!ext) {
                     ws.close(1000, 'Extension not registered');
                     return;
                 }
@@ -866,12 +1052,29 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                     return;
                 }
                 if (message.id !== undefined) {
-                    const pending = connection.pendingRequests.get(message.id);
+                    const pending = (() => {
+                        let pendingRequest = null;
+                        store.setState((s) => {
+                            const extensionEntry = s.extensions.get(connectionId);
+                            if (!extensionEntry) {
+                                return s;
+                            }
+                            const nextPendingRequest = extensionEntry.pendingRequests.get(message.id);
+                            if (!nextPendingRequest) {
+                                return s;
+                            }
+                            pendingRequest = nextPendingRequest;
+                            return relayState.removeExtensionPendingRequest(s, {
+                                extensionId: connectionId,
+                                requestId: message.id,
+                            });
+                        });
+                        return pendingRequest;
+                    })();
                     if (!pending) {
                         logger?.log('Unexpected response with id:', message.id);
                         return;
                     }
-                    connection.pendingRequests.delete(message.id);
                     if (message.error) {
                         pending.reject(new Error(message.error));
                     }
@@ -916,16 +1119,19 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                         direction: 'from-extension',
                         method,
                         sessionId,
-                        params
+                        params,
                     });
                     const cdpEvent = { method, sessionId, params };
                     emitter.emit('cdp:event', { event: cdpEvent, sessionId });
+                    maybeEmitBrowserDownloadCompatEvent({ method, params, extensionId: connectionId });
                     if (method === 'Target.attachedToTarget') {
                         const targetParams = params;
                         const incomingSessionId = sessionId;
                         const iframeParentFrameId = targetParams.targetInfo.parentFrameId;
-                        const iframeOwnerSessionId = targetParams.targetInfo.type === 'iframe' && iframeParentFrameId
-                            ? getPageTargetForFrameId({ connection, frameId: iframeParentFrameId })?.sessionId
+                        // Read current extension state for iframe parent lookup
+                        const currentExtState = store.getState().extensions.get(connectionId);
+                        const iframeOwnerSessionId = targetParams.targetInfo.type === 'iframe' && iframeParentFrameId && currentExtState
+                            ? getPageTargetForFrameId({ extensionState: currentExtState, frameId: iframeParentFrameId })?.sessionId
                             : undefined;
                         // Filter out restricted targets (unsupported types, extension pages, chrome:// URLs, etc.)
                         if (isRestrictedTarget(targetParams.targetInfo)) {
@@ -940,8 +1146,8 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                                         source: 'server',
                                     },
                                 }).catch((error) => {
-                                    const message = error instanceof Error ? error.message : String(error);
-                                    logger?.log(pc.yellow('[Server] Failed to resume restricted target:'), message);
+                                    const msg = error instanceof Error ? error.message : String(error);
+                                    logger?.log(pc.yellow('[Server] Failed to resume restricted target:'), msg);
                                 });
                             }
                             logger?.log(pc.gray(`[Server] Ignoring restricted target: ${targetParams.targetInfo.type} (${targetParams.targetInfo.url})`));
@@ -952,15 +1158,22 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                         }
                         logger?.log(pc.yellow('[Extension] Target.attachedToTarget full payload:'), JSON.stringify({ method, params: targetParams, sessionId }));
                         // Check if we already sent this target to clients (e.g., from Target.setAutoAttach response)
-                        const alreadyConnected = connection.connectedTargets.has(targetParams.sessionId);
-                        const existingTarget = connection.connectedTargets.get(targetParams.sessionId);
-                        // Always update our local state with latest target info
-                        connection.connectedTargets.set(targetParams.sessionId, {
+                        const alreadyConnected = currentExtState?.connectedTargets.has(targetParams.sessionId) ?? false;
+                        // State transition: add/update target
+                        store.setState((s) => relayState.addTarget(s, {
+                            extensionId: connectionId,
                             sessionId: targetParams.sessionId,
                             targetId: targetParams.targetInfo.targetId,
                             targetInfo: targetParams.targetInfo,
-                            frameIds: existingTarget?.frameIds ?? new Set()
-                        });
+                        }));
+                        const cachedDownloadBehavior = extensionDownloadBehavior.get(connectionId);
+                        if (cachedDownloadBehavior && targetParams.targetInfo.type === 'page') {
+                            void applyDownloadBehaviorToTargets({
+                                extensionId: connectionId,
+                                behavior: cachedDownloadBehavior,
+                                targetSessionIds: [targetParams.sessionId],
+                            });
+                        }
                         // Only forward to Playwright if this is a new target to avoid duplicates
                         if (!alreadyConnected) {
                             sendToPlaywright({
@@ -973,7 +1186,7 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                                     // session, detaches it, and the iframe stays paused (waitingForDebugger) which can hang navigations.
                                     sessionId: iframeOwnerSessionId ?? incomingSessionId,
                                     method: 'Target.attachedToTarget',
-                                    params: targetParams
+                                    params: targetParams,
                                 },
                                 source: 'extension',
                                 extensionId: connectionId,
@@ -982,11 +1195,11 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                     }
                     else if (method === 'Target.detachedFromTarget') {
                         const detachParams = params;
-                        connection.connectedTargets.delete(detachParams.sessionId);
+                        store.setState((s) => relayState.removeTarget(s, { extensionId: connectionId, sessionId: detachParams.sessionId }));
                         sendToPlaywright({
                             message: {
                                 method: 'Target.detachedFromTarget',
-                                params: detachParams
+                                params: detachParams,
                             },
                             source: 'extension',
                             extensionId: connectionId,
@@ -994,17 +1207,12 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                     }
                     else if (method === 'Target.targetCrashed') {
                         const crashParams = params;
-                        for (const [sid, target] of connection.connectedTargets.entries()) {
-                            if (target.targetId === crashParams.targetId) {
-                                connection.connectedTargets.delete(sid);
-                                logger?.log(pc.red('[Server] Target crashed, removing:'), crashParams.targetId);
-                                break;
-                            }
-                        }
+                        store.setState((s) => relayState.removeTargetByCrash(s, { extensionId: connectionId, targetId: crashParams.targetId }));
+                        logger?.log(pc.red('[Server] Target crashed, removing:'), crashParams.targetId);
                         sendToPlaywright({
                             message: {
                                 method: 'Target.targetCrashed',
-                                params: crashParams
+                                params: crashParams,
                             },
                             source: 'extension',
                             extensionId: connectionId,
@@ -1012,16 +1220,11 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                     }
                     else if (method === 'Target.targetInfoChanged') {
                         const infoParams = params;
-                        for (const target of connection.connectedTargets.values()) {
-                            if (target.targetId === infoParams.targetInfo.targetId) {
-                                target.targetInfo = infoParams.targetInfo;
-                                break;
-                            }
-                        }
+                        store.setState((s) => relayState.updateTargetInfo(s, { extensionId: connectionId, targetInfo: infoParams.targetInfo }));
                         sendToPlaywright({
                             message: {
                                 method: 'Target.targetInfoChanged',
-                                params: infoParams
+                                params: infoParams,
                             },
                             source: 'extension',
                             extensionId: connectionId,
@@ -1030,16 +1233,13 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                     else if (method === 'Page.frameAttached') {
                         const frameParams = params;
                         if (sessionId) {
-                            const target = connection.connectedTargets.get(sessionId);
-                            if (target) {
-                                target.frameIds.add(frameParams.frameId);
-                            }
+                            store.setState((s) => relayState.addFrameId(s, { extensionId: connectionId, sessionId, frameId: frameParams.frameId }));
                         }
                         sendToPlaywright({
                             message: {
                                 sessionId,
                                 method,
-                                params
+                                params,
                             },
                             source: 'extension',
                             extensionId: connectionId,
@@ -1047,15 +1247,12 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                     }
                     else if (method === 'Page.frameDetached') {
                         const frameParams = params;
-                        const ownerTarget = getPageTargetForFrameId({ connection, frameId: frameParams.frameId });
-                        if (ownerTarget) {
-                            ownerTarget.frameIds.delete(frameParams.frameId);
-                        }
+                        store.setState((s) => relayState.removeFrameId(s, { extensionId: connectionId, frameId: frameParams.frameId }));
                         sendToPlaywright({
                             message: {
                                 sessionId,
                                 method,
-                                params
+                                params,
                             },
                             source: 'extension',
                             extensionId: connectionId,
@@ -1064,27 +1261,22 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                     else if (method === 'Page.frameNavigated') {
                         const frameParams = params;
                         if (sessionId) {
-                            const target = connection.connectedTargets.get(sessionId);
-                            if (target) {
-                                target.frameIds.add(frameParams.frame.id);
-                            }
+                            store.setState((s) => relayState.addFrameId(s, { extensionId: connectionId, sessionId, frameId: frameParams.frame.id }));
                         }
                         if (!frameParams.frame.parentId && sessionId) {
-                            const target = connection.connectedTargets.get(sessionId);
-                            if (target) {
-                                target.targetInfo = {
-                                    ...target.targetInfo,
-                                    url: frameParams.frame.url,
-                                    title: frameParams.frame.name || target.targetInfo.title,
-                                };
-                                logger?.log(pc.magenta('[Server] Updated target URL from Page.frameNavigated:'), frameParams.frame.url);
-                            }
+                            store.setState((s) => relayState.updateTargetUrl(s, {
+                                extensionId: connectionId,
+                                sessionId,
+                                url: frameParams.frame.url,
+                                title: frameParams.frame.name || undefined,
+                            }));
+                            logger?.log(pc.magenta('[Server] Updated target URL from Page.frameNavigated:'), frameParams.frame.url);
                         }
                         sendToPlaywright({
                             message: {
                                 sessionId,
                                 method,
-                                params
+                                params,
                             },
                             source: 'extension',
                             extensionId: connectionId,
@@ -1093,20 +1285,14 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                     else if (method === 'Page.navigatedWithinDocument') {
                         const navParams = params;
                         if (sessionId) {
-                            const target = connection.connectedTargets.get(sessionId);
-                            if (target) {
-                                target.targetInfo = {
-                                    ...target.targetInfo,
-                                    url: navParams.url,
-                                };
-                                logger?.log(pc.magenta('[Server] Updated target URL from Page.navigatedWithinDocument:'), navParams.url);
-                            }
+                            store.setState((s) => relayState.updateTargetUrl(s, { extensionId: connectionId, sessionId, url: navParams.url }));
+                            logger?.log(pc.magenta('[Server] Updated target URL from Page.navigatedWithinDocument:'), navParams.url);
                         }
                         sendToPlaywright({
                             message: {
                                 sessionId,
                                 method,
-                                params
+                                params,
                             },
                             source: 'extension',
                             extensionId: connectionId,
@@ -1117,7 +1303,7 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                             message: {
                                 sessionId,
                                 method,
-                                params
+                                params,
                             },
                             source: 'extension',
                             extensionId: connectionId,
@@ -1125,10 +1311,9 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                     }
                 }
             },
-            onClose(event, ws) {
+            onClose(event) {
                 logger?.log(`Extension disconnected: code=${event.code} reason=${event.reason || 'none'} (${connectionId})`);
-                stopExtensionPing(connectionId);
-                // Cancel any active recordings BEFORE removing connection (cancelRecording checks isExtensionConnected)
+                // Cancel recordings BEFORE removing extension state (cancelRecording checks isExtensionConnected)
                 const recordingRelay = recordingRelays.get(connectionId);
                 if (recordingRelay) {
                     recordingRelay.cancelRecording({}).catch(() => {
@@ -1136,32 +1321,50 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                     });
                 }
                 recordingRelays.delete(connectionId);
-                const connection = extensionConnections.get(connectionId);
-                if (connection) {
-                    for (const pending of connection.pendingRequests.values()) {
+                // Reject all pending I/O requests (state cleanup happens in removeExtension below)
+                const closingExt = store.getState().extensions.get(connectionId);
+                if (closingExt) {
+                    stopExtensionPing(connectionId);
+                    for (const pending of closingExt.pendingRequests.values()) {
                         pending.reject(new Error('Extension connection closed'));
                     }
-                    connection.pendingRequests.clear();
-                    connection.connectedTargets.clear();
                 }
-                if (connection) {
-                    const mappedId = extensionKeyIndex.get(connection.stableKey);
-                    if (mappedId === connectionId) {
-                        extensionKeyIndex.delete(connection.stableKey);
-                    }
+                const currentRelayState = store.getState();
+                const closingExtension = currentRelayState.extensions.get(connectionId);
+                const successorCandidates = closingExtension
+                    ? Array.from(currentRelayState.extensions.values())
+                        .reverse()
+                        .filter((ext) => {
+                        return ext.id !== connectionId && ext.stableKey === closingExtension.stableKey && Boolean(ext.ws);
+                    })
+                    : [];
+                const successorExtension = closingExtension
+                    ? successorCandidates[0]
+                    : undefined;
+                if (successorExtension) {
+                    logger?.log(pc.yellow(`Rebinding clients from ${connectionId} to ${successorExtension.id} (stableKey: ${successorExtension.stableKey})`));
+                    store.setState((s) => {
+                        return relayState.rebindClientsToExtension(s, {
+                            fromExtensionId: connectionId,
+                            toExtensionId: successorExtension.id,
+                        });
+                    });
                 }
-                extensionConnections.delete(connectionId);
-                for (const [clientId, client] of playwrightClients.entries()) {
-                    if (client.extensionId !== connectionId) {
-                        continue;
+                // Close playwright clients bound to this extension when no successor exists.
+                if (!successorExtension) {
+                    const { playwrightClients } = store.getState();
+                    for (const client of playwrightClients.values()) {
+                        if (client.extensionId === connectionId) {
+                            client.ws.close(1000, 'Extension disconnected');
+                        }
                     }
-                    client.ws.close(1000, 'Extension disconnected');
-                    playwrightClients.delete(clientId);
                 }
+                // State transition: remove extension + its bound clients atomically
+                store.setState((s) => relayState.removeExtension(s, { extensionId: connectionId }));
             },
             onError(event) {
                 logger?.error('Extension WebSocket error:', event);
-            }
+            },
         };
     }));
     // ============================================================================
@@ -1233,7 +1436,7 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
     app.use('/recording/*', privilegedRouteMiddleware);
     app.post('/cli/execute', async (c) => {
         try {
-            const body = await c.req.json();
+            const body = (await c.req.json());
             const sessionId = normalizeSessionId(body.sessionId);
             const { code, timeout = 10000 } = body;
             if (!sessionId || !code) {
@@ -1254,7 +1457,7 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
     });
     app.post('/cli/reset', async (c) => {
         try {
-            const body = await c.req.json();
+            const body = (await c.req.json());
             const sessionId = normalizeSessionId(body.sessionId);
             if (!sessionId) {
                 return c.json({ error: 'sessionId is required' }, 400);
@@ -1284,13 +1487,13 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
         return c.json({ next: nextSessionNumber });
     });
     app.post('/cli/session/new', async (c) => {
-        const body = await c.req.json().catch(() => ({}));
+        const body = (await c.req.json().catch(() => ({})));
         const sessionId = String(nextSessionNumber++);
         const extensionId = body.extensionId || null;
         const cwd = body.cwd;
-        const allowDefault = !extensionId && extensionConnections.size === 1;
-        const extension = getExtensionConnection(extensionId, { allowFallback: allowDefault });
-        if (!extension) {
+        const allowDefault = !extensionId && store.getState().extensions.size === 1;
+        const conn = getExtensionConnection(extensionId, { allowFallback: allowDefault });
+        if (!conn) {
             const error = extensionId
                 ? `Extension not connected: ${extensionId}`
                 : 'Multiple extensions connected. Specify extensionId.';
@@ -1301,9 +1504,9 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
             sessionId,
             cwd,
             sessionMetadata: {
-                extensionId: extension.stableKey,
-                browser: extension.info.browser || null,
-                profile: extension.info ? { email: extension.info.email || '', id: extension.info.id || '' } : null,
+                extensionId: conn.stableKey,
+                browser: conn.info.browser || null,
+                profile: conn.info ? { email: conn.info.email || '', id: conn.info.id || '' } : null,
             },
         });
         const metadata = executor.getSessionMetadata();
@@ -1331,7 +1534,7 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
     });
     app.post('/cli/session/delete', async (c) => {
         try {
-            const body = await c.req.json();
+            const body = (await c.req.json());
             const sessionId = normalizeSessionId(body.sessionId);
             if (!sessionId) {
                 return c.json({ error: 'sessionId is required' }, 400);
@@ -1352,70 +1555,54 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
     // Recording Endpoints - For screen recording via chrome.tabCapture
     // ============================================================================
     app.post('/recording/start', async (c) => {
-        const body = await c.req.json();
+        const body = (await c.req.json());
         const sessionId = normalizeSessionId(body.sessionId);
         const { sessionId: _sessionId, ...recordingOptions } = body;
-        const manager = await getExecutorManager();
-        const executor = sessionId ? manager.getSession(sessionId) : null;
-        if (sessionId && !executor) {
-            return c.json({ success: false, error: `Session ${sessionId} not found` }, 404);
-        }
-        const extensionId = executor?.getSessionMetadata().extensionId || null;
+        const { extensionId, sessionId: resolvedSessionId } = await resolveRecordingRoute({ sessionId });
         const relay = getRecordingRelay(extensionId);
         if (!relay) {
             return c.json({ success: false, error: 'Extension not connected' }, 500);
         }
-        const recordingParams = (sessionId ? { ...recordingOptions, sessionId } : recordingOptions);
+        const recordingParams = (resolvedSessionId
+            ? { ...recordingOptions, sessionId: resolvedSessionId }
+            : recordingOptions);
         const result = await relay.startRecording(recordingParams);
-        const status = result.success ? 200 : (result.error?.includes('required') ? 400 : 500);
+        const status = result.success ? 200 : result.error?.includes('required') ? 400 : 500;
         return c.json(result, status);
     });
     app.post('/recording/stop', async (c) => {
-        const body = await c.req.json();
+        const body = (await c.req.json());
         const sessionId = normalizeSessionId(body.sessionId);
-        const manager = await getExecutorManager();
-        const executor = sessionId ? manager.getSession(sessionId) : null;
-        if (sessionId && !executor) {
-            return c.json({ success: false, error: `Session ${sessionId} not found` }, 404);
-        }
-        const extensionId = executor?.getSessionMetadata().extensionId || null;
+        const { extensionId, sessionId: resolvedSessionId } = await resolveRecordingRoute({ sessionId });
         const relay = getRecordingRelay(extensionId);
         if (!relay) {
             return c.json({ success: false, error: 'Extension not connected' }, 500);
         }
-        const stopParams = sessionId ? { sessionId } : {};
+        const stopParams = resolvedSessionId ? { sessionId: resolvedSessionId } : {};
         const result = await relay.stopRecording(stopParams);
-        const status = result.success ? 200 : (result.error?.includes('not found') ? 404 : 500);
+        const status = result.success ? 200 : result.error?.includes('not found') ? 404 : 500;
         return c.json(result, status);
     });
     app.get('/recording/status', async (c) => {
         const sessionId = normalizeSessionId(c.req.query('sessionId'));
-        const normalizedSessionId = sessionId || undefined;
-        const manager = await getExecutorManager();
-        const executor = normalizedSessionId ? manager.getSession(normalizedSessionId) : null;
-        const extensionId = executor?.getSessionMetadata().extensionId || null;
+        const { extensionId, sessionId: resolvedSessionId } = await resolveRecordingRoute({ sessionId });
         const relay = getRecordingRelay(extensionId);
         if (!relay) {
             return c.json({ isRecording: false });
         }
-        const isRecordingParams = normalizedSessionId ? { sessionId: normalizedSessionId } : {};
+        const isRecordingParams = resolvedSessionId ? { sessionId: resolvedSessionId } : {};
         const result = await relay.isRecording(isRecordingParams);
         return c.json(result);
     });
     app.post('/recording/cancel', async (c) => {
-        const body = await c.req.json();
+        const body = (await c.req.json());
         const sessionId = normalizeSessionId(body.sessionId);
-        const manager = await getExecutorManager();
-        const executor = sessionId ? manager.getSession(sessionId) : null;
-        if (sessionId && !executor) {
-            return c.json({ success: false, error: `Session ${sessionId} not found` }, 404);
-        }
-        const extensionId = executor?.getSessionMetadata().extensionId || null;
+        const { extensionId, sessionId: resolvedSessionId } = await resolveRecordingRoute({ sessionId });
         const relay = getRecordingRelay(extensionId);
         if (!relay) {
             return c.json({ success: false, error: 'Extension not connected' }, 500);
         }
-        const cancelParams = sessionId ? { sessionId } : {};
+        const cancelParams = resolvedSessionId ? { sessionId: resolvedSessionId } : {};
         const result = await relay.cancelRecording(cancelParams);
         return c.json(result);
     });
@@ -1431,14 +1618,21 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
     logger?.log('CDP endpoint:', cdpEndpoint);
     return {
         close() {
+            const { extensions, playwrightClients } = store.getState();
             for (const client of playwrightClients.values()) {
                 client.ws.close(1000, 'Server stopped');
             }
-            playwrightClients.clear();
-            for (const extension of extensionConnections.values()) {
-                extension.ws.close(1000, 'Server stopped');
+            for (const ext of extensions.values()) {
+                if (ext.pingInterval) {
+                    clearInterval(ext.pingInterval);
+                }
+                ext.ws?.close(1000, 'Server stopped');
             }
-            extensionConnections.clear();
+            // Reset store state
+            store.setState({
+                extensions: new Map(),
+                playwrightClients: new Map(),
+            });
             server.close();
             emitter.removeAllListeners();
         },
@@ -1447,7 +1641,7 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
         },
         off(event, listener) {
             emitter.off(event, listener);
-        }
+        },
     };
 }
 //# sourceMappingURL=cdp-relay.js.map