@jobshimo/browser-link 0.14.1 → 0.15.0

package/dist/extension/inpage/builders.js

@@ -0,0 +1,223 @@
+/**
+ * Builders that assemble the CDP `Runtime.evaluate` expression strings for
+ * `snapshot`, `find`, `click` and `type`. Extracted out of background.ts so
+ * the produced JS source can be unit-tested by evaluating it directly in a
+ * DOM environment (see the `*.test.ts` files next to this module) — the
+ * exact same string background.ts sends over CDP.
+ */
+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,
+    });
+    return `
+(() => {
+  ${DEEP_QUERY_JS}
+  ${DOM_HELPERS_JS}
+  const opts = ${optsJson};
+  const needle = opts.text.toLowerCase();
+  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 selectorSet = opts.role && ROLE_SELECTORS[opts.role]
+    ? ROLE_SELECTORS[opts.role]
+    : 'button, a, input, textarea, select, [role], [onclick], [contenteditable="true"], [tabindex]';
+  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) {
+    return { matched: false, reason: 'not-found' };
+  }
+  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};
+  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};
+  const el = deepQueryFirst(opts.selector);
+  if (!el) return false;
+  el.focus();
+  ${opts.clear ? "if ('value' in el) { el.value = ''; el.dispatchEvent(new Event('input', { bubbles: true })); }" : ''}
+  return true;
+})()`;
+}
+//# sourceMappingURL=builders.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"builders.js","sourceRoot":"","sources":["../../src/inpage/builders.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAwBlD,MAAM,UAAU,eAAe,CAAC,OAAqB,EAAE;IACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,cAAc,EAAE,OAAO,IAAI,CAAC,eAAe,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI;QACtF,eAAe,EAAE,IAAI,CAAC,gBAAgB,KAAK,IAAI;QAC/C,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;QACxD,cAAc,EACZ,OAAO,IAAI,CAAC,eAAe,KAAK,QAAQ,IAAI,IAAI,CAAC,eAAe,GAAG,CAAC;YAClE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,eAAe,EAAE,GAAG,CAAC;YACrC,CAAC,CAAC,GAAG;KACV,CAAC,CAAC;IACH,OAAO;;IAEL,aAAa;IACb,cAAc;iBACD,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4FxB,CAAC;AACF,CAAC;AAsBD,MAAM,UAAU,WAAW,CAAC,IAAc;IACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;QAC9E,KAAK,EAAE,IAAI,CAAC,KAAK,KAAK,IAAI;QAC1B,cAAc,EAAE,CAAC;KAClB,CAAC,CAAC;IACH,OAAO;;IAEL,aAAa;IACb,cAAc;iBACD,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuDxB,CAAC;AACF,CAAC;AAiBD,MAAM,UAAU,mBAAmB,CAAC,IAAsB;IACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAChF,OAAO;;IAEL,aAAa;iBACA,QAAQ;;;;;;;;;;;;;;;;;;CAkBxB,CAAC;AACF,CAAC;AAeD,MAAM,UAAU,kBAAkB,CAAC,IAAqB;IACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC7D,OAAO;;IAEL,aAAa;iBACA,QAAQ;;;;IAIrB,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,gGAAgG,CAAC,CAAC,CAAC,EAAE;;KAEjH,CAAC;AACN,CAAC"}

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

