firefox-devtools-mcp 0.3.0 → 0.5.1

package/dist/index.js

@@ -12192,6 +12192,9 @@ var init_core = __esm({
         if (this.options.profilePath) {
           firefoxOptions.setProfile(this.options.profilePath);
         }
+        if (this.options.acceptInsecureCerts) {
+          firefoxOptions.setAcceptInsecureCerts(true);
+        }
         this.driver = await new Builder().forBrowser(Browser.FIREFOX).setFirefoxOptions(firefoxOptions).build();
         log("\u2705 Firefox launched with BiDi");
         this.currentContextId = await this.driver.getWindowHandle();
@@ -12211,6 +12214,30 @@ var init_core = __esm({
         }
         return this.driver;
       }
+      /**
+       * Check if Firefox is still connected and responsive
+       * Returns false if Firefox was closed or connection is broken
+       */
+      async isConnected() {
+        if (!this.driver) {
+          return false;
+        }
+        try {
+          await this.driver.getWindowHandle();
+          return true;
+        } catch (error) {
+          logDebug("Connection check failed: Firefox is not responsive");
+          return false;
+        }
+      }
+      /**
+       * Reset driver state (used when Firefox is detected as closed)
+       */
+      reset() {
+        this.driver = null;
+        this.currentContextId = null;
+        logDebug("Driver state reset");
+      }
       /**
        * Get current browsing context ID
        */
@@ -12555,10 +12582,42 @@ var init_network = __esm({
        */
       parseHeaders(headers) {
         const result = {};
+        const normalizeValue = (value) => {
+          if (value === null || value === void 0) {
+            return null;
+          }
+          if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            return String(value);
+          }
+          if (Array.isArray(value)) {
+            const parts = value.map((item) => normalizeValue(item)).filter((item) => !!item);
+            return parts.length > 0 ? parts.join(", ") : null;
+          }
+          if (typeof value === "object") {
+            const obj = value;
+            if ("value" in obj) {
+              return normalizeValue(obj.value);
+            }
+            if ("bytes" in obj) {
+              return normalizeValue(obj.bytes);
+            }
+            try {
+              return JSON.stringify(obj);
+            } catch {
+              return null;
+            }
+          }
+          return String(value);
+        };
         if (Array.isArray(headers)) {
           for (const h of headers) {
-            if (h.name && h.value) {
-              result[h.name.toLowerCase()] = String(h.value);
+            const name = h?.name ? String(h.name).toLowerCase() : "";
+            if (!name) {
+              continue;
+            }
+            const normalizedValue = normalizeValue(h?.value);
+            if (normalizedValue !== null) {
+              result[name] = normalizedValue;
             }
           }
         }
@@ -12986,6 +13045,7 @@ var init_pages = __esm({
         if (index >= 0 && index < handles.length) {
           await this.driver.switchTo().window(handles[index]);
           this.setCurrentContextId(handles[index]);
+          this.cachedSelectedIdx = index;
         }
       }
       /**
@@ -12996,6 +13056,7 @@ var init_pages = __esm({
         const handles = await this.driver.getAllWindowHandles();
         const newIdx = handles.length - 1;
         this.setCurrentContextId(handles[newIdx]);
+        this.cachedSelectedIdx = newIdx;
         await this.driver.get(url);
         return newIdx;
       }
@@ -13131,7 +13192,7 @@ var MAX_ATTR_LENGTH;
 var init_formatter = __esm({
   "src/firefox/snapshot/formatter.ts"() {
     "use strict";
-    MAX_ATTR_LENGTH = 50;
+    MAX_ATTR_LENGTH = 30;
   }
 });
 
@@ -13300,10 +13361,12 @@ var init_manager = __esm({
           const currentFilePath = fileURLToPath(currentFileUrl);
           const currentDir = dirname(currentFilePath);
           const possiblePaths = [
-            // Production: relative to compiled dist/index.js location
-            resolve(currentDir, "../../snapshot.injected.global.js"),
-            // Alternative: relative to current working directory
-            resolve(process.cwd(), "dist/snapshot.injected.global.js")
+            // Production: relative to bundled dist/index.js (same directory)
+            resolve(currentDir, "snapshot.injected.global.js"),
+            // Development: relative to current working directory
+            resolve(process.cwd(), "dist/snapshot.injected.global.js"),
+            // npx: package is in node_modules, try to find it relative to the binary
+            resolve(currentDir, "../snapshot.injected.global.js")
           ];
           const attemptedPaths = [];
           for (const path of possiblePaths) {
@@ -13358,7 +13421,8 @@ ${attemptedPaths.map((p) => `  - ${p}`).join("\n")}`
           root: result.tree,
           snapshotId,
           timestamp: Date.now(),
-          truncated: result.truncated || false
+          truncated: result.truncated || false,
+          uidMap: result.uidMap
         };
         const snapshot = {
           text: formatSnapshotTree(result.tree),
@@ -13726,6 +13790,24 @@ var init_firefox = __esm({
       getDriver() {
         return this.core.getDriver();
       }
+      /**
+       * Check if Firefox is still connected and responsive
+       * Returns false if Firefox was closed or connection is broken
+       */
+      async isConnected() {
+        return await this.core.isConnected();
+      }
+      /**
+       * Reset all internal state (used when Firefox is detected as closed)
+       */
+      reset() {
+        this.core.reset();
+        this.consoleEvents = null;
+        this.networkEvents = null;
+        this.dom = null;
+        this.pages = null;
+        this.snapshot = null;
+      }
       // ============================================================================
       // Cleanup
       // ============================================================================
@@ -13737,6 +13819,30 @@ var init_firefox = __esm({
 });
 
 // src/utils/response-helpers.ts
+function truncateText(text, maxChars, suffix = "\n\n[... truncated - exceeded size limit]") {
+  if (text.length <= maxChars) {
+    return text;
+  }
+  return text.slice(0, maxChars - suffix.length) + suffix;
+}
+function truncateHeaders(headers) {
+  if (!headers) {
+    return null;
+  }
+  const result = {};
+  let totalChars = 0;
+  for (const [key, value] of Object.entries(headers)) {
+    const truncatedValue = value.length > TOKEN_LIMITS.MAX_HEADER_VALUE_CHARS ? value.slice(0, TOKEN_LIMITS.MAX_HEADER_VALUE_CHARS) + "...[truncated]" : value;
+    const entrySize = key.length + truncatedValue.length;
+    if (totalChars + entrySize > TOKEN_LIMITS.MAX_HEADERS_TOTAL_CHARS) {
+      result["__truncated__"] = "Headers truncated due to size limit";
+      break;
+    }
+    result[key] = truncatedValue;
+    totalChars += entrySize;
+  }
+  return result;
+}
 function successResponse(message) {
   return {
     content: [
@@ -13769,26 +13875,40 @@ function jsonResponse(data) {
     ]
   };
 }
+var TOKEN_LIMITS;
 var init_response_helpers = __esm({
   "src/utils/response-helpers.ts"() {
     "use strict";
+    TOKEN_LIMITS = {
+      /** Maximum characters for a single response (~12.5k tokens at ~4 chars/token) */
+      MAX_RESPONSE_CHARS: 5e4,
+      /** Maximum characters for screenshot base64 data (~10k tokens) */
+      MAX_SCREENSHOT_CHARS: 4e4,
+      /** Maximum characters per console message text */
+      MAX_CONSOLE_MESSAGE_CHARS: 2e3,
+      /** Maximum characters for network header values (per header) */
+      MAX_HEADER_VALUE_CHARS: 500,
+      /** Maximum total characters for all headers combined */
+      MAX_HEADERS_TOTAL_CHARS: 5e3,
+      /** Hard cap on snapshot lines (even if user requests more) */
+      MAX_SNAPSHOT_LINES_CAP: 500,
+      /** Warning threshold - show warning when response exceeds this */
+      WARNING_THRESHOLD_CHARS: 3e4
+    };
   }
 });
 
 // src/tools/pages.ts
 function formatPageList(tabs, selectedIdx) {
-  const lines = [`\u{1F4C4} Open pages (${tabs.length} total, selected: [${selectedIdx}]):`];
   if (tabs.length === 0) {
-    lines.push("  (no pages open)");
-  } else {
-    for (const tab of tabs) {
-      const idx = tabs.indexOf(tab);
-      const indicator = idx === selectedIdx ? "\u{1F449}" : "  ";
-      const title = tab.title || "Untitled";
-      const url = tab.url || "about:blank";
-      lines.push(`${indicator} [${idx}] ${title}`);
-      lines.push(`     ${url}`);
-    }
+    return "\u{1F4C4} No pages";
+  }
+  const lines = [`\u{1F4C4} ${tabs.length} pages (selected: ${selectedIdx})`];
+  for (const tab of tabs) {
+    const idx = tabs.indexOf(tab);
+    const marker = idx === selectedIdx ? ">" : " ";
+    const title = (tab.title || "Untitled").substring(0, 40);
+    lines.push(`${marker}[${idx}] ${title}`);
   }
   return lines.join("\n");
 }
@@ -13813,14 +13933,7 @@ async function handleNewPage(args2) {
     const { getFirefox: getFirefox2 } = await init_index().then(() => index_exports);
     const firefox3 = await getFirefox2();
     const newIdx = await firefox3.createNewPage(url);
-    await firefox3.refreshTabs();
-    const tabs = firefox3.getTabs();
-    const newTab = tabs[newIdx];
-    return successResponse(
-      `\u2705 Created new page [${newIdx}] and navigated to: ${url}
-   Title: ${newTab?.title || "Loading..."}
-   Total pages: ${tabs.length}`
-    );
+    return successResponse(`\u2705 new page [${newIdx}] \u2192 ${url}`);
   } catch (error) {
     return errorResponse(error);
   }
@@ -13841,10 +13954,7 @@ async function handleNavigatePage(args2) {
       throw new Error("No page selected");
     }
     await firefox3.navigate(url);
-    return successResponse(
-      `\u2705 Navigated page [${selectedIdx}] to: ${url}
-   Previous URL: ${page.url}`
-    );
+    return successResponse(`\u2705 [${selectedIdx}] \u2192 ${url}`);
   } catch (error) {
     return errorResponse(error);
   }
@@ -13857,47 +13967,30 @@ async function handleSelectPage(args2) {
     await firefox3.refreshTabs();
     const tabs = firefox3.getTabs();
     let selectedIdx;
-    let selectionMethod;
     if (typeof pageIdx === "number") {
       selectedIdx = pageIdx;
-      selectionMethod = "by index";
     } else if (url && typeof url === "string") {
       const urlLower = url.toLowerCase();
       const foundIdx = tabs.findIndex((tab) => tab.url?.toLowerCase().includes(urlLower));
       if (foundIdx === -1) {
-        throw new Error(
-          `No page found with URL matching "${url}". Use list_pages to see all available pages.`
-        );
+        throw new Error(`No page matching URL "${url}"`);
       }
       selectedIdx = foundIdx;
-      selectionMethod = `by URL pattern "${url}"`;
     } else if (title && typeof title === "string") {
       const titleLower = title.toLowerCase();
       const foundIdx = tabs.findIndex((tab) => tab.title?.toLowerCase().includes(titleLower));
       if (foundIdx === -1) {
-        throw new Error(
-          `No page found with title matching "${title}". Use list_pages to see all available pages.`
-        );
+        throw new Error(`No page matching title "${title}"`);
       }
       selectedIdx = foundIdx;
-      selectionMethod = `by title pattern "${title}"`;
     } else {
-      throw new Error(
-        "At least one of pageIdx, url, or title must be provided. Use list_pages to see available pages."
-      );
+      throw new Error("Provide pageIdx, url, or title");
     }
-    const page = tabs[selectedIdx];
-    if (!page) {
-      throw new Error(
-        `Page at index ${selectedIdx} not found. Use list_pages to see valid indices.`
-      );
+    if (!tabs[selectedIdx]) {
+      throw new Error(`Page [${selectedIdx}] not found`);
     }
     await firefox3.selectTab(selectedIdx);
-    return successResponse(
-      `\u2705 Selected page [${selectedIdx}] ${selectionMethod}
-   Title: ${page.title || "Untitled"}
-   URL: ${page.url || "about:blank"}`
-    );
+    return successResponse(`\u2705 selected [${selectedIdx}]`);
   } catch (error) {
     return errorResponse(error);
   }
@@ -13917,10 +14010,7 @@ async function handleClosePage(args2) {
       throw new Error(`Page with index ${pageIdx} not found`);
     }
     await firefox3.closeTab(pageIdx);
-    return successResponse(
-      `\u2705 Closed page [${pageIdx}]: ${pageToClose.title}
-   ${pageToClose.url}`
-    );
+    return successResponse(`\u2705 closed [${pageIdx}]`);
   } catch (error) {
     return errorResponse(error);
   }
@@ -13932,7 +14022,7 @@ var init_pages2 = __esm({
     init_response_helpers();
     listPagesTool = {
       name: "list_pages",
-      description: "List all open tabs with index, title, and URL. The currently selected tab is marked. Use the index with select_page.",
+      description: "List open tabs (index, title, URL). Selected tab is marked.",
       inputSchema: {
         type: "object",
         properties: {}
@@ -13940,13 +14030,13 @@ var init_pages2 = __esm({
     };
     newPageTool = {
       name: "new_page",
-      description: "Open a new tab and navigate it to the provided URL. Returns the new tab index in the response.",
+      description: "Open new tab at URL. Returns tab index.",
       inputSchema: {
         type: "object",
         properties: {
           url: {
             type: "string",
-            description: "URL to load in a new page"
+            description: "Target URL"
           }
         },
         required: ["url"]
@@ -13954,13 +14044,13 @@ var init_pages2 = __esm({
     };
     navigatePageTool = {
       name: "navigate_page",
-      description: "Navigate the currently selected tab to the provided URL.",
+      description: "Navigate selected tab to URL.",
       inputSchema: {
         type: "object",
         properties: {
           url: {
             type: "string",
-            description: "URL to navigate the page to"
+            description: "Target URL"
           }
         },
         required: ["url"]
@@ -13968,21 +14058,21 @@ var init_pages2 = __esm({
     };
     selectPageTool = {
       name: "select_page",
-      description: "Select the active tab by index (preferred), or by matching URL/title. Index takes precedence when multiple parameters are provided.",
+      description: "Select active tab by index, URL, or title. Index takes precedence.",
       inputSchema: {
         type: "object",
         properties: {
           pageIdx: {
             type: "number",
-            description: "The index of the page to select (e.g., 0, 1, 2). Use list_pages first to see all available page indices. Most reliable method."
+            description: "Tab index (0-based, most reliable)"
           },
           url: {
             type: "string",
-            description: 'Select page by URL (partial match, case-insensitive). Example: "github.com" will match "https://github.com/user/repo"'
+            description: "URL substring (case-insensitive)"
           },
           title: {
             type: "string",
-            description: 'Select page by title (partial match, case-insensitive). Example: "Google" will match "Google Search - About"'
+            description: "Title substring (case-insensitive)"
           }
         },
         required: []
@@ -13990,13 +14080,13 @@ var init_pages2 = __esm({
     };
     closePageTool = {
       name: "close_page",
-      description: "Close the tab at the given index. Use list_pages to find valid indices.",
+      description: "Close tab by index.",
       inputSchema: {
         type: "object",
         properties: {
           pageIdx: {
             type: "number",
-            description: "The index of the page to close"
+            description: "Tab index to close"
           }
         },
         required: ["pageIdx"]
@@ -14034,6 +14124,10 @@ async function handleListConsoleMessages(args2) {
     if (source) {
       messages = messages.filter((msg) => msg.source?.toLowerCase() === source.toLowerCase());
     }
+    messages = messages.map((msg) => ({
+      ...msg,
+      text: truncateText(msg.text, TOKEN_LIMITS.MAX_CONSOLE_MESSAGE_CHARS, "...[truncated]")
+    }));
     const maxLimit = limit ?? DEFAULT_LIMIT;
     const filteredCount = messages.length;
     const truncated = messages.length > maxLimit;
@@ -14127,7 +14221,7 @@ Total messages: ${totalCount}${filterInfo.length > 0 ? `, Filters: ${filterInfo.
     }
     if (truncated) {
       output += `
-... ${filteredCount - messages.length} more messages (increase limit to see more)`;
+[+${filteredCount - messages.length} more]`;
     }
     return successResponse(output);
   } catch (error) {
@@ -14140,11 +14234,7 @@ async function handleClearConsoleMessages(_args) {
     const firefox3 = await getFirefox2();
     const count = (await firefox3.getConsoleMessages()).length;
     firefox3.clearConsoleMessages();
-    return successResponse(
-      `Cleared ${count} console message(s) from buffer.
-
-You can now capture fresh console output from new page activity.`
-    );
+    return successResponse(`\u2705 cleared ${count} messages`);
   } catch (error) {
     return errorResponse(error);
   }
@@ -14156,42 +14246,42 @@ var init_console2 = __esm({
     init_response_helpers();
     listConsoleMessagesTool = {
       name: "list_console_messages",
-      description: "List console messages for the selected tab since the last navigation. Use filters (level, limit, sinceMs, textContains, source) to focus on recent and relevant logs.",
+      description: "List console messages. Supports filtering by level, time, text, source.",
       inputSchema: {
         type: "object",
         properties: {
           level: {
             type: "string",
             enum: ["debug", "info", "warn", "error"],
-            description: "Filter by console message level"
+            description: "Filter by level"
           },
           limit: {
             type: "number",
-            description: "Maximum number of messages to return (default: 50)"
+            description: "Max messages (default: 50)"
           },
           sinceMs: {
             type: "number",
-            description: "Only show messages from the last N milliseconds (filters by timestamp)"
+            description: "Only last N ms"
           },
           textContains: {
             type: "string",
-            description: "Filter messages by text content (case-insensitive substring match)"
+            description: "Text filter (case-insensitive)"
           },
           source: {
             type: "string",
-            description: 'Filter messages by source (e.g., "console-api", "javascript", "network")'
+            description: "Filter by source"
           },
           format: {
             type: "string",
             enum: ["text", "json"],
-            description: "Output format: text (default, human-readable) or json (structured data)"
+            description: "Output format (default: text)"
           }
         }
       }
     };
     clearConsoleMessagesTool = {
       name: "clear_console_messages",
-      description: "Clear the collected console messages. TIP: Clear before a new measurement to keep output focused.",
+      description: "Clear collected console messages.",
       inputSchema: {
         type: "object",
         properties: {}
@@ -14292,8 +14382,8 @@ async function handleListNetworkRequests(args2) {
           resourceType: req.resourceType,
           isXHR: req.isXHR,
           timings: req.timings || null,
-          requestHeaders: req.requestHeaders || null,
-          responseHeaders: req.responseHeaders || null
+          requestHeaders: truncateHeaders(req.requestHeaders),
+          responseHeaders: truncateHeaders(req.responseHeaders)
         }));
       }
       return jsonResponse(responseData);
@@ -14303,15 +14393,9 @@ async function handleListNetworkRequests(args2) {
         const statusInfo = req.status ? `[${req.status}${req.statusText ? " " + req.statusText : ""}]` : "[pending]";
         return `${req.id} | ${req.method} ${req.url} ${statusInfo}${req.isXHR ? " (XHR)" : ""}`;
       });
-      const summary = [
-        `Found ${requests.length} network request(s)${hasMore ? ` (showing first ${limit})` : ""}`,
-        "",
-        "Network Requests:",
-        ...formattedRequests,
-        "",
-        "TIP: Use the request ID (first column) with get_network_request for full details."
-      ].join("\n");
-      return successResponse(summary);
+      const header = `\u{1F4E1} ${requests.length} requests${hasMore ? ` (limit ${limit})` : ""}
+`;
+      return successResponse(header + formattedRequests.join("\n"));
     } else if (detail === "min") {
       const minData = limitedRequests.map((req) => ({
         id: req.id,
@@ -14324,8 +14408,7 @@ async function handleListNetworkRequests(args2) {
         duration: req.timings?.duration
       }));
       return successResponse(
-        `Found ${requests.length} requests${hasMore ? ` (showing first ${limit})` : ""}
-
+        `\u{1F4E1} ${requests.length} requests${hasMore ? ` (limit ${limit})` : ""}
 ` + JSON.stringify(minData, null, 2)
       );
     } else {
@@ -14338,19 +14421,16 @@ async function handleListNetworkRequests(args2) {
         resourceType: req.resourceType,
         isXHR: req.isXHR,
         timings: req.timings || null,
-        requestHeaders: req.requestHeaders || null,
-        responseHeaders: req.responseHeaders || null
+        requestHeaders: truncateHeaders(req.requestHeaders),
+        responseHeaders: truncateHeaders(req.responseHeaders)
       }));
       return successResponse(
-        `Found ${requests.length} requests${hasMore ? ` (showing first ${limit})` : ""}
-
+        `\u{1F4E1} ${requests.length} requests${hasMore ? ` (limit ${limit})` : ""}
 ` + JSON.stringify(fullData, null, 2)
       );
     }
   } catch (error) {
-    return errorResponse(
-      `Failed to list network requests: ${error instanceof Error ? error.message : String(error)}`
-    );
+    return errorResponse(error instanceof Error ? error : new Error(String(error)));
   }
 }
 async function handleGetNetworkRequest(args2) {
@@ -14361,9 +14441,7 @@ async function handleGetNetworkRequest(args2) {
       format = "text"
     } = args2;
     if (!id && !url) {
-      return errorResponse(
-        'Either "id" or "url" parameter is required.\n\nTIP: Call list_network_requests first and use the returned ID for reliable lookup.'
-      );
+      return errorResponse("id or url required");
     }
     const { getFirefox: getFirefox2 } = await init_index().then(() => index_exports);
     const firefox3 = await getFirefox2();
@@ -14372,29 +14450,16 @@ async function handleGetNetworkRequest(args2) {
     if (id) {
       request = requests.find((req) => req.id === id);
       if (!request) {
-        return errorResponse(
-          `No network request found with ID: ${id}
-
-TIP: The request may have been cleared. Call list_network_requests to see available requests.`
-        );
+        return errorResponse(`ID ${id} not found`);
       }
     } else if (url) {
       const matches = requests.filter((req) => req.url === url);
       if (matches.length === 0) {
-        return errorResponse(
-          `No network request found with URL: ${url}
-
-TIP: Use list_network_requests to see available requests.`
-        );
+        return errorResponse(`URL not found: ${url}`);
       }
       if (matches.length > 1) {
-        const matchInfo = matches.map((req) => `  - ID: ${req.id} | ${req.method} [${req.status || "pending"}]`).join("\n");
-        return errorResponse(
-          `Multiple requests (${matches.length}) found with URL: ${url}
-
-Please use one of these IDs with the "id" parameter:
-` + matchInfo
-        );
+        const ids = matches.map((req) => req.id).join(", ");
+        return errorResponse(`Multiple matches, use id: ${ids}`);
       }
       request = matches[0];
     }
@@ -14411,17 +14476,15 @@ Please use one of these IDs with the "id" parameter:
       isXHR: request.isXHR ?? false,
       timestamp: request.timestamp ?? null,
       timings: request.timings ?? null,
-      requestHeaders: request.requestHeaders ?? null,
-      responseHeaders: request.responseHeaders ?? null
+      requestHeaders: truncateHeaders(request.requestHeaders),
+      responseHeaders: truncateHeaders(request.responseHeaders)
     };
     if (format === "json") {
       return jsonResponse(details);
     }
-    return successResponse("Network Request Details:\n\n" + JSON.stringify(details, null, 2));
+    return successResponse(JSON.stringify(details, null, 2));
   } catch (error) {
-    return errorResponse(
-      `Failed to get network request: ${error instanceof Error ? error.message : String(error)}`
-    );
+    return errorResponse(error instanceof Error ? error : new Error(String(error)));
   }
 }
 var listNetworkRequestsTool, getNetworkRequestTool;
@@ -14431,82 +14494,82 @@ var init_network2 = __esm({
     init_response_helpers();
     listNetworkRequestsTool = {
       name: "list_network_requests",
-      description: "List recent network requests across all tabs. Network capture is always on. Use filters (limit, sinceMs, urlContains, method, status, resourceType) and detail (summary|min|full) to control output. Each entry includes a stable id for use with get_network_request.",
+      description: "List network requests. Returns IDs for get_network_request.",
       inputSchema: {
         type: "object",
         properties: {
           limit: {
             type: "number",
-            description: "Maximum number of requests to return (default: 50)"
+            description: "Max requests (default: 50)"
           },
           sinceMs: {
             type: "number",
-            description: "Return only requests newer than N milliseconds ago"
+            description: "Only last N ms"
           },
           urlContains: {
             type: "string",
-            description: "Filter requests by URL substring (case-insensitive)"
+            description: "URL filter (case-insensitive)"
           },
           method: {
             type: "string",
-            description: "Filter by HTTP method (GET, POST, etc., case-insensitive)"
+            description: "HTTP method filter"
           },
           status: {
             type: "number",
-            description: "Filter by exact HTTP status code"
+            description: "Exact status code"
           },
           statusMin: {
             type: "number",
-            description: "Filter by minimum HTTP status code"
+            description: "Min status code"
           },
           statusMax: {
             type: "number",
-            description: "Filter by maximum HTTP status code"
+            description: "Max status code"
           },
           isXHR: {
             type: "boolean",
-            description: "Filter by XHR/fetch requests only"
+            description: "XHR/fetch only"
           },
           resourceType: {
             type: "string",
-            description: "Filter by resource type (case-insensitive)"
+            description: "Resource type filter"
           },
           sortBy: {
             type: "string",
             enum: ["timestamp", "duration", "status"],
-            description: "Sort requests by field (default: timestamp descending)"
+            description: "Sort field (default: timestamp)"
           },
           detail: {
             type: "string",
             enum: ["summary", "min", "full"],
-            description: "Output detail level: summary (default), min (compact JSON), full (includes headers)"
+            description: "Detail level (default: summary)"
           },
           format: {
             type: "string",
             enum: ["text", "json"],
-            description: "Output format: text (default, human-readable) or json (structured data)"
+            description: "Output format (default: text)"
           }
         }
       }
     };
     getNetworkRequestTool = {
       name: "get_network_request",
-      description: "Get detailed information about a network request by id (recommended). URL lookup is available as a fallback but may match multiple requests.",
+      description: "Get request details by ID. URL lookup as fallback.",
       inputSchema: {
         type: "object",
         properties: {
           id: {
             type: "string",
-            description: "The request ID from list_network_requests (recommended)"
+            description: "Request ID from list_network_requests"
           },
           url: {
             type: "string",
-            description: "The URL of the request (fallback, may match multiple requests)"
+            description: "URL fallback (may match multiple)"
           },
           format: {
             type: "string",
             enum: ["text", "json"],
-            description: "Output format: text (default) or json (structured data)"
+            description: "Output format (default: text)"
           }
         }
       }
@@ -14514,15 +14577,31 @@ var init_network2 = __esm({
   }
 });
 
+// src/utils/uid-helpers.ts
+function handleUidError(error, uid) {
+  const errorMsg = error.message;
+  if (errorMsg.includes("stale") || errorMsg.includes("Snapshot") || errorMsg.includes("UID") || errorMsg.includes("not found")) {
+    return new Error(`${uid} stale/invalid. Call take_snapshot first.`);
+  }
+  return error;
+}
+var init_uid_helpers = __esm({
+  "src/utils/uid-helpers.ts"() {
+    "use strict";
+  }
+});
+
 // src/tools/snapshot.ts
 async function handleTakeSnapshot(args2) {
   try {
     const {
-      maxLines = MAX_SNAPSHOT_LINES,
+      maxLines: requestedMaxLines = DEFAULT_SNAPSHOT_LINES,
       includeAttributes = false,
       includeText = true,
       maxDepth
     } = args2 || {};
+    const maxLines = Math.min(Math.max(1, requestedMaxLines), TOKEN_LIMITS.MAX_SNAPSHOT_LINES_CAP);
+    const wasCapped = requestedMaxLines > TOKEN_LIMITS.MAX_SNAPSHOT_LINES_CAP;
     const { getFirefox: getFirefox2 } = await init_index().then(() => index_exports);
     const firefox3 = await getFirefox2();
     const snapshot = await firefox3.takeSnapshot();
@@ -14538,23 +14617,19 @@ async function handleTakeSnapshot(args2) {
     const lines = formattedText.split("\n");
     const truncated = lines.length > maxLines;
     const displayLines = truncated ? lines.slice(0, maxLines) : lines;
-    let output = "\u{1F4F8} Snapshot taken\n\n";
-    output += "\u2550\u2550\u2550 HOW TO USE THIS SNAPSHOT \u2550\u2550\u2550\n";
-    output += "\u2022 To interact with elements: use click_by_uid, hover_by_uid, or fill_by_uid with the UID\n";
-    output += "\u2022 After navigation: always call take_snapshot again (UIDs become stale)\n";
-    output += "\u2022 On stale UID errors: call take_snapshot \u2192 retry your action\n";
-    output += "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n";
-    output += `Snapshot ID: ${snapshot.json.snapshotId}
-`;
+    let output = `\u{1F4F8} Snapshot (id=${snapshot.json.snapshotId})`;
+    if (wasCapped) {
+      output += ` [maxLines capped: ${TOKEN_LIMITS.MAX_SNAPSHOT_LINES_CAP}]`;
+    }
     if (snapshot.json.truncated) {
-      output += "\u26A0\uFE0F  Snapshot content was truncated (too many elements in DOM)\n";
+      output += " [DOM truncated]";
     }
-    output += "\n";
+    output += "\n\n";
     output += displayLines.join("\n");
     if (truncated) {
       output += `
 
-... and ${lines.length - maxLines} more lines (use maxLines parameter to see more)`;
+[+${lines.length - maxLines} lines, use maxLines to see more]`;
     }
     return successResponse(output);
   } catch (error) {
@@ -14577,20 +14652,9 @@ async function handleResolveUidToSelector(args2) {
     const firefox3 = await getFirefox2();
     try {
       const selector = firefox3.resolveUidToSelector(uid);
-      return successResponse(`CSS Selector for UID "${uid}":
-
-${selector}`);
+      return successResponse(`${uid} \u2192 ${selector}`);
     } catch (error) {
-      const errorMsg = error.message;
-      if (errorMsg.includes("stale") || errorMsg.includes("Snapshot") || errorMsg.includes("UID") || errorMsg.includes("not found")) {
-        throw new Error(
-          `UID "${uid}" is from an old snapshot or not found.
-
-The page structure may have changed since the snapshot was taken.
-Please call take_snapshot to get fresh UIDs and try again.`
-        );
-      }
-      throw error;
+      throw handleUidError(error, uid);
     }
   } catch (error) {
     return errorResponse(error);
@@ -14601,53 +14665,52 @@ async function handleClearSnapshot(_args) {
     const { getFirefox: getFirefox2 } = await init_index().then(() => index_exports);
     const firefox3 = await getFirefox2();
     firefox3.clearSnapshot();
-    return successResponse(
-      "\u{1F9F9} Snapshot cache cleared.\n\nFor the next UID-dependent action, take a fresh snapshot first."
-    );
+    return successResponse("\u{1F9F9} Snapshot cleared");
   } catch (error) {
     return errorResponse(error);
   }
 }
-var MAX_SNAPSHOT_LINES, takeSnapshotTool, resolveUidToSelectorTool, clearSnapshotTool;
+var DEFAULT_SNAPSHOT_LINES, takeSnapshotTool, resolveUidToSelectorTool, clearSnapshotTool;
 var init_snapshot2 = __esm({
   "src/tools/snapshot.ts"() {
     "use strict";
     init_response_helpers();
-    MAX_SNAPSHOT_LINES = 100;
+    init_uid_helpers();
+    DEFAULT_SNAPSHOT_LINES = 100;
     takeSnapshotTool = {
       name: "take_snapshot",
-      description: "Capture a textual page snapshot with stable UIDs for elements. Always take a fresh snapshot after navigation or major DOM changes. TIP: Use the UIDs with click_by_uid / fill_by_uid / hover_by_uid. The output may be truncated for readability.",
+      description: "Capture DOM snapshot with stable UIDs. Retake after navigation.",
       inputSchema: {
         type: "object",
         properties: {
           maxLines: {
             type: "number",
-            description: "Maximum number of lines to return in output (default: 100)"
+            description: "Max lines (default: 100)"
           },
           includeAttributes: {
             type: "boolean",
-            description: "Include detailed ARIA and computed attributes in output (default: false)"
+            description: "Include ARIA attributes (default: false)"
           },
           includeText: {
             type: "boolean",
-            description: "Include text content in output (default: true)"
+            description: "Include text (default: true)"
           },
           maxDepth: {
             type: "number",
-            description: "Maximum depth of tree to include (default: unlimited)"
+            description: "Max tree depth"
           }
         }
       }
     };
     resolveUidToSelectorTool = {
       name: "resolve_uid_to_selector",
-      description: "Resolve a UID to a CSS selector (debugging aid). Fails on stale UIDs\u2014take a fresh snapshot first.",
+      description: "Resolve UID to CSS selector. Fails if stale.",
       inputSchema: {
         type: "object",
         properties: {
           uid: {
             type: "string",
-            description: "The UID from a snapshot to resolve"
+            description: "UID from snapshot"
           }
         },
         required: ["uid"]
@@ -14655,7 +14718,7 @@ var init_snapshot2 = __esm({
     };
     clearSnapshotTool = {
       name: "clear_snapshot",
-      description: "Clear the snapshot/UID cache. Usually not needed, as navigation invalidates snapshots automatically.",
+      description: "Clear snapshot cache. Usually not needed.",
       inputSchema: {
         type: "object",
         properties: {}
@@ -14665,18 +14728,6 @@ var init_snapshot2 = __esm({
 });
 
 // src/tools/input.ts
-function handleUidError(error, uid) {
-  const errorMsg = error.message;
-  if (errorMsg.includes("stale") || errorMsg.includes("Snapshot") || errorMsg.includes("UID") || errorMsg.includes("not found")) {
-    return new Error(
-      `UID "${uid}" is stale or invalid.
-
-The page may have changed since the snapshot was taken.
-Please call take_snapshot to get fresh UIDs and try again.`
-    );
-  }
-  return error;
-}
 async function handleClickByUid(args2) {
   try {
     const { uid, dblClick } = args2;
@@ -14687,9 +14738,7 @@ async function handleClickByUid(args2) {
     const firefox3 = await getFirefox2();
     try {
       await firefox3.clickByUid(uid, dblClick);
-      return successResponse(
-        `\u2705 ${dblClick ? "Double-clicked" : "Clicked"} element with UID "${uid}"`
-      );
+      return successResponse(`\u2705 ${dblClick ? "dblclick" : "click"} ${uid}`);
     } catch (error) {
       throw handleUidError(error, uid);
     }
@@ -14707,7 +14756,7 @@ async function handleHoverByUid(args2) {
     const firefox3 = await getFirefox2();
     try {
       await firefox3.hoverByUid(uid);
-      return successResponse(`\u2705 Hovered over element with UID "${uid}"`);
+      return successResponse(`\u2705 hover ${uid}`);
     } catch (error) {
       throw handleUidError(error, uid);
     }
@@ -14728,10 +14777,7 @@ async function handleFillByUid(args2) {
     const firefox3 = await getFirefox2();
     try {
       await firefox3.fillByUid(uid, value);
-      return successResponse(
-        `\u2705 Filled element with UID "${uid}"
-Value: ${value.substring(0, 50)}${value.length > 50 ? "..." : ""}`
-      );
+      return successResponse(`\u2705 fill ${uid}`);
     } catch (error) {
       throw handleUidError(error, uid);
     }
@@ -14752,16 +14798,11 @@ async function handleDragByUidToUid(args2) {
     const firefox3 = await getFirefox2();
     try {
       await firefox3.dragByUidToUid(fromUid, toUid);
-      return successResponse(`\u2705 Dragged element "${fromUid}" to "${toUid}"`);
+      return successResponse(`\u2705 drag ${fromUid}\u2192${toUid}`);
     } catch (error) {
       const errorMsg = error.message;
       if (errorMsg.includes("stale") || errorMsg.includes("Snapshot") || errorMsg.includes("UID")) {
-        throw new Error(
-          `One or both UIDs (from: "${fromUid}", to: "${toUid}") are stale or invalid.
-
-The page may have changed since the snapshot was taken.
-Please call take_snapshot to get fresh UIDs and try again.`
-        );
+        throw new Error(`UIDs stale/invalid. Call take_snapshot first.`);
       }
       throw error;
     }
@@ -14787,21 +14828,11 @@ async function handleFillFormByUid(args2) {
     const firefox3 = await getFirefox2();
     try {
       await firefox3.fillFormByUid(elements);
-      return successResponse(
-        `\u2705 Filled ${elements.length} form field(s):
-` + elements.map(
-          (el) => `  - ${el.uid}: ${el.value.substring(0, 30)}${el.value.length > 30 ? "..." : ""}`
-        ).join("\n")
-      );
+      return successResponse(`\u2705 filled ${elements.length} fields`);
     } catch (error) {
       const errorMsg = error.message;
       if (errorMsg.includes("stale") || errorMsg.includes("Snapshot") || errorMsg.includes("UID")) {
-        throw new Error(
-          `One or more UIDs are stale or invalid.
-
-The page may have changed since the snapshot was taken.
-Please call take_snapshot to get fresh UIDs and try again.`
-        );
+        throw new Error(`UIDs stale/invalid. Call take_snapshot first.`);
       }
       throw error;
     }
@@ -14822,26 +14853,17 @@ async function handleUploadFileByUid(args2) {
     const firefox3 = await getFirefox2();
     try {
       await firefox3.uploadFileByUid(uid, filePath);
-      return successResponse(`\u2705 Uploaded file to element with UID "${uid}"
-File: ${filePath}`);
+      return successResponse(`\u2705 upload ${uid}`);
     } catch (error) {
       const errorMsg = error.message;
       if (errorMsg.includes("stale") || errorMsg.includes("Snapshot") || errorMsg.includes("UID")) {
         throw handleUidError(error, uid);
       }
       if (errorMsg.includes("not a file input") || errorMsg.includes('type="file"')) {
-        throw new Error(
-          `Element with UID "${uid}" is not an <input type="file"> element.
-
-Please ensure the UID points to a file input element.`
-        );
+        throw new Error(`${uid} is not a file input`);
       }
       if (errorMsg.includes("hidden") || errorMsg.includes("not visible")) {
-        throw new Error(
-          `File input element with UID "${uid}" is hidden or not interactable.
-
-Some file inputs are hidden and cannot be directly interacted with.`
-        );
+        throw new Error(`${uid} is hidden/not interactable`);
       }
       throw error;
     }
@@ -14854,19 +14876,20 @@ var init_input = __esm({
   "src/tools/input.ts"() {
     "use strict";
     init_response_helpers();
+    init_uid_helpers();
     clickByUidTool = {
       name: "click_by_uid",
-      description: "Click an element identified by its UID. Supports double-click via dblClick=true. TIP: Take a fresh snapshot if the UID becomes stale.",
+      description: "Click element by UID. Set dblClick for double-click.",
       inputSchema: {
         type: "object",
         properties: {
           uid: {
             type: "string",
-            description: "The UID of the element to click"
+            description: "Element UID from snapshot"
           },
           dblClick: {
             type: "boolean",
-            description: "If true, performs a double-click (default: false)"
+            description: "Double-click (default: false)"
           }
         },
         required: ["uid"]
@@ -14874,13 +14897,13 @@ var init_input = __esm({
     };
     hoverByUidTool = {
       name: "hover_by_uid",
-      description: "Hover over an element identified by its UID. TIP: Take a fresh snapshot if the UID becomes stale.",
+      description: "Hover over element by UID.",
       inputSchema: {
         type: "object",
         properties: {
           uid: {
             type: "string",
-            description: "The UID of the element to hover over"
+            description: "Element UID from snapshot"
           }
         },
         required: ["uid"]
@@ -14888,17 +14911,17 @@ var init_input = __esm({
     };
     fillByUidTool = {
       name: "fill_by_uid",
-      description: "Fill a text input or textarea identified by its UID. Keep values short and safe. TIP: Take a fresh snapshot if the UID becomes stale.",
+      description: "Fill text input/textarea by UID.",
       inputSchema: {
         type: "object",
         properties: {
           uid: {
             type: "string",
-            description: "The UID of the input element"
+            description: "Input element UID from snapshot"
           },
           value: {
             type: "string",
-            description: "The text value to fill into the input"
+            description: "Text to fill"
           }
         },
         required: ["uid", "value"]
@@ -14906,17 +14929,17 @@ var init_input = __esm({
     };
     dragByUidToUidTool = {
       name: "drag_by_uid_to_uid",
-      description: "Simulate HTML5 drag-and-drop from one UID to another using JS drag events. May not work with all custom libraries.",
+      description: "Drag element to another (HTML5 drag events).",
       inputSchema: {
         type: "object",
         properties: {
           fromUid: {
             type: "string",
-            description: "The UID of the element to drag"
+            description: "Source element UID"
           },
           toUid: {
             type: "string",
-            description: "The UID of the target element to drop onto"
+            description: "Target element UID"
           }
         },
         required: ["fromUid", "toUid"]
@@ -14924,23 +14947,23 @@ var init_input = __esm({
     };
     fillFormByUidTool = {
       name: "fill_form_by_uid",
-      description: "Fill multiple form fields in one call using an array of {uid, value} pairs.",
+      description: "Fill multiple form fields at once.",
       inputSchema: {
         type: "object",
         properties: {
           elements: {
             type: "array",
-            description: "Array of form field UIDs with their values",
+            description: "Array of {uid, value} pairs",
             items: {
               type: "object",
               properties: {
                 uid: {
                   type: "string",
-                  description: "The UID of the form field"
+                  description: "Field UID"
                 },
                 value: {
                   type: "string",
-                  description: "The value to fill"
+                  description: "Field value"
                 }
               },
               required: ["uid", "value"]
@@ -14952,17 +14975,17 @@ var init_input = __esm({
     };
     uploadFileByUidTool = {
       name: "upload_file_by_uid",
-      description: 'Upload a file into an <input type="file"> element identified by its UID. The file path must be accessible to the server.',
+      description: "Upload file to file input by UID.",
       inputSchema: {
         type: "object",
         properties: {
           uid: {
             type: "string",
-            description: "The UID of the file input element"
+            description: "File input UID from snapshot"
           },
           filePath: {
             type: "string",
-            description: "Local filesystem path to the file to upload"
+            description: "Local file path"
           }
         },
         required: ["uid", "filePath"]
@@ -14972,60 +14995,46 @@ var init_input = __esm({
 });
 
 // src/tools/screenshot.ts
+function buildScreenshotResponse(base64Png, label) {
+  const sizeKB = Math.round(base64Png.length / 1024);
+  if (base64Png.length > TOKEN_LIMITS.MAX_SCREENSHOT_CHARS) {
+    const truncatedData = base64Png.slice(0, TOKEN_LIMITS.MAX_SCREENSHOT_CHARS);
+    return successResponse(`\u{1F4F8} ${label} (${sizeKB}KB) [truncated]
+${truncatedData}`);
+  }
+  const warn = base64Png.length > TOKEN_LIMITS.WARNING_THRESHOLD_CHARS ? " [large]" : "";
+  return successResponse(`\u{1F4F8} ${label} (${sizeKB}KB)${warn}
+${base64Png}`);
+}
 async function handleScreenshotPage(_args) {
   try {
     const { getFirefox: getFirefox2 } = await init_index().then(() => index_exports);
     const firefox3 = await getFirefox2();
     const base64Png = await firefox3.takeScreenshotPage();
     if (!base64Png || typeof base64Png !== "string") {
-      throw new Error("Failed to capture screenshot: invalid data returned");
+      throw new Error("Invalid screenshot data");
     }
-    return successResponse(
-      `\u{1F4F8} Page screenshot captured (${Math.round(base64Png.length / 1024)}KB)
-
-Base64 PNG data:
-${base64Png}`
-    );
+    return buildScreenshotResponse(base64Png, "page");
   } catch (error) {
-    return errorResponse(
-      new Error(
-        `Failed to capture page screenshot: ${error.message}
-
-The page may not be fully loaded or accessible.`
-      )
-    );
+    return errorResponse(error);
   }
 }
 async function handleScreenshotByUid(args2) {
   try {
     const { uid } = args2;
     if (!uid || typeof uid !== "string") {
-      throw new Error("uid parameter is required and must be a string");
+      throw new Error("uid required");
     }
     const { getFirefox: getFirefox2 } = await init_index().then(() => index_exports);
     const firefox3 = await getFirefox2();
     try {
       const base64Png = await firefox3.takeScreenshotByUid(uid);
       if (!base64Png || typeof base64Png !== "string") {
-        throw new Error("Failed to capture screenshot: invalid data returned");
+        throw new Error("Invalid screenshot data");
       }
-      return successResponse(
-        `\u{1F4F8} Element screenshot captured for UID "${uid}" (${Math.round(base64Png.length / 1024)}KB)
-
-Base64 PNG data:
-${base64Png}`
-      );
+      return buildScreenshotResponse(base64Png, uid);
     } catch (error) {
-      const errorMsg = error.message;
-      if (errorMsg.includes("stale") || errorMsg.includes("Snapshot") || errorMsg.includes("UID") || errorMsg.includes("not found")) {
-        throw new Error(
-          `UID "${uid}" is stale or invalid.
-
-The page may have changed since the snapshot was taken.
-Please call take_snapshot to get fresh UIDs and try again.`
-        );
-      }
-      throw error;
+      throw handleUidError(error, uid);
     }
   } catch (error) {
     return errorResponse(error);
@@ -15036,9 +15045,10 @@ var init_screenshot = __esm({
   "src/tools/screenshot.ts"() {
     "use strict";
     init_response_helpers();
+    init_uid_helpers();
     screenshotPageTool = {
       name: "screenshot_page",
-      description: "Capture a PNG screenshot of the current page and return it as a base64 string (without data: prefix). TIP: Use for visual verification rather than structural inspection.",
+      description: "Capture page screenshot as base64 PNG.",
       inputSchema: {
         type: "object",
         properties: {}
@@ -15046,13 +15056,13 @@ var init_screenshot = __esm({
     };
     screenshotByUidTool = {
       name: "screenshot_by_uid",
-      description: "Capture a PNG screenshot of a specific element by UID and return it as a base64 string (without data: prefix). TIP: Take a fresh snapshot if the UID is stale.",
+      description: "Capture element screenshot by UID as base64 PNG.",
       inputSchema: {
         type: "object",
         properties: {
           uid: {
             type: "string",
-            description: "The UID of the element to screenshot"
+            description: "Element UID from snapshot"
           }
         },
         required: ["uid"]
@@ -15069,17 +15079,11 @@ async function handleAcceptDialog(args2) {
     const firefox3 = await getFirefox2();
     try {
       await firefox3.acceptDialog(promptText);
-      let message = "\u2705 Dialog accepted";
-      if (promptText) {
-        message += ` with text: "${promptText}"`;
-      }
-      return successResponse(message);
+      return successResponse(promptText ? `\u2705 Accepted: "${promptText}"` : "\u2705 Accepted");
     } catch (error) {
       const errorMsg = error.message;
       if (errorMsg.includes("no such alert") || errorMsg.includes("No dialog")) {
-        throw new Error(
-          "No active dialog found.\n\nDialogs must be accepted shortly after they appear. Make sure a dialog is currently visible on the page."
-        );
+        throw new Error("No active dialog");
       }
       throw error;
     }
@@ -15093,13 +15097,11 @@ async function handleDismissDialog(_args) {
     const firefox3 = await getFirefox2();
     try {
       await firefox3.dismissDialog();
-      return successResponse("\u2705 Dialog dismissed/cancelled");
+      return successResponse("\u2705 Dismissed");
     } catch (error) {
       const errorMsg = error.message;
       if (errorMsg.includes("no such alert") || errorMsg.includes("No dialog")) {
-        throw new Error(
-          "No active dialog found.\n\nDialogs must be dismissed shortly after they appear. Make sure a dialog is currently visible on the page."
-        );
+        throw new Error("No active dialog");
       }
       throw error;
     }
@@ -15120,19 +15122,9 @@ async function handleNavigateHistory(args2) {
     } else {
       await firefox3.navigateForward();
     }
-    return successResponse(
-      `\u2705 Navigated ${direction} in history
-
-\u26A0\uFE0F  UIDs from previous snapshots are now stale. Call take_snapshot before using UID-based actions.`
-    );
+    return successResponse(`\u2705 ${direction}`);
   } catch (error) {
-    return errorResponse(
-      new Error(
-        `Failed to navigate ${args2.direction || "in history"}: ${error.message}
-
-The page may not have history in this direction available.`
-      )
-    );
+    return errorResponse(error);
   }
 }
 async function handleSetViewportSize(args2) {
@@ -15147,19 +15139,9 @@ async function handleSetViewportSize(args2) {
     const { getFirefox: getFirefox2 } = await init_index().then(() => index_exports);
     const firefox3 = await getFirefox2();
     await firefox3.setViewportSize(width, height);
-    return successResponse(
-      `\u2705 Viewport size set to ${width}x${height} pixels
-
-NOTE: Actual viewport may differ slightly in some browser modes (e.g., headless).`
-    );
+    return successResponse(`\u2705 ${width}x${height}`);
   } catch (error) {
-    return errorResponse(
-      new Error(
-        `Failed to set viewport size: ${error.message}
-
-Some browser configurations may not support precise viewport sizing.`
-      )
-    );
+    return errorResponse(error);
   }
 }
 var acceptDialogTool, dismissDialogTool, navigateHistoryTool, setViewportSizeTool;
@@ -15169,20 +15151,20 @@ var init_utilities = __esm({
     init_response_helpers();
     acceptDialogTool = {
       name: "accept_dialog",
-      description: "Accept the active browser dialog (alert/confirm/prompt). For prompts, you may provide promptText. Returns an error if no dialog is open.",
+      description: "Accept browser dialog. Provide promptText for prompts.",
       inputSchema: {
         type: "object",
         properties: {
           promptText: {
             type: "string",
-            description: "Text to enter in a prompt dialog (optional, only for prompt dialogs)"
+            description: "Text for prompt dialogs"
           }
         }
       }
     };
     dismissDialogTool = {
       name: "dismiss_dialog",
-      description: "Dismiss the active browser dialog (alert/confirm/prompt). Returns an error if no dialog is open.",
+      description: "Dismiss browser dialog.",
       inputSchema: {
         type: "object",
         properties: {}
@@ -15190,14 +15172,14 @@ var init_utilities = __esm({
     };
     navigateHistoryTool = {
       name: "navigate_history",
-      description: "Navigate the selected tab's history back or forward. NOTE: After navigation, UIDs from previous snapshots are stale\u2014take a new snapshot before UID-based actions.",
+      description: "Navigate history back/forward. UIDs become stale.",
       inputSchema: {
         type: "object",
         properties: {
           direction: {
             type: "string",
             enum: ["back", "forward"],
-            description: "Direction to navigate in history"
+            description: "back or forward"
           }
         },
         required: ["direction"]
@@ -15205,17 +15187,17 @@ var init_utilities = __esm({
     };
     setViewportSizeTool = {
       name: "set_viewport_size",
-      description: "Set the browser viewport size (width x height in pixels). In some modes (e.g., headless), the actual size may vary slightly.",
+      description: "Set viewport dimensions in pixels.",
       inputSchema: {
         type: "object",
         properties: {
           width: {
             type: "number",
-            description: "Viewport width in pixels"
+            description: "Width in pixels"
           },
           height: {
             type: "number",
-            description: "Viewport height in pixels"
+            description: "Height in pixels"
           }
         },
         required: ["width", "height"]
@@ -15238,6 +15220,33 @@ var init_tools = __esm({
   }
 });
 
+// src/utils/errors.ts
+function isDisconnectionError(error) {
+  if (error instanceof FirefoxDisconnectedError) {
+    return true;
+  }
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    return message.includes("session deleted") || message.includes("session not created") || message.includes("no such window") || message.includes("no such session") || message.includes("target window already closed") || message.includes("unable to connect") || message.includes("connection refused") || message.includes("not connected") || message.includes("driver not connected") || message.includes("invalid session id") || message.includes("browsing context has been discarded");
+  }
+  return false;
+}
+var FirefoxDisconnectedError;
+var init_errors2 = __esm({
+  "src/utils/errors.ts"() {
+    "use strict";
+    FirefoxDisconnectedError = class extends Error {
+      constructor(reason) {
+        const baseMessage = "Firefox browser is not connected";
+        const instruction = "The Firefox browser window was closed by the user. To continue browser automation, ask the user to restart the firefox-devtools-mcp server (they need to restart Claude Code or the MCP connection). This will launch a new Firefox instance.";
+        const fullMessage = reason ? `${baseMessage}: ${reason}. ${instruction}` : `${baseMessage}. ${instruction}`;
+        super(fullMessage);
+        this.name = "FirefoxDisconnectedError";
+      }
+    };
+  }
+});
+
 // node_modules/dotenv/package.json
 var require_package = __commonJS({
   "node_modules/dotenv/package.json"(exports, module) {
@@ -15640,28 +15649,46 @@ var require_main = __commonJS({
 var index_exports = {};
 __export(index_exports, {
   FirefoxDevTools: () => FirefoxClient,
+  FirefoxDisconnectedError: () => FirefoxDisconnectedError,
   args: () => args,
-  getFirefox: () => getFirefox
+  getFirefox: () => getFirefox,
+  isDisconnectionError: () => isDisconnectionError,
+  resetFirefox: () => resetFirefox
 });
 import { version } from "process";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { resolve as resolve2 } from "path";
 import { realpathSync } from "fs";
-async function getFirefox() {
-  if (!firefox2) {
-    log("Initializing Firefox DevTools connection...");
-    const options = {
-      firefoxPath: args.firefoxPath ?? void 0,
-      headless: args.headless,
-      profilePath: args.profilePath ?? void 0,
-      viewport: args.viewport ?? void 0,
-      args: args.firefoxArg ?? void 0,
-      startUrl: args.startUrl ?? void 0
-    };
-    firefox2 = new FirefoxClient(options);
-    await firefox2.connect();
-    log("Firefox DevTools connection established");
+function resetFirefox() {
+  if (firefox2) {
+    firefox2.reset();
+    firefox2 = null;
   }
+  log("Firefox instance reset - will reconnect on next tool call");
+}
+async function getFirefox() {
+  if (firefox2) {
+    const isConnected = await firefox2.isConnected();
+    if (!isConnected) {
+      log("Firefox connection lost - browser was closed or disconnected");
+      resetFirefox();
+      throw new FirefoxDisconnectedError("Browser was closed");
+    }
+    return firefox2;
+  }
+  log("Initializing Firefox DevTools connection...");
+  const options = {
+    firefoxPath: args.firefoxPath ?? void 0,
+    headless: args.headless,
+    profilePath: args.profilePath ?? void 0,
+    viewport: args.viewport ?? void 0,
+    args: args.firefoxArg ?? void 0,
+    startUrl: args.startUrl ?? void 0,
+    acceptInsecureCerts: args.acceptInsecureCerts
+  };
+  firefox2 = new FirefoxClient(options);
+  await firefox2.connect();
+  log("Firefox DevTools connection established");
   return firefox2;
 }
 async function main() {
@@ -15729,7 +15756,9 @@ var init_index = __esm({
     init_cli();
     init_firefox();
     init_tools();
+    init_errors2();
     init_firefox();
+    init_errors2();
     if (process.env.NODE_ENV !== "production") {
       try {
         const { config } = await Promise.resolve().then(() => __toESM(require_main(), 1));
@@ -15829,8 +15858,11 @@ var init_index = __esm({
 await init_index();
 export {
   FirefoxClient as FirefoxDevTools,
+  FirefoxDisconnectedError,
   args,
-  getFirefox
+  getFirefox,
+  isDisconnectionError,
+  resetFirefox
 };
 /*! Bundled license information: