@reticlehq/browser 2.6.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/actions/actions-dom.d.ts

@@ -30,6 +30,10 @@ export declare function firePointerNonBubbling(el: Element, type: string, relate
 /**
  * Pointer-based drag (dnd-kit / react-beautiful-dnd) + best-effort HTML5 DnD. Async: yields a
  * frame between phases so React commits state between steps (fixes stale-closure handlers).
+ *
+ * Dispatches along a PATH with real client coordinates and a held button. Without those a
+ * geometry-based library resolves the drop target as the source, so the action reports success over
+ * an app that did not change — a false green produced by the tool rather than caught by it.
  */
 export declare function dragElement(source: HTMLElement, target: HTMLElement | null, data: unknown): Promise<boolean>;
 export {};

package/dist/actions/actions-dom.js

@@ -109,28 +109,77 @@ function makeDataTransfer(data) {
     }
     return dt;
 }
+/** `buttons` bitmask for the primary button: 1 while held, 0 once released. */
+const BUTTON_HELD = 1;
+const BUTTON_RELEASED = 0;
+/**
+ * How many intermediate moves a drag emits.
+ *
+ * Enough to cross any realistic `activationConstraint: { distance: N }` while a sensor is watching,
+ * and few enough that a drag stays a handful of frames rather than an animation.
+ */
+const DRAG_STEPS = 5;
+/** The centre of an element in client coordinates — what a real pointer would be over. */
+function centreOf(el) {
+    const box = el.getBoundingClientRect();
+    return { x: box.left + box.width / 2, y: box.top + box.height / 2 };
+}
+/** A point `t` of the way from `a` to `b`, rounded — pointer coordinates are integers in practice. */
+function lerp(a, b, t) {
+    return { x: Math.round(a.x + (b.x - a.x) * t), y: Math.round(a.y + (b.y - a.y) * t) };
+}
 /**
  * Pointer-based drag (dnd-kit / react-beautiful-dnd) + best-effort HTML5 DnD. Async: yields a
  * frame between phases so React commits state between steps (fixes stale-closure handlers).
+ *
+ * Dispatches along a PATH with real client coordinates and a held button. Without those a
+ * geometry-based library resolves the drop target as the source, so the action reports success over
+ * an app that did not change — a false green produced by the tool rather than caught by it.
  */
 export async function dragElement(source, target, data) {
     const dest = target ?? source;
-    const fire = (el, type) => {
+    const from = centreOf(source);
+    const to = centreOf(dest);
+    /**
+     * Dispatch ONE pointer/mouse pair with real coordinates and button state.
+     *
+     * Everything here was missing before, and each omission breaks a different, standard library
+     * pattern: without coordinates a geometry-based collision resolver sees a zero delta and reports
+     * the source as its own drop target; without `buttons: 1` the usual "was the mouse released?"
+     * guard (`event.buttons === 0`) bails out mid-drag.
+     */
+    const fire = (el, type, at, buttons) => {
+        const init = {
+            bubbles: true,
+            cancelable: true,
+            clientX: at.x,
+            clientY: at.y,
+            screenX: at.x,
+            screenY: at.y,
+            buttons,
+            button: 0,
+        };
         if ('function' === typeof PointerEvent && type.startsWith('pointer')) {
-            el.dispatchEvent(new PointerEvent(type, { bubbles: true, cancelable: true }));
+            el.dispatchEvent(new PointerEvent(type, { ...init, pointerId: 1, isPrimary: true }));
         }
         else {
-            el.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true }));
+            el.dispatchEvent(new MouseEvent(type, init));
         }
     };
-    fire(source, 'pointerdown');
-    fire(source, 'mousedown');
+    fire(source, 'pointerdown', from, BUTTON_HELD);
+    fire(source, 'mousedown', from, BUTTON_HELD);
     await nativeFrame();
