@reticlehq/browser 2.2.0 → 2.3.0

package/dist/dom/snapshot.js

@@ -1,4 +1,6 @@
 import { ElementState, SnapshotMode } from '@reticlehq/core';
+import { capturedRootOf } from './shadow-registry.js';
+import { isFrame } from './realm.js';
 import { getAccessibleName, getRole, getStates, getValue, isVisible } from './a11y.js';
 import { refs } from './refs.js';
 import { isIgnored } from './dom-ignore.js';
@@ -93,10 +95,16 @@ function layoutSignature(style) {
  */
 function pierceChildren(parent) {
     const out = [...parent.children];
-    const shadow = parent.shadowRoot;
+    // A CLOSED root reports `shadowRoot === null` forever, but the registry captured it at the moment
+    // `attachShadow` returned it. `query` has been able to reach that content since; the snapshot could
+    // not, so the two tools disagreed about what is on the page — and the snapshot is the one an agent
+    // reads to decide what to query for, which makes its omission the one that actually costs.
+    const shadow = parent.shadowRoot ?? capturedRootOf(parent);
     if (shadow !== null)
         out.push(...shadow.children);
-    if (parent instanceof HTMLIFrameElement) {
+    // Realm-aware: an iframe nested INSIDE another frame's body belongs to that frame's realm, so the
+    // top window's constructor never matches it and nested embeds were silently never pierced.
+    if (isFrame(parent)) {
         try {
             const body = parent.contentDocument?.body;
             if (body !== null && body !== undefined)
@@ -156,11 +164,21 @@ function collectDialogs(root) {
     }
     return names;
 }
+/**
+ * Status for a snapshot, with uninformative defaults OMITTED.
+ *
+ * `reticle_act` already follows this rule — "fields at their uninformative default are omitted so a
+ * clean action collapses to its consequence" — and snapshot did not, so every response carried
+ * `visibleDialogs: []` whether or not a dialog existed. An empty array is the overwhelmingly common
+ * case, so the field was almost pure repetition; a reader learns nothing from its presence and
+ * everything from it.
+ */
 function buildStatus(root) {
+    const visibleDialogs = collectDialogs(root);
     return {
         route: `${location.pathname}${location.search}${location.hash}`,
         title: document.title,
-        visibleDialogs: collectDialogs(root),
+        ...(visibleDialogs.length > 0 ? { visibleDialogs } : {}),
     };
 }
 /** Build the semantic accessibility snapshot of the page or a subtree. */
@@ -195,4 +213,3 @@ export function buildSnapshot(options = {}) {
         truncated: ctx.truncated,
     };
 }
-//# sourceMappingURL=snapshot.js.map

package/dist/dom/source.d.ts

@@ -37,4 +37,3 @@ export declare function sourceFor(el: Element, adapterSource: SourceLocation | u
  * opening an editor or printing it.
  */
 export declare function formatSource(source: SourceLocation | undefined): string | undefined;
-//# sourceMappingURL=source.d.ts.map

package/dist/dom/source.js

@@ -56,4 +56,3 @@ export function sourceFor(el, adapterSource) {
 export function formatSource(source) {
     return source === undefined ? undefined : `${source.file}:${String(source.line)}`;
 }
-//# sourceMappingURL=source.js.map

package/dist/dom/theme.d.ts

@@ -23,4 +23,3 @@ 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 {};
-//# sourceMappingURL=theme.d.ts.map

package/dist/dom/theme.js

@@ -87,4 +87,3 @@ export function themeReport(cs) {
 export function resetThemeCache() {
     cached = null;
 }
-//# sourceMappingURL=theme.js.map

package/dist/dom/virtualized.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Rows a scroll container has reserved space for but has NOT rendered.
+ *
+ * `BlindSpotKind.VIRTUALIZED_UNMOUNTED` has had a label on the server since it was defined and
+ * nothing ever emitted it — a declared blind spot that could not fire, shaped exactly like the most
+ * common data-heavy UI there is. Measured on a 10,000-row console: 29 rows in the DOM, and a verdict
+ * that reported full coverage. An assertion like "no shipment is held" was a claim about 29 rows,
+ * delivered as a claim about all of them.
+ *
+ * The detector measures EMPTY RESERVED SPACE rather than guessing from child counts. A virtualizer
+ * sizes its scroll area for the whole list and renders only a window, so the area above the first
+ * child and below the last is space the container has promised and not filled. An ordinary list —
+ * even one with large gaps or margins between rows — spans its own scroll height, so it measures
+ * zero and never reports.
+ */
+/** How many rows a container is holding space for but has not rendered. 0 when it is not virtualized. */
+export declare function unmountedRowsIn(container: HTMLElement): number;
+/** Total unmounted rows across every scroll container on the page. */
+export declare function countUnmountedRows(): number;

package/dist/dom/virtualized.js

@@ -0,0 +1,80 @@
+/**
+ * Rows a scroll container has reserved space for but has NOT rendered.
+ *
+ * `BlindSpotKind.VIRTUALIZED_UNMOUNTED` has had a label on the server since it was defined and
+ * nothing ever emitted it — a declared blind spot that could not fire, shaped exactly like the most
+ * common data-heavy UI there is. Measured on a 10,000-row console: 29 rows in the DOM, and a verdict
+ * that reported full coverage. An assertion like "no shipment is held" was a claim about 29 rows,
+ * delivered as a claim about all of them.
+ *
+ * The detector measures EMPTY RESERVED SPACE rather than guessing from child counts. A virtualizer
+ * sizes its scroll area for the whole list and renders only a window, so the area above the first
+ * child and below the last is space the container has promised and not filled. An ordinary list —
+ * even one with large gaps or margins between rows — spans its own scroll height, so it measures
+ * zero and never reports.
+ */
+/** Below this, the empty space is padding or a sticky header rather than a virtualized remainder. */
+const UNMOUNTED_RATIO = 0.25;
+/** A container has to be meaningfully scrollable before "what is not rendered" is even a question. */
+const MIN_SCROLL_RATIO = 1.2;
+/**
+ * Virtualizers usually put one full-height SPACER inside the scroller and position rows absolutely
+ * inside it, so the scroller's own children are just that spacer. Descend through it to reach the
+ * rows — without this the spacer measures as filling the container and nothing is ever detected.
+ */
+function rowHost(container) {
+    let host = container;
+    for (let depth = 0; depth < 3; depth += 1) {
+        const children = Array.from(host.children).filter((c) => c instanceof HTMLElement);
+        const only = children.length === 1 ? children[0] : undefined;
+        if (only === undefined)
+            return host;
+        // A spacer is a single child that fills (or over-fills) the scroll area.
+        if (only.offsetHeight < host.scrollHeight * 0.9)
+            return host;
+        host = only;
+    }
+    return host;
+}
+/** How many rows a container is holding space for but has not rendered. 0 when it is not virtualized. */
+export function unmountedRowsIn(container) {
+    const scrollHeight = container.scrollHeight;
+    const clientHeight = container.clientHeight;
+    if (clientHeight <= 0 || scrollHeight < clientHeight * MIN_SCROLL_RATIO)
+        return 0;
+    const host = rowHost(container);
+    const rows = Array.from(host.children).filter((c) => c instanceof HTMLElement);
+    if (rows.length < 2)
+        return 0;
+    let top = Infinity;
+    let bottom = 0;
+    let totalHeight = 0;
+    for (const row of rows) {
+        const rowTop = row.offsetTop;
+        const rowBottom = rowTop + row.offsetHeight;
+        if (rowTop < top)
+            top = rowTop;
+        if (rowBottom > bottom)
+            bottom = rowBottom;
+        totalHeight += row.offsetHeight;
+    }
+    // Space the container reserved and left empty: above the first row plus below the last.
+    const empty = Math.max(0, top) + Math.max(0, scrollHeight - bottom);
+    if (empty < scrollHeight * UNMOUNTED_RATIO)
+        return 0;
+    const averageRow = totalHeight / rows.length;
+    if (averageRow <= 0)
+        return 0;
+    return Math.round(empty / averageRow);
+}
+/** Total unmounted rows across every scroll container on the page. */
+export function countUnmountedRows() {
+    let total = 0;
+    for (const element of document.querySelectorAll('*')) {
+        // Cheap gate first: only elements that actually scroll are worth measuring.
+        if (element.scrollHeight <= element.clientHeight)
+            continue;
+        total += unmountedRowsIn(element);
+    }
+    return total;
+}

package/dist/index.d.ts

@@ -26,4 +26,3 @@ export { describe, getRole, getAccessibleName, getStates, isVisible } from './do
 export { refs, RefRegistry } from './dom/refs.js';
 export { Annotator, installAnnotator, type AnnotatorDeps } from './review/annotator.js';
 export { resolveMarkAnchor, type MarkAnchor } from './review/mark-anchor.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -37,4 +37,3 @@ export { describe, getRole, getAccessibleName, getStates, isVisible } from './do
 export { refs, RefRegistry } from './dom/refs.js';
 export { Annotator, installAnnotator } from './review/annotator.js';
 export { resolveMarkAnchor } from './review/mark-anchor.js';
-//# sourceMappingURL=index.js.map

package/dist/observers/animation.d.ts

@@ -1,4 +1,3 @@
 import type { Emit, Teardown } from './types.js';
 /** Observe CSS animations + transitions and emit anim.start / anim.end. */
 export declare function installAnimation(emit: Emit): Teardown;
-//# sourceMappingURL=animation.d.ts.map

package/dist/observers/animation.js

@@ -32,4 +32,3 @@ export function installAnimation(emit) {
         document.removeEventListener('transitionend', onTransitionEnd, true);
     };
 }
-//# sourceMappingURL=animation.js.map

package/dist/observers/blind-spots.d.ts

@@ -3,10 +3,23 @@ import type { Emit, Teardown } from './types.js';
  * Blind-spot sensor. The SDK instruments the DOM, but a cross-origin iframe is a wall it cannot
  * see through — its contents, network, and console are invisible. Left unstated, a green verdict would
  * imply the whole page was verified. This detects cross-origin frames and emits a BLIND_SPOT event so the
- * server can mark results `coverage: partial` instead of lying by omission. Closed shadow roots and
- * virtualized-unmounted rows are the other kinds (detected elsewhere / by their tools); this sensor owns
- * the iframe case, the one that is cheaply and reliably detectable from the page.
+ * server can mark results `coverage: partial` instead of lying by omission. This sensor owns the three
+ * kinds cheaply and reliably detectable from the page: cross-origin frames, closed shadow roots, and
+ * virtualized-unmounted rows.
  */
+/**
+ * Elements rendering content nobody outside them can read.
+ *
+ * `attachShadow({mode:'closed'})` makes `el.shadowRoot` null FOREVER, for every caller — Reticle,
+ * Playwright's accessibility snapshot, a screenshot-reading model, all of them. There is no API that
+ * recovers it, so the only honest behaviour is to say the region exists and is unreadable.
+ *
+ * It is not directly detectable either, so this infers it: a custom element (a dash in the tag name is
+ * the spec's own rule) that has NO light-DOM children and no text, yet occupies layout space, is
+ * painting from somewhere. Nothing else produces that combination — an empty custom element that
+ * renders nothing measures zero and is skipped.
+ */
+export declare function countClosedShadowRoots(): number;
 /**
  * Whether a frame is cross-origin (unobservable). A same-origin frame exposes its `contentDocument`; a
  * cross-origin one returns null (or THROWS a SecurityError on access). A src-less / about:blank frame is
@@ -16,4 +29,3 @@ export declare function isCrossOriginFrame(frame: HTMLIFrameElement): boolean;
 /** How many of the given frames are cross-origin (unobservable). */
 export declare function countCrossOriginFrames(frames: readonly HTMLIFrameElement[]): number;
 export declare function installBlindSpots(emit: Emit): Teardown;
-//# sourceMappingURL=blind-spots.d.ts.map

package/dist/observers/blind-spots.js

@@ -1,13 +1,49 @@
 import { EventType, BlindSpotKind } from '@reticlehq/core';
+import { countUnmountedRows } from '../dom/virtualized.js';
+import { isCaptured } from '../dom/shadow-registry.js';
+import { sameOriginFrameBodies } from './frames.js';
 import { nativeClearTimeout, nativeSetTimeout } from '../timers/native-timers.js';
 /**
  * Blind-spot sensor. The SDK instruments the DOM, but a cross-origin iframe is a wall it cannot
  * see through — its contents, network, and console are invisible. Left unstated, a green verdict would
  * imply the whole page was verified. This detects cross-origin frames and emits a BLIND_SPOT event so the
- * server can mark results `coverage: partial` instead of lying by omission. Closed shadow roots and
- * virtualized-unmounted rows are the other kinds (detected elsewhere / by their tools); this sensor owns
- * the iframe case, the one that is cheaply and reliably detectable from the page.
+ * server can mark results `coverage: partial` instead of lying by omission. This sensor owns the three
+ * kinds cheaply and reliably detectable from the page: cross-origin frames, closed shadow roots, and
+ * virtualized-unmounted rows.
  */
+/**
+ * Elements rendering content nobody outside them can read.
+ *
+ * `attachShadow({mode:'closed'})` makes `el.shadowRoot` null FOREVER, for every caller — Reticle,
+ * Playwright's accessibility snapshot, a screenshot-reading model, all of them. There is no API that
+ * recovers it, so the only honest behaviour is to say the region exists and is unreadable.
+ *
+ * It is not directly detectable either, so this infers it: a custom element (a dash in the tag name is
+ * the spec's own rule) that has NO light-DOM children and no text, yet occupies layout space, is
+ * painting from somewhere. Nothing else produces that combination — an empty custom element that
+ * renders nothing measures zero and is skipped.
+ */
+export function countClosedShadowRoots() {
+    let count = 0;
+    for (const el of document.querySelectorAll('*')) {
+        if (!el.tagName.includes('-'))
+            continue;
+        if (el.shadowRoot !== null)
+            continue; // open — readable, not a blind spot
+        // A closed root attached AFTER the SDK installed was captured from attachShadow's return value,
+        // so it is readable too. Only what was genuinely missed is declared.
+        if (isCaptured(el))
+            continue;
+        if (el.children.length > 0)
+            continue;
+        if ((el.textContent ?? '').trim().length > 0)
+            continue;
+        if (el.offsetHeight <= 0 && el.offsetWidth <= 0)
+            continue;
+        count += 1;
+    }
+    return count;
+}
 /**
  * Whether a frame is cross-origin (unobservable). A same-origin frame exposes its `contentDocument`; a
  * cross-origin one returns null (or THROWS a SecurityError on access). A src-less / about:blank frame is
@@ -35,6 +71,15 @@ export function countCrossOriginFrames(frames) {
 function currentCount() {
     return countCrossOriginFrames(Array.from(document.querySelectorAll('iframe')));
 }
+/**
+ * Same-origin frames — observed for DOM, NOT for network.
+ *
+ * Their `fetch` lives in the frame's own realm, which the top realm's patch never sees. Left
+ * undeclared, `settled` can read true while a frame request is still in flight.
+ */
+function uninstrumentedFrameCount() {
+    return sameOriginFrameBodies(document).length;
+}
 /**
  * Watch the page for cross-origin iframes and emit BLIND_SPOT whenever the count CHANGES (install +
  * on any added/removed frame). Only the delta is emitted — never a per-mutation flood — so a static
@@ -48,14 +93,24 @@ function currentCount() {
  */
 const RECHECK_DEBOUNCE_MS = 250;
 export function installBlindSpots(emit) {
-    let last = -1;
+    // Every kind is counted the same way and emitted on CHANGE only, so a static embed or a steady list
+    // reports once instead of flooding. Virtualized rows matter most: without them an assertion over a
+    // 10,000-row grid is a claim about the ~29 on screen, delivered as full coverage.
+    const sensors = [
+        { kind: BlindSpotKind.CROSS_ORIGIN_IFRAME, count: currentCount },
+        { kind: BlindSpotKind.UNINSTRUMENTED_FRAME, count: uninstrumentedFrameCount },
+        { kind: BlindSpotKind.CLOSED_SHADOW_ROOT, count: countClosedShadowRoots },
+        { kind: BlindSpotKind.VIRTUALIZED_UNMOUNTED, count: countUnmountedRows },
+    ];
+    const last = new Map();
     const report = () => {
-        const count = currentCount();
-        if (count === last)
-            return;
-        last = count;
-        if (count > 0) {
-            emit(EventType.BLIND_SPOT, { kind: BlindSpotKind.CROSS_ORIGIN_IFRAME, count });
+        for (const sensor of sensors) {
+            const count = sensor.count();
+            if (count === last.get(sensor.kind))
+                continue;
+            last.set(sensor.kind, count);
+            if (count > 0)
+                emit(EventType.BLIND_SPOT, { kind: sensor.kind, count });
         }
     };
     report();
@@ -86,4 +141,3 @@ export function installBlindSpots(emit) {
         observer.disconnect();
     };
 }
-//# sourceMappingURL=blind-spots.js.map

package/dist/observers/console.d.ts

@@ -1,4 +1,3 @@
 import type { Emit, Teardown } from './types.js';
 /** Patch console.{log,warn,error} and window error events. Reversible. */
 export declare function installConsole(emit: Emit): Teardown;
-//# sourceMappingURL=console.d.ts.map

package/dist/observers/console.js

@@ -88,4 +88,3 @@ export function installConsole(emit) {
         window.removeEventListener('unhandledrejection', onRejection);
     };
 }
-//# sourceMappingURL=console.js.map

package/dist/observers/dom.d.ts

@@ -1,4 +1,2 @@
 import type { Emit, Teardown } from './types.js';
-/** Observe DOM mutations and emit semantic (not raw) events. */
 export declare function installDom(emit: Emit): Teardown;
-//# sourceMappingURL=dom.d.ts.map

package/dist/observers/dom.js

@@ -8,13 +8,16 @@ import { refs } from '../dom/refs.js';
  * container persists across ticks, so its testid (or ref) is the identity that does accumulate.
  */
 function regionKeyOf(target) {
-    const el = target instanceof Element ? target : null;
+    const el = isElement(target) ? target : null;
     if (el === null)
         return undefined;
     const labelled = el.closest('[data-testid]');
     return labelled?.getAttribute('data-testid') ?? refs.refFor(el);
 }
 import { isReticleOverlay } from '../dom/dom-ignore.js';
+import { capturedRoots, installShadowRegistry, onShadowRoot } from '../dom/shadow-registry.js';
+import { isElement } from '../dom/realm.js';
+import { observeSameOriginFrames } from './frames.js';
 const WATCHED_ATTRS = [
     'class',
     'hidden',
@@ -46,7 +49,30 @@ 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 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 ?? '';
+    }
+    const trimmed = out.trim();
+    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;
@@ -58,9 +84,7 @@ export function installDom(emit) {
         for (const record of records) {
             if (record.type === 'attributes') {
                 const target = record.target;
-                if (target instanceof Element &&
-                    record.attributeName !== null &&
-                    !isReticleOverlay(target)) {
+                if (isElement(target) && record.attributeName !== null && !isReticleOverlay(target)) {
                     if (changed >= MAX_PER_BATCH) {
                         dropped += 1;
                         continue;
@@ -93,8 +117,31 @@ 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)) {
+                    if (changed >= MAX_PER_BATCH)
+                        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));
+                    }
+                }
+            }
             for (const node of record.addedNodes) {
-                if (!(node instanceof Element))
+                if (!isElement(node))
                     continue;
                 if (added >= MAX_PER_BATCH) {
                     dropped += 1;
@@ -117,7 +164,7 @@ export function installDom(emit) {
                 }
             }
             for (const node of record.removedNodes) {
-                if (!(node instanceof Element))
+                if (!isElement(node))
                     continue;
                 if (removed >= MAX_PER_BATCH) {
                     dropped += 1;
@@ -139,7 +186,7 @@ export function installDom(emit) {
         if (dropped > 0)
             emit(EventType.TRUNCATED, { channel: TruncationChannel.DOM, dropped });
     });
-    observer.observe(document.documentElement, {
+    const options = {
         subtree: true,
         childList: true,
         attributes: true,
@@ -147,9 +194,20 @@ export function installDom(emit) {
         attributeOldValue: true,
         characterData: true,
         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();
+        unsubscribe();
+        stopRegistry();
         observer.disconnect();
     };
 }
-//# sourceMappingURL=dom.js.map

package/dist/observers/download.d.ts

@@ -0,0 +1,6 @@
+import type { Emit, Teardown } from './types.js';
+export 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

@@ -0,0 +1,103 @@
+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. */
+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 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 });
+        }
+        return url;
+    };
+    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);
+        });
+    };
+    const emitDownload = (record, filename, text) => {
+        const data = { mimeType: record.type, bytes: record.size };
+        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 (opts.capturePreview === true) {
+                const { body, truncated } = projectBody(text.slice(0, PREVIEW_CHARS), record.type);
+                data['preview'] = body;
+                if (truncated)
+                    data['previewTruncated'] = true;
+            }
+        }
+        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 (anchor === null)
+            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);
+        }
+        originalClick.call(this);
+    };
+    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;
+        known.clear();
+    };
+}

