@jobshimo/browser-link 0.34.1 → 0.35.0

package/dist/extension/inpage/observer.js

@@ -0,0 +1,416 @@
+/**
+ * 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 const OBSERVER_VERSION = 1;
+/** 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. */
+export const OBSERVER_GLOBAL = '__blPageObserver';
+const DEFAULT_DESCRIPTOR_CAP = 20;
+const MAX_DESCRIPTOR_CAP = 100;
+const DEFAULT_RING_SIZE = 64;
+const MAX_RING_SIZE = 1024;
+function clampInt(value, fallback, min, max) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.floor(value)));
+}
+/**
+ * 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 }`.
+ */
+export function buildObserverInstallJs(opts = {}) {
+    const optsJson = JSON.stringify({
+        key: OBSERVER_GLOBAL,
+        binding: typeof opts.binding === 'string' && opts.binding.length > 0 ? opts.binding : OBSERVER_BINDING,
+        version: clampInt(opts.version, OBSERVER_VERSION, 0, Number.MAX_SAFE_INTEGER),
+        cap: clampInt(opts.descriptor_cap, DEFAULT_DESCRIPTOR_CAP, 1, MAX_DESCRIPTOR_CAP),
+        ringSize: clampInt(opts.ring_size, DEFAULT_RING_SIZE, 1, MAX_RING_SIZE),
+    });
+    return `
+(() => {
+  const opts = ${optsJson};
+  const existing = window[opts.key];
+  if (existing && typeof existing.version === 'number' && existing.version >= opts.version) {
+    return { ok: true, installed: false, version: existing.version, doc_id: existing.doc_id, coverage: existing.coverage };
+  }
+  if (existing && typeof existing.teardown === 'function') {
+    try { existing.teardown(); } catch (e) {}
+  }
+  let isFrame = true;
+  try { isFrame = window !== window.top; } catch (e) {}
+  const zeroKinds = () => ({ childList: 0, attributes: 0, characterData: 0 });
+  const g = {
+    version: opts.version,
+    doc_id: Math.random().toString(36).slice(2, 10) + Date.now().toString(36),
+    seq: 0,
+    ring: [],
+    pending: new Map(),
+    pendingRecords: 0,
+    pendingKinds: zeroKinds(),
+    pendingRoots: { document: false, shadow: false },
+    t0: 0,
+    timer: null,
+    rescan: null,
+    roots: 0,
+    coverage: 'full',
+    baselines: new Map(),
+    dead: false,
+  };
+  const observers = [];
+  const observed = new WeakSet();
+  const round = (n) => Math.round(n * 10) / 10;
+
+  function push(message) {
+    const fn = window[opts.binding];
+    if (typeof fn !== 'function') return;
+    try { fn(JSON.stringify(message)); } catch (e) {}
+  }
+
+  function fold(records, kind) {
+    for (const rec of records) {
+      if (g.pendingRecords === 0) g.t0 = performance.now();
+      g.pendingRecords++;
+      g.pendingKinds[rec.type]++;
+      g.pendingRoots[kind] = true;
+      const target = rec.type === 'characterData' ? rec.target.parentNode : rec.target;
+      if (!target) continue;
+      g.pending.set(target, (g.pending.get(target) || 0) + 1);
+    }
+  }
+
+  function drain() {
+    for (const o of observers) {
+      const recs = o.mo.takeRecords();
+      if (recs.length) fold(recs, o.kind);
+    }
+  }
+
+  function segment(el) {
+    const tag = el.localName || String(el.nodeName).toLowerCase();
+    return el.id ? tag + '#' + el.id : tag;
+  }
+
+  function pathOf(node) {
+    const parts = [];
+    let n = node;
+    let segments = 0;
+    while (n && segments < 6) {
+      if (n.nodeType === 1) {
+        if (n === document.documentElement) break;
+        parts.unshift(segment(n));
+        segments++;
+        n = n.parentNode;
+      } else if (n.nodeType === 11 && n.host) {
+        parts.unshift('#shadow');
+        n = n.host;
+      } else {
+        break;
+      }
+    }
+    return parts.join('>');
+  }
+
+  function describe(node) {
+    if (node.nodeType === 11) {
+      return { tag: '#shadow-root', path: node.host ? pathOf(node.host) + '>#shadow' : '#shadow' };
+    }
+    if (node.nodeType === 9) return { tag: '#document', path: '#document' };
+    const d = { tag: node.localName || String(node.nodeName).toLowerCase() };
+    if (typeof node.id === 'string' && node.id) d.id = node.id;
+    const role = typeof node.getAttribute === 'function' ? node.getAttribute('role') : null;
+    if (role) d.role = role;
+    d.path = pathOf(node);
+    return d;
+  }
+
+  function flush() {
+    if (g.timer !== null) {
+      clearTimeout(g.timer);
+      g.timer = null;
+    }
+    drain();
+    if (g.pendingRecords === 0) return null;
+    const entries = Array.from(g.pending.entries()).sort((a, b) => b[1] - a[1]);
+    const top = entries.slice(0, opts.cap);
+    const summary = {
+      type: 'summary',
+      doc_id: g.doc_id,
+      seq: ++g.seq,
+      t0: round(g.t0),
+      t1: round(performance.now()),
+      records: g.pendingRecords,
+      targets: entries.length,
+      kinds: g.pendingKinds,
+      roots: { document: g.pendingRoots.document, shadow: g.pendingRoots.shadow, frame: isFrame },
+      descriptors: top.map((e) => describe(e[0])),
+      overflow: entries.length - top.length,
+    };
+    g.ring.push({ summary: summary, counts: top.map((e) => e[1]) });
+    while (g.ring.length > opts.ringSize) g.ring.shift();
+    g.pending = new Map();
+    g.pendingRecords = 0;
+    g.pendingKinds = zeroKinds();
+    g.pendingRoots = { document: false, shadow: false };
+    push(summary);
+    return summary;
+  }
+
+  function onTimer() {
+    g.timer = null;
+    try { flush(); } catch (e) {}
+  }
+
+  function onRecords(kind) {
+    return (records) => {
+      if (g.dead) return;
+      try {
+        fold(records, kind);
+        if (g.pendingRecords > 0 && g.timer === null) g.timer = setTimeout(onTimer, 16);
+      } catch (e) {}
+    };
+  }
+
+  function observe(root, kind) {
+    if (!root || observed.has(root)) return;
+    observed.add(root);
+    try {
+      const mo = new MutationObserver(onRecords(kind));
+      mo.observe(root, { subtree: true, childList: true, attributes: true, characterData: true });
+      observers.push({ mo: mo, kind: kind });
+      g.roots++;
+    } catch (e) {}
+  }
+
+  function walk(root) {
+    let all;
+    try { all = root.querySelectorAll('*'); } catch (e) { return; }
+    for (const el of all) {
+      const sr = el.shadowRoot;
+      if (sr) {
+        observe(sr, 'shadow');
+        walk(sr);
+      }
+    }
+  }
+
+  observe(document, 'document');
+  walk(document);
+
+  const proto = Element.prototype;
+  const originalAttach = proto.attachShadow;
+  let patchedAttach = null;
+  if (typeof originalAttach === 'function') {
+    try {
+      const candidate = function attachShadow() {
+        const root = originalAttach.apply(this, arguments);
+        if (!g.dead) {
+          try { observe(root, 'shadow'); } catch (e) {}
+        }
+        return root;
+      };
+      proto.attachShadow = candidate;
+      if (proto.attachShadow !== candidate) throw new Error('attachShadow not patchable');
+      patchedAttach = candidate;
+    } catch (e) {
+      g.coverage = 'partial';
+      g.rescan = setInterval(() => {
+        try { walk(document); } catch (err) {}
+      }, 2000);
+    }
+  }
+
+  function onNav() {
+    if (g.dead) return;
+    push({ type: 'nav', doc_id: g.doc_id, url: location.href });
+  }
+  const hist = window.history;
+  const historyPatches = [];
+  for (const name of ['pushState', 'replaceState']) {
+    const original = hist[name];
+    if (typeof original !== 'function') continue;
+    const hadOwn = Object.prototype.hasOwnProperty.call(hist, name);
+    const wrapped = function () {
+      const result = original.apply(this, arguments);
+      try { onNav(); } catch (e) {}
+      return result;
+    };
+    try {
+      hist[name] = wrapped;
+      historyPatches.push({ name: name, original: original, wrapped: wrapped, hadOwn: hadOwn });
+    } catch (e) {}
+  }
+  window.addEventListener('popstate', onNav);
+  window.addEventListener('hashchange', onNav);
+
+  g.flush = flush;
+
+  g.mark = function () {
+    flush();
+    const mark = g.seq;
+    g.baselines.delete(mark);
+    g.baselines.set(mark, { url: location.href, active: document.activeElement });
+    while (g.baselines.size > 16) g.baselines.delete(g.baselines.keys().next().value);
+    return { ok: true, doc_id: g.doc_id, mark: mark, url: location.href, has_focus_baseline: true };
+  };
+
+  g.changes = function (mark, docId) {
+    if (docId && docId !== g.doc_id) return { ok: false, reason: 'doc-changed' };
+    const base = g.baselines.get(mark);
+    if (!base) return { ok: false, reason: 'doc-changed' };
+    flush();
+    const items = g.ring.filter((it) => it.summary.seq > mark);
+    const kinds = zeroKinds();
+    const roots = { document: false, shadow: false, frame: isFrame };
+    const merged = new Map();
+    let records = 0;
+    let targets = 0;
+    let overflow = 0;
+    for (const it of items) {
+      const s = it.summary;
+      records += s.records;
+      targets += s.targets;
+      overflow += s.overflow;
+      kinds.childList += s.kinds.childList;
+      kinds.attributes += s.kinds.attributes;
+      kinds.characterData += s.kinds.characterData;
+      roots.document = roots.document || s.roots.document;
+      roots.shadow = roots.shadow || s.roots.shadow;
+      s.descriptors.forEach((d, i) => {
+        const key = d.tag + '\\u0000' + (d.id || '') + '\\u0000' + d.path;
+        const m = merged.get(key);
+        if (m) m.n += it.counts[i];
+        else merged.set(key, { d: d, n: it.counts[i] });
+      });
+    }
+    const sorted = Array.from(merged.values()).sort((a, b) => b.n - a.n);
+    const descriptors = sorted.slice(0, opts.cap).map((m) => m.d);
+    overflow += sorted.length - descriptors.length;
+    const out = {
+      ok: true,
+      doc_id: g.doc_id,
+      since: mark,
+      records: records,
+      targets: targets,
+      kinds: kinds,
+      roots: roots,
+      descriptors: descriptors,
+      overflow: overflow,
+    };
+    if (g.seq > mark && (items.length === 0 || items[0].summary.seq !== mark + 1)) out.truncated = true;
+    if (location.href !== base.url) out.url_changed = location.href;
+    if (document.activeElement !== base.active) out.focus_moved = true;
+    return out;
+  };
+
+  g.teardown = function () {
+    if (g.dead) return;
+    g.dead = true;
+    if (g.timer !== null) clearTimeout(g.timer);
+    if (g.rescan !== null) clearInterval(g.rescan);
+    for (const o of observers) {
+      try { o.mo.disconnect(); } catch (e) {}
+    }
+    observers.length = 0;
+    if (patchedAttach && proto.attachShadow === patchedAttach) {
+      try { proto.attachShadow = originalAttach; } catch (e) {}
+    }
+    for (const p of historyPatches) {
+      if (hist[p.name] !== p.wrapped) continue;
+      try {
+        if (p.hadOwn) hist[p.name] = p.original;
+        else delete hist[p.name];
+      } catch (e) {}
+    }
+    window.removeEventListener('popstate', onNav);
+    window.removeEventListener('hashchange', onNav);
+    g.baselines.clear();
+    if (window[opts.key] === g) {
+      try { delete window[opts.key]; } catch (e) {}
+    }
+  };
+
+  Object.defineProperty(window, opts.key, { value: g, configurable: true, writable: true, enumerable: false });
+  push({ type: 'doc_start', doc_id: g.doc_id, url: location.href, version: g.version, coverage: g.coverage });
+  return { ok: true, installed: true, version: g.version, doc_id: g.doc_id, coverage: g.coverage };
+})()`;
+}
+const UNAVAILABLE = "{ ok: false, reason: 'observer-unavailable' }";
+function callInstance(call) {
+    return `
+(() => {
+  const g = window[${JSON.stringify(OBSERVER_GLOBAL)}];
+  if (!g || g.dead || typeof g.doc_id !== 'string') return ${UNAVAILABLE};
+  try {
+    return ${call};
+  } catch (e) {
+    return ${UNAVAILABLE};
+  }
+})()`;
+}
+/**
+ * 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 function buildObserverMarkJs() {
+    return callInstance('g.mark()');
+}
+/**
+ * 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 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';
+    return callInstance(`g.changes(${markJson}, ${docJson})`);
+}
+/**
+ * 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 function buildObserverTeardownJs() {
+    return `
+(() => {
+  const key = ${JSON.stringify(OBSERVER_GLOBAL)};
+  const g = window[key];
+  if (!g) return { ok: true, removed: false };
+  if (typeof g.teardown === 'function') {
+    try { g.teardown(); } catch (e) {}
+  }
+  if (window[key] === g) {
+    try { delete window[key]; } catch (e) {}
+  }
+  return { ok: true, removed: true };
+})()`;
+}
+//# sourceMappingURL=observer.js.map

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

@@ -0,0 +1 @@
+{"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.34.1",
+  "version": "0.35.0",
   "description": "Bridge between Chrome and an MCP client (Claude Code, OpenCode, GitHub Copilot CLI, …). Per-tab manual activation.",
   "permissions": [
     "debugger",

package/dist/extension/observer-host.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Host side of the page observer (spec v4 §5.4–§5.5): the per-tab mirror of
+ * what the in-page observer (`inpage/observer.ts`) has pushed through its
+ * binding, and the rule that folds an action's "changes since mark" into
+ * the settle result. Caller-context logic, not injected page JS, and free of
+ * `chrome.*` / CDP calls so it is unit-testable on its own and can be copied
+ * verbatim by the cdp-direct transport on the server. The caller owns every
+ * evaluation; this module only parses and decides.
+ */
+import type { PageObserverMessage, PageObserverSummary } from '@browser-link/shared';
+/** Summaries kept in the host mirror (the page keeps its own, larger ring). */
+export declare const OBSERVER_RECENT_CAP = 32;
+/** Per-tab host state for the page observer of the tab's top document. */
+export interface ObserverMirror {
+    /** True once the install commands succeeded on this tab. */
+    installed: boolean;
+    doc_id?: string;
+    url?: string;
+    coverage?: 'full' | 'partial';
+    last_seq: number;
+    recent: PageObserverSummary[];
+}
+export type ObserverMessageOutcome = {
+    kind: 'doc_start';
+    url: string;
+} | {
+    kind: 'nav';
+    url: string;
+} | {
+    kind: 'summary';
+} | {
+    kind: 'ignored';
+};
+/** Reason attached as `settle.observer` when `changes` could not be read. */
+export type ObserverChangesFailure = 'observer-unavailable' | 'doc-changed' | 'changes-error';
+/** The settle result as the action callers carry it (`settleSafely`). */
+export type SettleResultLike = Record<string, unknown>;
+export declare function createObserverMirror(): ObserverMirror;
+/**
+ * Parse one binding payload. The binding is a page-visible global, so the
+ * payload is untrusted: anything that is not valid JSON in one of the three
+ * observer message shapes yields `null`.
+ */
+export declare function parseObserverMessage(payload: string): PageObserverMessage | null;
+/**
+ * Fold one observer message into the mirror. `doc_start` and `nav` are
+ * assumed to come from the top document — the caller confirms that first
+ * with `TOP_DOCUMENT_PROBE_JS` / `isTopDocumentMessage`, because the install
+ * script also runs in same-process child frames. Summaries from a child
+ * frame (`roots.frame`) or from a document other than the mirrored one are
+ * ignored. A `nav` that does not change the URL (e.g. a state-only
+ * `replaceState`) is ignored so it does not emit a navigation event.
+ */
+export declare function applyObserverMessage(mirror: ObserverMirror, message: PageObserverMessage): ObserverMessageOutcome;
+/**
+ * Expression evaluated in the tab's top document (default `Runtime.evaluate`
+ * context) to tell whether a `doc_start` / `nav` came from it: evaluates to
+ * `{ doc_id }` of the observer installed there, or `{ doc_id: null }`.
+ */
+export declare const TOP_DOCUMENT_PROBE_JS: string;
+/** True when the top-document probe reports the message's `doc_id`. */
+export declare function isTopDocumentMessage(probe: unknown, docId: string): boolean;
+/** The part of an action mark (`buildObserverMarkJs`) the changes read needs. */
+export interface ObserverMark {
+    mark: number;
+    doc_id: string;
+}
+/**
+ * Validate the result of the mark evaluation. `null` means there is no
+ * usable mark (observer missing, `ok: false`, or a malformed value); the
+ * caller then skips the changes read and reports the failure instead.
+ */
+export declare function readObserverMark(value: unknown): ObserverMark | null;
+/**
+ * Fold the observer's "changes since mark" into a settle result (spec v4
+ * §5.4). With valid changes: attach `changes` (the `SettleChanges` shape),
+ * recompute `mutation_count` from the observer's records, and replace
+ * `url_changed` / `focus_moved` with the values baselined at the action
+ * mark (present only when they changed). Otherwise keep every settle field
+ * as `settleSafely` produced it and add `changes: null` plus
+ * `observer: <reason>`. A `null` settle (settle disabled) stays `null`.
+ * Returns a new object; never throws.
+ */
+export declare function mergeSettleChanges(settle: SettleResultLike | null, changes: unknown): SettleResultLike | null;

