@reticlehq/browser 2.13.1 → 3.1.0

package/dist/observers/console.js

@@ -1,12 +1,11 @@
 import { EventType, TRANSPORT_LIMITS } from '@reticlehq/core';
+import { observeSafely } from './types.js';
 import { safeStringify } from '../security/serialization.js';
 import { requireCapturedMethod } from '../util/captured-method.js';
 const METHOD_EVENT = {
     log: EventType.CONSOLE_LOG,
     warn: EventType.CONSOLE_WARN,
     error: EventType.CONSOLE_ERROR,
-    // info/debug are captured for the raw console channel but excluded from summaries/deviation reports
-    // (low signal — most apps chatter here). Lean: no stack, like log/warn.
     info: EventType.CONSOLE_INFO,
     debug: EventType.CONSOLE_DEBUG,
 };
@@ -21,14 +20,12 @@ function stringifyArgs(args) {
     })
         .join(' ');
 }
-/** Stacks can be long; cap so a deep async trace never blows the event budget. */
 const MAX_STACK_LEN = TRANSPORT_LIMITS.MAX_STACK_LENGTH;
 function capStack(stack) {
     if (stack === undefined || 0 === stack.length)
         return undefined;
     return stack.length > MAX_STACK_LEN ? stack.slice(0, MAX_STACK_LEN) : stack;
 }
