@reticlehq/browser 2.2.0 → 2.3.0

package/dist/dom/desktop-capture.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Desktop screenshots, asked of the runtime that owns the window.
+ *
+ * A browser tab is captured through CDP. A desktop webview has no CDP endpoint, so the pixels have
+ * to come from the shell — and the shell is the only party that can produce them CORRECTLY.
+ *
+ * Capturing a screen *region* instead was tried and rejected: it photographs the glass, so an app
+ * window sitting behind the editor yields a picture of the editor, saved as a visual baseline that a
+ * later diff would trust. A screenshot tool that can silently return another window's pixels is
+ * worse than one that returns nothing — it manufactures exactly the false green Reticle exists to
+ * eliminate. Electron's `webContents.capturePage()` reads the window's own backing store instead:
+ * correct while occluded, correct while backgrounded, and needing no screen-recording permission.
+ *
+ * Both desktop runtimes can do this, each through its own shell API — `webContents.capturePage()` on
+ * Electron, and on Tauri the platform's own webview snapshot (`WKWebView.takeSnapshot`, WebView2
+ * `CapturePreview`, or WebKitGTK's snapshot). None of them reads the screen, so all stay correct with
+ * the window occluded, hidden, or running headless with nothing on screen at all.
+ *
+ * The app opts in with one line in its main process (`@reticlehq/electron/main`) or one Rust command
+ * (`reticle-tauri`). Absent that, this returns `{ ok: false }` and the tool reports no-provider
+ * rather than guessing.
+ */
+export interface CaptureResult {
+    ok: boolean;
+    /**
+     * Filesystem path of the captured PNG, written by the desktop shell.
+     *
+     * A path, not the image bytes: the SDK's transport sanitizer caps every string at 64KB, so a
+     * base64 PNG came back SILENTLY TRUNCATED and was saved as a "successful" screenshot that no
+     * decoder could read. The daemon and the app always share a machine here (the bridge is loopback),
+     * so handing over a path keeps the image off the event wire entirely.
+     */
+    path?: string;
+    reason?: string;
+}
+export declare function captureDesktopWindow(fullPage?: boolean): Promise<CaptureResult>;

package/dist/dom/desktop-capture.js

