@jobshimo/browser-link 0.34.1 → 0.35.0

package/dist/extension/background.js

@@ -1,4 +1,6 @@
-import { buildSnapshotJs, buildFindJs, buildClickResolveJs, buildTypeResolveJs, buildFocusJs, buildStateJs, buildDragProbeJs, buildElementRectJs, } from './inpage/builders.js';
+import { buildSnapshotJs, buildFindJs, buildClickResolveJs, buildTypeResolveJs, buildFocusJs, buildStateJs, buildDragProbeJs, buildElementRectJs, buildWaitForSelectorJs, } from './inpage/builders.js';
+import { OBSERVER_BINDING, buildObserverChangesJs, buildObserverInstallJs, buildObserverMarkJs, buildObserverTeardownJs, } from './inpage/observer.js';
+import { TOP_DOCUMENT_PROBE_JS, applyObserverMessage, createObserverMirror, isTopDocumentMessage, mergeSettleChanges, parseObserverMessage, readObserverMark, } from './observer-host.js';
 import { runScreenshot } from './screenshot.js';
 import { buildKeyEventSequence, resolveKey, modifiersToBitmask, MODIFIER_BITS, } from './keymap.js';
 import { resolveSettleParams, settleSafely } from './settle.js';
@@ -425,6 +427,171 @@ function sleep(ms) {
 function runSettle(tabId, settle) {
     return settleSafely((expression) => evaluateInTab(tabId, expression), settle);
 }
+const OBSERVER_UNAVAILABLE = { ok: false, reason: 'observer-unavailable' };
+const OBSERVER_DOC_CHANGED = { ok: false, reason: 'doc-changed' };
+/** Ceiling for one observer plumbing evaluation: a page frozen by a native
+ * dialog never answers `Runtime.evaluate`, and `cleanup` must still be
+ * able to detach. */
+const OBSERVER_EVAL_TIMEOUT_MS = 2_000;
+/** Race a CDP call against `OBSERVER_EVAL_TIMEOUT_MS`; rejects on timeout. */
+async function withObserverTimeout(work) {
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            reject(new Error(`observer evaluation timed out after ${OBSERVER_EVAL_TIMEOUT_MS}ms`));
+        }, OBSERVER_EVAL_TIMEOUT_MS);
+    });
+    return Promise.race([work, timeout]).finally(() => {
+        clearTimeout(timer);
+    });
+}
+/**
+ * `Runtime.evaluate` for page-observer plumbing (mark, changes, probes,
+ * teardown). Unlike `evaluateInTab` it passes no `userGesture` — these
+ * reads must never hand the page transient user activation it did not
+ * earn — and it rejects after `OBSERVER_EVAL_TIMEOUT_MS`.
+ */
+async function evaluateObserverJs(tabId, expression) {
+    const result = await withObserverTimeout(cdp(tabId, 'Runtime.evaluate', {
+        expression,
+        returnByValue: true,
+    }));
+    if (result.exceptionDetails) {
+        const ex = result.exceptionDetails;
+        throw new Error(ex.exception?.description ?? ex.text ?? 'Evaluation failed');
+    }
+    return result.result.value;
+}
+/**
+ * Take the page observer's action mark BEFORE an action dispatches (spec v4
+ * §5.4). `null` when settle is off for this call (no changes are reported
+ * then); an `observer-unavailable` marker when the observer was never
+ * installed on this tab or the mark could not be taken.
+ */
+async function takeObserverMark(tabId, settle) {
+    if (!settle)
+        return null;
+    if (tabStates.get(tabId)?.observer?.installed !== true)
+        return OBSERVER_UNAVAILABLE;
+    try {
+        return await evaluateObserverJs(tabId, buildObserverMarkJs());
+    }
+    catch {
+        return OBSERVER_UNAVAILABLE;
+    }
+}
+/**
+ * Run the settle wait, then read what the page observer saw since `mark`
+ * and fold it into the settle result (`mergeSettleChanges`). Never throws:
+ * a changes read that rejects — typically because the action navigated and
+ * destroyed the context — is reported as `doc-changed`.
+ */
+async function settleWithChanges(tabId, settle, mark) {
+    const settleResult = await runSettle(tabId, settle);
+    if (!settleResult)
+        return undefined;
+    const parsed = readObserverMark(mark);
+    let changes = mark ?? OBSERVER_UNAVAILABLE;
+    if (parsed) {
+        try {
+            changes = await evaluateObserverJs(tabId, buildObserverChangesJs(parsed.mark, parsed.doc_id));
+        }
+        catch {
+            changes = OBSERVER_DOC_CHANGED;
+        }
+    }
+    return mergeSettleChanges(settleResult, changes) ?? undefined;
+}
+/**
+ * Handle one page-observer binding message. Summaries only update the
+ * mirror. `doc_start` / `nav` are first checked against the top document
+ * (the install script also runs in same-process child frames, and the
+ * binding is page-visible), then reported to the server as a
+ * `tab-navigated` bridge event so it can keep the tab's URL and title
+ * current.
+ */
+async function handleObserverMessage(state, payload) {
+    const mirror = state.observer;
+    if (!mirror)
+        return;
+    const message = parseObserverMessage(payload);
+    if (!message)
+        return;
+    if (message.type === 'summary') {
+        applyObserverMessage(mirror, message);
+        return;
+    }
+    let probe;
+    try {
+        probe = await evaluateObserverJs(state.tabId, TOP_DOCUMENT_PROBE_JS);
+    }
+    catch {
+        return;
+    }
+    if (!isTopDocumentMessage(probe, message.doc_id))
+        return;
+    const outcome = applyObserverMessage(mirror, message);
+    if (outcome.kind !== 'doc_start' && outcome.kind !== 'nav')
+        return;
+    let title = '';
+    try {
+        title = (await chrome.tabs.get(state.tabId)).title ?? '';
+    }
+    catch {
+        // Best effort — the tab may be closing; the URL is still worth sending.
+    }
+    if (state.ws && state.ws.readyState === WebSocket.OPEN && state.serverTabId) {
+        send(state.ws, {
+            kind: 'bridge.event',
+            eventKind: 'tab-navigated',
+            tabId: state.serverTabId,
+            data: { url: outcome.url, title },
+        });
+    }
+}
+/**
+ * Install the page observer on a freshly attached tab: the push binding,
+ * then the observer as a new-document script that also runs immediately in
+ * the current document. Non-fatal — on failure the tab connects as before
+ * and actions report `settle.changes: null` with `observer-unavailable`.
+ */
+async function installObserver(state) {
+    const mirror = createObserverMirror();
+    state.observer = mirror;
+    try {
+        await cdp(state.tabId, 'Runtime.addBinding', { name: OBSERVER_BINDING });
+        const added = await cdp(state.tabId, 'Page.addScriptToEvaluateOnNewDocument', { source: buildObserverInstallJs(), runImmediately: true });
+        if (typeof added?.identifier === 'string')
+            state.observerScriptId = added.identifier;
+        mirror.installed = true;
+    }
+    catch (err) {
+        console.warn('browser-link: page observer not installed', err instanceof Error ? err.message : String(err));
+    }
+}
+/** Best-effort observer removal before the debugger detaches. */
+async function uninstallObserver(state) {
+    if (!state.observer?.installed)
+        return;
+    state.observer.installed = false;
+    if (state.observerScriptId !== undefined) {
+        try {
+            await withObserverTimeout(cdp(state.tabId, 'Page.removeScriptToEvaluateOnNewDocument', {
+                identifier: state.observerScriptId,
+            }));
+        }
+        catch {
+            // Best effort — the tab may already be gone.
+        }
+        state.observerScriptId = undefined;
+    }
+    try {
+        await evaluateObserverJs(state.tabId, buildObserverTeardownJs());
+    }
+    catch {
+        // Best effort — the tab may already be gone.
+    }
+}
 /**
  * Dispatch the CDP `Input.dispatchKeyEvent` sequence for one resolved key.
  * The event shapes come from `buildKeyEventSequence` (keymap.ts) — pure and
@@ -472,34 +639,6 @@ function waitForCdpEvent(tabId, method, timeoutMs) {
         chrome.debugger.onEvent.addListener(handler);
     });
 }
-/**
- * Build the JS expression that checks a single wait_for condition for a
- * selector. Returns a boolean. Used by `case 'wait_for'` in handleTool.
- *
- *  - visible:  element exists AND non-zero box AND opacity > 0
- *  - hidden:   element doesn't exist OR zero box OR opacity 0 OR display:none
- *  - attached: element exists in DOM (any state)
- *  - detached: element does NOT exist in DOM
- */
-function buildWaitSelectorExpr(selector, condition) {
-    const sel = JSON.stringify(selector);
-    if (condition === 'attached') {
-        return `Boolean(document.querySelector(${sel}))`;
-    }
-    if (condition === 'detached') {
-        return `!document.querySelector(${sel})`;
-    }
-    // visible / hidden share the same probe — only the truthiness flips.
-    const want = condition === 'hidden' ? '!' : '';
-    return `(() => {
-    const el = document.querySelector(${sel});
-    if (!el) return ${condition === 'hidden' ? 'true' : 'false'};
-    const s = getComputedStyle(el);
-    if (s.display === 'none' || s.visibility === 'hidden' || s.opacity === '0') return ${condition === 'hidden' ? 'true' : 'false'};
-    const r = el.getBoundingClientRect();
-    return ${want}(r.width > 0 && r.height > 0);
-  })()`;
-}
 // Convert an arbitrary console arg (`unknown`) into something printable
 // without leaking `[object Object]`. Used by the console buffer when CDP
 // hands us values we don't statically know.
