@jobshimo/browser-link 0.34.1 → 0.36.0

package/dist/extension/inpage/builders.js

@@ -8,6 +8,52 @@
  */
 import { DEEP_QUERY_JS } from './deep-query.js';
 import { DOM_HELPERS_JS } from './dom-helpers.js';
+import { OBSERVER_GLOBAL } from './observer.js';
+/**
+ * In-page access to the page observer's element identity (spec v4 §5.6),
+ * 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`;
+ *   - `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
+ *     `null`.
+ * Without the observer (injection failed, pre-observer document) all are
+ * no-ops, so every result is byte-identical to the pre-ref output.
+ */
+export const PAGE_OBSERVER_JS = `
+  const pageObserver = (() => {
+    try {
+      const g = window[${JSON.stringify(OBSERVER_GLOBAL)}];
+      if (g && !g.dead && typeof g.refFor === 'function') return g;
+    } catch (e) {}
+    return null;
+  })();
+  function refOf(el) {
+    if (!pageObserver) return null;
+    try {
+      const ref = pageObserver.refFor(el);
+      return typeof ref === 'string' ? ref : null;
+    } catch (e) {
+      return null;
+    }
+  }
+  function withDocId(result) {
+    if (pageObserver && typeof pageObserver.doc_id === 'string') result.doc_id = pageObserver.doc_id;
+    return result;
+  }
+  function snapshotStore() {
+    if (
+      pageObserver &&
+      typeof pageObserver.recordSnapshot === 'function' &&
+      typeof pageObserver.getSnapshot === 'function'
+    ) {
+      return pageObserver;
+    }
+    return null;
+  }
+`;
 export function buildSnapshotJs(opts = {}) {
     const optsJson = JSON.stringify({
         withinSelector: typeof opts.within_selector === 'string' ? opts.within_selector : null,
@@ -16,23 +62,25 @@ export function buildSnapshotJs(opts = {}) {
         maxInteractive: typeof opts.max_interactive === 'number' && opts.max_interactive > 0
             ? Math.min(opts.max_interactive, 500)
             : 120,
+        since: typeof opts.since === 'string' ? opts.since : null,
     });
     return `
 (() => {
   ${DEEP_QUERY_JS}
   ${DOM_HELPERS_JS}
+  ${PAGE_OBSERVER_JS}
   const opts = ${optsJson};
   let root = document;
   let notice = '';
   if (opts.withinSelector) {
     const sub = deepQueryFirst(opts.withinSelector);
     if (!sub) {
-      return {
+      return withDocId({
         title: document.title,
         url: location.href,
         interactive: [],
         notice: 'within_selector did not match any element',
-      };
+      });
     }
     root = sub;
   }
@@ -75,6 +123,8 @@ export function buildSnapshotJs(opts = {}) {
     const role = el.getAttribute('role') || tag;
     const selInfo = genSelectorInfo(el);
     const entry = { tag, role, selector: selInfo.selector };
+    const ref = refOf(el);
+    if (ref) entry.ref = ref;
     if (selInfo.ambiguous) entry.ambiguous = true;
     const txt = shortText(el);
     if (txt) entry.text = txt;
@@ -94,26 +144,105 @@ export function buildSnapshotJs(opts = {}) {
     if (frame) entry.frame = frame;
     interactive.push(entry);
   });
-  const result = {
-    title: document.title,
-    url: location.href,
-    interactive: interactive.slice(0, opts.maxInteractive),
-  };
+  let headings = null;
+  let visibleText = '';
   if (!opts.onlyInteractive) {
-    const headings = [];
+    const found = [];
     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 });
+      if (t) found.push({ level: h.tagName, text: t });
     });
-    result.headings = headings.slice(0, 30);
+    headings = found.slice(0, 30);
     const textRoot = (root === document) ? (document.body || document) : root;
-    const visibleText = (textRoot && textRoot.innerText) ? textRoot.innerText.slice(0, 4000) : '';
+    visibleText = (textRoot && textRoot.innerText) ? textRoot.innerText.slice(0, 4000) : '';
+  }
+  let snapshotId = null;
+  if (withDocId({}).doc_id && typeof pageObserver.nextSnapshotId === 'function') {
+    const issued = pageObserver.nextSnapshotId();
+    if (typeof issued === 'string') snapshotId = issued;
+  }
+  function fullResult() {
+    const result = {
+      title: document.title,
+      url: location.href,
+      interactive: interactive.slice(0, opts.maxInteractive),
+    };
+    if (headings) result.headings = headings;
     if (visibleText) result.text = visibleText;
+    if (notice) result.notice = notice;
+    withDocId(result);
+    if (snapshotId) result.snapshot_id = snapshotId;
+    return result;
   }
-  if (notice) result.notice = notice;
-  return result;
+  // Record every snapshot (with or without since) so a later call can diff
+  // against it. Entries are keyed by ref; the hash is the entry serialised
+  // without its ref, in emission order. Capped at the first 500 entries.
+  const store = snapshotId ? snapshotStore() : null;
+  // A snapshot_id is \`<doc_id>:s<N>\`: a since whose prefix (before the LAST
+  // ':') is not this document's doc_id, or that has no ':', came from another
+  // document and is never looked up.
+  const sinceCut = opts.since === null ? -1 : opts.since.lastIndexOf(':');
+  const sinceSameDoc =
+    sinceCut >= 0 && withDocId({}).doc_id === opts.since.slice(0, sinceCut);
+  const previous = store && sinceSameDoc ? store.getSnapshot(opts.since) : null;
+  const current = new Map();
+  const headingsHash = headings ? JSON.stringify(headings) : null;
+  const textHash = opts.onlyInteractive ? null : visibleText;
+  if (store) {
+    for (const entry of interactive) {
+      if (current.size >= 500) break;
+      if (typeof entry.ref !== 'string') continue;
+      const copy = {};
+      for (const key of Object.keys(entry)) if (key !== 'ref') copy[key] = entry[key];
+      current.set(entry.ref, { hash: JSON.stringify(copy), entry });
+    }
+    store.recordSnapshot(snapshotId, { entries: current, headings_hash: headingsHash, text_hash: textHash });
+  }
+  if (opts.since === null) return fullResult();
+  if (!store) {
+    const result = fullResult();
+    result.since = opts.since;
+    result.since_status = 'observer-unavailable';
+    return result;
+  }
+  if (!previous || !previous.entries || typeof previous.entries.get !== 'function') {
+    const result = fullResult();
+    result.since = opts.since;
+    result.since_status = sinceSameDoc ? 'evicted' : 'doc-changed';
+    return result;
+  }
+  const added = [];
+  const changed = [];
+  const removed = [];
+  current.forEach((item, ref) => {
+    const old = previous.entries.get(ref);
+    if (!old) added.push(item.entry);
+    else if (old.hash !== item.hash) changed.push(item.entry);
+  });
+  previous.entries.forEach((item, ref) => {
+    if (current.has(ref) || removed.length >= 500) return;
+    const gone = { ref, tag: item.entry.tag };
+    if (item.entry.text) gone.text = item.entry.text;
+    removed.push(gone);
+  });
+  // max_interactive applies after diffing (added first, then changed), so
+  // a window shift never masquerades as change.
+  const listed = added.concat(changed);
+  const kept = listed.slice(0, opts.maxInteractive);
+  const diff = withDocId({ title: document.title, url: location.href });
+  diff.snapshot_id = snapshotId;
+  diff.since = opts.since;
+  diff.added = kept.slice(0, Math.min(added.length, kept.length));
+  diff.removed = removed;
+  diff.changed = kept.slice(diff.added.length);
+  if (listed.length > kept.length) diff.overflow = listed.length - kept.length;
+  if (!opts.onlyInteractive) {
+    if (headingsHash !== previous.headings_hash) diff.headings = headings;
+    if (textHash !== previous.text_hash) diff.text = visibleText;
+  }
+  return diff;
 })()
 `;
 }
@@ -129,6 +258,7 @@ export function buildFindJs(opts) {
 (() => {
   ${DEEP_QUERY_JS}
   ${DOM_HELPERS_JS}
+  ${PAGE_OBSERVER_JS}
   const opts = ${optsJson};
   const needle = opts.text.toLowerCase();
   const needleTokens = needle.split(/[^a-z0-9]+/).filter(Boolean);
@@ -189,6 +319,8 @@ export function buildFindJs(opts) {
     }
     function toNearMiss(el) {
       const entry = { text: snippetOf(el), selector: genSelector(el) };
+      const ref = refOf(el);
+      if (ref) entry.ref = ref;
       const roleAttr = el.getAttribute('role');
       if (roleAttr) entry.role = roleAttr;
       return entry;
@@ -221,44 +353,46 @@ export function buildFindJs(opts) {
           ' but none with role "' + opts.role + '"' +
           (closest ? ' — closest: ' + describeForError(closest) + ' "' + snippetOf(closest) + '"' : '');
         result.near_misses = ranked.map(toNearMiss);
-        return result;
+        return withDocId(result);
       }
       const ranked = rankCandidates(broadAll);
       if (ranked.length > 0) result.near_misses = ranked.map(toNearMiss);
-      return result;
+      return withDocId(result);
     }
     const ranked = rankCandidates(all);
     if (ranked.length > 0) result.near_misses = ranked.map(toNearMiss);
-    return result;
+    return withDocId(result);
   }
   if (matches.length > 1) {
-    return {
+    return withDocId({
       matched: false,
       reason: 'multiple-matches',
-      candidates: matches.slice(0, opts.candidateLimit).map((el) => ({
-        selector: genSelector(el),
-        text: shortText(el),
-        tag: el.tagName.toLowerCase(),
-      })),
-    };
+      candidates: matches.slice(0, opts.candidateLimit).map((el) => {
+        const candidate = { selector: genSelector(el) };
+        const ref = refOf(el);
+        if (ref) candidate.ref = ref;
+        candidate.text = shortText(el);
+        candidate.tag = el.tagName.toLowerCase();
+        return candidate;
+      }),
+    });
   }
   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),
+  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 result;
+  return withDocId(result);
 })()
 `;
 }
@@ -323,6 +457,26 @@ export function buildFocusJs(opts) {
   return true;
 })()`;
 }