@@ -0,0 +1,113 @@
+/**
+ * Desktop screenshots, asked of the runtime that owns the window.
+ *
+ * A browser tab is captured through CDP. A desktop webview has no CDP endpoint, so the pixels have
+ * to come from the shell — and the shell is the only party that can produce them CORRECTLY.
+ *
+ * Capturing a screen *region* instead was tried and rejected: it photographs the glass, so an app
+ * window sitting behind the editor yields a picture of the editor, saved as a visual baseline that a
+ * later diff would trust. A screenshot tool that can silently return another window's pixels is
+ * worse than one that returns nothing — it manufactures exactly the false green Reticle exists to
+ * eliminate. Electron's `webContents.capturePage()` reads the window's own backing store instead:
+ * correct while occluded, correct while backgrounded, and needing no screen-recording permission.
+ *
+ * Both desktop runtimes can do this, each through its own shell API — `webContents.capturePage()` on
+ * Electron, and on Tauri the platform's own webview snapshot (`WKWebView.takeSnapshot`, WebView2
+ * `CapturePreview`, or WebKitGTK's snapshot). None of them reads the screen, so all stay correct with
+ * the window occluded, hidden, or running headless with nothing on screen at all.
+ *
+ * The app opts in with one line in its main process (`@reticlehq/electron/main`) or one Rust command
+ * (`reticle-tauri`). Absent that, this returns `{ ok: false }` and the tool reports no-provider
+ * rather than guessing.
+ */
+import { RETICLE_IPC_GLOBAL, RETICLE_TAURI_CAPTURE_COMMAND, VisualReason } from '@reticlehq/core';
+import { nativeFrame } from '../timers/native-timers.js';
+import { RETICLE_OVERLAY } from './dom-ignore.js';
+/**
+ * What a shell returns when it can photograph the viewport but not the whole scroll height.
+ *
+ * Only WebKitGTK can render a full document offscreen; `capturePage()` and `takeSnapshot` both give
+ * what is composited. Downgrading silently would be the worst option available: the caller asked for
+ * the content below the fold, would get an image without it, and would bank it as a baseline that a
+ * later diff reports as matching. So the shells say so, and the tool reports the reason.
+ */
+const FULL_PAGE_UNSUPPORTED_MARKER = VisualReason.FULL_PAGE_UNSUPPORTED;
+const TAURI_INTERNALS_GLOBAL = '__TAURI_INTERNALS__';
+/**
+ * Tauri's capture path, used when no preload-installed channel exists.
+ *
+ * Electron can install `RETICLE_IPC_GLOBAL` from its preload, which runs before app code. Tauri has
+ * no preload stage at all, so requiring the same global would mean every Tauri app hand-writing a
+ * frontend shim — a setup step that silently yields "no screenshots" when forgotten. Invoking the
+ * command directly removes the JavaScript side entirely: the app registers one Rust command and the
+ * SDK finds it. Absent that command the invoke rejects, and this reports no-provider like any other.
+ */
+function tauriCapture() {
+    const internals = window[TAURI_INTERNALS_GLOBAL];
+    if (typeof internals?.invoke !== 'function')
+        return undefined;
+    const invoke = internals.invoke.bind(internals);
+    return async (fullPage) => {
+        const path = await invoke(RETICLE_TAURI_CAPTURE_COMMAND, { fullPage: fullPage === true });
+        return typeof path === 'string' ? path : null;
+    };
+}
+/**
+ * Take Reticle's own UI out of the shot, then put it back.
+ *
+ * The shell photographs the composited window, so anything Reticle mounted is IN the picture — and
+ * the presenter panel is the worst possible thing to bank into a visual baseline, because it renders
+ * live session state: an event tally, a log tail, a run badge. A baseline captured with it is a
+ * baseline of Reticle's own UI as much as the app's, and the next `reticle_visual_diff` reports a
+ * change that belongs entirely to the observer. That is measuring the instrument.
+ *
+ * Two frames, not one: the first lets the style change apply, the second lets the compositor present
+ * it — capture before that and the shell photographs the pre-hide window anyway. Both are BOUNDED
+ * frames, which is load-bearing rather than defensive: a headless Tauri window is hidden, and a
+ * hidden webview never fires `requestAnimationFrame` at all, so a raw double-rAF here deadlocked
+ * every capture until the command timed out at 8s. Restoration runs in a `finally`, so a capture
+ * that throws still leaves the panel on screen for the human watching.
+ */
+async function withReticleUiHidden(capture) {
+    // The SAME selector the snapshot layer already uses to keep Reticle's own DOM out of what the
+    // agent reads — the presenter panel, the cursor, the glow, and the annotator's "flag a bug"
+    // button. One definition: a root that leaked into snapshots once would otherwise leak into
+    // baselines the second time someone added one.
+    const roots = [...document.querySelectorAll(RETICLE_OVERLAY)];
+    const previous = roots.map((el) => el.style.visibility);
+    // `visibility`, not `display`: it keeps the element's box, so hiding cannot reflow the app
+    // underneath and change the very layout the screenshot is meant to record.
+    for (const el of roots)
+        el.style.visibility = 'hidden';
+    try {
+        if (roots.length > 0) {
+            await nativeFrame();
+            await nativeFrame();
+        }
+        return await capture();
+    }
+    finally {
+        roots.forEach((el, i) => {
+            el.style.visibility = previous[i] ?? '';
+        });
+    }
+}
+export async function captureDesktopWindow(fullPage = false) {
+    const channel = window[RETICLE_IPC_GLOBAL];
+    const capture = typeof channel?.capture === 'function' ? channel.capture : tauriCapture();
+    if (capture === undefined) {
+        return { ok: false, reason: 'no desktop capture helper installed' };
+    }
+    try {
+        const path = await withReticleUiHidden(() => capture(fullPage));
+        return typeof path === 'string' && path.length > 0
+            ? { ok: true, path }
+            : { ok: false, reason: 'capture returned no image' };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return reason.includes(FULL_PAGE_UNSUPPORTED_MARKER)
+            ? { ok: false, reason: FULL_PAGE_UNSUPPORTED_MARKER }
+            : { ok: false, reason };
+    }
+}

