@jobshimo/browser-link 0.34.1 → 0.35.0

package/dist/cdp/inpage/observer.js

@@ -0,0 +1,405 @@
+/**
+ * Independent copy of `packages/extension/src/inpage/observer.ts` — see
+ * `./deep-query.ts`'s header comment for why this is a verbatim duplicate
+ * rather than a cross-package import.
+ *
+ * The page observer: a persistent, coalescing MutationObserver that runs in
+ * the page's MAIN world (spec v4 §5.1–§5.3). cdp-direct installs it with the
+ * same `Runtime.addBinding` + `Page.addScriptToEvaluateOnNewDocument` pair as
+ * the extension. Everything below this header must stay byte-identical to the
+ * extension original — `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/cdp/inpage/observer.js.map

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

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

@@ -0,0 +1,137 @@
+/** Per-kind MutationRecord counts reported by the page observer. */
+interface PageObserverKinds {
+    childList: number;
+    attributes: number;
+    characterData: number;
+}
+/** Which kinds of root the counted records came from. `frame` is true when
+ * the observer runs in a child frame (`window !== window.top`). */
+interface PageObserverRoots {
+    document: boolean;
+    shadow: boolean;
+    frame: boolean;
+}
+/** One mutated target, as described by the page observer. `path` is a short
+ * structural path such as `body>div#app>ul` (at most six element segments,
+ * no indexes), with a `#shadow` segment at each shadow-root boundary. A
+ * shadow root that was itself the mutation target is reported with tag
+ * `#shadow-root`. */
+interface PageObserverDescriptor {
+    tag: string;
+    id?: string;
+    role?: string;
+    path: string;
+}
+/** One coalesced flush of the page observer: every MutationRecord seen
+ * since the previous flush, folded per target element. */
+interface PageObserverSummary {
+    type: 'summary';
+    doc_id: string;
+    /** Monotonic per document, starting at 1. */
+    seq: number;
+    /** `performance.now()` at the first record and at the flush. */
+    t0: number;
+    t1: number;
+    records: number;
+    /** Distinct target elements in this flush. */
+    targets: number;
+    kinds: PageObserverKinds;
+    roots: PageObserverRoots;
+    /** Up to the descriptor cap, ordered by record count (highest first). */
+    descriptors: PageObserverDescriptor[];
+    /** Targets beyond the descriptor cap. */
+    overflow: number;
+}
+/** Pushed once when the page observer installs in a document. */
+interface PageObserverDocStart {
+    type: 'doc_start';
+    doc_id: string;
+    url: string;
+    version: number;
+    /** `partial` when `attachShadow` could not be patched and the observer
+     * falls back to a periodic rescan for open shadow roots. */
+    coverage: 'full' | 'partial';
+}
+/** Pushed on `pushState`, `replaceState`, `popstate` and `hashchange`. */
+interface PageObserverNav {
+    type: 'nav';
+    doc_id: string;
+    url: string;
+}
+/** Every message the page observer pushes through its binding (JSON). */
+type PageObserverMessage = PageObserverSummary | PageObserverDocStart | PageObserverNav;
+/** 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;
+export {};