claude-browser-bridge 3.0.3 → 4.0.0

package/index.js

@@ -224,35 +224,66 @@ const HELP_TOOL = {
   inputSchema: { type: "object", properties: {} },
 };
 
-const HELP_TEXT = `# Claude Browser Bridge — 57 Tools Usage Guide
-
-## CRITICAL RULES (read before using ANY tool):
-1. ALWAYS start with \`diagnose\` — it returns snapshot + console errors + network failures + API responses in ONE call. NEVER call snapshot, get_console, get_network separately.
-2. Use \`batch\` for 2+ independent calls — e.g. batch([{name:"get_cookies"}, {name:"get_storage"}]).
-3. Pin with \`select_tab\` once, then stop passing tab_id — the pin persists.
-4. Use \`new_tab\` for research — NEVER navigate away from the app tab.
-5. After EVERY CSS/UI code change, take a \`screenshot\` to verify. Never claim "this should work" without seeing it.
-6. Use \`inject_css\` to test CSS fixes instantly without rebuilding, then write to file once confirmed.
-7. After 3 failed fix attempts, search the web: new_tab({url:"https://google.com/search?q=..."}).
-
-## Tool Categories:
-- Core: diagnose, batch, select_tab, snapshot, eval, screenshot, full_page_screenshot, get_page_text, get_html, get_page_info
-- Interaction: click, fill, hover, scroll, press_key, select_option, upload_file, highlight_element
-- Navigation: navigate, new_tab, close_tab, go_back, go_forward, reload, list_tabs, wait_for
-- Debugging: get_console, get_grouped_console, get_network, search_network_bodies, get_styles, get_cookies, get_storage, get_clipboard, watch_dom_changes, generate_selector
-- Performance: performance_trace, heap_snapshot_summary, get_load_timeline
-- Accessibility: get_accessibility_tree, check_contrast
-- Emulation: emulate_device, network_throttle, set_geolocation, toggle_dark_mode
-- Testing: visual_diff, inject_css, mock_network, record_actions, replay_actions, handle_dialog
-- Productivity: save_form_profile, load_form_profile, save_tab_session, restore_tab_session, edit_cookie, export_pdf
-
-## Key Workflows:
-- Investigate a page: diagnose → read errors → fix → screenshot to verify
-- Visual bug fix: batch([screenshot, get_styles]) → edit code → screenshot → compare → iterate
-- Performance audit: batch([performance_trace, heap_snapshot_summary, get_load_timeline])
-- Accessibility check: batch([get_accessibility_tree, check_contrast])
-- Test error states: mock_network({url_pattern:"/api/x", status_code:500}) → reload → screenshot
-- Record regression test: record_actions → reproduce bug → stop → fix → replay_actions to verify
+const HELP_TEXT = `# Claude Browser Bridge — 58 Tools
+
+## WHICH TOOL FIRST? (decision tree)
+- Investigating a bug → diagnose (gives snapshot + errors + network + API responses in ONE call)
+- Fixing CSS/visual → batch([screenshot, get_styles({selector:".target"}), get_html({selector:".target"})])
+- Performance check → batch([performance_trace, get_load_timeline, heap_snapshot_summary])
+- Accessibility audit → batch([get_accessibility_tree, check_contrast({selector:".text"})])
+- Reading page content → eval (specific data) or get_page_text (all text)
+- Interacting with page → diagnose first (get refs), then click/fill using refs
+- Opening a URL for research → new_tab (NEVER navigate away from the app tab)
+- Don't know → diagnose (covers 80% of needs)
+
+## 10 CRITICAL RULES:
+1. diagnose FIRST, always. ONE call replaces snapshot+get_console+get_network.
+2. batch for parallel. 2+ independent calls → always batch. Every sequential call wastes 2-3 seconds.
+3. select_tab once, never again. Pin target tab at start, stop passing tab_id.
+4. new_tab for research. NEVER navigate the app tab to docs/Google.
+5. screenshot after EVERY code edit. Never claim a fix works without seeing it.
+6. inject_css before editing files. Test CSS live, confirm with screenshot, THEN write to file.
+7. eval for state. React state, Redux store, variables — faster than parsing page text.
+8. get_styles for CSS. Never guess computed values — read them.
+9. 3 failed attempts = search web. new_tab + Google search. Stop guessing.
+10. Use refs from diagnose/snapshot for click/fill. Never guess CSS selectors.
+
+## KEY WORKFLOWS:
+
+Visual/CSS Fix:
+  batch([screenshot, get_styles, get_html]) → inject_css({css:"..."}) → screenshot → if good, write to file
+
+Bug Investigation:
+  diagnose → read errors → batch([get_grouped_console, get_network]) → fix → screenshot → verify
+
+Performance Audit:
+  batch([performance_trace, get_load_timeline, heap_snapshot_summary])
+
+Page Interaction:
+  diagnose → fill({ref:"ref_3", value:"..."}) → click({ref:"ref_0"}) → wait_for({text:"Success"})
+
+Multi-tab Research:
+  select_tab(app) → new_tab(docs) → get_page_text → close_tab → continue on app
+
+Error State Testing:
+  mock_network({url_pattern:"/api/cart", status_code:500}) → reload → screenshot
+
+Regression Testing:
+  record_actions → reproduce → stop → fix → replay_actions → screenshot
+
+Before/After Comparison:
+  screenshot (save dataUrl) → make changes → visual_diff({before_dataUrl:"..."})
+
+## ALL 58 TOOLS BY CATEGORY:
+Core: diagnose, batch, select_tab, snapshot, eval, screenshot, full_page_screenshot, get_page_text, get_html, get_page_info, browser_bridge_help
+Interaction: click, fill, hover, scroll, press_key, select_option, upload_file, highlight_element
+Navigation: navigate, new_tab, close_tab, go_back, go_forward, reload, list_tabs, wait_for
+Debugging: get_console, get_grouped_console, get_network, search_network_bodies, get_styles, get_cookies, get_storage, get_clipboard, watch_dom_changes, generate_selector
+Performance: performance_trace, heap_snapshot_summary, get_load_timeline
+Accessibility: get_accessibility_tree, check_contrast
+Emulation: emulate_device, network_throttle, set_geolocation, toggle_dark_mode
+Testing: visual_diff, inject_css, mock_network, record_actions, replay_actions, handle_dialog
+Productivity: save_form_profile, load_form_profile, save_tab_session, restore_tab_session, edit_cookie, export_pdf
 `;
 
 const BATCH_TOOL = {
@@ -846,10 +877,89 @@ const TOOLS = [
       required: ["query"],
     },
   },
+  // =================== SESSION-REQUESTED TOOLS ===================
+  {
+    name: "inspect_pixel",
+    description: "Sample RGBA color at a specific pixel coordinate on any rendered element. Bypasses CORS restrictions on images. Use percent=true to specify x/y as percentages of the element's size (e.g. x:50, y:50 = center). Returns hex color, opacity, and element bounding box.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        selector: { type: "string" }, ref: { type: "string" },
+        x: { type: "number", description: "X coordinate (pixels from element left, or percentage if percent=true)" },
+        y: { type: "number", description: "Y coordinate (pixels from element top, or percentage if percent=true)" },
+        percent: { type: "boolean", description: "If true, x/y are percentages (0-100) of the element size" },
+        ...TAB_ID,
+      },
+    },
+  },
+  {
+    name: "get_element_rect",
+    description: "Get exact computed position (viewport + offset + scroll), size, z-index, visibility, opacity, and parent info for any element. Use include_children=true to also get bounding boxes of all child elements — essential for debugging stacking/layering issues.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        selector: { type: "string" }, ref: { type: "string" },
+        include_children: { type: "boolean", description: "Also return child element rects (default false)" },
+        ...TAB_ID,
+      },
+    },
+  },
+  {
+    name: "compare_tabs",
+    description: "Screenshot two tabs side by side and compute a pixel diff between them. Returns both screenshots plus a diff image with changes in red. Use for comparing the same page across products, environments (prod vs staging), or before/after states.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tab_id_1: { type: "number", description: "First tab to screenshot" },
+        tab_id_2: { type: "number", description: "Second tab to screenshot" },
+      },
+      required: ["tab_id_1", "tab_id_2"],
+    },
+  },
+  {
+    name: "annotate",
+    description: "Draw persistent colored borders + labels on elements for visual debugging. Annotations stay visible across screenshots — use to identify layers, z-index stacking, or mark multiple elements at once. Call clear_annotations to remove them.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        selector: { type: "string" }, ref: { type: "string" },
+        label: { type: "string", description: "Text label shown above the element" },
+        color: { type: "string", description: "Border/label color (default '#D97757')" },
+        annotations: { type: "array", items: { type: "object" }, description: "Array of {selector, ref, label, color} for annotating multiple elements at once" },
+        ...TAB_ID,
+      },
+    },
+  },
+  {
+    name: "clear_annotations",
+    description: "Remove all annotations drawn by the annotate tool.",
+    inputSchema: { type: "object", properties: { ...TAB_ID } },
+  },
+  {
+    name: "capture_canvas",
+    description: "Flatten stacked child images inside a container element into a single canvas capture (like the browser renders them). Returns a PNG. Use for inspecting composited garment/image layers where individual images stack via z-index.",
+    inputSchema: {
+      type: "object",
+      properties: { selector: { type: "string" }, ref: { type: "string" }, ...TAB_ID },
+    },
+  },
+  {
+    name: "set_storage",
+    description: "Write to localStorage or sessionStorage. Handles complex JSON objects safely. Use action='remove' to delete a key, action='clear' to clear all storage.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        key: { type: "string" }, value: { description: "Value to set (string or JSON object)" },
+        storage_type: { type: "string", enum: ["local", "session"], description: "Default: local" },
+        action: { type: "string", enum: ["set", "remove", "clear"], description: "Default: set" },
+        ...TAB_ID,
+      },
+    },
+  },
 ];
 
 const server = new Server(
-  { name: "browser-bridge", version: "3.0.0" },
+  { name: "browser-bridge", version: "4.0.0" },
   { capabilities: { tools: {} } }
 );
 
@@ -875,6 +985,25 @@ function formatResult(name, result) {
       ],
     };
   }
+  if (name === "capture_canvas" && result?.dataUrl) {
+    const base64 = result.dataUrl.replace(/^data:image\/png;base64,/, "");
+    const { dataUrl, ...rest } = result;
+    return {
+      content: [
+        { type: "image", data: base64, mimeType: "image/png" },
+        { type: "text", text: JSON.stringify(rest, null, 2) },
+      ],
+    };
+  }
+  if (name === "compare_tabs" && result?.diffImage) {
+    const diffBase64 = result.diffImage.replace(/^data:image\/png;base64,/, "");
+    return {
+      content: [
+        { type: "text", text: `Diff: ${result.diffPercent}% changed (${result.diffPixels} pixels)` },
+        { type: "image", data: diffBase64, mimeType: "image/png" },
+      ],
+    };
+  }
   return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-browser-bridge",
-  "version": "3.0.3",
+  "version": "4.0.0",
   "description": "Connect your live Chrome tabs to Claude Code — 57 tools for debugging, performance, accessibility, device emulation, and browser automation.",
   "type": "module",
   "bin": {