@@ -0,0 +1,40 @@
+/**
+ * In-page JS source injected into CDP `Runtime.evaluate` expressions built
+ * by background.ts. 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 the
+ * extension's own service worker. Keep the syntax plain (`var`/`function`,
+ * no optional chaining assumptions) since it must run unmodified in
+ * whatever JS engine the connected tab uses, and keep it dependency-free so
+ * it can be unit-tested by evaluating this exact string in a DOM
+ * environment (see `deep-query.test.ts`).
+ *
+ * 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";

package/dist/extension/inpage/deep-query.js

@@ -0,0 +1,308 @@
+/**
+ * In-page JS source injected into CDP `Runtime.evaluate` expressions built
+ * by background.ts. 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 the
+ * extension's own service worker. Keep the syntax plain (`var`/`function`,
+ * no optional chaining assumptions) since it must run unmodified in
+ * whatever JS engine the connected tab uses, and keep it dependency-free so
+ * it can be unit-tested by evaluating this exact string in a DOM
+ * environment (see `deep-query.test.ts`).
+ *
+ * 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 const DEEP_QUERY_JS = `
+  function collectSearchRoots(start) {
+    // start: a Document, Element or ShadowRoot to scope the search to.
+    // Returns [start, ...every open shadow root and same-origin iframe
+    // document reachable inside start's subtree, recursively]. The caller
+    // runs .querySelectorAll()/.querySelector() on each entry directly —
+    // each entry's own querySelectorAll does NOT pierce into nested shadow
+    // roots or iframes on its own, which is why we enumerate them here.
+    var roots = [start];
+    function walk(scope, depth) {
+      // Depth guard, same pattern as the other recursive helpers here:
+      // pathological nesting (or a cycle introduced by a broken mock)
+      // must degrade to a truncated result, never a stack overflow.
+      if (depth > 20) return;
+      var all;
+      try {
+        all = scope.querySelectorAll('*');
+      } catch (_) {
+        return;
+      }
+      for (var i = 0; i < all.length; i++) {
+        var el = all[i];
+        if (el.shadowRoot) {
+          roots.push(el.shadowRoot);
+          walk(el.shadowRoot, depth + 1);
+        }
+        if (el.tagName === 'IFRAME') {
+          var doc = null;
+          try {
+            doc = el.contentDocument;
+          } catch (_) {
+            doc = null;
+          }
+          if (doc) {
+            roots.push(doc);
+            walk(doc, depth + 1);
+          }
+        }
+      }
+    }
+    walk(start, 0);
+    return roots;
+  }
+
+  function deepWalkAll(callback, start) {
+    // Tree-walk primitive: invoke callback(el) for every element reachable
+    // from start (default: document) across the top document, every open
+    // shadow root, and every same-origin iframe document.
+    var root = start || document;
+    var roots = collectSearchRoots(root);
+    for (var r = 0; r < roots.length; r++) {
+      var all;
+      try {
+        all = roots[r].querySelectorAll('*');
+      } catch (_) {
+        continue;
+      }
+      for (var i = 0; i < all.length; i++) callback(all[i]);
+    }
+  }
+
+  function deepQueryAll(selector, start) {
+    var root = start || document;
+    var roots = collectSearchRoots(root);
+    var out = [];
+    for (var r = 0; r < roots.length; r++) {
+      var found;
+      try {
+        found = roots[r].querySelectorAll(selector);
+      } catch (_) {
+        continue;
+      }
+      for (var i = 0; i < found.length; i++) out.push(found[i]);
+    }
+    return out;
+  }
+
+  function deepQueryFirst(selector, start) {
+    var root = start || document;
+    var roots = collectSearchRoots(root);
+    for (var r = 0; r < roots.length; r++) {
+      var el = null;
+      try {
+        el = roots[r].querySelector(selector);
+      } catch (_) {
+        el = null;
+      }
+      if (el) return el;
+    }
+    return null;
+  }
+
+  function frameElementChain(el) {
+    // Walk up from el's own window to the top window, collecting the
+    // <iframe> element that hosts each intermediate document. Outermost
+    // frame first. Same-origin only — frameElement throws/returns null
+    // across an origin boundary, at which point the chain simply stops
+    // (the coordinate math below degrades gracefully rather than throwing).
+    var chain = [];
+    var doc = el.ownerDocument;
+    var win = doc && doc.defaultView;
+    if (!win) return chain;
+    var topWin;
+    try {
+      topWin = win.top;
+    } catch (_) {
+      topWin = win;
+    }
+    var guard = 0;
+    while (win && win !== topWin && guard < 20) {
+      guard++;
+      var fe = null;
+      try {
+        fe = win.frameElement;
+      } catch (_) {
+        fe = null;
+      }
+      if (!fe) break;
+      chain.unshift(fe);
+      win = fe.ownerDocument && fe.ownerDocument.defaultView;
+    }
+    return chain;
+  }
+
+  function frameViewportOriginOffset(fe) {
+    // The embedded document's viewport origin sits at the frame element's
+    // CONTENT box, but getBoundingClientRect() returns the BORDER box —
+    // border and padding must be added on top of rect.left/rect.top or
+    // every coordinate inside a styled iframe lands short. clientLeft/
+    // clientTop are the border widths; padding comes from computed style
+    // (read through the frame's own view — same-origin, so reachable).
+    var borderX = fe.clientLeft || 0;
+    var borderY = fe.clientTop || 0;
+    var padX = 0;
+    var padY = 0;
+    try {
+      var view = (fe.ownerDocument && fe.ownerDocument.defaultView) || window;
+      var style = view.getComputedStyle(fe);
+      padX = parseFloat(style.paddingLeft) || 0;
+      padY = parseFloat(style.paddingTop) || 0;
+    } catch (_) {}
+    return { x: borderX + padX, y: borderY + padY };
+  }
+
+  function clickRectOf(el) {
+    // For a line-wrapped INLINE element (a link spanning two lines), the
+    // center of getBoundingClientRect() can land in the unpainted gap
+    // between the line boxes — elementFromPoint would report whatever sits
+    // behind, and a dispatched click would miss. The first client rect is
+    // always a painted fragment, so its center is a safe click point.
+    // Block-level elements have exactly one client rect, identical to the
+    // bounding rect — no behavior change for them.
+    var rects = null;
+    try {
+      rects = el.getClientRects ? el.getClientRects() : null;
+    } catch (_) {
+      rects = null;
+    }
+    if (rects && rects.length > 0) return rects[0];
+    return el.getBoundingClientRect();
+  }
+
+  function viewportCenterOf(el) {
+    // Returns the element's click point in two coordinate spaces:
+    //  - localX/localY: relative to el's OWN document viewport (what
+    //    that document's elementFromPoint expects).
+    //  - x/y: relative to the TOP-LEVEL viewport (what CDP
+    //    Input.dispatchMouseEvent expects) — localX/localY plus the
+    //    accumulated content-box origin of every ancestor <iframe>
+    //    element (border-box rect + border + padding). Shadow DOM
+    //    boundaries need no offset: they do not introduce a new
+    //    coordinate space.
+    // Both spaces derive from the SAME point (first-client-rect center),
+    // so the occlusion hit-test and the CDP dispatch always agree.
+    var rect = clickRectOf(el);
+    var localX = rect.left + rect.width / 2;
+    var localY = rect.top + rect.height / 2;
+    var chain = frameElementChain(el);
+    var offsetX = 0;
+    var offsetY = 0;
+    for (var i = 0; i < chain.length; i++) {
+      var frameRect = chain[i].getBoundingClientRect();
+      var origin = frameViewportOriginOffset(chain[i]);
+      offsetX += frameRect.left + origin.x;
+      offsetY += frameRect.top + origin.y;
+    }
+    return { x: offsetX + localX, y: offsetY + localY, localX: localX, localY: localY };
+  }
+
+  function composedContains(ancestor, node) {
+    // Node.contains() does not cross shadow boundaries. This walks the
+    // COMPOSED tree: when climbing hits a ShadowRoot (no parentNode), jump
+    // to its host and keep climbing.
+    var cur = node;
+    var guard = 0;
+    while (cur && guard < 1000) {
+      guard++;
+      if (cur === ancestor) return true;
+      if (cur.parentNode) {
+        cur = cur.parentNode;
+        continue;
+      }
+      if (cur.host) {
+        cur = cur.host;
+        continue;
+      }
+      break;
+    }
+    return false;
+  }
+
+  function describeElement(el) {
+    if (!el || !el.tagName) return 'an unknown element';
+    var desc = el.tagName.toLowerCase();
+    if (el.id) desc += '#' + el.id;
+    if (el.classList && el.classList.length) {
+      var classes = [];
+      for (var i = 0; i < el.classList.length && i < 2; i++) classes.push(el.classList[i]);
+      if (classes.length) desc += '.' + classes.join('.');
+    }
+    return desc;
+  }
+
+  function hitTestDeep(root, x, y) {
+    var node = null;
+    try {
+      node = root && root.elementFromPoint ? root.elementFromPoint(x, y) : null;
+    } catch (_) {
+      node = null;
+    }
+    // The hit element may itself host a nested open shadow root whose
+    // content visually covers the point — descend until elementFromPoint
+    // stops finding a deeper shadow tree.
+    var guard = 0;
+    while (node && node.shadowRoot && guard < 20) {
+      guard++;
+      var inner = null;
+      try {
+        inner = node.shadowRoot.elementFromPoint ? node.shadowRoot.elementFromPoint(x, y) : null;
+      } catch (_) {
+        inner = null;
+      }
+      if (!inner || inner === node) break;
+      node = inner;
+    }
+    return node;
+  }
+
+  function checkOcclusion(target, localX, localY) {
+    // Hit-test starting from the element's OWN root (its closest shadow
+    // root, or the document that owns it when not in shadow DOM) using
+    // LOCAL coordinates — the same coordinate space that root's own
+    // elementFromPoint expects (an iframe document's viewport starts at
+    // its own top-left, not the top-level page's).
+    var root = target.getRootNode ? target.getRootNode() : document;
+    var hit = hitTestDeep(root, localX, localY);
+    if (!hit) {
+      // Nothing hit-tested at all (e.g. elementFromPoint unsupported in
+      // this environment, or the point is outside the rendered area).
+      // Fail open rather than block a click we cannot actually verify.
+      return { allowed: true };
+    }
+    if (hit === target || composedContains(target, hit) || composedContains(hit, target)) {
+      return { allowed: true };
+    }
+    return { allowed: false, blocker: describeElement(hit) };
+  }
+`;
+//# sourceMappingURL=deep-query.js.map

package/dist/extension/inpage/deep-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-query.js","sourceRoot":"","sources":["../../src/inpage/deep-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2Q5B,CAAC"}

package/dist/extension/inpage/dom-helpers.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared in-page DOM helpers, injected verbatim into any JS template that
+ * needs them (`buildSnapshotJs`, `buildFindJs`). Defining them once here
+ * keeps the heuristics (visibility, selector generation, accessible text)
+ * identical across tools so a selector returned by `snapshot` and a selector
+ * returned by `find` follow the same rules.
+ *
+ * `genSelectorInfo` calls `deepQueryAll` to verify a candidate selector is
+ * unique across the FULL deep search scope (top document + every open
+ * shadow root + every same-origin iframe), not just `document`. That is a
+ * runtime dependency, not an import-time one — these are plain string
+ * templates concatenated at the CDP-expression build site, not real ES
+ * modules. Always interpolate `DEEP_QUERY_JS` (from `./deep-query.js`)
+ * BEFORE this constant in any expression that calls `genSelectorInfo`.
+ *
+ * When even a fully-qualified structural path stays ambiguous (two
+ * structurally-identical twins in different roots — no CSS syntax can
+ * scope to one root), `genSelectorInfo` returns `ambiguous: true` and the
+ * snapshot/find builders surface it on the affected entry so agents know
+ * that selector resolves first-match-wins and must not be cached.
+ */
+export declare const DOM_HELPERS_JS = "\n  function isVisible(el) {\n    if (!(el instanceof HTMLElement)) return true;\n    const style = getComputedStyle(el);\n    if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') return false;\n    if (el.offsetParent === null && style.position !== 'fixed') return false;\n    return true;\n  }\n  function shortText(el) {\n    const t = (el.innerText || el.textContent || '').trim();\n    return t.length > 120 ? t.slice(0, 120) + '...' : t;\n  }\n  function safeCss(s) {\n    return s.replace(/\"/g, '\\\\\"');\n  }\n  function genSelectorInfo(el) {\n    // Uniqueness is verified with deepQueryAll \u2014 an id/testid/aria-label/\n    // name that is unique in the top document can still collide with an\n    // identically-attributed element inside a shadow root or same-origin\n    // iframe, since each root has its own independent attribute namespace.\n    if (el.id && !/^[\\d]/.test(el.id) && !/\\s/.test(el.id)) {\n      try {\n        const candidate = '#' + CSS.escape(el.id);\n        if (deepQueryAll(candidate).length === 1) return { selector: candidate, ambiguous: false };\n      } catch (_) {}\n    }\n    const tid = el.getAttribute('data-testid');\n    if (tid) {\n      const candidate = '[data-testid=\"' + safeCss(tid) + '\"]';\n      if (deepQueryAll(candidate).length === 1) return { selector: candidate, ambiguous: false };\n    }\n    const al = el.getAttribute('aria-label');\n    if (al && al.length < 60) {\n      const candidate = el.tagName.toLowerCase() + '[aria-label=\"' + safeCss(al) + '\"]';\n      if (deepQueryAll(candidate).length === 1) return { selector: candidate, ambiguous: false };\n    }\n    const name = el.getAttribute('name');\n    if (name && (el.tagName === 'INPUT' || el.tagName === 'SELECT' || el.tagName === 'TEXTAREA')) {\n      const candidate = el.tagName.toLowerCase() + '[name=\"' + safeCss(name) + '\"]';\n      if (deepQueryAll(candidate).length === 1) return { selector: candidate, ambiguous: false };\n    }\n    // Structural fallback, verified like every shortcut above. The short\n    // form (6 parts, indexed only where siblings force it) is preferred\n    // for stability; when it matches more than one element across roots,\n    // retry with a fully-qualified path (every level :nth-of-type-indexed,\n    // climbed all the way to the root boundary).\n    const structural = buildStructuralSelector(el, 6, false);\n    try {\n      if (deepQueryAll(structural).length === 1) return { selector: structural, ambiguous: false };\n    } catch (_) {}\n    const qualified = buildStructuralSelector(el, 32, true);\n    try {\n      if (deepQueryAll(qualified).length === 1) return { selector: qualified, ambiguous: false };\n    } catch (_) {}\n    // Still ambiguous: structurally-identical twins in different roots.\n    // No CSS syntax can scope a selector to one shadow root / iframe, so\n    // return the most qualified path and flag it \u2014 deepQueryFirst will\n    // resolve it first-match-wins (deterministic traversal order), and\n    // the flag tells agents not to cache it.\n    return { selector: qualified, ambiguous: true };\n  }\n  function genSelector(el) {\n    return genSelectorInfo(el).selector;\n  }\n  function buildStructuralSelector(el, maxParts, alwaysIndex) {\n    // Local-root-scoped structural path: CLIMBING stops at a shadow root or\n    // document boundary (parentElement is null for a shadow root's direct\n    // children) \u2014 matches how deepQueryAll scopes each root's own\n    // querySelectorAll call, so the path resolves back to the same element\n    // when re-queried through deepQueryFirst. Sibling lookup for the\n    // :nth-of-type qualifier uses parentNode rather than parentElement so a\n    // shadow root's own top-level children (parentNode = the ShadowRoot,\n    // which still exposes .children) get disambiguated too, even though we\n    // do not climb past that boundary. With alwaysIndex, every level gets\n    // an explicit :nth-of-type \u2014 maximum qualification for the retry pass.\n    const parts = [];\n    let cur = el;\n    while (cur && cur.nodeType === 1 && cur !== document.body && parts.length < maxParts) {\n      let part = cur.tagName.toLowerCase();\n      const parentNode = cur.parentNode;\n      if (parentNode && parentNode.children) {\n        const sib = Array.from(parentNode.children).filter(s => s.tagName === cur.tagName);\n        if (sib.length > 1 || alwaysIndex) {\n          part += ':nth-of-type(' + (sib.indexOf(cur) + 1) + ')';\n        }\n      }\n      parts.unshift(part);\n      cur = cur.parentElement;\n    }\n    return parts.join(' > ');\n  }\n  function accessibleText(el) {\n    const aria = el.getAttribute && el.getAttribute('aria-label');\n    if (aria) return aria;\n    const txt = (el.innerText || el.textContent || '').trim();\n    if (txt) return txt;\n    if ('value' in el && el.value) return String(el.value);\n    const ph = el.getAttribute && el.getAttribute('placeholder');\n    if (ph) return ph;\n    const title = el.getAttribute && el.getAttribute('title');\n    if (title) return title;\n    return '';\n  }\n  function frameSelectorFor(el) {\n    // Lightweight context field for snapshot/find entries: the selector of\n    // the innermost same-origin <iframe> hosting el, or null when el lives\n    // in the top document. Computed via genSelector so it benefits from the\n    // same deep-uniqueness verification.\n    if (el.ownerDocument === document) return null;\n    const win = el.ownerDocument && el.ownerDocument.defaultView;\n    let fe = null;\n    try {\n      fe = win && win.frameElement;\n    } catch (_) {\n      fe = null;\n    }\n    if (!fe) return null;\n    return genSelector(fe);\n  }\n";