package/dist/extension/observer-host.js

@@ -0,0 +1,172 @@
+import { OBSERVER_GLOBAL } from './inpage/observer.js';
+/** Summaries kept in the host mirror (the page keeps its own, larger ring). */
+export const OBSERVER_RECENT_CAP = 32;
+export function createObserverMirror() {
+    return { installed: false, last_seq: 0, recent: [] };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isCount(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+function isKinds(value) {
+    return (isRecord(value) &&
+        isCount(value.childList) &&
+        isCount(value.attributes) &&
+        isCount(value.characterData));
+}
+function isRoots(value) {
+    return (isRecord(value) &&
+        typeof value.document === 'boolean' &&
+        typeof value.shadow === 'boolean' &&
+        typeof value.frame === 'boolean');
+}
+/** Shared by summaries and by the "changes since mark" aggregate. */
+function hasChangeCounts(value) {
+    return (isCount(value.records) &&
+        isCount(value.targets) &&
+        isKinds(value.kinds) &&
+        isRoots(value.roots) &&
+        Array.isArray(value.descriptors) &&
+        isCount(value.overflow));
+}
+/**
+ * Parse one binding payload. The binding is a page-visible global, so the
+ * payload is untrusted: anything that is not valid JSON in one of the three
+ * observer message shapes yields `null`.
+ */
+export function parseObserverMessage(payload) {
+    let raw;
+    try {
+        raw = JSON.parse(payload);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(raw) || typeof raw.doc_id !== 'string')
+        return null;
+    switch (raw.type) {
+        case 'summary':
+            return isCount(raw.seq) && hasChangeCounts(raw)
+                ? raw
+                : null;
+        case 'doc_start':
+            return typeof raw.url === 'string' && (raw.coverage === 'full' || raw.coverage === 'partial')
+                ? raw
+                : null;
+        case 'nav':
+            return typeof raw.url === 'string' ? raw : null;
+        default:
+            return null;
+    }
+}
+/**
+ * Fold one observer message into the mirror. `doc_start` and `nav` are
+ * assumed to come from the top document — the caller confirms that first
+ * with `TOP_DOCUMENT_PROBE_JS` / `isTopDocumentMessage`, because the install
+ * script also runs in same-process child frames. Summaries from a child
+ * frame (`roots.frame`) or from a document other than the mirrored one are
+ * ignored. A `nav` that does not change the URL (e.g. a state-only
+ * `replaceState`) is ignored so it does not emit a navigation event.
+ */
+export function applyObserverMessage(mirror, message) {
+    switch (message.type) {
+        case 'doc_start':
+            mirror.doc_id = message.doc_id;
+            mirror.url = message.url;
+            mirror.coverage = message.coverage;
+            mirror.last_seq = 0;
+            mirror.recent = [];
+            return { kind: 'doc_start', url: message.url };
+        case 'nav':
+            if (mirror.doc_id !== undefined && message.doc_id !== mirror.doc_id)
+                return { kind: 'ignored' };
+            if (message.url === mirror.url)
+                return { kind: 'ignored' };
+            mirror.url = message.url;
+            return { kind: 'nav', url: message.url };
+        case 'summary':
+            if (message.roots.frame)
+                return { kind: 'ignored' };
+            if (mirror.doc_id !== undefined && message.doc_id !== mirror.doc_id)
+                return { kind: 'ignored' };
+            mirror.last_seq = Math.max(mirror.last_seq, message.seq);
+            mirror.recent.push(message);
+            while (mirror.recent.length > OBSERVER_RECENT_CAP)
+                mirror.recent.shift();
+            return { kind: 'summary' };
+        default:
+            return { kind: 'ignored' };
+    }
+}
+/**
+ * Expression evaluated in the tab's top document (default `Runtime.evaluate`
+ * context) to tell whether a `doc_start` / `nav` came from it: evaluates to
+ * `{ doc_id }` of the observer installed there, or `{ doc_id: null }`.
+ */
+export const TOP_DOCUMENT_PROBE_JS = `(() => {
+  const g = window[${JSON.stringify(OBSERVER_GLOBAL)}];
+  return { doc_id: g && typeof g.doc_id === 'string' ? g.doc_id : null };
+})()`;
+/** True when the top-document probe reports the message's `doc_id`. */
+export function isTopDocumentMessage(probe, docId) {
+    return isRecord(probe) && typeof probe.doc_id === 'string' && probe.doc_id === docId;
+}
+/**
+ * Validate the result of the mark evaluation. `null` means there is no
+ * usable mark (observer missing, `ok: false`, or a malformed value); the
+ * caller then skips the changes read and reports the failure instead.
+ */
+export function readObserverMark(value) {
+    if (!isRecord(value) || value.ok !== true)
+        return null;
+    if (!isCount(value.mark) || typeof value.doc_id !== 'string')
+        return null;
+    return { mark: value.mark, doc_id: value.doc_id };
+}
+function failureReason(changes) {
+    if (isRecord(changes) &&
+        changes.ok === false &&
+        (changes.reason === 'observer-unavailable' || changes.reason === 'doc-changed')) {
+        return changes.reason;
+    }
+    return 'changes-error';
+}
+/**
+ * Fold the observer's "changes since mark" into a settle result (spec v4
+ * §5.4). With valid changes: attach `changes` (the `SettleChanges` shape),
+ * recompute `mutation_count` from the observer's records, and replace
+ * `url_changed` / `focus_moved` with the values baselined at the action
+ * mark (present only when they changed). Otherwise keep every settle field
+ * as `settleSafely` produced it and add `changes: null` plus
+ * `observer: <reason>`. A `null` settle (settle disabled) stays `null`.
+ * Returns a new object; never throws.
+ */
+export function mergeSettleChanges(settle, changes) {
+    if (settle === null)
+        return null;
+    if (!isRecord(changes) || changes.ok !== true || !hasChangeCounts(changes)) {
+        return { ...settle, changes: null, observer: failureReason(changes) };
+    }
+    const summary = {
+        records: changes.records,
+        targets: changes.targets,
+        kinds: changes.kinds,
+        roots: changes.roots,
+        descriptors: changes.descriptors,
+        overflow: changes.overflow,
+    };
+    if (changes.truncated === true)
+        summary.truncated = true;
+    const merged = { ...settle, mutation_count: summary.records };
+    delete merged.url_changed;
+    delete merged.focus_moved;
+    if (typeof changes.url_changed === 'string')
+        merged.url_changed = changes.url_changed;
+    if (changes.focus_moved === true)
+        merged.focus_moved = true;
+    merged.changes = summary;
+    return merged;
+}
+//# sourceMappingURL=observer-host.js.map