@hasna/browser 0.0.3 → 0.0.4

package/dist/cli/index.js

@@ -2121,6 +2121,12 @@ var init_types = __esm(() => {
 });
 
 // src/db/schema.ts
+var exports_schema = {};
+__export(exports_schema, {
+  resetDatabase: () => resetDatabase,
+  getDatabase: () => getDatabase,
+  getDataDir: () => getDataDir
+});
 import { Database } from "bun:sqlite";
 import { join } from "path";
 import { mkdirSync } from "fs";
@@ -2146,6 +2152,15 @@ function getDatabase(path) {
   runMigrations(_db);
   return _db;
 }
+function resetDatabase() {
+  if (_db) {
+    try {
+      _db.close();
+    } catch {}
+  }
+  _db = null;
+  _dbPath = null;
+}
 function runMigrations(db) {
   db.exec(`
     CREATE TABLE IF NOT EXISTS schema_migrations (
@@ -2313,7 +2328,14 @@ import { randomUUID } from "crypto";
 function createSession(data) {
   const db = getDatabase();
   const id = randomUUID();
-  db.prepare("INSERT INTO sessions (id, engine, project_id, agent_id, start_url, name) VALUES (?, ?, ?, ?, ?, ?)").run(id, data.engine, data.projectId ?? null, data.agentId ?? null, data.startUrl ?? null, data.name ?? null);
+  let name = data.name ?? null;
+  if (name) {
+    const existing = db.query("SELECT id FROM sessions WHERE name = ?").get(name);
+    if (existing) {
+      name = `${name}-${id.slice(0, 6)}`;
+    }
+  }
+  db.prepare("INSERT INTO sessions (id, engine, project_id, agent_id, start_url, name) VALUES (?, ?, ?, ?, ?, ?)").run(id, data.engine, data.projectId ?? null, data.agentId ?? null, data.startUrl ?? null, name);
   return getSession(id);
 }
 function getSessionByName(name) {
@@ -2876,12 +2898,19 @@ async function createSession2(opts = {}) {
       userAgent: opts.userAgent
     });
   }
+  let sessionName = opts.name ?? (opts.startUrl ? (() => {
+    try {
+      return new URL(opts.startUrl).hostname;
+    } catch {
+      return;
+    }
+  })() : undefined);
   const session = createSession({
     engine: resolvedEngine,
     projectId: opts.projectId,
     agentId: opts.agentId,
     startUrl: opts.startUrl,
-    name: opts.name ?? (opts.startUrl ? new URL(opts.startUrl).hostname : undefined)
+    name: sessionName
   });
   if (opts.stealth) {
     try {
@@ -2978,12 +3007,28 @@ var init_session = __esm(() => {
 });
 
 // src/lib/snapshot.ts
+var exports_snapshot = {};
+__export(exports_snapshot, {
+  takeSnapshot: () => takeSnapshot,
+  setLastSnapshot: () => setLastSnapshot,
+  hasRefs: () => hasRefs,
+  getSessionRefs: () => getSessionRefs,
+  getRefLocator: () => getRefLocator,
+  getRefInfo: () => getRefInfo,
+  getLastSnapshot: () => getLastSnapshot,
+  diffSnapshots: () => diffSnapshots,
+  clearSessionRefs: () => clearSessionRefs,
+  clearLastSnapshot: () => clearLastSnapshot
+});
 function getLastSnapshot(sessionId) {
   return lastSnapshots.get(sessionId) ?? null;
 }
 function setLastSnapshot(sessionId, snapshot) {
   lastSnapshots.set(sessionId, snapshot);
 }
+function clearLastSnapshot(sessionId) {
+  lastSnapshots.delete(sessionId);
+}
 async function takeSnapshot(page, sessionId) {
   let ariaTree;
   try {
@@ -3086,6 +3131,21 @@ function getRefLocator(page, sessionId, ref) {
     throw new Error(`Ref ${ref} not found. Available refs: ${[...refMap.keys()].slice(0, 20).join(", ")}`);
   return page.getByRole(entry.role, { name: entry.name }).first();
 }
+function getRefInfo(sessionId, ref) {
+  const refMap = sessionRefMaps.get(sessionId);
+  if (!refMap)
+    return null;
+  return refMap.get(ref) ?? null;
+}
+function getSessionRefs(sessionId) {
+  return sessionRefMaps.get(sessionId) ?? null;
+}
+function clearSessionRefs(sessionId) {
+  sessionRefMaps.delete(sessionId);
+}
+function hasRefs(sessionId) {
+  return sessionRefMaps.has(sessionId) && (sessionRefMaps.get(sessionId)?.size ?? 0) > 0;
+}
 function refKey(info) {
   return `${info.role}::${info.name}`;
 }
@@ -10166,11 +10226,20 @@ async function takeScreenshot(page, opts) {
     }
     const originalSizeBytes = rawBuffer.length;
     let finalBuffer;
-    if (compress && format !== "png") {
-      finalBuffer = await compressBuffer(rawBuffer, format, quality ?? 82, maxWidth);
-    } else if (compress && format === "png") {
-      finalBuffer = await compressBuffer(rawBuffer, "png", quality ?? 9, maxWidth);
-    } else {
+    let compressed = true;
+    let fallback = false;
+    try {
+      if (compress && format !== "png") {
+        finalBuffer = await compressBuffer(rawBuffer, format, quality ?? 82, maxWidth);
+      } else if (compress && format === "png") {
+        finalBuffer = await compressBuffer(rawBuffer, "png", quality ?? 9, maxWidth);
+      } else {
+        finalBuffer = rawBuffer;
+        compressed = false;
+      }
+    } catch (sharpErr) {
+      fallback = true;
+      compressed = false;
       finalBuffer = rawBuffer;
     }
     const compressedSizeBytes = finalBuffer.length;
@@ -10198,7 +10267,8 @@ async function takeScreenshot(page, opts) {
       compressed_size_bytes: compressedSizeBytes,
       compression_ratio: compressionRatio,
       thumbnail_path: thumbnailPath,
-      thumbnail_base64: thumbnailBase64
+      thumbnail_base64: thumbnailBase64,
+      ...fallback ? { fallback: true, compressed: false } : {}
     };
     if (opts?.track !== false) {
       try {
@@ -15298,7 +15368,8 @@ async function annotateScreenshot(page, sessionId) {
   const annotations = [];
   const labelToRef = {};
   let labelCounter = 1;
-  for (const [ref, info] of Object.entries(snapshot.refs)) {
+  const refsToAnnotate = Object.entries(snapshot.refs).slice(0, MAX_ANNOTATIONS);
+  for (const [ref, info] of refsToAnnotate) {
     try {
       const locator = page.getByRole(info.role, { name: info.name }).first();
       const box = await locator.boundingBox();
@@ -15337,7 +15408,7 @@ async function annotateScreenshot(page, sessionId) {
   const annotatedBuffer = await import_sharp3.default(rawBuffer).composite([{ input: Buffer.from(svg), top: 0, left: 0 }]).webp({ quality: 85 }).toBuffer();
   return { buffer: annotatedBuffer, annotations, labelToRef };
 }
-var import_sharp3;
+var import_sharp3, MAX_ANNOTATIONS = 40;
 var init_annotate = __esm(() => {
   init_snapshot();
   import_sharp3 = __toESM(require_lib(), 1);
@@ -15347,6 +15418,8 @@ var init_annotate = __esm(() => {
 var exports_mcp = {};
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { readFileSync as readFileSync3 } from "fs";
+import { join as join7 } from "path";
 function json(data) {
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }
@@ -15358,7 +15431,7 @@ function err(e) {
     isError: true
   };
 }
-var networkLogCleanup, consoleCaptureCleanup, harCaptures, server, activeWatchHandles, transport;
+var _pkg, networkLogCleanup, consoleCaptureCleanup, harCaptures, server, activeWatchHandles, _startupToolCount, transport;
 var init_mcp = __esm(async () => {
   init_zod();
   init_session();
@@ -15382,6 +15455,7 @@ var init_mcp = __esm(async () => {
   init_dialogs();
   init_profiles();
   init_types();
+  _pkg = JSON.parse(readFileSync3(join7(import.meta.dir, "../../package.json"), "utf8"));
   networkLogCleanup = new Map;
   consoleCaptureCleanup = new Map;
   harCaptures = new Map;
@@ -15436,13 +15510,50 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_navigate", "Navigate to a URL. Returns title + thumbnail + accessibility snapshot preview with refs.", { session_id: exports_external.string(), url: exports_external.string(), timeout: exports_external.number().optional().default(30000), auto_snapshot: exports_external.boolean().optional().default(true), auto_thumbnail: exports_external.boolean().optional().default(true) }, async ({ session_id, url, timeout, auto_snapshot, auto_thumbnail }) => {
+  server.tool("browser_navigate", "Navigate to a URL. Auto-detects redirects, auto-names session, returns compact refs + thumbnail.", {
+    session_id: exports_external.string(),
+    url: exports_external.string(),
+    timeout: exports_external.number().optional().default(30000),
+    auto_snapshot: exports_external.boolean().optional().default(true),
+    auto_thumbnail: exports_external.boolean().optional().default(true)
+  }, async ({ session_id, url, timeout, auto_snapshot, auto_thumbnail }) => {
     try {
       const page = getSessionPage(session_id);
       await navigate(page, url, timeout);
       const title = await getTitle(page);
       const current_url = await getUrl(page);
-      const result = { url, title, current_url };
+      const redirected = current_url !== url && current_url !== url + "/" && url !== current_url.replace(/\/$/, "");
+      let redirect_type;
+      if (redirected) {
+        try {
+          const reqHost = new URL(url).hostname;
+          const resHost = new URL(current_url).hostname;
+          const reqPath = new URL(url).pathname;
+          const resPath = new URL(current_url).pathname;
+          if (reqHost !== resHost)
+            redirect_type = "canonical";
+          else if (resPath.match(/\/[a-z]{2}-[a-z]{2}\//))
+            redirect_type = "geo";
+          else if (current_url.includes("login") || current_url.includes("signin"))
+            redirect_type = "auth";
+          else
+            redirect_type = "unknown";
+        } catch {}
+      }
+      try {
+        const session = getSession2(session_id);
+        if (!session.name) {
+          const hostname = new URL(current_url).hostname;
+          renameSession2(session_id, hostname);
+        }
+      } catch {}
+      const result = {
+        url,
+        title,
+        current_url,
+        redirected,
+        ...redirect_type ? { redirect_type } : {}
+      };
       if (auto_thumbnail) {
         try {
           const ss = await takeScreenshot(page, { maxWidth: 400, quality: 60, track: false, thumbnail: false });
@@ -15452,7 +15563,9 @@ var init_mcp = __esm(async () => {
       if (auto_snapshot) {
         try {
           const snap = await takeSnapshot(page, session_id);
-          result.snapshot_preview = snap.tree.slice(0, 3000);
+          setLastSnapshot(session_id, snap);
+          const refEntries = Object.entries(snap.refs).slice(0, 30);
+          result.snapshot_refs = refEntries.map(([ref, info]) => `${info.role}:${info.name.slice(0, 50)} [${ref}]`).join(", ");
           result.interactive_count = snap.interactive_count;
           result.has_errors = getConsoleLog(session_id, "error").length > 0;
         } catch {}
@@ -15558,7 +15671,7 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_check", "Check or uncheck a checkbox by ref or selector", { session_id: exports_external.string(), selector: exports_external.string().optional(), ref: exports_external.string().optional(), checked: exports_external.boolean() }, async ({ session_id, selector, ref, checked }) => {
+  server.tool("browser_toggle", "Check or uncheck a checkbox by ref or selector", { session_id: exports_external.string(), selector: exports_external.string().optional(), ref: exports_external.string().optional(), checked: exports_external.boolean() }, async ({ session_id, selector, ref, checked }) => {
     try {
       const page = getSessionPage(session_id);
       if (ref) {
@@ -15649,12 +15762,33 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_snapshot", "Get a structured accessibility snapshot with element refs (@e0, @e1...). Use refs in browser_click, browser_type, etc.", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_snapshot", "Get accessibility snapshot with element refs (@e0, @e1...). Use compact=true (default) for token-efficient output. Use refs in browser_click, browser_type, etc.", {
+    session_id: exports_external.string(),
+    compact: exports_external.boolean().optional().default(true),
+    max_refs: exports_external.number().optional().default(50),
+    full_tree: exports_external.boolean().optional().default(false)
+  }, async ({ session_id, compact, max_refs, full_tree }) => {
     try {
       const page = getSessionPage(session_id);
       const result = await takeSnapshot(page, session_id);
       setLastSnapshot(session_id, result);
-      return json({ snapshot: result.tree, refs: result.refs, interactive_count: result.interactive_count });
+      const refEntries = Object.entries(result.refs).slice(0, max_refs);
+      const limitedRefs = Object.fromEntries(refEntries);
+      const truncated = Object.keys(result.refs).length > max_refs;
+      if (compact && !full_tree) {
+        const compactRefs = refEntries.map(([ref, info]) => `${info.role}:${info.name.slice(0, 60)} [${ref}]${info.checked !== undefined ? ` checked=${info.checked}` : ""}${!info.enabled ? " disabled" : ""}`).join(`
+`);
+        return json({
+          snapshot_compact: compactRefs,
+          interactive_count: result.interactive_count,
+          shown_count: refEntries.length,
+          truncated,
+          refs: limitedRefs
+        });
+      }
+      const tree = full_tree ? result.tree : result.tree.slice(0, 5000) + (result.tree.length > 5000 ? `
+... (truncated \u2014 use full_tree=true for complete)` : "");
+      return json({ snapshot: tree, refs: limitedRefs, interactive_count: result.interactive_count, truncated });
     } catch (e) {
       return err(e);
     }
@@ -16136,40 +16270,6 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_page_check", "One-call page summary: page info + console errors + performance metrics + thumbnail + accessibility snapshot preview. Replaces 4-5 separate tool calls.", { session_id: exports_external.string() }, async ({ session_id }) => {
-    try {
-      const page = getSessionPage(session_id);
-      const info = await getPageInfo(page);
-      const errors2 = getConsoleLog(session_id, "error");
-      info.has_console_errors = errors2.length > 0;
-      let perf = {};
-      try {
-        perf = await getPerformanceMetrics(page);
-      } catch {}
-      let thumbnail_base64 = "";
-      try {
-        const ss = await takeScreenshot(page, { maxWidth: 400, quality: 60, track: false, thumbnail: false });
-        thumbnail_base64 = ss.base64;
-      } catch {}
-      let snapshot_preview = "";
-      let interactive_count = 0;
-      try {
-        const snap = await takeSnapshot(page, session_id);
-        snapshot_preview = snap.tree.slice(0, 2000);
-        interactive_count = snap.interactive_count;
-      } catch {}
-      return json({
-        ...info,
-        error_count: errors2.length,
-        performance: perf,
-        thumbnail_base64: thumbnail_base64.length > 50000 ? "" : thumbnail_base64,
-        snapshot_preview,
-        interactive_count
-      });
-    } catch (e) {
-      return err(e);
-    }
-  });
   server.tool("browser_gallery_list", "List screenshot gallery entries with optional filters", {
     project_id: exports_external.string().optional(),
     session_id: exports_external.string().optional(),
@@ -16494,7 +16594,7 @@ var init_mcp = __esm(async () => {
           { tool: "browser_hover", description: "Hover over an element" },
           { tool: "browser_scroll", description: "Scroll the page" },
           { tool: "browser_select", description: "Select a dropdown option" },
-          { tool: "browser_check", description: "Check/uncheck a checkbox" },
+          { tool: "browser_toggle", description: "Check/uncheck a checkbox" },
           { tool: "browser_upload", description: "Upload a file to an input" },
           { tool: "browser_press_key", description: "Press a keyboard key" },
           { tool: "browser_wait", description: "Wait for a selector to appear" },
@@ -16514,9 +16614,10 @@ var init_mcp = __esm(async () => {
           { tool: "browser_evaluate", description: "Execute JavaScript in page context" }
         ],
         Capture: [
-          { tool: "browser_screenshot", description: "Take a screenshot (PNG/JPEG/WebP)" },
+          { tool: "browser_screenshot", description: "Take a screenshot (PNG/JPEG/WebP, annotate=true for labels)" },
           { tool: "browser_pdf", description: "Generate a PDF of the page" },
-          { tool: "browser_scroll_and_screenshot", description: "Scroll then screenshot in one call" }
+          { tool: "browser_scroll_and_screenshot", description: "Scroll then screenshot in one call" },
+          { tool: "browser_scroll_to_element", description: "Scroll element into view + screenshot" }
         ],
         Storage: [
           { tool: "browser_cookies_get", description: "Get cookies" },
@@ -16595,7 +16696,8 @@ var init_mcp = __esm(async () => {
           { tool: "browser_tab_close", description: "Close a tab by index" }
         ],
         Meta: [
-          { tool: "browser_page_check", description: "One-call page summary with diagnostics" },
+          { tool: "browser_check", description: "RECOMMENDED: One-call page summary with diagnostics" },
+          { tool: "browser_version", description: "Show running binary version and tool count" },
           { tool: "browser_help", description: "Show this help (all tools)" },
           { tool: "browser_snapshot_diff", description: "Diff current snapshot vs previous" },
           { tool: "browser_watch_start", description: "Watch page for DOM changes" },
@@ -16609,6 +16711,88 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
+  server.tool("browser_version", "Get the running browser MCP version, tool count, and environment info. Use this to verify which binary is active.", {}, async () => {
+    try {
+      const { getDataDir: getDataDir4 } = await Promise.resolve().then(() => (init_schema(), exports_schema));
+      const toolCount = Object.keys(server._registeredTools ?? {}).length;
+      return json({
+        version: _pkg.version,
+        mcp_tools_count: toolCount,
+        bun_version: Bun.version,
+        data_dir: getDataDir4(),
+        node_env: process.env["NODE_ENV"] ?? "production"
+      });
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_scroll_to_element", "Scroll an element into view (by ref or selector) then optionally take a screenshot of it. Replaces scroll + wait + screenshot pattern.", {
+    session_id: exports_external.string(),
+    selector: exports_external.string().optional(),
+    ref: exports_external.string().optional(),
+    screenshot: exports_external.boolean().optional().default(true),
+    wait_ms: exports_external.number().optional().default(200)
+  }, async ({ session_id, selector, ref, screenshot: doScreenshot, wait_ms }) => {
+    try {
+      const page = getSessionPage(session_id);
+      let locator;
+      if (ref) {
+        const { getRefLocator: getRefLocator2 } = await Promise.resolve().then(() => (init_snapshot(), exports_snapshot));
+        locator = getRefLocator2(page, session_id, ref);
+      } else if (selector) {
+        locator = page.locator(selector).first();
+      } else {
+        return err(new Error("Either ref or selector is required"));
+      }
+      await locator.scrollIntoViewIfNeeded();
+      await new Promise((r) => setTimeout(r, wait_ms));
+      const result = { scrolled: ref ?? selector };
+      if (doScreenshot) {
+        try {
+          const ss = await takeScreenshot(page, { selector, track: false });
+          ss.url = page.url();
+          if (ss.base64.length > 50000) {
+            ss.base64_truncated = true;
+            ss.base64 = ss.thumbnail_base64 ?? "";
+          }
+          result.screenshot = ss;
+        } catch {}
+      }
+      return json(result);
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_check", "RECOMMENDED FIRST CALL: one-shot page summary \u2014 url, title, errors, performance, thumbnail, refs. Replaces 4+ separate tool calls.", { session_id: exports_external.string() }, async ({ session_id }) => {
+    try {
+      const page = getSessionPage(session_id);
+      const info = await getPageInfo(page);
+      const errors2 = getConsoleLog(session_id, "error");
+      info.has_console_errors = errors2.length > 0;
+      let perf = {};
+      try {
+        perf = await getPerformanceMetrics(page);
+      } catch {}
+      let thumbnail_base64 = "";
+      try {
+        const ss = await takeScreenshot(page, { maxWidth: 400, quality: 60, track: false, thumbnail: false });
+        thumbnail_base64 = ss.base64.length > 50000 ? "" : ss.base64;
+      } catch {}
+      let snapshot_refs = "";
+      let interactive_count = 0;
+      try {
+        const snap = await takeSnapshot(page, session_id);
+        setLastSnapshot(session_id, snap);
+        interactive_count = snap.interactive_count;
+        snapshot_refs = Object.entries(snap.refs).slice(0, 30).map(([ref, i]) => `${i.role}:${i.name.slice(0, 50)} [${ref}]`).join(", ");
+      } catch {}
+      return json({ ...info, error_count: errors2.length, performance: perf, thumbnail_base64, snapshot_refs, interactive_count });
+    } catch (e) {
+      return err(e);
+    }
+  });
+  _startupToolCount = Object.keys(server._registeredTools ?? {}).length;
+  console.error(`@hasna/browser v${_pkg.version} \u2014 ${_startupToolCount} tools | data: ${(await Promise.resolve().then(() => (init_schema(), exports_schema))).getDataDir()}`);
   transport = new StdioServerTransport;
   await server.connect(transport);
 });
@@ -16651,7 +16835,7 @@ var init_snapshots = __esm(() => {
 
 // src/server/index.ts
 var exports_server = {};
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 import { existsSync as existsSync4 } from "fs";
 function ok(data, status = 200) {
   return new Response(JSON.stringify(data), {
@@ -16945,13 +17129,13 @@ var init_server = __esm(() => {
           const id = path.split("/")[3];
           return ok({ deleted: deleteDownload(id) });
         }
-        const dashboardDist = join7(import.meta.dir, "../../dashboard/dist");
+        const dashboardDist = join8(import.meta.dir, "../../dashboard/dist");
         if (existsSync4(dashboardDist)) {
-          const filePath = path === "/" ? join7(dashboardDist, "index.html") : join7(dashboardDist, path);
+          const filePath = path === "/" ? join8(dashboardDist, "index.html") : join8(dashboardDist, path);
           if (existsSync4(filePath)) {
             return new Response(Bun.file(filePath), { headers: CORS_HEADERS });
           }
-          return new Response(Bun.file(join7(dashboardDist, "index.html")), { headers: CORS_HEADERS });
+          return new Response(Bun.file(join8(dashboardDist, "index.html")), { headers: CORS_HEADERS });
         }
         if (path === "/" || path === "") {
           return new Response("@hasna/browser REST API running. Dashboard not built.", {
@@ -16993,10 +17177,10 @@ init_projects();
 init_recorder();
 init_recordings();
 init_lightpanda();
-import { readFileSync as readFileSync3 } from "fs";
-import { join as join8 } from "path";
+import { readFileSync as readFileSync4 } from "fs";
+import { join as join9 } from "path";
 import chalk from "chalk";
-var pkg = JSON.parse(readFileSync3(join8(import.meta.dir, "../../package.json"), "utf8"));
+var pkg = JSON.parse(readFileSync4(join9(import.meta.dir, "../../package.json"), "utf8"));
 var program2 = new Command;
 program2.name("browser").description("@hasna/browser \u2014 general-purpose browser agent CLI").version(pkg.version);
 program2.command("navigate <url>").description("Navigate to a URL and optionally take a screenshot").option("--engine <engine>", "Browser engine: playwright|cdp|lightpanda|auto", "auto").option("--screenshot", "Take a screenshot after navigation").option("--extract", "Extract page text after navigation").option("--headless", "Run in headless mode (default: true)", true).action(async (url, opts) => {

package/dist/db/sessions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../src/db/sessions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAG/E,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAO9D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAG7D;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAI/D;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAK9C;AAED,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,aAAa,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,EAAE,CAQ/F;AAED,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAO9E;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAG9C"}
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../src/db/sessions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAG/E,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAiB9D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAG7D;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAI/D;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAK9C;AAED,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,aAAa,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,EAAE,CAQ/F;AAED,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAO9E;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAG9C"}

package/dist/index.js

@@ -6827,7 +6827,14 @@ import { randomUUID as randomUUID3 } from "crypto";
 function createSession(data) {
   const db = getDatabase();
   const id = randomUUID3();
-  db.prepare("INSERT INTO sessions (id, engine, project_id, agent_id, start_url, name) VALUES (?, ?, ?, ?, ?, ?)").run(id, data.engine, data.projectId ?? null, data.agentId ?? null, data.startUrl ?? null, data.name ?? null);
+  let name = data.name ?? null;
+  if (name) {
+    const existing = db.query("SELECT id FROM sessions WHERE name = ?").get(name);
+    if (existing) {
+      name = `${name}-${id.slice(0, 6)}`;
+    }
+  }
+  db.prepare("INSERT INTO sessions (id, engine, project_id, agent_id, start_url, name) VALUES (?, ?, ?, ?, ?, ?)").run(id, data.engine, data.projectId ?? null, data.agentId ?? null, data.startUrl ?? null, name);
   return getSession(id);
 }
 function getSessionByName(name) {
@@ -7728,12 +7735,19 @@ async function createSession2(opts = {}) {
       userAgent: opts.userAgent
     });
   }
+  let sessionName = opts.name ?? (opts.startUrl ? (() => {
+    try {
+      return new URL(opts.startUrl).hostname;
+    } catch {
+      return;
+    }
+  })() : undefined);
   const session = createSession({
     engine: resolvedEngine,
     projectId: opts.projectId,
     agentId: opts.agentId,
     startUrl: opts.startUrl,
-    name: opts.name ?? (opts.startUrl ? new URL(opts.startUrl).hostname : undefined)
+    name: sessionName
   });
   if (opts.stealth) {
     try {
@@ -8496,11 +8510,20 @@ async function takeScreenshot(page, opts) {
     }
     const originalSizeBytes = rawBuffer.length;
     let finalBuffer;
-    if (compress && format !== "png") {
-      finalBuffer = await compressBuffer(rawBuffer, format, quality ?? 82, maxWidth);
-    } else if (compress && format === "png") {
-      finalBuffer = await compressBuffer(rawBuffer, "png", quality ?? 9, maxWidth);
-    } else {
+    let compressed = true;
+    let fallback = false;
+    try {
+      if (compress && format !== "png") {
+        finalBuffer = await compressBuffer(rawBuffer, format, quality ?? 82, maxWidth);
+      } else if (compress && format === "png") {
+        finalBuffer = await compressBuffer(rawBuffer, "png", quality ?? 9, maxWidth);
+      } else {
+        finalBuffer = rawBuffer;
+        compressed = false;
+      }
+    } catch (sharpErr) {
+      fallback = true;
+      compressed = false;
       finalBuffer = rawBuffer;
     }
     const compressedSizeBytes = finalBuffer.length;
@@ -8528,7 +8551,8 @@ async function takeScreenshot(page, opts) {
       compressed_size_bytes: compressedSizeBytes,
       compression_ratio: compressionRatio,
       thumbnail_path: thumbnailPath,
-      thumbnail_base64: thumbnailBase64
+      thumbnail_base64: thumbnailBase64,
+      ...fallback ? { fallback: true, compressed: false } : {}
     };
     if (opts?.track !== false) {
       try {

package/dist/lib/annotate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"annotate.d.ts","sourceRoot":"","sources":["../../src/lib/annotate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAIvC,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,EACV,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,yBAAyB,CAAC,CAqEpC"}
+{"version":3,"file":"annotate.d.ts","sourceRoot":"","sources":["../../src/lib/annotate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAIvC,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAID,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,EACV,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,yBAAyB,CAAC,CAwEpC"}

package/dist/lib/screenshot-v4.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=screenshot-v4.test.d.ts.map

package/dist/lib/screenshot-v4.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot-v4.test.d.ts","sourceRoot":"","sources":["../../src/lib/screenshot-v4.test.ts"],"names":[],"mappings":""}

package/dist/lib/screenshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../src/lib/screenshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAKvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAgDpG,wBAAsB,cAAc,CAClC,IAAI,EAAE,IAAI,EACV,IAAI,CAAC,EAAE,iBAAiB,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACrF,OAAO,CAAC,gBAAgB,CAAC,CA8G3B;AAID,wBAAsB,WAAW,CAC/B,IAAI,EAAE,IAAI,EACV,IAAI,CAAC,EAAE,UAAU,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACzC,OAAO,CAAC,SAAS,CAAC,CA6BpB"}
+{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../src/lib/screenshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAKvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAgDpG,wBAAsB,cAAc,CAClC,IAAI,EAAE,IAAI,EACV,IAAI,CAAC,EAAE,iBAAiB,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACrF,OAAO,CAAC,gBAAgB,CAAC,CAyH3B;AAID,wBAAsB,WAAW,CAC/B,IAAI,EAAE,IAAI,EACV,IAAI,CAAC,EAAE,UAAU,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACzC,OAAO,CAAC,SAAS,CAAC,CA6BpB"}

package/dist/lib/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/lib/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAAE,aAAa,EAAW,MAAM,mBAAmB,CAAC;AAyB3D,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,IAAI,CAAC;CACZ;AAED,wBAAsB,aAAa,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA+D3F;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAWtD;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAI5D;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAIjE;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAIlE;AAED,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAgBtE;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,aAAa,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,EAAE,CAE/F;AAED,wBAAgB,iBAAiB,IAAI,OAAO,EAAE,CAE7C;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAItD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,kBAE5C;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,WAErD;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAGxF"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/lib/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAAE,aAAa,EAAW,MAAM,mBAAmB,CAAC;AAyB3D,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,IAAI,CAAC;CACZ;AAED,wBAAsB,aAAa,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAiE3F;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAWtD;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAI5D;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAIjE;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAIlE;AAED,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAgBtE;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,aAAa,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,EAAE,CAE/F;AAED,wBAAgB,iBAAiB,IAAI,OAAO,EAAE,CAE7C;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAItD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,kBAE5C;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,WAErD;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAGxF"}

package/dist/mcp/index.js

@@ -30,6 +30,12 @@ var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = import.meta.require;
 
 // src/db/schema.ts
+var exports_schema = {};
+__export(exports_schema, {
+  resetDatabase: () => resetDatabase,
+  getDatabase: () => getDatabase,
+  getDataDir: () => getDataDir
+});
 import { Database } from "bun:sqlite";
 import { join } from "path";
 import { mkdirSync } from "fs";
@@ -55,6 +61,15 @@ function getDatabase(path) {
   runMigrations(_db);
   return _db;
 }
+function resetDatabase() {
+  if (_db) {
+    try {
+      _db.close();
+    } catch {}
+  }
+  _db = null;
+  _dbPath = null;
+}
 function runMigrations(db) {
   db.exec(`
     CREATE TABLE IF NOT EXISTS schema_migrations (
@@ -252,12 +267,28 @@ var init_console_log = __esm(() => {
 });
 
 // src/lib/snapshot.ts
+var exports_snapshot = {};
+__export(exports_snapshot, {
+  takeSnapshot: () => takeSnapshot,
+  setLastSnapshot: () => setLastSnapshot,
+  hasRefs: () => hasRefs,
+  getSessionRefs: () => getSessionRefs,
+  getRefLocator: () => getRefLocator,
+  getRefInfo: () => getRefInfo,
+  getLastSnapshot: () => getLastSnapshot,
+  diffSnapshots: () => diffSnapshots,
+  clearSessionRefs: () => clearSessionRefs,
+  clearLastSnapshot: () => clearLastSnapshot
+});
 function getLastSnapshot(sessionId) {
   return lastSnapshots.get(sessionId) ?? null;
 }
 function setLastSnapshot(sessionId, snapshot) {
   lastSnapshots.set(sessionId, snapshot);
 }
+function clearLastSnapshot(sessionId) {
+  lastSnapshots.delete(sessionId);
+}
 async function takeSnapshot(page, sessionId) {
   let ariaTree;
   try {
@@ -360,6 +391,21 @@ function getRefLocator(page, sessionId, ref) {
     throw new Error(`Ref ${ref} not found. Available refs: ${[...refMap.keys()].slice(0, 20).join(", ")}`);
   return page.getByRole(entry.role, { name: entry.name }).first();
 }
+function getRefInfo(sessionId, ref) {
+  const refMap = sessionRefMaps.get(sessionId);
+  if (!refMap)
+    return null;
+  return refMap.get(ref) ?? null;
+}
+function getSessionRefs(sessionId) {
+  return sessionRefMaps.get(sessionId) ?? null;
+}
+function clearSessionRefs(sessionId) {
+  sessionRefMaps.delete(sessionId);
+}
+function hasRefs(sessionId) {
+  return sessionRefMaps.has(sessionId) && (sessionRefMaps.get(sessionId)?.size ?? 0) > 0;
+}
 function refKey(info) {
   return `${info.role}::${info.name}`;
 }
@@ -6833,7 +6879,8 @@ async function annotateScreenshot(page, sessionId) {
   const annotations = [];
   const labelToRef = {};
   let labelCounter = 1;
-  for (const [ref, info] of Object.entries(snapshot.refs)) {
+  const refsToAnnotate = Object.entries(snapshot.refs).slice(0, MAX_ANNOTATIONS);
+  for (const [ref, info] of refsToAnnotate) {
     try {
       const locator = page.getByRole(info.role, { name: info.name }).first();
       const box = await locator.boundingBox();
@@ -6872,7 +6919,7 @@ async function annotateScreenshot(page, sessionId) {
   const annotatedBuffer = await import_sharp3.default(rawBuffer).composite([{ input: Buffer.from(svg), top: 0, left: 0 }]).webp({ quality: 85 }).toBuffer();
   return { buffer: annotatedBuffer, annotations, labelToRef };
 }
-var import_sharp3;
+var import_sharp3, MAX_ANNOTATIONS = 40;
 var init_annotate = __esm(() => {
   init_snapshot();
   import_sharp3 = __toESM(require_lib(), 1);
@@ -10855,6 +10902,10 @@ var coerce = {
   date: (arg) => ZodDate.create({ ...arg, coerce: true })
 };
 var NEVER = INVALID;
+// src/mcp/index.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { join as join7 } from "path";
+
 // src/types/index.ts
 class BrowserError extends Error {
   code;
@@ -10922,7 +10973,14 @@ import { randomUUID } from "crypto";
 function createSession(data) {
   const db = getDatabase();
   const id = randomUUID();
-  db.prepare("INSERT INTO sessions (id, engine, project_id, agent_id, start_url, name) VALUES (?, ?, ?, ?, ?, ?)").run(id, data.engine, data.projectId ?? null, data.agentId ?? null, data.startUrl ?? null, data.name ?? null);
+  let name = data.name ?? null;
+  if (name) {
+    const existing = db.query("SELECT id FROM sessions WHERE name = ?").get(name);
+    if (existing) {
+      name = `${name}-${id.slice(0, 6)}`;
+    }
+  }
+  db.prepare("INSERT INTO sessions (id, engine, project_id, agent_id, start_url, name) VALUES (?, ?, ?, ?, ?, ?)").run(id, data.engine, data.projectId ?? null, data.agentId ?? null, data.startUrl ?? null, name);
   return getSession(id);
 }
 function getSessionByName(name) {
@@ -11424,12 +11482,19 @@ async function createSession2(opts = {}) {
       userAgent: opts.userAgent
     });
   }
+  let sessionName = opts.name ?? (opts.startUrl ? (() => {
+    try {
+      return new URL(opts.startUrl).hostname;
+    } catch {
+      return;
+    }
+  })() : undefined);
   const session = createSession({
     engine: resolvedEngine,
     projectId: opts.projectId,
     agentId: opts.agentId,
     startUrl: opts.startUrl,
-    name: opts.name ?? (opts.startUrl ? new URL(opts.startUrl).hostname : undefined)
+    name: sessionName
   });
   if (opts.stealth) {
     try {
@@ -12116,11 +12181,20 @@ async function takeScreenshot(page, opts) {
     }
     const originalSizeBytes = rawBuffer.length;
     let finalBuffer;
-    if (compress && format !== "png") {
-      finalBuffer = await compressBuffer(rawBuffer, format, quality ?? 82, maxWidth);
-    } else if (compress && format === "png") {
-      finalBuffer = await compressBuffer(rawBuffer, "png", quality ?? 9, maxWidth);
-    } else {
+    let compressed = true;
+    let fallback = false;
+    try {
+      if (compress && format !== "png") {
+        finalBuffer = await compressBuffer(rawBuffer, format, quality ?? 82, maxWidth);
+      } else if (compress && format === "png") {
+        finalBuffer = await compressBuffer(rawBuffer, "png", quality ?? 9, maxWidth);
+      } else {
+        finalBuffer = rawBuffer;
+        compressed = false;
+      }
+    } catch (sharpErr) {
+      fallback = true;
+      compressed = false;
       finalBuffer = rawBuffer;
     }
     const compressedSizeBytes = finalBuffer.length;
@@ -12148,7 +12222,8 @@ async function takeScreenshot(page, opts) {
       compressed_size_bytes: compressedSizeBytes,
       compression_ratio: compressionRatio,
       thumbnail_path: thumbnailPath,
-      thumbnail_base64: thumbnailBase64
+      thumbnail_base64: thumbnailBase64,
+      ...fallback ? { fallback: true, compressed: false } : {}
     };
     if (opts?.track !== false) {
       try {
@@ -13149,6 +13224,7 @@ function deleteProfile(name) {
 }
 
 // src/mcp/index.ts
+var _pkg = JSON.parse(readFileSync3(join7(import.meta.dir, "../../package.json"), "utf8"));
 var networkLogCleanup = new Map;
 var consoleCaptureCleanup = new Map;
 var harCaptures = new Map;
@@ -13214,13 +13290,50 @@ server.tool("browser_session_close", "Close a browser session", { session_id: ex
     return err(e);
   }
 });
-server.tool("browser_navigate", "Navigate to a URL. Returns title + thumbnail + accessibility snapshot preview with refs.", { session_id: exports_external.string(), url: exports_external.string(), timeout: exports_external.number().optional().default(30000), auto_snapshot: exports_external.boolean().optional().default(true), auto_thumbnail: exports_external.boolean().optional().default(true) }, async ({ session_id, url, timeout, auto_snapshot, auto_thumbnail }) => {
+server.tool("browser_navigate", "Navigate to a URL. Auto-detects redirects, auto-names session, returns compact refs + thumbnail.", {
+  session_id: exports_external.string(),
+  url: exports_external.string(),
+  timeout: exports_external.number().optional().default(30000),
+  auto_snapshot: exports_external.boolean().optional().default(true),
+  auto_thumbnail: exports_external.boolean().optional().default(true)
+}, async ({ session_id, url, timeout, auto_snapshot, auto_thumbnail }) => {
   try {
     const page = getSessionPage(session_id);
     await navigate(page, url, timeout);
     const title = await getTitle(page);
     const current_url = await getUrl(page);
-    const result = { url, title, current_url };
+    const redirected = current_url !== url && current_url !== url + "/" && url !== current_url.replace(/\/$/, "");
+    let redirect_type;
+    if (redirected) {
+      try {
+        const reqHost = new URL(url).hostname;
+        const resHost = new URL(current_url).hostname;
+        const reqPath = new URL(url).pathname;
+        const resPath = new URL(current_url).pathname;
+        if (reqHost !== resHost)
+          redirect_type = "canonical";
+        else if (resPath.match(/\/[a-z]{2}-[a-z]{2}\//))
+          redirect_type = "geo";
+        else if (current_url.includes("login") || current_url.includes("signin"))
+          redirect_type = "auth";
+        else
+          redirect_type = "unknown";
+      } catch {}
+    }
+    try {
+      const session = getSession2(session_id);
+      if (!session.name) {
+        const hostname = new URL(current_url).hostname;
+        renameSession2(session_id, hostname);
+      }
+    } catch {}
+    const result = {
+      url,
+      title,
+      current_url,
+      redirected,
+      ...redirect_type ? { redirect_type } : {}
+    };
     if (auto_thumbnail) {
       try {
         const ss = await takeScreenshot(page, { maxWidth: 400, quality: 60, track: false, thumbnail: false });
@@ -13230,7 +13343,9 @@ server.tool("browser_navigate", "Navigate to a URL. Returns title + thumbnail +
     if (auto_snapshot) {
       try {
         const snap = await takeSnapshot(page, session_id);
-        result.snapshot_preview = snap.tree.slice(0, 3000);
+        setLastSnapshot(session_id, snap);
+        const refEntries = Object.entries(snap.refs).slice(0, 30);
+        result.snapshot_refs = refEntries.map(([ref, info]) => `${info.role}:${info.name.slice(0, 50)} [${ref}]`).join(", ");
         result.interactive_count = snap.interactive_count;
         result.has_errors = getConsoleLog(session_id, "error").length > 0;
       } catch {}
@@ -13336,7 +13451,7 @@ server.tool("browser_select", "Select a dropdown option by ref or selector", { s
     return err(e);
   }
 });
-server.tool("browser_check", "Check or uncheck a checkbox by ref or selector", { session_id: exports_external.string(), selector: exports_external.string().optional(), ref: exports_external.string().optional(), checked: exports_external.boolean() }, async ({ session_id, selector, ref, checked }) => {
+server.tool("browser_toggle", "Check or uncheck a checkbox by ref or selector", { session_id: exports_external.string(), selector: exports_external.string().optional(), ref: exports_external.string().optional(), checked: exports_external.boolean() }, async ({ session_id, selector, ref, checked }) => {
   try {
     const page = getSessionPage(session_id);
     if (ref) {
@@ -13427,12 +13542,33 @@ server.tool("browser_find", "Find elements matching a selector and return their
     return err(e);
   }
 });
-server.tool("browser_snapshot", "Get a structured accessibility snapshot with element refs (@e0, @e1...). Use refs in browser_click, browser_type, etc.", { session_id: exports_external.string() }, async ({ session_id }) => {
+server.tool("browser_snapshot", "Get accessibility snapshot with element refs (@e0, @e1...). Use compact=true (default) for token-efficient output. Use refs in browser_click, browser_type, etc.", {
+  session_id: exports_external.string(),
+  compact: exports_external.boolean().optional().default(true),
+  max_refs: exports_external.number().optional().default(50),
+  full_tree: exports_external.boolean().optional().default(false)
+}, async ({ session_id, compact, max_refs, full_tree }) => {
   try {
     const page = getSessionPage(session_id);
     const result = await takeSnapshot(page, session_id);
     setLastSnapshot(session_id, result);
-    return json({ snapshot: result.tree, refs: result.refs, interactive_count: result.interactive_count });
+    const refEntries = Object.entries(result.refs).slice(0, max_refs);
+    const limitedRefs = Object.fromEntries(refEntries);
+    const truncated = Object.keys(result.refs).length > max_refs;
+    if (compact && !full_tree) {
+      const compactRefs = refEntries.map(([ref, info]) => `${info.role}:${info.name.slice(0, 60)} [${ref}]${info.checked !== undefined ? ` checked=${info.checked}` : ""}${!info.enabled ? " disabled" : ""}`).join(`
+`);
+      return json({
+        snapshot_compact: compactRefs,
+        interactive_count: result.interactive_count,
+        shown_count: refEntries.length,
+        truncated,
+        refs: limitedRefs
+      });
+    }
+    const tree = full_tree ? result.tree : result.tree.slice(0, 5000) + (result.tree.length > 5000 ? `
+... (truncated \u2014 use full_tree=true for complete)` : "");
+    return json({ snapshot: tree, refs: limitedRefs, interactive_count: result.interactive_count, truncated });
   } catch (e) {
     return err(e);
   }
@@ -13914,40 +14050,6 @@ server.tool("browser_watch_stop", "Stop a DOM change watcher", { watch_id: expor
     return err(e);
   }
 });
-server.tool("browser_page_check", "One-call page summary: page info + console errors + performance metrics + thumbnail + accessibility snapshot preview. Replaces 4-5 separate tool calls.", { session_id: exports_external.string() }, async ({ session_id }) => {
-  try {
-    const page = getSessionPage(session_id);
-    const info = await getPageInfo(page);
-    const errors2 = getConsoleLog(session_id, "error");
-    info.has_console_errors = errors2.length > 0;
-    let perf = {};
-    try {
-      perf = await getPerformanceMetrics(page);
-    } catch {}
-    let thumbnail_base64 = "";
-    try {
-      const ss = await takeScreenshot(page, { maxWidth: 400, quality: 60, track: false, thumbnail: false });
-      thumbnail_base64 = ss.base64;
-    } catch {}
-    let snapshot_preview = "";
-    let interactive_count = 0;
-    try {
-      const snap = await takeSnapshot(page, session_id);
-      snapshot_preview = snap.tree.slice(0, 2000);
-      interactive_count = snap.interactive_count;
-    } catch {}
-    return json({
-      ...info,
-      error_count: errors2.length,
-      performance: perf,
-      thumbnail_base64: thumbnail_base64.length > 50000 ? "" : thumbnail_base64,
-      snapshot_preview,
-      interactive_count
-    });
-  } catch (e) {
-    return err(e);
-  }
-});
 server.tool("browser_gallery_list", "List screenshot gallery entries with optional filters", {
   project_id: exports_external.string().optional(),
   session_id: exports_external.string().optional(),
@@ -14272,7 +14374,7 @@ server.tool("browser_help", "Show all available browser tools grouped by categor
         { tool: "browser_hover", description: "Hover over an element" },
         { tool: "browser_scroll", description: "Scroll the page" },
         { tool: "browser_select", description: "Select a dropdown option" },
-        { tool: "browser_check", description: "Check/uncheck a checkbox" },
+        { tool: "browser_toggle", description: "Check/uncheck a checkbox" },
         { tool: "browser_upload", description: "Upload a file to an input" },
         { tool: "browser_press_key", description: "Press a keyboard key" },
         { tool: "browser_wait", description: "Wait for a selector to appear" },
@@ -14292,9 +14394,10 @@ server.tool("browser_help", "Show all available browser tools grouped by categor
         { tool: "browser_evaluate", description: "Execute JavaScript in page context" }
       ],
       Capture: [
-        { tool: "browser_screenshot", description: "Take a screenshot (PNG/JPEG/WebP)" },
+        { tool: "browser_screenshot", description: "Take a screenshot (PNG/JPEG/WebP, annotate=true for labels)" },
         { tool: "browser_pdf", description: "Generate a PDF of the page" },
-        { tool: "browser_scroll_and_screenshot", description: "Scroll then screenshot in one call" }
+        { tool: "browser_scroll_and_screenshot", description: "Scroll then screenshot in one call" },
+        { tool: "browser_scroll_to_element", description: "Scroll element into view + screenshot" }
       ],
       Storage: [
         { tool: "browser_cookies_get", description: "Get cookies" },
@@ -14373,7 +14476,8 @@ server.tool("browser_help", "Show all available browser tools grouped by categor
         { tool: "browser_tab_close", description: "Close a tab by index" }
       ],
       Meta: [
-        { tool: "browser_page_check", description: "One-call page summary with diagnostics" },
+        { tool: "browser_check", description: "RECOMMENDED: One-call page summary with diagnostics" },
+        { tool: "browser_version", description: "Show running binary version and tool count" },
         { tool: "browser_help", description: "Show this help (all tools)" },
         { tool: "browser_snapshot_diff", description: "Diff current snapshot vs previous" },
         { tool: "browser_watch_start", description: "Watch page for DOM changes" },
@@ -14387,5 +14491,87 @@ server.tool("browser_help", "Show all available browser tools grouped by categor
     return err(e);
   }
 });
+server.tool("browser_version", "Get the running browser MCP version, tool count, and environment info. Use this to verify which binary is active.", {}, async () => {
+  try {
+    const { getDataDir: getDataDir4 } = await Promise.resolve().then(() => (init_schema(), exports_schema));
+    const toolCount = Object.keys(server._registeredTools ?? {}).length;
+    return json({
+      version: _pkg.version,
+      mcp_tools_count: toolCount,
+      bun_version: Bun.version,
+      data_dir: getDataDir4(),
+      node_env: process.env["NODE_ENV"] ?? "production"
+    });
+  } catch (e) {
+    return err(e);
+  }
+});
+server.tool("browser_scroll_to_element", "Scroll an element into view (by ref or selector) then optionally take a screenshot of it. Replaces scroll + wait + screenshot pattern.", {
+  session_id: exports_external.string(),
+  selector: exports_external.string().optional(),
+  ref: exports_external.string().optional(),
+  screenshot: exports_external.boolean().optional().default(true),
+  wait_ms: exports_external.number().optional().default(200)
+}, async ({ session_id, selector, ref, screenshot: doScreenshot, wait_ms }) => {
+  try {
+    const page = getSessionPage(session_id);
+    let locator;
+    if (ref) {
+      const { getRefLocator: getRefLocator2 } = await Promise.resolve().then(() => (init_snapshot(), exports_snapshot));
+      locator = getRefLocator2(page, session_id, ref);
+    } else if (selector) {
+      locator = page.locator(selector).first();
+    } else {
+      return err(new Error("Either ref or selector is required"));
+    }
+    await locator.scrollIntoViewIfNeeded();
+    await new Promise((r) => setTimeout(r, wait_ms));
+    const result = { scrolled: ref ?? selector };
+    if (doScreenshot) {
+      try {
+        const ss = await takeScreenshot(page, { selector, track: false });
+        ss.url = page.url();
+        if (ss.base64.length > 50000) {
+          ss.base64_truncated = true;
+          ss.base64 = ss.thumbnail_base64 ?? "";
+        }
+        result.screenshot = ss;
+      } catch {}
+    }
+    return json(result);
+  } catch (e) {
+    return err(e);
+  }
+});
+server.tool("browser_check", "RECOMMENDED FIRST CALL: one-shot page summary \u2014 url, title, errors, performance, thumbnail, refs. Replaces 4+ separate tool calls.", { session_id: exports_external.string() }, async ({ session_id }) => {
+  try {
+    const page = getSessionPage(session_id);
+    const info = await getPageInfo(page);
+    const errors2 = getConsoleLog(session_id, "error");
+    info.has_console_errors = errors2.length > 0;
+    let perf = {};
+    try {
+      perf = await getPerformanceMetrics(page);
+    } catch {}
+    let thumbnail_base64 = "";
+    try {
+      const ss = await takeScreenshot(page, { maxWidth: 400, quality: 60, track: false, thumbnail: false });
+      thumbnail_base64 = ss.base64.length > 50000 ? "" : ss.base64;
+    } catch {}
+    let snapshot_refs = "";
+    let interactive_count = 0;
+    try {
+      const snap = await takeSnapshot(page, session_id);
+      setLastSnapshot(session_id, snap);
+      interactive_count = snap.interactive_count;
+      snapshot_refs = Object.entries(snap.refs).slice(0, 30).map(([ref, i]) => `${i.role}:${i.name.slice(0, 50)} [${ref}]`).join(", ");
+    } catch {}
+    return json({ ...info, error_count: errors2.length, performance: perf, thumbnail_base64, snapshot_refs, interactive_count });
+  } catch (e) {
+    return err(e);
+  }
+});
+var _startupToolCount = Object.keys(server._registeredTools ?? {}).length;
+console.error(`@hasna/browser v${_pkg.version} \u2014 ${_startupToolCount} tools | data: ${(await Promise.resolve().then(() => (init_schema(), exports_schema))).getDataDir()}`);
 var transport = new StdioServerTransport;
 await server.connect(transport);

package/dist/mcp/v4.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=v4.test.d.ts.map

package/dist/mcp/v4.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v4.test.d.ts","sourceRoot":"","sources":["../../src/mcp/v4.test.ts"],"names":[],"mappings":""}

package/dist/server/index.js

@@ -6881,7 +6881,14 @@ import { randomUUID } from "crypto";
 function createSession(data) {
   const db = getDatabase();
   const id = randomUUID();
-  db.prepare("INSERT INTO sessions (id, engine, project_id, agent_id, start_url, name) VALUES (?, ?, ?, ?, ?, ?)").run(id, data.engine, data.projectId ?? null, data.agentId ?? null, data.startUrl ?? null, data.name ?? null);
+  let name = data.name ?? null;
+  if (name) {
+    const existing = db.query("SELECT id FROM sessions WHERE name = ?").get(name);
+    if (existing) {
+      name = `${name}-${id.slice(0, 6)}`;
+    }
+  }
+  db.prepare("INSERT INTO sessions (id, engine, project_id, agent_id, start_url, name) VALUES (?, ?, ?, ?, ?, ?)").run(id, data.engine, data.projectId ?? null, data.agentId ?? null, data.startUrl ?? null, name);
   return getSession(id);
 }
 function getSession(id) {
@@ -7361,12 +7368,19 @@ async function createSession2(opts = {}) {
       userAgent: opts.userAgent
     });
   }
+  let sessionName = opts.name ?? (opts.startUrl ? (() => {
+    try {
+      return new URL(opts.startUrl).hostname;
+    } catch {
+      return;
+    }
+  })() : undefined);
   const session = createSession({
     engine: resolvedEngine,
     projectId: opts.projectId,
     agentId: opts.agentId,
     startUrl: opts.startUrl,
-    name: opts.name ?? (opts.startUrl ? new URL(opts.startUrl).hostname : undefined)
+    name: sessionName
   });
   if (opts.stealth) {
     try {
@@ -7744,11 +7758,20 @@ async function takeScreenshot(page, opts) {
     }
     const originalSizeBytes = rawBuffer.length;
     let finalBuffer;
-    if (compress && format !== "png") {
-      finalBuffer = await compressBuffer(rawBuffer, format, quality ?? 82, maxWidth);
-    } else if (compress && format === "png") {
-      finalBuffer = await compressBuffer(rawBuffer, "png", quality ?? 9, maxWidth);
-    } else {
+    let compressed = true;
+    let fallback = false;
+    try {
+      if (compress && format !== "png") {
+        finalBuffer = await compressBuffer(rawBuffer, format, quality ?? 82, maxWidth);
+      } else if (compress && format === "png") {
+        finalBuffer = await compressBuffer(rawBuffer, "png", quality ?? 9, maxWidth);
+      } else {
+        finalBuffer = rawBuffer;
+        compressed = false;
+      }
+    } catch (sharpErr) {
+      fallback = true;
+      compressed = false;
       finalBuffer = rawBuffer;
     }
     const compressedSizeBytes = finalBuffer.length;
@@ -7776,7 +7799,8 @@ async function takeScreenshot(page, opts) {
       compressed_size_bytes: compressedSizeBytes,
       compression_ratio: compressionRatio,
       thumbnail_path: thumbnailPath,
-      thumbnail_base64: thumbnailBase64
+      thumbnail_base64: thumbnailBase64,
+      ...fallback ? { fallback: true, compressed: false } : {}
     };
     if (opts?.track !== false) {
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/browser",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "General-purpose browser agent toolkit — Playwright, Chrome DevTools Protocol, Lightpanda with auto engine selection. CLI + MCP + REST + SDK.",
   "type": "module",
   "main": "dist/index.js",