@reticlehq/browser 2.7.0 → 2.8.0

package/README.md

@@ -8,10 +8,10 @@ npm i -D @reticlehq/browser
 
 ```ts
 import { reticle } from '@reticlehq/browser';
-if (import.meta.env.DEV) reticle.connect({ session: 'my-app' });
+if (import.meta.env.DEV) reticle.connect(); // session defaults to a fresh per-tab id
 
 // surface non-DOM events too:
 reticle.signal('webhook:received', { provider: 'stripe' });
 ```
 
-Pair with [`@reticlehq/server`](https://www.npmjs.com/package/@reticlehq/server) (the bridge + MCP server) and optionally [`@reticlehq/react`](https://www.npmjs.com/package/@reticlehq/react) for component/source mapping. See the [main README](https://github.com/reticlehq/reticle) for the full picture. Dev-only, localhost-only by default. MIT.
+Pair with [`@reticlehq/server`](https://www.npmjs.com/package/@reticlehq/server) (the bridge + MCP server) and optionally [`@reticlehq/react`](https://www.npmjs.com/package/@reticlehq/react) for component/source mapping. See the [main README](https://github.com/reticlehq/reticle) for the full picture. Dev-only, localhost-only by default. Apache-2.0.

package/dist/commands/commands.js

@@ -91,6 +91,12 @@ function inspect(ref) {
     // stamped host. `act` already did this; inspect did not, so the two tools disagreed about the same
     // ref and inspect — the tool you reach for to ask where something lives — was the one saying null.
     const source = formatSource(sourceFor(el, component?.source));
+    const scroll = {
+        scrollTop: el.scrollTop,
+        scrollHeight: el.scrollHeight,
+        clientHeight: el.clientHeight,
+        overflowY: cs?.overflowY ?? 'visible',
+    };
     return {
         ...describe(el),
         ...(source !== undefined ? { source } : {}),
@@ -103,6 +109,7 @@ function inspect(ref) {
         // not this control (a z-index/overlay bug the DOM tree cannot show).
         occluded: isOccluded(el, rect),
         styles,
+        scroll,
         // Theme compliance vs the app's design tokens (off-theme colors a DOM tool can't judge).
         theme: cs !== null ? themeReport(cs) : null,
         component,

package/dist/dom/desktop-capture.js

@@ -32,6 +32,18 @@ import { RETICLE_OVERLAY } from './dom-ignore.js';
  * later diff reports as matching. So the shells say so, and the tool reports the reason.
  */
 const FULL_PAGE_UNSUPPORTED_MARKER = VisualReason.FULL_PAGE_UNSUPPORTED;
+/**
+ * Reasons a shell can name, in the order they are matched.
+ *
+ * The shell throws one of these rather than answering a bare null, because "nothing came back" was
+ * covering three different problems at once: a window with no composited frame yet, a webContents
+ * that had gone away, and any error at all. They need different responses from the reader, and the
+ * tool reported them identically.
+ */
+const RECOGNISED_MARKERS = [
+    FULL_PAGE_UNSUPPORTED_MARKER,
+    VisualReason.NOT_COMPOSITED,
+];
 const TAURI_INTERNALS_GLOBAL = '__TAURI_INTERNALS__';
 /**
  * Tauri's capture path, used when no preload-installed channel exists.
@@ -106,8 +118,13 @@ export async function captureDesktopWindow(fullPage = false) {
     }
     catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
-        return reason.includes(FULL_PAGE_UNSUPPORTED_MARKER)
-            ? { ok: false, reason: FULL_PAGE_UNSUPPORTED_MARKER }
-            : { ok: false, reason };
+        // Recognised markers are reported as the reason ITSELF, so the tool can branch on a closed
+        // vocabulary rather than on prose. Everything else keeps its own message: dressing an unknown
+        // failure up as a known one would send the reader to the wrong place entirely.
+        for (const marker of RECOGNISED_MARKERS) {
+            if (reason.includes(marker))
+                return { ok: false, reason: marker };
+        }
+        return { ok: false, reason };
     }
 }

package/dist/dom/refs.d.ts

@@ -31,8 +31,36 @@ export declare const MAX_TRACKED_REFS = 10000;
  * the message.
  */
 export declare function echoRef(ref: string): string;
+/**
+ * How many numbers a document claims at once.
+ *
+ * The reservation is a synchronous storage write, so it cannot happen per mint — mints are frequent
+ * (every meaningful DOM addition, every transitionend, every scroll reveal). One write per this many
+ * mints is free.
+ *
+ * Sized to keep refs SHORT, and the first attempt at that reasoned about the wrong axis. It bounded
+ * how many navigations it took to reach seven digits and concluded "a hundred" — but the cost is not
+ * paid at seven digits, it is paid at every digit, on every ref, in every snapshot and every error
+ * message, on every turn. At 10,000 the SECOND document already mints five-digit refs.
+ *
+ * Measured on one unchanged three-element page across a session: 61 tokens on the first document,
+ * 64 after a reload, 65 later — +6.5% for the same page, entirely in ref width. The benchmark saw the
+ * same thing as a ~4% rise in average observation cost, which is what a benchmark is for.
+ *
+ * So the block is small. A document claims another one when it outmints this, which costs one more
+ * storage write and is exactly proportional: a page with thousands of elements has a long snapshot
+ * anyway, and a small page — the common case, and the one an agent drives repeatedly — keeps
+ * three-digit refs across dozens of navigations.
+ */
+export declare const REF_BLOCK = 100;
 export declare class RefRegistry {
     #private;
+    /**
+     * Storage is injected rather than read from the global for the same reason the clock is: it is an
+     * ambient dependency that decides behaviour, and the cross-document property is untestable if the
+     * only way to get a second document is to actually navigate.
+     */
+    constructor(storage?: () => Storage | undefined);
     /** How many reverse entries are currently retained. Exposed so the bound can be asserted. */
     get size(): number;
     /** Get the existing ref for an element, or mint a new one. */

package/dist/dom/refs.js

@@ -44,11 +44,96 @@ export function echoRef(ref) {
  * over-cap mint, and the expensive dead-entry sweep runs once per this many mints (amortized O(1)).
  */
 const SWEEP_EVERY_MINTS = 1000;
+/**
+ * Where a document records the ref numbers it has claimed, so the next one starts past them.
+ *
+ * Refs are per-DOCUMENT: a reload or a cross-page link tears this module down and the next document
+ * used to start minting from `e1` again. So `e7` from page A was a valid, resolvable, DIFFERENT
+ * element on page B — nothing refused, the wrong element was acted on, and the result came back `ok`.
+ * The SPA case was always safe (WeakRef liveness + isConnected); this was the other half, and the
+ * more dangerous one, because it produced a false green instead of an error.
+ *
+ * Deliberately NOT a change to the ref grammar. Stamping refs `e7@3` would have worked too, but every
+ * agent passes refs back verbatim and every saved flow on disk already holds bare ones, so it buys a
+ * wire-format migration for a property the sequence itself can carry. A number that never restarts
+ * means a stale ref simply misses the map, and the refusal that already exists — already worded for
+ * exactly this case — fires unchanged.
+ *
+ * Namespaced like the session key it sits beside; `sessionStorage` is the right scope for the same
+ * reason session continuity uses it (survives reloads and same-tab navigations, not shared with
+ * another tab, which is a different session with its own registry anyway).
+ */
+const REF_BASE_KEY = '__reticle_ref_base';
+/**
+ * How many numbers a document claims at once.
+ *
+ * The reservation is a synchronous storage write, so it cannot happen per mint — mints are frequent
+ * (every meaningful DOM addition, every transitionend, every scroll reveal). One write per this many
+ * mints is free.
+ *
+ * Sized to keep refs SHORT, and the first attempt at that reasoned about the wrong axis. It bounded
+ * how many navigations it took to reach seven digits and concluded "a hundred" — but the cost is not
+ * paid at seven digits, it is paid at every digit, on every ref, in every snapshot and every error
+ * message, on every turn. At 10,000 the SECOND document already mints five-digit refs.
+ *
+ * Measured on one unchanged three-element page across a session: 61 tokens on the first document,
+ * 64 after a reload, 65 later — +6.5% for the same page, entirely in ref width. The benchmark saw the
+ * same thing as a ~4% rise in average observation cost, which is what a benchmark is for.
+ *
+ * So the block is small. A document claims another one when it outmints this, which costs one more
+ * storage write and is exactly proportional: a page with thousands of elements has a long snapshot
+ * anyway, and a small page — the common case, and the one an agent drives repeatedly — keeps
+ * three-digit refs across dozens of navigations.
+ */
+export const REF_BLOCK = 100;
+/** The reserved-block high-water mark, or 0 when storage is unavailable or its value is junk. */
+function readBase(store) {
+    try {
+        const raw = store?.getItem(REF_BASE_KEY);
+        const value = null === raw || undefined === raw ? Number.NaN : Number(raw);
+        return Number.isSafeInteger(value) && value > 0 ? value : 0;
+    }
+    catch {
+        return 0; // a sandboxed iframe throws on access; a session must still start
+    }
+}
 export class RefRegistry {
     #toRef = new WeakMap();
     #fromRef = new Map();
+    #storage;
     #seq = 0;
+    /** The end of the block currently reserved. Minting past it claims the next one. */
+    #reserved = 0;
     #mintsSinceSweep = 0;
+    /**
+     * Storage is injected rather than read from the global for the same reason the clock is: it is an
+     * ambient dependency that decides behaviour, and the cross-document property is untestable if the
+     * only way to get a second document is to actually navigate.
+     */
+    constructor(storage = () => globalThis.sessionStorage) {
+        this.#storage = storage;
+    }
+    /** Read the tab's high-water mark and claim the next block, BEFORE any of it is handed out. */
+    #reserve() {
+        let store;
+        try {
+            store = this.#storage();
+        }
+        catch {
+            store = undefined; // hostile storage: no cross-document guarantee, but the session still starts
+        }
+        const base = Math.max(readBase(store), this.#seq);
+        this.#reserved = base + REF_BLOCK;
+        try {
+            store?.setItem(REF_BASE_KEY, String(this.#reserved));
+        }
+        catch {
+            /* same: never block a mint on storage */
+        }
+        // Claimed on the FIRST mint, not at unload — a page that crashes, is killed, or navigates away
+        // without firing unload has still permanently spent its numbers.
+        this.#seq = base;
+    }
     /** How many reverse entries are currently retained. Exposed so the bound can be asserted. */
     get size() {
         return this.#fromRef.size;
@@ -85,6 +170,8 @@ export class RefRegistry {
             this.#fromRef.set(existing, weak ?? new WeakRef(el));
             return existing;
         }
+        if (this.#seq >= this.#reserved)
+            this.#reserve();
         this.#seq += 1;
         const ref = asRef(`e${String(this.#seq)}`);
         this.#toRef.set(el, ref);

package/dist/dom/theme.d.ts

@@ -1,25 +1,48 @@
 /**
  * Design-token (theme) awareness — the in-source answer to "is this color on-theme?". A DOM/a11y
  * tool sees a color rendered; it does not know the app's INTENDED palette. Reticle reads the design
- * tokens the app declares as `:root` CSS custom properties and reports, per element, whether its
- * color/background maps to a token or is an off-palette hardcoded value. That is a theme-compliance
- * signal no outside-the-page tool has without re-deriving the palette itself.
+ * tokens the app declares as CSS custom properties, resolves them AS THE PAGE CURRENTLY RENDERS
+ * THEM, and reports, per element, which tokens its color/background map to or whether the value is
+ * an off-palette hardcoded one. That is a theme-compliance signal no outside-the-page tool has
+ * without re-deriving the palette itself.
  *
  * Conservative by design: only a SET, opaque color with no matching token is flagged off-theme, and
- * the matched token name is returned when there is one — so the agent can judge, not just trust a flag.
+ * every matching token name is returned — so the agent can judge, not just trust a flag.
+ *
+ * Two defects made this field untrustworthy in BOTH directions before it was rewritten:
+ *   - the reverse map was color → ONE name, first writer wins, so a button styled with a brand token
+ *     was told its background was a focus-border token because the two resolve to the same hex. The
+ *     name is the part an agent reasons about, and it was arbitrary among the candidates.
+ *   - the palette was built from the RAW `:root` declaration text and cached for the page lifetime,
+ *     on the reasoning that a theme rarely changes at runtime. A human toggling the theme between
+ *     two inspect calls left every lookup keyed on the previous theme's colors, so a `<summary>` that
+ *     had just been changed to a text token reported a surface token. The reporter read that as their
+ *     edit not applying and went hunting for a theme-scope bug that did not exist.
+ * Hence: no cache, values resolved through `getComputedStyle` so the active theme wins, and the
+ * scope that was active at capture time reported alongside, so two results minutes apart are
+ * comparable at all.
  */
 interface ThemeReport {
-    /** Matched design-token name for the text color, or null when the color is off-palette. */
+    /**
+     * The ONE design token matching the text color, or null. Null both when nothing matches and when
+     * several tokens share the color: the previous behaviour picked an arbitrary winner and the caller
+     * could not tell, which is the whole defect. Read `colorTokens` for the full answer; this field
+     * stays for callers that only ever wanted the unambiguous case.
+     */
     colorToken: string | null;
-    /** Matched design-token name for the background color, or null. */
+    /** Every design token whose resolved value is the text color. Empty when the color is off-palette. */
+    colorTokens: string[];
+    /** The one design token matching the background color, or null (same abstain-on-tie rule). */
     backgroundToken: string | null;
-    /** True when a set, opaque color uses no design token — a theme violation worth surfacing. */
+    /** Every design token whose resolved value is the background color. */
+    backgroundTokens: string[];
+    /** True when a set, opaque color matches NO design token — a theme violation worth surfacing. */
     offTheme: boolean;
-    /** How many color tokens the app declared (0 ⇒ no palette found, so offTheme is never asserted). */
+    /** How many color tokens resolved under the active theme (0 ⇒ offTheme is never asserted). */
     tokenCount: number;
+    /** Theme scope active at capture time, e.g. `.dark`, so two results taken apart are comparable. */
+    themeScope: string | null;
 }
 /** Report an element's theme compliance from its computed style. */
 export declare function themeReport(cs: CSSStyleDeclaration): ThemeReport;
-/** Drop the cached palette (call if the app swaps themes at runtime). */
-export declare function resetThemeCache(): void;
 export {};

package/dist/dom/theme.js

@@ -1,33 +1,32 @@
 /**
  * Design-token (theme) awareness — the in-source answer to "is this color on-theme?". A DOM/a11y
  * tool sees a color rendered; it does not know the app's INTENDED palette. Reticle reads the design
- * tokens the app declares as `:root` CSS custom properties and reports, per element, whether its
- * color/background maps to a token or is an off-palette hardcoded value. That is a theme-compliance
- * signal no outside-the-page tool has without re-deriving the palette itself.
+ * tokens the app declares as CSS custom properties, resolves them AS THE PAGE CURRENTLY RENDERS
+ * THEM, and reports, per element, which tokens its color/background map to or whether the value is
+ * an off-palette hardcoded one. That is a theme-compliance signal no outside-the-page tool has
+ * without re-deriving the palette itself.
  *
  * Conservative by design: only a SET, opaque color with no matching token is flagged off-theme, and
- * the matched token name is returned when there is one — so the agent can judge, not just trust a flag.
+ * every matching token name is returned — so the agent can judge, not just trust a flag.
+ *
+ * Two defects made this field untrustworthy in BOTH directions before it was rewritten:
+ *   - the reverse map was color → ONE name, first writer wins, so a button styled with a brand token
+ *     was told its background was a focus-border token because the two resolve to the same hex. The
+ *     name is the part an agent reasons about, and it was arbitrary among the candidates.
+ *   - the palette was built from the RAW `:root` declaration text and cached for the page lifetime,
+ *     on the reasoning that a theme rarely changes at runtime. A human toggling the theme between
+ *     two inspect calls left every lookup keyed on the previous theme's colors, so a `<summary>` that
+ *     had just been changed to a text token reported a surface token. The reporter read that as their
+ *     edit not applying and went hunting for a theme-scope bug that did not exist.
+ * Hence: no cache, values resolved through `getComputedStyle` so the active theme wins, and the
+ * scope that was active at capture time reported alongside, so two results minutes apart are
+ * comparable at all.
  */
-let cached = null;
-/** Resolve any CSS color string to canonical computed `rgb...)`/`rgba...)`, or null if not a color. */
-function toRgb(value) {
-    if (0 === value.length)
-        return null;
-    const probe = document.createElement('span');
-    probe.style.color = '';
-    probe.style.color = value; // invalid colors leave it empty (the setter rejects them)
-    if ('' === probe.style.color)
-        return null;
-    probe.style.position = 'absolute';
-    probe.style.pointerEvents = 'none';
-    document.body.appendChild(probe);
-    const rgb = getComputedStyle(probe).color;
-    probe.remove();
-    return rgb;
-}
-/** Collect `--token: value` declarations from every:root/html rule across the app's stylesheets. */
-function collectTokens() {
-    const out = {};
+/** Attribute an app flips to switch themes, reported as part of the scope so results are comparable. */
+const THEME_ATTRIBUTE = 'data-theme';
+/** Collect every custom-property NAME the app declares, in any rule. */
+function tokenNames() {
+    const names = new Set();
     for (const sheet of Array.from(document.styleSheets)) {
         let rules = null;
         try {
@@ -41,49 +40,109 @@ function collectTokens() {
         for (const rule of Array.from(rules)) {
             if (!(rule instanceof CSSStyleRule))
                 continue;
-            if (!/(^|,)\s*(:root|html)\b/.test(rule.selectorText))
-                continue;
+            // Deliberately NOT filtered to `:root`/`html`: a theme block is usually `.dark` or
+            // `[data-theme="dark"]`, and an app that declares its palette only there had no palette at all
+            // under the old filter. Names are cheap; a name that is not in scope resolves to nothing below
+            // and is dropped, so widening collection cannot invent a token.
             for (const prop of Array.from(rule.style)) {
                 if (prop.startsWith('--'))
-                    out[prop] = rule.style.getPropertyValue(prop).trim();
+                    names.add(prop);
             }
         }
     }
-    return out;
+    return names;
 }
-/** The app's palette (color tokens → rgb), built once and cached (theme rarely changes at runtime). */
+/**
+ * The palette as the page renders it right now: canonical `rgb(...)` → every token with that color.
+ *
+ * Resolved against `document.body` rather than the raw declaration text, because custom properties
+ * inherit: this picks up a theme scoped to `<html>` or to `<body>`, and picks up the value the
+ * ACTIVE theme block won with rather than whichever block the stylesheet happened to list first.
+ */
 function palette() {
-    if (cached !== null)
-        return cached;
     const byColor = new Map();
-    for (const [name, value] of Object.entries(collectTokens())) {
-        const rgb = toRgb(value);
-        if (rgb !== null && !byColor.has(rgb))
-            byColor.set(rgb, name);
+    const root = document.body ?? document.documentElement;
+    if (null === root)
+        return byColor;
+    const rootStyle = getComputedStyle(root);
+    // One shared probe for the whole build. There is no cache any more, so this runs per inspect, and
+    // a span per token would be a few hundred appends on a real design system.
+    const probe = document.createElement('span');
+    probe.style.position = 'absolute';
+    probe.style.pointerEvents = 'none';
+    document.body.appendChild(probe);
+    try {
+        for (const name of tokenNames()) {
+            const rgb = toRgb(probe, rootStyle.getPropertyValue(name).trim());
+            if (null === rgb)
+                continue;
+            const named = byColor.get(rgb);
+            if (named === undefined)
+                byColor.set(rgb, [name]);
+            else
+                named.push(name);
+        }
+    }
+    finally {
+        probe.remove();
     }
-    cached = { byColor };
-    return cached;
+    // Sorted so the reported order is a property of the app's tokens, not of stylesheet iteration
+    // order — the same collision must read the same way on two consecutive inspects.
+    for (const named of byColor.values())
+        named.sort();
+    return byColor;
+}
+/** Resolve any CSS color string to canonical computed `rgb...)`/`rgba...)`, or null if not a color. */
+function toRgb(probe, value) {
+    if (0 === value.length)
+        return null;
+    probe.style.color = '';
+    probe.style.color = value; // invalid colors leave it empty (the setter rejects them)
+    if ('' === probe.style.color)
+        return null;
+    return getComputedStyle(probe).color;
 }
 /** True for a color that carries no visual weight (fully transparent) — never flagged off-theme. */
 function isTransparent(rgb) {
     return 'rgba(0, 0, 0, 0)' === rgb || 'transparent' === rgb;
 }
+/**
+ * The theme scope in force at capture time, as a selector-shaped string (`.dark[data-theme="dark"]`),
+ * or null when the root carries no theme marker at all.
+ */
+function themeScope() {
+    const el = document.documentElement;
+    if (null === el)
+        return null;
+    const classes = Array.from(el.classList)
+        .map((c) => `.${c}`)
+        .join('');
+    const attr = el.getAttribute(THEME_ATTRIBUTE);
+    const scope = `${classes}${null === attr ? '' : `[${THEME_ATTRIBUTE}="${attr}"]`}`;
+    return 0 === scope.length ? null : scope;
+}
+/** The unambiguous match, or null when the palette cannot tell the candidates apart. */
+function sole(names) {
+    return 1 === names.length ? (names[0] ?? null) : null;
+}
 /** Report an element's theme compliance from its computed style. */
 export function themeReport(cs) {
-    const p = palette();
-    const colorToken = p.byColor.get(cs.color) ?? null;
-    const backgroundToken = p.byColor.get(cs.backgroundColor) ?? null;
-    const colorOff = !isTransparent(cs.color) && null === colorToken;
-    const bgOff = !isTransparent(cs.backgroundColor) && null === backgroundToken;
+    const byColor = palette();
+    const colorTokens = byColor.get(cs.color) ?? [];
+    const backgroundTokens = byColor.get(cs.backgroundColor) ?? [];
+    const colorOff = !isTransparent(cs.color) && 0 === colorTokens.length;
+    const bgOff = !isTransparent(cs.backgroundColor) && 0 === backgroundTokens.length;
+    let tokenCount = 0;
+    for (const named of byColor.values())
+        tokenCount += named.length;
     return {
-        colorToken,
-        backgroundToken,
+        colorToken: sole(colorTokens),
+        colorTokens,
+        backgroundToken: sole(backgroundTokens),
+        backgroundTokens,
         // Only meaningful when a palette exists; an app with no tokens can't violate one.
-        offTheme: p.byColor.size > 0 && (colorOff || bgOff),
-        tokenCount: p.byColor.size,
+        offTheme: tokenCount > 0 && (colorOff || bgOff),
+        tokenCount,
+        themeScope: themeScope(),
     };
 }
-/** Drop the cached palette (call if the app swaps themes at runtime). */
-export function resetThemeCache() {
-    cached = null;
-}

package/dist/observers/console.js

@@ -1,5 +1,6 @@
 import { EventType, TRANSPORT_LIMITS } from '@reticlehq/core';
 import { safeStringify } from '../security/serialization.js';
+import { requireCapturedMethod } from '../util/captured-method.js';
 const METHOD_EVENT = {
     log: EventType.CONSOLE_LOG,
     warn: EventType.CONSOLE_WARN,
@@ -41,8 +42,10 @@ export function installConsole(emit) {
     const originals = new Map();
     const patched = new Map();
     for (const method of methods) {
-        // Store the true original for teardown identity; call through a bound copy.
-        const original = console[method];
+        // Store the true original for teardown identity; call through a bound copy. Read as a stored
+        // VALUE rather than a method reference — see capturedMethod for why that distinction is the
+        // honest way to say "I am detaching this deliberately and putting it back".
+        const original = requireCapturedMethod(console, method);
         originals.set(method, original);
         const callOriginal = original.bind(console);
         const wrapper = (...args) => {

package/dist/observers/network.js

@@ -3,6 +3,7 @@ import { captureMethod } from '../patching/capture-method.js';
 import { isCapturableType, projectBody, withBodyDeadline } from './network-body.js';
 import { redactUrl } from './network-redact.js';
 import { watchStreamedBody } from './network-stream.js';
+import { requireCapturedMethod } from '../util/captured-method.js';
 // Redaction moved to its own cohesive module (network.ts is at its line cap); re-exported so callers
 // and the existing test suite keep importing it from here.
 export { redactUrl };
@@ -195,7 +196,7 @@ export function installNetwork(emit, opts = {}) {
     const reinterpret = opts.reinterpret;
     // Keep the true original for teardown identity, plus a window-bound copy to invoke
     // (fetch throws "Illegal invocation" if called with the wrong `this`).
-    const origFetch = window.fetch;
+    const origFetch = requireCapturedMethod(window, 'fetch');
     const callFetch = origFetch.bind(window);
     // Declare it if we are not the first to wrap fetch.
     //
@@ -320,8 +321,9 @@ export function installNetwork(emit, opts = {}) {
         }
     };
     // Remember it, so a later install recognises our own wrapper instead of reporting the app.
-    OURS.add(window.fetch);
-    const patchedFetch = window.fetch;
+    // Our own wrapper, read the same way — it is a value we stored a line ago, not a method call.
+    const patchedFetch = requireCapturedMethod(window, 'fetch');
+    OURS.add(patchedFetch);
     const meta = new WeakMap();
     const proto = XMLHttpRequest.prototype;
     const origOpen = captureMethod(proto, 'open');

package/dist/registry/emitter.d.ts

@@ -6,8 +6,8 @@
  */
 /** Structural emitter the host app's components depend on. */
 export interface ReticleEmitter {
-    signal(name: string, data?: Record<string, unknown>): void;
-    state(name: string, value: unknown): void;
+    signal: (name: string, data?: Record<string, unknown>) => void;
+    state: (name: string, value: unknown) => void;
 }
 /** The subset of the reticle singleton an emitter proxies to (lets tests inject a fake). */
 export interface EmitterTarget {

package/dist/reticle.js

@@ -2,6 +2,7 @@ import { EventType, RETICLE_DEFAULT_PORT, RETICLE_PROTOCOL_VERSION, RETICLE_URL_
 import { rememberSessionLabel } from './session-continuity.js';
 import { createCommandRegistry, RELOAD_CACHE_BUST_PARAM, } from './commands/commands.js';
 import { Transport } from './transport/transport.js';
+import { unreachableMessage } from './transport/unreachable-message.js';
 import { adapterNames } from './registry/adapters.js';
 import { registerCapabilities, setCapabilitiesListener, hasCapabilities, } from './registry/capabilities.js';
 import { installAllObservers } from './observers/install-all.js';
@@ -228,13 +229,10 @@ export class Reticle {
                     this.#presenter.setState(SessionState.ENDED, BRIDGE_LOST_SUMMARY);
                 }
             },
-            // First-connect never succeeded ⇒ the bridge is unreachable at this URL. Tell the developer
-            // exactly what went wrong and how to fix it, instead of retrying silently forever.
+            // First-connect never succeeded ⇒ this page's socket is not opening at this URL. Say what the
+            // page observed rather than guessing at the daemon, which it cannot see from in here.
             onUnreachable: ({ url: tried, attempts }) => {
-                nativeWarn(`[Reticle] could not reach the bridge at ${tried} after ${String(attempts)} attempts. ` +
-                    `Is the Reticle daemon running on that port? If your app runs in a container/devcontainer/WSL, ` +
-                    `the daemon is on a different host — set the WS URL explicitly (Vite: VITE_RETICLE_WS_URL, ` +
-                    `or reticle.connect({ url })). Still retrying…`);
+                nativeWarn(unreachableMessage(tried, attempts));
             },
         });
         // Capabilities registered AFTER connect (which is when they are registered, by design) must

package/dist/timers/clock.js

@@ -2,6 +2,7 @@
 // can deterministically advance time (toasts, debounces, auto-dismiss, commit-on-blur).
 // We do NOT patch requestAnimationFrame/microtasks/MessageChannel — React's scheduler relies
 // on those, and freezing them would stall the page. Opt-in + reversible.
+import { requireCapturedMethod } from '../util/captured-method.js';
 let installed = false;
 let virtualNow = 0;
 let realBase = 0;
@@ -17,12 +18,14 @@ export function freezeClock() {
     installed = true;
     virtualNow = 0;
     realBase = Date.now();
+    // Captured as stored VALUES, so teardown restores the same function objects the page had. See
+    // capturedMethod: these are deliberate unbound captures and the descriptor read says so.
     originals = {
-        setTimeout: window.setTimeout,
-        clearTimeout: window.clearTimeout,
-        setInterval: window.setInterval,
-        clearInterval: window.clearInterval,
-        dateNow: Date.now,
+        setTimeout: requireCapturedMethod(window, 'setTimeout'),
+        clearTimeout: requireCapturedMethod(window, 'clearTimeout'),
+        setInterval: requireCapturedMethod(window, 'setInterval'),
+        clearInterval: requireCapturedMethod(window, 'clearInterval'),
+        dateNow: requireCapturedMethod(Date, 'now'),
     };
     const schedule = (cb, delay, interval) => {
         const id = seq;

package/dist/transport/unreachable-message.d.ts

@@ -0,0 +1,12 @@
+/**
+ * What the page says when its websocket never opened.
+ *
+ * Pulled out of the connect path so it is a pure string function with a test on its CLAIMS rather
+ * than a template inlined in a warn call. The rule it exists to hold: report what this page observed
+ * and what it could not determine, never a cause. See unreachable-message.test.ts.
+ */
+/**
+ * The page tried, failed, and cannot see why. Names the address and the attempt count, refuses to
+ * diagnose the daemon, and lists the checks in the order that actually resolves the ambiguity.
+ */
+export declare function unreachableMessage(url: string, attempts: number): string;

package/dist/transport/unreachable-message.js

@@ -0,0 +1,20 @@
+/**
+ * What the page says when its websocket never opened.
+ *
+ * Pulled out of the connect path so it is a pure string function with a test on its CLAIMS rather
+ * than a template inlined in a warn call. The rule it exists to hold: report what this page observed
+ * and what it could not determine, never a cause. See unreachable-message.test.ts.
+ */
+/**
+ * The page tried, failed, and cannot see why. Names the address and the attempt count, refuses to
+ * diagnose the daemon, and lists the checks in the order that actually resolves the ambiguity.
+ */
+export function unreachableMessage(url, attempts) {
+    return (`[Reticle] this page could not open a websocket to ${url}. ${String(attempts)} attempts, all ` +
+        `failed. That is everything the page can see: from inside the browser it cannot tell a daemon ` +
+        `that is not there from one it is not allowed to reach, so this is not evidence about the ` +
+        `daemon. What answers it: run \`npx @reticlehq/server status\` to see whether one is listening ` +
+        `and on which port. If your app runs in a container, devcontainer or WSL, the daemon is on a ` +
+        `different host, so set the URL explicitly (Vite: VITE_RETICLE_WS_URL, or ` +
+        `reticle.connect({ url })). An https page cannot open a ws:// socket at all. Still retrying…`);
+}

package/dist/util/captured-method.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Read a host object's method as a STORED VALUE, for code that has to put it back.
+ *
+ * Every observer here patches a global and must be able to undo it: `console.error`, `window.fetch`,
+ * `window.setTimeout`, `Date.now`. Undoing means holding the true original — the same function
+ * object, so teardown restores exactly what was there and a later install can recognise it by
+ * identity — and calling through a separately bound copy, because a host method invoked with the
+ * wrong receiver throws (`fetch` gives "Illegal invocation").
+ *
+ * Written as `const original = window.fetch`, that is a bare unbound method reference, and
+ * `@typescript-eslint/unbound-method` is right to flag the SHAPE even though this use is deliberate:
+ * the rule cannot see that the next line binds it, nor that the raw value only ever goes back into
+ * the slot it came from.
+ *
+ * The two obvious ways out are both wrong here. An `eslint-disable` is against this repo's standing
+ * rule and hides the shape from every future reader. Annotating `this: void` asserts the function
+ * does not use its receiver — which for a console method or `fetch` is simply false, and is the very
+ * reason the binding exists.
+ *
+ * So the intent is expressed instead of suppressed. A property descriptor's `value` is a stored
+ * value, not a method being detached from its object, which is exactly the distinction the rule is
+ * drawing and exactly what this code wants. It is also strictly more accurate for the restore case:
+ * it reads what the slot HOLDS rather than what calling the property would do, so an accessor
+ * defined on the object cannot be silently flattened into its result.
+ *
+ * Returns undefined when the property is absent or inherited rather than own — a caller that needs a
+ * fallback to the prototype chain should say so at its own call site rather than have it hidden here.
+ */
+export declare function capturedMethod<T>(target: object, key: PropertyKey): T | undefined;
+/**
+ * The same, for a property this code knows is present — the globals every observer patches.
+ *
+ * Throws rather than returning a broken teardown. A missing `window.fetch` is not a condition any
+ * caller here can recover from, and silently installing a patch that cannot be undone is worse than
+ * refusing: the page keeps the wrapper for the rest of its life with nothing able to remove it.
+ */
+export declare function requireCapturedMethod<T>(target: object, key: PropertyKey): T;

package/dist/util/captured-method.js

@@ -0,0 +1,45 @@
+/**
+ * Read a host object's method as a STORED VALUE, for code that has to put it back.
+ *
+ * Every observer here patches a global and must be able to undo it: `console.error`, `window.fetch`,
+ * `window.setTimeout`, `Date.now`. Undoing means holding the true original — the same function
+ * object, so teardown restores exactly what was there and a later install can recognise it by
+ * identity — and calling through a separately bound copy, because a host method invoked with the
+ * wrong receiver throws (`fetch` gives "Illegal invocation").
+ *
+ * Written as `const original = window.fetch`, that is a bare unbound method reference, and
+ * `@typescript-eslint/unbound-method` is right to flag the SHAPE even though this use is deliberate:
+ * the rule cannot see that the next line binds it, nor that the raw value only ever goes back into
+ * the slot it came from.
+ *
+ * The two obvious ways out are both wrong here. An `eslint-disable` is against this repo's standing
+ * rule and hides the shape from every future reader. Annotating `this: void` asserts the function
+ * does not use its receiver — which for a console method or `fetch` is simply false, and is the very
+ * reason the binding exists.
+ *
+ * So the intent is expressed instead of suppressed. A property descriptor's `value` is a stored
+ * value, not a method being detached from its object, which is exactly the distinction the rule is
+ * drawing and exactly what this code wants. It is also strictly more accurate for the restore case:
+ * it reads what the slot HOLDS rather than what calling the property would do, so an accessor
+ * defined on the object cannot be silently flattened into its result.
+ *
+ * Returns undefined when the property is absent or inherited rather than own — a caller that needs a
+ * fallback to the prototype chain should say so at its own call site rather than have it hidden here.
+ */
+export function capturedMethod(target, key) {
+    return Object.getOwnPropertyDescriptor(target, key)?.value;
+}
+/**
+ * The same, for a property this code knows is present — the globals every observer patches.
+ *
+ * Throws rather than returning a broken teardown. A missing `window.fetch` is not a condition any
+ * caller here can recover from, and silently installing a patch that cannot be undone is worse than
+ * refusing: the page keeps the wrapper for the rest of its life with nothing able to remove it.
+ */
+export function requireCapturedMethod(target, key) {
+    const value = capturedMethod(target, key);
+    if (value === undefined) {
+        throw new Error(`[Reticle] cannot patch ${String(key)}: it is not an own property of the target`);
+    }
+    return value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/browser",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Reticle browser SDK — installs observers, builds semantic snapshots, executes actions, talks to the bridge.",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,13 +14,13 @@
   },
   "dependencies": {
     "@testing-library/dom": "^10.4.1",
-    "@reticlehq/core": "2.7.0"
+    "@reticlehq/core": "2.8.0"
   },
   "devDependencies": {
     "@tanstack/query-core": "^5.101.4",
-    "@types/jsdom": "^28.0.3",
+    "@types/jsdom": "^30.0.0",
     "jotai": "^2.20.2",
-    "jsdom": "^29.1.1",
+    "jsdom": "^30.0.1",
     "mobx": "^7.0.0",
     "pinia": "^4.0.2",
     "react": "^19.2.8",