package/dist/observers/focus.d.ts

@@ -7,4 +7,3 @@ export declare function focusLabel(el: EventTarget | null): string | undefined;
  * FOCUS_CHANGE {to, from, toBody}. Reversible.
  */
 export declare function installFocus(emit: Emit): Teardown;
-//# sourceMappingURL=focus.d.ts.map

package/dist/observers/focus.js

@@ -46,4 +46,3 @@ export function installFocus(emit) {
         document.removeEventListener('focusout', onFocusOut);
     };
 }
-//# sourceMappingURL=focus.js.map

package/dist/observers/frames.d.ts

@@ -0,0 +1,12 @@
+import type { Teardown } from './types.js';
+/** Every same-origin frame body at or beneath `root`, in document order. */
+export declare function sameOriginFrameBodies(root: ParentNode): HTMLElement[];
+/**
+ * Call `attach` for every same-origin frame body now and after each frame load.
+ *
+ * A frame that navigates gets a BRAND NEW document, so the old observation is dead and re-attaching on
+ * `load` is not optional — without it, observation silently stops the first time an embedded panel
+ * routes. Attaching twice to the same node is harmless (MutationObserver de-duplicates), so no
+ * bookkeeping is kept.
+ */
+export declare function observeSameOriginFrames(attach: (body: HTMLElement) => void): Teardown;