@reticlehq/browser 2.13.0 → 2.14.0

package/dist/dom/snapshot.js

@@ -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/source.d.ts

@@ -1,53 +1,9 @@
-/**
- * Where an element is defined in the codebase.
- *
- * This is the single most valuable thing Reticle can hand an agent that has to fix what Reticle just
- * found. Locating the right FILE is what turns a report into an edit; without it the agent pays for a
- * search loop that the instrumentation already knows the answer to.
- *
- * Two lookups, because the callers have very different cost budgets:
- *
- *   sourceFromDom  — reads the babel-stamped `data-reticle-source` off the nearest ancestor. One
- *                    native upward walk, bounded by tree depth. Safe to call per element on paths
- *                    that describe many elements at once (query results, snapshots).
- *   sourceFor      — prefers a framework adapter's answer (which knows the component that RENDERED
- *                    the element, not just the nearest stamped host) and falls back to the DOM. The
- *                    adapter path walks the fiber tree, so this belongs on single-element paths
- *                    (inspect, act, review) and not in a loop.
- *
- * Both report source independently of how the element is ANCHORED. Anchor answers "how do I find this
- * again", source answers "where is it written" — collapsing the two once meant that adding a
- * data-testid, which Reticle's own docs recommend, silently removed the source pointer.
- */
 export interface SourceLocation {
     file: string;
     line: number;
 }
-/** Parse a `data-reticle-source="file:line:column"` value into `{ file, line }` (column dropped). */
 export declare function parseSourceAttr(value: string | null): SourceLocation | undefined;
-/** The nearest babel-stamped source at or above this element. Cheap enough to call in bulk. */
 export declare function sourceFromDom(el: Element): SourceLocation | undefined;
-/** Best source for the element: the framework adapter's, else the nearest babel-stamped attribute. */
 export declare function sourceFor(el: Element, adapterSource: SourceLocation | undefined): SourceLocation | undefined;
-/**
- * Does ANY element in this document carry a source stamp?
- *
- * The difference between "this element has no stamp" and "the stamping loader is not running at
- * all" — two answers that look identical from a single missing `source` field, and that call for
- * completely different next actions. The first is ordinary: not every element sits under a stamped
- * host. The second means "fix at file:line", the single most-cited reason to reach for Reticle over
- * a generic DOM tool, is silently unavailable for the whole session — and it has been discovered by
- * reading the adapter's source rather than from anything Reticle said.
- *
- * One `querySelector`, which stops at the first hit, so this is cheap enough to answer on a
- * single-element path like inspect. It is only consulted when a source is already missing.
- */
 export declare function documentHasSourceStamps(doc: Document): boolean;
-/**
- * `file:line` — the form an agent can act on directly.
- *
- * Deliberately a single compact string rather than an object: it costs a couple of dozen bytes on a
- * descriptor that may repeat hundreds of times in one response, and every consumer of it is either
- * opening an editor or printing it.
- */
 export declare function formatSource(source: SourceLocation | undefined): string | undefined;

package/dist/dom/source.js

@@ -1,28 +1,5 @@
-/**
- * Where an element is defined in the codebase.
- *
- * This is the single most valuable thing Reticle can hand an agent that has to fix what Reticle just
- * found. Locating the right FILE is what turns a report into an edit; without it the agent pays for a
- * search loop that the instrumentation already knows the answer to.
- *
- * Two lookups, because the callers have very different cost budgets:
- *
- *   sourceFromDom  — reads the babel-stamped `data-reticle-source` off the nearest ancestor. One
- *                    native upward walk, bounded by tree depth. Safe to call per element on paths
- *                    that describe many elements at once (query results, snapshots).
- *   sourceFor      — prefers a framework adapter's answer (which knows the component that RENDERED
- *                    the element, not just the nearest stamped host) and falls back to the DOM. The
- *                    adapter path walks the fiber tree, so this belongs on single-element paths
- *                    (inspect, act, review) and not in a loop.
- *
- * Both report source independently of how the element is ANCHORED. Anchor answers "how do I find this
- * again", source answers "where is it written" — collapsing the two once meant that adding a
- * data-testid, which Reticle's own docs recommend, silently removed the source pointer.
- */
 import { DATA_RETICLE_SOURCE_ATTR } from '@reticlehq/core';
-/** Stamped by @reticlehq/babel-plugin / @reticlehq/vite-plugin in dev as `file:line:column`. */
 const SOURCE_ATTR = DATA_RETICLE_SOURCE_ATTR;
-/** Parse a `data-reticle-source="file:line:column"` value into `{ file, line }` (column dropped). */
 export function parseSourceAttr(value) {
     if (null === value)
         return undefined;
@@ -35,40 +12,18 @@ export function parseSourceAttr(value) {
         return undefined;
     return { file, line };
 }
-/** The nearest babel-stamped source at or above this element. Cheap enough to call in bulk. */
 export function sourceFromDom(el) {
     const host = el.closest(`[${SOURCE_ATTR}]`);
     return host !== null ? parseSourceAttr(host.getAttribute(SOURCE_ATTR)) : undefined;
 }
-/** Best source for the element: the framework adapter's, else the nearest babel-stamped attribute. */
 export function sourceFor(el, adapterSource) {
     if (adapterSource !== undefined)
         return { file: adapterSource.file, line: adapterSource.line };
     return sourceFromDom(el);
 }
-/**
- * Does ANY element in this document carry a source stamp?
- *
- * The difference between "this element has no stamp" and "the stamping loader is not running at
- * all" — two answers that look identical from a single missing `source` field, and that call for
- * completely different next actions. The first is ordinary: not every element sits under a stamped
- * host. The second means "fix at file:line", the single most-cited reason to reach for Reticle over
- * a generic DOM tool, is silently unavailable for the whole session — and it has been discovered by
- * reading the adapter's source rather than from anything Reticle said.
- *
- * One `querySelector`, which stops at the first hit, so this is cheap enough to answer on a
- * single-element path like inspect. It is only consulted when a source is already missing.
- */
 export function documentHasSourceStamps(doc) {
     return doc.querySelector(`[${SOURCE_ATTR}]`) !== null;
 }
-/**
- * `file:line` — the form an agent can act on directly.
- *
- * Deliberately a single compact string rather than an object: it costs a couple of dozen bytes on a
- * descriptor that may repeat hundreds of times in one response, and every consumer of it is either
- * opening an editor or printing it.
- */
 export function formatSource(source) {
     return source === undefined ? undefined : `${source.file}:${String(source.line)}`;
 }

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 {};

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;