@reticlehq/browser 2.13.1 → 3.1.0

package/dist/dom/shadow-registry.js

@@ -1,63 +1,11 @@
-/**
- * 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)
@@ -70,7 +18,6 @@ function sweep() {
         roots.delete(oldest.value);
     }
 }
-/** The live roots behind the weak entries. */
 function liveRoots() {
     const out = [];
     for (const ref of roots) {
@@ -82,10 +29,6 @@ function liveRoots() {
 }
 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);
@@ -99,15 +42,12 @@ function record(root, 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;
@@ -116,21 +56,12 @@ export function capturedRootOf(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;
@@ -146,19 +77,18 @@ export function installShadowRegistry() {
             const root = el.shadowRoot;
             if (null === root)
                 continue;
-            record(root, el); // idempotent — a root the patch already caught is skipped inside
+            record(root, el);
             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
+            return;
         roots.clear();
         listeners.clear();
     };

package/dist/dom/snapshot.d.ts

@@ -2,12 +2,7 @@ import { SnapshotMode } from '@reticlehq/core';
 interface SnapshotStatus {
     route: string;
     title: string;
-    /** Open dialogs, OMITTED when there are none — absence means "no dialog is up". */
     visibleDialogs?: string[];
-    /**
-     * Present ONLY when a whole-page snapshot came back near-empty because an open overlay
-     * aria-hidden the rest of the page (#397). Absence means the page is not hidden behind an overlay.
-     */
     overlayHidingPage?: string;
 }
 export interface SnapshotResult {
@@ -15,32 +10,11 @@ export interface SnapshotResult {
     status: SnapshotStatus;
     nodes: number;
     truncated: boolean;
-    /**
-     * True when a `scope` was given but resolved to nothing. The snapshot then covers NOTHING rather
-     * than silently falling back to the whole page — an agent snapshotting "the modal" after it closed
-     * must not receive the entire page as if it were the modal.
-     */
     scopeMissing?: boolean;
-    /**
-     * How many MEANINGFUL nodes the lean walk passed over, present only in a lean mode and only when
-     * non-zero. This is what stops an empty `interactive` tree reading as an empty page — the mode is
-     * a role filter, and a production app whose controls carry no roles yields nothing while being
-     * full of things to drive. It shipped untyped: the value was spread into the result and every
-     * consumer had to reach for it without a type, including the tool that builds the note from it.
-     */
     leanSkipped?: number;
-    /**
-     * Refs of the subtree roots the walk never entered, present ONLY when `truncated`. This is the
-     * cut's own frontier: re-snapshot each with `{ scope: ref, includeRoot: true }` and the union is
-     * the whole tree. Without it `truncated` says only THAT the read stopped, never WHERE, so nobody
-     * could finish it — and a reader who does not finish it must not conclude anything is ABSENT.
-     */
+    hiddenSkipped?: number;
+    domElements?: number;
     unread?: string[];
-    /**
-     * True when the frontier itself did not fit in `MAX_UNREAD_BRANCHES`, so `unread` is a prefix of
-     * the branches that were cut. Completion is then impossible from this read, and the difference
-     * between "impossible" and "not attempted" is the whole point of saying so.
-     */
     unreadOverflow?: true;
 }
 interface SnapshotOptions {
@@ -48,23 +22,8 @@ interface SnapshotOptions {
     mode?: SnapshotMode | undefined;
     maxNodes?: number | undefined;
     maxDepth?: number | undefined;
-    /**
-     * Emit the scope element's OWN line before its descendants. Off by default (a scoped snapshot has
-     * always been the subtree UNDER the scope); the completion re-read needs it, because the branch it
-     * is re-reading is exactly the node the truncated walk stopped before emitting.
-     */
     includeRoot?: boolean | undefined;
 }
-/**
- * Cap on how many cut branches one snapshot names.
- *
- * A hostile or merely huge DOM can cut thousands of siblings at once (a non-virtualized grid does it
- * routinely), and a frontier that large is neither affordable to send nor useful to re-read one at a
- * time. Fifty is well above what a real page's cut produces — the frontier is the branches at the
- * node cap, not the nodes themselves — and small enough that the list stays a hint rather than a
- * second snapshot. Past it the read declares `unreadOverflow` instead of quietly sending fewer.
- */
 export declare const MAX_UNREAD_BRANCHES = 50;
-/** Build the semantic accessibility snapshot of the page or a subtree. */
 export declare function buildSnapshot(options?: SnapshotOptions): SnapshotResult;
 export {};

package/dist/dom/snapshot.js

@@ -2,7 +2,7 @@ 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 { refs } from './addressing/refs.js';
 import { isIgnored, isReticleOverlay } from './dom-ignore.js';
 const INTERACTIVE = new Set([
     'button',
@@ -20,62 +20,35 @@ const INTERACTIVE = new Set([
     'option',
 ]);
 const SKIP_TAGS = new Set(['script', 'style', 'noscript', 'template', 'head', 'meta', 'link']);
-/** Roles whose whole purpose is announcing a change; both imply an implicit aria-live. */
 const ANNOUNCE_ROLES = new Set(['alert', 'status']);
-/**
- * Is this element the app SAYING something changed?
- *
- * INTERACTIVE mode keeps only actionable elements, which silently drops the one node that explains
- * why an action did nothing — the error the app just rendered. An agent told to prefer the cheaper
- * mode was structurally blind to the failure it had caused: the click reports settled with a DOM
- * mutation, and the lean snapshot shows the same controls as before. Live regions exist precisely
- * to announce state changes to a consumer that cannot see the screen, which is exactly the agent,
- * so they are the principled exception — and a bounded one, since a page has very few.
- */
 function announces(el, role) {
     if (ANNOUNCE_ROLES.has(role))
         return true;
     const live = el.getAttribute('aria-live');
     return live !== null && 'off' !== live;
 }
-/** Cap on inlined text content so a verbose node can't blow up the snapshot. */
 const TEXT_MAX = 80;
-/**
- * Concatenated DIRECT text of an element (its own text nodes, not descendants' — those are
- * captured when their own element is walked, so no duplication). Collapsed + truncated.
- * This is what makes a silent removal of non-interactive content (e.g. a KPI card) visible:
- * the accessibility role tree alone omits generic containers' text.
- */
 function directText(el) {
     let out = '';
     for (const node of el.childNodes) {
-        if (3 === node.nodeType /* Node.TEXT_NODE */)
+        if (3 === node.nodeType)
             out += node.textContent ?? '';
     }
     const collapsed = out.replace(/\s+/g, ' ').trim();
     return collapsed.length > TEXT_MAX ? `${collapsed.slice(0, TEXT_MAX)}…` : collapsed;
 }
-/**
- * Cap on how many cut branches one snapshot names.
- *
- * A hostile or merely huge DOM can cut thousands of siblings at once (a non-virtualized grid does it
- * routinely), and a frontier that large is neither affordable to send nor useful to re-read one at a
- * time. Fifty is well above what a real page's cut produces — the frontier is the branches at the
- * node cap, not the nodes themselves — and small enough that the list stays a hint rather than a
- * second snapshot. Past it the read declares `unreadOverflow` instead of quietly sending fewer.
- */
 export const MAX_UNREAD_BRANCHES = 50;
-/** Cheap skips that need no computed style (tags, overlays, aria-hidden, [hidden]). */
+function hiddenByMarkup(el) {
+    if ('true' === el.getAttribute('aria-hidden'))
+        return true;
+    return el instanceof HTMLElement && el.hidden;
+}
 function skipEarly(el) {
     if (SKIP_TAGS.has(el.tagName.toLowerCase()))
         return true;
     if (isIgnored(el))
-        return true; // Reticle overlay + known dev overlays
-    if ('true' === el.getAttribute('aria-hidden'))
         return true;
-    if (el instanceof HTMLElement && el.hidden)
-        return true;
-    return false;
+    return hiddenByMarkup(el);
 }
 function stateSuffix(el) {
     const states = getStates(el).filter((s) => s === ElementState.DISABLED ||
@@ -84,42 +57,30 @@ function stateSuffix(el) {
         s === ElementState.FOCUSED);
     return states.length > 0 ? ` [${states.join(',')}]` : '';
 }
-function formatLine(el, depth, role, name, layout) {
+function formatLine(el, depth, role, name, layout, ownText = '') {
     const indent = '  '.repeat(depth);
     const value = getValue(el);
-    // A testid stands in for the accessible name when there is none. Including a role-less control and
-    // then printing it as a bare `- generic` is worse than leaving it out: it is visible and it cannot
-    // be addressed. This is the name its author gave it.
     const label = name;
     const namePart = label.length > 0 ? ` "${label}"` : '';
     const refPart = INTERACTIVE.has(role) || label.length > 0 ? ` (ref=${refs.refFor(el)})` : '';
     const valuePart = value !== undefined && value.length > 0 ? ` [value="${value}"]` : '';
     const layoutPart = layout.length > 0 ? ` [${layout}]` : '';
-    return `${indent}- ${role}${namePart}${refPart}${valuePart}${layoutPart}${stateSuffix(el)}`;
+    const textPart = ownText.length > 0 ? ` [text="${ownText}"]` : '';
+    return `${indent}- ${role}${namePart}${refPart}${valuePart}${textPart}${layoutPart}${stateSuffix(el)}`;
 }
-/** A generic container's own text content, with no ref (kept lean — text isn't actionable). */
 function formatTextLine(depth, text) {
     return `${'  '.repeat(depth)}- text "${text}"`;
 }
-/**
- * Compact signature of an element's own layout when it is a grid/flex container. A layout
- * regression (e.g. grid columns 2 -> 3) leaves the role+text tree identical, so a role-only
- * snapshot is blind to it; this line makes it visible. Empty for non-container elements.
- */
 function layoutSignature(style) {
     if (null === style)
         return '';
     const display = style.display;
-    // Grid track templates are the high-signal CLS case (column/row count + sizing) and there are
-    // few grid containers per page. Flex is intentionally excluded: nearly every row is a flex
-    // box, so signing them all floods the snapshot for little regression value.
     if ('grid' === display || 'inline-grid' === display) {
         const cols = style.gridTemplateColumns;
         return cols !== '' && cols !== 'none' ? `grid-cols:${cols}` : 'grid';
     }
     return '';
 }
-/** Record a cut branch on the frontier, declaring an overflow rather than shortening it silently. */
 function recordUnread(branches, ctx) {
     for (const branch of branches) {
         if (ctx.unread.length >= MAX_UNREAD_BRANCHES) {
@@ -129,23 +90,11 @@ function recordUnread(branches, ctx) {
         ctx.unread.push(refs.refFor(branch));
     }
 }
-/**
- * The children to walk under `parent`, piercing boundaries a plain `.children` misses: an OPEN shadow
- * root renders as part of the element (web components / design systems), and a SAME-ORIGIN iframe's
- * body is real content. Cross-origin frames throw on access and are skipped by design. Without this,
- * an entire category of modern apps is invisible to reticle_snapshot (systematic false negative).
- */
 function pierceChildren(parent) {
     const out = [...parent.children];
-    // 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);
-    // 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;
@@ -153,84 +102,39 @@ function pierceChildren(parent) {
                 out.push(...body.children);
         }
         catch {
-            /* cross-origin frame — inaccessible by design */
         }
     }
     return out;
 }
-/** Emit one element (if it earns a line) and descend into it. Split out of `walk` so the completion
- * re-read can start AT a branch root — the node the truncated walk stopped just before emitting. */
 function visit(child, depth, ctx, inLive) {
-    if (skipEarly(child))
+    if (skipEarly(child)) {
+        if (hiddenByMarkup(child))
+            ctx.hiddenSkipped += 1;
         return;
-    // Resolve computed style ONCE per node (the dominant snapshot cost) and thread it into both the
-    // display-none skip and the layout signature — was two forced style resolutions per node.
+    }
     const view = child.ownerDocument.defaultView;
     const style = view !== null ? view.getComputedStyle(child) : null;
-    if (style !== null && 'none' === style.display)
+    if (style !== null && 'none' === style.display) {
+        ctx.hiddenSkipped += 1;
         return;
+    }
     const role = getRole(child);
     const name = getAccessibleName(child);
     const interactive = INTERACTIVE.has(role);
-    // Announcements are exempt from leanness, and so is everything inside one: a live region whose
-    // message sits in a child element would otherwise be included as a contentless `- generic`.
     const announce = inLive || announces(child, role);
     const lean = ctx.mode === SnapshotMode.INTERACTIVE && !announce;
-    // A generic, unnamed container's own text content — only consulted outside INTERACTIVE mode,
-    // so the actionable-only view stays lean while FULL/meaningful views see content regressions.
-    const text = !lean && 'generic' === role && 0 === name.length ? directText(child) : '';
-    // Layout signature for grid/flex containers — makes CLS/layout regressions visible.
+    const text = !lean && 0 === name.length ? directText(child) : '';
     const layout = lean ? '' : layoutSignature(style);
-    // Actionable WITHOUT an interactive role, which is most of the real web.
-    //
-    // `interactive` is a role test, and a large share of production UI carries no roles at all.
-    // Measured on MarkText, a production Electron editor: `mode:"interactive"` returned an EMPTY tree
-    // where `mode:"full"` found 47 nodes, because its whole block picker is `<div>`s. An empty tree is
-    // indistinguishable from an empty page, and the tool description recommends this mode as the
-    // default — so the cheaper view told an agent there was nothing to drive.
-    //
-    // A `data-testid` ONLY. It is a handle its author put there to be driven, and it marks one element
-    // rather than a subtree.
-    //
-    // `cursor: pointer` was tried here as a second signal — it is how an app tells a HUMAN that a
-    // thing is clickable — and measured on MarkText it was a disaster: interactive went from 0 nodes
-    // and 72 tokens to 180 nodes and 870, against a FULL snapshot of 47 nodes and 424. The pointer
-    // cursor is inherited, so every wrapper div inside a clickable row matched, and the lean mode
-    // became twice the size of the complete one while adding nothing but nameless `- generic` lines.
-    // The mode's whole claim is that it is smaller; a signal that cannot tell a control from its
-    // ancestors cannot be used to decide what a control is.
-    // `data-testid` was tried here as a second signal, on the premise that it is a handle its author
-    // put there to be driven. Measured against our own instrumented bench app, the premise is false:
-    // the lean tree on its dashboard came to 16 nodes and 175 tokens, and EIGHT were display elements
-    // — kpi-deploys, kpi-success, kpi-p95, kpi-services, area-chart, activity-feed, brand. Half the
-    // "actionable" view was things nothing can act on, and the mode roughly doubled to carry them; the
-    // benchmark read it as a 4% verification-efficiency regression. A testid marks what a TEST cares
-    // about, which is a superset of what a driver can use.
-    //
-    // It did not even help the case it shipped for: MarkText's controls carry no testid. `leanSkipped`
-    // is what fixed that — an empty tree that says how many it passed over is no longer an empty page.
-    //
-    // `cursor: pointer` was tried too and was worse: interactive went from 0 nodes and 72 tokens to
-    // 180 and 870 against a FULL snapshot of 47/424, because the pointer cursor is inherited and every
-    // wrapper div inside a clickable row matched. A signal that cannot tell a control from its
-    // ancestors cannot decide what a control is.
     const actionable = interactive;
-    // A testid still makes an element MEANINGFUL, so `full` keeps it and can name and address it. It
-    // just is not evidence that the element is ACTIONABLE, which is the only question lean mode asks.
     const meaningful = actionable || role !== 'generic' || name.length > 0 || text.length > 0 || layout.length > 0;
     const include = lean ? actionable : meaningful;
-    // Counted, not just skipped. An empty INTERACTIVE tree is indistinguishable from an empty page,
-    // and on a real app the difference is everything: MarkText's block picker is 20+ live controls
-    // that carry no role, no testid and no pointer cursor, so the lean view is empty while the app is
-    // full of things to drive. Knowing how many were passed over is what turns "" into "look again in
-    // full mode" — see the note the snapshot tool builds from this.
     if (lean && !include && meaningful)
         ctx.leanSkipped += 1;
     if (include) {
         ctx.nodes += 1;
-        ctx.lines.push(text.length > 0 && 0 === name.length && 0 === layout.length
+        ctx.lines.push('generic' === role && text.length > 0 && 0 === layout.length
             ? formatTextLine(depth, text)
-            : formatLine(child, depth, role, name, layout));
+            : formatLine(child, depth, role, name, layout, text));
         walk(child, depth + 1, ctx, announce);
     }
     else {
@@ -244,8 +148,6 @@ function walk(parent, depth, ctx, inLive = false) {
     for (let index = 0; index < children.length; index += 1) {
         if (ctx.nodes >= ctx.maxNodes) {
             ctx.truncated = true;
-            // Everything from here on is unread, not absent. Naming the frontier is what makes the cut
-            // recoverable — see `unread` on SnapshotResult.
             recordUnread(children.slice(index), ctx);
             return;
         }
@@ -254,16 +156,6 @@ function walk(parent, depth, ctx, inLive = false) {
             visit(child, depth, ctx, inLive);
     }
 }
-/**
- * The APP's open dialogs. Reticle's own panels are excluded, always.
- *
- * The HUD's chat and report panels carry `role="dialog"` because that is the correct role for what
- * they are — but they are OUR surface, not the application's. Once the presenter became visible to
- * the tool surface (so that Reticle can be used to check its own HUD), every snapshot of every page
- * started reporting `visibleDialogs: ["Reticle agent chat"]`, telling the agent a modal was up when
- * the app had none. An agent that believes a dialog is open dismisses it before doing anything else,
- * which is a wasted action at best and a dismissed REAL dialog at worst.
- */
 function collectDialogs(root) {
     const nodes = root.querySelectorAll('[role="dialog"], dialog[open], [aria-modal="true"]');
     const names = [];
@@ -275,40 +167,22 @@ 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.
- */
-/**
- * A focus-trap modal (Radix and friends) marks every sibling of the portal root aria-hidden. The
- * snapshot walk correctly skips aria-hidden subtrees, so a whole-page snapshot can return only the
- * overlay's own nodes and nothing else -- indistinguishable from "this page is empty". If the
- * overlay's cleanup is stuck (common on a throttled tab), every later action then dispatches with no
- * effect because the overlay genuinely captures pointer events. Say so instead of returning a
- * near-empty tree with no explanation. (#397)
- */
 function overlayHidingPage(root) {
-    // Only meaningful for a whole-page snapshot; a scoped snapshot is the subtree the caller chose.
     if (root !== document.body)
         return undefined;
     const dialogs = document.body.querySelectorAll('[role="dialog"], dialog[open], [aria-modal="true"]');
     let modal;
+    let hiddenCandidate;
     for (const d of dialogs) {
-        // Never OUR overlay. Reticle's HUD must not be able to explain the app's absence with itself:
-        // that turns "the page did not render" into "an overlay is covering it", which sends the reader
-        // to dismiss a panel that was never the problem.
         if (isReticleOverlay(d))
             continue;
         if (isVisible(d)) {
             modal = d;
             break;
         }
+        hiddenCandidate ??= d;
     }
+    modal ??= hiddenCandidate;
     if (modal === undefined)
         return undefined;
     const modalEl = modal;
@@ -331,13 +205,11 @@ function buildStatus(root) {
         ...(overlay !== undefined ? { overlayHidingPage: overlay } : {}),
     };
 }
-/** Build the semantic accessibility snapshot of the page or a subtree. */
 export function buildSnapshot(options = {}) {
     const mode = options.mode ?? SnapshotMode.FULL;
     const scopeEl = options.scope !== undefined
         ? (refs.resolve(options.scope) ?? document.querySelector(options.scope))
         : document.body;
-    // A given-but-missing scope snapshots NOTHING and says so — never a silent whole-page fallback.
     const scopeMissing = options.scope !== undefined && !(scopeEl instanceof Element);
     const root = scopeEl instanceof Element ? scopeEl : document.body;
     const status = buildStatus(root);
@@ -351,6 +223,7 @@ export function buildSnapshot(options = {}) {
         lines: [],
         nodes: 0,
         leanSkipped: 0,
+        hiddenSkipped: 0,
         truncated: false,
         mode,
         maxNodes: options.maxNodes ?? 400,
@@ -367,7 +240,9 @@ export function buildSnapshot(options = {}) {
         status,
         nodes: ctx.nodes,
         truncated: ctx.truncated,
+        ...(0 === ctx.nodes ? { domElements: root.querySelectorAll('*').length } : {}),
         ...(ctx.leanSkipped > 0 ? { leanSkipped: ctx.leanSkipped } : {}),
+        ...(ctx.hiddenSkipped > 0 ? { hiddenSkipped: ctx.hiddenSkipped } : {}),
         ...(ctx.unread.length > 0 ? { unread: ctx.unread } : {}),
         ...(ctx.unreadOverflow ? { unreadOverflow: true } : {}),
     };

package/dist/dom/theme.d.ts

@@ -1,48 +1,11 @@
-/**
- * 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.
- */
 interface ThemeReport {
-    /**
-     * The ONE design token matching the text color, or null. Null both when nothing matches and when
-     * several tokens share the color: the previous behaviour picked an arbitrary winner and the caller
-     * could not tell, which is the whole defect. Read `colorTokens` for the full answer; this field
-     * stays for callers that only ever wanted the unambiguous case.
-     */
     colorToken: string | null;
-    /** Every design token whose resolved value is the text color. Empty when the color is off-palette. */
     colorTokens: string[];
-    /** The one design token matching the background color, or null (same abstain-on-tie rule). */
     backgroundToken: string | null;
-    /** Every design token whose resolved value is the background color. */
     backgroundTokens: string[];
-    /** True when a set, opaque color matches NO design token — a theme violation worth surfacing. */
     offTheme: boolean;
-    /** How many color tokens resolved under the active theme (0 ⇒ offTheme is never asserted). */
     tokenCount: number;
-    /** Theme scope active at capture time, e.g. `.dark`, so two results taken apart are comparable. */
     themeScope: string | null;
 }
-/** Report an element's theme compliance from its computed style. */
 export declare function themeReport(cs: CSSStyleDeclaration): ThemeReport;
 export {};