+export function buildWaitForSelectorJs(selector, condition) {
+    const optsJson = JSON.stringify({ selector, condition });
+    return `
+(() => {
+  ${DEEP_QUERY_JS}
+  const opts = ${optsJson};
+  document.querySelector(opts.selector);
+  const el = deepQueryFirst(opts.selector);
+  if (opts.condition === 'attached') return Boolean(el);
+  if (opts.condition === 'detached') return !el;
+  const wantHidden = opts.condition === 'hidden';
+  if (!el) return wantHidden;
+  const view = (el.ownerDocument && el.ownerDocument.defaultView) || window;
+  const s = view.getComputedStyle(el);
+  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;
+})()`;
+}
 export function buildElementRectJs(opts) {
     const optsJson = JSON.stringify({ selector: opts.selector });
     return `
@@ -603,12 +757,16 @@ export function buildExpectProbeJs(opts) {
  * `focused` beyond `<body>`, no `dialogs` when none are open, and no
  * `scroll` when the page is at its default (0,0) position — token-lean by
  * construction, matching the omit-falsy convention the other builders use.
+ *
+ * With the page observer installed (see `PAGE_OBSERVER_JS`), `focused`
+ * carries `ref` right after `selector` and the result carries `doc_id`.
  */
 export function buildStateJs() {
     return `
 (() => {
   ${DEEP_QUERY_JS}
   ${DOM_HELPERS_JS}
+  ${PAGE_OBSERVER_JS}
   function deepActiveElement() {
     let el = document.activeElement;
     let guard = 0;
@@ -669,7 +827,10 @@ export function buildStateJs() {
   const active = deepActiveElement();
   if (active && active !== document.body && active.tagName) {
     const selInfo = genSelectorInfo(active);
-    const focused = { selector: selInfo.selector, tag: active.tagName.toLowerCase() };
+    const focused = { selector: selInfo.selector };
+    const ref = refOf(active);
+    if (ref) focused.ref = ref;
+    focused.tag = active.tagName.toLowerCase();
     if (selInfo.ambiguous) focused.ambiguous = true;
     result.focused = focused;
   }
@@ -689,7 +850,7 @@ export function buildStateJs() {
   const scrollY = Math.round(window.scrollY);
   if (scrollX !== 0 || scrollY !== 0) result.scroll = { x: scrollX, y: scrollY };
 
-  return result;
+  return withDocId(result);
 })()
 `;
 }

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

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

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

@@ -0,0 +1,88 @@
+/**
+ * The page observer: a persistent, coalescing MutationObserver that runs in
+ * the page's MAIN world (spec v4 §5.1–§5.3). The host installs it once per
+ * tab with `Runtime.addBinding` + `Page.addScriptToEvaluateOnNewDocument`
+ * (`runImmediately: true`), so Chrome re-runs it in every new document and
+ * in every same-process frame before page scripts. It pushes one summary
+ * per flush through the binding and keeps a bounded ring of summaries so an
+ * action window (mark → changes) can be read back exactly.
+ *
+ * Lab findings this source honours (`packages/plan/lab/2026-11-06-live-page-model/`):
+ *   - flushes are scheduled with `setTimeout`, never `requestAnimationFrame`
+ *     (rAF never fires in a hidden tab);
+ *   - the instance is versioned: an older instance is torn down and replaced,
+ *     an equal or newer one is left alone — never "if present, return";
+ *   - one observer per root (an observer on `document` alone misses shadow
+ *     roots), with `Element.prototype.attachShadow` patched to catch every
+ *     root created later, open or closed.
+ *
+ * Verbatim sibling: `packages/server/src/cdp/inpage/observer.ts` (the server
+ * publishes standalone and cannot import this package). Everything below this
+ * header must stay byte-identical — `cdp/drift.test.ts` enforces it and
+ * `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;
+/** 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. */
+export declare const OBSERVER_GLOBAL = "__blPageObserver";
+export interface ObserverInstallOpts {
+    /** Binding name to push through; defaults to `OBSERVER_BINDING`. */
+    binding?: string;
+    /** Instance version; defaults to `OBSERVER_VERSION`. */
+    version?: number;
+    /** Max target descriptors per summary (default 20, clamped to 1..100). */
+    descriptor_cap?: number;
+    /** Summaries kept for mark/changes read-back (default 64, clamped to 1..1024). */
+    ring_size?: number;
+}
+/**
+ * Build the observer install source. Valid both as a
+ * `Page.addScriptToEvaluateOnNewDocument` source and as a one-off
+ * `Runtime.evaluate` expression, which evaluates to
+ * `{ 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()`
+ * 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.
+ * `recordSnapshot(id, record)` keeps the last 4 snapshot records per document
+ * instance (oldest evicted first) for `snapshot({ since })`; `getSnapshot(id)`
+ * returns the record or `null` when unknown or evicted. The record is opaque
+ * here. Both are inert after teardown, which clears the store.
+ */
+export declare function buildObserverInstallJs(opts?: ObserverInstallOpts): string;
+/**
+ * Build the action-mark expression. Forces a flush (including records still
+ * queued in the observers) so the mark is exact, then baselines URL and focus.
+ * Evaluates to `{ ok: true, doc_id, mark, url, has_focus_baseline: true }` or
+ * `{ ok: false, reason: 'observer-unavailable' }`.
+ */
+export declare function buildObserverMarkJs(): string;
+/**
+ * Build the "changes since mark" expression. Forces a flush, then aggregates
+ * the ring summaries with `seq > mark`. `docId`, when given, must match the
+ * current document. Evaluates to the aggregated changes (see
+ * `SettleChanges` in `@browser-link/shared`) plus `ok`, `doc_id`, `since`,
+ * and `url_changed` / `focus_moved` only when they differ from the mark's
+ * baseline; or `{ ok: false, reason: 'observer-unavailable' | 'doc-changed' }`.
+ */
+export declare function buildObserverChangesJs(mark: number, docId?: string): string;
+/**
+ * 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' }`.
+ */
+export declare function buildObserverRefResolveJs(ref: string): string;
+/**
+ * Build the teardown expression: disconnects every observer, restores the
+ * `attachShadow` and `history` patches when they are still the observer's,
+ * and removes the global. Idempotent; evaluates to `{ ok: true, removed }`.
+ */
+export declare function buildObserverTeardownJs(): string;