github-router 0.3.45 → 0.3.66

package/dist/browser-ext/background.js

@@ -20,15 +20,38 @@
 
 const NATIVE_HOST_NAME = "com.githubrouter.browser"
 
+// Snapshot cache + invalidation lives in a sibling module so the
+// matcher-cascade work in Phase 2 can consume it without dragging in
+// the entire 1700-line background.js dispatcher.
+import {
+  captureSnapshot,
+  invalidateSnapshot,
+} from "./snapshot.js"
+import { extractSnapshotCDP } from "./snapshot-cdp.js"
+
 // ---------------------------------------------------------------------
-// Navigation policy — list of URL patterns blocked from open / navigate.
-// Mirrored in src/lib/browser-mcp/policy.ts (defense in depth).
+// Navigation policy — URL patterns this extension blocks at
+// webNavigation.onBeforeNavigate. This list is INTENTIONALLY NARROWER
+// than the bridge-side regex in src/lib/browser-mcp/policy.ts: the
+// bridge regex only fires for tool-initiated nav (browser_open_tab /
+// browser_navigate) so it can safely block `extensions` without
+// affecting the human user, while THIS regex fires for user-typed URL
+// bar nav too and must preserve human access to chrome://extensions /
+// edge://extensions (needed to reload this extension after package
+// updates).
 // ---------------------------------------------------------------------
 
+// `extensions` is intentionally omitted from the extension-side regex —
+// chrome.webNavigation.onBeforeNavigate fires for ALL top-level
+// navigations including the user typing in the URL bar, so including it
+// here would lock the user out of managing the very extension that
+// loads this code (and prevent the reload arrow that auto-update falls
+// back to). Bridge-side policy.ts keeps `extensions` in its regex,
+// which is sufficient because the bridge regex only gates tool-
+// initiated nav (browser_open_tab / browser_navigate).
 const BLOCKED_URL_RE =
