claude-browser-bridge 3.0.4 → 4.0.1

package/index.js

@@ -220,15 +220,17 @@ establish();
 const HELP_TOOL = {
   name: "browser_bridge_help",
   description:
-    "Returns the complete usage guide for all 57 browser-bridge tools. Call this ONCE at the start of any session where you need to use browser tools, to learn the optimal workflows and avoid slow anti-patterns.",
+    "Returns the complete usage guide for all 65 browser-bridge tools. Call this ONCE at the start of any session where you need to use browser tools, to learn the optimal workflows and avoid slow anti-patterns.",
   inputSchema: { type: "object", properties: {} },
 };
 
-const HELP_TEXT = `# Claude Browser Bridge — 58 Tools
+const HELP_TEXT = `# Claude Browser Bridge — 65 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"})])
+- Debugging image layers/z-index → batch([get_element_rect({selector:".container", include_children:true}), annotate({annotations:[...]})])
+- Checking pixel colors on images → inspect_pixel({selector:"img", x:50, y:50, percent:true})
 - 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)
@@ -274,7 +276,19 @@ Regression Testing:
 Before/After Comparison:
   screenshot (save dataUrl) → make changes → visual_diff({before_dataUrl:"..."})
 
-## ALL 58 TOOLS BY CATEGORY:
+Image/Layer Debugging:
+  annotate({annotations:[{selector:".base",label:"Base",color:"red"},{selector:".overlay",label:"Overlay",color:"blue"}]}) → screenshot → clear_annotations
+  inspect_pixel({selector:".garment-img", x:50, y:30, percent:true}) → check if transparent or opaque
+  get_element_rect({selector:".container", include_children:true}) → see all child positions + z-indexes
+  capture_canvas({selector:".composer"}) → flatten all stacked images into one PNG
+
+Cross-Product Comparison:
+  new_tab({url:"product-A"}) → new_tab({url:"product-B"}) → compare_tabs({tab_id_1:A, tab_id_2:B})
+
+State Management Testing:
+  set_storage({key:"cache", action:"remove"}) → reload → verify fresh state
+
+## ALL 65 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
@@ -284,6 +298,8 @@ 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
+Visual Debugging: inspect_pixel, get_element_rect, compare_tabs, annotate, clear_annotations, capture_canvas
+Storage: set_storage
 `;
 
 const BATCH_TOOL = {
@@ -877,10 +893,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: {} } }
 );
 
@@ -906,6 +1001,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,7 +1,7 @@
 {
   "name": "claude-browser-bridge",
-  "version": "3.0.4",
-  "description": "Connect your live Chrome tabs to Claude Code — 57 tools for debugging, performance, accessibility, device emulation, and browser automation.",
+  "version": "4.0.1",
+  "description": "Connect your live Chrome tabs to Claude Code — 65 tools for debugging, performance, accessibility, visual inspection, and browser automation.",
   "type": "module",
   "bin": {
     "claude-browser-bridge": "./bin/cli.js"