@mozilla/firefox-devtools-mcp-moz 0.10.0 → 0.10.1

package/dist.moz/index.js

@@ -14841,7 +14841,7 @@ var init_constants = __esm({
   "src/config/constants.ts"() {
     "use strict";
     SERVER_NAME = true ? "@mozilla/firefox-devtools-mcp" : "firefox-devtools";
-    SERVER_VERSION = true ? "0.10.0" : "dev";
+    SERVER_VERSION = true ? "0.10.1" : "dev";
   }
 });
 
@@ -15348,68 +15348,6 @@ var init_core3 = __esm({
       getOptions() {
         return this.options;
       }
-      /**
-       * Wait for WebSocket to be in OPEN state
-       */
-      async waitForWebSocketOpen(ws, timeout = 5e3) {
-        if (ws.readyState === 1) {
-          return;
-        }
-        if (ws.readyState === 0) {
-          return new Promise((resolve4, reject) => {
-            const timeoutId = setTimeout(() => {
-              ws.off("open", onOpen);
-              reject(new Error("Timeout waiting for WebSocket to open"));
-            }, timeout);
-            const onOpen = () => {
-              clearTimeout(timeoutId);
-              ws.off("open", onOpen);
-              resolve4();
-            };
-            ws.on("open", onOpen);
-          });
-        }
-        throw new Error(`WebSocket is not open: readyState ${ws.readyState}`);
-      }
-      /**
-       * Send raw BiDi command and get response
-       */
-      async sendBiDiCommand(method, params = {}) {
-        if (!this.driver) {
-          throw new Error("Driver not connected");
-        }
-        const bidi = await this.driver.getBidi();
-        const ws = bidi.socket;
-        await this.waitForWebSocketOpen(ws);
-        const id = Math.floor(Math.random() * 1e6);
-        return new Promise((resolve4, reject) => {
-          const messageHandler = (data) => {
-            try {
-              const payload = JSON.parse(data.toString());
-              if (payload.id === id) {
-                ws.off("message", messageHandler);
-                if (payload.error) {
-                  reject(new Error(`BiDi error: ${JSON.stringify(payload.error)}`));
-                } else {
-                  resolve4(payload.result);
-                }
-              }
-            } catch {
-            }
-          };
-          ws.on("message", messageHandler);
-          const command = {
-            id,
-            method,
-            params
-          };
-          ws.send(JSON.stringify(command));
-          setTimeout(() => {
-            ws.off("message", messageHandler);
-            reject(new Error(`BiDi command timeout: ${method}`));
-          }, 1e4);
-        });
-      }
       /**
        * Close driver and cleanup.
        * - Tries graceful quit() with a timeout; on timeout, force-kills via onQuit_().
@@ -15479,6 +15417,107 @@ var init_core3 = __esm({
   }
 });
 
+// src/firefox/bidi.ts
+import EventEmitter from "events";
+var BiDiFacade;
+var init_bidi = __esm({
+  "src/firefox/bidi.ts"() {
+    "use strict";
+    init_logger();
+    BiDiFacade = class extends EventEmitter {
+      constructor(driver) {
+        super();
+        this.driver = driver;
+      }
+      listening = false;
+      nextCommandId = 1;
+      async subscribe(events) {
+        const bidi = await this.driver.getBidi();
+        if (!this.listening) {
+          this.listenForEvents(bidi.socket);
+          this.listening = true;
+        }
+        await bidi.subscribe(events);
+      }
+      async sendCommand(method, params = {}) {
+        const bidi = await this.driver.getBidi();
+        const ws = bidi.socket;
+        await this.waitForWebSocketOpen(ws);
+        const id = this.nextCommandId++;
+        return new Promise((resolve4, reject) => {
+          const messageHandler = (data) => {
+            try {
+              const payload = JSON.parse(data.toString());
+              if (payload.id === id) {
+                ws.off("message", messageHandler);
+                if (payload.error) {
+                  reject(new Error(`BiDi error: ${JSON.stringify(payload.error)}`));
+                } else {
+                  resolve4(payload.result);
+                }
+              }
+            } catch {
+            }
+          };
+          ws.on("message", messageHandler);
+          const command = {
+            id,
+            method,
+            params
+          };
+          ws.send(JSON.stringify(command));
+          setTimeout(() => {
+            ws.off("message", messageHandler);
+            reject(new Error(`BiDi command timeout: ${method}`));
+          }, 1e4);
+        });
+      }
+      listenForEvents(ws) {
+        ws.on("message", (data) => {
+          let payload;
+          try {
+            payload = JSON.parse(data.toString());
+          } catch {
+            return;
+          }
+          if (payload?.type === "event" && payload.method) {
+            try {
+              this.emit(payload.method, payload.params);
+            } catch (error2) {
+              logDebug(
+                `Error emitting ${payload.method} event: ${error2 instanceof Error ? error2.message : String(error2)}`
+              );
+            }
+          }
+        });
+      }
+      /**
+       * Wait for WebSocket to be in OPEN state
+       */
+      async waitForWebSocketOpen(ws, timeout = 5e3) {
+        if (ws.readyState === 1) {
+          return;
+        }
+        if (ws.readyState === 0) {
+          return new Promise((resolve4, reject) => {
+            const timeoutId = setTimeout(() => {
+              ws.off("open", onOpen);
+              reject(new Error("Timeout waiting for WebSocket to open"));
+            }, timeout);
+            const onOpen = () => {
+              clearTimeout(timeoutId);
+              ws.off("open", onOpen);
+              resolve4();
+            };
+            ws.on("open", onOpen);
+          });
+        }
+        throw new Error(`WebSocket is not open: readyState ${ws.readyState}`);
+      }
+    };
+  }
+});
+
 // src/utils/remote-value.ts
 function remoteValueToNative(rv) {
   if (!rv || typeof rv !== "object") {
@@ -15549,8 +15588,8 @@ var init_console = __esm({
     MAX_CONSOLE_MESSAGES = 1e3;
     CONSOLE_TTL_MS = 5 * 60 * 1e3;
     ConsoleEvents = class {
-      constructor(driver, options = {}) {
-        this.driver = driver;
+      constructor(bidi, options = {}) {
+        this.bidi = bidi;
         this.options = {
           autoClearOnNavigate: false,
           // Changed default to false to preserve logs across tabs
@@ -15563,44 +15602,27 @@ var init_console = __esm({
       /**
        * Subscribe to BiDi console events and navigation lifecycle
        */
-      async subscribe(contextId) {
+      async subscribe() {
         if (this.subscribed) {
           return;
         }
-        const bidi = await this.driver.getBidi();
-        await bidi.subscribe("log.entryAdded", contextId ? [contextId] : void 0);
-        try {
-          await bidi.subscribe("browsingContext.load", contextId ? [contextId] : void 0);
-          await bidi.subscribe("browsingContext.domContentLoaded", contextId ? [contextId] : void 0);
-        } catch {
-          logDebug(
-            "Navigation events subscription skipped (may not be available in this Firefox version)"
-          );
-        }
-        const ws = bidi.socket;
-        ws.on("message", (data) => {
-          try {
-            const payload = JSON.parse(data.toString());
-            if (payload?.method === "log.entryAdded") {
-              const entry = payload.params;
-              const message = {
-                level: entry.level || "info",
-                text: entry.text || (entry.args ? JSON.stringify(entry.args) : ""),
-                timestamp: entry.timestamp || Date.now(),
-                source: entry.source?.realm,
-                args: entry.args
-              };
-              this.consoleMessages.push(message);
-              logDebug(`Console [${message.level}]: ${message.text}`);
-            }
-            if (payload?.method === "browsingContext.load" || payload?.method === "browsingContext.domContentLoaded") {
-              if (this.options.autoClearOnNavigate) {
-                this.clearMessages();
-              }
-            }
-          } catch {
-          }
+        await this.bidi.subscribe("log.entryAdded");
+        await this.bidi.subscribe(["browsingContext.load", "browsingContext.domContentLoaded"]);
+        this.bidi.on("log.entryAdded", (entry) => {
+          const message = {
+            level: entry.level || "info",
+            text: entry.text || (entry.args ? JSON.stringify(entry.args) : ""),
+            timestamp: entry.timestamp || Date.now(),
+            source: entry.source?.realm,
+            args: entry.args
+          };
+          this.consoleMessages.push(message);
+          logDebug(`Console [${message.level}]: ${message.text}`);
         });
+        if (this.options.autoClearOnNavigate) {
+          this.bidi.on("browsingContext.load", () => this.clearMessages());
+          this.bidi.on("browsingContext.domContentLoaded", () => this.clearMessages());
+        }
         this.subscribed = true;
         logDebug("Console listener active with lifecycle hooks");
       }
@@ -15648,9 +15670,8 @@ var init_network = __esm({
     NETWORK_TTL_MS = 5 * 60 * 1e3;
     MAX_ENCODED_DATA_SIZE = 10 * 1e3 * 1e3;
     NetworkEvents = class {
-      constructor(driver, options = {}, sendCommand) {
-        this.driver = driver;
-        this.sendCommand = sendCommand;
+      constructor(bidi, options = {}) {
+        this.bidi = bidi;
         this.options = {
           autoClearOnNavigate: true,
           ...options
@@ -15666,90 +15687,81 @@ var init_network = __esm({
        * Subscribe to BiDi network events and navigation lifecycle
        * Enables monitoring by default (always-on capture)
        */
-      async subscribe(contextId) {
+      async subscribe() {
         if (this.subscribed) {
           return;
         }
-        const bidi = await this.driver.getBidi();
-        await bidi.subscribe("network.beforeRequestSent", contextId ? [contextId] : void 0);
-        await bidi.subscribe("network.responseStarted", contextId ? [contextId] : void 0);
-        await bidi.subscribe("network.responseCompleted", contextId ? [contextId] : void 0);
-        try {
-          await bidi.subscribe("browsingContext.load", contextId ? [contextId] : void 0);
-          await bidi.subscribe("browsingContext.domContentLoaded", contextId ? [contextId] : void 0);
-        } catch {
-          logDebug(
-            "Navigation events subscription skipped (may not be available in this Firefox version)"
-          );
-        }
-        const ws = bidi.socket;
-        ws.on("message", (data) => {
-          try {
-            const payload = JSON.parse(data.toString());
-            if (payload?.method === "browsingContext.load" || payload?.method === "browsingContext.domContentLoaded") {
-              if (this.enabled && this.options.autoClearOnNavigate) {
-                this.clearRequests();
-              }
-              return;
-            }
-            if (!this.enabled) {
-              return;
-            }
-            if (payload?.method === "network.beforeRequestSent") {
-              const req = payload.params;
-              const requestId = req.request?.request || req.requestId;
-              if (!requestId) {
-                return;
-              }
-              this.requestStartTimes.set(requestId, Date.now());
-              const record2 = {
-                id: requestId,
-                url: req.request?.url || "",
-                method: req.request?.method || "GET",
-                timestamp: Date.now(),
-                resourceType: this.guessResourceType(req.request?.url || ""),
-                isXHR: req.initiator?.type === "xmlhttprequest" || req.initiator?.type === "fetch",
-                requestHeaders: this.parseHeaders(req.request?.headers || []),
-                timings: {
-                  requestTime: Date.now()
-                }
-              };
-              this.networkRecords.set(requestId, record2);
-              logDebug(`Network request [${record2.method}]: ${record2.url}`);
-            }
-            if (payload?.method === "network.responseStarted") {
-              const resp = payload.params;
-              const requestId = resp.request?.request || resp.requestId;
-              if (!requestId) {
-                return;
-              }
-              const existing = this.networkRecords.get(requestId);
-              if (existing) {
-                existing.status = resp.response?.status;
-                existing.statusText = resp.response?.statusText || "";
-                existing.responseHeaders = this.parseHeaders(resp.response?.headers || []);
-              }
+        await this.bidi.subscribe([
+          "network.beforeRequestSent",
+          "network.responseStarted",
+          "network.responseCompleted"
+        ]);
+        await this.bidi.subscribe(["browsingContext.load", "browsingContext.domContentLoaded"]);
+        const onLoadEvent = () => {
+          if (this.enabled && this.options.autoClearOnNavigate) {
+            this.clearRequests();
+          }
+        };
+        this.bidi.on("browsingContext.domContentLoaded", onLoadEvent);
+        this.bidi.on("browsingContext.load", onLoadEvent);
+        this.bidi.on("network.beforeRequestSent", (req) => {
+          if (!this.enabled) {
+            return;
+          }
+          const requestId = req.request?.request || req.requestId;
+          if (!requestId) {
+            return;
+          }
+          this.requestStartTimes.set(requestId, Date.now());
+          const record2 = {
+            id: requestId,
+            url: req.request?.url || "",
+            method: req.request?.method || "GET",
+            timestamp: Date.now(),
+            resourceType: this.guessResourceType(req.request?.url || ""),
+            isXHR: req.initiator?.type === "xmlhttprequest" || req.initiator?.type === "fetch",
+            requestHeaders: this.parseHeaders(req.request?.headers || []),
+            timings: {
+              requestTime: Date.now()
             }
-            if (payload?.method === "network.responseCompleted") {
-              const resp = payload.params;
-              const requestId = resp.request?.request || resp.requestId;
-              if (!requestId) {
-                return;
-              }
-              const existing = this.networkRecords.get(requestId);
-              const startTime = this.requestStartTimes.get(requestId);
-              if (existing && startTime) {
-                existing.timings.responseTime = Date.now();
-                existing.timings.duration = Date.now() - startTime;
-                if (!existing.status && resp.response?.status) {
-                  existing.status = resp.response.status;
-                  existing.statusText = resp.response.statusText || "";
-                }
-              }
-              this.requestStartTimes.delete(requestId);
+          };
+          this.networkRecords.set(requestId, record2);
+          logDebug(`Network request [${record2.method}]: ${record2.url}`);
+        });
+        this.bidi.on("network.responseStarted", (resp) => {
+          if (!this.enabled) {
+            return;
+          }
+          const requestId = resp.request?.request || resp.requestId;
+          if (!requestId) {
+            return;
+          }
+          const existing = this.networkRecords.get(requestId);
+          if (existing) {
+            existing.status = resp.response?.status;
+            existing.statusText = resp.response?.statusText || "";
+            existing.responseHeaders = this.parseHeaders(resp.response?.headers || []);
+          }
+        });
+        this.bidi.on("network.responseCompleted", (resp) => {
+          if (!this.enabled) {
+            return;
+          }
+          const requestId = resp.request?.request || resp.requestId;
+          if (!requestId) {
+            return;
+          }
+          const existing = this.networkRecords.get(requestId);
+          const startTime = this.requestStartTimes.get(requestId);
+          if (existing && startTime) {
+            existing.timings.responseTime = Date.now();
+            existing.timings.duration = Date.now() - startTime;
+            if (!existing.status && resp.response?.status) {
+              existing.status = resp.response.status;
+              existing.statusText = resp.response.statusText || "";
             }
-          } catch {
           }
+          this.requestStartTimes.delete(requestId);
         });
         await this.registerDataCollector();
         this.subscribed = true;
@@ -15765,11 +15777,8 @@ var init_network = __esm({
           logDebug("Network body capture disabled, skipping data collector registration");
           return;
         }
-        if (!this.sendCommand) {
-          return;
-        }
         try {
-          const result = await this.sendCommand("network.addDataCollector", {
+          const result = await this.bidi.sendCommand("network.addDataCollector", {
             dataTypes: ["request", "response"],
             maxEncodedDataSize: MAX_ENCODED_DATA_SIZE
           });
@@ -15789,11 +15798,11 @@ var init_network = __esm({
        * when the body was never collected, evicted, or the browser lacks support.
        */
       async fetchBody(requestId, dataType) {
-        if (!this.sendCommand || !this.collectorId) {
+        if (!this.collectorId) {
           return { ok: false, reason: "unsupported" };
         }
         try {
-          const result = await this.sendCommand("network.getData", {
+          const result = await this.bidi.sendCommand("network.getData", {
             request: requestId,
             dataType
           });
@@ -15975,46 +15984,35 @@ var init_debugging = __esm({
     init_logger();
     MAX_LOGPOINT_RESULTS = 100;
     DebuggingEvents = class {
-      constructor(driver, sendBiDiCommand) {
-        this.driver = driver;
-        this.sendBiDiCommand = sendBiDiCommand;
+      constructor(bidi) {
+        this.bidi = bidi;
       }
       logpoints = /* @__PURE__ */ new Map();
       subscribed = false;
       /**
        * Subscribe to moz:debugging events
        */
-      async subscribe(contextId) {
+      async subscribe() {
         if (this.subscribed) {
           return;
         }
-        const bidi = await this.driver.getBidi();
         try {
-          await bidi.subscribe("moz:debugging.paused", contextId ? [contextId] : void 0);
-          await bidi.subscribe("moz:debugging.resumed", contextId ? [contextId] : void 0);
+          await this.bidi.subscribe(["moz:debugging.paused", "moz:debugging.resumed"]);
         } catch {
           logDebug(
             "Debugging events subscription skipped (may not be available in this Firefox version)"
           );
         }
-        const ws = bidi.socket;
-        ws.on("message", (data) => {
-          try {
-            const payload = JSON.parse(data.toString());
-            if (payload?.method === "moz:debugging.paused") {
-              const { context, url, line, column } = payload.params;
-              const logpointId = this.findLogpointByLocation(url, line);
-              if (logpointId) {
-                void this.handleLogpointPause(context, logpointId);
-                return;
-              }
-              logDebug(`moz:Debugging paused in context: ${context} at ${url}:${line}:${column}`);
-            }
-            if (payload?.method === "moz:debugging.resumed") {
-              logDebug(`moz:Debugging resumed in context: ${payload.params.context}`);
-            }
-          } catch {
+        this.bidi.on("moz:debugging.paused", ({ context, url, line, column }) => {
+          const logpointId = this.findLogpointByLocation(url, line);
+          if (logpointId) {
+            void this.handleLogpointPause(context, logpointId);
+            return;
           }
+          logDebug(`moz:Debugging paused in context: ${context} at ${url}:${line}:${column}`);
+        });
+        this.bidi.on("moz:debugging.resumed", (entry) => {
+          logDebug(`moz:Debugging resumed in context: ${entry.context}`);
         });
         this.subscribed = true;
         logDebug("moz:debugging listener active");
@@ -16048,7 +16046,7 @@ var init_debugging = __esm({
         }
         logDebug(`Logpoint hit: ${logpointId} in context ${contextId}`);
         try {
-          const result = await this.sendBiDiCommand("script.evaluate", {
+          const result = await this.bidi.sendCommand("script.evaluate", {
             expression: entry.expression,
             target: { context: contextId },
             awaitPromise: false
@@ -16080,7 +16078,7 @@ var init_debugging = __esm({
               logDebug(`Logpoint ${logpointId}: result buffer capped at ${MAX_LOGPOINT_RESULTS}`);
             }
           }
-          await this.sendBiDiCommand("moz:debugging.resume", { context: contextId }).catch((err) => {
+          await this.bidi.sendCommand("moz:debugging.resume", { context: contextId }).catch((err) => {
             logDebug(`Failed to resume after logpoint: ${String(err)}`);
           });
         }
@@ -16098,8 +16096,8 @@ var init_downloads = __esm({
     MAX_DOWNLOADS = 500;
     DOWNLOAD_TTL_MS = 30 * 60 * 1e3;
     DownloadEvents = class {
-      constructor(driver) {
-        this.driver = driver;
+      constructor(bidi) {
+        this.bidi = bidi;
       }
       downloads = /* @__PURE__ */ new Map();
       subscribed = false;
@@ -16111,65 +16109,53 @@ var init_downloads = __esm({
       /**
        * Subscribe to BiDi download events.
        */
-      async subscribe(contextId) {
+      async subscribe() {
         if (this.subscribed) {
           return;
         }
-        const bidi = await this.driver.getBidi();
-        const contexts = contextId ? [contextId] : void 0;
-        await bidi.subscribe("browsingContext.downloadWillBegin", contexts);
-        await bidi.subscribe("browsingContext.downloadEnd", contexts);
-        const ws = bidi.socket;
-        ws.on("message", (data) => {
-          try {
-            const payload = JSON.parse(data.toString());
-            if (payload?.method === "browsingContext.downloadWillBegin") {
-              const p = payload.params;
-              let key = p.download ?? p.navigation;
-              if (!key) {
-                key = `download-${this.fallbackCounter++}`;
-                this.pendingFallbackKey = key;
-              }
-              this.downloads.set(key, {
-                id: key,
-                context: p.context,
-                navigation: p.navigation ?? null,
-                url: p.url || "",
-                suggestedFilename: p.suggestedFilename || "",
-                status: "in_progress",
-                startTimestamp: p.timestamp ?? Date.now()
-              });
-              logDebug(`Download started: filename=${p.suggestedFilename}, url=${p.url}, id=${key}`);
-            }
-            if (payload?.method === "browsingContext.downloadEnd") {
-              const p = payload.params;
-              let key = p?.download ?? p?.navigation;
-              if (!key) {
-                key = this.pendingFallbackKey ?? `download-${this.fallbackCounter++}`;
-                this.pendingFallbackKey = null;
-              }
-              const existing = this.downloads.get(key) ?? {
-                id: key,
-                context: p.context,
-                navigation: p.navigation ?? null,
-                url: p.url || "",
-                suggestedFilename: "",
-                status: "in_progress",
-                startTimestamp: p.timestamp ?? Date.now()
-              };
-              existing.status = p.status;
-              existing.endTimestamp = p.timestamp ?? Date.now();
-              existing.durationMs = existing.endTimestamp - existing.startTimestamp;
-              if (p.status === "complete" && p.filepath) {
-                existing.filepath = p.filepath;
-              }
-              this.downloads.set(key, existing);
-              logDebug(
-                `Download ${p.status}: filepath=${existing.filepath}, url=${existing.url}, id=${key}`
-              );
-            }
-          } catch {
+        await this.bidi.subscribe(["browsingContext.downloadWillBegin", "browsingContext.downloadEnd"]);
+        this.bidi.on("browsingContext.downloadWillBegin", (p) => {
+          let key = p.download ?? p.navigation;
+          if (!key) {
+            key = `download-${this.fallbackCounter++}`;
+            this.pendingFallbackKey = key;
+          }
+          this.downloads.set(key, {
+            id: key,
+            context: p.context,
+            navigation: p.navigation ?? null,
+            url: p.url || "",
+            suggestedFilename: p.suggestedFilename || "",
+            status: "in_progress",
+            startTimestamp: p.timestamp ?? Date.now()
+          });
+          logDebug(`Download started: filename=${p.suggestedFilename}, url=${p.url}, id=${key}`);
+        });
+        this.bidi.on("browsingContext.downloadEnd", (p) => {
+          let key = p?.download ?? p?.navigation;
+          if (!key) {
+            key = this.pendingFallbackKey ?? `download-${this.fallbackCounter++}`;
+            this.pendingFallbackKey = null;
+          }
+          const existing = this.downloads.get(key) ?? {
+            id: key,
+            context: p.context,
+            navigation: p.navigation ?? null,
+            url: p.url || "",
+            suggestedFilename: "",
+            status: "in_progress",
+            startTimestamp: p.timestamp ?? Date.now()
+          };
+          existing.status = p.status;
+          existing.endTimestamp = p.timestamp ?? Date.now();
+          existing.durationMs = existing.endTimestamp - existing.startTimestamp;
+          if (p.status === "complete" && p.filepath) {
+            existing.filepath = p.filepath;
           }
+          this.downloads.set(key, existing);
+          logDebug(
+            `Download ${p.status}: filepath=${existing.filepath}, url=${existing.url}, id=${key}`
+          );
         });
         this.subscribed = true;
         logDebug("Download listener ready");
@@ -17052,6 +17038,7 @@ var init_firefox = __esm({
   "src/firefox/index.ts"() {
     "use strict";
     init_core3();
+    init_bidi();
     init_logger();
     init_remote_value();
     init_events();
@@ -17060,6 +17047,7 @@ var init_firefox = __esm({
     init_snapshot();
     FirefoxClient = class {
       core;
+      bidi = null;
       consoleEvents = null;
       networkEvents = null;
       debuggingEvents = null;
@@ -17070,31 +17058,52 @@ var init_firefox = __esm({
       constructor(options) {
         this.core = new FirefoxCore(options);
       }
+      getBidi() {
+        if (!this.bidi) {
+          throw new Error("Not connected");
+        }
+        return this.bidi;
+      }
       /**
        * Connect and initialize all modules
        */
       async connect() {
         await this.core.connect();
         const driver = this.core.getDriver();
+        this.bidi = new BiDiFacade(driver);
         this.snapshot = new SnapshotManager(driver);
-        const hasBidi = "getBidi" in driver && typeof driver.getBidi === "function";
-        if (hasBidi) {
-          this.consoleEvents = new ConsoleEvents(driver, {
-            autoClearOnNavigate: false
-          });
-          this.networkEvents = new NetworkEvents(
-            driver,
-            {
-              autoClearOnNavigate: false,
-              captureBodies: this.core.getOptions().captureNetworkBodies !== false
-            },
-            (method, params) => this.core.sendBiDiCommand(method, params ?? {})
-          );
-          this.debuggingEvents = new DebuggingEvents(
-            driver,
-            (method, params) => this.core.sendBiDiCommand(method, params)
-          );
-          this.downloadEvents = new DownloadEvents(driver);
+        this.consoleEvents = new ConsoleEvents(this.bidi, {
+          autoClearOnNavigate: false
+        });
+        try {
+          await this.consoleEvents.subscribe();
+        } catch {
+          logDebug("Unable to subscribe to console events");
+          this.consoleEvents = null;
+        }
+        this.networkEvents = new NetworkEvents(this.bidi, {
+          autoClearOnNavigate: false,
+          captureBodies: this.core.getOptions().captureNetworkBodies !== false
+        });
+        try {
+          await this.networkEvents.subscribe();
+        } catch {
+          logDebug("Unable to subscribe to network events");
+          this.networkEvents = null;
+        }
+        this.debuggingEvents = new DebuggingEvents(this.bidi);
+        try {
+          await this.debuggingEvents.subscribe();
+        } catch {
+          logDebug("Unable to subscribe to debugging events");
+          this.debuggingEvents = null;
+        }
+        this.downloadEvents = new DownloadEvents(this.bidi);
+        try {
+          await this.downloadEvents.subscribe();
+        } catch {
+          logDebug("Unable to subscribe to download events");
+          this.downloadEvents = null;
         }
         this.dom = new DomInteractions(
           driver,
@@ -17104,40 +17113,8 @@ var init_firefox = __esm({
           driver,
           () => this.core.getCurrentContextId(),
           (id) => this.core.setCurrentContextId(id),
-          (method, params) => this.core.sendBiDiCommand(method, params)
+          (method, params) => this.getBidi().sendCommand(method, params)
         );
-        if (this.consoleEvents) {
-          try {
-            await this.consoleEvents.subscribe(void 0);
-          } catch {
-            logDebug("Unable to subscribe to console events");
-            this.consoleEvents = null;
-          }
-        }
-        if (this.networkEvents) {
-          try {
-            await this.networkEvents.subscribe(void 0);
-          } catch {
-            logDebug("Unable to subscribe to network events");
-            this.networkEvents = null;
-          }
-        }
-        if (this.debuggingEvents) {
-          try {
-            await this.debuggingEvents.subscribe();
-          } catch {
-            logDebug("Unable to subscribe to debugging events");
-            this.debuggingEvents = null;
-          }
-        }
-        if (this.downloadEvents) {
-          try {
-            await this.downloadEvents.subscribe(void 0);
-          } catch {
-            logDebug("Unable to subscribe to download events");
-            this.downloadEvents = null;
-          }
-        }
       }
       // ============================================================================
       // DOM / Evaluate
@@ -17149,7 +17126,7 @@ var init_firefox = __esm({
        * native value; throws on a script exception.
        */
       async evaluate(expression) {
-        const result = await this.core.sendBiDiCommand("script.evaluate", {
+        const result = await this.getBidi().sendCommand("script.evaluate", {
           expression,
           awaitPromise: true,
           target: { context: this.core.getCurrentContextId() }
@@ -17394,7 +17371,7 @@ var init_firefox = __esm({
        */
       async setDownloadBehavior(behavior) {
         const downloadBehavior = behavior === "default" ? null : behavior === "allowed" ? { type: "allowed" } : { type: "denied" };
-        await this.core.sendBiDiCommand("browser.setDownloadBehavior", { downloadBehavior });
+        await this.getBidi().sendCommand("browser.setDownloadBehavior", { downloadBehavior });
       }
       // ============================================================================
       // Snapshot
@@ -17446,7 +17423,7 @@ var init_firefox = __esm({
        * @internal
        */
       async sendBiDiCommand(method, params = {}) {
-        return await this.core.sendBiDiCommand(method, params);
+        return await this.getBidi().sendCommand(method, params);
       }
       /**
        * Get WebDriver instance (for advanced operations)
@@ -17491,7 +17468,7 @@ var init_firefox = __esm({
         if (!this.debuggingEvents) {
           throw new Error("Debugging events not available");
         }
-        const result = await this.core.sendBiDiCommand("moz:debugging.setBreakpoint", {
+        const result = await this.getBidi().sendCommand("moz:debugging.setBreakpoint", {
           location: { url, line }
         });
         const logpointId = result.breakpoint;
@@ -17505,7 +17482,7 @@ var init_firefox = __esm({
         if (!this.debuggingEvents) {
           throw new Error("Debugging events not available");
         }
-        await this.core.sendBiDiCommand("moz:debugging.removeBreakpoint", {
+        await this.getBidi().sendCommand("moz:debugging.removeBreakpoint", {
           breakpoint: logpointId
         });
         this.debuggingEvents.removeLogpoint(logpointId);
@@ -17559,11 +17536,56 @@ var init_firefox = __esm({
   }
 });
 
+// src/tools/instructions.ts
+function buildInstructions(moduleNames, toolNames) {
+  const byName = new Map(MODULES.map((m) => [m.name, m]));
+  const capabilities = moduleNames.flatMap((name) => {
+    const module17 = byName.get(name);
+    return module17 ? [`- ${module17.name}: ${module17.description}`] : [];
+  });
+  const sections = [INSTRUCTIONS_INTRO, ["Enabled capabilities:", ...capabilities].join("\n")];
+  const core = CORE_TOOLS.filter((name) => toolNames.has(name));
+  if (core.length > 0) {
+    const groups = TASK_TOOLS.flatMap(({ purpose, tools }) => {
+      const available = tools.filter((name) => toolNames.has(name));
+      return available.length > 0 ? [`${available.join(" / ")} for ${purpose}`] : [];
+    });
+    const extra = groups.length > 0 ? ` Add task-specific tools to the same search: ${groups.join(", ")}.` : "";
+    sections.push(
+      `When these tools are deferred, load the core set in one search rather than one at a time: ${core.join(", ")}.${extra}`
+    );
+  }
+  return sections.join("\n\n");
+}
+var INSTRUCTIONS_INTRO, CORE_TOOLS, TASK_TOOLS;
+var init_instructions = __esm({
+  "src/tools/instructions.ts"() {
+    "use strict";
+    init_tools();
+    INSTRUCTIONS_INTRO = [
+      "Browse and debug the web with Firefox.",
+      "Use this for any browser or web page task: opening a URL, automating a web flow,",
+      "or debugging a page (console errors, network requests, DOM state).",
+      "The task does not need to name Firefox, reach for these tools unless another",
+      "browser is explicitly requested.",
+      "Chrome-only browser tools do not control Firefox, do not assume they cover this."
+    ].join(" ");
+    CORE_TOOLS = ["list_pages", "new_page", "navigate_page", "take_snapshot", "get_page_text"];
+    TASK_TOOLS = [
+      { purpose: "interaction", tools: ["click_by_uid", "fill_by_uid", "hover_by_uid"] },
+      { purpose: "debugging", tools: ["list_console_messages", "list_network_requests"] },
+      { purpose: "visuals", tools: ["screenshot_page", "screenshot_by_uid"] },
+      { purpose: "one-off JS", tools: ["evaluate_script"] }
+    ];
+  }
+});
+
 // src/tools/registry.ts
 function buildToolset(options) {
   const { moduleNames, warnings } = selectModules(options);
   const { toolDefinitions, handlers } = collectTools(moduleNames);
-  return { moduleNames, warnings, toolDefinitions, handlers };
+  const instructions = buildInstructions(moduleNames, new Set(handlers.keys()));
+  return { moduleNames, warnings, toolDefinitions, handlers, instructions };
 }
 function selectModules(options) {
   const { tools: requested, preset, enableScript, enablePrivilegedContext } = options;
@@ -17651,6 +17673,7 @@ var init_registry = __esm({
   "src/tools/registry.ts"() {
     "use strict";
     init_tools();
+    init_instructions();
     privilegedModuleNames = new Set(MODULES.filter((m) => m.privileged).map((m) => m.name));
   }
 });
@@ -17771,7 +17794,8 @@ async function run(parseArgsFn, importMetaUrl, allowPrivileged = false) {
     moduleNames,
     warnings,
     toolDefinitions: allTools,
-    handlers: toolHandlers
+    handlers: toolHandlers,
+    instructions
   } = buildToolset({
     tools: args.tools,
     preset: args.toolPreset,
@@ -17801,7 +17825,8 @@ async function run(parseArgsFn, importMetaUrl, allowPrivileged = false) {
     {
       capabilities: {
         tools: {}
-      }
+      },
+      instructions
     }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mozilla/firefox-devtools-mcp-moz",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Model Context Protocol (MCP) server for Firefox DevTools automation (moz build with privileged context support)",
   "author": "Mozilla",
   "license": "MIT OR Apache-2.0",

package/plugins/firefox-devtools-mcp/skills/debug/SKILL.md

@@ -1,6 +1,8 @@
 ---
+name: debug
 description: Show console errors and failed network requests
 argument-hint: [console|network|all]
+disable-model-invocation: true
 ---
 
 # /firefox-devtools-mcp:debug

package/plugins/firefox-devtools-mcp/skills/navigate/SKILL.md

@@ -2,6 +2,7 @@
 name: navigate
 description: Navigate Firefox to a URL and take a DOM snapshot for interaction
 argument-hint: <url>
+disable-model-invocation: true
 ---
 
 # /firefox-devtools-mcp:navigate

package/plugins/firefox-devtools-mcp/skills/screenshot/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: screenshot
-description: Take a screenshot of a URL or the current page. Use when the user asks to capture, screenshot, or photograph a web page or URL.
+description: Take a screenshot of a URL or the current page
 argument-hint: [url or uid]
+disable-model-invocation: true
 ---
 
 # /firefox-devtools-mcp:screenshot

package/plugins/firefox-devtools-mcp/skills/web-performance/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: web-performance
+description: Find and fix why a website is slow by capturing and analyzing a Firefox performance profile, or by analyzing a profile the user already has (a saved file or a profiler.firefox.com share link). Use for slow page loads, janky scrolling or animation, slow interactions or a slow STR, long tasks, layout thrashing, or heavy JavaScript.
+---
+
+Work from a real profile, find the cause in the user's code, report it honestly, and if asked, fix it and prove the fix worked. The firefox-devtools MCP drives Firefox and records a profile when there is none yet; `profiler-cli` queries the profile, whether you captured it or the user brought it. Report in web-platform terms (LCP, main-thread blocking, reflow, render-blocking resources), not Gecko internals - unless the target is Firefox itself rather than a page, in which case platform frames are the subject and the fix lands in mozilla-central.
+
+## Step 0: Prerequisites
+
+profiler-cli needs Node.js >= 24:
+```bash
+command -v profiler-cli >/dev/null 2>&1 || npm install -g @firefox-devtools/profiler-cli@latest
+```
+`npx @firefox-devtools/profiler-cli@latest` also works but re-resolves on every call.
+
+The rest of this step is only for capturing. Skip it when the user already has a profile.
+
+The profiler tools need **Firefox 154+**. Check with `get_firefox_info`, which also launches it. If Firefox is missing or older, stop and ask the user to install a current release or point the server at one with `--firefox-path`. The profiler tools also need the `developer` tool preset: if `profiler_start` is absent, ask the user to restart the server with `--tool-preset developer`, since the default `basic` preset has no profiler.
+
+## Step 1: Pick the scenario
+
+**If the user already has a profile** - a saved `.json.gz`, or a `share.firefox.dev` / profiler.firefox.com link - there is nothing to capture: skip to Step 3 and `load` it directly. Ask what they were doing while it recorded, since the capture type decides the entry point in the playbook. Verifying a fix (Step 6) still needs a capture, so if you cannot reach their setup, hand them the recipe and ask for an after profile.
+
+Otherwise ask if unclear: **page load**, **interaction / STR** (one slow action), or **ongoing jank** (scroll stutter, dropped frames, CPU pinning). Each has a recipe in `references/capture-recipes.md`.
+
+## Step 2: Capture
+
+Follow that recipe. Keep the window tight - start late, stop early - and keep the profile path `profiler_stop` returns.
+
+## Step 3: Analyze
+
+1. Run `profiler-cli guide` and read the **entire** output; it is the command reference for everything below. Do not skim, and make sure that Bash did not truncate it.
+2. `profiler-cli load <path>`, or `profiler-cli load <share-url>` for a profile the user shared.
+3. Work through `references/analysis-playbook.md`: thread selection, the entry point for each capture type, and a symptom-to-command map.
+
+Run the commands and interpret the output yourself; do not print commands for the user to run.
+
+## Step 4: Find the cause in the source
+
+`Grep`/`Glob`/`Read` the project for the code behind a hot function or request, and confirm the mechanism. If you cannot connect a finding to real source, say so instead of inventing a code path.
+
+## Step 5: Report with explicit confidence
+
+Label every finding:
+- **Confirmed** - in the profile and cross-checked (stack traced to source, a measured before/after, a `performance.measure` you captured). State the evidence.
+- **Likely** - strong single-source evidence, not cross-checked. Say what would confirm it.
+- **Hypothesis** - a plausible reading of ambiguous data. Say so, and how to validate it.
+
+If sampling is sparse, the window was wrong, or the time is mostly idle, call it inconclusive and re-capture instead of guessing.
+
+Per finding: what is slow -> evidence (function/marker/request and its cost) plus confidence -> why -> the fix in the developer's terms. Biggest confirmed wins first.
+
+When a "likely" or "hypothesis" finding is worth acting on, get more evidence first. `references/validation.md` covers instrumenting the page with User Timing and reading navigation, resource, paint, LCP and Event Timing entries.
+
+## Step 6: Fix and verify
+
+Implement only if asked, keeping the change minimal and tied to the confirmed finding. Then re-capture like-for-like (see the before/after section of the recipes) and compare the metric that was slow. Quantify the gain; if it did not improve, or something else regressed, say so and reconsider.
+
+## Step 7: Clean up
+
+`profiler-cli stop` - the daemon holds a port and memory until stopped. Stop the Firefox profiler if `profiler_is_active`, and remove instrumentation you injected unless the user wants it kept.

package/plugins/firefox-devtools-mcp/skills/web-performance/references/analysis-playbook.md

@@ -0,0 +1,62 @@
+# Analysis playbook
+
+Turning a loaded profile into web-platform findings. Assumes `profiler-cli guide` has been read in full (it documents the flags used here) and the profile is loaded.
+
+## Select the right thread
+
+Start on the content process main thread: the `GeckoMain` thread of the `Isolated Web Content [<url>]` process serving the page. Most of the script, layout and paint work a user feels is there. Cross-origin iframes get their own content process, so third-party work (ads, embeds) sits under a different one; worker cost sits on `DOM Worker` threads.
+
+That is where to start, not where to stop. Depending on the problem:
+
+- **Network.** The request is not content-process work at all. `GeckoMain` in the parent process drives navigation and channel setup, and `Socket Thread` does connection, TLS and transfer, with `DNS Resolver`, `TRR Background` and `Cache2 I/O` next to it - in the parent, or in a separate `Socket` process when the build runs one. A content thread sitting idle while requests are in flight means the answer is on those threads.
+- **Scrolling, animation, dropped frames.** `Compositor`, `Renderer` and the GPU-process threads, alongside the content main thread.
+- **Firefox itself as the target.** Any platform thread can be the subject, most often parent `GeckoMain`.
+
+A thread is only in the profile if the capture recorded it: the `web-developer` preset leaves out the networking threads, so a network question usually needs a re-capture with `preset="networking"`.
+
+## Start here
+
+**Page-load captures:** `thread page-load` gives navigation timing, FCP/LCP, resources, CPU and jank periods in one view, and its marker handles feed `zoom push` and `marker info`. "No page load markers found in this thread" means the capture has no navigation or the thread is wrong - it is not a verdict about the page.
+
+**Interaction and jank captures** never navigate, so `page-load` returns nothing for them. Enter through markers:
+
+```
+profiler-cli thread markers --min-duration 50 --list   # long intervals, chronological
+profiler-cli zoom push m-<handle>                      # onto the worst one
+profiler-cli thread samples-top-down                   # what ran during it
+```
+
+Blocking main-thread work appears as a long `Runnable`, or `Perform microtasks`. `DOMEvent` markers locate the interaction. Ignore long-lived span markers that are not blocking work: `Image Animation` (one animating GIF spans the whole recording), `IPC Accumulator`. `--has-stack` with `marker stack <handle>` gives the stack that belongs to a marker.
+
+## Minified bundles: apply the source map first
+
+If JS frames show mangled names (`a`, `t.exports`), de-minify before reading stacks.
+
+```
+profiler-cli sourcemap sources                  # bundles with a source map, as src-N, plus their sourceMapURL
+profiler-cli sourcemap apply dist/bundle.js.map
+```
+
+`apply` reads a local file, it does not fetch: take the `.map` from the user's build output, and if `sources` shows a remote `sourceMapURL`, download it first. It rewrites stacks in place, so apply before reading call trees. The guide's SOURCE MAPS section covers `--to src-N` and ambiguous matches. With no map, keep findings at function level - mangled names do not support line-level claims.
+
+## Symptom -> where to look
+
+**Do not limit yourself to the categories below.** They are the common cases, not a list of the problems a profile can answer. The data decides what the problem is; if the symptom does not match any of them, or the profile points somewhere else, follow the profile. Forcing a finding into one of these buckets is how you end up reporting the wrong cause.
+
+**Slow first paint / LCP / content appears late.** `thread page-load` for which phase dominates. Before first byte is server or network; between response and paint is client work. `thread markers` shows when paint, DOMContentLoaded and load actually fired.
+
+**Long tasks / blocked main thread / unresponsive UI.** Take long tasks from the profile: `page-load` jank periods for a navigation capture, the marker route above otherwise. `samples-bottom-up` complements the top-down tree by showing hot leaf functions and their callers. If the hot frames are framework internals (render, reconcile, hydrate), look for too many or too expensive components rather than one slow function.
+
+**Heavy JavaScript.** `thread functions` for a flat list by CPU percentage, `samples-top-down` for the tree, `function annotate <handle>` for per-line timing, `function expand <handle>` for a truncated name.
+
+**Layout thrashing / forced reflow.** In `samples-top-down`, look for reflow/layout/style-recalc frames interleaved with script - that pattern is a script reading layout, writing, then reading again, forcing synchronous reflow. `thread markers` shows how often layout and reflow markers fire. Then find the read-write-read loop in the source.
+
+**Slow or render-blocking network.** `thread network` gives per-request timing phases (DNS, connect, TLS, wait, download) for the selected thread. Look for render-blocking CSS/JS in the head, long TTFB, request chains where each waits on the previous, and duplicate downloads. When the cost is in the transfer itself rather than in how the page requested it, follow it onto the parent's `GeckoMain` and `Socket Thread` as described above. The profile has timing but not response headers, so for `content-encoding`, `cache-control` and `content-type` - what tells you whether an asset is actually compressed or cacheable - use the MCP's `list_network_requests` and `get_network_request`.
+
+**User Timing.** `thread markers` shows the developer's `performance.mark`/`measure` alongside platform markers; `marker info` and `marker stack` give one marker's detail and its stack.
+
+**Anything else.** Let the profile pick the direction: `profile info` for which process and thread actually burned CPU or stalled, then markers and samples on that thread.
+
+## Before recommending a fix
+
+Correlate the hot stack with markers and network timing. A stack alone says what ran, rarely why it ran.

package/plugins/firefox-devtools-mcp/skills/web-performance/references/capture-recipes.md

@@ -0,0 +1,53 @@
+# Capture recipes
+
+Record the right profile per scenario. If a capture misses the slow moment or is mostly idle, re-capture instead of salvaging it.
+
+Applies to every recipe:
+- Firefox launches lazily on the first MCP call (`list_pages`, `get_firefox_info`). Reuse the existing session and tab; only `new_page` / `navigate_page` for a different page or a clean state.
+- `preset="web-developer"` is the usual choice for `profiler_start`, but it does not record the networking threads. A network-shaped problem (slow TTFB, connection or TLS setup, DNS, cache misses) might want `networking` instead. Use `firefox-platform` when the target is Firefox itself, another preset when the problem sits squarely in its domain, or explicit `entries`/`interval`/`features`/`threads` when none of them fit.
+- `profiler_stop` saves to Firefox's downloads directory and returns the path. Keep it.
+- If nothing records, check `profiler_is_active` and confirm Firefox is 154+.
+
+## Page load
+
+The recording should span one navigation with nothing before it.
+
+1. `navigate_page url="about:blank"`, so the navigation is captured from the start.
+2. `profiler_start`.
+3. `navigate_page url="https://the-page"` - this navigation is the whole recording.
+4. Wait for the page to finish, then stop promptly without recording an idle tail. There is no wait tool, so poll: `evaluate_script function="() => [document.readyState, performance.getEntriesByType('navigation')[0]?.loadEventEnd]"`, or `screenshot_page`.
+5. `profiler_stop`.
+
+Caching caveat: this is a clean navigation but not a cold load. The session shares Firefox's HTTP cache, and `about:blank` or a new tab does not clear it. Neither can you: there is no cache-clearing or private-window tool. So either:
+- label the finding a warm-cache load, or
+- for a real first visit, `restart_firefox` with `profilePath` set to a fresh empty directory - a new profile starts with an empty cache, but it closes every tab and drops cookies and logins, so it is no good for authenticated pages.
+
+Confirm which one you got instead of assuming: in `thread network`, a cold load shows real DNS/connect/download phases for subresources, a warm one near-zero fetch time.
+
+Warm variant (repeat visit): navigate to the URL and let it settle first, then start the profiler and navigate to it again. The second navigation is the measured one.
+
+## Interaction or STR
+
+Record the action, not the setup.
+
+1. `navigate_page` to the state right before the slow action. Do NOT perform it yet.
+2. `take_snapshot` to resolve the UIDs you will need, so the recorded window is only the action.
+3. `profiler_start`.
+4. Perform exactly the steps the user reports as slow, in order, with the automation tools.
+5. `profiler_stop` as soon as the slow result is visible.
+
+If the DOM changed and you need a fresh snapshot mid-recording, `take_snapshot` again; it does not meaningfully pollute the profile.
+
+## Ongoing jank (scroll, animation, CPU pinning)
+
+1. `navigate_page` to the janky page and state.
+2. `profiler_start`.
+3. Reproduce the jank for a few representative seconds. Drive the scrolling if you can, otherwise ask the user to scroll while recording.
+4. `profiler_stop`.
+
+## Re-capturing to verify a fix
+
+The second capture must be like-for-like or the comparison is meaningless:
+- Same recipe, URL, STR steps and window length.
+- Same cache warmth and page state; a cold-vs-warm difference will swamp the fix.
+- Ideally the same `performance.mark`/`measure` instrumentation (see `validation.md`), so you compare the same measured span rather than two eyeballed windows.

package/plugins/firefox-devtools-mcp/skills/web-performance/references/validation.md

@@ -0,0 +1,35 @@
+# Validation: turning guesses into measurements
+
+Use this when a "likely" or "hypothesis" finding matters enough to act on, or to get a reliable metric for a before/after comparison. Instrumentation goes into the user's source where there is source to edit, and through `evaluate_script` otherwise.
+
+## Bracket the operation with User Timing
+
+Marks and measures appear both as markers in the next captured profile and via `performance.getEntriesByType('measure')`.
+
+**If the user's source is available, put the marks there instead.** They then measure only the operation, can wrap code you cannot reach from the outside, survive a navigation, and are still in place for the after-fix capture, so both runs measure the same span.
+
+With no source to edit, bracket from outside while the profiler records:
+
+1. `performance.mark('before')`, then perform the STR step with the automation tools.
+2. `performance.mark('after')` and `performance.measure('op', 'before', 'after')`.
+3. Read back with `evaluate_script function="() => performance.getEntriesByType('measure').map(m => ({name: m.name, dur: m.duration}))"`, and find the same span in the profile with `thread markers --search op`.
+
+Those are three separate tool calls, so the measure also contains the MCP round-trips and your own thinking time between them. Treat it as a way to locate the span in the profile, not as the operation's cost.
+
+A measured duration matching the sampled cost confirms the finding; a mismatch means sampling misattributed it, which is common with inlined or minified code.
+
+## LCP and Event Timing
+
+Firefox might not support every entry type Chrome does, and `observe()` ignores an unsupported one with a console warning and no exception - you get an empty result that reads like a clean bill of health. Check before relying on one, rather than assuming the Chrome set:
+
+`evaluate_script function="() => PerformanceObserver.supportedEntryTypes"`
+
+Anything missing from that list has to come from the profile instead.
+
+An observer needs a document, and `evaluate_script` runs in the *current* one - a navigation destroys it along with anything on `window`. For a page load, install the observer *after* the navigation settles; `buffered: true` replays entries that already fired, so nothing is missed. For an STR, install it before the action.
+
+```
+evaluate_script function="() => { window.__perf = {lcp: 0, events: []}; new PerformanceObserver(l => { for (const e of l.getEntries()) window.__perf.lcp = e.startTime; }).observe({type: 'largest-contentful-paint', buffered: true}); new PerformanceObserver(l => { for (const e of l.getEntries()) window.__perf.events.push({name: e.name, dur: e.duration}); }).observe({type: 'event', buffered: true, durationThreshold: 16}); }"
+```
+
+Read back with `evaluate_script function="() => window.__perf"`. The last LCP entry wins; `event` entries give per-interaction latency.