@reticlehq/browser 2.13.1 → 3.1.0

package/dist/actions/appeared-text.d.ts

@@ -1,26 +1,6 @@
-/**
- * Gathers the text an action put on the page, from mutation records the observer already receives.
- *
- * `domMutatedWithin` counts records and throws their content away, so a failed login reports
- * `ok / settled / mutated` and reads exactly like a successful one. The message the app rendered
- * was passing through this callback the whole time.
- *
- * Deliberately reports what appeared, never what it means: no error/success classification, no
- * guessing which fragment matters. Truncated, because a route change can add a whole page.
- */
 export declare class AppearedText {
     #private;
     collect(records: readonly MutationRecord[]): void;
-    /**
-     * `{ appeared }` when the APP added text, `{}` otherwise — an absent key means it added none.
-     *
-     * `wrote` is the value the action itself just set, and is excluded: a textarea carries its value
-     * in a child text node, so a controlled one re-rendering after the write mutates characterData
-     * with the caller's own string. Handing that back is noise wearing the name of evidence, and
-     * `valueChanged` already reports that the write landed. Exact-match only, so an app that quotes
-     * your input inside a sentence of its own ("No results for zzz") is still reported — that is
-     * the app talking.
-     */
     effect(wrote?: string): {
         appeared?: string;
     };

package/dist/actions/appeared-text.js

@@ -1,34 +1,15 @@
 import { isIgnored } from '../dom/dom-ignore.js';
-/** Cap on the reported text. Enough for an error message, far short of a re-rendered page. */
 const APPEARED_MAX = 200;
-/** Separator between distinct fragments that appeared in the same window. */
 const JOIN = ' | ';
 const TEXT_NODE = 3;
-/** Any letter, in any script — Latin, Cyrillic, CJK, Arabic. */
 const HAS_LETTER = /\p{L}/u;
-/**
- * A fragment with no letters at all is not the app saying something.
- *
- * The Hostile fixture mutates a counter every 16ms, and clicking a button on that page reported
- * `appeared: "409"` — the ticker, not the action's effect. A count-up animation is exactly what
- * emits a bare number into the settle window, and a bare number carries no message a reader can
- * act on. Deliberately conservative: it drops only fragments with NO letters, so "status 500",
- * "3 items deleted" and "Could not save" all survive. An app whose only feedback is a naked
- * numeral loses it here — the snapshot still shows it, and that is the cheaper mistake.
- */
 function saysSomething(text) {
     return HAS_LETTER.test(text);
 }
-/**
- * Gathers the text an action put on the page, from mutation records the observer already receives.
- *
- * `domMutatedWithin` counts records and throws their content away, so a failed login reports
- * `ok / settled / mutated` and reads exactly like a successful one. The message the app rendered
- * was passing through this callback the whole time.
- *
- * Deliberately reports what appeared, never what it means: no error/success classification, no
- * guessing which fragment matters. Truncated, because a route change can add a whole page.
- */
+const MAX_MESSAGE_ELEMENTS = 3;
+function isRenderedView(node) {
+    return node instanceof Element && node.querySelectorAll('*').length > MAX_MESSAGE_ELEMENTS;
+}
 export class AppearedText {
     #seen = new Set();
     #length = 0;
@@ -37,28 +18,19 @@ export class AppearedText {
             if (this.#full())
                 return;
             if ('characterData' === record.type) {
-                // The NEW value; oldValue is not requested, so this is what the reader now sees.
                 this.#add(record.target.textContent, record.target.parentElement);
                 continue;
             }
             for (const node of record.addedNodes) {
                 if (this.#full())
                     return;
+                if (isRenderedView(node))
+                    continue;
                 const owner = TEXT_NODE === node.nodeType ? node.parentElement : elementOf(node);
                 this.#add(node.textContent, owner);
             }
         }
     }
-    /**
-     * `{ appeared }` when the APP added text, `{}` otherwise — an absent key means it added none.
-     *
-     * `wrote` is the value the action itself just set, and is excluded: a textarea carries its value
-     * in a child text node, so a controlled one re-rendering after the write mutates characterData
-     * with the caller's own string. Handing that back is noise wearing the name of evidence, and
-     * `valueChanged` already reports that the write landed. Exact-match only, so an app that quotes
-     * your input inside a sentence of its own ("No results for zzz") is still reported — that is
-     * the app talking.
-     */
     effect(wrote) {
         const said = [...this.#seen].filter((text) => text !== wrote);
         if (0 === said.length)
@@ -72,8 +44,6 @@ export class AppearedText {
         return this.#length > APPEARED_MAX;
     }
     #add(raw, owner) {
-        // Reticle's own overlay mutates constantly (the "live" panel); reporting it as the app's
-        // response would be worse than reporting nothing.
         if (null !== owner && isIgnored(owner))
             return;
         const text = (raw ?? '').replace(/\s+/g, ' ').trim();

package/dist/actions/danger-context.d.ts

@@ -0,0 +1,3 @@
+export declare function dangerousActionContext(el: HTMLElement): string;
+export declare function submitControlFor(el: HTMLElement): HTMLElement | null;
+export declare function requiresDangerousConfirmation(text: string, role?: string): boolean;

package/dist/actions/danger-context.js

@@ -0,0 +1,39 @@
+import { isDangerousActionText } from '@reticlehq/core';
+import { getAccessibleName } from '../dom/a11y.js';
+const LABEL_VALUED_INPUT_TYPES = new Set([
+    'submit',
+    'button',
+    'reset',
+    'image',
+]);
+function holdsUserText(el) {
+    if (el.isContentEditable)
+        return true;
+    if (el instanceof HTMLTextAreaElement)
+        return true;
+    if (el instanceof HTMLInputElement)
+        return !LABEL_VALUED_INPUT_TYPES.has(el.type.toLowerCase());
+    return false;
+}
+export function dangerousActionContext(el) {
+    const form = el.closest('form');
+    const ownText = holdsUserText(el)
+        ? ['', '']
+        : [el.textContent ?? '', el.getAttribute('value') ?? ''];
+    return [
+        getAccessibleName(el),
+        ...ownText,
+        el.getAttribute('title') ?? '',
+        el.getAttribute('aria-label') ?? '',
+        el.getAttribute('href') ?? '',
+        form?.getAttribute('action') ?? '',
+    ].join(' ');
+}
+const SUBMIT_CONTROL_SELECTOR = 'button[type="submit"], input[type="submit"], button:not([type]):not([type=""])';
+export function submitControlFor(el) {
+    const found = el.closest('form')?.querySelector(SUBMIT_CONTROL_SELECTOR);
+    return found instanceof HTMLElement ? found : null;
+}
+export function requiresDangerousConfirmation(text, role) {
+    return isDangerousActionText(text, role);
+}

package/dist/actions/scroll.d.ts

@@ -1,18 +1,16 @@
-/** Outcome of one container scroll — enough for the server to drive a find loop. */
 interface ScrollResult {
-    /** scrollTop actually moved (false ⇒ already at the end / not scrollable). */
     scrolled: boolean;
     scrollTop: number;
     scrollHeight: number;
     clientHeight: number;
-    /** At (or within 1px of) the bottom — no more rows to reveal by scrolling down. */
     atEnd: boolean;
+    atStart: boolean;
+    scrollLeft: number;
+    scrollWidth: number;
+    clientWidth: number;
+    atLeftEnd: boolean;
+    atRightEnd: boolean;
 }
-/**
- * Scroll the container of `ref` (or the document) down by `dy` (default ~one viewport) so a
- * virtualized list mounts its next window of rows. If `fraction` (0–1) is supplied, jumps
- * directly to that fraction of scrollHeight instead of stepping — enables bisection for large
- * lists where a specific row index is known (targetIndex / totalCount = fraction).
- */
-export declare function scrollContainer(ref: string | undefined, dy: number | undefined, fraction?: number): ScrollResult;
+export declare function scrollContainer(ref: string | undefined, dy: number | undefined, fraction?: number, dx?: number): ScrollResult;
+export declare function scrollFrom(base: Element | undefined, dy: number | undefined, fraction?: number, dx?: number): ScrollResult;
 export {};

package/dist/actions/scroll.js

@@ -1,43 +1,54 @@
-import { refs } from '../dom/refs.js';
+import { refs } from '../dom/addressing/refs.js';
 const FALLBACK_STEP_PX = 400;
 const VIEWPORT_FRACTION = 0.8;
-/** The nearest scrollable ancestor of `el` (inclusive), else the document scrolling element. */
-function nearestScrollable(el) {
+function nearestScrollable(el, axis) {
     let cur = el;
     while (cur !== null && cur !== document.body) {
-        const oy = getComputedStyle(cur).overflowY;
-        if (('auto' === oy || 'scroll' === oy) && cur.scrollHeight > cur.clientHeight)
+        const style = getComputedStyle(cur);
+        const overflow = 'x' === axis ? style.overflowX : style.overflowY;
+        const scrollable = 'x' === axis ? cur.scrollWidth > cur.clientWidth : cur.scrollHeight > cur.clientHeight;
+        if (('auto' === overflow || 'scroll' === overflow) && scrollable)
             return cur;
         cur = cur.parentElement;
     }
     return document.scrollingElement ?? document.documentElement;
 }
-/**
- * Scroll the container of `ref` (or the document) down by `dy` (default ~one viewport) so a
- * virtualized list mounts its next window of rows. If `fraction` (0–1) is supplied, jumps
- * directly to that fraction of scrollHeight instead of stepping — enables bisection for large
- * lists where a specific row index is known (targetIndex / totalCount = fraction).
- */
-export function scrollContainer(ref, dy, fraction) {
+export function scrollContainer(ref, dy, fraction, dx) {
     const base = ref !== undefined ? refs.resolve(ref) : null;
-    const target = base instanceof Element
-        ? nearestScrollable(base)
+    return scrollFrom(base instanceof Element ? base : undefined, dy, fraction, dx);
+}
+export function scrollFrom(base, dy, fraction, dx) {
+    const axis = dx !== undefined && dx !== 0 && (dy === undefined || 0 === dy) ? 'x' : 'y';
+    const target = base !== undefined
+        ? nearestScrollable(base, axis)
         : (document.scrollingElement ?? document.documentElement);
     const before = target.scrollTop;
+    const beforeLeft = target.scrollLeft;
     if (fraction !== undefined && fraction >= 0 && fraction <= 1) {
         target.scrollTop = Math.round(target.scrollHeight * fraction);
     }
     else {
-        const step = dy ?? (Math.round(target.clientHeight * VIEWPORT_FRACTION) || FALLBACK_STEP_PX);
-        target.scrollTop = before + step;
+        if (dx !== undefined && dx !== 0)
+            target.scrollLeft = beforeLeft + dx;
+        if (dx === undefined || (dy !== undefined && 0 !== dy)) {
+            const step = dy ?? (Math.round(target.clientHeight * VIEWPORT_FRACTION) || FALLBACK_STEP_PX);
+            target.scrollTop = before + step;
+        }
     }
     target.dispatchEvent(new Event('scroll', { bubbles: false }));
     const after = target.scrollTop;
+    const afterLeft = target.scrollLeft;
     return {
-        scrolled: after !== before,
+        scrolled: after !== before || afterLeft !== beforeLeft,
         scrollTop: after,
         scrollHeight: target.scrollHeight,
         clientHeight: target.clientHeight,
         atEnd: after + target.clientHeight >= target.scrollHeight - 1,
+        atStart: after <= 1,
+        scrollLeft: afterLeft,
+        scrollWidth: target.scrollWidth,
+        clientWidth: target.clientWidth,
+        atLeftEnd: afterLeft <= 1,
+        atRightEnd: afterLeft + target.clientWidth >= target.scrollWidth - 1,
     };
 }

package/dist/actions/synthetic/synthetic-input.d.ts

@@ -0,0 +1,2 @@
+export declare function isSyntheticInput(): boolean;
+export declare function asSyntheticInput<T>(dispatch: () => T): T;

package/dist/actions/synthetic/synthetic-input.js

@@ -0,0 +1,13 @@
+let depth = 0;
+export function isSyntheticInput() {
+    return depth > 0;
+}
+export function asSyntheticInput(dispatch) {
+    depth += 1;
+    try {
+        return dispatch();
+    }
+    finally {
+        depth -= 1;
+    }
+}

package/dist/actions/value-input.d.ts

@@ -1,33 +1,3 @@
-/**
- * Writing a value into a field, and the two preconditions that make it honest.
- *
- * Lifted out of actions.ts when that file hit the 600-line cap. It is a cohesive unit: every export
- * here exists so that a value write either lands as a real user's edit would, or is refused with a
- * reason — never forced through while reporting success.
- */
-/**
- * Set a value on a controlled input the way React expects (native setter + input event).
- * Returns the `input` event's dispatchEvent result (defaultPrevented of the primary event).
- */
 export declare function setNativeValue(el: HTMLInputElement | HTMLTextAreaElement, value: string): boolean;
-/**
- * Refuse to write to a field a person could not edit.
- *
- * `readonly` and `disabled` block USER input, not scripted assignment, so the prototype value setter
- * writes straight through both. Measured: filling a readonly input reported `ok:true` and
- * `valueChanged:true` with nothing in the effect block marking it read-only. That leaves the app in a
- * state no user could reach, and every conclusion drawn from what follows is about software nobody
- * can operate — the same reason the click path reports `occluded`, and the same choice Playwright
- * makes when it refuses to fill a non-editable element.
- */
-/**
- * A rich-text target is UNSUPPORTED, not a mistake by the caller.
- *
- * Every rich-text editor (TipTap, Quill, ProseMirror, Slate, Lexical) is `[contenteditable]`, and
- * these actions handle only input/textarea. `cannot fill a <div>` reads as "you picked the wrong
- * element" and sends the reader hunting for a better selector that does not exist. Support is not
- * faked: assigning textContent would update the DOM while the editor's own model kept the old value,
- * so the tool would report success for content the app will never submit.
- */
 export declare function assertNotRichText(el: HTMLElement, action: string): void;
 export declare function assertEditable(el: HTMLInputElement | HTMLTextAreaElement, action: string): void;

package/dist/actions/value-input.js

@@ -1,18 +1,6 @@
 import { captureValueSetter } from '../patching/capture-method.js';
 import { valuePrototypeOf } from '../dom/realm.js';
-/**
- * Writing a value into a field, and the two preconditions that make it honest.
- *
- * Lifted out of actions.ts when that file hit the 600-line cap. It is a cohesive unit: every export
- * here exists so that a value write either lands as a real user's edit would, or is refused with a
- * reason — never forced through while reporting success.
- */
-/**
- * Set a value on a controlled input the way React expects (native setter + input event).
- * Returns the `input` event's dispatchEvent result (defaultPrevented of the primary event).
- */
 export function setNativeValue(el, value) {
-    // Realm-aware: a controlled input inside a same-origin frame has its own prototype.
     const proto = valuePrototypeOf(el);
     const setter = proto === undefined ? undefined : captureValueSetter(proto);
     if (setter !== undefined) {
@@ -25,28 +13,7 @@ export function setNativeValue(el, value) {
     el.dispatchEvent(new Event('change', { bubbles: true }));
     return !notPrevented;
 }
-/**
- * Refuse to write to a field a person could not edit.
- *
- * `readonly` and `disabled` block USER input, not scripted assignment, so the prototype value setter
- * writes straight through both. Measured: filling a readonly input reported `ok:true` and
- * `valueChanged:true` with nothing in the effect block marking it read-only. That leaves the app in a
- * state no user could reach, and every conclusion drawn from what follows is about software nobody
- * can operate — the same reason the click path reports `occluded`, and the same choice Playwright
- * makes when it refuses to fill a non-editable element.
- */
-/**
- * A rich-text target is UNSUPPORTED, not a mistake by the caller.
- *
- * Every rich-text editor (TipTap, Quill, ProseMirror, Slate, Lexical) is `[contenteditable]`, and
- * these actions handle only input/textarea. `cannot fill a <div>` reads as "you picked the wrong
- * element" and sends the reader hunting for a better selector that does not exist. Support is not
- * faked: assigning textContent would update the DOM while the editor's own model kept the old value,
- * so the tool would report success for content the app will never submit.
- */
 export function assertNotRichText(el, action) {
-    // The ATTRIBUTE, not `isContentEditable`: jsdom does not implement the property, so a test would
-    // pass against a guard that never fires in the environment the unit suite runs in.
     const flag = el.getAttribute('contenteditable');
     if (el.isContentEditable || (flag !== null && flag !== 'false')) {
         throw new Error(`cannot ${action} a contenteditable element — rich-text editors keep their own document model, ` +

package/dist/commands/commands.d.ts

@@ -1,6 +1,4 @@
 export type CommandHandler = (args: Record<string, unknown>) => unknown;
-/** Query param appended on a hard reload to bypass the browser cache. */
 export declare const RELOAD_CACHE_BUST_PARAM = "_reticle_reload";
 export declare function resolveNavigationUrl(rawUrl: string, baseUrl: string): string | null;
-/** Map browser command names to handlers. Used by the transport on each COMMAND. */
 export declare function createCommandRegistry(): Map<string, CommandHandler>;

package/dist/commands/commands.js

@@ -1,23 +1,23 @@
 import { ActionType, ComponentStateReason, DANGEROUS_ACTION_CONFIRM_ARG, ElementQuerySchema, ReticleCommand, SnapshotMode, TRANSPORT_LIMITS, selectPath, capDepth, } from '@reticlehq/core';
 import { buildSnapshot } from '../dom/snapshot.js';
+import { paintContextOf } from '../dom/paint-context.js';
 import { matchQuery, runQuery } from '../dom/query.js';
 import { executeAction, executeSequence, dispatchWebMcp, } from '../actions/actions.js';
 import { describe } from '../dom/a11y.js';
-import { documentHasSourceStamps, sourceFor, formatSource } from '../dom/source.js';
+import { documentHasSourceStamps, sourceFor, formatSource } from '../dom/addressing/source.js';
 import { themeReport } from '../dom/theme.js';
-import { refs } from '../dom/refs.js';
+import { refs } from '../dom/addressing/refs.js';
 import { editEpoch } from '../edit-epoch.js';
 import { isButton, isInput } from '../dom/realm.js';
 import { hitTestOccluder } from '../dom/occlusion.js';
 import { readStorage } from '../observers/storage.js';
 import { captureDesktopWindow } from '../dom/desktop-capture.js';
-import { identifyComponent, readComponentState } from '../registry/adapters.js';
+import { identifyComponent, readComponentState } from '../registry/stores/adapters.js';
 import { readStoresWithTruncation, readStoresRaw, storeNames } from '../registry/stores.js';
 import { sanitizeWithReport } from '../security/serialization.js';
 import { getCapabilities } from '../registry/capabilities.js';
 import { freezeClock, advanceClock, resetClock, isClockFrozen } from '../timers/clock.js';
 import { scrollContainer } from '../actions/scroll.js';
-/** Query param appended on a hard reload to bypass the browser cache. */
 export const RELOAD_CACHE_BUST_PARAM = '_reticle_reload';
 function str(value) {
     return 'string' === typeof value ? value : undefined;
@@ -49,10 +49,6 @@ function queryFromArgs(args) {
         alt: str(args['alt']),
         component: str(args['component']),
         scope: str(args['scope']),
-        // The THIRD allowlist a query input has to appear in — tool schema, server forward, and here.
-        // `self` was in the first two and missing from this one, so a live call returned zero matches on
-        // an element that was plainly on the page, with no error to explain it. Same shape as the
-        // `attrs` drop below it.
         self: true === args['self'] ? true : undefined,
         attrs: Array.isArray(args['attrs'])
             ? args['attrs'].filter((a) => 'string' === typeof a)
@@ -62,20 +58,12 @@ function queryFromArgs(args) {
 }
 function inspect(ref) {
     const el = refs.resolve(ref);
-    // THROW, exactly as executeAction does. Returning an error payload made it a SUCCESSFUL command
-    // result, which the server then handed to reticle_inspect's outputSchema (ref/role/name/states/
-    // visible all required) — so the MCP layer answered -32602 Output validation error for the most
-    // ordinary thing that follows a click. The wording matches actions.ts because the server's
-    // recovery table keys off /no longer resolves to an element/ to attach the stale-ref recovery.
     if (null === el)
         throw new Error(editEpoch.staleRefMessage(ref));
     const rect = el.getBoundingClientRect();
     const component = identifyComponent(el);
     const view = el.ownerDocument.defaultView;
     const cs = view !== null ? view.getComputedStyle(el) : null;
-    // Computed style the a11y tree is blind to — `cursor` (does it look interactive?), display/
-    // visibility, and color/opacity — so a UI bug that leaves the element "present but unusable"
-    // (dead cursor, invisible, recolored) is observable in one inspect call.
     const styles = cs !== null
         ? {
             color: cs.color,
@@ -86,16 +74,7 @@ function inspect(ref) {
             visibility: cs.visibility,
         }
         : null;
-    // `describe()` carries the CHEAP source (the nearest babel-stamped ancestor), because it runs per
-    // element on paths that describe hundreds at once. inspect is a single-element path, so it takes
-    // the adapter's answer first — the component that actually RENDERED this element, not the nearest
-    // stamped host. `act` already did this; inspect did not, so the two tools disagreed about the same
-    // ref and inspect — the tool you reach for to ask where something lives — was the one saying null.
     const source = formatSource(sourceFor(el, component?.source));
-    // Say WHY the source is missing rather than omitting the field and leaving the caller to guess.
-    // No stamp anywhere in the document is decisive: the loader is not running, so no element will
-    // have one this session, and the fix is a build-config change rather than anything about this
-    // element. Only computed when `source` is already absent, so the ordinary path pays nothing.
     const sourceUnavailable = source !== undefined
         ? undefined
         : documentHasSourceStamps(el.ownerDocument)
@@ -106,31 +85,32 @@ function inspect(ref) {
         scrollHeight: el.scrollHeight,
         clientHeight: el.clientHeight,
         overflowY: cs?.overflowY ?? 'visible',
+        scrollLeft: el.scrollLeft,
+        scrollWidth: el.scrollWidth,
+        clientWidth: el.clientWidth,
+        overflowX: cs?.overflowX ?? 'visible',
     };
+    const paintContext = paintContextOf(el);
     return {
         ...describe(el),
         ...(source !== undefined ? { source } : {}),
+        ...(paintContext.length > 0 ? { paintContext } : {}),
         ...(sourceUnavailable !== undefined ? { sourceUnavailable } : {}),
         tag: el.tagName.toLowerCase(),
         href: el.getAttribute('href') ?? undefined,
         formAction: isButton(el) || isInput(el) ? (el.form?.getAttribute('action') ?? undefined) : undefined,
         formText: isButton(el) || isInput(el) ? (el.form?.textContent ?? undefined) : undefined,
         box: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
-        // True when another element sits over this one's center point — the click would hit the overlay,
-        // not this control (a z-index/overlay bug the DOM tree cannot show).
         occluded: isOccluded(el, rect),
         styles,
         scroll,
-        // Theme compliance vs the app's design tokens (off-theme colors a DOM tool can't judge).
         theme: cs !== null ? themeReport(cs) : null,
         component,
     };
 }
-/** Whether a NON-Reticle element covers this one's center point (a transparent overlay / z-index bug). */
 function isOccluded(el, rect) {
     return hitTestOccluder(el, rect) !== null;
 }
-/** Narrowing guard: an adapter returned a ComponentStateResult (has a boolean `ok`). */
 function isComponentStateResult(value) {
     return ('object' === typeof value && value !== null && 'ok' in value && 'boolean' === typeof value.ok);
 }
@@ -138,21 +118,8 @@ const COMPONENT_UNAVAILABLE = {
     ok: false,
     reason: ComponentStateReason.UNAVAILABLE,
 };
-/**
- * Stores are the reliable path. The `ref` component read is bounded: a stale ref, no
- * adapter, or an adapter returning a non-conforming value all collapse to a structured
- * `{ ok: false, reason }` — never a raw (possibly circular) object that could hang serialization.
- *
- * `path`/`depth` are applied HERE, in the page, BEFORE the value crosses the transport — so a scoped
- * read of a huge store (e.g. `deployments.0.status` on a 500-row store) returns only the small
- * sub-tree and is never truncated. (Previously selection ran server-side, AFTER the whole store had
- * already been size-capped in transit, which silently lost any field after a large array.)
- */
 function readState(ref, store, path, depth) {
     const names = storeNames();
-    // Scoped read: walk `path` into the RAW (uncapped) store, then sanitize only the selected sub-tree.
-    // Selecting before the transport cap is what lets a deep/large path (row 250 of a 500-row array)
-    // resolve — capping first would truncate the store before selection ever reached the row.
     if (path !== undefined || depth !== undefined) {
         const rawStores = readStoresRaw(store);
         const base = store !== undefined ? rawStores[store] : { stores: rawStores, storeNames: names };
@@ -164,13 +131,8 @@ function readState(ref, store, path, depth) {
             path,
             found: selection.found,
             value: projected.value,
-            // Even a SCOPED read can hit the caps when the selected sub-tree is itself large; saying so is
-            // what keeps "the list is short" distinguishable from "I shortened the list".
             ...(projected.truncation === undefined ? {} : { truncation: projected.truncation }),
             ...('availableKeys' in selection ? { availableKeys: selection.availableKeys } : {}),
-            // How many keys there REALLY were, when the near-miss list is a sample. Without it, 50 names
-            // and no marker reads as "the key you asked for does not exist" — the strongest negative
-            // signal there is, and a false one when the key is simply number 51.
             ...('totalKeys' in selection ? { totalKeys: selection.totalKeys } : {}),
             storeNames: names,
         };
@@ -180,8 +142,6 @@ function readState(ref, store, path, depth) {
         stores,
         storeNames: names,
     };
-    // The whole-store read is where a large store silently became a small one. Present only when a cap
-    // actually fired, so an intact read is unchanged and the field's presence is the warning.
     if (truncation !== undefined)
         result.truncation = truncation;
     if (ref !== undefined && ref.length > 0) {
@@ -196,19 +156,6 @@ function readState(ref, store, path, depth) {
     }
     return result;
 }
-/**
- * Every animation, and WHICH element it drives.
- *
- * Reported from the field: a page with nine concurrent animations returned nine indistinguishable
- * `{playState, currentTime, duration}` rows. `a.effect` was read only for `getTiming()`, never for
- * its `target` — so the tool advertised "targets/timing" and shipped timing alone. A list you cannot
- * index is not a list, and the question this tool exists to answer is "is THAT thing still
- * animating".
- *
- * `describe()` is reused rather than inventing a target shape: it is what `reticle_query` returns,
- * so the descriptor carries a `ref` the agent can pass straight to `reticle_act` — a target you
- * cannot act on would be half an answer.
- */
 function listAnimations() {
     const doc = document;
     if (typeof doc.getAnimations !== 'function')
@@ -216,9 +163,6 @@ function listAnimations() {
     const animations = doc.getAnimations().map((a) => {
         const effect = a.effect;
         const timing = effect?.getTiming();
-        // A KeyframeEffect's target is legitimately nullable, and only KeyframeEffect has one at all.
-        // `null` is reported explicitly: omitting the key would make "this animation has no element"
-        // indistinguishable from the bug above, which is the distinction the fix exists to draw.
         const target = effect?.target ?? null;
         return {
             playState: a.playState,
@@ -240,14 +184,11 @@ export function resolveNavigationUrl(rawUrl, baseUrl) {
         return null;
     }
 }
-/** Map browser command names to handlers. Used by the transport on each COMMAND. */
 export function createCommandRegistry() {
     const reg = new Map();
     reg.set(ReticleCommand.SNAPSHOT, (args) => buildSnapshot({
         scope: str(args['scope']),
         mode: str(args['mode']) ?? SnapshotMode.FULL,
-        // Only the completion re-read sets this: it re-reads a branch the truncated walk stopped
-        // BEFORE emitting, so that branch's own line has to come back with its descendants.
         includeRoot: true === args['includeRoot'],
     }));
     reg.set(ReticleCommand.QUERY, (args) => {
@@ -300,7 +241,6 @@ export function createCommandRegistry() {
     });
     reg.set(ReticleCommand.REFRESH, (args) => {
         if (true === args['hard']) {
-            // Hard reload: navigate to self with a cache-busting param then replace history.
             const url = new URL(window.location.href);
             url.searchParams.set(RELOAD_CACHE_BUST_PARAM, String(Date.now()));
             window.location.replace(url.toString());