@jobshimo/browser-link 0.21.0 → 0.23.0

package/dist/cdp/inpage/builders.js

@@ -0,0 +1,501 @@
+/**
+ * Independent copy of `packages/extension/src/inpage/builders.ts` — see
+ * `./deep-query.ts`'s header comment for why this is a verbatim duplicate
+ * rather than a cross-package import.
+ *
+ * DELIBERATELY A SUBSET: only the builders `cdp/transport.ts` needs for
+ * cdp-direct's v1 supported tool set (snapshot, find, click, type, press,
+ * state, plus the shared settle wait) are copied. `buildDragProbeJs` /
+ * `DragProbeOpts` are NOT copied — `browser.drag` is explicitly out of
+ * v1 scope for cdp-direct (see the README's cdp-direct tool-support table
+ * and `cdp/transport.ts`'s `CDP_TOOL_SUPPORT`). If drag is ever added to
+ * cdp-direct, copy `buildDragProbeJs` here at that time.
+ *
+ * Builders that assemble the CDP `Runtime.evaluate` expression strings for
+ * `snapshot`, `find`, `click`, `type`, `press` and the shared post-action
+ * `settle` wait. The exact same string the extension sends over CDP. Because
+ * this file is a SUBSET it is not byte-compared wholesale; instead the two
+ * security-critical pieces it interpolates — `DEEP_QUERY_JS` and
+ * `DOM_HELPERS_JS` — are asserted byte-identical to their extension siblings
+ * by `cdp/drift.test.ts`, and `cdp/inpage/builders.test.ts` proves this copy
+ * embeds exactly those shared helpers.
+ */
+import { DEEP_QUERY_JS } from './deep-query.js';
+import { DOM_HELPERS_JS } from './dom-helpers.js';
+export function buildSnapshotJs(opts = {}) {
+    const optsJson = JSON.stringify({
+        withinSelector: typeof opts.within_selector === 'string' ? opts.within_selector : null,
+        onlyInteractive: opts.only_interactive === true,
+        exclude: Array.isArray(opts.exclude) ? opts.exclude : [],
+        maxInteractive: typeof opts.max_interactive === 'number' && opts.max_interactive > 0
+            ? Math.min(opts.max_interactive, 500)
+            : 120,
+    });
+    return `
+(() => {
+  ${DEEP_QUERY_JS}
+  ${DOM_HELPERS_JS}
+  const opts = ${optsJson};
+  let root = document;
+  let notice = '';
+  if (opts.withinSelector) {
+    const sub = deepQueryFirst(opts.withinSelector);
+    if (!sub) {
+      return {
+        title: document.title,
+        url: location.href,
+        interactive: [],
+        notice: 'within_selector did not match any element',
+      };
+    }
+    root = sub;
+  }
+  const excludeSet = new Set((opts.exclude || []).map(s => String(s).toLowerCase()));
+  function inExcludedLandmark(el) {
+    // Composed-tree climb (same pattern as composedContains): walking via
+    // parentElement alone would stop dead at a shadow boundary — a button
+    // inside a web component slotted into <nav> would escape exclusion.
+    // parentNode reaches the ShadowRoot; jumping to .host continues the
+    // climb in the host document.
+    if (excludeSet.size === 0) return false;
+    let cur = el.parentNode;
+    let guard = 0;
+    while (cur && guard < 1000) {
+      guard++;
+      if (cur === root) return false;
+      if (cur.nodeType === 1) {
+        const tag = cur.tagName ? cur.tagName.toLowerCase() : '';
+        if (excludeSet.has(tag)) return true;
+        if (cur === document.body) return false;
+        cur = cur.parentNode;
+        continue;
+      }
+      if (cur.host) {
+        cur = cur.host;
+        continue;
+      }
+      break;
+    }
+    return false;
+  }
+  const sel = 'a[href], button, input, select, textarea, [role=button], [role=link], [role=checkbox], [role=tab], [role=menuitem], [contenteditable=true]';
+  const interactive = [];
+  deepQueryAll(sel, root).forEach((el) => {
+    if (!isVisible(el)) return;
+    if (inExcludedLandmark(el)) return;
+    const tag = el.tagName.toLowerCase();
+    const role = el.getAttribute('role') || tag;
+    const selInfo = genSelectorInfo(el);
+    const entry = { tag, role, selector: selInfo.selector };
+    if (selInfo.ambiguous) entry.ambiguous = true;
+    const txt = shortText(el);
+    if (txt) entry.text = txt;
+    if ('value' in el && el.value) entry.value = String(el.value);
+    const placeholder = el.getAttribute('placeholder');
+    if (placeholder) entry.placeholder = placeholder;
+    const aria_label = el.getAttribute('aria-label');
+    if (aria_label) entry.aria_label = aria_label;
+    const name = el.getAttribute('name');
+    if (name) entry.name = name;
+    const type = el.getAttribute('type');
+    if (type) entry.type = type;
+    const href = el.getAttribute('href');
+    if (href) entry.href = href;
+    if ('disabled' in el && el.disabled) entry.disabled = true;
+    const frame = frameSelectorFor(el);
+    if (frame) entry.frame = frame;
+    interactive.push(entry);
+  });
+  const result = {
+    title: document.title,
+    url: location.href,
+    interactive: interactive.slice(0, opts.maxInteractive),
+  };
+  if (!opts.onlyInteractive) {
+    const headings = [];
+    deepQueryAll('h1, h2, h3', root).forEach((h) => {
+      if (!isVisible(h)) return;
+      if (inExcludedLandmark(h)) return;
+      const t = shortText(h);
+      if (t) headings.push({ level: h.tagName, text: t });
+    });
+    result.headings = headings.slice(0, 30);
+    const textRoot = (root === document) ? (document.body || document) : root;
+    const visibleText = (textRoot && textRoot.innerText) ? textRoot.innerText.slice(0, 4000) : '';
+    if (visibleText) result.text = visibleText;
+  }
+  if (notice) result.notice = notice;
+  return result;
+})()
+`;
+}
+export function buildFindJs(opts) {
+    const optsJson = JSON.stringify({
+        text: opts.text,
+        role: typeof opts.role === 'string' && opts.role.length > 0 ? opts.role : null,
+        exact: opts.exact === true,
+        candidateLimit: 5,
+        nearMissLimit: 3,
+    });
+    return `
+(() => {
+  ${DEEP_QUERY_JS}
+  ${DOM_HELPERS_JS}
+  const opts = ${optsJson};
+  const needle = opts.text.toLowerCase();
+  const needleTokens = needle.split(/[^a-z0-9]+/).filter(Boolean);
+  const ROLE_SELECTORS = {
+    button: 'button, [role="button"], input[type="button"], input[type="submit"], input[type="reset"]',
+    link: 'a[href], [role="link"]',
+    textbox: 'input[type="text"], input[type="email"], input[type="password"], input[type="search"], input[type="url"], input[type="tel"], input:not([type]), textarea, [role="textbox"], [contenteditable="true"]',
+    checkbox: 'input[type="checkbox"], [role="checkbox"]',
+    tab: '[role="tab"]',
+    menuitem: '[role="menuitem"]',
+  };
+  const BROAD_SELECTOR = 'button, a, input, textarea, select, [role], [onclick], [contenteditable="true"], [tabindex]';
+  const selectorSet = opts.role && ROLE_SELECTORS[opts.role]
+    ? ROLE_SELECTORS[opts.role]
+    : BROAD_SELECTOR;
+  const all = deepQueryAll(selectorSet);
+  const matches = [];
+  for (const el of all) {
+    if (!isVisible(el)) continue;
+    const text = accessibleText(el).trim();
+    if (text.length === 0) continue;
+    const lower = text.toLowerCase();
+    const ok = opts.exact ? lower === needle : lower.includes(needle);
+    if (ok) matches.push(el);
+  }
+  if (matches.length === 0) {
+    // Near-miss ranking: containment beats token overlap; anything scoring
+    // 0 is dropped so the suggestion list never pads itself with noise.
+    function snippetOf(el) {
+      const t = accessibleText(el).trim();
+      return t.length > 60 ? t.slice(0, 60) + '...' : t;
+    }
+    function scoreText(text) {
+      const lower = text.toLowerCase();
+      const contains = lower.includes(needle);
+      const candTokens = lower.split(/[^a-z0-9]+/).filter(Boolean);
+      let overlap = 0;
+      for (let i = 0; i < needleTokens.length; i++) {
+        if (candTokens.indexOf(needleTokens[i]) !== -1) overlap++;
+      }
+      if (!contains && overlap === 0) return -1;
+      return (contains ? 1000 : 0) + overlap * 10;
+    }
+    function rankCandidates(elements) {
+      const scored = [];
+      for (const el of elements) {
+        if (!isVisible(el)) continue;
+        const text = accessibleText(el).trim();
+        if (text.length === 0) continue;
+        const score = scoreText(text);
+        if (score < 0) continue;
+        scored.push({ el: el, score: score });
+      }
+      scored.sort((a, b) => b.score - a.score);
+      return scored.slice(0, opts.nearMissLimit).map((s) => s.el);
+    }
+    function toNearMiss(el) {
+      const entry = { text: snippetOf(el), selector: genSelector(el) };
+      const roleAttr = el.getAttribute('role');
+      if (roleAttr) entry.role = roleAttr;
+      return entry;
+    }
+    function describeForError(el) {
+      const tag = el.tagName.toLowerCase();
+      if (el.hasAttribute('onclick')) return '<' + tag + ' onclick>';
+      const role = el.getAttribute('role');
+      if (role) return '<' + tag + ' role="' + role + '">';
+      return '<' + tag + '>';
+    }
+    const result = { matched: false, reason: 'not-found' };
+    if (opts.role) {
+      // Role narrowed the scan — check whether the text exists OUTSIDE the
+      // role filter so the error can name the exclusion explicitly instead
+      // of reporting a bare not-found.
+      const broadAll = deepQueryAll(BROAD_SELECTOR);
+      const broadTextMatches = [];
+      for (const el of broadAll) {
+        if (!isVisible(el)) continue;
+        const text = accessibleText(el).trim();
+        if (text.length === 0) continue;
+        if (text.toLowerCase().includes(needle)) broadTextMatches.push(el);
+      }
+      if (broadTextMatches.length > 0) {
+        const ranked = rankCandidates(broadTextMatches);
+        const closest = ranked[0];
+        result.error = 'text matched ' + broadTextMatches.length + ' element' +
+          (broadTextMatches.length === 1 ? '' : 's') +
+          ' but none with role "' + opts.role + '"' +
+          (closest ? ' — closest: ' + describeForError(closest) + ' "' + snippetOf(closest) + '"' : '');
+        result.near_misses = ranked.map(toNearMiss);
+        return result;
+      }
+      const ranked = rankCandidates(broadAll);
+      if (ranked.length > 0) result.near_misses = ranked.map(toNearMiss);
+      return result;
+    }
+    const ranked = rankCandidates(all);
+    if (ranked.length > 0) result.near_misses = ranked.map(toNearMiss);
+    return result;
+  }
+  if (matches.length > 1) {
+    return {
+      matched: false,
+      reason: 'multiple-matches',
+      candidates: matches.slice(0, opts.candidateLimit).map((el) => ({
+        selector: genSelector(el),
+        text: shortText(el),
+        tag: el.tagName.toLowerCase(),
+      })),
+    };
+  }
+  const el = matches[0];
+  const center = viewportCenterOf(el);
+  const selInfo = genSelectorInfo(el);
+  const result = {
+    matched: true,
+    selector: selInfo.selector,
+    coords: {
+      x: Math.round(center.x),
+      y: Math.round(center.y),
+    },
+    tag: el.tagName.toLowerCase(),
+    text: shortText(el),
+  };
+  if (selInfo.ambiguous) result.ambiguous = true;
+  const frame = frameSelectorFor(el);
+  if (frame) result.frame = frame;
+  return result;
+})()
+`;
+}
+export function buildClickResolveJs(opts) {
+    const optsJson = JSON.stringify({ selector: opts.selector, force: opts.force });
+    return `
+(() => {
+  ${DEEP_QUERY_JS}
+  const opts = ${optsJson};
+  try {
+    document.querySelector(opts.selector);
+  } catch (e) {
+    return { ok: false, reason: 'invalid-selector', error: e && e.message ? e.message : String(e) };
+  }
+  const el = deepQueryFirst(opts.selector);
+  if (!el) return { ok: false, reason: 'not-found' };
+  const chain = frameElementChain(el);
+  for (const fe of chain) {
+    if (fe.scrollIntoView) fe.scrollIntoView({ block: 'center', inline: 'center' });
+  }
+  if (el.scrollIntoView) el.scrollIntoView({ block: 'center', inline: 'center' });
+  const center = viewportCenterOf(el);
+  const tag = el.tagName.toLowerCase();
+  if (!opts.force) {
+    const occlusion = checkOcclusion(el, center.localX, center.localY);
+    if (!occlusion.allowed) {
+      return { ok: false, reason: 'occluded', blocker: occlusion.blocker };
+    }
+  }
+  return { ok: true, x: center.x, y: center.y, tag };
+})()
+`;
+}
+export function buildTypeResolveJs(opts) {
+    const optsJson = JSON.stringify({ selector: opts.selector });
+    return `
+(() => {
+  ${DEEP_QUERY_JS}
+  const opts = ${optsJson};
+  try {
+    document.querySelector(opts.selector);
+  } catch (e) {
+    return { ok: false, reason: 'invalid-selector', error: e && e.message ? e.message : String(e) };
+  }
+  const el = deepQueryFirst(opts.selector);
+  if (!el) return { ok: false, reason: 'not-found' };
+  el.focus();
+  ${opts.clear ? "if ('value' in el) { el.value = ''; el.dispatchEvent(new Event('input', { bubbles: true })); }" : ''}
+  return { ok: true };
+})()`;
+}
+export function buildFocusJs(opts) {
+    const optsJson = JSON.stringify({ selector: opts.selector });
+    return `
+(() => {
+  ${DEEP_QUERY_JS}
+  const opts = ${optsJson};
+  const el = deepQueryFirst(opts.selector);
+  if (!el) return false;
+  el.focus();
+  return true;
+})()`;
+}
+export function buildSettleJs(opts) {
+    const optsJson = JSON.stringify({
+        settleMs: Math.max(0, opts.settle_ms),
+        timeoutMs: Math.max(0, opts.settle_timeout_ms),
+    });
+    return `
+(() => {
+  const opts = ${optsJson};
+  const startUrl = location.href;
+  const startActiveEl = document.activeElement;
+  const state = { mutationCount: 0, lastMutationAt: Date.now() };
+  const observer = new MutationObserver((mutations) => {
+    state.mutationCount += mutations.length;
+    state.lastMutationAt = Date.now();
+  });
+  observer.observe(document, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+    characterData: true,
+  });
+  const start = Date.now();
+  return new Promise((resolve) => {
+    function finish(settled) {
+      observer.disconnect();
+      const result = {
+        settled: settled,
+        duration_ms: Date.now() - start,
+        mutation_count: state.mutationCount,
+      };
+      if (location.href !== startUrl) result.url_changed = location.href;
+      if (document.activeElement !== startActiveEl) result.focus_moved = true;
+      resolve(result);
+    }
+    if (opts.settleMs <= 0) {
+      finish(true);
+      return;
+    }
+    (function check() {
+      const now = Date.now();
+      const quietFor = now - state.lastMutationAt;
+      if (quietFor >= opts.settleMs) {
+        finish(true);
+        return;
+      }
+      if (now - start >= opts.timeoutMs) {
+        finish(false);
+        return;
+      }
+      setTimeout(check, Math.min(opts.settleMs - quietFor, 50));
+    })();
+  });
+})()`;
+}
+/**
+ * Build the `browser.state` expression: a compact orientation snapshot —
+ * current url/title, the deep-resolved focused element, visible dialog-role
+ * elements, scroll position, and viewport size. Cheaper than a full
+ * `browser.snapshot` when the agent only needs "where am I right now".
+ *
+ * `focused` descends through `document.activeElement` past shadow-root and
+ * same-origin-iframe boundaries to the real innermost focused element (a
+ * shadow host or an <iframe> being "active" at one level is not the actual
+ * focus target the agent cares about). Its `selector` goes through the same
+ * `genSelectorInfo` uniqueness check `snapshot`/`find` use, so it carries
+ * `ambiguous: true` under the same structurally-identical-twins condition.
+ *
+ * `dialogs` matches visible `[role=dialog]`, `[role=alertdialog]` and open
+ * `<dialog>` elements found via the same deep walk, with a best-effort
+ * `label` resolved from aria-label / aria-labelledby / the first heading
+ * inside the dialog.
+ *
+ * Every optional field is omitted when there is nothing to report: no
+ * `focused` beyond `<body>`, no `dialogs` when none are open, and no
+ * `scroll` when the page is at its default (0,0) position — token-lean by
+ * construction, matching the omit-falsy convention the other builders use.
+ */
+export function buildStateJs() {
+    return `
+(() => {
+  ${DEEP_QUERY_JS}
+  ${DOM_HELPERS_JS}
+  function deepActiveElement() {
+    let el = document.activeElement;
+    let guard = 0;
+    while (el && guard < 20) {
+      guard++;
+      if (el.shadowRoot && el.shadowRoot.activeElement) {
+        el = el.shadowRoot.activeElement;
+        continue;
+      }
+      if (el.tagName === 'IFRAME') {
+        let innerDoc = null;
+        try {
+          innerDoc = el.contentDocument;
+        } catch (_) {
+          innerDoc = null;
+        }
+        if (innerDoc && innerDoc.activeElement && innerDoc.activeElement !== innerDoc.body) {
+          el = innerDoc.activeElement;
+          continue;
+        }
+      }
+      break;
+    }
+    return el;
+  }
+  function dialogLabel(el) {
+    const aria = el.getAttribute('aria-label');
+    if (aria) return aria;
+    const labelledby = el.getAttribute('aria-labelledby');
+    if (labelledby) {
+      const ids = labelledby.split(/\\s+/);
+      const parts = [];
+      for (let i = 0; i < ids.length; i++) {
+        if (!ids[i]) continue;
+        const target = deepQueryFirst('#' + CSS.escape(ids[i]));
+        if (target) {
+          const t = shortText(target);
+          if (t) parts.push(t);
+        }
+      }
+      const joined = parts.join(' ').trim();
+      if (joined) return joined;
+    }
+    const heading = deepQueryFirst('h1, h2, h3', el);
+    if (heading) {
+      const t = shortText(heading);
+      if (t) return t;
+    }
+    return '';
+  }
+
+  const result = {
+    url: location.href,
+    title: document.title,
+    viewport: { w: window.innerWidth, h: window.innerHeight },
+  };
+
+  const active = deepActiveElement();
+  if (active && active !== document.body && active.tagName) {
+    const selInfo = genSelectorInfo(active);
+    const focused = { selector: selInfo.selector, tag: active.tagName.toLowerCase() };
+    if (selInfo.ambiguous) focused.ambiguous = true;
+    result.focused = focused;
+  }
+
+  const dialogs = [];
+  deepQueryAll('[role="dialog"], [role="alertdialog"], dialog[open]').forEach((el) => {
+    if (!isVisible(el)) return;
+    const role = el.getAttribute('role') || 'dialog';
+    const entry = { selector: genSelector(el), role: role };
+    const label = dialogLabel(el);
+    if (label) entry.label = label;
+    dialogs.push(entry);
+  });
+  if (dialogs.length > 0) result.dialogs = dialogs;
+
+  const scrollX = Math.round(window.scrollX);
+  const scrollY = Math.round(window.scrollY);
+  if (scrollX !== 0 || scrollY !== 0) result.scroll = { x: scrollX, y: scrollY };
+
+  return result;
+})()
+`;
+}
+//# sourceMappingURL=builders.js.map

