@jobshimo/browser-link 0.35.0 → 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);
 })()
 `;
 }
@@ -623,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;
@@ -689,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;
   }
@@ -709,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":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AA6BlD,MAAM,UAAU,eAAe,CAAC,OAAqB,EAAE;IACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,cAAc,EAAE,OAAO,IAAI,CAAC,eAAe,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI;QACtF,eAAe,EAAE,IAAI,CAAC,gBAAgB,KAAK,IAAI;QAC/C,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;QACxD,cAAc,EACZ,OAAO,IAAI,CAAC,eAAe,KAAK,QAAQ,IAAI,IAAI,CAAC,eAAe,GAAG,CAAC;YAClE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,eAAe,EAAE,GAAG,CAAC;YACrC,CAAC,CAAC,GAAG;KACV,CAAC,CAAC;IACH,OAAO;;IAEL,aAAa;IACb,cAAc;iBACD,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8FxB,CAAC;AACF,CAAC;AAwCD,MAAM,UAAU,WAAW,CAAC,IAAc;IACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;QAC9E,KAAK,EAAE,IAAI,CAAC,KAAK,KAAK,IAAI;QAC1B,cAAc,EAAE,CAAC;QACjB,aAAa,EAAE,CAAC;KACjB,CAAC,CAAC;IACH,OAAO;;IAEL,aAAa;IACb,cAAc;iBACD,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmIxB,CAAC;AACF,CAAC;AAiCD,MAAM,UAAU,mBAAmB,CAAC,IAAsB;IACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAChF,OAAO;;IAEL,aAAa;iBACA,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;CAwBxB,CAAC;AACF,CAAC;AAqBD,MAAM,UAAU,kBAAkB,CAAC,IAAqB;IACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC7D,OAAO;;IAEL,aAAa;iBACA,QAAQ;;;;;;;;;IASrB,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,gGAAgG,CAAC,CAAC,CAAC,EAAE;;KAEjH,CAAC;AACN,CAAC;AAeD,MAAM,UAAU,YAAY,CAAC,IAAsB;IACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC7D,OAAO;;IAEL,aAAa;iBACA,QAAQ;;;;;KAKpB,CAAC;AACN,CAAC;AAoBD,MAAM,UAAU,sBAAsB,CACpC,QAAgB,EAChB,SAAmC;IAEnC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;IACzD,OAAO;;IAEL,aAAa;iBACA,QAAQ;;;;;;;;;;;;;KAapB,CAAC;AACN,CAAC;AAiBD,MAAM,UAAU,kBAAkB,CAAC,IAAqB;IACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC7D,OAAO;;IAEL,aAAa;iBACA,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAuCpB,CAAC;AACN,CAAC;AAwCD,MAAM,UAAU,gBAAgB,CAAC,IAAmB;IAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,IAAI,CAAC,IAAI;KAChB,CAAC,CAAC;IACH,OAAO;;IAEL,aAAa;cACH,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsDrB,CAAC;AACF,CAAC;AA8BD,MAAM,UAAU,aAAa,CAAC,IAAgB;IAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC;QACrC,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,iBAAiB,CAAC;KAC/C,CAAC,CAAC;IACH,OAAO;;iBAEQ,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA6CpB,CAAC;AACN,CAAC;AAQD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAqB;IACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,eAAe,EAAE,IAAI,CAAC,gBAAgB;QACtC,kBAAkB,EAAE,IAAI,CAAC,mBAAmB;QAC5C,WAAW,EAAE,IAAI,CAAC,YAAY;KAC/B,CAAC,CAAC;IACH,OAAO;;IAEL,aAAa;IACb,cAAc;iBACD,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4DxB,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO;;IAEL,aAAa;IACb,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmFjB,CAAC;AACF,CAAC"}
+{"version":3,"file":"builders.js","sourceRoot":"","sources":["../../src/inpage/builders.ts"],"names":[],"mappings":"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"}

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

@@ -22,7 +22,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 = 1;
+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. */
@@ -42,6 +42,19 @@ export interface ObserverInstallOpts {
  * `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;
 /**
@@ -60,6 +73,13 @@ export declare function buildObserverMarkJs(): string;
  * 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,

package/dist/extension/inpage/observer.js

@@ -22,7 +22,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 = 1;
+export const OBSERVER_VERSION = 2;
 /** 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. */
