@reticlehq/browser 2.2.1 → 2.4.0

package/dist/dom/shadow-registry.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Every shadow root this SDK has seen created, open or closed.
+ *
+ * Two problems are solved by the same record.
+ *
+ * **Observation.** A `MutationObserver` on `documentElement` does NOT cross a shadow boundary, so a
+ * click that changes text inside a web component produced an entirely empty observe window. Measured
+ * on a console with a shadow-DOM alert badge: the click landed, the badge changed, and `observe`
+ * reported zero DOM events — indistinguishable from an app that ignored the click. The DOM observer
+ * needs a list of roots to attach to, and no API enumerates them.
+ *
+ * **Closed roots.** `element.shadowRoot` is null forever for `mode: 'closed'`, so a closed root is
+ * unreadable AFTER the fact — but `attachShadow` still RETURNS it to its caller. Patching that call
+ * captures the root at the one instant it is exposed. This only works when the SDK is installed
+ * before the component upgrades, which is why hosts are tracked individually rather than assumed:
+ * whatever was missed is still declared as a blind spot, and only what was genuinely captured stops
+ * being one.
+ */
+/**
+ * Bookkeeping ceiling. Weak references make the ROOTS collectable; this bounds the entries pointing
+ * at them, which are not. Sized far above any real page's live component count.
+ */
+export declare const MAX_TRACKED_ROOTS = 4000;
+/** Dead-entry sweeps are O(retained), so they run once per this many roots rather than per root. */
+export declare const SWEEP_EVERY = 250;
+/** Shadow roots captured so far. Includes closed roots when the patch was installed in time. */
+export declare function capturedRoots(): readonly ShadowRoot[];
+/** Whether this element's shadow root was captured — i.e. whether its contents are reachable. */
+export declare function isCaptured(host: Element): boolean;
+/** The captured root for a host, or null. Non-null for closed roots the patch caught in time. */
+export declare function capturedRootOf(host: Element): ShadowRoot | null;
+/** Run `listener` for every root captured from now on. Returns an unsubscribe. */
+export declare function onShadowRoot(listener: (root: ShadowRoot) => void): () => void;
+/**
+ * Patch `attachShadow` to record each root as it is created, and sweep the roots that already exist.
+ *
+ * The sweep can only find OPEN roots (there is no other way in), so a closed root attached before
+ * install stays unreachable — correctly, and it is declared as such.
+ */
+export declare function installShadowRegistry(): () => void;

package/dist/dom/shadow-registry.js

