github-router 0.3.41 → 0.3.43

package/dist/browser-ext/background.js

@@ -152,6 +152,14 @@ async function toolScreenshot(args) {
       await sleep(150)
     }
   }
+  // Both this API and CDP Page.captureScreenshot require the browser
+  // to have a real OS-level rendering surface. On Chrome-for-Testing
+  // launched in plain headed mode without --headless=new, no such
+  // surface exists and either path hangs indefinitely — the Playwright
+  // E2E harness passes --headless=new in its args list for exactly this
+  // reason. Real Chrome with a visible window has a surface and works
+  // fine. If you're driving Chrome-for-Testing programmatically and
+  // need screenshots, launch with `--headless=new`.
   const dataUrl = await chrome.tabs.captureVisibleTab(windowId, { format })
   // dataUrl: "data:image/png;base64,...."
   const m = /^data:([^;]+);base64,(.*)$/.exec(dataUrl)
@@ -194,7 +202,16 @@ async function toolReadPage(args) {
       const MAX = 256 * 1024
       let text = document.body ? document.body.innerText : ""
       if (text.length > MAX) text = text.slice(0, MAX)
-      return { text, elements }
+      // Viewport metadata so the model can correlate CSS-px bbox to
+      // device-px pixels in browser_screenshot (device_px = css_px * dpr).
+      const viewport = {
+        width: window.innerWidth,
+        height: window.innerHeight,
+        devicePixelRatio: window.devicePixelRatio,
+        scrollX: window.scrollX,
+        scrollY: window.scrollY,
+      }
+      return { text, elements, viewport }
     },
   })
   if (!result || typeof result.result !== "object") {
@@ -304,13 +321,52 @@ async function toolFill(args) {
 }
 
 async function toolScroll(args) {
-  const tabId = typeof args.tabId === "number" ? args.tabId : undefined
+  const tabId = args.tabId
   const target = args.target
-  const pixels = typeof args.pixels === "number" ? args.pixels : 0
+  assertTabId("browser_scroll", tabId)
+  const pixels = Number.isFinite(args.pixels) ? args.pixels : 0
   const ref = typeof args.ref === "string" ? args.ref : null
-  if (!tabId) throw new Error("browser_scroll: tabId is required")
-  if (!["top", "bottom", "pixels", "element"].includes(target)) {
-    throw new Error(`browser_scroll: target must be top|bottom|pixels|element, got ${String(target)}`)
+  if (!["top", "bottom", "pixels", "element", "at-pointer"].includes(target)) {
+    throw new Error(`browser_scroll: target must be top|bottom|pixels|element|at-pointer, got ${String(target)}`)
+  }
+  if (target === "at-pointer") {
+    // Wheel scroll a sub-region at a pointer location. Necessary for
+    // chat windows / infinite-scroll lists / modal bodies that have
+    // their own scroll container and ignore window.scrollTo. The wheel
+    // event bubbles through the scroll-container ancestor at the
+    // pointer location, so positioning the cursor on the right region
+    // is what makes it scroll instead of the outer window.
+    const selector = typeof args.selector === "string" ? args.selector : null
+    const x = Number.isFinite(args.x) ? args.x : undefined
+    const y = Number.isFinite(args.y) ? args.y : undefined
+    assertSingleTarget("browser_scroll(at-pointer)", ref, selector, x, y)
+    const deltaX = clampNum(Number.isFinite(args.deltaX) ? args.deltaX : 0, -10_000, 10_000)
+    const deltaY = clampNum(Number.isFinite(args.deltaY) ? args.deltaY : 0, -10_000, 10_000)
+    if (deltaX === 0 && deltaY === 0) {
+      throw new Error("browser_scroll(at-pointer): at least one of deltaX / deltaY must be non-zero")
+    }
+    const force = args.force === true
+    const pos = await resolveMouseTarget(tabId, ref, selector, x, y)
+    if (pos.hitTest && !pos.hitTest.isTarget && !force) {
+      throw new Error(`target_obscured: topmost is ${pos.hitTest.topmost || pos.hitTest.note}`)
+    }
+    return await withTabInputLock(tabId, async () => {
+      await attachDebuggerOnce(tabId)
+      // Position the cursor first so the wheel event lands on the
+      // right scroll-container ancestor.
+      await chrome.debugger.sendCommand({ tabId }, "Input.dispatchMouseEvent", {
+        type: "mouseMoved",
+        x: pos.x, y: pos.y,
+        button: "none", buttons: 0, modifiers: 0, pointerType: "mouse",
+      })
+      await chrome.debugger.sendCommand({ tabId }, "Input.dispatchMouseEvent", {
+        type: "mouseWheel",
+        x: pos.x, y: pos.y,
+        deltaX, deltaY,
+        button: "none", buttons: 0, modifiers: 0, pointerType: "mouse",
+      })
+      return { ok: true, scrolled: { x: pos.x, y: pos.y, deltaX, deltaY } }
+    })
   }
   const [result] = await chrome.scripting.executeScript({
     target: { tabId },
@@ -354,22 +410,702 @@ async function toolKeyboard(args) {
   // attachment. The attach stays for the tab's lifetime — chrome's
   // "is being controlled" banner is the visible cost, accepted in
   // exchange for cross-tool composability.
-  await attachDebuggerOnce(tabId)
-  const winVK = key.length === 1 ? key.toUpperCase().charCodeAt(0) : 0
-  await chrome.debugger.sendCommand({ tabId }, "Input.dispatchKeyEvent", {
-    type: "keyDown",
-    modifiers: bits,
-    key,
-    text: key.length === 1 ? key : undefined,
-    windowsVirtualKeyCode: winVK,
+  return await withTabInputLock(tabId, async () => {
+    await attachDebuggerOnce(tabId)
+    const winVK = key.length === 1 ? key.toUpperCase().charCodeAt(0) : 0
+    await chrome.debugger.sendCommand({ tabId }, "Input.dispatchKeyEvent", {
+      type: "keyDown",
+      modifiers: bits,
+      key,
+      text: key.length === 1 ? key : undefined,
+      windowsVirtualKeyCode: winVK,
+    })
+    await chrome.debugger.sendCommand({ tabId }, "Input.dispatchKeyEvent", {
+      type: "keyUp",
+      modifiers: bits,
+      key,
+      windowsVirtualKeyCode: winVK,
+    })
+    return { ok: true }
   })
-  await chrome.debugger.sendCommand({ tabId }, "Input.dispatchKeyEvent", {
-    type: "keyUp",
-    modifiers: bits,
-    key,
-    windowsVirtualKeyCode: winVK,
+}
+
+// ---------------------------------------------------------------------
+// Humanlike input v2: browser_mouse, browser_drag, browser_type, browser_locate
+// ---------------------------------------------------------------------
+// All four are CDP-driven (Input.dispatchMouseEvent / Input.dispatchKeyEvent),
+// share the per-tab input mutex (withTabInputLock), and inherit the
+// hardened attachDebuggerOnce. resolveMouseTarget centralises ref /
+// selector / (x,y) → bbox-center resolution AND the elementFromPoint
+// hit-test so all three coordinate-driven tools refuse to act on
+// occluded targets by default (force:true bypass).
+
+const BUTTON_BITS = { left: 1, right: 2, middle: 4 }
+
+function clampNum(v, min, max) {
+  const n = typeof v === "number" ? v : Number(v)
+  if (!Number.isFinite(n)) return min
+  return Math.max(min, Math.min(max, n))
+}
+
+// Per-tab input mutex. CDP mouse / keyboard state is global per
+// attachment, so two parallel browser_mouse / browser_drag / browser_type
+// calls on the same tab would interleave and corrupt each other (one
+// call's mouseMoved would land mid-drag of another). The global
+// MAX_INFLIGHT_TOOLS_CALL=8 cap doesn't help — it's global, not per-tab.
+// This mutex is per-tab, layered on top.
+const tabInputLockTails = new Map() // tabId → Promise (tail of the lock chain)
+
+// Wall-clock cap on how long ONE input call may hold its tab's mutex,
+// passed per-call (each tool sizes its own cap). Acts as a deadlock
+// release valve when an in-extension hang outlives the dispatcher's
+// WS-side timeout — without this cap the lock would stay held forever
+// (CDP commands don't abort when the dispatcher's WS disconnects).
+//
+// On wedge: we force-detach `chrome.debugger` for the tab AND bump the
+// tab's input generation. The detach makes all in-flight `sendCommand`
+// promises in the wedged fn() reject with "Debugger is not attached"
+// — without this, the wedged fn could keep dispatching stale CDP
+// events (e.g. a leftover `mouseReleased`) after the next caller has
+// already taken the lock and started a fresh drag, corrupting it.
+// `attachedTabs` is cleared so the next caller's `attachDebuggerOnce`
+// re-attaches cleanly. Cost: per-tab `consoleBuffers` /
+// `networkBuffers` are dropped (their backing CDP domain is no longer
+// enabled); the next `browser_console_logs` / `browser_network_log`
+// call re-`Runtime.enable` / `Network.enable` and starts capturing
+// fresh. A loud console.warn surfaces the wedge to forensic readers.
+//
+// Default cap = 60s — comfortably covers mouse/drag/scroll/keyboard
+// dispatcher maxMs (30s/30s/15s/10s) plus CDP overhead. `browser_type`
+// passes a larger explicit cap to accommodate its legitimately-slow
+// per-keystroke max (210s + grace).
+const DEFAULT_TAB_INPUT_LOCK_HOLD_CAP_MS = 60_000
+const TYPE_TAB_INPUT_LOCK_HOLD_CAP_MS = 240_000
+
+const tabInputGenerations = new Map() // tabId → number, bumped each acquire + on wedge
+
+async function withTabInputLock(tabId, fn, holdCapMs = DEFAULT_TAB_INPUT_LOCK_HOLD_CAP_MS) {
+  const previousTail = tabInputLockTails.get(tabId) || Promise.resolve()
+  let release
+  const myTurn = new Promise((r) => { release = r })
+  const newTail = previousTail.then(() => myTurn)
+  tabInputLockTails.set(tabId, newTail)
+  await previousTail
+  let timer
+  let wedged = false
+  try {
+    return await Promise.race([
+      fn(),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          wedged = true
+          reject(new Error(
+            `input_lock_wedged: held > ${holdCapMs}ms on tabId=${tabId}; force-detached debugger to abort the stuck CDP call.`,
+          ))
+        }, holdCapMs)
+      }),
+    ])
+  } finally {
+    if (timer !== undefined) clearTimeout(timer)
+    if (wedged) {
+      console.warn(`[browser-bridge] tab ${tabId} input lock wedged past ${holdCapMs}ms — force-detaching debugger`)
+      // Force-detach so the wedged fn's pending sendCommand promises
+      // reject and any further CDP calls it queues fail too. Without
+      // this, stale events from the wedged call can interleave with
+      // the next caller and corrupt drags / mouse state.
+      try {
+        await chrome.debugger.detach({ tabId })
+      } catch {
+        // already detached / tab gone — fine
+      }
+      attachedTabs.delete(tabId)
+      // Buffers need re-enabling next time their domains attach.
+      consoleBuffers.delete(tabId)
+      networkBuffers.delete(tabId)
+      // Bump the generation so any wedged fn() that checks before
+      // its next CDP send (future tools may opt in) sees the stale
+      // marker and bails out early.
+      tabInputGenerations.set(tabId, (tabInputGenerations.get(tabId) || 0) + 1)
+    }
+    release()
+    // GC the Map entry only if no later caller chained on top of us.
+    // If they did, the tail has been replaced; leave it alone.
+    if (tabInputLockTails.get(tabId) === newTail) {
+      tabInputLockTails.delete(tabId)
+    }
+  }
+}
+
+async function dispatchMouseEvent(tabId, type, x, y, button, buttons, clickCount) {
+  await chrome.debugger.sendCommand({ tabId }, "Input.dispatchMouseEvent", {
+    type, x, y, button, buttons, clickCount, modifiers: 0, pointerType: "mouse",
   })
-  return { ok: true }
+}
+
+// Resolve ref / selector / (x,y) → { x, y, draggable?, hitTest? }.
+// hitTest carries elementFromPoint topmost-element identity so the
+// caller can decide whether the target is actually clickable or is
+// occluded by an overlay (default behavior: refuse with target_obscured
+// unless force:true).
+// Resolve ref / selector / (x,y) → { x, y, draggable?, hitTest? }.
+// hitTest carries elementFromPoint topmost-element identity so the
+// caller can decide whether the target is actually clickable or is
+// occluded by an overlay (default behavior: refuse with target_obscured
+// unless force:true). Exclusivity (exactly ONE of ref / selector /
+// (x,y)) is checked by the caller — see assertSingleTarget.
+async function resolveMouseTarget(tabId, ref, selector, x, y) {
+  if (Number.isFinite(x) && Number.isFinite(y)) {
+    // Coordinate mode: no target identity, no hit-test (we don't know
+    // which element the caller expects to hit).
+    return { x: Math.round(x), y: Math.round(y), draggable: false, hitTest: null }
+  }
+  if (!ref && !selector) {
+    throw new Error("target required: provide ref, selector, or both x and y")
+  }
+  const [result] = await chrome.scripting.executeScript({
+    target: { tabId },
+    func: (ref, selector) => {
+      const sel = ref
+        ? `[data-gh-router-ref="${typeof CSS !== "undefined" && CSS.escape ? CSS.escape(ref) : ref.replace(/["\\]/g, "\\$&")}"]`
+        : selector
+      const el = document.querySelector(sel)
+      if (!el) return { error: `element not found: ${sel}` }
+      const rect = el.getBoundingClientRect()
+      const cx = Math.round(rect.x + rect.width / 2)
+      const cy = Math.round(rect.y + rect.height / 2)
+      const inView = cx >= 0 && cy >= 0 && cx <= window.innerWidth && cy <= window.innerHeight
+      const draggable = el.draggable === true
+      if (!inView) {
+        return {
+          x: cx, y: cy, draggable,
+          hitTest: { isTarget: false, note: "target center off-viewport" },
+        }
+      }
+      const top = document.elementFromPoint(cx, cy)
+      // isTarget: only accept when topmost IS the element, or topmost
+      // is a DESCENDANT of the element (clicking the child bubbles to
+      // the target). Do NOT accept top.contains(el) — that would be
+      // true whenever the topmost falls through to a parent (e.g. when
+      // el has pointer-events:none, or is fully covered by a sibling
+      // and elementFromPoint walks up to the container). That's
+      // exactly the "obscured" case we want to flag.
+      const isTarget = !!top && (top === el || el.contains(top))
+      let topmost = "(none)"
+      if (top) {
+        const id = top.id ? "#" + top.id : ""
+        const cls = top.className && typeof top.className === "string" ? "." + top.className.split(/\s+/).filter(Boolean).slice(0, 2).join(".") : ""
+        topmost = `${top.tagName.toLowerCase()}${id}${cls}`
+      }
+      return {
+        x: cx, y: cy, draggable,
+        hitTest: { isTarget, topmost },
+      }
+    },
+    args: [ref || null, selector || null],
+  })
+  if (!result || !result.result) {
+    throw new Error("target resolution failed: scripting.executeScript returned nothing")
+  }
+  if (result.result.error) throw new Error(result.result.error)
+  return result.result
+}
+
+// Validate that exactly one target descriptor is provided. The model
+// must not silently win one over another — if both ref and (x,y) are
+// passed, throw rather than silently picking. `prefix` is the tool /
+// arg-group name for the error message.
+function assertSingleTarget(prefix, ref, selector, x, y) {
+  const hasRef = !!ref
+  const hasSel = !!selector
+  const xSet = x !== undefined
+  const ySet = y !== undefined
+  if (xSet !== ySet) {
+    throw new Error(`${prefix}: x and y must be provided together`)
+  }
+  const hasCoords = xSet && ySet
+  const sources = (hasRef ? 1 : 0) + (hasSel ? 1 : 0) + (hasCoords ? 1 : 0)
+  if (sources === 0) {
+    throw new Error(`${prefix}: provide one of ref, selector, or (x, y)`)
+  }
+  if (sources > 1) {
+    throw new Error(`${prefix}: pass exactly one of ref, selector, or (x, y) — not multiple`)
+  }
+}
+
+function assertTabId(prefix, tabId) {
+  if (!Number.isInteger(tabId) || tabId < 0) {
+    throw new Error(`${prefix}: tabId must be a non-negative integer`)
+  }
+}
+
+async function toolMouse(args) {
+  const tabId = args.tabId
+  const action = args.action
+  assertTabId("browser_mouse", tabId)
+  if (!["move", "click", "dblclick", "down", "up"].includes(action)) {
+    throw new Error(`browser_mouse: action must be move|click|dblclick|down|up, got ${String(action)}`)
+  }
+  const buttonRaw = typeof args.button === "string" ? args.button : "left"
+  if (!["left", "right", "middle"].includes(buttonRaw)) {
+    throw new Error(`browser_mouse: button must be left|right|middle, got ${buttonRaw}`)
+  }
+  const button = buttonRaw
+  const buttonBits = BUTTON_BITS[button]
+  const steps = Math.round(clampNum(args.steps ?? 1, 1, 100))
+  const stepDelayMs = Math.round(clampNum(args.stepDelayMs ?? 8, 0, 50))
+  const force = args.force === true
+  const ref = typeof args.ref === "string" ? args.ref : null
+  const selector = typeof args.selector === "string" ? args.selector : null
+  const x = Number.isFinite(args.x) ? args.x : undefined
+  const y = Number.isFinite(args.y) ? args.y : undefined
+  assertSingleTarget("browser_mouse", ref, selector, x, y)
+
+  const target = await resolveMouseTarget(tabId, ref, selector, x, y)
+  if (target.hitTest && !target.hitTest.isTarget && !force) {
+    throw new Error(
+      `target_obscured: topmost is ${target.hitTest.topmost || target.hitTest.note}. Pass force:true to bypass.`,
+    )
+  }
+
+  return await withTabInputLock(tabId, async () => {
+    await attachDebuggerOnce(tabId)
+    // Interpolated approach: synthesise an origin point a bit away from
+    // the target and walk N steps in. We don't track a real cursor
+    // position across calls (MV3 SW dormancy would silently wipe it);
+    // the synthetic approach still fires the expected mouseMoved
+    // sequence for libraries that need a trajectory.
+    const path = steps > 1 ? interpolateApproach(target.x, target.y, steps) : [{ x: target.x, y: target.y }]
+    for (let i = 0; i < path.length; i++) {
+      await dispatchMouseEvent(tabId, "mouseMoved", path[i].x, path[i].y, "none", 0, 1)
+      if (i < path.length - 1 && stepDelayMs > 0) await sleep(stepDelayMs)
+    }
+    if (action === "move") {
+      return { ok: true, position: { x: target.x, y: target.y } }
+    }
+    if (action === "down") {
+      await dispatchMouseEvent(tabId, "mousePressed", target.x, target.y, button, buttonBits, 1)
+      return { ok: true }
+    }
+    if (action === "up") {
+      await dispatchMouseEvent(tabId, "mouseReleased", target.x, target.y, button, 0, 1)
+      return { ok: true }
+    }
+    if (action === "click") {
+      await dispatchMouseEvent(tabId, "mousePressed", target.x, target.y, button, buttonBits, 1)
+      await dispatchMouseEvent(tabId, "mouseReleased", target.x, target.y, button, 0, 1)
+      return { ok: true }
+    }
+    // dblclick: two press/release cycles with incrementing clickCount.
+    // A single press/release with clickCount:2 is NOT a real double-click;
+    // browsers expect two single clicks in quick succession with the
+    // clickCount on the second one bumped to 2, which is what fires the
+    // `dblclick` event.
+    await dispatchMouseEvent(tabId, "mousePressed", target.x, target.y, button, buttonBits, 1)
+    await dispatchMouseEvent(tabId, "mouseReleased", target.x, target.y, button, 0, 1)
+    await dispatchMouseEvent(tabId, "mousePressed", target.x, target.y, button, buttonBits, 2)
+    await dispatchMouseEvent(tabId, "mouseReleased", target.x, target.y, button, 0, 2)
+    return { ok: true }
+  })
+}
+
+function interpolateApproach(targetX, targetY, steps) {
+  // Synthetic origin: ~50px to the left and ~20px above the target so
+  // the first mouseMoved is a small approach rather than a teleport.
+  // Clamp to 0 so we never dispatch a negative-coordinate event near
+  // the viewport edge (some site code defensively bails on negative
+  // clientX/Y; some CDP versions reject outright).
+  const originX = Math.max(0, targetX - 50)
+  const originY = Math.max(0, targetY - 20)
+  const path = []
+  for (let i = 1; i <= steps; i++) {
+    const t = i / steps
+    path.push({
+      x: Math.round(originX + (targetX - originX) * t),
+      y: Math.round(originY + (targetY - originY) * t),
+    })
+  }
+  return path
+}
+
+async function toolDrag(args) {
+  const tabId = args.tabId
+  assertTabId("browser_drag", tabId)
+  const buttonRaw = typeof args.button === "string" ? args.button : "left"
+  if (!["left", "middle"].includes(buttonRaw)) {
+    throw new Error(`browser_drag: button must be left|middle, got ${buttonRaw}`)
+  }
+  const button = buttonRaw
+  const buttonBits = BUTTON_BITS[button]
+  const steps = Math.round(clampNum(args.steps ?? 15, 1, 100))
+  const stepDelayMs = Math.round(clampNum(args.stepDelayMs ?? 12, 0, 50))
+  const force = args.force === true
+  const modeRaw = typeof args.mode === "string" ? args.mode : "auto"
+  if (!["auto", "pointer", "html5"].includes(modeRaw)) {
+    throw new Error(`browser_drag: mode must be auto|pointer|html5, got ${modeRaw}`)
+  }
+
+  const fromRef = typeof args.fromRef === "string" ? args.fromRef : null
+  const fromSelector = typeof args.fromSelector === "string" ? args.fromSelector : null
+  const fromX = Number.isFinite(args.fromX) ? args.fromX : undefined
+  const fromY = Number.isFinite(args.fromY) ? args.fromY : undefined
+  assertSingleTarget("browser_drag.from", fromRef, fromSelector, fromX, fromY)
+  const toRef = typeof args.toRef === "string" ? args.toRef : null
+  const toSelector = typeof args.toSelector === "string" ? args.toSelector : null
+  const toX = Number.isFinite(args.toX) ? args.toX : undefined
+  const toY = Number.isFinite(args.toY) ? args.toY : undefined
+  assertSingleTarget("browser_drag.to", toRef, toSelector, toX, toY)
+
+  const from = await resolveMouseTarget(tabId, fromRef, fromSelector, fromX, fromY)
+  const to = await resolveMouseTarget(tabId, toRef, toSelector, toX, toY)
+  if (from.hitTest && !from.hitTest.isTarget && !force) {
+    throw new Error(
+      `target_obscured: drag source topmost is ${from.hitTest.topmost || from.hitTest.note}. Pass force:true to bypass.`,
+    )
+  }
+  const mode = modeRaw === "auto" ? (from.draggable ? "html5" : "pointer") : modeRaw
+
+  return await withTabInputLock(tabId, async () => {
+    await attachDebuggerOnce(tabId)
+    if (mode === "html5") {
+      await dragHtml5(tabId, from, to, button, buttonBits, steps, stepDelayMs)
+    } else {
+      await dragPointer(tabId, from, to, button, buttonBits, steps, stepDelayMs)
+    }
+    return { ok: true, mode_used: mode, from: { x: from.x, y: from.y }, to: { x: to.x, y: to.y } }
+  })
+}
+
+async function dragPointer(tabId, from, to, button, buttonBits, steps, stepDelayMs) {
+  // Pointer-event-based DnD (react-dnd, Sortable.js, mouse-event-driven
+  // drag handlers). Hold the button (buttons:buttonBits) throughout the
+  // intermediate mouseMoved events — without that bit set, pointer-event
+  // handlers see pointermove with buttons:0 and abort drag tracking.
+  //
+  // Safety: track pressed state. If ANY dispatch between mousePressed
+  // and mouseReleased throws (CDP timeout / target crash / nav / invalid
+  // coords), the finally block must still release the button — CDP mouse
+  // state is global per attachment, so a stuck press would poison every
+  // subsequent click on this tab. The per-tab mutex doesn't help; the
+  // renderer-side state survives.
+  await dispatchMouseEvent(tabId, "mouseMoved", from.x, from.y, "none", 0, 1)
+  let pressed = false
+  try {
+    await dispatchMouseEvent(tabId, "mousePressed", from.x, from.y, button, buttonBits, 1)
+    pressed = true
+    for (let i = 1; i <= steps; i++) {
+      const t = i / steps
+      const x = Math.round(from.x + (to.x - from.x) * t)
+      const y = Math.round(from.y + (to.y - from.y) * t)
+      await chrome.debugger.sendCommand({ tabId }, "Input.dispatchMouseEvent", {
+        type: "mouseMoved", x, y, button, buttons: buttonBits, modifiers: 0, pointerType: "mouse",
+      })
+      if (i < steps && stepDelayMs > 0) await sleep(stepDelayMs)
+    }
+    await dispatchMouseEvent(tabId, "mouseReleased", to.x, to.y, button, 0, 1)
+    pressed = false
+  } finally {
+    if (pressed) {
+      try {
+        await dispatchMouseEvent(tabId, "mouseReleased", to.x, to.y, button, 0, 1)
+      } catch {
+        // Swallow — don't mask the original error. A second failure here
+        // means the tab is in worse trouble than a stuck button.
+      }
+    }
+  }
+}
+
+async function dragHtml5(tabId, from, to, button, buttonBits, steps, stepDelayMs) {
+  // HTML5 native DnD (draggable="true" elements). Raw CDP mouse events
+  // CAN'T trigger Chromium's native dragstart pipeline — the only path
+  // is Input.setInterceptDrags(true) + Input.dispatchDragEvent. We
+  // press + move a few times to trigger drag-detect, capture the
+  // DragData via the dragIntercepted event, then dispatch dragEnter /
+  // dragOver / drop to the destination.
+  //
+  // Safety: same stuck-button concern as dragPointer. Track `pressed`
+  // and release in finally. Additionally, if the dragIntercepted event
+  // never arrives within the deadline, throw instead of silently
+  // returning ok:true — the model would otherwise reason from a
+  // phantom-new-state. Caller (toolDrag) can fall back to pointer mode.
+  let intercepted = null
+  const listener = (source, method, params) => {
+    if (source.tabId !== tabId) return
+    if (method === "Input.dragIntercepted" && params && params.data) {
+      intercepted = params.data
+    }
+  }
+  chrome.debugger.onEvent.addListener(listener)
+  let pressed = false
+  try {
+    await chrome.debugger.sendCommand({ tabId }, "Input.setInterceptDrags", { enabled: true })
+    await dispatchMouseEvent(tabId, "mouseMoved", from.x, from.y, "none", 0, 1)
+    await dispatchMouseEvent(tabId, "mousePressed", from.x, from.y, button, buttonBits, 1)
+    pressed = true
+    // A handful of intermediate moves to trigger drag-detect heuristics
+    // (Chromium fires dragstart after ~5px of movement with the button held).
+    const startMoves = Math.min(5, steps)
+    for (let i = 1; i <= startMoves; i++) {
+      const t = (i / startMoves) * 0.3 // partial progress toward dest
+      const x = Math.round(from.x + (to.x - from.x) * t)
+      const y = Math.round(from.y + (to.y - from.y) * t)
+      await chrome.debugger.sendCommand({ tabId }, "Input.dispatchMouseEvent", {
+        type: "mouseMoved", x, y, button, buttons: buttonBits, modifiers: 0, pointerType: "mouse",
+      })
+      if (stepDelayMs > 0) await sleep(stepDelayMs)
+    }
+    // Wait for the dragIntercepted event (up to 1s). Without this we
+    // wouldn't have the DragData payload to send to dispatchDragEvent.
+    const deadline = Date.now() + 1_000
+    while (!intercepted && Date.now() < deadline) {
+      await sleep(20)
+    }
+    if (!intercepted) {
+      // Source isn't actually html5-draggable, or page called
+      // event.preventDefault() on dragstart, or drag-detect heuristic
+      // didn't fire. DO NOT silently report success — the model would
+      // reason from a phantom state. Throw so toolDrag's caller knows
+      // to retry with mode:"pointer".
+      throw new Error("drag_failed: Input.dragIntercepted never arrived within 1s — source may not be html5-draggable or dragstart was prevented. Retry with mode:\"pointer\".")
+    }
+    await chrome.debugger.sendCommand({ tabId }, "Input.dispatchDragEvent", {
+      type: "dragEnter", x: to.x, y: to.y, data: intercepted,
+    })
+    await chrome.debugger.sendCommand({ tabId }, "Input.dispatchDragEvent", {
+      type: "dragOver", x: to.x, y: to.y, data: intercepted,
+    })
+    await chrome.debugger.sendCommand({ tabId }, "Input.dispatchDragEvent", {
+      type: "drop", x: to.x, y: to.y, data: intercepted,
+    })
+    await dispatchMouseEvent(tabId, "mouseReleased", to.x, to.y, button, 0, 1)
+    pressed = false
+  } finally {
+    chrome.debugger.onEvent.removeListener(listener)
+    if (pressed) {
+      try {
+        await dispatchMouseEvent(tabId, "mouseReleased", to.x, to.y, button, 0, 1)
+      } catch {
+        // Swallow — don't mask the original error.
+      }
+    }
+    try {
+      await chrome.debugger.sendCommand({ tabId }, "Input.setInterceptDrags", { enabled: false })
+    } catch {
+      // Ignore — turning intercept off on a fresh attach is harmless.
+    }
+  }
+}
+
+async function toolType(args) {
+  const tabId = args.tabId
+  assertTabId("browser_type", tabId)
+  const textRaw = typeof args.text === "string" ? args.text : undefined
+  if (typeof textRaw !== "string") throw new Error("browser_type: text (string) is required")
+  if (textRaw.length > 4096) {
+    throw new Error("browser_type: text exceeds 4096-character limit")
+  }
+  // Normalize CRLF / lone CR to LF so Windows-origin clipboard text and
+  // HTTP-response text don't throw the "invalid control char U+000D"
+  // rejection downstream. Models pasting from any source should "just
+  // work" — the user's intent for "\r\n" is unambiguously a newline.
+  const text = textRaw.replace(/\r\n?/g, "\n")
+  const delayMs = Math.round(clampNum(args.delayMs ?? 0, 0, 50))
+  // Validate: reject control chars not in our whitelist. \n, \t, \b are
+  // remapped to named keys (Enter / Tab / Backspace). \r is already
+  // normalized to \n above. Other control chars (< 0x20) have no key
+  // mapping and would produce junk events; reject up front so the model
+  // can route them through browser_keyboard.
+  for (const ch of text) {
+    const code = ch.codePointAt(0)
+    if (code === undefined) continue
+    if (code < 0x20 && code !== 0x0A && code !== 0x09 && code !== 0x08) {
+      const hex = code.toString(16).toUpperCase().padStart(4, "0")
+      throw new Error(
+        `invalid_text: control char U+${hex} not supported. browser_type whitelist: \\n=Enter, \\t=Tab, \\b=Backspace, \\r normalized to \\n. Use browser_keyboard for other control sequences.`,
+      )
+    }
+  }
+  return await withTabInputLock(tabId, async () => {
+    await attachDebuggerOnce(tabId)
+    let count = 0
+    for (const ch of text) {
+      const code = ch.codePointAt(0)
+      let key, codeStr, vkc, sendText
+      if (code === 0x0A) {
+        key = "Enter"; codeStr = "Enter"; vkc = 13; sendText = undefined
+      } else if (code === 0x09) {
+        key = "Tab"; codeStr = "Tab"; vkc = 9; sendText = undefined
+      } else if (code === 0x08) {
+        key = "Backspace"; codeStr = "Backspace"; vkc = 8; sendText = undefined
+      } else {
+        key = ch
+        // Punctuation table fills in real Windows-VK values for the
+        // characters whose naive `charCodeAt` would collide with
+        // unrelated VK codes (e.g. '.' = 46 = VK_DELETE). Letters and
+        // digits use their natural charCode (VK_A..VK_Z / VK_0..VK_9
+        // happen to match). Everything else: 0, and CDP infers event
+        // semantics from `key` + `text`. Without this, sites that
+        // fall back to `event.keyCode` for hotkey handling would see
+        // 0 for typed punctuation; with it they get the canonical VK.
+        const punctVk = PUNCT_TO_VK[ch]
+        if (/^[a-zA-Z0-9]$/.test(ch)) {
+          vkc = ch.toUpperCase().charCodeAt(0)
+        } else if (punctVk !== undefined) {
+          vkc = punctVk
+        } else {
+          vkc = 0
+        }
+        codeStr = deriveKeyCode(ch)
+        sendText = ch
+      }
+      // Correct CDP recipe: keyDown WITH text fires keydown + keypress +
+      // input together. Do NOT also send a separate `char` event — that
+      // would double-fire keypress/input on most sites.
+      const downParams = {
+        type: "keyDown",
+        key,
+        code: codeStr || undefined,
+        modifiers: 0,
+        windowsVirtualKeyCode: vkc,
+      }
+      if (sendText !== undefined) downParams.text = sendText
+      await chrome.debugger.sendCommand({ tabId }, "Input.dispatchKeyEvent", downParams)
+      await chrome.debugger.sendCommand({ tabId }, "Input.dispatchKeyEvent", {
+        type: "keyUp",
+        key,
+        code: codeStr || undefined,
+        modifiers: 0,
+        windowsVirtualKeyCode: vkc,
+      })
+      count++
+      if (delayMs > 0) await sleep(delayMs)
+    }
+    return { ok: true, chars: count }
+  }, TYPE_TAB_INPUT_LOCK_HOLD_CAP_MS)
+}
+
+// Windows VK codes for the printable punctuation that browser_type
+// needs to send. Letters and digits aren't here — their natural
+// charCode happens to match VK_A..VK_Z / VK_0..VK_9 and the typing
+// loop derives those inline. This table covers the unshifted AND
+// shift-modified character on each US-layout punctuation key; both
+// map to the same physical-key VK (the shift state is implied by the
+// `text` field, and we don't dispatch a separate shift keydown).
+//
+// Source: Windows VK reference (learn.microsoft.com/...windows-keyboard-codes)
+// — VK_OEM_* are the layout-specific punctuation codes (US-QWERTY here).
+const PUNCT_TO_VK = Object.freeze({
+  // Shift+number row
+  "!": 49, "@": 50, "#": 51, "$": 52, "%": 53,
+  "^": 54, "&": 55, "*": 56, "(": 57, ")": 48,
+  // VK_OEM_1 .. VK_OEM_7 + space
+  ";": 186, ":": 186,
+  "=": 187, "+": 187,
+  ",": 188, "<": 188,
+  "-": 189, "_": 189,
+  ".": 190, ">": 190,
+  "/": 191, "?": 191,
+  "`": 192, "~": 192,
+  "[": 219, "{": 219,
+  "\\": 220, "|": 220,
+  "]": 221, "}": 221,
+  "'": 222, '"': 222,
+  " ": 32, // VK_SPACE
+})
+
+function deriveKeyCode(ch) {
+  // Best-effort code field. Covers ASCII printable chars including
+  // shift-modified punctuation (! → Digit1, @ → Digit2, < → Comma,
+  // etc) so `event.code` reports the PHYSICAL key the char lives on
+  // — sites that check `event.code === "Digit1"` for layout-aware
+  // shortcuts work the same whether the user typed `1` or `!`.
+  // Non-ASCII falls back to empty string.
+  if (/^[a-zA-Z]$/.test(ch)) return "Key" + ch.toUpperCase()
+  if (/^[0-9]$/.test(ch)) return "Digit" + ch
+  if (ch === " ") return "Space"
+  const map = {
+    // Number-row shift partners
+    "!": "Digit1", "@": "Digit2", "#": "Digit3", "$": "Digit4", "%": "Digit5",
+    "^": "Digit6", "&": "Digit7", "*": "Digit8", "(": "Digit9", ")": "Digit0",
+    // OEM keys (US-QWERTY)
+    "-": "Minus", "_": "Minus",
+    "=": "Equal", "+": "Equal",
+    "[": "BracketLeft", "{": "BracketLeft",
+    "]": "BracketRight", "}": "BracketRight",
+    "\\": "Backslash", "|": "Backslash",
+    ";": "Semicolon", ":": "Semicolon",
+    "'": "Quote", '"': "Quote",
+    ",": "Comma", "<": "Comma",
+    ".": "Period", ">": "Period",
+    "/": "Slash", "?": "Slash",
+    "`": "Backquote", "~": "Backquote",
+  }
+  return map[ch] || ""
+}
+
+async function toolLocate(args) {
+  const tabId = args.tabId
+  const ref = typeof args.ref === "string" ? args.ref : null
+  const selector = typeof args.selector === "string" ? args.selector : null
+  assertTabId("browser_locate", tabId)
+  if (!ref && !selector) throw new Error("browser_locate: ref or selector is required")
+  if (ref && selector) throw new Error("browser_locate: pass exactly one of ref or selector, not both")
+  const [result] = await chrome.scripting.executeScript({
+    target: { tabId },
+    func: (ref, selector) => {
+      const viewport = {
+        width: window.innerWidth,
+        height: window.innerHeight,
+        devicePixelRatio: window.devicePixelRatio,
+        scrollX: window.scrollX,
+        scrollY: window.scrollY,
+      }
+      const sel = ref
+        ? `[data-gh-router-ref="${typeof CSS !== "undefined" && CSS.escape ? CSS.escape(ref) : ref.replace(/["\\]/g, "\\$&")}"]`
+        : selector
+      const el = document.querySelector(sel)
+      if (!el) return { found: false, viewport }
+      const rect = el.getBoundingClientRect()
+      const cx = Math.round(rect.x + rect.width / 2)
+      const cy = Math.round(rect.y + rect.height / 2)
+      const style = getComputedStyle(el)
+      const visible =
+        rect.width > 0 && rect.height > 0
+        && style.display !== "none"
+        && style.visibility !== "hidden"
+        && parseFloat(style.opacity || "1") > 0
+      const inView = cx >= 0 && cy >= 0 && cx <= window.innerWidth && cy <= window.innerHeight
+      let topmostAtCenter = null
+      if (inView) {
+        const top = document.elementFromPoint(cx, cy)
+        // Same hit-test rule as resolveMouseTarget: target IS topmost
+        // or contains it as a descendant. Ancestor-containment (top
+        // contains el) is FALSE here because that's the obscured case.
+        const isTarget = !!top && (top === el || el.contains(top))
+        const topRef = top && top.getAttribute ? top.getAttribute("data-gh-router-ref") : null
+        topmostAtCenter = {
+          isTarget,
+          tag: top ? top.tagName.toLowerCase() : null,
+          refOrSelector: topRef || null,
+        }
+      }
+      return {
+        found: true,
+        bbox: [Math.round(rect.x), Math.round(rect.y), Math.round(rect.width), Math.round(rect.height)],
+        center: [cx, cy],
+        inView,
+        visible,
+        pointerEvents: style.pointerEvents,
+        topmostAtCenter,
+        viewport,
+      }
+    },
+    args: [ref || null, selector || null],
+  })
+  if (!result || typeof result.result !== "object") {
+    throw new Error("browser_locate: scripting.executeScript returned nothing")
+  }
+  return result.result
 }
 
 async function toolWait(args) {
@@ -504,18 +1240,56 @@ const attachedTabs = new Set()
 const MAX_BUFFER_ENTRIES = 1000
 
 async function attachDebuggerOnce(tabId, opts) {
-  if (!attachedTabs.has(tabId)) {
-    try { await chrome.debugger.attach({ tabId }, "1.3") } catch { /* may already be attached */ }
-    attachedTabs.add(tabId)
-  }
-  if (opts?.console && !consoleBuffers.has(tabId)) {
-    consoleBuffers.set(tabId, [])
-    await chrome.debugger.sendCommand({ tabId }, "Runtime.enable")
-  }
-  if (opts?.network && !networkBuffers.has(tabId)) {
-    networkBuffers.set(tabId, [])
-    await chrome.debugger.sendCommand({ tabId }, "Network.enable")
-  }
+  // navigator.locks serializes concurrent attach attempts after MV3 SW
+  // respawn (when the in-memory attachedTabs Set is wiped but Chrome may
+  // have kept the underlying CDP attachment alive past the SW death).
+  // Without this lock, two parallel tool calls would both call
+  // chrome.debugger.attach and the loser would throw
+  // "Another debugger is already attached to this target".
+  //
+  // The "already attached" branch is subtle: "already attached" can mean
+  // (a) WE attached and the SW just lost the cache, OR (b) DevTools /
+  // another extension owns the session and we DON'T. Don't blindly trust
+  // (a) — that would poison the cache and every subsequent sendCommand
+  // would fail with cryptic CDP errors. Prove ownership with a no-op
+  // Runtime.evaluate; only cache on success.
+  await navigator.locks.request(`browser-mcp:debugger-attach:${tabId}`, async () => {
+    if (!attachedTabs.has(tabId)) {
+      let mustVerifyOwnership = false
+      try {
+        await chrome.debugger.attach({ tabId }, "1.3")
+      } catch (err) {
+        const msg = err && err.message ? err.message : String(err)
+        const alreadyAttached = /already attached/i.test(msg) || /already debugging/i.test(msg)
+        if (!alreadyAttached) throw err
+        // "Already attached" — could be us (Chrome kept the attachment
+        // past our SW death) or another debugger (DevTools open, etc.).
+        // Don't cache yet; verify below.
+        mustVerifyOwnership = true
+      }
+      if (mustVerifyOwnership) {
+        try {
+          await chrome.debugger.sendCommand({ tabId }, "Runtime.evaluate", {
+            expression: "1", returnByValue: true,
+          })
+          // sendCommand succeeded → we own the attachment. Safe to cache.
+        } catch {
+          throw new Error(
+            "browser-mcp: chrome.debugger reports attached but we do not own the session — likely DevTools is open on this tab (or another extension is debugging). Close DevTools and retry.",
+          )
+        }
+      }
+      attachedTabs.add(tabId)
+    }
+    if (opts?.console && !consoleBuffers.has(tabId)) {
+      consoleBuffers.set(tabId, [])
+      await chrome.debugger.sendCommand({ tabId }, "Runtime.enable")
+    }
+    if (opts?.network && !networkBuffers.has(tabId)) {
+      networkBuffers.set(tabId, [])
+      await chrome.debugger.sendCommand({ tabId }, "Network.enable")
+    }
+  })
 }
 
 chrome.debugger.onEvent.addListener((source, method, params) => {
@@ -548,9 +1322,23 @@ chrome.debugger.onDetach.addListener((source) => {
     attachedTabs.delete(source.tabId)
     consoleBuffers.delete(source.tabId)
     networkBuffers.delete(source.tabId)
+    tabInputLockTails.delete(source.tabId)
   }
 })
 
+// Clean per-tab state on tab close. attachedTabs / consoleBuffers /
+// networkBuffers are also cleaned by debugger.onDetach above (Chrome
+// detaches on tab close), but doing it here too is cheap and protects
+// against listener ordering surprises. tabInputLockTails is NOT
+// cleaned by onDetach in some scenarios (the lock-chain Map can leak
+// if a drag was in flight when the tab closed); cover it here.
+chrome.tabs.onRemoved.addListener((tabId) => {
+  attachedTabs.delete(tabId)
+  consoleBuffers.delete(tabId)
+  networkBuffers.delete(tabId)
+  tabInputLockTails.delete(tabId)
+})
+
 async function toolConsoleLogs(args) {
   const tabId = typeof args.tabId === "number" ? args.tabId : undefined
   const level = typeof args.level === "string" ? args.level : "all"
@@ -594,6 +1382,10 @@ const TOOL_HANDLERS = {
   browser_download: toolDownload,
   browser_console_logs: toolConsoleLogs,
   browser_network_log: toolNetworkLog,
+  browser_mouse: toolMouse,
+  browser_drag: toolDrag,
+  browser_type: toolType,
+  browser_locate: toolLocate,
 }
 
 // ---------------------------------------------------------------------