@jobshimo/browser-link 0.36.0 → 0.37.0

package/dist/cdp/inpage/builders.js

@@ -28,7 +28,7 @@ import { OBSERVER_GLOBAL } from './observer.js';
  * injected verbatim into `buildSnapshotJs`, `buildFindJs` and `buildStateJs`.
  * The observer global is looked up ONCE per evaluation and used only when it
  * is present, not torn down, and exposes `refFor`:
- *   - `refOf(el)` returns the observer's `e<N>` ref for `el`, or `null`;
+ *   - `refOf(el)` returns the observer's `<doc_tag>:e<N>` ref for `el`, or `null`;
  *   - `withDocId(result)` adds `doc_id` to `result` and returns it;
  *   - `snapshotStore()` returns the observer when it keeps snapshot records
  *     (`recordSnapshot` / `getSnapshot`, used by `snapshot({ since })`), else
@@ -68,6 +68,53 @@ export const PAGE_OBSERVER_JS = `
     return null;
   }
 `;
+/**
+ * In-page action-target resolution (spec v4 §6.3), injected after
+ * `DEEP_QUERY_JS` and `PAGE_OBSERVER_JS` into the builders that take a
+ * `selector` or a `ref` (click, type, focus, element rect, `wait_for` by
+ * ref, `find` by ref):
+ * `resolveTarget(opts)` with a non-empty `opts.ref` asks the observer
+ * (`resolveRefDetailed`, which re-resolves a replaced node by its semantic
+ * key) and answers `{ ok: true, el, reresolved }`, `{ ok: false, reason:
+ * 'ref-stale', ref, doc_id }` or `{ ok: false, reason: 'observer-unavailable'
+ * }`; otherwise it resolves `opts.selector` exactly as the selector builders
+ * always did (`invalid-selector` checked against `document` first, then
+ * `deepQueryFirst`, `not-found`). Kept out of `PAGE_OBSERVER_JS` so the
+ * snapshot and state sources do not carry code they never call.
+ */
+export const RESOLVE_TARGET_JS = `
+  function resolveTarget(opts) {
+    if (typeof opts.ref === 'string' && opts.ref.length > 0) {
+      if (!pageObserver || typeof pageObserver.resolveRefDetailed !== 'function') {
+        return { ok: false, reason: 'observer-unavailable' };
+      }
+      let found = null;
+      try {
+        found = pageObserver.resolveRefDetailed(opts.ref);
+      } catch (e) {
+        found = null;
+      }
+      if (!found || !found.el) return withDocId({ ok: false, reason: 'ref-stale', ref: opts.ref });
+      return { ok: true, el: found.el, reresolved: found.reresolved === true };
+    }
+    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' };
+    return { ok: true, el: el, reresolved: false };
+  }
+`;
+/** JSON for the `selector` / `ref` pair, embedded as data in the built
+ * source; `ref` is included only when given so a selector build keeps the
+ * same options object as before. */
+function targetJson(opts) {
+    return typeof opts.ref === 'string' && opts.ref.length > 0
+        ? { selector: opts.selector, ref: opts.ref }
+        : { selector: opts.selector };
+}
 export function buildSnapshotJs(opts = {}) {
     const optsJson = JSON.stringify({
         withinSelector: typeof opts.within_selector === 'string' ? opts.within_selector : null,
@@ -260,6 +307,16 @@ export function buildSnapshotJs(opts = {}) {
 })()
 `;
 }
+/** Only the documented key fields reach the built source, as JSON data. */
+function findKeyJson(key) {
+    return Array.isArray(key.path)
+        ? {
+            role: key.role,
+            name: key.name,
+            path: key.path.map((step) => ({ tag: step.tag, index: step.index })),
+        }
+        : { role: key.role, name: key.name };
+}
 export function buildFindJs(opts) {
     const optsJson = JSON.stringify({
         text: opts.text,
@@ -267,13 +324,98 @@ export function buildFindJs(opts) {
         exact: opts.exact === true,
         candidateLimit: 5,
         nearMissLimit: 3,
+        ...(typeof opts.ref === 'string' && opts.ref.length > 0 ? { ref: opts.ref } : {}),
+        ...(opts.key ? { key: findKeyJson(opts.key) } : {}),
     });
     return `
 (() => {
   ${DEEP_QUERY_JS}
   ${DOM_HELPERS_JS}
   ${PAGE_OBSERVER_JS}
+  ${typeof opts.ref === 'string' && opts.ref.length > 0 ? RESOLVE_TARGET_JS : ''}
   const opts = ${optsJson};
+  function semanticKeyOf(el) {
+    if (!pageObserver || typeof pageObserver.semanticKeyFor !== 'function') return null;
+    try {
+      const key = pageObserver.semanticKeyFor(el);
+      return key && typeof key === 'object' ? key : null;
+    } catch (e) {
+      return null;
+    }
+  }
+  function singleMatch(el, ref, reresolved) {
+    const center = viewportCenterOf(el);
+    const selInfo = genSelectorInfo(el);
+    const result = { matched: true, selector: selInfo.selector };
+    if (ref) result.ref = ref;
+    result.coords = {
+      x: Math.round(center.x),
+      y: Math.round(center.y),
+    };
+    result.tag = el.tagName.toLowerCase();
+    result.text = shortText(el);
+    if (selInfo.ambiguous) result.ambiguous = true;
+    const frame = frameSelectorFor(el);
+    if (frame) result.frame = frame;
+    if (reresolved) result.reresolved = true;
+    const key = semanticKeyOf(el);
+    if (key) result.semantic_key = key;
+    return withDocId(result);
+  }
+  if (typeof opts.ref === 'string') {
+    const target = resolveTarget(opts);
+    if (!target.ok) {
+      const failure = { matched: false, reason: target.reason, ref: opts.ref };
+      return withDocId(failure);
+    }
+    return singleMatch(target.el, opts.ref, target.reresolved);
+  }
+  if (opts.key) {
+    if (!pageObserver || typeof pageObserver.semanticKeyFor !== 'function') {
+      return { matched: false, reason: 'observer-unavailable' };
+    }
+    const wanted = opts.key;
+    const candidates = [];
+    for (const el of deepQueryAll('*')) {
+      const key = semanticKeyOf(el);
+      if (key && key.role === wanted.role && key.name === wanted.name) {
+        candidates.push({ el: el, path: Array.isArray(key.path) ? key.path : [] });
+      }
+    }
+    const count = candidates.length;
+    const shared = 'key: ' + count + ' candidates share role and name; ';
+    let picked = null;
+    let error = count > 1 ? shared + 'pass path to disambiguate' : null;
+    if (!Array.isArray(wanted.path)) {
+      if (count === 1) picked = candidates[0].el;
+    } else {
+      // Same rule as the observer's re-resolution: identical tag path and
+      // exactly one such candidate; identical rows are refused, never guessed.
+      let sameTags = 0;
+      let only = null;
+      for (const c of candidates) {
+        if (c.path.length !== wanted.path.length) continue;
+        let same = true;
+        for (let i = 0; i < c.path.length && same; i++) {
+          if (c.path[i].tag !== wanted.path[i].tag) same = false;
+        }
+        if (!same) continue;
+        sameTags++;
+        only = c.el;
+      }
+      if (sameTags === 1) {
+        picked = only;
+      } else if (sameTags > 1) {
+        error = 'key: ' + sameTags + ' candidates share role, name and tag path';
+      } else if (count > 0) {
+        error = shared + 'none has the same tag path';
+      }
+    }
+    if (picked) return singleMatch(picked, refOf(picked), false);
+    const failure = { matched: false, reason: 'not-found' };
+    if (error) failure.error = error;
+    return withDocId(failure);
+  }
   const needle = opts.text.toLowerCase();
   const needleTokens = needle.split(/[^a-z0-9]+/).filter(Boolean);
   const ROLE_SELECTORS = {
@@ -392,37 +534,21 @@ export function buildFindJs(opts) {
     });
   }
   const el = matches[0];
-  const center = viewportCenterOf(el);
-  const selInfo = genSelectorInfo(el);
-  const result = { matched: true, selector: selInfo.selector };
-  const ref = refOf(el);
-  if (ref) result.ref = ref;
-  result.coords = {
-    x: Math.round(center.x),
-    y: Math.round(center.y),
-  };
-  result.tag = el.tagName.toLowerCase();
-  result.text = shortText(el);
-  if (selInfo.ambiguous) result.ambiguous = true;
-  const frame = frameSelectorFor(el);
-  if (frame) result.frame = frame;
-  return withDocId(result);
+  return singleMatch(el, refOf(el), false);
 })()
 `;
 }
 export function buildClickResolveJs(opts) {
-    const optsJson = JSON.stringify({ selector: opts.selector, force: opts.force });
+    const optsJson = JSON.stringify({ ...targetJson(opts), force: opts.force });
     return `
 (() => {
   ${DEEP_QUERY_JS}
+  ${PAGE_OBSERVER_JS}
+  ${RESOLVE_TARGET_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 target = resolveTarget(opts);
+  if (!target.ok) return target;
+  const el = target.el;
   const chain = frameElementChain(el);
   for (const fe of chain) {
     if (fe.scrollIntoView) fe.scrollIntoView({ block: 'center', inline: 'center' });
@@ -437,41 +563,59 @@ export function buildClickResolveJs(opts) {
   const result = { ok: true, x: center.x, y: center.y, tag };
   const hit = occlusion.allowed ? occlusion.hit : occlusion.blocker;
   if (hit) result.hit_element = hit;
+  if (target.reresolved) result.reresolved = true;
   return result;
 })()
 `;
 }
 export function buildTypeResolveJs(opts) {
-    const optsJson = JSON.stringify({ selector: opts.selector });
+    const optsJson = JSON.stringify(targetJson(opts));
     return `
 (() => {
   ${DEEP_QUERY_JS}
+  ${PAGE_OBSERVER_JS}
+  ${RESOLVE_TARGET_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 target = resolveTarget(opts);
+  if (!target.ok) return target;
+  const el = target.el;
   el.focus();
   ${opts.clear ? "if ('value' in el) { el.value = ''; el.dispatchEvent(new Event('input', { bubbles: true })); }" : ''}
-  return { ok: true };
+  return target.reresolved ? { ok: true, reresolved: true } : { ok: true };
 })()`;
 }
 export function buildFocusJs(opts) {
-    const optsJson = JSON.stringify({ selector: opts.selector });
+    const optsJson = JSON.stringify(targetJson(opts));
     return `
 (() => {
   ${DEEP_QUERY_JS}
+  ${PAGE_OBSERVER_JS}
+  ${RESOLVE_TARGET_JS}
   const opts = ${optsJson};
-  const el = deepQueryFirst(opts.selector);
-  if (!el) return false;
-  el.focus();
-  return true;
+  const target = resolveTarget(opts);
+  const byRef = typeof opts.ref === 'string';
+  if (!target.ok) return byRef ? target : false;
+  target.el.focus();
+  if (!byRef) return true;
+  return target.reresolved ? { ok: true, reresolved: true } : { ok: true };
 })()`;
 }
-export function buildWaitForSelectorJs(selector, condition) {
+export function buildWaitForSelectorJs(target, condition) {
+    if (typeof target !== 'string') {
+        const refOptsJson = JSON.stringify({ ref: target.ref, condition });
+        return `
+(() => {
+  ${DEEP_QUERY_JS}
+  ${PAGE_OBSERVER_JS}
+  ${RESOLVE_TARGET_JS}
+  const opts = ${refOptsJson};
+  const target = resolveTarget(opts);
+  if (!target.ok && target.reason === 'observer-unavailable') return target;
+  const el = target.ok ? target.el : null;
+  ${WAIT_FOR_CONDITION_JS}
+})()`;
+    }
+    const selector = target;
     const optsJson = JSON.stringify({ selector, condition });
     return `
 (() => {
@@ -479,7 +623,12 @@ export function buildWaitForSelectorJs(selector, condition) {
   const opts = ${optsJson};
   document.querySelector(opts.selector);
   const el = deepQueryFirst(opts.selector);
-  if (opts.condition === 'attached') return Boolean(el);
+  ${WAIT_FOR_CONDITION_JS}
+})()`;
+}
+/** The condition check shared by both `wait_for` probe targets; `el` is
+ * the resolved element or `null`. */
+const WAIT_FOR_CONDITION_JS = `if (opts.condition === 'attached') return Boolean(el);
   if (opts.condition === 'detached') return !el;
   const wantHidden = opts.condition === 'hidden';
   if (!el) return wantHidden;
@@ -488,22 +637,18 @@ export function buildWaitForSelectorJs(selector, condition) {
   if (s.display === 'none' || s.visibility === 'hidden' || s.opacity === '0') return wantHidden;
   const r = el.getBoundingClientRect();
   const shown = r.width > 0 && r.height > 0;
-  return wantHidden ? !shown : shown;
-})()`;
-}
+  return wantHidden ? !shown : shown;`;
 export function buildElementRectJs(opts) {
-    const optsJson = JSON.stringify({ selector: opts.selector });
+    const optsJson = JSON.stringify(targetJson(opts));
     return `
 (() => {
   ${DEEP_QUERY_JS}
+  ${PAGE_OBSERVER_JS}
+  ${RESOLVE_TARGET_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 target = resolveTarget(opts);
+  if (!target.ok) return target;
+  const el = target.el;
   const chain = frameElementChain(el);
   // behavior 'instant' overrides CSS scroll-behavior: smooth, which would
   // leave the rect below stale while the scroll is still animating.
@@ -528,13 +673,15 @@ export function buildElementRectJs(opts) {
     scrollX = top.scrollX || 0;
     scrollY = top.scrollY || 0;
   } catch (_) {}
-  return {
+  const result = {
     ok: true,
     x: offsetX + rect.left + scrollX,
     y: offsetY + rect.top + scrollY,
     width: rect.width,
     height: rect.height,
   };
+  if (target.reresolved) result.reresolved = true;
+  return result;
 })()`;
 }
 export function buildSettleJs(opts) {

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

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

package/dist/cdp/inpage/observer.d.ts

@@ -11,7 +11,7 @@
  * `cdp/builders-parity.test.ts` checks the built output.
  */
 /** Bump whenever the in-page protocol (global shape, messages, methods) changes. */
-export declare const OBSERVER_VERSION = 2;
+export declare const OBSERVER_VERSION = 3;
 /** Name of the `Runtime.addBinding` function the observer pushes messages through. */
 export declare const OBSERVER_BINDING = "__blPageObserverPush";
 /** Well-known global that holds the installed observer instance. */
@@ -33,10 +33,30 @@ export interface ObserverInstallOpts {
  * `{ ok: true, installed, version, doc_id, coverage }`.
  *
  * The instance also owns element identity (spec v4 §5.6): `refFor(el)` issues
- * `e<N>` (monotonic per document instance, from `e1`) the first time an
- * element is seen and reuses it while the node lives; `resolveRef(ref)`
- * returns the element while it is connected, else `null`. Refs are only valid
- * for the `doc_id` that issued them. Neither method throws. `nextSnapshotId()`
+ * `<doc_tag>:e<N>` (`doc_tag` = the first 6 characters of `doc_id`, N
+ * monotonic per document instance, from 1) the first time an element is seen
+ * and reuses it while the node lives; `resolveRef(ref)` returns the element
+ * while it is connected, else `null`. Refs are only valid for the document
+ * instance that issued them: a ref whose tag is not this instance's tag, or a
+ * bare `e<N>` with no tag, is `null` everywhere (resolve, re-resolve, key)
+ * without consulting the registries. Neither method throws.
+ *
+ * Secondary identity (spec v4 §5.6, decided by lab 10): `semanticKeyFor(el)`
+ * returns `{ role, name, path }` — role from the `role` attribute or a small
+ * implicit table, accessible-ish name (aria-label, aria-labelledby, associated
+ * label, text ≤ 80 chars, placeholder, title, button-like input value) and up
+ * to 8 `{ tag, index }` ancestor steps (1-based same-tag sibling index, a
+ * shadow boundary as `{ tag: '#shadow', index: 0 }`). `refFor` stores the key
+ * when it issues a ref. `resolveRefDetailed(ref)` returns `{ el, reresolved }`:
+ * the live node with `reresolved: false`, else the element with the same role,
+ * name and tag-only path when exactly one exists, rebinding the ref to it
+ * (`reresolved: true`); zero or several candidates give `null` (sibling
+ * indices are kept in the key as data but never pick among candidates). Candidates come from the document, every open shadow root reachable
+ * from it, and every root the `attachShadow` patch observed (closed ones
+ * included); closed roots attached before install are not reachable.
+ * `resolveRef(ref)` is `resolveRefDetailed(ref)?.el ?? null`. `keyForRef(ref)`
+ * returns a copy of the stored key or `null`. None of these throws.
+ * `nextSnapshotId()`
  * issues `<doc_id>:s<N>` (N monotonic per document instance, from 1) for each
  * `snapshot` result and returns `null` once the instance is torn down; the
  * `doc_id` prefix lets a stale id from another document be rejected.
@@ -65,10 +85,19 @@ export declare function buildObserverChangesJs(mark: number, docId?: string): st
 /**
  * Build the ref-resolve expression, for tests and debugging. Evaluates to
  * `{ ok: true, found: true, tag }` when `ref` names an element of the current
- * document that is still connected, `{ ok: true, found: false }` when it is
- * unknown or stale, or `{ ok: false, reason: 'observer-unavailable' }`.
+ * document that is still connected — plus `reresolved: true` when the node was
+ * gone and the ref was just rebound by its semantic key —
+ * `{ ok: true, found: false }` when it is unknown or stale, or
+ * `{ ok: false, reason: 'observer-unavailable' }`.
  */
 export declare function buildObserverRefResolveJs(ref: string): string;
+/**
+ * Build the semantic-key read expression. Evaluates to `{ ok: true, key }`
+ * with the `{ role, name, path }` stored when `ref` was issued, `{ ok: true,
+ * key: null }` for a ref this document instance does not know, or
+ * `{ ok: false, reason: 'observer-unavailable' }`.
+ */
+export declare function buildObserverSemanticKeyJs(ref: string): string;
 /**
  * Build the teardown expression: disconnects every observer, restores the
  * `attachShadow` and `history` patches when they are still the observer's,