package/dist/cdp/inpage/builders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.js","sourceRoot":"","sources":["../../../src/cdp/inpage/builders.ts"],"names":[],"mappings":"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"}

package/dist/cdp/inpage/deep-query.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Independent copy of `packages/extension/src/inpage/deep-query.ts` — used
+ * by the cdp-direct transport (`../transport.ts`) to build the exact same
+ * `Runtime.evaluate` expressions the extension's `background.ts` sends,
+ * over a raw CDP-over-WS connection instead of `chrome.debugger`.
+ *
+ * Duplicated rather than imported for the same reason `config.ts` and
+ * `messages.ts` keep independent copies of extension-side constants/types:
+ * `@jobshimo/browser-link` (this package) publishes to npm standalone and
+ * must not carry a workspace dependency on `@browser-link/extension` (a
+ * private, unpublished package with `chrome.*` types in its own tsconfig).
+ * This file is copied VERBATIM — it has zero `chrome.*` references (it only
+ * builds a JS-source string that runs inside the TARGET PAGE, never the
+ * extension/server process), so there is nothing to adapt. If the source
+ * file changes, re-copy it here — the exported `DEEP_QUERY_JS` body is
+ * asserted byte-identical to the sibling at
+ * `packages/extension/src/inpage/deep-query.ts` by `cdp/drift.test.ts`,
+ * which fails the build if the two ever diverge (a security fix to one copy
+ * must reach the other).
+ *
+ * In-page JS source injected into CDP `Runtime.evaluate` expressions. This
+ * is the "deep search" layer that lets `snapshot`, `find`, `click` and
+ * `type` see past two boundaries plain `document.querySelector` /
+ * `document.querySelectorAll` cannot cross:
+ *
+ *   - OPEN Shadow DOM roots (`element.attachShadow({ mode: 'open' })`),
+ *     walked recursively (shadow roots nested inside shadow roots).
+ *   - Same-origin `<iframe>` documents, walked recursively (iframes nested
+ *     inside iframes, shadow roots nested inside iframes and vice versa).
+ *
+ * Exported as a raw string, not real TypeScript — it runs inside the
+ * TARGET PAGE's JS context via CDP `Runtime.evaluate`, not inside this
+ * process. Keep the syntax plain (`var`/`function`, no optional chaining
+ * assumptions) since it must run unmodified in whatever JS engine the
+ * connected tab uses.
+ *
+ * Known limitations (also documented on the MCP tool descriptions):
+ *   - CLOSED shadow roots (`{ mode: 'closed' }`) are unreachable from page
+ *     world JS — `element.shadowRoot` is `null` for them by design. There
+ *     is no CDP-level workaround from `Runtime.evaluate`.
+ *   - CROSS-ORIGIN iframes are unreachable — `contentDocument` throws or
+ *     returns null under the same-origin policy. Access is wrapped in
+ *     try/catch so a cross-origin frame is silently skipped rather than
+ *     failing the whole query.
+ *   - A plain CSS selector cannot distinguish between two elements that
+ *     produce byte-identical generated selectors in two different roots
+ *     (e.g. two structurally-identical Shadow DOM component instances).
+ *     `deepQueryFirst` returns the first match in traversal order
+ *     (the start root itself, then nested shadow roots, then nested
+ *     same-origin iframe documents, depth-first). Extremely rare in
+ *     practice — real content differs — but worth knowing when a page
+ *     repeats the exact same component markup in multiple places. When
+ *     selector generation cannot avoid this (see `genSelectorInfo` in
+ *     `dom-helpers.ts`), snapshot/find mark the affected entry with
+ *     `ambiguous: true` so agents know not to cache that selector.
+ */
+export declare const DEEP_QUERY_JS = "\n  function collectSearchRoots(start) {\n    // start: a Document, Element or ShadowRoot to scope the search to.\n    // Returns [start, ...every open shadow root and same-origin iframe\n    // document reachable inside start's subtree, recursively]. The caller\n    // runs .querySelectorAll()/.querySelector() on each entry directly \u2014\n    // each entry's own querySelectorAll does NOT pierce into nested shadow\n    // roots or iframes on its own, which is why we enumerate them here.\n    var roots = [start];\n    function walk(scope, depth) {\n      // Depth guard, same pattern as the other recursive helpers here:\n      // pathological nesting (or a cycle introduced by a broken mock)\n      // must degrade to a truncated result, never a stack overflow.\n      if (depth > 20) return;\n      var all;\n      try {\n        all = scope.querySelectorAll('*');\n      } catch (_) {\n        return;\n      }\n      for (var i = 0; i < all.length; i++) {\n        var el = all[i];\n        if (el.shadowRoot) {\n          roots.push(el.shadowRoot);\n          walk(el.shadowRoot, depth + 1);\n        }\n        if (el.tagName === 'IFRAME') {\n          var doc = null;\n          try {\n            doc = el.contentDocument;\n          } catch (_) {\n            doc = null;\n          }\n          if (doc) {\n            roots.push(doc);\n            walk(doc, depth + 1);\n          }\n        }\n      }\n    }\n    walk(start, 0);\n    return roots;\n  }\n\n  function deepWalkAll(callback, start) {\n    // Tree-walk primitive: invoke callback(el) for every element reachable\n    // from start (default: document) across the top document, every open\n    // shadow root, and every same-origin iframe document.\n    var root = start || document;\n    var roots = collectSearchRoots(root);\n    for (var r = 0; r < roots.length; r++) {\n      var all;\n      try {\n        all = roots[r].querySelectorAll('*');\n      } catch (_) {\n        continue;\n      }\n      for (var i = 0; i < all.length; i++) callback(all[i]);\n    }\n  }\n\n  function deepQueryAll(selector, start) {\n    var root = start || document;\n    var roots = collectSearchRoots(root);\n    var out = [];\n    for (var r = 0; r < roots.length; r++) {\n      var found;\n      try {\n        found = roots[r].querySelectorAll(selector);\n      } catch (_) {\n        continue;\n      }\n      for (var i = 0; i < found.length; i++) out.push(found[i]);\n    }\n    return out;\n  }\n\n  function deepQueryFirst(selector, start) {\n    var root = start || document;\n    var roots = collectSearchRoots(root);\n    for (var r = 0; r < roots.length; r++) {\n      var el = null;\n      try {\n        el = roots[r].querySelector(selector);\n      } catch (_) {\n        el = null;\n      }\n      if (el) return el;\n    }\n    return null;\n  }\n\n  function frameElementChain(el) {\n    // Walk up from el's own window to the top window, collecting the\n    // <iframe> element that hosts each intermediate document. Outermost\n    // frame first. Same-origin only \u2014 frameElement throws/returns null\n    // across an origin boundary, at which point the chain simply stops\n    // (the coordinate math below degrades gracefully rather than throwing).\n    var chain = [];\n    var doc = el.ownerDocument;\n    var win = doc && doc.defaultView;\n    if (!win) return chain;\n    var topWin;\n    try {\n      topWin = win.top;\n    } catch (_) {\n      topWin = win;\n    }\n    var guard = 0;\n    while (win && win !== topWin && guard < 20) {\n      guard++;\n      var fe = null;\n      try {\n        fe = win.frameElement;\n      } catch (_) {\n        fe = null;\n      }\n      if (!fe) break;\n      chain.unshift(fe);\n      win = fe.ownerDocument && fe.ownerDocument.defaultView;\n    }\n    return chain;\n  }\n\n  function frameViewportOriginOffset(fe) {\n    // The embedded document's viewport origin sits at the frame element's\n    // CONTENT box, but getBoundingClientRect() returns the BORDER box \u2014\n    // border and padding must be added on top of rect.left/rect.top or\n    // every coordinate inside a styled iframe lands short. clientLeft/\n    // clientTop are the border widths; padding comes from computed style\n    // (read through the frame's own view \u2014 same-origin, so reachable).\n    var borderX = fe.clientLeft || 0;\n    var borderY = fe.clientTop || 0;\n    var padX = 0;\n    var padY = 0;\n    try {\n      var view = (fe.ownerDocument && fe.ownerDocument.defaultView) || window;\n      var style = view.getComputedStyle(fe);\n      padX = parseFloat(style.paddingLeft) || 0;\n      padY = parseFloat(style.paddingTop) || 0;\n    } catch (_) {}\n    return { x: borderX + padX, y: borderY + padY };\n  }\n\n  function clickRectOf(el) {\n    // For a line-wrapped INLINE element (a link spanning two lines), the\n    // center of getBoundingClientRect() can land in the unpainted gap\n    // between the line boxes \u2014 elementFromPoint would report whatever sits\n    // behind, and a dispatched click would miss. The first client rect is\n    // always a painted fragment, so its center is a safe click point.\n    // Block-level elements have exactly one client rect, identical to the\n    // bounding rect \u2014 no behavior change for them.\n    var rects = null;\n    try {\n      rects = el.getClientRects ? el.getClientRects() : null;\n    } catch (_) {\n      rects = null;\n    }\n    if (rects && rects.length > 0) return rects[0];\n    return el.getBoundingClientRect();\n  }\n\n  function viewportCenterOf(el) {\n    // Returns the element's click point in two coordinate spaces:\n    //  - localX/localY: relative to el's OWN document viewport (what\n    //    that document's elementFromPoint expects).\n    //  - x/y: relative to the TOP-LEVEL viewport (what CDP\n    //    Input.dispatchMouseEvent expects) \u2014 localX/localY plus the\n    //    accumulated content-box origin of every ancestor <iframe>\n    //    element (border-box rect + border + padding). Shadow DOM\n    //    boundaries need no offset: they do not introduce a new\n    //    coordinate space.\n    // Both spaces derive from the SAME point (first-client-rect center),\n    // so the occlusion hit-test and the CDP dispatch always agree.\n    var rect = clickRectOf(el);\n    var localX = rect.left + rect.width / 2;\n    var localY = rect.top + rect.height / 2;\n    var chain = frameElementChain(el);\n    var offsetX = 0;\n    var offsetY = 0;\n    for (var i = 0; i < chain.length; i++) {\n      var frameRect = chain[i].getBoundingClientRect();\n      var origin = frameViewportOriginOffset(chain[i]);\n      offsetX += frameRect.left + origin.x;\n      offsetY += frameRect.top + origin.y;\n    }\n    return { x: offsetX + localX, y: offsetY + localY, localX: localX, localY: localY };\n  }\n\n  function composedContains(ancestor, node) {\n    // Node.contains() does not cross shadow boundaries. This walks the\n    // COMPOSED tree: when climbing hits a ShadowRoot (no parentNode), jump\n    // to its host and keep climbing.\n    var cur = node;\n    var guard = 0;\n    while (cur && guard < 1000) {\n      guard++;\n      if (cur === ancestor) return true;\n      if (cur.parentNode) {\n        cur = cur.parentNode;\n        continue;\n      }\n      if (cur.host) {\n        cur = cur.host;\n        continue;\n      }\n      break;\n    }\n    return false;\n  }\n\n  function describeElement(el) {\n    if (!el || !el.tagName) return 'an unknown element';\n    var desc = el.tagName.toLowerCase();\n    if (el.id) desc += '#' + el.id;\n    if (el.classList && el.classList.length) {\n      var classes = [];\n      for (var i = 0; i < el.classList.length && i < 2; i++) classes.push(el.classList[i]);\n      if (classes.length) desc += '.' + classes.join('.');\n    }\n    return desc;\n  }\n\n  function hitTestDeep(root, x, y) {\n    var node = null;\n    try {\n      node = root && root.elementFromPoint ? root.elementFromPoint(x, y) : null;\n    } catch (_) {\n      node = null;\n    }\n    // The hit element may itself host a nested open shadow root whose\n    // content visually covers the point \u2014 descend until elementFromPoint\n    // stops finding a deeper shadow tree.\n    var guard = 0;\n    while (node && node.shadowRoot && guard < 20) {\n      guard++;\n      var inner = null;\n      try {\n        inner = node.shadowRoot.elementFromPoint ? node.shadowRoot.elementFromPoint(x, y) : null;\n      } catch (_) {\n        inner = null;\n      }\n      if (!inner || inner === node) break;\n      node = inner;\n    }\n    return node;\n  }\n\n  function checkOcclusion(target, localX, localY) {\n    // Hit-test starting from the element's OWN root (its closest shadow\n    // root, or the document that owns it when not in shadow DOM) using\n    // LOCAL coordinates \u2014 the same coordinate space that root's own\n    // elementFromPoint expects (an iframe document's viewport starts at\n    // its own top-left, not the top-level page's).\n    var root = target.getRootNode ? target.getRootNode() : document;\n    var hit = hitTestDeep(root, localX, localY);\n    if (!hit) {\n      // Nothing hit-tested at all (e.g. elementFromPoint unsupported in\n      // this environment, or the point is outside the rendered area).\n      // Fail open rather than block a click we cannot actually verify.\n      return { allowed: true };\n    }\n    if (hit === target || composedContains(target, hit) || composedContains(hit, target)) {\n      return { allowed: true };\n    }\n    return { allowed: false, blocker: describeElement(hit) };\n  }\n";