package/dist/dom/dom-ignore.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Selectors for Reticle's own presenter overlay (cursor, HUD, glow) + the annotator's "flag a bug"
+ * UI (`data-reticle-mark`) — never observed/snapshotted. The annotator mounts by DEFAULT with the
+ * presenter, so omitting its selector here leaked a phantom `<button>Flag a bug</button>` into every
+ * snapshot and streamed its highlight-box mutations/transitions as if the APP had rendered them.
+ */
+export declare const RETICLE_OVERLAY = "[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow],[data-reticle-mark]";
 /** Let the host app add selectors to exclude from snapshots (e.g. its own dev widgets). */
 export declare function setIgnoreSelectors(selectors: string[]): void;
 /** True if the element is part of Reticle's own presenter overlay. */
@@ -6,4 +13,3 @@ export declare function isReticleOverlay(el: Element): boolean;
 export declare function isReticleUi(node: Element | null): boolean;
 /** True if the element should be excluded from snapshots/queries (Reticle overlay or dev overlay). */
 export declare function isIgnored(el: Element): boolean;
-//# sourceMappingURL=dom-ignore.d.ts.map

package/dist/dom/dom-ignore.js

@@ -4,7 +4,7 @@
  * presenter, so omitting its selector here leaked a phantom `<button>Flag a bug</button>` into every
  * snapshot and streamed its highlight-box mutations/transitions as if the APP had rendered them.
  */
-const RETICLE_OVERLAY = '[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow],[data-reticle-mark]';
+export const RETICLE_OVERLAY = '[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow],[data-reticle-mark]';
 /** Known third-party dev overlays to keep out of snapshots (Agentation, Next dev UI). */
 const DEV_OVERLAYS = '[data-agentation],#__next-build-watcher,nextjs-portal,[data-nextjs-dialog],[data-nextjs-toast]';
 let extraIgnore = '';
@@ -33,4 +33,3 @@ export function isIgnored(el) {
         : `${RETICLE_OVERLAY},${DEV_OVERLAYS}`;
     return el.closest(sel) !== null;
 }
-//# sourceMappingURL=dom-ignore.js.map

package/dist/dom/occlusion.d.ts

@@ -6,4 +6,3 @@
  * we never false-positive an occlusion. Reticle's own HUD is never treated as an occluder.
  */
 export declare function hitTestOccluder(el: Element, rect: DOMRect): Element | null;
-//# sourceMappingURL=occlusion.d.ts.map

package/dist/dom/occlusion.js

@@ -18,4 +18,3 @@ export function hitTestOccluder(el, rect) {
     const lands = top === el || el.contains(top) || top.contains(el);
     return lands ? null : top;
 }
-//# sourceMappingURL=occlusion.js.map

package/dist/dom/query.d.ts

