@jobshimo/browser-link 0.22.0 → 0.23.0

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

@@ -0,0 +1,325 @@
+/**
+ * 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 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/cdp/inpage/deep-query.js.map

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

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

@@ -0,0 +1,27 @@
+/**
+ * Independent copy of `packages/extension/src/inpage/dom-helpers.ts` — see
+ * `./deep-query.ts`'s header comment for why this is a verbatim duplicate
+ * rather than a cross-package import. The exported `DOM_HELPERS_JS` body is
+ * asserted byte-identical to that sibling by `cdp/drift.test.ts`.
+ *
+ * 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";

package/dist/cdp/inpage/dom-helpers.js

@@ -0,0 +1,147 @@
+/**
+ * Independent copy of `packages/extension/src/inpage/dom-helpers.ts` — see
+ * `./deep-query.ts`'s header comment for why this is a verbatim duplicate
+ * rather than a cross-package import. The exported `DOM_HELPERS_JS` body is
+ * asserted byte-identical to that sibling by `cdp/drift.test.ts`.
+ *
+ * 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 const DOM_HELPERS_JS = `
+  function isVisible(el) {
+    if (!(el instanceof HTMLElement)) return true;
+    const style = getComputedStyle(el);
+    if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') return false;
+    if (el.offsetParent === null && style.position !== 'fixed') return false;
+    return true;
+  }
+  function shortText(el) {
+    const t = (el.innerText || el.textContent || '').trim();
+    return t.length > 120 ? t.slice(0, 120) + '...' : t;
+  }
+  function safeCss(s) {
+    return s.replace(/"/g, '\\\\"');
+  }
+  function genSelectorInfo(el) {
+    // Uniqueness is verified with deepQueryAll — an id/testid/aria-label/
+    // name that is unique in the top document can still collide with an
+    // identically-attributed element inside a shadow root or same-origin
+    // iframe, since each root has its own independent attribute namespace.
+    if (el.id && !/^[\\d]/.test(el.id) && !/\\s/.test(el.id)) {
+      try {
+        const candidate = '#' + CSS.escape(el.id);
+        if (deepQueryAll(candidate).length === 1) return { selector: candidate, ambiguous: false };
+      } catch (_) {}
+    }
+    const tid = el.getAttribute('data-testid');
+    if (tid) {
+      const candidate = '[data-testid="' + safeCss(tid) + '"]';
+      if (deepQueryAll(candidate).length === 1) return { selector: candidate, ambiguous: false };
+    }
+    const al = el.getAttribute('aria-label');
+    if (al && al.length < 60) {
+      const candidate = el.tagName.toLowerCase() + '[aria-label="' + safeCss(al) + '"]';
+      if (deepQueryAll(candidate).length === 1) return { selector: candidate, ambiguous: false };
+    }
+    const name = el.getAttribute('name');
+    if (name && (el.tagName === 'INPUT' || el.tagName === 'SELECT' || el.tagName === 'TEXTAREA')) {
+      const candidate = el.tagName.toLowerCase() + '[name="' + safeCss(name) + '"]';
+      if (deepQueryAll(candidate).length === 1) return { selector: candidate, ambiguous: false };
+    }
+    // Structural fallback, verified like every shortcut above. The short
+    // form (6 parts, indexed only where siblings force it) is preferred
+    // for stability; when it matches more than one element across roots,
+    // retry with a fully-qualified path (every level :nth-of-type-indexed,
+    // climbed all the way to the root boundary).
+    const structural = buildStructuralSelector(el, 6, false);
+    try {
+      if (deepQueryAll(structural).length === 1) return { selector: structural, ambiguous: false };
+    } catch (_) {}
+    const qualified = buildStructuralSelector(el, 32, true);
+    try {
+      if (deepQueryAll(qualified).length === 1) return { selector: qualified, ambiguous: false };
+    } catch (_) {}
+    // Still ambiguous: structurally-identical twins in different roots.
+    // No CSS syntax can scope a selector to one shadow root / iframe, so
+    // return the most qualified path and flag it — deepQueryFirst will
+    // resolve it first-match-wins (deterministic traversal order), and
+    // the flag tells agents not to cache it.
+    return { selector: qualified, ambiguous: true };
+  }
+  function genSelector(el) {
+    return genSelectorInfo(el).selector;
+  }
+  function buildStructuralSelector(el, maxParts, alwaysIndex) {
+    // Local-root-scoped structural path: CLIMBING stops at a shadow root or
+    // document boundary (parentElement is null for a shadow root's direct
+    // children) — matches how deepQueryAll scopes each root's own
+    // querySelectorAll call, so the path resolves back to the same element
+    // when re-queried through deepQueryFirst. Sibling lookup for the
+    // :nth-of-type qualifier uses parentNode rather than parentElement so a
+    // shadow root's own top-level children (parentNode = the ShadowRoot,
+    // which still exposes .children) get disambiguated too, even though we
+    // do not climb past that boundary. With alwaysIndex, every level gets
+    // an explicit :nth-of-type — maximum qualification for the retry pass.
+    const parts = [];
+    let cur = el;
+    while (cur && cur.nodeType === 1 && cur !== document.body && parts.length < maxParts) {
+      let part = cur.tagName.toLowerCase();
+      const parentNode = cur.parentNode;
+      if (parentNode && parentNode.children) {
+        const sib = Array.from(parentNode.children).filter(s => s.tagName === cur.tagName);
+        if (sib.length > 1 || alwaysIndex) {
+          part += ':nth-of-type(' + (sib.indexOf(cur) + 1) + ')';
+        }
+      }
+      parts.unshift(part);
+      cur = cur.parentElement;
+    }
+    return parts.join(' > ');
+  }
+  function accessibleText(el) {
+    const aria = el.getAttribute && el.getAttribute('aria-label');
+    if (aria) return aria;
+    const txt = (el.innerText || el.textContent || '').trim();
+    if (txt) return txt;
+    if ('value' in el && el.value) return String(el.value);
+    const ph = el.getAttribute && el.getAttribute('placeholder');
+    if (ph) return ph;
+    const title = el.getAttribute && el.getAttribute('title');
+    if (title) return title;
+    return '';
+  }
+  function frameSelectorFor(el) {
+    // Lightweight context field for snapshot/find entries: the selector of
+    // the innermost same-origin <iframe> hosting el, or null when el lives
+    // in the top document. Computed via genSelector so it benefits from the
+    // same deep-uniqueness verification.
+    if (el.ownerDocument === document) return null;
+    const win = el.ownerDocument && el.ownerDocument.defaultView;
+    let fe = null;
+    try {
+      fe = win && win.frameElement;
+    } catch (_) {
+      fe = null;
+    }
+    if (!fe) return null;
+    return genSelector(fe);
+  }
+`;
+//# sourceMappingURL=dom-helpers.js.map

package/dist/cdp/inpage/dom-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-helpers.js","sourceRoot":"","sources":["../../../src/cdp/inpage/dom-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuH7B,CAAC"}

package/dist/cdp/keymap.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Independent copy of `packages/extension/src/keymap.ts` — see
+ * `inpage/deep-query.ts`'s header comment for why this package duplicates
+ * rather than imports extension-side modules. Byte-identical logic;
+ * `cdp/drift.test.ts` asserts the `MODIFIER_BITS` mapping stays in lockstep
+ * with the sibling at `packages/extension/src/keymap.ts`.
+ *
+ * Keyboard key definitions for CDP `Input.dispatchKeyEvent`, driving
+ * `browser.press` over the cdp-direct transport (`./transport.ts`).
+ *
+ * Modeled after Puppeteer's `USKeyboardLayout` (US keyboard — the only
+ * layout CDP's `Input.dispatchKeyEvent` needs; Chrome maps
+ * `windowsVirtualKeyCode` + `code` to the OS's actual layout on its own),
+ * trimmed to what `browser.press` exposes: the named control/navigation
+ * keys plus any single printable character.
+ */
+export interface KeyDefinition {
+    /** DOM `KeyboardEvent.key` value. */
+    key: string;
+    /** DOM `KeyboardEvent.code` value — physical key identity. */
+    code: string;
+    /** CDP `windowsVirtualKeyCode` (mirrored into `nativeVirtualKeyCode`).
+     * Chrome derives the platform-native key from this plus `code` — the
+     * same numeric value works on every OS. */
+    keyCode: number;
+    /** Text CDP should insert via a `char` event. Only set for keys that
+     * produce visible input (printable characters, Space). Control keys
+     * (Enter, Escape, Tab, arrows, …) omit it — they dispatch keyDown/keyUp
+     * only, no `char` event, matching real hardware. */
+    text?: string;
+    /** True when producing this exact character requires the Shift modifier
+     * on a US layout (e.g. "@" is Shift+2, "_" is Shift+-). The caller ORs
+     * this into the dispatched modifiers bitmask so `event.shiftKey`
+     * reports correctly even when the caller only asked for the character,
+     * not the physical chord. */
+    needsShift?: boolean;
+}
+/**
+ * Resolve a human-provided `key` name (the `browser.press` `key` param)
+ * into CDP dispatch parameters. Accepts:
+ *  - a named control/navigation key, case-insensitive ("Enter", "arrowup"),
+ *  - a single printable character, case-SENSITIVE ("a" vs "A", "@").
+ *
+ * Returns `null` when the name is neither — the caller surfaces that as a
+ * validation error instead of silently no-op'ing on an unrecognized key.
+ */
+export declare function resolveKey(name: string): KeyDefinition | null;
+/** CDP `Input.dispatchKeyEvent` modifiers bitmask. */
+export declare const MODIFIER_BITS: Readonly<Record<string, number>>;
+/** Fold a `modifiers` array (as accepted by `browser.press`) into the CDP
+ * bitmask. Unknown entries are ignored defensively — the server-side
+ * dispatcher already validates the enum, this is a second line of
+ * defence for direct/test callers. */
+export declare function modifiersToBitmask(modifiers: readonly string[] | undefined): number;
+/** One CDP `Input.dispatchKeyEvent` command payload. A type alias (not an
+ * interface) so it carries an implicit index signature and is directly
+ * assignable to the `Record<string, unknown>` the transport's `cdp()`
+ * helper takes. */
+export type CdpKeyEvent = {
+    type: 'keyDown' | 'rawKeyDown' | 'char' | 'keyUp';
+    modifiers: number;
+    key: string;
+    code: string;
+    windowsVirtualKeyCode: number;
+    nativeVirtualKeyCode: number;
+    text?: string;
+    unmodifiedText?: string;
+};
+/**
+ * Build the CDP `Input.dispatchKeyEvent` sequence for one key press.
+ * Pure function so the exact event shapes are unit-testable.
+ *
+ * Shape: a text-bearing key (printable characters, Space, Enter) gets a
+ * `keyDown` (identity only, no `text` field — Chrome would insert text
+ * from a text-bearing keyDown AND from a following char event, doubling
+ * the input) followed by a separate `char` event carrying the text — the
+ * `char` event is what produces the KEYPRESS whose default action drives
+ * text insertion and, for Enter ('\r'), the WHATWG implicit form
+ * submission. A control key with no text (Escape, Tab, arrows, …) gets
+ * `rawKeyDown` with nothing to follow but `keyUp`, matching real hardware
+ * (those keys never fire keypress in Blink).
+ */
+export declare function buildKeyEventSequence(def: KeyDefinition, modifiers: number): CdpKeyEvent[];