@reticlehq/browser 2.13.1 → 3.1.0

package/dist/dom/theme.js

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

package/dist/dom/virtualized.d.ts

@@ -1,19 +1,2 @@
-/**
- * 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

@@ -1,27 +1,5 @@
-/**
- * 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) {
@@ -29,14 +7,12 @@ function rowHost(container) {
         const only = 1 === children.length ? 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;
@@ -58,7 +34,6 @@ export function unmountedRowsIn(container) {
             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;
@@ -67,11 +42,9 @@ export function unmountedRowsIn(container) {
         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);

package/dist/edit-epoch.d.ts

@@ -1,32 +1,10 @@
-import { type RefRegistry } from './dom/refs.js';
+import { type RefRegistry } from './dom/addressing/refs.js';
 export declare class EditEpoch {
     #private;
-    /** The registry is injected for the same reason the clock is: the interesting property is the
-     *  RELATION between when a ref was minted and when an edit landed, and a global has no seam. */
     constructor(registry: RefRegistry);
-    /**
-     * How many hot updates this document has applied.
-     *
-     * `NO_EDITS_OBSERVED` means exactly that and never "none happened": most pages Reticle instruments
-     * have no channel that could report one, so absence here is UNKNOWN.
-     */
     get current(): number;
-    /** Subscribe to a hot-update channel if one was handed in. Anything else is silently ignored —
-     *  no channel is the normal case, not an error. */
     observe(hot: unknown): void;
-    /** Record that an update was applied, naming the files it changed (which may be none). */
     applied(files: readonly string[]): void;
-    /**
-     * The refusal for a ref that no longer resolves — saying WHY when the page can tell us.
-     *
-     * The generic wording is untouched and stays at the front: it is already tuned, and the server's
-     * recovery table matches on it. When the ref predates the last hot update the diagnosis is
-     * appended, because "you edited TripCard.tsx and it re-rendered" is a next step and "that ref is
-     * stale" is a dead end. A ref minted AFTER the last update gets the generic message unchanged —
-     * blaming an edit for an ordinary post-click stale ref would be a confident wrong answer, which is
-     * worse than the vague right one.
-     */
     staleRefMessage(ref: string): string;
 }
-/** The epoch of the page, paired with the process-wide ref registry it has to reason against. */
 export declare const editEpoch: EditEpoch;

package/dist/edit-epoch.js

@@ -1,38 +1,9 @@
 import { NO_EDITS_OBSERVED } from '@reticlehq/core';
-import { echoRef, refs } from './dom/refs.js';
-/**
- * What the page can tell us about its own source being edited underneath it.
- *
- * The agent driving Reticle edits source and re-verifies in a loop. When an edit lands, the dev
- * server hot-updates the module and the framework re-renders: DOM nodes are REPLACED, every ref the
- * agent holds points at a detached node — and there was no navigation, so the document is the same
- * one and `documentId` never moves. The agent got a generic "that ref is stale" and could not tell
- * its own edit landing from a bug in the app it was verifying.
- *
- * DELIBERATELY NOT A BUILD INTEGRATION. Nothing here watches files, reads the user's repo or knows
- * what a module graph is. The page is told by its own dev server that it hot-updated; this records
- * that it happened and what it named, and that is the whole feature.
- */
-/**
- * Vite's "the update has been applied" event, on a hot context.
- *
- * `vite:afterUpdate` rather than `vite:beforeUpdate`: the point of the epoch is that the DOM has
- * been replaced, and before the update it has not been yet.
- *
- * The SDK does NOT depend on Vite — it ships to Next, Electron, Tauri and plain pages, and it cannot
- * read `import.meta.hot` of its own module in any of them (a dependency is pre-bundled by Vite's
- * optimizer and gets no hot context at all). The channel is handed IN by whoever has one, and this
- * name is the only Vite-shaped thing in the SDK.
- */
+import { echoRef, refs } from './dom/addressing/refs.js';
 const HOT_UPDATE_APPLIED = 'vite:afterUpdate';