-    fire(dest, 'pointermove');
-    fire(dest, 'mousemove');
-    await nativeFrame();
-    fire(dest, 'pointerup');
-    fire(dest, 'mouseup');
+    // A path, not a jump. `activationConstraint: { distance: N }` is the standard way to keep a
+    // draggable card clickable, and a sensor only starts a drag once it has SEEN the pointer travel
+    // that far — which a single move from A to B never shows it.
+    for (let step = 1; step <= DRAG_STEPS; step += 1) {
+        const at = lerp(from, to, step / DRAG_STEPS);
+        fire(dest, 'pointermove', at, BUTTON_HELD);
+        fire(dest, 'mousemove', at, BUTTON_HELD);
+        await nativeFrame();
+    }
+    fire(dest, 'pointerup', to, BUTTON_RELEASED);
+    fire(dest, 'mouseup', to, BUTTON_RELEASED);
     let dropPrevented = false;
     if ('function' === typeof DragEvent) {
         const dataTransfer = makeDataTransfer(data);

package/dist/actions/actions.js

@@ -112,13 +112,112 @@ function dangerousActionContext(el) {
 function requiresDangerousConfirmation(text) {
     return isDangerousActionText(text);
 }
+/**
+ * Which key a `press` is asking for.
+ *
+ * `text` FIRST, because that is what the tool description documents ("{ text } for type/press") and
+ * therefore what agents send. The implementation read only `args['key']` and defaulted to `'Enter'`,
+ * so the documented call — `press` with `{ text: 'Escape' }` — silently dispatched **Enter** and
+ * reported success. Two field reports blamed "synthetic events not reaching the app"; the events
+ * arrived perfectly and said the wrong thing.
+ *
+ * Enter is the worst possible substitute to pick by accident: on a focused field inside a form it
+ * SUBMITS it, so a request to dismiss a dialog could file the form behind it. `key` still works —
+ * it is what anyone reading the source would have sent — and the default only applies when neither
+ * was named.
+ */
+function pressKey(args) {
+    const text = args['text'];
+    if ('string' === typeof text && text.length > 0)
+        return text;
+    return asString(args['key'], 'Enter');
+}
+/**
+ * The PHYSICAL key identity — `event.code` — derived from the logical key.
+ *
+ * A real browser always sends both, and a meaningful class of library reads only `code`, because it
+ * is the layout-independent one: dnd-kit's KeyboardSensor matches its activation and arrow keys on
+ * it, and so does react-aria. We sent `key` alone, so those handlers simply never matched — the
+ * event fired, the listener ran, the guard failed, and the action reported dispatched over an app
+ * that did nothing. Reported from the field as a keyboard drag that could be neither started nor
+ * steered.
+ *
+ * An explicit `code` always wins: a caller driving a non-US layout knows something this derivation
+ * cannot. And an unrecognised multi-character key yields `''` rather than a guess — a wrong `code`
+ * is worse than none, because a handler will act on it.
+ */
+function pressCode(args, key) {
+    const explicit = args['code'];
+    if ('string' === typeof explicit && explicit.length > 0)
+        return explicit;
+    if (' ' === key)
+        return 'Space';
+    if (1 === key.length) {
+        if (/[a-z]/i.test(key))
+            return `Key${key.toUpperCase()}`;
+        if (/[0-9]/.test(key))
+            return `Digit${key}`;
+        return '';
+    }
+    // Named keys — 'Enter', 'Escape', 'Tab', 'ArrowDown' — already ARE their own code.
+    return /^[A-Z][A-Za-z0-9]*$/.test(key) && KNOWN_NAMED_KEYS.has(key) ? key : '';
+}
+/**
+ * Named keys whose `code` equals their `key`. An allow-list rather than a shape test: `Zzz` looks
+ * exactly like `Tab` to a regex, and inventing `code: "Zzz"` would be a confident fabrication.
+ */
+const KNOWN_NAMED_KEYS = new Set([
+    'Enter',
+    'Escape',
+    'Tab',
+    'Backspace',
+    'Delete',
+    'Home',
+    'End',
+    'PageUp',
+    'PageDown',
+    'ArrowUp',
+    'ArrowDown',
+    'ArrowLeft',
+    'ArrowRight',
+    'Insert',
+    'F1',
+    'F2',
+    'F3',
+    'F4',
+    'F5',
+    'F6',
+    'F7',
+    'F8',
+    'F9',
+    'F10',
+    'F11',
+    'F12',
+]);
+/**
+ * The drop target a `drag` names, under either spelling.
+ *
+ * `toRef` is what the source has always read and it appears NOWHERE in the tool description an
+ * agent sees — the `args` sentence names `value`, `text`, `native`, `holdMs` and `confirmDangerous`
+ * and omits the one argument without which this action cannot do its job. So agents guess, and
+ * `target` is the guess they make. Accepting it costs nothing and removes a whole class of
+ * silently-target-less drags; the description now documents `toRef` as well.
+ */
+function dragTargetRef(args) {
+    const named = asString(args['toRef']);
+    return '' !== named ? named : asString(args['target']);
+}
 function assertActionAllowed(el, action, args) {
     const canTrigger = action === ActionType.CLICK ||
         action === ActionType.DBLCLICK ||
         action === ActionType.DRAG ||
         action === ActionType.SUBMIT ||
-        (action === ActionType.PRESS && 'Enter' === asString(args['key'], 'Enter'));
-    const dragTarget = action === ActionType.DRAG ? refs.resolve(asString(args['toRef'])) : null;
+        // Read through the SAME resolver as the dispatch below. Reading a different argument here meant
+        // the destructive-action guard classified the call by a key nobody had asked for.
+        (action === ActionType.PRESS && 'Enter' === pressKey(args));
+    // Same resolver as the dispatch below, so the destructive-action guard cannot classify a drag
+    // by a target the dispatch will not use.
+    const dragTarget = action === ActionType.DRAG ? refs.resolve(dragTargetRef(args)) : null;
     const context = isHtmlElement(dragTarget)
         ? `${dangerousActionContext(el)} ${dangerousActionContext(dragTarget)}`
         : dangerousActionContext(el);
@@ -304,13 +403,39 @@ async function dispatchOther(el, action, args) {
             }
             throw new Error(`cannot select on a <${el.tagName.toLowerCase()}>`);
         case ActionType.CHECK:
-        case ActionType.UNCHECK:
-            if (isInput(el)) {
-                el.checked = action === ActionType.CHECK;
-                el.dispatchEvent(new Event('change', { bubbles: true }));
+        case ActionType.UNCHECK: {
+            if (!isInput(el))
+                throw new Error(`cannot (un)check a <${el.tagName.toLowerCase()}>`);
+            // Same rule as the readonly/disabled refusal on fill: if a real user could not do it, forcing
+            // it is not a test, it is damage — and a green over it is a false one.
+            if (!enabledOf(el)) {
+                throw new Error(`cannot ${action} a disabled control — a real user could not, so neither will Reticle`);
+            }
+            const wanted = action === ActionType.CHECK;
+            // Already there: report success and touch nothing. `check` means "end up checked", not
+            // "toggle", so clicking here would flip it OFF and hand the app an event no user produced.
+            if (el.checked === wanted)
                 return false;
+            // `click()`, never `el.checked = …`. Assigning the property flips the pixel and tells no
+            // framework: React binds a checkbox's onChange to the CLICK event, and its value tracker
+            // dedups the change it would otherwise synthesise from a direct assignment — so a controlled
+            // `checked={state}` box never heard from us while the action reported success. `click()` is
+            // the one DOM call that runs the element's ACTIVATION BEHAVIOUR (the native toggle) as well
+            // as firing the event; `dispatchEvent` does not.
+            let prevented = false;
+            // On window, so it runs after every listener on the element itself whenever they were added.
+            const probe = (e) => {
+                prevented = e.defaultPrevented;
+            };
+            window.addEventListener('click', probe, { once: true, capture: false });
+            try {
+                el.click();
+            }
+            finally {
+                window.removeEventListener('click', probe, false);
             }
-            throw new Error(`cannot (un)check a <${el.tagName.toLowerCase()}>`);
+            return prevented;
+        }
         case ActionType.SUBMIT: {
             const form = isForm(el) ? el : el.closest('form');
             if (null === form)
@@ -319,9 +444,10 @@ async function dispatchOther(el, action, args) {
             return false; // requestSubmit returns void; the internal submit event is unobservable.
         }
         case ActionType.PRESS: {
-            const key = asString(args['key'], 'Enter');
-            const down = el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }));
-            el.dispatchEvent(new KeyboardEvent('keyup', { key, bubbles: true }));
+            const key = pressKey(args);
+            const code = pressCode(args, key);
+            const down = el.dispatchEvent(new KeyboardEvent('keydown', { key, code, bubbles: true, cancelable: true }));
+            el.dispatchEvent(new KeyboardEvent('keyup', { key, code, bubbles: true }));
             return !down;
         }
         case ActionType.SCROLL_INTO_VIEW:
@@ -342,11 +468,21 @@ async function dispatchOther(el, action, args) {
             return !inputOk;
         }
         case ActionType.DRAG: {
-            const toRef = asString(args['toRef']);
+            const toRef = dragTargetRef(args);
             // asString falls back to '' (never undefined), so the old `!== undefined` was always true and
-            // handed '' to refs.resolve. A drag with no target ref is a free drag — resolve nothing.
-            const resolved = toRef !== '' ? refs.resolve(toRef) : null;
-            return await dragElement(el, isHtmlElement(resolved) ? resolved : null, args['data']);
+            // handed '' to refs.resolve. A drag with NO target named is a free drag — resolve nothing.
+            if ('' === toRef)
+                return await dragElement(el, null, args['data']);
+            // A target WAS named and did not resolve. That is a malformed call, not a free drag: dragging
+            // nowhere and reporting `ok: true` is a false green, and it is the one this action produced
+            // in the field — the drop target argument is undocumented, the agent guessed a name, the guess
+            // read as "no target", and the drag landed nowhere while every effect field looked healthy.
+            const resolved = refs.resolve(toRef);
+            if (!isHtmlElement(resolved)) {
+                throw new Error(`drag target '${echoRef(toRef)}' did not resolve to an element — pass a ref from ` +
+                    'reticle_snapshot or reticle_query as args.toRef (alias: args.target)');
+            }
+            return await dragElement(el, resolved, args['data']);
         }
         default:
             throw new Error(`unknown action '${action}'`);

package/dist/commands/commands.js

@@ -48,6 +48,11 @@ function queryFromArgs(args) {
         alt: str(args['alt']),
         component: str(args['component']),
         scope: str(args['scope']),
+        // The THIRD allowlist a query input has to appear in — tool schema, server forward, and here.
+        // `self` was in the first two and missing from this one, so a live call returned zero matches on
+        // an element that was plainly on the page, with no error to explain it. Same shape as the
+        // `attrs` drop below it.
+        self: true === args['self'] ? true : undefined,
         attrs: Array.isArray(args['attrs'])
             ? args['attrs'].filter((a) => 'string' === typeof a)
             : undefined,
@@ -86,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 } : {}),
@@ -98,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/query.js

@@ -259,6 +259,16 @@ function findCandidates(query) {
     // scopeMissing flag is what keeps "gone scope" distinct from "absent element".
     if (null === container)
         return { candidates: [], scopeMissing: true };
+    // `self: true` asks for the container ITSELF, which every other path excludes by construction.
+    // A layout element with no role, name, testid or own text is unreachable by any semantic locator,
+    // and it is routinely the element carrying the handler — "click the empty space in this row" is a
+    // real user action that was simply not expressible. Requires a scope: without one there is no root
+    // to return, and answering `document.body` would be a wrong answer wearing the shape of one.
+    if (true === query.self) {
+        if (query.scope === undefined)
+            return { candidates: [], scopeMissing };
+        return { candidates: isIgnored(container) ? [] : [container], scopeMissing };
+    }
     const seen = new Set();
     const out = [];
     const collect = (els) => {

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');
@@ -449,6 +451,10 @@ export function installNetwork(emit, opts = {}) {
                     });
                 });
             }
+            // `override` is required, not decorative: this shadows WebSocket.prototype.send, and without
+            // the keyword a rename or signature drift in the base class would silently turn this from an
+            // override into a NEW method — the observer would stop intercepting and report no WebSocket
+            // traffic at all, which reads as "the app sends none". Caught by noImplicitOverride.
             send(data) {
                 if (this.#isBridge) {
                     super.send(data);

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';
@@ -160,7 +161,7 @@ export class Reticle {
         // Dev-only backstop: refuse to activate in a production build (SSR healthcheck, prod bundle opened
         // on localhost). `process` may not exist in a raw browser, so read NODE_ENV off globalThis.
         const proc = globalThis.process;
-        const nodeEnv = proc?.env?.NODE_ENV;
+        const nodeEnv = proc?.env?.['NODE_ENV'];
         if (shouldBlockProduction(nodeEnv, true === options.allowInProduction)) {
             globalThis.console.warn('[Reticle] disabled in production (NODE_ENV=production). Gate the import behind ' +
                 'import.meta.env.DEV, or pass allowInProduction:true to override.');
@@ -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.6.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.6.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",