@@ -649,6 +788,11 @@ function attachDebuggerListener(state) {
             }
             return;
         }
+        if (method === 'Runtime.bindingCalled' &&
+            params.name === OBSERVER_BINDING) {
+            void handleObserverMessage(state, params.payload ?? '');
+            return;
+        }
         if (method === 'Runtime.bindingCalled') {
             // Fired for EVERY CDP binding on the tab, not just ours. Two gates
             // before a payload is even parsed: the per-session binding name must
@@ -863,6 +1007,7 @@ async function performClick(tabId, params) {
             }
             return { ok: false, error: `Element not found: ${selector}` };
         }
+        const mark = await takeObserverMark(tabId, settle);
         const baseline = await beginExpect(evaluate, expectSpec);
         await cdp(tabId, 'Input.dispatchMouseEvent', {
             type: 'mouseMoved',
@@ -883,7 +1028,7 @@ async function performClick(tabId, params) {
             button: 'left',
             clickCount: 1,
         });
-        const settleResult = await runSettle(tabId, settle);
+        const settleResult = await settleWithChanges(tabId, settle, mark);
         const verdict = await verifyExpect(evaluate, expectSpec, baseline, settleResult);
         if (!verdict.ok)
             return { ok: false, error: verdict.error };
@@ -918,9 +1063,10 @@ async function performType(tabId, params) {
                 return { ok: false, error: `Element not found: ${selector}` };
             }
         }