@@ -16,4 +16,3 @@ export declare function matchQuery(query: ElementQuery, state?: ElementState, li
  * do — silently put the server back to counting survivors and calling that the answer.
  */
 export declare function runQuery(query: ElementQuery, limit?: number): QueryResult;
-//# sourceMappingURL=query.d.ts.map

package/dist/dom/query.js

@@ -1,6 +1,9 @@
 import { queryAllByRole, queryAllByText, queryAllByLabelText, queryAllByPlaceholderText, queryAllByTestId, queryAllByAltText, } from '@testing-library/dom';
 import { DATA_RETICLE_SOURCE_ATTR, ElementState, QueryBy, REDACTED_VALUE, TRANSPORT_LIMITS, } from '@reticlehq/core';
+import { isFrame, isHtmlElement } from './realm.js';
+import { capturedRootOf } from './shadow-registry.js';
 import { describe, getStates, isVisible } from './a11y.js';
+import { isIgnored } from './dom-ignore.js';
 import { isSensitiveKey } from '../security/serialization.js';
 import { getCapabilities } from '../registry/capabilities.js';
 import { identifyComponent } from '../registry/adapters.js';
@@ -22,11 +25,11 @@ function resolveContainer(scope) {
     if (scope === undefined)
         return { container: document.body, scopeMissing: false };
     const byRef = refs.resolve(scope);
-    if (byRef instanceof HTMLElement)
+    if (isHtmlElement(byRef))
         return { container: byRef, scopeMissing: false };
     try {
         const found = document.querySelector(scope);
-        if (found instanceof HTMLElement)
+        if (isHtmlElement(found))
             return { container: found, scopeMissing: false };
     }
     catch {
@@ -138,18 +141,56 @@ function findIn(container, query) {
  * A closed root is deliberately unreachable — `element.shadowRoot` is null by design, and the SDK
  * reports that as a blind spot rather than pretending to see through it.
  */
-function openShadowRootsUnder(root) {
+/**
+ * A same-origin `<iframe>`'s body, or null when the document is unreachable.
+ *
+ * Cross-origin access THROWS in some engines and yields null in others, so both are handled — and
+ * both mean the same thing here: not ours to read. That case is not a silent skip, it is reported
+ * separately as a declared blind spot.
+ */
+function readableFrameBody(frame) {
+    try {
+        return frame.contentDocument?.body ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** How deep to follow frames-inside-frames before giving up. Real consoles nest one, maybe two. */
+const FRAME_DEPTH_MAX = 3;
+/**
+ * Every root beneath the scope that the page can read but `querySelectorAll` will not reach:
+ * open shadow roots, and the documents of SAME-ORIGIN iframes.
+ *
+ * The iframe half was measured missing: a same-origin frame whose text the page could read straight
+ * off `contentDocument` returned zero matches from `query`, and coverage said nothing about it — the
+ * worst combination, an absent-element answer for content that is right there. Cross-origin frames
+ * are a genuinely different case and stay unread; they are declared instead.
+ */
+function embeddedRootsUnder(root) {
     const found = [];
-    const walk = (node) => {
+    const walk = (node, depth) => {
         for (const el of node.querySelectorAll('*')) {
-            const shadow = el.shadowRoot;
+            const shadow = el.shadowRoot ?? capturedRootOf(el);
             if (shadow !== null) {
+                // A ShadowRoot is a DocumentFragment; the Testing-Library queries accept any HTMLElement-like
+                // container, and every call site only reads from it.
                 found.push(shadow);
-                walk(shadow); // nested web components
+                walk(shadow, depth); // nested web components
+                continue;
             }
+            if (depth >= FRAME_DEPTH_MAX)
+                continue;
+            if (!isFrame(el))
+                continue;
+            const body = readableFrameBody(el);
+            if (body === null)
+                continue; // cross-origin — declared, not searched
+            found.push(body);
+            walk(body, depth + 1);
         }
     };
-    walk(root);
+    walk(root, 0);
     return found;
 }
 /**
@@ -185,16 +226,22 @@ function findCandidates(query) {
         for (const el of els) {
             if (seen.has(el))
                 continue; // reachable from both host and root — count once
+            // Reticle's OWN UI is not part of the app under test. `snapshot` has always excluded it; query
+            // did not, so the presenter panel and the annotator answered `by: role` like app controls —
+            // measured on a real merchant dashboard, 7 of the 40 buttons an agent could see were ours
+            // ("Pause", "End", "Minimise the panel", "Export", "Flag a bug for the agent"). Two of those
+            // share a NAME with a real control on that page, so an agent resolving "Export" could drive the
+            // observer instead of the app and then reason about the result. Filtered here, at the one
+            // collection point, so every entry path (by role/text/testid, shadow roots, scoped) is covered.
+            if (isIgnored(el))
+                continue;
             seen.add(el);
             out.push(el);
         }
     };
     collect(findIn(container, query));
-    for (const shadow of openShadowRootsUnder(container)) {
-        // A ShadowRoot is a DocumentFragment; the Testing-Library queries accept any HTMLElement-like
-        // container, and every call site below only reads from it.
-        collect(findIn(shadow, query));
-    }
+    for (const embedded of embeddedRootsUnder(container))
+        collect(findIn(embedded, query));
     return { candidates: out, scopeMissing };
 }
 /** Longest attribute value returned; one enormous href must not blow the response budget. */
@@ -351,6 +398,8 @@ function buildEmptyHint(query) {
     const all = container.querySelectorAll(`[${TESTID_ATTR}]`);
     const present = [];
     for (const el of Array.from(all)) {
+        if (isIgnored(el))
+            continue; // the "what IS here" hint must not advertise Reticle's own UI either
         const id = el.getAttribute(TESTID_ATTR);
         if (id !== null && id.length > 0 && !present.includes(id)) {
             present.push(id);
@@ -388,4 +437,3 @@ export function runQuery(query, limit) {
     }
     return { elements: result.elements, count: result.count, ...scopeFields };
 }
-//# sourceMappingURL=query.js.map

package/dist/dom/realm.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Cross-realm type tests.
+ *
+ * `instanceof` compares against ONE realm's constructor. An element inside a same-origin `<iframe>`
+ * lives in that document's realm, so `frameButton instanceof HTMLElement` — evaluated with the top
+ * window's `HTMLElement` — is FALSE for a perfectly ordinary button.
+ *
+ * That is not theoretical. Once `query` learned to descend into same-origin frames, it returned the
+ * frame's button correctly and `act` then rejected the ref with "is not an HTMLElement": found, and
+ * unusable. A find you cannot act on is worse than a miss, because it reads as a product bug in the
+ * app rather than in the tool.
+ *
+ * These resolve the constructor from the NODE's own document instead, so an element is measured
+ * against its own realm. Same-realm nodes behave exactly as `instanceof` did.
+ */
+export declare const isElement: (n: unknown) => n is Element;
+export declare const isImage: (n: unknown) => n is HTMLImageElement;
+export declare const isHtmlElement: (n: unknown) => n is HTMLElement;
+export declare const isInput: (n: unknown) => n is HTMLInputElement;
+export declare const isTextArea: (n: unknown) => n is HTMLTextAreaElement;
+export declare const isSelect: (n: unknown) => n is HTMLSelectElement;
+export declare const isButton: (n: unknown) => n is HTMLButtonElement;
+export declare const isForm: (n: unknown) => n is HTMLFormElement;
+export declare const isFrame: (n: unknown) => n is HTMLIFrameElement;
+/**
+ * The prototype whose native value setter drives `el` — React and friends install their own accessor
+ * on the instance, so a value write has to go through the prototype's. It must come from the
+ * ELEMENT's realm for the same reason as above.
+ */
+export declare function valuePrototypeOf(el: Element): object | undefined;

package/dist/dom/realm.js

@@ -0,0 +1,58 @@
+/**
+ * Cross-realm type tests.
+ *
+ * `instanceof` compares against ONE realm's constructor. An element inside a same-origin `<iframe>`
+ * lives in that document's realm, so `frameButton instanceof HTMLElement` — evaluated with the top
+ * window's `HTMLElement` — is FALSE for a perfectly ordinary button.
+ *
+ * That is not theoretical. Once `query` learned to descend into same-origin frames, it returned the
+ * frame's button correctly and `act` then rejected the ref with "is not an HTMLElement": found, and
+ * unusable. A find you cannot act on is worse than a miss, because it reads as a product bug in the
+ * app rather than in the tool.
+ *
+ * These resolve the constructor from the NODE's own document instead, so an element is measured
+ * against its own realm. Same-realm nodes behave exactly as `instanceof` did.
+ */
+/** The constructor named `name` in the realm that owns `node`, or undefined if there isn't one. */
+function ctorIn(node, name) {
+    if (node === null || typeof node !== 'object')
+        return undefined;
+    // A Document owns itself; every other node reports an ownerDocument.
+    const doc = node.ownerDocument ?? node;
+    const view = doc.defaultView;
+    if (view === null || view === undefined)
+        return undefined;
+    return view[name];
+}
+/**
+ * `node instanceof <name>`, evaluated in the node's own realm.
+ *
+ * Falls back to the ambient constructor when the node has no view — a detached document, or a jsdom
+ * fragment — so behaviour outside a browser is unchanged.
+ */
+function isIn(node, name, ambient) {
+    const ctor = ctorIn(node, name) ?? ambient;
+    return typeof ctor === 'function' && node instanceof ctor;
+}
+export const isElement = (n) => isIn(n, 'Element', typeof Element === 'undefined' ? undefined : Element);
+export const isImage = (n) => isIn(n, 'HTMLImageElement', typeof HTMLImageElement === 'undefined' ? undefined : HTMLImageElement);
+export const isHtmlElement = (n) => isIn(n, 'HTMLElement', typeof HTMLElement === 'undefined' ? undefined : HTMLElement);
+export const isInput = (n) => isIn(n, 'HTMLInputElement', typeof HTMLInputElement === 'undefined' ? undefined : HTMLInputElement);
+export const isTextArea = (n) => isIn(n, 'HTMLTextAreaElement', typeof HTMLTextAreaElement === 'undefined' ? undefined : HTMLTextAreaElement);
+export const isSelect = (n) => isIn(n, 'HTMLSelectElement', typeof HTMLSelectElement === 'undefined' ? undefined : HTMLSelectElement);
+export const isButton = (n) => isIn(n, 'HTMLButtonElement', typeof HTMLButtonElement === 'undefined' ? undefined : HTMLButtonElement);
+export const isForm = (n) => isIn(n, 'HTMLFormElement', typeof HTMLFormElement === 'undefined' ? undefined : HTMLFormElement);
+export const isFrame = (n) => isIn(n, 'HTMLIFrameElement', typeof HTMLIFrameElement === 'undefined' ? undefined : HTMLIFrameElement);
+/**
+ * The prototype whose native value setter drives `el` — React and friends install their own accessor
+ * on the instance, so a value write has to go through the prototype's. It must come from the
+ * ELEMENT's realm for the same reason as above.
+ */
+export function valuePrototypeOf(el) {
+    const name = isTextArea(el) ? 'HTMLTextAreaElement' : 'HTMLInputElement';
+    const ctor = ctorIn(el, name);
+    if (typeof ctor !== 'function')
+        return undefined;
+    const proto = ctor.prototype;
+    return typeof proto === 'object' && proto !== null ? proto : undefined;
+}

package/dist/dom/refs.d.ts

@@ -35,4 +35,3 @@ export declare class RefRegistry {
 }
 /** Process-wide registry shared by snapshot, query, and the action executor. */
 export declare const refs: RefRegistry;
-//# sourceMappingURL=refs.d.ts.map

package/dist/dom/refs.js

@@ -108,4 +108,3 @@ export class RefRegistry {
 }
 /** Process-wide registry shared by snapshot, query, and the action executor. */
 export const refs = new RefRegistry();
-//# sourceMappingURL=refs.js.map

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