-  /^(chrome|edge|brave|opera|vivaldi):\/\/(settings|preferences|extensions|policy|management|password|flags|flag-descriptions)/i
-const BLOCKED_VIEW_SOURCE_RE =
-  /^view-source:(chrome|edge):\/\/(settings|extensions)/i
+  /^(chrome|edge|brave|opera|vivaldi):\/\/(settings|preferences|policy|management|password|flags|flag-descriptions)/i
+const BLOCKED_VIEW_SOURCE_RE = /^view-source:(chrome|edge):\/\/settings/i
 
 function isBlockedUrl(url) {
   if (typeof url !== "string") return false
@@ -170,40 +193,117 @@ async function toolScreenshot(args) {
 async function toolReadPage(args) {
   const tabId = typeof args.tabId === "number" ? args.tabId : undefined
   if (!tabId) throw new Error("browser_read_page: tabId is required")
+  const mode = args.mode === "full" ? "full" : "summary"
+  const refresh = args.refresh === true
+  // Phase 1c-CDP: try the CDP `Accessibility.getFullAXTree`-based
+  // extractor first. Better cross-origin iframe coverage, real
+  // platform-computed accessible names, AX-tree-flagged hidden /
+  // disabled state. Falls back to the legacy DOM walker when CDP
+  // attach fails (enterprise DeveloperToolsAvailability=2, DevTools
+  // already open on the tab, sandbox restriction). The fallback path
+  // produces a strict-subset shape so consumers don't have to branch.
+  const extractor = async (tId, ext) => {
+    try {
+      return await extractSnapshotCDP(tId, ext, {
+        attachDebugger: attachDebuggerOnce,
+        sendCommand: (id, method, params) => chrome.debugger.sendCommand({ tabId: id }, method, params),
+      })
+    } catch (err) {
+      const msg = err && err.message ? err.message : String(err)
+      console.warn(`[browser-mcp/snapshot] CDP extractor failed, falling back to legacy: ${msg}`)
+      return await extractSnapshotLegacy(tId, ext)
+    }
+  }
+  return captureSnapshot(tabId, { mode, refresh }, extractor)
+}
+
+/**
+ * Legacy `document.querySelectorAll`-based extractor. Stays as the
+ * default extractor until Phase 1b-CDP lands; will become the fallback
+ * path when CDP attach fails (enterprise policy, DevTools open on the
+ * tab, etc.). The implementation runs in the page world via
+ * chrome.scripting.executeScript and returns a PageSnapshot-shaped
+ * object that snapshot.captureSnapshot caches and returns to the
+ * caller.
+ */
+async function extractSnapshotLegacy(tabId, opts) {
+  const mode = opts?.mode === "full" ? "full" : "summary"
   const [result] = await chrome.scripting.executeScript({
     target: { tabId },
-    func: () => {
-      // Element refs: every interactive element gets an id we return to
-      // the caller; subsequent click/fill calls reference these refs
-      // instead of brittle CSS selectors. Refs are stable for the
-      // lifetime of a single read_page snapshot.
-      const interactive = "a, button, input, select, textarea, [role='button'], [role='link'], [role='checkbox']"
-      const els = Array.from(document.querySelectorAll(interactive))
-      const elements = els.slice(0, 200).map((el, i) => {
-        const ref = `e${i + 1}`
-        el.setAttribute("data-gh-router-ref", ref)
-        const rect = el.getBoundingClientRect()
-        return {
-          ref,
-          role: el.getAttribute("role") || el.tagName.toLowerCase(),
-          name:
-            (el.getAttribute("aria-label") ||
-              el.textContent ||
-              el.getAttribute("value") ||
-              el.getAttribute("placeholder") ||
-              "")
-              .trim()
-              .slice(0, 200),
-          bbox: [Math.round(rect.x), Math.round(rect.y), Math.round(rect.width), Math.round(rect.height)],
+    func: (mode) => {
+      // Stable ref attribution: every interactive element gets a
+      // data-gh-router-ref attribute the model uses for subsequent
+      // ref-based actions. Stable for the lifetime of one read_page.
+      //
+      // Traversal: descend into open shadow roots so web-component-heavy
+      // UIs (e.g. modern React apps with shadow encapsulation) surface
+      // their interactive elements. Cross-origin iframes are not reached
+      // from in-page script — that needs CDP and is documented as a
+      // future enhancement.
+      const INTERACTIVE_ROLES = new Set([
+        "button",
+        "link",
+        "textbox",
+        "combobox",
+        "checkbox",
+        "radio",
+        "switch",
+        "tab",
+        "menuitem",
+        "option",
+        "slider",
+        "searchbox",
+        "spinbutton",
+        "treeitem",
+      ])
+      const INTERACTIVE_TAGS = new Set([
+        "a",
+        "button",
+        "input",
+        "select",
+        "textarea",
+      ])
+      function isInteractive(el) {
+        const role = el.getAttribute("role")
+        if (role && INTERACTIVE_ROLES.has(role)) return true
+        if (INTERACTIVE_TAGS.has(el.tagName.toLowerCase())) return true
+        if (el.hasAttribute("contenteditable") && el.getAttribute("contenteditable") !== "false") return true
+        const ti = el.getAttribute("tabindex")
+        if (ti !== null && Number.parseInt(ti, 10) >= 0) return true
+        return false
+      }
+      function nameOf(el) {
+        const labelledBy = el.getAttribute("aria-labelledby")
+        if (labelledBy) {
+          const labelEl = document.getElementById(labelledBy)
+          if (labelEl) return (labelEl.textContent || "").trim().slice(0, 200)
         }
-      })
-      // Page text: innerText is roughly what a user reads. Cap at
-      // 256 KiB to keep the response tractable.
-      const MAX = 256 * 1024
-      let text = document.body ? document.body.innerText : ""
-      if (text.length > MAX) text = text.slice(0, MAX)
-      // Viewport metadata so the model can correlate CSS-px bbox to
-      // device-px pixels in browser_screenshot (device_px = css_px * dpr).
+        return (
+          el.getAttribute("aria-label")
+          || el.getAttribute("title")
+          || (el.textContent || "")
+          || el.getAttribute("value")
+          || el.getAttribute("placeholder")
+          || el.getAttribute("alt")
+          || ""
+        ).trim().slice(0, 200)
+      }
+      function walkDeep(root, sink) {
+        // Walk every element under root, descending into open shadow
+        // roots. Closed shadow roots are intentionally opaque per the
+        // web spec; nothing we can do.
+        // NodeFilter.SHOW_ELEMENT === 1.
+        const walker = root.createTreeWalker
+          ? root.createTreeWalker(root, 1)
+          : document.createTreeWalker(root, 1)
+        let n
+        while ((n = walker.nextNode())) {
+          sink.push(n)
+          if (n.shadowRoot && n.shadowRoot.mode === "open") {
+            walkDeep(n.shadowRoot, sink)
+          }
+        }
+      }
       const viewport = {
         width: window.innerWidth,
         height: window.innerHeight,
@@ -211,8 +311,258 @@ async function toolReadPage(args) {
         scrollX: window.scrollX,
         scrollY: window.scrollY,
       }
-      return { text, elements, viewport }
+      function inViewport(rect) {
+        return (
+          rect.bottom > 0
+          && rect.right > 0
+          && rect.top < viewport.height
+          && rect.left < viewport.width
+          && rect.width > 0
+          && rect.height > 0
+        )
+      }
+      const allElements = []
+      walkDeep(document, allElements)
+      const interactive = allElements.filter(isInteractive)
+      // Stable refs across snapshots: if an element already carries a
+      // data-gh-router-ref from a prior snapshot, keep it. New elements
+      // get the next unused counter. Result: ref `e42` refers to the
+      // SAME element across reads, so model can do `read_page → click(ref)
+      // → read_page` and the ref-to-element binding stays valid.
+      const usedRefs = new Set()
+      for (const el of interactive) {
+        const existing = el.getAttribute("data-gh-router-ref")
+        if (existing && /^e\d+$/.test(existing)) usedRefs.add(existing)
+      }
+      let nextRef = 1
+      function nextFreshRef() {
+        while (usedRefs.has(`e${nextRef}`)) nextRef++
+        const r = `e${nextRef}`
+        usedRefs.add(r)
+        nextRef++
+        return r
+      }
+      // Summary mode: viewport-visible only; drop nameless non-tag
+      // elements (a div with role="button" but no aria-label is noise).
+      // Full mode: keep everything, model asked for it.
+      const ELEMENT_CAP = 200
+      const LANDMARK_ROLES = new Set([
+        "dialog", "alertdialog", "region", "navigation", "main",
+        "form", "search", "complementary", "banner", "contentinfo",
+      ])
+      const LANDMARK_TAGS = new Set([
+        "dialog", "form", "nav", "main", "header", "footer", "aside", "section",
+      ])
+      // Pre-mint refs for landmark ancestors so child elements can
+      // cite parent refs without a second walk.
+      function landmarkRefsFor(el) {
+        const refs = []
+        let cur = el.parentElement
+        let depth = 0
+        while (cur && depth < 12 && refs.length < 4) {
+          const role = cur.getAttribute && cur.getAttribute("role")
+          const ctag = cur.tagName && cur.tagName.toLowerCase()
+          const isLandmark = (role && LANDMARK_ROLES.has(role)) || LANDMARK_TAGS.has(ctag)
+          if (isLandmark) {
+            let r = cur.getAttribute("data-gh-router-ref")
+            if (!r || !/^e\d+$/.test(r)) {
+              r = nextFreshRef()
+              cur.setAttribute("data-gh-router-ref", r)
+            }
+            refs.push(r)
+          }
+          cur = cur.parentElement
+          depth++
+        }
+        return refs
+      }
+      function stateFlagsFor(el, tag) {
+        const flags = {}
+        // disabled: prefer the property (more reliable than the attr
+        // for inputs / buttons; aria-disabled covers role=button divs).
+        if (el.disabled === true || el.getAttribute("aria-disabled") === "true") flags.disabled = true
+        if (el.checked === true) flags.checked = true
+        else if (el.indeterminate === true) flags.checked = "mixed"
+        else if (el.getAttribute("aria-checked") === "true") flags.checked = true
+        else if (el.getAttribute("aria-checked") === "mixed") flags.checked = "mixed"
+        const aria = (name) => el.getAttribute(name)
+        if (aria("aria-expanded") === "true") flags.expanded = true
+        else if (aria("aria-expanded") === "false") flags.expanded = false
+        if (el.selected === true || aria("aria-selected") === "true") flags.selected = true
+        if (aria("aria-pressed") === "true") flags.pressed = true
+        else if (aria("aria-pressed") === "false") flags.pressed = false
+        if (el.required === true || aria("aria-required") === "true") flags.required = true
+        if (el.readOnly === true || aria("aria-readonly") === "true") flags.readonly = true
+        if (aria("aria-invalid") === "true") flags.invalid = true
+        if (document.activeElement === el) flags.focused = true
+        // hidden: aria-hidden takes precedence; offsetParent === null
+        // covers display:none parents (NOT a reliable visibility check
+        // for fixed-position elements but a reasonable cheap signal).
+        if (aria("aria-hidden") === "true") flags.hidden = true
+        else if (tag !== "body" && el.offsetParent === null && getComputedStyle(el).position !== "fixed") {
+          flags.hidden = true
+        }
+        return flags
+      }
+      function inputExtrasFor(el, tag) {
+        const out = {}
+        if (tag === "input" || tag === "textarea" || tag === "select") {
+          const t = (el.type || "").toLowerCase()
+          if (t) out.inputType = t
+        }
+        const ph = el.placeholder || el.getAttribute("placeholder")
+        if (ph) out.placeholder = String(ph).slice(0, 200)
+        const ac = el.getAttribute("autocomplete")
+        if (ac) out.autocomplete = ac
+        // For inputs / textareas / select, value is the current user
+        // input. Bounded so a huge textarea doesn't bloat the snapshot.
+        if (typeof el.value === "string" && el.value.length > 0) {
+          out.value = el.value.slice(0, 200)
+        }
+        return out
+      }
+      function attrExtrasFor(el) {
+        // Surface raw attrs the matcher's L5 testid layer + L7 semantic
+        // heuristic want to see. Limited to a handful — we don't want
+        // to dump every attribute on every element.
+        const out = {}
+        const id = el.id
+        if (id) out.id = id
+        const testid = el.getAttribute("data-testid") || el.getAttribute("data-test-id")
+          || el.getAttribute("data-test") || el.getAttribute("data-qa")
+        if (testid) out.testid = testid
+        const nameAttr = el.getAttribute("name")
+        if (nameAttr) out.name_attr = nameAttr
+        const aria = el.getAttribute("aria-label")
+        if (aria) out.aria_label = aria
+        return out
+      }
+      const elements = []
+      for (const el of interactive) {
+        if (elements.length >= ELEMENT_CAP) break
+        const rect = el.getBoundingClientRect()
+        if (mode === "summary" && !inViewport(rect)) continue
+        const name = nameOf(el)
+        const tag = el.tagName.toLowerCase()
+        if (mode === "summary" && !name && !INTERACTIVE_TAGS.has(tag)) continue
+        let ref = el.getAttribute("data-gh-router-ref")
+        if (!ref || !/^e\d+$/.test(ref)) {
+          ref = nextFreshRef()
+          el.setAttribute("data-gh-router-ref", ref)
+        }
+        const entry = {
+          ref,
+          role: el.getAttribute("role") || tag,
+          tag,
+          bbox: [
+            Math.round(rect.x),
+            Math.round(rect.y),
+            Math.round(rect.width),
+            Math.round(rect.height),
+          ],
+        }
+        if (name) entry.name = name
+        // Inline state flags onto the entry. Each is omitted when
+        // false / default per the snapshot-types contract.
+        const flags = stateFlagsFor(el, tag)
+        for (const k of Object.keys(flags)) entry[k] = flags[k]
+        // Input-shaped extras (placeholder / inputType / value /
+        // autocomplete) — only present for input-shaped elements.
+        const inExtras = inputExtrasFor(el, tag)
+        if (inExtras.inputType) entry.inputType = inExtras.inputType
+        if (inExtras.placeholder) entry.placeholder = inExtras.placeholder
+        if (inExtras.autocomplete) entry.autocomplete = inExtras.autocomplete
+        if (inExtras.value) entry.value = inExtras.value
+        // Raw attribute extras for L5 testid + L7 semantic layers.
+        // Stored on a single `attrs` object to keep the top-level
+        // shape stable.
+        const attrExtras = attrExtrasFor(el)
+        if (Object.keys(attrExtras).length > 0) entry.attrs = attrExtras
+        // Landmark ancestry — up to 4 deep, dialog / form / nav / etc.
+        const landmarks = landmarkRefsFor(el)
+        if (landmarks.length > 0) entry.landmarks = landmarks
+        elements.push(entry)
+      }
+      // Text extraction.
+      // summary: walk text nodes whose parent is in the viewport; cap
+      // at 20 KB. The model sees what a user could read without
+      // scrolling. Off-screen content remains reachable via mode:"full".
+      // full: 256 KiB innerText cap (legacy behavior).
+      let text = ""
+      if (mode === "full") {
+        const MAX_FULL = 256 * 1024
+        text = document.body ? document.body.innerText : ""
+        if (text.length > MAX_FULL) text = text.slice(0, MAX_FULL)
+      } else {
+        const TEXT_CAP = 20 * 1024
+        const parts = []
+        let total = 0
+        const root = document.body || document.documentElement
+        if (root) {
+          const tw = document.createTreeWalker(root, 4) // NodeFilter.SHOW_TEXT === 4
+          let n
+          while ((n = tw.nextNode())) {
+            const parent = n.parentElement
+            if (!parent) continue
+            // Skip script/style content.
+            const ptag = parent.tagName ? parent.tagName.toLowerCase() : ""
+            if (ptag === "script" || ptag === "style" || ptag === "noscript") continue
+            const pr = parent.getBoundingClientRect()
+            if (!inViewport(pr)) continue
+            const t = (n.textContent || "").replace(/\s+/g, " ").trim()
+            if (!t) continue
+            if (total + t.length + 1 > TEXT_CAP) {
+              parts.push(t.slice(0, Math.max(0, TEXT_CAP - total)))
+              break
+            }
+            parts.push(t)
+            total += t.length + 1
+          }
+        }
+        text = parts.join("\n")
+      }
+      // visualSurfaces: canvas + svg of non-trivial size in the
+      // viewport. Signals "this region needs vision" to the lead model
+      // so it knows to call browser_screenshot / let browser_act
+      // auto-escalate when the text-based pickElement misses.
+      const visualSurfaces = []
+      const VS_MIN = 100
+      const canvasNodes = allElements.filter((el) => {
+        const t = el.tagName && el.tagName.toLowerCase()
+        return t === "canvas" || t === "svg"
+      })
+      for (const el of canvasNodes) {
+        const rect = el.getBoundingClientRect()
+        if (rect.width < VS_MIN || rect.height < VS_MIN) continue
+        if (!inViewport(rect)) continue
+        let ref = el.getAttribute("data-gh-router-ref")
+        if (!ref) {
+          ref = `v${visualSurfaces.length + 1}`
+          el.setAttribute("data-gh-router-ref", ref)
+        }
+        visualSurfaces.push({
+          ref,
+          kind: el.tagName.toLowerCase(),
+          bbox: [
+            Math.round(rect.x),
+            Math.round(rect.y),
+            Math.round(rect.width),
+            Math.round(rect.height),
+          ],
+        })
+      }
+      const out = {
+        mode,
+        url: window.location.href,
+        title: document.title,
+        text,
+        elements,
+        viewport,
+      }
+      if (visualSurfaces.length > 0) out.visualSurfaces = visualSurfaces
+      return out
     },
+    args: [mode],
   })
   if (!result || typeof result.result !== "object") {
     throw new Error("browser_read_page: scripting.executeScript returned nothing")
@@ -232,36 +582,93 @@ async function toolClick(args) {
   const clickCount = typeof args.clickCount === "number" ? args.clickCount : 1
   if (!tabId) throw new Error("browser_click: tabId is required")
   if (!ref && !selector) throw new Error("browser_click: ref or selector is required")
-  const before = await chrome.tabs.get(tabId)
-  const urlBefore = before.url
-  const [result] = await chrome.scripting.executeScript({
-    target: { tabId },
-    func: (ref, selector, button, clickCount) => {
-      const sel = ref ? `[data-gh-router-ref="${ref}"]` : selector
-      const el = document.querySelector(sel)
-      if (!el) return { ok: false, error: `element not found: ${sel}` }
-      // Use native .click() for left-button (handles default action,
-      // form submission, etc); MouseEvent for right-click context menus.
-      if (button === "right") {
-        for (let i = 0; i < clickCount; i++) {
-          el.dispatchEvent(new MouseEvent("contextmenu", { bubbles: true, cancelable: true, button: 2 }))
+  // Subscribe to nav events BEFORE dispatching the click so a fast
+  // click → nav transition can't race past us. Cleanup runs in
+  // finally so an executeScript throw doesn't leak listeners.
+  const navState = watchTabNavigation(tabId)
+  try {
+    const [result] = await chrome.scripting.executeScript({
+      target: { tabId },
+      func: (ref, selector, button, clickCount) => {
+        const sel = ref ? `[data-gh-router-ref="${ref}"]` : selector
+        const el = document.querySelector(sel)
+        if (!el) return { ok: false, error: `element not found: ${sel}` }
+        // Use native .click() for left-button (handles default action,
+        // form submission, etc); MouseEvent for right-click context menus.
+        if (button === "right") {
+          for (let i = 0; i < clickCount; i++) {
+            el.dispatchEvent(new MouseEvent("contextmenu", { bubbles: true, cancelable: true, button: 2 }))
+          }
+        } else {
+          for (let i = 0; i < clickCount; i++) el.click()
         }
-      } else {
-        for (let i = 0; i < clickCount; i++) el.click()
-      }
-      return { ok: true }
-    },
-    args: [ref, selector, button, clickCount],
-  })
-  if (!result || !result.result || !result.result.ok) {
-    throw new Error(`browser_click: ${result?.result?.error ?? "execution failed"}`)
+        return { ok: true }
+      },
+      args: [ref, selector, button, clickCount],
+    })
+    if (!result || !result.result || !result.result.ok) {
+      throw new Error(`browser_click: ${result?.result?.error ?? "execution failed"}`)
+    }
+    // Accurate navigated detection via webNavigation events (replaces the
+    // old 300ms URL-poll which missed slow nav and reported navigated:false
+    // for clicks that DID navigate but took longer to commit). Wait up to
+    // ~150ms for onBeforeNavigate to fire; if it does, then wait up to
+    // ~5s for onCommitted to land. If onBeforeNavigate never fires, no
+    // navigation was triggered — return immediately, no wasted latency.
+    const navigated = await navState.promise
+    return { ok: true, navigated }
+  } finally {
+    navState.cleanup()
+  }
+}
+
+/**
+ * Pre-subscribe to chrome.webNavigation events for an upcoming click
+ * on a tab. Returns a {promise, cleanup} pair. The caller fires the
+ * click AFTER calling this so the listener can never miss the
+ * onBeforeNavigate that the click triggers.
+ *
+ * Promise resolves to:
+ *   - true when onCommitted fires for tabId+frameId 0 within ~5s of
+ *     an onBeforeNavigate also firing on that tab/frame, OR
+ *   - false when onBeforeNavigate doesn't fire within ~150ms post-call
+ *     (= no nav triggered by the click).
+ *
+ * cleanup() removes both listeners — caller MUST invoke from a finally
+ * block to avoid leaking event subscriptions on errors.
+ */
+function watchTabNavigation(tabId) {
+  const NO_NAV_MS = 150
+  const COMMIT_MS = 5000
+  let onBefore
+  let onCommitted
+  let resolved = false
+  let noNavTimer
+  let commitTimer
+  const cleanup = () => {
+    try { if (onBefore) chrome.webNavigation.onBeforeNavigate.removeListener(onBefore) } catch { /* ignore */ }
+    try { if (onCommitted) chrome.webNavigation.onCommitted.removeListener(onCommitted) } catch { /* ignore */ }
+    if (noNavTimer) clearTimeout(noNavTimer)
+    if (commitTimer) clearTimeout(commitTimer)
   }
-  // Brief settle window so clicks that trigger navigation surface in
-  // the response. 300ms is enough to catch immediate-redirect clicks
-  // without significantly slowing the tool's tail latency.
-  await sleep(300)
-  const after = await chrome.tabs.get(tabId)
-  return { ok: true, navigated: after.url !== urlBefore }
+  const promise = new Promise((resolve) => {
+    const settle = (v) => { if (!resolved) { resolved = true; resolve(v) } }
+    onCommitted = (details) => {
+      if (details.tabId === tabId && details.frameId === 0) settle(true)
+    }
+    onBefore = (details) => {
+      if (details.tabId !== tabId || details.frameId !== 0) return
+      // Nav started; switch from "did we get a nav at all" to "wait
+      // for commit". If commit doesn't land in COMMIT_MS, assume the
+      // nav stuck or was cancelled and report true (a nav DID start).
+      if (noNavTimer) { clearTimeout(noNavTimer); noNavTimer = undefined }
+      commitTimer = setTimeout(() => settle(true), COMMIT_MS)
+    }
+    chrome.webNavigation.onBeforeNavigate.addListener(onBefore)
+    chrome.webNavigation.onCommitted.addListener(onCommitted)
+    noNavTimer = setTimeout(() => settle(false), NO_NAV_MS)
+  })
+  return { promise, cleanup }
 }
 
 async function toolFill(args) {
@@ -1289,9 +1696,29 @@ async function attachDebuggerOnce(tabId, opts) {
       networkBuffers.set(tabId, [])
       await chrome.debugger.sendCommand({ tabId }, "Network.enable")
     }
+    // CDP a11y-tree extraction needs DOM + Page + Accessibility
+    // domains enabled. We track them in a single Set so a second
+    // captureSnapshot call on the same tab is a no-op.
+    if (opts?.accessibility && !axDomainsEnabledTabs.has(tabId)) {
+      axDomainsEnabledTabs.add(tabId)
+      try {
+        await chrome.debugger.sendCommand({ tabId }, "DOM.enable")
+        await chrome.debugger.sendCommand({ tabId }, "Page.enable")
+        await chrome.debugger.sendCommand({ tabId }, "Accessibility.enable")
+      } catch (err) {
+        // Roll back the tracking flag so the next call retries.
+        axDomainsEnabledTabs.delete(tabId)
+        throw err
+      }
+    }
   })
 }
 
+// Track which tabs have the CDP a11y domains enabled (DOM + Page +
+// Accessibility). Cleared on debugger.onDetach / tabs.onRemoved
+// alongside the other per-tab state.
+const axDomainsEnabledTabs = new Set()
+
 chrome.debugger.onEvent.addListener((source, method, params) => {
   const tabId = source.tabId
   if (typeof tabId !== "number") return
@@ -1323,6 +1750,12 @@ chrome.debugger.onDetach.addListener((source) => {
     consoleBuffers.delete(source.tabId)
     networkBuffers.delete(source.tabId)
     tabInputLockTails.delete(source.tabId)
+    axDomainsEnabledTabs.delete(source.tabId)
+    // Snapshot cache: CDP-written refs survive a detach (they're DOM
+    // attributes, not CDP state), but bbox/AXNode IDs become unreliable
+    // because re-attach needs a fresh DOM.enable handshake. Safer to
+    // invalidate and re-capture on next read.
+    invalidateSnapshot(source.tabId, "debugger-detach")
   }
 })
 
@@ -1337,6 +1770,22 @@ chrome.tabs.onRemoved.addListener((tabId) => {
   consoleBuffers.delete(tabId)
   networkBuffers.delete(tabId)
   tabInputLockTails.delete(tabId)
+  axDomainsEnabledTabs.delete(tabId)
+  invalidateSnapshot(tabId, "tab-closed")
+})
+
+// Snapshot cache invalidation on top-frame navigation. The legacy ref
+// scheme (data-gh-router-ref DOM attribute) does NOT survive a fresh
+// document load, so a stale snapshot would return refs that resolve
+// to nothing. Invalidate so the next read captures the new document.
+// We intentionally do NOT invalidate on child-frame navigations — a
+// click inside an iframe shouldn't bust the whole-tab snapshot. Phase
+// 1b-CDP will revisit this when cross-origin iframe ref attribution
+// changes the trade-off.
+chrome.webNavigation.onCommitted.addListener((details) => {
+  if (details.frameId === 0 && typeof details.tabId === "number") {
+    invalidateSnapshot(details.tabId, "navigation")
+  }
 })
 
 async function toolConsoleLogs(args) {
@@ -1362,6 +1811,128 @@ async function toolNetworkLog(args) {
   return { entries: drained }
 }
 
+// ---------------------------------------------------------------------
+// Bot-challenge detection (Phase 4 auto-detect)
+// ---------------------------------------------------------------------
+// Listens to chrome.webRequest.onHeadersReceived for response-header
+// fingerprints of major bot-protection vendors. On match: post a
+// `__botDetected__` control frame to the bridge. The bridge tracks
+// which tabs are flagged and the proxy dispatcher consults that state
+// via /health to inject humanlike pacing for paced tabs.
+//
+// Signature confidence tiers:
+//   HIGH (per-vendor, single-hit enables): cf-ray + 403/503, x-dd-b,
+//     x-px-block, x-px-uuid, x-incapsula header on 403.
+//   MEDIUM (cookie / generic — deferred to v2): _abck=*~-1~ cookie,
+//     burst of 403/429 across 5 s window.
+//
+// False-positive guard: only fires when we actually own the
+// connection to the bridge (`nativePort` set). No phantom signals
+// during SW startup before the port opens.
+
+const BOT_DETECTION_VENDORS = {
+  cloudflare: (resp) => {
+    if (resp.statusCode !== 403 && resp.statusCode !== 503) return null
+    const cfRay = headerValue(resp.responseHeaders, "cf-ray")
+    return cfRay ? { signal: "cf-ray + " + resp.statusCode, evidence: cfRay.slice(0, 60) } : null
+  },
+  datadome: (resp) => {
+    const dd = headerValue(resp.responseHeaders, "x-dd-b")
+    return dd === "1" ? { signal: "x-dd-b=1", evidence: "" } : null
+  },
+  perimeterx: (resp) => {
+    if (headerValue(resp.responseHeaders, "x-px-block") === "1") {
+      return { signal: "x-px-block=1", evidence: "" }
+    }
+    const pxUuid = headerValue(resp.responseHeaders, "x-px-uuid")
+    if (pxUuid && (resp.statusCode === 403 || resp.statusCode === 429)) {
+      return { signal: "x-px-uuid + " + resp.statusCode, evidence: pxUuid.slice(0, 36) }
+    }
+    return null
+  },
+  imperva: (resp) => {
+    if (resp.statusCode !== 403) return null
+    const iinfo = headerValue(resp.responseHeaders, "x-iinfo")
+    return iinfo ? { signal: "x-iinfo + 403", evidence: iinfo.slice(0, 40) } : null
+  },
+}
+
+function headerValue(headers, name) {
+  if (!Array.isArray(headers)) return undefined
+  const lower = name.toLowerCase()
+  for (const h of headers) {
+    if (h.name && h.name.toLowerCase() === lower) return h.value
+  }
+  return undefined
+}
+
+// Per-tab deduplication: a single vendor's signature firing repeatedly
+// on a tab should emit ONE control frame, not one per response. Bridge
+// already de-dupes by tabId on its side; we de-dupe here too to keep
+// the wire quiet.
+const detectedVendorsByTab = new Map() // tabId -> Set<vendor>
+
+function emitBotDetected(tabId, vendor, signal, evidence) {
+  if (typeof tabId !== "number" || tabId < 0) return
+  if (!nativePort) return
+  let seen = detectedVendorsByTab.get(tabId)
+  if (!seen) {
+    seen = new Set()
+    detectedVendorsByTab.set(tabId, seen)
+  }
+  if (seen.has(vendor)) return
+  seen.add(vendor)
+  try {
+    nativePort.postMessage({
+      type: "__botDetected__",
+      tabId,
+      vendor,
+      signal,
+      evidence,
+      ts: Date.now(),
+    })
+  } catch (err) {
+    console.warn("[browser-bridge/bot-detect] post failed:", err)
+  }
+}
+
+// MAIN frame only — sub-resource 403s on tracking pixels are common
+// noise. Vendor blocks always land on the main document request.
+try {
+  chrome.webRequest.onHeadersReceived.addListener(
+    (details) => {
+      try {
+        for (const [vendor, probe] of Object.entries(BOT_DETECTION_VENDORS)) {
+          const hit = probe(details)
+          if (hit) {
+            emitBotDetected(details.tabId, vendor, hit.signal, hit.evidence)
+            break
+          }
+        }
+      } catch (err) {
+        console.warn("[browser-bridge/bot-detect] probe crashed:", err)
+      }
+    },
+    { urls: ["<all_urls>"], types: ["main_frame"] },
+    ["responseHeaders"],
+  )
+} catch (err) {
+  // webRequest permission may not be granted on some enterprise
+  // policies; auto-detect just no-ops in that case.
+  console.warn("[browser-bridge/bot-detect] webRequest listener registration failed:", err)
+}
+
+// Cleanup: clear vendor dedup state on navigation + tab close so a
+// new document gets a fresh detection window.
+chrome.webNavigation.onCommitted.addListener((details) => {
+  if (details.frameId === 0 && typeof details.tabId === "number") {
+    detectedVendorsByTab.delete(details.tabId)
+  }
+})
+chrome.tabs.onRemoved.addListener((tabId) => {
+  detectedVendorsByTab.delete(tabId)
+})
+
 const TOOL_HANDLERS = {
   __ping__: () => ({
     pong: true,
@@ -1438,11 +2009,39 @@ function connectBridge() {
     nativePort = undefined
   })
   nativePort = port
+  // Hello frame — lets the bridge associate this connection with a
+  // version. Pre-flight on the proxy side compares this against the
+  // version stamped into dist/browser-ext/manifest.json at build, and
+  // triggers an auto-reload (via __reload__ control frame) when the
+  // package has been updated but the loaded extension is stale.
+  try {
+    port.postMessage({
+      type: "__hello__",
+      version: chrome.runtime.getManifest().version,
+    })
+  } catch (err) {
+    console.warn("[browser-bridge] hello frame failed:", err)
+  }
   return port
 }
 
 async function handleBridgeRequest(req, port) {
-  if (!req || typeof req.id !== "string" || typeof req.tool !== "string") return
+  if (!req) return
+  // Control frames — not regular tool dispatches. The bridge sends
+  // these out-of-band; the {id, tool, args} shape doesn't apply.
+  if (req.type === "__reload__") {
+    // chrome.runtime.reload terminates this service worker and starts
+    // a fresh one that re-reads on-disk files. Used by the proxy's
+    // pre-flight when the loaded extension version doesn't match the
+    // version stamped into dist/browser-ext/manifest.json.
+    try {
+      chrome.runtime.reload()
+    } catch (err) {
+      console.warn("[browser-bridge] reload failed:", err)
+    }
+    return
+  }
+  if (typeof req.id !== "string" || typeof req.tool !== "string") return
   const handler = TOOL_HANDLERS[req.tool]
   if (!handler) {
     port.postMessage({ id: req.id, ok: false, error: `unknown tool: ${req.tool}`, code: "unknown_tool" })
@@ -1451,11 +2050,43 @@ async function handleBridgeRequest(req, port) {
   try {
     const data = await handler(req.args || {})
     port.postMessage({ id: req.id, ok: true, data })
+    // Snapshot cache invalidation for mutating actions. The matcher
+    // cascade (Phase 2) dispatches against cached snapshots; a
+    // successful click / fill / type / etc. likely changed the page,
+    // so the cached element list is stale. Invalidate by tabId from
+    // the request args; tools that don't carry a tabId (open_tab on
+    // create-path, list_tabs) are not page-mutating per-tab so they
+    // skip this.
+    if (MUTATES_PAGE.has(req.tool)) {
+      const tabId = typeof req.args?.tabId === "number" ? req.args.tabId : undefined
+      if (typeof tabId === "number") {
+        invalidateSnapshot(tabId, `mutation:${req.tool}`)
+      }
+    }
   } catch (err) {
     port.postMessage({ id: req.id, ok: false, error: err && err.message ? err.message : String(err) })
   }
 }
 
+// Tools whose successful execution likely mutates the page's DOM,
+// triggering snapshot-cache invalidation for the tabId in args. Kept
+// as a Set rather than per-tool flags so adding a new mutating tool
+// is one line. Conservative: tools listed here MAY not mutate (e.g.
+// click on a disabled button is a no-op); the cost of a spurious
+// invalidate is one extra capture on next read, vs the cost of a
+// stale snapshot which is silent dispatch against a vanished ref.
+const MUTATES_PAGE = new Set([
+  "browser_click",
+  "browser_fill",
+  "browser_type",
+  "browser_keyboard",
+  "browser_scroll",
+  "browser_mouse",
+  "browser_drag",
+  "browser_navigate",
+  "browser_eval_js",
+])
+
 chrome.runtime.onInstalled.addListener(() => {
   try { connectBridge() } catch (err) { console.warn("[browser-bridge] onInstalled connect failed:", err) }
 })
@@ -1483,17 +2114,17 @@ chrome.tabs.onUpdated.addListener(() => {
   try { connectBridge() } catch (err) { console.warn("[browser-bridge] onUpdated connect failed:", err) }
 })
 
-// Defense in depth — webNavigation listener catches in-page-initiated
-// navigations (JS-driven redirects, meta-refresh, anchor clicks the
-// model didn't go through browser_navigate for). Tool-initiated paths
-// already pre-check via isBlockedUrl() / the bridge-layer policy.ts,
-// so this is the safety net for navigations the bridge can't see.
-//
-// On match: cancel the navigation by routing the tab back to
-// about:blank, AND log a console.error so browser_console_logs can
-// surface "the model tried to navigate to a blocked URL" on the next
-// drain. The cancel happens via chrome.tabs.update — there's no
-// onBeforeNavigate "cancel" API in MV3.
+// webNavigation.onBeforeNavigate fires for ALL top-level navigations
+// — user-typed URL bar entries AND in-page-initiated nav (JS redirect,
+// meta-refresh, anchor clicks). It does NOT expose transitionType, so
+// we can't cheaply distinguish initiator at this stage. Consequence:
+// every URL in BLOCKED_URL_RE is unreachable when this extension is
+// enabled, including for the human user. `extensions` is deliberately
+// excluded from BLOCKED_URL_RE to preserve user access to the page
+// they need to manage this extension; bridge-side policy.ts still
+// rejects tool-initiated nav there. On match: route the tab back to
+// about:blank (no onBeforeNavigate cancel API in MV3) and log a
+// console.error so browser_console_logs can surface it on next drain.
 chrome.webNavigation.onBeforeNavigate.addListener((details) => {
   if (details.frameId !== 0) return  // only top-level frame
   if (isBlockedUrl(details.url)) {