-/** How many changed files a refusal names before it stops being a diagnosis and starts being a list. */
 const MAX_NAMED_FILES = 3;
-/** The exact substring the server's recovery table keys off. Changing it silently unclassifies. */
 const STALE_REF_REFUSAL = 'no longer resolves to an element';
-/** The clause that turns a dead end into a diagnosis, and the one the server's table matches on. */
 const CODE_CHANGED = 'the code changed underneath it';
-/** Anything object-shaped, as a bag of unknowns. The payload comes from the page, so nothing about
- *  its shape is guaranteed and every field has to be checked before it is read. */
 function fields(value) {
     return null !== value && 'object' === typeof value
         ? value
@@ -41,7 +12,6 @@ function fields(value) {
 function isHotLike(value) {
     return 'function' === typeof fields(value)?.['on'];
 }
-/** The file paths a hot-update payload named, narrowed from `unknown`. */
 function updatedPaths(payload) {
     const updates = fields(payload)?.['updates'];
     if (!Array.isArray(updates))
@@ -58,43 +28,22 @@ export class EditEpoch {
     #epoch = NO_EDITS_OBSERVED;
     #files = [];
     #refs;
-    /** The registry is injected for the same reason the clock is: the interesting property is the
-     *  RELATION between when a ref was minted and when an edit landed, and a global has no seam. */
     constructor(registry) {
         this.#refs = registry;
     }
-    /**
-     * How many hot updates this document has applied.
-     *
-     * `NO_EDITS_OBSERVED` means exactly that and never "none happened": most pages Reticle instruments
-     * have no channel that could report one, so absence here is UNKNOWN.
-     */
     get current() {
         return this.#epoch;
     }
-    /** Subscribe to a hot-update channel if one was handed in. Anything else is silently ignored —
-     *  no channel is the normal case, not an error. */
     observe(hot) {
         if (!isHotLike(hot))
             return;
         hot.on(HOT_UPDATE_APPLIED, (payload) => this.applied(updatedPaths(payload)));
     }
-    /** Record that an update was applied, naming the files it changed (which may be none). */
     applied(files) {
         this.#epoch += 1;
         this.#files = files.slice(0, MAX_NAMED_FILES);
         this.#refs.markEdited();
     }
-    /**
-     * The refusal for a ref that no longer resolves — saying WHY when the page can tell us.
-     *
-     * The generic wording is untouched and stays at the front: it is already tuned, and the server's
-     * recovery table matches on it. When the ref predates the last hot update the diagnosis is
-     * appended, because "you edited TripCard.tsx and it re-rendered" is a next step and "that ref is
-     * stale" is a dead end. A ref minted AFTER the last update gets the generic message unchanged —
-     * blaming an edit for an ordinary post-click stale ref would be a confident wrong answer, which is
-     * worse than the vague right one.
-     */
     staleRefMessage(ref) {
         const generic = `ref '${echoRef(ref)}' ${STALE_REF_REFUSAL}`;
         if (!this.#refs.mintedBeforeLastEdit(ref))
@@ -104,5 +53,4 @@ export class EditEpoch {
             'replaced the node. Query again for a fresh ref: this is your own edit landing, not the app failing.');
     }
 }
-/** The epoch of the page, paired with the process-wide ref registry it has to reason against. */
 export const editEpoch = new EditEpoch(refs);

package/dist/index.d.ts

@@ -1,11 +1,10 @@
-import { Reticle } from './reticle.js';
-export declare const reticle: Reticle;
+export { reticle } from './reticle-singleton.js';
 export { Reticle } from './reticle.js';
 export type { ReticleConnectOptions } from './reticle.js';
 export { SESSION_AUTO } from '@reticlehq/core';
 export { setIgnoreSelectors } from './dom/dom-ignore.js';
-export { registerAdapter, identifyComponent, readComponentState, elementHasHoverHandlers, adapterNames, } from './registry/adapters.js';
-export type { ReticleAdapter, ComponentInfo, ComponentSource } from './registry/adapters.js';
+export { registerAdapter, identifyComponent, readComponentState, elementHasHoverHandlers, adapterNames, } from './registry/stores/adapters.js';
+export type { ReticleAdapter, ComponentInfo, ComponentSource } from './registry/stores/adapters.js';
 export { registerStore, unregisterStore, storeNames, readStores, readStoresWithTruncation, sourceOwner, markAdapterSource, } from './registry/stores.js';
 export type { StoreGetter, StoreLike, StoreSubscribe } from './registry/stores.js';
 export { tanstackQueryStore, jotaiStore, xstateStore, valtioStore, mobxStore, recoilStore, svelteStore, piniaStore, pushStore, } from './registry/store-adapters.js';
@@ -23,6 +22,6 @@ export type { ChartReport, ChartFinding, CanvasChartData } from './dom/chart.js'
 export { matchQuery, runQuery } from './dom/query.js';
 export { executeAction, executeSequence } from './actions/actions.js';
 export { describe, getRole, getAccessibleName, getStates, isVisible } from './dom/a11y.js';
-export { refs, RefRegistry } from './dom/refs.js';
+export { refs, RefRegistry } from './dom/addressing/refs.js';
 export { Annotator, installAnnotator, type AnnotatorDeps } from './review/annotator.js';
 export { resolveMarkAnchor, type MarkAnchor } from './review/mark-anchor.js';

package/dist/index.js

@@ -1,43 +1,19 @@
-import { Reticle } from './reticle.js';
-/**
- * The singleton embedded in the host app: `import { reticle } from '@reticlehq/browser'`.
- * Persisted on a global so HMR module re-evaluation reuses the same (already-connected)
- * instance instead of creating a second bridge connection (feedback #7).
- */
-const globalStore = globalThis;
-export const reticle = (globalStore.__reticleInstance ??= new Reticle());
+export { reticle } from './reticle-singleton.js';
 export { Reticle } from './reticle.js';
-// Session label sentinel: pass as `session` (or omit it) to get a unique per-tab id (no collisions).
 export { SESSION_AUTO } from '@reticlehq/core';
-// Exclude your own dev widgets from snapshots/observers.
 export { setIgnoreSelectors } from './dom/dom-ignore.js';
-// Adapter API (used by @reticlehq/react and other framework adapters).
-export { registerAdapter, identifyComponent, readComponentState, elementHasHoverHandlers, adapterNames, } from './registry/adapters.js';
-// Store registry: pull live framework/store state on demand.
-export { registerStore, unregisterStore, storeNames, readStores, readStoresWithTruncation, 
-// Which name a store SOURCE is registered under. The React adapter discovers stores from the fiber
-// tree and needs this to tell "the app already wired this exact store" from "this is another one" —
-// a question neither the name nor the read value can answer.
-sourceOwner, markAdapterSource, } from './registry/stores.js';
-// 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 { registerAdapter, identifyComponent, readComponentState, elementHasHoverHandlers, adapterNames, } from './registry/stores/adapters.js';
+export { registerStore, unregisterStore, storeNames, readStores, readStoresWithTruncation, sourceOwner, markAdapterSource, } from './registry/stores.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, 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';
 export { registerReticleDomain } from './registry/domains.js';
-// Lower-level building blocks (useful for tests and advanced embedding).
 export { buildSnapshot } from './dom/snapshot.js';
-// Chart inspection. Surfaced automatically on any element descriptor that contains faulty plot
-// geometry (see ElementDescriptor.chart), and exported for direct use — canvasChartData is the only
-// route to a canvas chart's data, since its pixels are not DOM.
 export { inspectChart, canvasChartData } from './dom/chart.js';
 export { matchQuery, runQuery } from './dom/query.js';
 export { executeAction, executeSequence } from './actions/actions.js';
 export { describe, getRole, getAccessibleName, getStates, isVisible } from './dom/a11y.js';
-export { refs, RefRegistry } from './dom/refs.js';
+export { refs, RefRegistry } from './dom/addressing/refs.js';
 export { Annotator, installAnnotator } from './review/annotator.js';
 export { resolveMarkAnchor } from './review/mark-anchor.js';

package/dist/observers/animation.d.ts

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

package/dist/observers/animation.js

@@ -1,14 +1,11 @@
 import { EventType } from '@reticlehq/core';
-import { refs } from '../dom/refs.js';
+import { refs } from '../dom/addressing/refs.js';
 import { isReticleOverlay } from '../dom/dom-ignore.js';
-/** Observe CSS animations + transitions and emit anim.start / anim.end. */
 export function installAnimation(emit) {
     const ac = new AbortController();
     const { signal } = ac;
     const onStart = (event) => {
         const target = event.target;
-        // Skip Reticle's own HUD keyframes (reticle-pulse/reticle-shimmer/…) so observe/record never
-        // self-pollute the agent's view of the app (matches the DOM observer's overlay filter).
         if (target instanceof Element && !isReticleOverlay(target)) {
             emit(EventType.ANIM_START, { name: event.animationName }, refs.refFor(target));
         }

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

@@ -1,31 +1,5 @@
 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. 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
- * same-origin and simply not navigated — not a blind spot.
- */
 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;

package/dist/observers/blind-spots.js

@@ -2,36 +2,14 @@ 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. 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.
- */
+import { nativeClearTimeout, nativeSetTimeout } from '../timers/native/native-timers.js';
 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.
+            continue;
         if (isCaptured(el))
             continue;
         if (el.children.length > 0)
@@ -44,11 +22,6 @@ export function countClosedShadowRoots() {
     }
     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
- * same-origin and simply not navigated — not a blind spot.
- */
 export function isCrossOriginFrame(frame) {
     const src = frame.getAttribute('src');
     if (null === src || 0 === src.length)
@@ -57,10 +30,9 @@ export function isCrossOriginFrame(frame) {
         return null === frame.contentDocument;
     }
     catch {
-        return true; // SecurityError on access is itself proof of cross-origin
+        return true;
     }
 }
-/** How many of the given frames are cross-origin (unobservable). */
 export function countCrossOriginFrames(frames) {
     let count = 0;
     for (const frame of frames)
@@ -71,31 +43,11 @@ 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
- * embed reports once. Reversible: disconnects the observer on teardown.
- */
-/**
- * How long added/removed nodes are allowed to pile up before the frame count is re-checked.
- *
- * A blind spot is a coverage caveat on a verdict, not a live signal — noticing an embed a fraction of
- * a second later costs nothing, while checking on every mutation costs a DOM scan per render.
- */
 const RECHECK_DEBOUNCE_MS = 250;
 export function installBlindSpots(emit) {
-    // 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 },
@@ -114,17 +66,6 @@ export function installBlindSpots(emit) {
         }
     };
     report();
-    // Coalesce rather than gate.
-    //
-    // This used to try to skip unrelated churn by testing each added/removed node with
-    // `n.querySelector('iframe')` — but that is a full subtree scan per mutated node, so a React commit
-    // mounting a 500-node panel paid a 500-node scan to decide whether to do a document scan. The gate
-    // cost more than the work, and it scaled with exactly the thing a large app does most.
-    //
-    // Since report() emits only when the count CHANGES, running it late and rarely is free. One
-    // debounced document scan per quarter-second replaces per-node scanning, and it is also more
-    // correct: the old gate's `querySelector` missed an iframe added inside a subtree whose own root
-    // was a text or comment node.
     let pending;
     const observer = new MutationObserver(() => {
         if (pending !== undefined)

package/dist/observers/console.d.ts

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