@@ -0,0 +1,165 @@
+/**
+ * Every shadow root this SDK has seen created, open or closed.
+ *
+ * Two problems are solved by the same record.
+ *
+ * **Observation.** A `MutationObserver` on `documentElement` does NOT cross a shadow boundary, so a
+ * click that changes text inside a web component produced an entirely empty observe window. Measured
+ * on a console with a shadow-DOM alert badge: the click landed, the badge changed, and `observe`
+ * reported zero DOM events — indistinguishable from an app that ignored the click. The DOM observer
+ * needs a list of roots to attach to, and no API enumerates them.
+ *
+ * **Closed roots.** `element.shadowRoot` is null forever for `mode: 'closed'`, so a closed root is
+ * unreadable AFTER the fact — but `attachShadow` still RETURNS it to its caller. Patching that call
+ * captures the root at the one instant it is exposed. This only works when the SDK is installed
+ * before the component upgrades, which is why hosts are tracked individually rather than assumed:
+ * whatever was missed is still declared as a blind spot, and only what was genuinely captured stops
+ * being one.
+ */
+import { captureMethod } from '../patching/capture-method.js';
+/**
+ * How many installs are live.
+ *
+ * The state below is module-level, and a dev-only SDK gets installed more than once: Vite re-runs the
+ * module on hot reload, so `connect()` can run again before the previous instance is torn down.
+ * Measured: install, subscribe, install again, tear down the SECOND one — and the FIRST instance's
+ * subscribers were gone, so the DOM observer silently stopped being told about new shadow roots for
+ * the rest of the session. Shared state must only be cleared by the last install standing.
+ */
+let installs = 0;
+/**
+ * Retained shadow roots, weakly.
+ *
+ * This was a strong `Set` and it never shrank. Measured: a virtualized list that renders and removes
+ * 5,000 web-component rows left 5,000 roots retained — each pinning its whole shadow subtree, and
+ * pinning its host through `root.host`, so nothing the list discarded could ever be collected. A
+ * design system's rows ARE web components, so the most ordinary data-heavy page is the worst case,
+ * and this SDK is meant to sit in a dev session all day.
+ *
+ * Same shape `RefRegistry` already uses for element handles: hold weakly, bound the bookkeeping,
+ * sweep the dead entries periodically rather than on every write.
+ */
+const roots = new Set();
+/**
+ * Membership, separately and weakly.
+ *
+ * The weak entries above are for ENUMERATION and cannot answer "have I seen this root" without
+ * dereferencing all of them — which turns every `attachShadow` into a scan of every root so far, and
+ * a 5,000-row list into 25 million comparisons. A WeakSet answers it in O(1) and retains nothing.
+ */
+const known = new WeakSet();
+const hosts = new WeakSet();
+/**
+ * Bookkeeping ceiling. Weak references make the ROOTS collectable; this bounds the entries pointing
+ * at them, which are not. Sized far above any real page's live component count.
+ */
+export const MAX_TRACKED_ROOTS = 4000;
+/** Dead-entry sweeps are O(retained), so they run once per this many roots rather than per root. */
+export const SWEEP_EVERY = 250;
+let sinceSweep = 0;
+/** Drop entries whose root has been collected, then any excess by age (Set keeps insertion order). */
+function sweep() {
+    for (const ref of roots) {
+        if (ref.deref() === undefined)
+            roots.delete(ref);
+    }
+    while (roots.size > MAX_TRACKED_ROOTS) {
+        const oldest = roots.values().next();
+        if (oldest.done === true)
+            break;
+        roots.delete(oldest.value);
+    }
+}
+/** The live roots behind the weak entries. */
+function liveRoots() {
+    const out = [];
+    for (const ref of roots) {
+        const root = ref.deref();
+        if (root !== undefined)
+            out.push(root);
+    }
+    return out;
+}
+const listeners = new Set();
+function record(root, host) {
+    // Idempotent. A hot reload leaves one patch wrapping another, so a single `attachShadow` travels
+    // through both and reports twice; the initial sweep can also meet a root the patch already caught.
+    // Subscribers must see each root exactly once — they attach an observer per root, and counting one
+    // twice is how a "reported once" guarantee quietly becomes "reported per install".
+    if (known.has(root))
+        return;
+    known.add(root);
+    roots.add(new WeakRef(root));
+    sinceSweep += 1;
+    if (sinceSweep >= SWEEP_EVERY) {
+        sinceSweep = 0;
+        sweep();
+    }
+    hosts.add(host);
+    for (const listener of listeners)
+        listener(root);
+}
+/** Shadow roots captured so far. Includes closed roots when the patch was installed in time. */
+export function capturedRoots() {
+    return liveRoots();
+}
+/** Whether this element's shadow root was captured — i.e. whether its contents are reachable. */
+export function isCaptured(host) {
+    return hosts.has(host);
+}
+/** The captured root for a host, or null. Non-null for closed roots the patch caught in time. */
+export function capturedRootOf(host) {
+    if (!hosts.has(host))
+        return null;
+    for (const root of liveRoots())
+        if (root.host === host)
+            return root;
+    return null;
+}
+/** Run `listener` for every root captured from now on. Returns an unsubscribe. */
+export function onShadowRoot(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+/**
+ * Patch `attachShadow` to record each root as it is created, and sweep the roots that already exist.
+ *
+ * The sweep can only find OPEN roots (there is no other way in), so a closed root attached before
+ * install stays unreachable — correctly, and it is declared as such.
+ */
+export function installShadowRegistry() {
+    const proto = Element.prototype;
+    // Through captureMethod, like every other patch site here: reading a method to hold and restore it
+    // is the one thing `unbound-method` exists to flag, and the intention is named there once.
+    const original = captureMethod(proto, 'attachShadow');
+    if (typeof original !== 'function')
+        return () => undefined;
+    installs += 1;
+    const patched = function patchedAttachShadow(init) {
+        const root = original.call(this, init);
+        record(root, this);
+        return root;
+    };
+    proto.attachShadow = patched;
+    const sweep = (node) => {
+        for (const el of node.querySelectorAll('*')) {
+            const root = el.shadowRoot;
+            if (root === null)
+                continue;
+            record(root, el); // idempotent — a root the patch already caught is skipped inside
+            sweep(root);
+        }
+    };
+    if (document.documentElement !== null)
+        sweep(document.documentElement);
+    return () => {
+        // Restore only if nobody patched over us; clobbering a later patch is worse than leaving ours.
+        if (captureMethod(proto, 'attachShadow') === patched)
+            proto.attachShadow = original;
+        installs -= 1;
+        if (installs > 0)
+            return; // another install is still using this state
+        roots.clear();
+        listeners.clear();
+    };
+}

package/dist/dom/snapshot.d.ts

@@ -2,7 +2,8 @@ import { SnapshotMode } from '@reticlehq/core';
 interface SnapshotStatus {
     route: string;
     title: string;
-    visibleDialogs: string[];
+    /** Open dialogs, OMITTED when there are none — absence means "no dialog is up". */
+    visibleDialogs?: string[];
 }
 export interface SnapshotResult {
     tree: string;
@@ -25,4 +26,3 @@ interface SnapshotOptions {
 /** Build the semantic accessibility snapshot of the page or a subtree. */
 export declare function buildSnapshot(options?: SnapshotOptions): SnapshotResult;
 export {};
-//# sourceMappingURL=snapshot.d.ts.map

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

@@ -8,9 +8,9 @@ export { registerAdapter, identifyComponent, readComponentState, elementHasHover
 export type { ReticleAdapter, ComponentInfo, ComponentSource } from './registry/adapters.js';
 export { registerStore, unregisterStore, storeNames, readStores, readStoresWithTruncation, } from './registry/stores.js';
 export type { StoreGetter, StoreLike, StoreSubscribe } from './registry/stores.js';
-export { tanstackQueryStore, jotaiStore, xstateStore, valtioStore, mobxStore, pushStore, } from './registry/store-adapters.js';
-export type { QuerySnapshot } from './registry/store-adapters.js';
-export { registerCapabilities, getCapabilities, hasCapabilities } from './registry/capabilities.js';
+export { tanstackQueryStore, jotaiStore, xstateStore, valtioStore, mobxStore, recoilStore, svelteStore, piniaStore, pushStore, } from './registry/store-adapters.js';
+export type { QuerySnapshot, RecoilAtomSnapshot } from './registry/store-adapters.js';
+export { registerCapabilities, getCapabilities, hasCapabilities, setCapabilitiesListener, } from './registry/capabilities.js';
 export type { Capabilities, CapabilitiesInput, CapabilityFlow } from './registry/capabilities.js';
 export { createReticleEmitter } from './registry/emitter.js';
 export type { ReticleEmitter, EmitterTarget, CreateReticleEmitterOptions, } from './registry/emitter.js';
@@ -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

@@ -18,9 +18,9 @@ export { registerStore, unregisterStore, storeNames, readStores, readStoresWithT
 // Adapters for state libraries that do not natively expose `{getState, subscribe}`. zustand and Redux
 // need none of these; TanStack Query is the one that matters most, because a stale-cache bug fires no
 // request and renders a plausible value, so the cache is the only witness.
-export { tanstackQueryStore, jotaiStore, xstateStore, valtioStore, mobxStore, pushStore, } from './registry/store-adapters.js';
+export { tanstackQueryStore, jotaiStore, xstateStore, valtioStore, mobxStore, recoilStore, svelteStore, piniaStore, pushStore, } from './registry/store-adapters.js';
 // Capability registry: the app self-describes its testable surface via reticle.describe.
-export { registerCapabilities, getCapabilities, hasCapabilities } from './registry/capabilities.js';
+export { registerCapabilities, getCapabilities, hasCapabilities, setCapabilitiesListener, } from './registry/capabilities.js';
 // SDK helpers: adopt the recommended integration patterns without boilerplate.
 export { createReticleEmitter } from './registry/emitter.js';
 export { commitAndSignal } from './registry/commit-and-signal.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