-/** The stack of the first Error argument, if any — the single biggest diagnosis upgrade, near-zero cost. */
 function firstErrorStack(args) {
     for (const arg of args) {
         if (arg instanceof Error)
@@ -36,58 +33,72 @@ function firstErrorStack(args) {
     }
     return undefined;
 }
-/** Patch console.{log,warn,error} and window error events. Reversible. */
 export function installConsole(emit) {
     const methods = ['log', 'warn', 'error', 'info', 'debug'];
     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. 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) => {
-            // Only console.error carries a stack — the diagnosis case; log/warn stay lean.
-            const stack = 'error' === method ? firstErrorStack(args) : undefined;
-            emit(METHOD_EVENT[method], {
-                message: stringifyArgs(args),
-                ...(stack === undefined ? {} : { stack }),
-            });
             callOriginal(...args);
+            observeSafely(() => {
+                const stack = 'error' === method ? firstErrorStack(args) : undefined;
+                emit(METHOD_EVENT[method], {
+                    message: stringifyArgs(args),
+                    ...(stack === undefined ? {} : { stack }),
+                });
+            });
         };
         patched.set(method, wrapper);
         console[method] = wrapper;
     }
     const onError = (event) => {
-        const stack = capStack(event.error instanceof Error ? event.error.stack : undefined);
-        emit(EventType.ERROR_UNCAUGHT, {
-            message: event.message,
-            source: event.filename,
-            line: event.lineno,
-            ...(stack === undefined ? {} : { stack }),
+        if (!(event instanceof ErrorEvent)) {
+            const target = event.target;
+            if (!(target instanceof Element) || target === document)
+                return;
+            const tag = target.tagName.toLowerCase();
+            const url = target.getAttribute('src') ?? target.getAttribute('href') ?? '';
+            observeSafely(() => {
+                emit(EventType.ERROR_UNCAUGHT, {
+                    message: `<${tag}> failed to load${0 === url.length ? '' : `: ${url}`}`,
+                    kind: 'resource',
+                    ...(0 === url.length ? {} : { source: url }),
+                });
+            });
+            return;
+        }
+        observeSafely(() => {
+            const stack = capStack(event.error instanceof Error ? event.error.stack : undefined);
+            emit(EventType.ERROR_UNCAUGHT, {
+                message: event.message,
+                source: event.filename,
+                line: event.lineno,
+                ...(stack === undefined ? {} : { stack }),
+            });
         });
     };
     const onRejection = (event) => {
-        const reason = event.reason;
-        const stack = capStack(reason instanceof Error ? reason.stack : undefined);
-        emit(EventType.ERROR_UNCAUGHT, {
-            message: reason instanceof Error ? reason.message : String(reason),
-            kind: 'unhandledrejection',
-            ...(stack === undefined ? {} : { stack }),
+        observeSafely(() => {
+            const reason = event.reason;
+            const stack = capStack(reason instanceof Error ? reason.stack : undefined);
+            emit(EventType.ERROR_UNCAUGHT, {
+                message: reason instanceof Error ? reason.message : String(reason),
+                kind: 'unhandledrejection',
+                ...(stack === undefined ? {} : { stack }),
+            });
         });
     };
-    window.addEventListener('error', onError);
+    window.addEventListener('error', onError, true);
     window.addEventListener('unhandledrejection', onRejection);
     return () => {
         for (const [method, original] of originals) {
-            // Restore only if console[method] still holds our wrapper — a logging SDK (Sentry, LogRocket)
-            // that wrapped console AFTER connect() must keep its instrumentation on teardown.
             if (console[method] === patched.get(method))
                 console[method] = original;
         }
-        window.removeEventListener('error', onError);
+        window.removeEventListener('error', onError, true);
         window.removeEventListener('unhandledrejection', onRejection);
     };
 }

package/dist/observers/context-open.d.ts

@@ -1,12 +1,2 @@
-import type { Emit, Teardown } from './types.js';
-/**
- * The page asked for ANOTHER browsing context — `window.open` — so the consequence of whatever was
- * just clicked may live where this document's SDK cannot follow. An OAuth sign-in is the archetype:
- * the POST succeeds, the popup carries the whole flow, and the original tab legitimately never
- * changes (#508). Without this event the contradiction layer reads that shape as response-ignored,
- * accusing the client of ignoring a response it handed to a window nobody can see.
- *
- * The wrap preserves the call exactly: same arguments, same return value, and a null/undefined
- * first argument (the "open a blank tab" form) still emits, since a blank tab can navigate anywhere.
- */
+import { type Emit, type Teardown } from './types.js';
 export declare function installContextOpen(emit: Emit): Teardown;

package/dist/observers/context-open.js

@@ -1,25 +1,21 @@
 import { EventType } from '@reticlehq/core';
 import { captureMethod } from '../patching/capture-method.js';
-/**
- * The page asked for ANOTHER browsing context — `window.open` — so the consequence of whatever was
- * just clicked may live where this document's SDK cannot follow. An OAuth sign-in is the archetype:
- * the POST succeeds, the popup carries the whole flow, and the original tab legitimately never
- * changes (#508). Without this event the contradiction layer reads that shape as response-ignored,
- * accusing the client of ignoring a response it handed to a window nobody can see.
- *
- * The wrap preserves the call exactly: same arguments, same return value, and a null/undefined
- * first argument (the "open a blank tab" form) still emits, since a blank tab can navigate anywhere.
- */
+import { observeSafely } from './types.js';
 export function installContextOpen(emit) {
     const originalOpen = captureMethod(window, 'open');
     if (originalOpen === undefined)
         return () => { };
     const openPatch = function (href, target, features) {
-        emit(EventType.CONTEXT_OPENED, { ...(href === undefined ? {} : { href }) });
-        return originalOpen.call(this, href, target, features);
+        const opened = originalOpen.call(this, href, target, features);
+        observeSafely(() => {
+            emit(EventType.CONTEXT_OPENED, { ...(href === undefined ? {} : { href }) });
+        });
+        return opened;
     };
-    window.open = openPatch;
+    const patchedOpen = openPatch;
+    window.open = patchedOpen;
     return () => {
-        window.open = originalOpen;
+        if (window.open === patchedOpen)
+            window.open = originalOpen;
     };
 }

package/dist/observers/departure.d.ts

@@ -0,0 +1,3 @@
+import { type Emit, type Teardown } from './types.js';
+export declare function isDeparture(href: string, downloadAttr: boolean, here: string): boolean;
+export declare function installDeparture(emit: Emit): Teardown;

package/dist/observers/departure.js

@@ -0,0 +1,52 @@
+import { EventType, NetInitiator } from '@reticlehq/core';
+import { observeSafely } from './types.js';
+const NON_NAVIGATING = /^(javascript|mailto|tel|sms|blob|data):/i;
+function anchorFor(target) {
+    if (!(target instanceof Element))
+        return undefined;
+    const anchor = target.closest('a');
+    return anchor instanceof HTMLAnchorElement ? anchor : undefined;
+}
+export function isDeparture(href, downloadAttr, here) {
+    if (0 === href.length || NON_NAVIGATING.test(href))
+        return false;
+    if (downloadAttr)
+        return true;
+    try {
+        const target = new URL(href, here);
+        const current = new URL(here);
+        if (target.origin === current.origin) {
+            return target.pathname !== current.pathname || target.search !== current.search;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function installDeparture(emit) {
+    if ('undefined' === typeof document)
+        return () => undefined;
+    let seq = 0;
+    const onClick = (event) => {
+        observeSafely(() => {
+            const anchor = anchorFor(event.target);
+            if (anchor === undefined)
+                return;
+            const href = anchor.getAttribute('href') ?? '';
+            const here = document.location.href;
+            if (!isDeparture(href, anchor.hasAttribute('download'), here))
+                return;
+            seq += 1;
+            emit(EventType.NET_PENDING, {
+                id: `nav-${String(seq)}`,
+                method: 'GET',
+                url: new URL(href, here).toString(),
+                initiator: NetInitiator.NAVIGATION,
+                ...(anchor.hasAttribute('download') ? { download: true } : {}),
+            });
+        });
+    };
+    document.addEventListener('click', onClick, true);
+    return () => document.removeEventListener('click', onClick, true);
+}

package/dist/observers/dialogs.d.ts

@@ -0,0 +1,2 @@
+import { type Emit, type Teardown } from './types.js';
+export declare function installDialogs(emit: Emit): Teardown;

package/dist/observers/dialogs.js

@@ -0,0 +1,39 @@
+import { EventType } from '@reticlehq/core';
+import { observeSafely } from './types.js';
+import { isSyntheticInput } from '../actions/synthetic/synthetic-input.js';
+const DECLINED = { alert: undefined, confirm: false, prompt: null };
+const KINDS = ['alert', 'confirm', 'prompt'];
+export function installDialogs(emit) {
+    const slots = window;
+    const originals = new Map();
+    const patched = new Map();
+    for (const kind of KINDS) {
+        const original = slots[kind];
+        if ('function' !== typeof original)
+            continue;
+        originals.set(kind, original);
+        const callOriginal = original.bind(window);
+        const wrapper = (...args) => {
+            if (!isSyntheticInput())
+                return callOriginal(...args);
+            const answered = DECLINED[kind];
+            const message = args[0];
+            observeSafely(() => {
+                emit(EventType.DIALOG_OPENED, {
+                    kind,
+                    ...('string' === typeof message ? { message } : {}),
+                    ...(answered === undefined ? {} : { answered }),
+                });
+            });
+            return answered;
+        };
+        patched.set(kind, wrapper);
+        slots[kind] = wrapper;
+    }
+    return () => {
+        for (const [kind, original] of originals) {
+            if (slots[kind] === patched.get(kind))
+                slots[kind] = original;
+        }
+    };
+}

package/dist/observers/dom.js

@@ -1,12 +1,6 @@
 import { EventType, TruncationChannel } from '@reticlehq/core';
 import { getAccessibleName, getRole, isVisible } from '../dom/a11y.js';
-import { refs } from '../dom/refs.js';
-/**
- * A STABLE identity for the region a mutation happened in. Ambient learning cannot key on the element
- * ref for a churning list: every appended row is a NEW element (fresh ref) and a removed one has no ref
- * at all, so per-ref counts never accumulate and the region is never recognized as ambient. The
- * container persists across ticks, so its testid (or ref) is the identity that does accumulate.
- */
+import { refs } from '../dom/addressing/refs.js';
 function regionKeyOf(target) {
     const el = isElement(target) ? target : null;
     if (null === el)
@@ -28,13 +22,11 @@ const WATCHED_ATTRS = [
     'aria-selected',
     'aria-checked',
     'data-state',
-    // Widened: visual + resource + form-value attributes. Values are capped (they can be long).
     'style',
     'src',
     'href',
     'value',
 ];
-/** Attribute/text values are capped per event — style/src can be huge and would bloat the ledger. */
 const MAX_ATTR_VALUE_LEN = 120;
 function capValue(value) {
     if (null === value)
@@ -43,24 +35,34 @@ function capValue(value) {
 }
 const DIALOG_ROLES = new Set(['dialog', 'alertdialog']);
 const LIVE_ROLES = new Set(['alert', 'status']);
-/** Max meaningful added/removed nodes reported per mutation batch (backpressure). */
 const MAX_PER_BATCH = 40;
 function isMeaningful(role, name) {
     return role !== 'generic' || name.length > 0;
 }
-/** Observe DOM mutations and emit semantic (not raw) events. */
-/**
- * The trimmed text carried by a node list, or undefined when it carries none.
- *
- * Whitespace-only nodes are ignored deliberately: a re-render that reshuffles indentation would
- * otherwise emit a text change on every layout node, which is noise the timeline cannot afford.
- */
+const MOUNT_SCAN_LIMIT = 40;
+function describeMount(node) {
+    const role = getRole(node);
+    const name = getAccessibleName(node);
+    if (isMeaningful(role, name))
+        return { role, name, el: node };
+    let scanned = 0;
+    for (const child of node.querySelectorAll('*')) {
+        if (scanned >= MOUNT_SCAN_LIMIT)
+            return undefined;
+        scanned += 1;
+        if (isReticleOverlay(child))
+            continue;
+        const childRole = getRole(child);
+        const childName = getAccessibleName(child);
+        if (isMeaningful(childRole, childName))
+            return { role: childRole, name: childName, el: child };
+    }
+    return undefined;
+}
 const TEXT_NODE = 3;
 function textOf(nodes) {
     let out = '';
     for (const node of nodes) {
-        // The numeric nodeType, not `Node.TEXT_NODE`: the global `Node` constructor is not guaranteed to
-        // exist wherever this runs, and referencing it threw a ReferenceError rather than degrading.
         if (node.nodeType !== TEXT_NODE)
             continue;
         out += node.nodeValue ?? '';
@@ -69,17 +71,11 @@ function textOf(nodes) {
     return trimmed.length > 0 ? trimmed : undefined;
 }
 export function installDom(emit) {
-    // Installed here rather than in the bootstrap list because this observer is the registry's reason
-    // for existing, and the ordering matters: a root attached between the two would be missed by both.
-    // It is also the only chance to capture a CLOSED root, which attachShadow returns exactly once.
     const stopRegistry = installShadowRegistry();
     const observer = new MutationObserver((records) => {
         let added = 0;
         let removed = 0;
         let changed = 0;
-        // Count element nodes dropped purely because a per-batch cap was already reached. The cap is on
-        // MEANINGFUL events, so it is only hit after a real flood — the count is a raw over-estimate
-        // (it can include not-yet-inspected noise) but `dropped > 0` honestly means "this batch was capped".
         let dropped = 0;
         for (const record of records) {
             if ('attributes' === record.type) {
@@ -90,7 +86,6 @@ export function installDom(emit) {
                         continue;
                     }
                     changed += 1;
-                    // Old value (attributeOldValue) + capped new value — a diff, not just a reading.
                     const value = capValue(target.getAttribute(record.attributeName));
                     const old = capValue(record.oldValue);
                     emit(EventType.DOM_ATTR, {
@@ -102,8 +97,6 @@ export function installDom(emit) {
                 continue;
             }
             if ('characterData' === record.type) {
-                // In-place text change inside an existing subtree (wizard steps, inline edits) —
-                // childList-only would miss this.
                 const parent = record.target.parentElement;
                 if (parent !== null && !isReticleOverlay(parent)) {
                     if (changed >= MAX_PER_BATCH) {
@@ -117,14 +110,6 @@ export function installDom(emit) {
                 }
                 continue;
             }
-            // A TEXT node arriving or leaving is a text change, and it is the ordinary one. `characterData`
-            // fires only when an EXISTING text node's `data` is edited in place; `el.textContent = x`,
-            // `innerText`, and React replacing a child all REPLACE the node instead — a childList mutation
-            // carrying a Text node, which the Element-only loops below skip. Measured on a live page:
-            // `firstChild.data = x` emitted `dom.text`, while `textContent`, `innerText` and
-            // `appendChild(createTextNode())` emitted NOTHING. So the most common visible change an app
-            // makes — updating text — produced no event at all, `reticle_observe` reported "nothing
-            // happened" over a screen that had visibly changed, and `settled` went quiet immediately.
             if (textOf(record.addedNodes) !== undefined || textOf(record.removedNodes) !== undefined) {
                 const parent = isElement(record.target) ? record.target : null;
                 if (parent !== null && !isReticleOverlay(parent)) {
@@ -132,8 +117,6 @@ export function installDom(emit) {
                         dropped += 1;
                     else {
                         changed += 1;
-                        // The element's text AFTER the mutation, so a cleared node reports '' rather than the
-                        // text that just left — the reader wants what is on screen now.
                         const text = (parent.textContent ?? '').trim().slice(0, 80);
                         const old = capValue(textOf(record.removedNodes) ?? null);
                         emit(EventType.DOM_TEXT, { text, ...(old === undefined ? {} : { old }) }, refs.refFor(parent));
@@ -149,12 +132,12 @@ export function installDom(emit) {
                 }
                 if (isReticleOverlay(node))
                     continue;
-                const role = getRole(node);
-                const name = getAccessibleName(node);
-                if (!isMeaningful(role, name))
+                const mounted = describeMount(node);
+                if (mounted === undefined)
                     continue;
+                const { role, name } = mounted;
                 added += 1;
-                const ref = refs.refFor(node);
+                const ref = refs.refFor(mounted.el);
                 emit(EventType.DOM_ADDED, { role, name, region: regionKeyOf(record.target) }, ref);
                 if (DIALOG_ROLES.has(role) ||
                     LIVE_ROLES.has(role) ||
@@ -172,17 +155,14 @@ export function installDom(emit) {
                 }
                 if (isReticleOverlay(node))
                     continue;
-                const role = getRole(node);
-                const name = getAccessibleName(node);
-                if (!isMeaningful(role, name))
+                const gone = describeMount(node);
+                if (gone === undefined)
                     continue;
+                const { role, name } = gone;
                 removed += 1;
-                // A removed node has no ref (it is gone), so the CONTAINER is the only stable identity — and it
-                // is what ambient learning needs to recognize a churning region.
                 emit(EventType.DOM_REMOVED, { role, name, region: regionKeyOf(record.target) });
             }
         }
-        // Never silent: a capped batch tells the ledger its DOM counts understate reality.
         if (dropped > 0)
             emit(EventType.TRUNCATED, { channel: TruncationChannel.DOM, dropped });
     });
@@ -196,13 +176,9 @@ export function installDom(emit) {
         characterDataOldValue: true,
     };
     observer.observe(document.documentElement, options);
-    // A MutationObserver does NOT cross a shadow boundary, so every root needs its own observation.
-    // Without this, a click that changed text inside a web component produced an empty observe window —
-    // the same shape as an app that ignored the click entirely.
     for (const root of capturedRoots())
         observer.observe(root, options);
     const unsubscribe = onShadowRoot((root) => observer.observe(root, options));
-    // Same-origin frame documents are separate node trees for the same reason, with the same symptom.
     const stopFrames = observeSameOriginFrames((body) => observer.observe(body, options));
     return () => {
         stopFrames();

package/dist/observers/download.d.ts

@@ -1,6 +1,5 @@
-import type { Emit, Teardown } from './types.js';
+import { type Emit, type Teardown } from './types.js';
 interface DownloadOptions {
-    /** Include a content preview. Gated for the same reason request bodies are: exports hold PII. */
     capturePreview?: boolean;
 }
 export declare function installDownload(emit: Emit, opts?: DownloadOptions): Teardown;

package/dist/observers/download.js

@@ -1,58 +1,37 @@
 import { EventType } from '@reticlehq/core';
 import { captureMethod } from '../patching/capture-method.js';
-import { projectBody } from './network-body.js';
-/**
- * Files the app PRODUCES — the one artifact class an outside-the-browser tool cannot inspect.
- *
- * A generated export never crosses the network: the app builds a Blob, hands it to
- * `URL.createObjectURL`, and clicks an anchor. There is no request to intercept, and Playwright MCP
- * has no tool that returns a downloaded file at all. Reticle runs inside the page, where the Blob is
- * constructed, so the export is observable before it reaches the disk.
- *
- * Measured on a real merchant dashboard: one Export click produced a CSV wrong three ways at once —
- * 25 data rows in a file named `transactions-128-rows.csv`, an unquoted `3 Aug, 10:00 pm` that
- * shifts every column after it, and an `amount_inr` header over rows denominated in USD — while the
- * click itself reported a clean success and every other channel agreed. The benchmark's ground truth
- * records those three as missed by BOTH toolchains, for the same reason: nobody opened the file.
- */
-/** Text-like types worth counting lines in and previewing. Anything else reports type + size only. */
+import { projectBody } from './net-detail/network-body.js';
+import { observeSafely, observeValue } from './types.js';
 const TEXTUAL = /text\/|json|csv|xml|ndjson|javascript/i;
-/** Lines are reported for text files; the preview is capped and redacted by projectBody. */
 const PREVIEW_CHARS = 2000;
 export function installDownload(emit, opts = {}) {
-    // jsdom does not implement `createObjectURL`, and plenty of users run this SDK under jsdom in their
-    // own test suite. Reaching for `.bind` on an absent function threw during `connect()` — an
-    // observability layer taking the host app down with it, which is the one failure mode it may never
-    // have. No object URLs means no generated files to observe, so this simply stands down.
     if (typeof URL.createObjectURL !== 'function')
         return () => undefined;
     const objectUrl = URL.createObjectURL.bind(URL);
     const known = new Map();
-    /**
-     * `createObjectURL` is where the file becomes real. The filename is NOT here — it lives on the
-     * anchor that gets clicked — so the blob is remembered against its URL and reported when either
-     * the anchor fires or, failing that, on a microtask so a download that is never clicked (a
-     * generated preview, an <img> src) is still visible.
-     */
     const originalCreate = captureMethod(URL, 'createObjectURL');
-    URL.createObjectURL = function reticleObservedObjectUrl(obj) {
+    const patchedCreate = function reticleObservedObjectUrl(obj) {
         const url = objectUrl(obj);
-        if (typeof Blob !== 'undefined' && obj instanceof Blob) {
-            // Started here, awaited at report time — never blocking the app's own download path.
-            const text = TEXTUAL.test(obj.type)
-                ? obj.text().catch(() => undefined)
-                : Promise.resolve(undefined);
-            known.set(url, { type: obj.type, size: obj.size, text });
-        }
+        observeSafely(() => {
+            if (typeof Blob !== 'undefined' && obj instanceof Blob) {
+                const text = TEXTUAL.test(obj.type)
+                    ? obj.text().catch(() => undefined)
+                    : Promise.resolve(undefined);
+                known.set(url, { type: obj.type, size: obj.size, text });
+            }
+        });
         return url;
     };
+    URL.createObjectURL = patchedCreate;
     const report = (url, filename) => {
         const record = known.get(url);
         if (record === undefined)
             return;
         known.delete(url);
         void record.text.then((text) => {
-            emitDownload(record, filename, text);
+            observeSafely(() => {
+                emitDownload(record, filename, text);
+            });
         });
     };
     const emitDownload = (record, filename, text) => {
@@ -60,8 +39,6 @@ export function installDownload(emit, opts = {}) {
         if (filename !== undefined && filename.length > 0)
             data['filename'] = filename;
         if (text !== undefined) {
-            // The LINE COUNT is reported even without preview capture: it is a number, not content, and it
-            // is the whole tell for "25 rows in a file the toast calls 128".
             data['lines'] = text.split('\n').filter((l) => l.length > 0).length;
             if (true === opts.capturePreview) {
                 const { body, truncated } = projectBody(text.slice(0, PREVIEW_CHARS), record.type);
@@ -72,32 +49,38 @@ export function installDownload(emit, opts = {}) {
         }
         emit(EventType.DOWNLOAD, data);
     };
-    /**
-     * An anchor click carries the NAME. Captured at the document level so it sees the click whether the
-     * app dispatches it programmatically or a human does, and whether or not the anchor is in the DOM.
-     */
     const onClick = (event) => {
-        const target = event.target;
-        const anchor = target instanceof Element ? target.closest('a[download]') : null;
-        if (null === anchor)
-            return;
-        report(anchor.getAttribute('href') ?? '', anchor.getAttribute('download') ?? undefined);
+        observeSafely(() => {
+            const target = event.target;
+            const anchor = target instanceof Element ? target.closest('a[download]') : null;
+            if (null === anchor)
+                return;
+            report(anchor.getAttribute('href') ?? '', anchor.getAttribute('download') ?? undefined);
+        });
     };
     document.addEventListener('click', onClick, true);
-    // A programmatic `a.click()` on an anchor never inserted into the document dispatches no bubbling
-    // event this listener can see, so the anchor path is patched too.
     const originalClick = captureMethod(HTMLAnchorElement.prototype, 'click');
-    HTMLAnchorElement.prototype.click = function reticleObservedAnchorClick() {
-        if (this.hasAttribute('download')) {
-            report(this.getAttribute('href') ?? '', this.getAttribute('download') ?? undefined);
-        }
+    const patchedClick = function reticleObservedAnchorClick() {
+        const pending = observeValue(() => this.hasAttribute('download')
+            ? {
+                href: this.getAttribute('href') ?? '',
+                name: this.getAttribute('download') ?? undefined,
+            }
+            : undefined);
         originalClick.call(this);
+        observeSafely(() => {
+            if (pending !== undefined)
+                report(pending.href, pending.name);
+        });
     };
+    HTMLAnchorElement.prototype.click = patchedClick;
     return () => {
-        // A REAL restore, so teardown leaves the page exactly as it was found.
         document.removeEventListener('click', onClick, true);
-        URL.createObjectURL = originalCreate;
-        HTMLAnchorElement.prototype.click = originalClick;
+        if (URL.createObjectURL === patchedCreate)
+            URL.createObjectURL = originalCreate;
+        if (HTMLAnchorElement.prototype.click === patchedClick) {
+            HTMLAnchorElement.prototype.click = originalClick;
+        }
         known.clear();
     };
 }

package/dist/observers/focus.d.ts

@@ -1,9 +1,3 @@
 import type { Emit, Teardown } from './types.js';
-/** A human-legible label for a focused element, or undefined for body/none. Pure; exported for testing. */
 export declare function focusLabel(el: EventTarget | null): string | undefined;
-/**
- * Track element focus movement. Focus dropping to <body> after an act — a modal that closed and stranded
- * focus, a button that vanished — is a real accessibility/UX regression no screenshot names. Emits
- * FOCUS_CHANGE {to, from, toBody}. Reversible.
- */
 export declare function installFocus(emit: Emit): Teardown;

package/dist/observers/focus.js

@@ -1,6 +1,5 @@
 import { EventType } from '@reticlehq/core';
 import { getAccessibleName, getRole } from '../dom/a11y.js';
-/** A human-legible label for a focused element, or undefined for body/none. Pure; exported for testing. */
 export function focusLabel(el) {
     if (!(el instanceof Element) || el === document.body)
         return undefined;
@@ -11,11 +10,6 @@ export function focusLabel(el) {
 function toBody(el) {
     return null === el || el === document.body;
 }
-/**
- * Track element focus movement. Focus dropping to <body> after an act — a modal that closed and stranded
- * focus, a button that vanished — is a real accessibility/UX regression no screenshot names. Emits
- * FOCUS_CHANGE {to, from, toBody}. Reversible.
- */
 export function installFocus(emit) {
     const ac = new AbortController();
     const { signal } = ac;
@@ -31,7 +25,6 @@ export function installFocus(emit) {
         });
     };
     const onFocusOut = (event) => {
-        // Focus left with nothing gaining it → it dropped to the body (the regression case).
         if (event.relatedTarget !== null)
             return;
         const from = last;