+        const mark = await takeObserverMark(tabId, settle);
         const baseline = await beginExpect(evaluate, expectSpec);
         await cdp(tabId, 'Input.insertText', { text });
-        const settleResult = await runSettle(tabId, settle);
+        const settleResult = await settleWithChanges(tabId, settle, mark);
         const verdict = await verifyExpect(evaluate, expectSpec, baseline, settleResult);
         if (!verdict.ok)
             return { ok: false, error: verdict.error };
@@ -959,9 +1105,10 @@ async function performPress(tabId, params) {
                 return { ok: false, error: `Element not found: ${params.selector}` };
             }
         }
+        const mark = await takeObserverMark(tabId, settle);
         const baseline = await beginExpect(evaluate, expectSpec);
         await dispatchKeyEvent(tabId, def, modifiers);
-        const settleResult = await runSettle(tabId, settle);
+        const settleResult = await settleWithChanges(tabId, settle, mark);
         const verdict = await verifyExpect(evaluate, expectSpec, baseline, settleResult);
         if (!verdict.ok)
             return { ok: false, error: verdict.error };
@@ -1010,7 +1157,7 @@ shouldCancel) {
         // null and we return matched=false immediately.
         let check = null;
         if (waitSelector !== undefined) {
-            const expr = buildWaitSelectorExpr(waitSelector, waitCondition);
+            const expr = buildWaitForSelectorJs(waitSelector, waitCondition);
             check = async () => {
                 try {
                     const result = await evaluateInTab(tabId, expr);
@@ -2229,6 +2376,7 @@ async function cleanup(tabId) {
         }
     }
     if (state.debuggerAttached) {
+        await uninstallObserver(state);
         try {
             await chrome.debugger.detach({ tabId });
         }
@@ -2486,6 +2634,7 @@ async function doConnectTab(tabId) {
             error: `Could not enable CDP: ${err instanceof Error ? err.message : String(err)}`,
         };
     }
+    await installObserver(state);
     const ws = new WebSocket(WS_URL);
     state.ws = ws;
     // Capture the fields we'll send over the wire NOW that we've already