@jobshimo/browser-link 0.36.0 → 0.37.0

package/dist/cdp/inpage/observer.js

@@ -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 const OBSERVER_VERSION = 2;
+export const OBSERVER_VERSION = 3;
 /** Name of the `Runtime.addBinding` function the observer pushes messages through. */
 export const OBSERVER_BINDING = '__blPageObserverPush';
 /** Well-known global that holds the installed observer instance. */
@@ -32,10 +32,30 @@ function clampInt(value, fallback, min, max) {
  * `{ 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.
@@ -86,7 +106,14 @@ export function buildObserverInstallJs(opts = {}) {
   const observed = new WeakSet();
   let refs = new WeakMap();
   const refNodes = new Map();
+  // Semantic key captured when each ref is issued; kept while the ref lives so
+  // a replaced node can be found again (spec v4 §5.6 secondary identity).
+  const refKeys = new Map();
   let refSeq = 0;
+  // Every ref carries the issuing document's tag, so a ref from another
+  // document instance (or a bare e<N>) never reaches the registries.
+  const refPrefix = g.doc_id.slice(0, 6) + ':e';
+  const ownsRef = (ref) => typeof ref === 'string' && ref.startsWith(refPrefix);
   let snapshotSeq = 0;
   // Last SNAPSHOT_KEEP snapshot records (opaque to the observer; the snapshot
   // builder owns their shape), keyed by snapshot_id in insertion order.
@@ -214,7 +241,7 @@ export function buildObserverInstallJs(opts = {}) {
     try {
       const mo = new MutationObserver(onRecords(kind));
       mo.observe(root, { subtree: true, childList: true, attributes: true, characterData: true });
-      observers.push({ mo: mo, kind: kind });
+      observers.push({ mo: mo, kind: kind, root: root });
       g.roots++;
     } catch (e) {}
   }
@@ -282,13 +309,179 @@ export function buildObserverInstallJs(opts = {}) {
 
   g.flush = flush;
 
+  const KEY_PATH_STEPS = 8;
+  const KEY_TEXT_CAP = 80;
+  // Elements an HTML <label> can be associated with.
+  const LABELABLE = ['button', 'input', 'meter', 'output', 'progress', 'select', 'textarea'];
+  const BUTTON_INPUT_TYPES = ['button', 'submit', 'reset'];
+
+  function tagOf(el) {
+    return el.localName || String(el.nodeName).toLowerCase();
+  }
+
+  function collapse(text) {
+    return String(text || '').replace(/\\s+/g, ' ').trim();
+  }
+
+  function inputType(el) {
+    return (el.getAttribute('type') || 'text').toLowerCase();
+  }
+
+  function roleOf(el) {
+    const explicit = (el.getAttribute('role') || '').trim();
+    if (explicit) return explicit;
+    const tag = tagOf(el);
+    if (tag === 'a' && el.hasAttribute('href')) return 'link';
+    if (tag === 'button' || tag === 'summary') return 'button';
+    if (tag === 'input') {
+      const type = inputType(el);
+      if (type === 'checkbox' || type === 'radio') return type;
+      if (BUTTON_INPUT_TYPES.indexOf(type) >= 0) return 'button';
+      return 'textbox';
+    }
+    if (tag === 'textarea') return 'textbox';
+    if (tag === 'select') return 'combobox';
+    if (el.hasAttribute('contenteditable') && el.getAttribute('contenteditable') !== 'false') return 'textbox';
+    return tag;
+  }
+
+  function labelTextOf(el, root) {
+    if (LABELABLE.indexOf(tagOf(el)) < 0) return '';
+    const id = el.getAttribute('id');
+    if (id && root && typeof root.querySelectorAll === 'function') {
+      for (const label of root.querySelectorAll('label')) {
+        if (label.getAttribute('for') !== id) continue;
+        const text = collapse(label.textContent);
+        if (text) return text;
+      }
+    }
+    const wrapping = typeof el.closest === 'function' ? el.closest('label') : null;
+    return wrapping ? collapse(wrapping.textContent) : '';
+  }
+
+  function nameOf(el) {
+    const ariaLabel = collapse(el.getAttribute('aria-label'));
+    if (ariaLabel) return ariaLabel;
+    const root = typeof el.getRootNode === 'function' ? el.getRootNode() : document;
+    const labelledBy = collapse(el.getAttribute('aria-labelledby'));
+    if (labelledBy && root && typeof root.getElementById === 'function') {
+      const parts = [];
+      for (const id of labelledBy.split(' ')) {
+        const target = root.getElementById(id);
+        const text = target ? collapse(target.textContent) : '';
+        if (text) parts.push(text);
+      }
+      if (parts.length > 0) return parts.join(' ');
+    }
+    const label = labelTextOf(el, root);
+    if (label) return label;
+    const text = collapse(el.textContent).slice(0, KEY_TEXT_CAP);
+    if (text) return text;
+    const placeholder = collapse(el.getAttribute('placeholder'));
+    if (placeholder) return placeholder;
+    const title = collapse(el.getAttribute('title'));
+    if (title) return title;
+    if (tagOf(el) === 'input' && BUTTON_INPUT_TYPES.indexOf(inputType(el)) >= 0) return collapse(el.value);
+    return '';
+  }
+
+  function sameTagIndex(el) {
+    const tag = el.localName;
+    let index = 1;
+    for (let s = el.previousElementSibling; s; s = s.previousElementSibling) {
+      if (s.localName === tag) index++;
+    }
+    return index;
+  }
+
+  // Unlike pathOf (descriptors, pinned settle output), this path carries the
+  // same-tag sibling index: role + name alone collides (spec v4 §4.6).
+  function keyPathOf(el) {
+    const steps = [];
+    let n = el;
+    while (n && steps.length < KEY_PATH_STEPS) {
+      if (n.nodeType === 1) {
+        if (n === document.documentElement) break;
+        steps.unshift({ tag: tagOf(n), index: sameTagIndex(n) });
+        n = n.parentNode;
+      } else if (n.nodeType === 11 && n.host) {
+        steps.unshift({ tag: '#shadow', index: 0 });
+        n = n.host;
+      } else {
+        break;
+      }
+    }
+    return steps;
+  }
+
+  function semanticKeyFor(el) {
+    try {
+      if (!el || el.nodeType !== 1) return null;
+      return { role: roleOf(el), name: nameOf(el), path: keyPathOf(el) };
+    } catch (e) {
+      return null;
+    }
+  }
+
+  // The document, every open shadow root reachable from it, and every root the
+  // attachShadow patch observed (closed ones included) whose host is connected.
+  function searchRoots() {
+    const roots = [document];
+    const seen = new Set(roots);
+    const add = (root) => {
+      if (!root || seen.has(root)) return;
+      if (root.nodeType === 11 && !(root.host && root.host.isConnected)) return;
+      seen.add(root);
+      roots.push(root);
+    };
+    for (const o of observers) add(o.root);
+    for (let i = 0; i < roots.length; i++) {
+      let all;
+      try { all = roots[i].querySelectorAll('*'); } catch (e) { continue; }
+      for (const el of all) {
+        if (el.shadowRoot) add(el.shadowRoot);
+      }
+    }
+    return roots;
+  }
+
+  // Same role and name and an identical tag-only path, and exactly one such
+  // element: identical rows are refused, never guessed, so a ref never jumps
+  // across rows. Sibling indices stay in the key but select nothing.
+  function findByKey(key) {
+    const last = key.path[key.path.length - 1];
+    if (!last) return null;
+    let found = null;
+    for (const root of searchRoots()) {
+      let all;
+      try { all = root.querySelectorAll('*'); } catch (e) { continue; }
+      for (const el of all) {
+        if (tagOf(el) !== last.tag || roleOf(el) !== key.role || nameOf(el) !== key.name) continue;
+        const path = keyPathOf(el);
+        if (path.length !== key.path.length) continue;
+        let same = true;
+        for (let i = 0; i < path.length && same; i++) {
+          if (path[i].tag !== key.path[i].tag) same = false;
+        }
+        if (!same) continue;
+        if (found) return null;
+        found = el;
+      }
+    }
+    return found;
+  }
+
+  g.semanticKeyFor = semanticKeyFor;
+
   g.refFor = function (el) {
     try {
       if (g.dead || !el || el.nodeType !== 1) return null;
       let ref = refs.get(el);
       if (!ref) {
-        ref = 'e' + ++refSeq;
+        ref = refPrefix + ++refSeq;
         refs.set(el, ref);
+        const key = semanticKeyFor(el);
+        if (key) refKeys.set(ref, key);
       }
       // Same node, same ref: re-register one pruned while it was detached.
       if (!refNodes.has(ref)) refNodes.set(ref, holdWeakly(el));
@@ -298,20 +491,40 @@ export function buildObserverInstallJs(opts = {}) {
     }
   };
 
-  g.resolveRef = function (ref) {
+  g.resolveRefDetailed = function (ref) {
     try {
-      if (typeof ref !== 'string') return null;
+      if (g.dead || !ownsRef(ref)) return null;
       const held = refNodes.get(ref);
-      if (!held) return null;
-      const el = held.deref();
-      if (el && el.isConnected) return el;
+      const old = held ? held.deref() : null;
+      if (old && old.isConnected) return { el: old, reresolved: false };
       refNodes.delete(ref);
-      return null;
+      const key = refKeys.get(ref);
+      if (!key) return null;
+      const el = findByKey(key);
+      if (!el) return null;
+      if (old && refs.get(old) === ref) refs.delete(old);
+      // A node that already has its own ref keeps it for refFor; this ref
+      // still resolves to it through refNodes.
+      if (!refs.has(el)) refs.set(el, ref);
+      refNodes.set(ref, holdWeakly(el));
+      return { el: el, reresolved: true };
     } catch (e) {
       return null;
     }
   };
 
+  g.resolveRef = function (ref) {
+    const result = g.resolveRefDetailed(ref);
+    return result ? result.el : null;
+  };
+
+  g.keyForRef = function (ref) {
+    if (g.dead || !ownsRef(ref)) return null;
+    const key = refKeys.get(ref);
+    if (!key) return null;
+    return { role: key.role, name: key.name, path: key.path.map((s) => ({ tag: s.tag, index: s.index })) };
+  };
+
   g.nextSnapshotId = function () {
     if (g.dead) return null;
     return g.doc_id + ':s' + ++snapshotSeq;
@@ -411,6 +624,7 @@ export function buildObserverInstallJs(opts = {}) {
     g.baselines.clear();
     refs = new WeakMap();
     refNodes.clear();
+    refKeys.clear();
     snapshotSeq = 0;
     snapshots.clear();
     if (window[opts.key] === g) {
@@ -479,12 +693,24 @@ function jsStringLiteral(value) {
 /**
  * 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 function buildObserverRefResolveJs(ref) {
     const refJson = jsStringLiteral(typeof ref === 'string' ? ref : '');
-    return callInstance(`((el) => el ? { ok: true, found: true, tag: el.localName || String(el.nodeName).toLowerCase() } : { ok: true, found: false })(g.resolveRef(${refJson}))`);
+    return callInstance(`((r) => { if (!r) return { ok: true, found: false }; const tag = r.el.localName || String(r.el.nodeName).toLowerCase(); return r.reresolved ? { ok: true, found: true, tag: tag, reresolved: true } : { ok: true, found: true, tag: tag }; })(g.resolveRefDetailed(${refJson}))`);
+}
+/**
+ * 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 function buildObserverSemanticKeyJs(ref) {
+    const refJson = jsStringLiteral(typeof ref === 'string' ? ref : '');
+    return callInstance(`({ ok: true, key: g.keyForRef(${refJson}) })`);
 }
 /**
  * Build the teardown expression: disconnects every observer, restores the

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

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

package/dist/cdp/transport.js

@@ -30,7 +30,7 @@ import { resolveSettleParams, settleSafely } from './settle.js';
 import { beginExpect, resolveExpectParams, verifyExpect } from './expect.js';
 import { buildKeyEventSequence, modifiersToBitmask, resolveKey } from './keymap.js';
 import { cancelDetachedFlow, detachedFlowForTab, detachedFlowStatus, finishDetachedFlow, registerDetachedFlow, reportDetachedProgress, shouldStopDetachedFlow, } from './detached-flows.js';
-import { runFlow, } from './flow.js';
+import { refFailureMessage, runFlow, } from './flow.js';
 // The declarative v1 support table lives in `./support.ts` (zero
 // dependencies, importable by `tools/browser-dispatch.ts` without pulling
 // in this whole transport) — re-exported here so existing callers of
@@ -375,6 +375,18 @@ async function dispatchKeyEventSequence(client, def, modifiers) {
 }
 async function performFind(client, params) {
     try {
+        if (params.key !== undefined) {
+            const value = await evaluateInTab(client, buildFindJs({ key: params.key }));
+            return { ok: true, result: value };
+        }
+        if (params.ref !== undefined) {
+            const ref = params.ref;
+            const found = await evaluateInTab(client, buildFindJs({ ref }));
+            const refError = found.matched ? null : refFailureMessage(found, ref);
+            if (refError)
+                return { ok: false, error: refError };
+            return { ok: true, result: found };
+        }
         if (!params.text)
             return { ok: false, error: 'find: text required' };
         const opts = { text: params.text, role: params.role, exact: params.exact === true };
@@ -387,16 +399,19 @@ async function performFind(client, params) {
 }
 async function performClick(client, params) {
     try {
-        const { selector, force = false } = params;
+        const { selector, ref, force = false } = params;
         const settle = resolveSettleParams({
             settle_ms: params.settle_ms,
             settle_timeout_ms: params.settle_timeout_ms,
         });
         const expectSpec = resolveExpectParams(params.expect);
         const evaluate = (expression) => evaluateInTab(client, expression);
-        const resolveOpts = { selector, force };
+        const resolveOpts = ref !== undefined ? { ref, force } : { selector, force };
         const resolved = await evaluateInTab(client, buildClickResolveJs(resolveOpts));
         if (!resolved.ok) {
+            const refError = ref !== undefined ? refFailureMessage(resolved, ref) : null;
+            if (refError)
+                return { ok: false, error: refError };
             if (resolved.reason === 'occluded') {
                 return {
                     ok: false,
@@ -406,7 +421,7 @@ async function performClick(client, params) {
             if (resolved.reason === 'invalid-selector') {
                 return { ok: false, error: `Invalid selector "${selector}": ${resolved.error}` };
             }
-            return { ok: false, error: `Element not found: ${selector}` };
+            return { ok: false, error: `Element not found: ${ref ?? selector}` };
         }
         const mark = await takeObserverMark(client, settle);
         const baseline = await beginExpect(evaluate, expectSpec);
@@ -433,7 +448,11 @@ async function performClick(client, params) {
         const verdict = await verifyExpect(evaluate, expectSpec, baseline, settleResult);
         if (!verdict.ok)
             return { ok: false, error: verdict.error };
-        const result = { clicked: selector, tag: resolved.tag };
+        const result = { clicked: ref ?? selector ?? '', tag: resolved.tag };
+        if (ref !== undefined)
+            result.ref = ref;
+        if (resolved.reresolved === true)
+            result.reresolved = true;
         if (resolved.hit_element)
             result.hit_element = resolved.hit_element;
         if (settleResult)
@@ -448,14 +467,26 @@ async function performClick(client, params) {
 }
 async function performType(client, params) {
     try {
-        const { selector, text, clear = false } = params;
+        const { selector, ref, text, clear = false } = params;
         const settle = resolveSettleParams({
             settle_ms: params.settle_ms,
             settle_timeout_ms: params.settle_timeout_ms,
         });
         const expectSpec = resolveExpectParams(params.expect);
         const evaluate = (expression) => evaluateInTab(client, expression);
-        if (selector !== undefined) {
+        let reresolved = false;
+        if (ref !== undefined) {
+            const opts = { ref, clear };
+            const resolved = await evaluateInTab(client, buildTypeResolveJs(opts));
+            if (!resolved.ok) {
+                return {
+                    ok: false,
+                    error: refFailureMessage(resolved, ref) ?? `Element not found: ${ref}`,
+                };
+            }
+            reresolved = resolved.reresolved === true;
+        }
+        else if (selector !== undefined) {
             const opts = { selector, clear };
             const resolved = await evaluateInTab(client, buildTypeResolveJs(opts));
             if (!resolved.ok) {
@@ -475,6 +506,10 @@ async function performType(client, params) {
         const result = { typed: text.length };
         if (selector !== undefined)
             result.selector = selector;
+        if (ref !== undefined)
+            result.ref = ref;
+        if (reresolved)
+            result.reresolved = true;
         if (settleResult)
             result.settle = settleResult;
         if (verdict.expect)
@@ -501,7 +536,16 @@ async function performPress(client, params) {
         });
         const expectSpec = resolveExpectParams(params.expect);
         const evaluate = (expression) => evaluateInTab(client, expression);
-        if (params.selector) {
+        const ref = params.ref;
+        let reresolved = false;
+        if (ref !== undefined) {
+            const focused = await evaluateInTab(client, buildFocusJs({ ref }));
+            if (!focused.ok) {
+                return { ok: false, error: refFailureMessage(focused, ref) ?? `Element not found: ${ref}` };
+            }
+            reresolved = focused.reresolved === true;
+        }
+        else if (params.selector) {
             const focused = await evaluateInTab(client, buildFocusJs({ selector: params.selector }));
             if (!focused) {
                 return { ok: false, error: `Element not found: ${params.selector}` };
@@ -515,6 +559,10 @@ async function performPress(client, params) {
         if (!verdict.ok)
             return { ok: false, error: verdict.error };
         const result = { key, modifiers: modifierNames };
+        if (ref !== undefined)
+            result.ref = ref;
+        if (reresolved)
+            result.reresolved = true;
         if (settleResult)
             result.settle = settleResult;
         if (verdict.expect)
@@ -570,6 +618,10 @@ shouldCancel) {
                 ? MAX_POLL_MS
                 : requestedPoll;
         let check = null;
+        // Set when a ref probe reports that the page has no observer: the ref
+        // can never resolve, so the wait fails instead of timing out (or, for
+        // `detached` / `hidden`, matching a ref it never looked up).
+        const refProbe = { unavailable: false };
         if (waitSelector !== undefined) {
             const expr = buildWaitForSelectorJs(waitSelector, waitCondition);
             check = async () => {
@@ -582,6 +634,22 @@ shouldCancel) {
                 }
             };
         }
+        else if (params.ref !== undefined) {
+            const expr = buildWaitForSelectorJs({ ref: params.ref }, waitCondition);
+            check = async () => {
+                try {
+                    const value = await evaluateInTab(client, expr);
+                    if (typeof value === 'object' && value !== null) {
+                        refProbe.unavailable = true;
+                        return true;
+                    }
+                    return value === true;
+                }
+                catch {
+                    return false;
+                }
+            };
+        }
         else if (waitExpression !== undefined) {
             const wrapped = `Boolean(${waitExpression})`;
             check = async () => {
@@ -613,6 +681,12 @@ shouldCancel) {
             await sleep(pollIntervalMs);
         }
         const elapsedMs = Date.now() - startedAt;
+        if (refProbe.unavailable && params.ref !== undefined) {
+            return {
+                ok: false,
+                error: refFailureMessage({ reason: 'observer-unavailable' }, params.ref) ?? '',
+            };
+        }
         // 'cancelled' is deliberately distinct from 'timeout': the step
         // executor turns a timeout into a flow FAILURE (with a recovery
         // snapshot) and a cancellation into a clean `stopped_by: 'cancelled'`.
@@ -739,14 +813,18 @@ export async function callCdpTool(tabId, tool, params, timeoutMs) {
                 text: typeof p.text === 'string' ? p.text : '',
                 role: typeof p.role === 'string' ? p.role : undefined,
                 exact: p.exact === true,
+                ref: typeof p.ref === 'string' ? p.ref : undefined,
+                key: typeof p.key === 'object' && p.key !== null ? p.key : undefined,
             });
             if (!outcome.ok)
                 throw new Error(outcome.error);
             return outcome.result;
         }
         case 'click': {
+            const ref = typeof p.ref === 'string' ? p.ref : undefined;
             const outcome = await performClick(client, {
-                selector: typeof p.selector === 'string' ? p.selector : '',
+                selector: typeof p.selector === 'string' ? p.selector : ref !== undefined ? undefined : '',
+                ref,
                 force: p.force === true,
                 settle_ms: typeof p.settle_ms === 'number' ? p.settle_ms : undefined,
                 settle_timeout_ms: typeof p.settle_timeout_ms === 'number' ? p.settle_timeout_ms : undefined,
@@ -759,6 +837,7 @@ export async function callCdpTool(tabId, tool, params, timeoutMs) {
         case 'type': {
             const outcome = await performType(client, {
                 selector: typeof p.selector === 'string' ? p.selector : undefined,
+                ref: typeof p.ref === 'string' ? p.ref : undefined,
                 text: typeof p.text === 'string' ? p.text : '',
                 clear: p.clear === true,
                 settle_ms: typeof p.settle_ms === 'number' ? p.settle_ms : undefined,
@@ -777,6 +856,7 @@ export async function callCdpTool(tabId, tool, params, timeoutMs) {
                 key: typeof p.key === 'string' ? p.key : undefined,
                 modifiers: modifierNames,
                 selector: typeof p.selector === 'string' ? p.selector : undefined,
+                ref: typeof p.ref === 'string' ? p.ref : undefined,
                 settle_ms: typeof p.settle_ms === 'number' ? p.settle_ms : undefined,
                 settle_timeout_ms: typeof p.settle_timeout_ms === 'number' ? p.settle_timeout_ms : undefined,
                 expect: p.expect,
@@ -792,6 +872,7 @@ export async function callCdpTool(tabId, tool, params, timeoutMs) {
         case 'wait_for': {
             const outcome = await performWaitFor(client, {
                 selector: typeof p.selector === 'string' ? p.selector : undefined,
+                ref: typeof p.ref === 'string' ? p.ref : undefined,
                 expression: typeof p.expression === 'string' ? p.expression : undefined,
                 network_url: typeof p.network_url === 'string' ? p.network_url : undefined,
                 condition: typeof p.condition === 'string' ? p.condition : undefined,