@@ -41,6 +41,19 @@ function clampInt(value, fallback, min, max) {
  * `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 function buildObserverInstallJs(opts = {}) {
     const optsJson = JSON.stringify({
@@ -82,6 +95,18 @@ export function buildObserverInstallJs(opts = {}) {
   };
   const observers = [];
   const observed = new WeakSet();
+  let refs = new WeakMap();
+  const refNodes = new Map();
+  let refSeq = 0;
+  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.
+  const SNAPSHOT_KEEP = 4;
+  const snapshots = new Map();
+  // WeakRef keeps the registry from pinning removed nodes; the fallback only
+  // matters on engines without it (Chrome has it since 84).
+  const holdWeakly =
+    typeof WeakRef === 'function' ? (el) => new WeakRef(el) : (el) => ({ deref: () => el });
   const round = (n) => Math.round(n * 10) / 10;
 
   function push(message) {
@@ -268,6 +293,53 @@ export function buildObserverInstallJs(opts = {}) {
 
   g.flush = flush;
 
+  g.refFor = function (el) {
+    try {
+      if (g.dead || !el || el.nodeType !== 1) return null;
+      let ref = refs.get(el);
+      if (!ref) {
+        ref = 'e' + ++refSeq;
+        refs.set(el, ref);
+      }
+      // Same node, same ref: re-register one pruned while it was detached.
+      if (!refNodes.has(ref)) refNodes.set(ref, holdWeakly(el));
+      return ref;
+    } catch (e) {
+      return null;
+    }
+  };
+
+  g.resolveRef = function (ref) {
+    try {
+      if (typeof ref !== 'string') return null;
+      const held = refNodes.get(ref);
+      if (!held) return null;
+      const el = held.deref();
+      if (el && el.isConnected) return el;
+      refNodes.delete(ref);
+      return null;
+    } catch (e) {
+      return null;
+    }
+  };
+
+  g.nextSnapshotId = function () {
+    if (g.dead) return null;
+    return g.doc_id + ':s' + ++snapshotSeq;
+  };
+  g.recordSnapshot = function (id, record) {
+    if (g.dead || typeof id !== 'string') return;
+    snapshots.delete(id);
+    snapshots.set(id, record);
+    while (snapshots.size > SNAPSHOT_KEEP) snapshots.delete(snapshots.keys().next().value);
+  };
+
+  g.getSnapshot = function (id) {
+    if (g.dead || typeof id !== 'string') return null;
+    const record = snapshots.get(id);
+    return record === undefined ? null : record;
+  };
+
   g.mark = function () {
     flush();
     const mark = g.seq;
@@ -348,6 +420,10 @@ export function buildObserverInstallJs(opts = {}) {
     window.removeEventListener('popstate', onNav);
     window.removeEventListener('hashchange', onNav);
     g.baselines.clear();
+    refs = new WeakMap();
+    refNodes.clear();
+    snapshotSeq = 0;
+    snapshots.clear();
     if (window[opts.key] === g) {
       try { delete window[opts.key]; } catch (e) {}
     }
@@ -390,9 +466,37 @@ export function buildObserverMarkJs() {
  */
 export function buildObserverChangesJs(mark, docId) {
     const markJson = JSON.stringify(clampInt(mark, 0, 0, Number.MAX_SAFE_INTEGER));
-    const docJson = typeof docId === 'string' && docId.length > 0 ? JSON.stringify(docId) : 'null';
+    const docJson = typeof docId === 'string' && docId.length > 0 ? jsStringLiteral(docId) : 'null';
     return callInstance(`g.changes(${markJson}, ${docJson})`);
 }
+/**
+ * A string literal safe to embed in JS source. `JSON.stringify` alone leaves
+ * U+2028 / U+2029 (line terminators in older JS grammars) and `<` (which can
+ * close a surrounding `<script>`) unescaped; this escapes them as `\uXXXX`,
+ * which parses back to the same string.
+ */
+function jsStringLiteral(value) {
+    // The two separators are written as char codes so this source file never
+    // carries them raw; the replacement is the six-character escape sequence.
+    const lineSeparator = String.fromCharCode(0x2028);
+    const paragraphSeparator = String.fromCharCode(0x2029);
+    return JSON.stringify(value)
+        .split(lineSeparator)
+        .join('\\u2028')
+        .split(paragraphSeparator)
+        .join('\\u2029')
+        .replace(/</g, '\\u003c');
+}
+/**
+ * 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 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}))`);
+}
 /**
  * Build the teardown expression: disconnects every observer, restores the
  * `attachShadow` and `history` patches when they are still the observer's,

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

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

package/dist/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "browser-link",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "Bridge between Chrome and an MCP client (Claude Code, OpenCode, GitHub Copilot CLI, …). Per-tab manual activation.",
   "permissions": [
     "debugger",

package/dist/tools/browser-definitions.js

@@ -188,7 +188,7 @@ export const BROWSER_TOOL_DEFINITIONS = [
     },
     {
         name: 'browser.snapshot',
-        description: 'Snapshot of the tab: title, url, visible text (truncated) and a list of interactive elements (buttons, links, inputs, selects, textareas) with a CSS selector and labels. Use this to understand page state before clicking or typing. Elements whose computed `pointer-events` is `none` (invisible accessibility layers that can never receive a real click) are excluded from the interactive list, though their text still contributes to headings/text; a descendant that re-enables itself with `pointer-events:auto` is still listed. The scan pierces OPEN Shadow DOM roots and same-origin iframes (nested arbitrarily) — a web component internal or an in-page iframe shows up without extra steps. An entry for an element living inside an iframe carries an extra `frame` field (the CSS selector of the innermost hosting iframe) so you know it is framed; entries in the top document or in Shadow DOM omit it. An entry whose selector could not be made unique across all roots (structurally-identical component twins) carries `ambiguous: true` — that selector resolves first-match-wins, so use it immediately and do NOT store it in the persistent map. Optional filters keep the response small: `within_selector` restricts the scan to a subtree (also deep-search-aware — it can target a subtree inside a shadow root or iframe); `only_interactive` skips headings and the text dump; `exclude` drops landmarks like nav/footer; `max_interactive` overrides the default cap of 120. The per-entry serializer omits empty-string fields, so the same call returns a leaner payload than before — no behavior change for clients that read by key.',
+        description: 'Snapshot of the tab: title, url, visible text (truncated) and a list of interactive elements (buttons, links, inputs, selects, textareas) with a CSS selector and labels. Use this to understand page state before clicking or typing. Elements whose computed `pointer-events` is `none` (invisible accessibility layers that can never receive a real click) are excluded from the interactive list, though their text still contributes to headings/text; a descendant that re-enables itself with `pointer-events:auto` is still listed. The scan pierces OPEN Shadow DOM roots and same-origin iframes (nested arbitrarily) — a web component internal or an in-page iframe shows up without extra steps. An entry for an element living inside an iframe carries an extra `frame` field (the CSS selector of the innermost hosting iframe) so you know it is framed; entries in the top document or in Shadow DOM omit it. An entry whose selector could not be made unique across all roots (structurally-identical component twins) carries `ambiguous: true` — that selector resolves first-match-wins, so use it immediately and do NOT store it in the persistent map. Optional filters keep the response small: `within_selector` restricts the scan to a subtree (also deep-search-aware — it can target a subtree inside a shadow root or iframe); `only_interactive` skips headings and the text dump; `exclude` drops landmarks like nav/footer; `max_interactive` overrides the default cap of 120. The per-entry serializer omits empty-string fields, so the same call returns a leaner payload than before — no behavior change for clients that read by key. When the page observer is running in the tab, each interactive entry also carries `ref` (right after `selector`): a per-document element handle `e<N>` issued by the page observer, stable for the same element across snapshot/find/state calls and valid only for the `doc_id` that issued it; unlike `ambiguous` (a selector-level warning), a `ref` names exactly one element of the current document. The result then also carries `doc_id` (the document instance that issued the refs; it changes on every new document) and `snapshot_id` (`<doc_id>:s<N>`, one per snapshot call in that document). All three are additive and ignorable, and are absent when the observer is not in the page. Pass `since: <snapshot_id>` to get a diff instead of the whole page: `{ title, url, doc_id, snapshot_id, since, added, removed, changed, overflow? }`, where `added` and `changed` are full entries (added first) and `removed` is `{ ref, tag, text? }`. `max_interactive` applies after diffing to `added` + `changed` and `overflow` (count dropped) appears only when above 0; `headings` and `text` appear in a diff only when `only_interactive` is false and they changed. When no diff can be made the result is the full snapshot plus `since` and `since_status`: `doc-changed` (the `since` prefix is not the current `doc_id`, or it has no `:`), `evicted` (same document, but not among the last 4 snapshots or never issued) or `observer-unavailable`. An invalid `since` (not a string, or over 64 characters) is dropped and a plain full snapshot is returned; a `within_selector` miss ignores `since`.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -210,6 +210,11 @@ export const BROWSER_TOOL_DEFINITIONS = [
                     type: 'number',
                     description: 'Cap on the number of interactive entries returned. Default 120, hard ceiling 500.',
                 },
+                since: {
+                    type: 'string',
+                    maxLength: 64,
+                    description: 'The `snapshot_id` of an earlier snapshot of this document. Format `<doc_id>:s<N>`. Returns only `added`, `removed` and `changed` entries (by `ref`) against it; when it cannot diff, returns the full snapshot plus `since_status` (`evicted`, `doc-changed` or `observer-unavailable`). The observer keeps the last 4 snapshots per document.',
+                },
             },
             required: ['tab_id'],
             additionalProperties: false,
@@ -221,6 +226,7 @@ export const BROWSER_TOOL_DEFINITIONS = [
                 'Before clicking or typing, to find a stable selector for the target element.',
                 'When the user reports a layout or visual issue and you need to ground your reasoning in what is actually rendered.',
                 'When you only care about a region of the page, pass `within_selector` so the response stays small.',
+                'When you look at the same view again: take one full snapshot, keep its `snapshot_id`, and pass it as `since` on every later look.',
             ],
             gotchas: [
                 'The snapshot is the source of truth; the persistent map is a cache, not a substitute.',
@@ -228,13 +234,17 @@ export const BROWSER_TOOL_DEFINITIONS = [
                 'Empty-string fields (`placeholder`, `aria_label`, etc.) are omitted from each entry. Read by key with optional-chaining or fall back to "".',
                 'CLOSED shadow roots (attachShadow({mode:"closed"})) are unreachable from any CDP-based tool — there is no workaround. Cross-origin iframes are also unreachable (same-origin policy); their content is invisible to this scan.',
                 'Two structurally-identical component instances in different roots (e.g. twin web components with byte-identical internals) cannot be told apart by any CSS selector — no syntax scopes a selector to one shadow root. Affected entries carry `ambiguous: true`; their selector resolves to the FIRST match in a deterministic traversal order. Use it right away, never cache it.',
+                '`ref`, `doc_id` and `snapshot_id` appear only when the page observer is running in the tab. A `ref` dies with its document: compare `doc_id` before trusting a ref from an earlier call, and never store refs in the persistent map. `ref` is informational for now: it is not yet accepted as an action target.',
+                'With `since`, a `since_status` of `doc-changed`, `evicted` or `observer-unavailable` means you already received the full snapshot: keep its new `snapshot_id` for the next `since`. Do not diff against the old id again.',
+                'The structural selector adds `:nth-of-type` only when siblings force it, so inserting a sibling can change the selector of a neighbour and list that neighbour in `changed`. The selector did change: use the current one, not the one from the earlier snapshot.',
+                'A diff covers at most the first 500 interactive entries of each snapshot, and `removed` is capped at 500.',
             ],
             example: 'browser.snapshot({ tab_id: "tab_1", within_selector: "main", exclude: ["nav", "footer"] })',
         },
     },
     {
         name: 'browser.find',
-        description: 'Locate ONE interactive element by its visible text and return a stable selector plus viewport coordinates. The match is case-insensitive substring by default (set `exact:true` for full-string equality). Pass `role` to narrow to a specific ARIA role (`button`, `link`, `textbox`, `checkbox`, `tab`, `menuitem`) — without it the scan covers buttons, links, inputs, role-bearing elements, contenteditable nodes, and `[onclick]` divs (the "peruvian markup" case). Elements whose computed `pointer-events` is `none` (invisible accessibility layers that can never receive a real click) are never returned as matches, though they can still surface as `near_misses` hints. The scan pierces OPEN Shadow DOM roots and same-origin iframes, same as browser.snapshot. Returns `{ matched: true, selector, coords:{x,y}, tag, text, frame?, ambiguous? }` on a unique hit, `{ matched: false, reason: "not-found", error?, near_misses? }` when nothing matches, or `{ matched: false, reason: "multiple-matches", candidates: [{selector, text, tag}] }` (up to 5) when several elements match — pick one and try again with `exact:true` or a longer text. On `not-found`, `near_misses` carries up to 3 VISIBLE candidates (`{text, selector, role?}`) ranked by substring containment then token overlap — omitted entirely when nothing plausible exists. When `role` excluded matches that the text DID find elsewhere, `error` names it explicitly (e.g. `text matched 2 elements but none with role "button" — closest: <div onclick> "GIF picker"`). `frame`, when present, is the CSS selector of the innermost iframe hosting the match. `ambiguous: true`, when present, means the selector could not be made unique across all roots (structurally-identical twins) and resolves first-match-wins — use it immediately, never cache it. `coords` are already mapped to TOP-LEVEL viewport coordinates even when the match lives inside an iframe. The returned `selector` uses the same heuristic as `browser.snapshot` (id → data-testid → aria-label → name → positional fallback, each verified unique across the full deep search scope), so a subsequent `browser.click` / `browser.type` works without re-querying.',
+        description: 'Locate ONE interactive element by its visible text and return a stable selector plus viewport coordinates. The match is case-insensitive substring by default (set `exact:true` for full-string equality). Pass `role` to narrow to a specific ARIA role (`button`, `link`, `textbox`, `checkbox`, `tab`, `menuitem`) — without it the scan covers buttons, links, inputs, role-bearing elements, contenteditable nodes, and `[onclick]` divs (the "peruvian markup" case). Elements whose computed `pointer-events` is `none` (invisible accessibility layers that can never receive a real click) are never returned as matches, though they can still surface as `near_misses` hints. The scan pierces OPEN Shadow DOM roots and same-origin iframes, same as browser.snapshot. Returns `{ matched: true, selector, ref?, coords:{x,y}, tag, text, frame?, ambiguous?, doc_id? }` on a unique hit, `{ matched: false, reason: "not-found", error?, near_misses?, doc_id? }` when nothing matches, or `{ matched: false, reason: "multiple-matches", candidates: [{selector, ref?, text, tag}], doc_id? }` (up to 5) when several elements match — pick one and try again with `exact:true` or a longer text. On `not-found`, `near_misses` carries up to 3 VISIBLE candidates (`{text, selector, ref?, role?}`) ranked by substring containment then token overlap — omitted entirely when nothing plausible exists. When `role` excluded matches that the text DID find elsewhere, `error` names it explicitly (e.g. `text matched 2 elements but none with role "button" — closest: <div onclick> "GIF picker"`). `frame`, when present, is the CSS selector of the innermost iframe hosting the match. `ambiguous: true`, when present, means the selector could not be made unique across all roots (structurally-identical twins) and resolves first-match-wins — use it immediately, never cache it. `coords` are already mapped to TOP-LEVEL viewport coordinates even when the match lives inside an iframe. The returned `selector` uses the same heuristic as `browser.snapshot` (id → data-testid → aria-label → name → positional fallback, each verified unique across the full deep search scope), so a subsequent `browser.click` / `browser.type` works without re-querying. `ref` and `doc_id` are additive, ignorable fields present only when the page observer is running in the tab: `ref` is the same per-document element handle `e<N>` that browser.snapshot reports for that element, valid only for the `doc_id` that issued it.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -277,7 +287,7 @@ export const BROWSER_TOOL_DEFINITIONS = [
     },
     {
         name: 'browser.state',
-        description: 'Compact orientation snapshot — cheaper than a full browser.snapshot when the agent only needs to know where it is. Returns { url, title, viewport:{w,h}, focused?, dialogs?, scroll? }. `focused` is the innermost actually-focused element (descending through open Shadow DOM roots and same-origin iframes past `document.activeElement`, which by itself only reports a shadow host or an <iframe> element) as `{ selector, tag, ambiguous? }`. `dialogs` lists visible `[role=dialog]`, `[role=alertdialog]` and open `<dialog>` elements as `{ selector, role, label? }`, `label` best-effort from aria-label / aria-labelledby / the first heading inside. `scroll` is `{x,y}` and is omitted when the page is at its default (0,0) position. Every optional field is omitted when there is nothing to report.',
+        description: 'Compact orientation snapshot — cheaper than a full browser.snapshot when the agent only needs to know where it is. Returns { url, title, viewport:{w,h}, focused?, dialogs?, scroll? }. `focused` is the innermost actually-focused element (descending through open Shadow DOM roots and same-origin iframes past `document.activeElement`, which by itself only reports a shadow host or an <iframe> element) as `{ selector, ref?, tag, ambiguous? }`. `dialogs` lists visible `[role=dialog]`, `[role=alertdialog]` and open `<dialog>` elements as `{ selector, role, label? }`, `label` best-effort from aria-label / aria-labelledby / the first heading inside. `scroll` is `{x,y}` and is omitted when the page is at its default (0,0) position. Every optional field is omitted when there is nothing to report. When the page observer is running in the tab, `focused.ref` is the same per-document element handle `e<N>` that browser.snapshot reports for that element and the result carries `doc_id`; both are additive, ignorable, valid only for that `doc_id`, and absent when the observer is not in the page.',
         inputSchema: {
             type: 'object',
             properties: { tab_id: { type: 'string' } },