@reticlehq/browser 2.13.0 → 2.14.0

package/dist/dom/realm.js

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

package/dist/dom/refs.d.ts

@@ -1,90 +1,14 @@
 import { type Ref } from '@reticlehq/core';
-/**
- * Stable, human-meaningful element handles. Each element gets a ref like `e7`; the same
- * element keeps its ref across snapshots, and a ref re-resolves to its element as long as
- * the element is still in the document.
- */
-/**
- * How many ref -> element entries are retained.
- *
- * The forward map is weak, so elements are always collectable; this bounds the BOOKKEEPING, which was
- * not. Refs are minted far more often than an agent asks about them — every meaningful DOM addition,
- * every transitionend, every scroll reveal — and the only eviction used to be "the agent happened to
- * resolve this exact dead ref". A busy app over a long session therefore accumulated entries for
- * elements that had been garbage for hours.
- *
- * Sized generously because eviction is not free of consequence (see refFor): the useful lifetime of a
- * ref is one agent turn, and this is far more than any one turn produces.
- */
 export declare const MAX_TRACKED_REFS = 10000;
-/**
- * A ref, made safe to interpolate into an error message.
- *
- * A ref Reticle mints is `e7` — three characters. A ref a CALLER passes is whatever they typed, and
- * an agent guessing at the schema can pass 100KB of it. Every stale-ref message interpolates that
- * value directly, so the caller's own bad argument came back as a 100KB error.
- *
- * The server caps error messages centrally, but it cannot help here: the browser's transport
- * serializer truncates from the TAIL first, which severs "… no longer resolves to an element" — the
- * exact substring the server's recovery table matches on. A stale ref then arrives classified as a
- * possible Reticle defect. So the echo is bounded at the source, where the untrusted value enters
- * the message.
- */
 export declare function echoRef(ref: string): string;
-/**
- * How many numbers a document claims at once.
- *
- * The reservation is a synchronous storage write, so it cannot happen per mint — mints are frequent
- * (every meaningful DOM addition, every transitionend, every scroll reveal). One write per this many
- * mints is free.
- *
- * Sized to keep refs SHORT, and the first attempt at that reasoned about the wrong axis. It bounded
- * how many navigations it took to reach seven digits and concluded "a hundred" — but the cost is not
- * paid at seven digits, it is paid at every digit, on every ref, in every snapshot and every error
- * message, on every turn. At 10,000 the SECOND document already mints five-digit refs.
- *
- * Measured on one unchanged three-element page across a session: 61 tokens on the first document,
- * 64 after a reload, 65 later — +6.5% for the same page, entirely in ref width. The benchmark saw the
- * same thing as a ~4% rise in average observation cost, which is what a benchmark is for.
- *
- * So the block is small. A document claims another one when it outmints this, which costs one more
- * storage write and is exactly proportional: a page with thousands of elements has a long snapshot
- * anyway, and a small page — the common case, and the one an agent drives repeatedly — keeps
- * three-digit refs across dozens of navigations.
- */
 export declare const REF_BLOCK = 100;
 export declare class RefRegistry {
     #private;
-    /**
-     * Storage is injected rather than read from the global for the same reason the clock is: it is an
-     * ambient dependency that decides behaviour, and the cross-document property is untestable if the
-     * only way to get a second document is to actually navigate.
-     */
     constructor(storage?: () => Storage | undefined);
-    /** How many reverse entries are currently retained. Exposed so the bound can be asserted. */
     get size(): number;
-    /**
-     * A hot update just replaced modules in this document: every ref handed out so far was minted
-     * against the DOM the previous version of that code produced.
-     *
-     * Only the boundary is recorded. Nothing is evicted — a hot update is not a navigation, and most
-     * of the page survives one, so refs minted before it very often still resolve. This exists so the
-     * ones that DON'T can say why.
-     */
     markEdited(): void;
-    /** Was this ref handed out before the last hot update? False while no update has been observed. */
     mintedBeforeLastEdit(ref: string): boolean;
-    /** Get the existing ref for an element, or mint a new one. */
     refFor(el: Element): Ref;
-    /**
-     * Resolve a ref back to its element, or null if it's gone/detached.
-     *
-     * Takes a plain `string` ON PURPOSE: this is the untrusted-input path — the ref comes from the agent
-     * over the wire, and a miss is answered with null rather than an error. Requiring a branded Ref here
-     * would force a meaningless cast at every wire boundary and buy nothing; the brand's value is on the
-     * MINT (refFor) so our own code cannot pass, say, a sessionId where a handle is expected.
-     */
     resolve(ref: string): Element | null;
 }
-/** Process-wide registry shared by snapshot, query, and the action executor. */
 export declare const refs: RefRegistry;

package/dist/dom/refs.js

@@ -1,94 +1,14 @@
 import { TRANSPORT_LIMITS, asRef } from '@reticlehq/core';
-/**
- * Stable, human-meaningful element handles. Each element gets a ref like `e7`; the same
- * element keeps its ref across snapshots, and a ref re-resolves to its element as long as
- * the element is still in the document.
- */
-/**
- * How many ref -> element entries are retained.
- *
- * The forward map is weak, so elements are always collectable; this bounds the BOOKKEEPING, which was
- * not. Refs are minted far more often than an agent asks about them — every meaningful DOM addition,
- * every transitionend, every scroll reveal — and the only eviction used to be "the agent happened to
- * resolve this exact dead ref". A busy app over a long session therefore accumulated entries for
- * elements that had been garbage for hours.
- *
- * Sized generously because eviction is not free of consequence (see refFor): the useful lifetime of a
- * ref is one agent turn, and this is far more than any one turn produces.
- */
 export const MAX_TRACKED_REFS = 10000;
-/** Marks a ref that was too long to echo in full. */
 const REF_ELISION = '…';
-/** Every ref Reticle mints is this letter followed by its sequence number. */
 const REF_PREFIX = 'e';
-/**
- * A ref, made safe to interpolate into an error message.
- *
- * A ref Reticle mints is `e7` — three characters. A ref a CALLER passes is whatever they typed, and
- * an agent guessing at the schema can pass 100KB of it. Every stale-ref message interpolates that
- * value directly, so the caller's own bad argument came back as a 100KB error.
- *
- * The server caps error messages centrally, but it cannot help here: the browser's transport
- * serializer truncates from the TAIL first, which severs "… no longer resolves to an element" — the
- * exact substring the server's recovery table matches on. A stale ref then arrives classified as a
- * possible Reticle defect. So the echo is bounded at the source, where the untrusted value enters
- * the message.
- */
 export function echoRef(ref) {
     const max = TRANSPORT_LIMITS.MAX_REF_LENGTH;
     return max >= ref.length ? ref : `${ref.slice(0, max)}${REF_ELISION}`;
 }
-/**
- * Full-sweep cadence. The deref-sweep is O(retained), and a page legitimately holding ≥ MAX_TRACKED_REFS
- * live elements (a 10k-node dashboard) can never get under the cap that way, so running it on EVERY mint
- * over the cap turned each mint into a 10k-entry scan — measured 264µs vs 0.20µs (1,300x) on the app's
- * main thread, ~2.6% of it forever on a churning page. The cap is instead held by an O(1) oldest-drop per
- * over-cap mint, and the expensive dead-entry sweep runs once per this many mints (amortized O(1)).
- */
 const SWEEP_EVERY_MINTS = 1000;
-/**
- * Where a document records the ref numbers it has claimed, so the next one starts past them.
- *
- * Refs are per-DOCUMENT: a reload or a cross-page link tears this module down and the next document
- * used to start minting from `e1` again. So `e7` from page A was a valid, resolvable, DIFFERENT
- * element on page B — nothing refused, the wrong element was acted on, and the result came back `ok`.
- * The SPA case was always safe (WeakRef liveness + isConnected); this was the other half, and the
- * more dangerous one, because it produced a false green instead of an error.
- *
- * Deliberately NOT a change to the ref grammar. Stamping refs `e7@3` would have worked too, but every
- * agent passes refs back verbatim and every saved flow on disk already holds bare ones, so it buys a
- * wire-format migration for a property the sequence itself can carry. A number that never restarts
- * means a stale ref simply misses the map, and the refusal that already exists — already worded for
- * exactly this case — fires unchanged.
- *
- * Namespaced like the session key it sits beside; `sessionStorage` is the right scope for the same
- * reason session continuity uses it (survives reloads and same-tab navigations, not shared with
- * another tab, which is a different session with its own registry anyway).
- */
 const REF_BASE_KEY = '__reticle_ref_base';
-/**
- * How many numbers a document claims at once.
- *
- * The reservation is a synchronous storage write, so it cannot happen per mint — mints are frequent
- * (every meaningful DOM addition, every transitionend, every scroll reveal). One write per this many
- * mints is free.
- *
- * Sized to keep refs SHORT, and the first attempt at that reasoned about the wrong axis. It bounded
- * how many navigations it took to reach seven digits and concluded "a hundred" — but the cost is not
- * paid at seven digits, it is paid at every digit, on every ref, in every snapshot and every error
- * message, on every turn. At 10,000 the SECOND document already mints five-digit refs.
- *
- * Measured on one unchanged three-element page across a session: 61 tokens on the first document,
- * 64 after a reload, 65 later — +6.5% for the same page, entirely in ref width. The benchmark saw the
- * same thing as a ~4% rise in average observation cost, which is what a benchmark is for.
- *
- * So the block is small. A document claims another one when it outmints this, which costs one more
- * storage write and is exactly proportional: a page with thousands of elements has a long snapshot
- * anyway, and a small page — the common case, and the one an agent drives repeatedly — keeps
- * three-digit refs across dozens of navigations.
- */
 export const REF_BLOCK = 100;
-/** The reserved-block high-water mark, or 0 when storage is unavailable or its value is junk. */
 function readBase(store) {
     try {
         const raw = store?.getItem(REF_BASE_KEY);
@@ -96,7 +16,7 @@ function readBase(store) {
         return Number.isSafeInteger(value) && value > 0 ? value : 0;
     }
     catch {
-        return 0; // a sandboxed iframe throws on access; a session must still start
+        return 0;
     }
 }
 export class RefRegistry {
@@ -104,34 +24,19 @@ export class RefRegistry {
     #fromRef = new Map();
     #storage;
     #seq = 0;
-    /** The end of the block currently reserved. Minting past it claims the next one. */
     #reserved = 0;
     #mintsSinceSweep = 0;
-    /**
-     * The highest number handed out before the last hot update was applied, or 0 while none has been.
-     *
-     * A watermark rather than a per-ref stamp: the sequence never restarts within a document, so one
-     * number separates "minted before the code changed" from "minted after it" for every ref at once.
-     * The alternative — an epoch on every map entry — is bookkeeping paid on every mint for an answer
-     * needed only on the rare refusal.
-     */
     #editedAtSeq = 0;
-    /**
-     * Storage is injected rather than read from the global for the same reason the clock is: it is an
-     * ambient dependency that decides behaviour, and the cross-document property is untestable if the
-     * only way to get a second document is to actually navigate.
-     */
     constructor(storage = () => globalThis.sessionStorage) {
         this.#storage = storage;
     }
-    /** Read the tab's high-water mark and claim the next block, BEFORE any of it is handed out. */
     #reserve() {
         let store;
         try {
             store = this.#storage();
         }
         catch {
-            store = undefined; // hostile storage: no cross-document guarantee, but the session still starts
+            store = undefined;
         }
         const base = Math.max(readBase(store), this.#seq);
         this.#reserved = base + REF_BLOCK;
@@ -139,25 +44,17 @@ export class RefRegistry {
             store?.setItem(REF_BASE_KEY, String(this.#reserved));
         }
         catch {
-            /* same: never block a mint on storage */
         }
-        // Claimed on the FIRST mint, not at unload — a page that crashes, is killed, or navigates away
-        // without firing unload has still permanently spent its numbers.
         this.#seq = base;
     }
-    /** How many reverse entries are currently retained. Exposed so the bound can be asserted. */
     get size() {
         return this.#fromRef.size;
     }
-    /** O(1): drop the least-recently-minted reverse entry. Map iterates in insertion order, so the front
-     *  is the oldest. A still-live element whose entry is dropped re-registers on its next refFor. */
     #evictOldest() {
         const oldest = this.#fromRef.keys().next();
         if (oldest.done !== true)
             this.#fromRef.delete(oldest.value);
     }
-    /** Full pass: drop every entry whose element has been collected or detached (frees genuinely dead
-     *  bookkeeping), then any remaining excess by age. Amortized — called once per SWEEP_EVERY_MINTS. */
     #sweep() {
         for (const [ref, weak] of this.#fromRef) {
             const el = weak.deref();
@@ -167,33 +64,18 @@ export class RefRegistry {
         while (this.#fromRef.size > MAX_TRACKED_REFS)
             this.#evictOldest();
     }
-    /**
-     * A hot update just replaced modules in this document: every ref handed out so far was minted
-     * against the DOM the previous version of that code produced.
-     *
-     * Only the boundary is recorded. Nothing is evicted — a hot update is not a navigation, and most
-     * of the page survives one, so refs minted before it very often still resolve. This exists so the
-     * ones that DON'T can say why.
-     */
     markEdited() {
         this.#editedAtSeq = this.#seq;
     }
-    /** Was this ref handed out before the last hot update? False while no update has been observed. */
     mintedBeforeLastEdit(ref) {
         if (0 === this.#editedAtSeq || !ref.startsWith(REF_PREFIX))
             return false;
         const n = Number(ref.slice(REF_PREFIX.length));
         return Number.isSafeInteger(n) && n > 0 && n <= this.#editedAtSeq;
     }
-    /** Get the existing ref for an element, or mint a new one. */
     refFor(el) {
         const existing = this.#toRef.get(el);
         if (existing !== undefined) {
-            // Re-register if this element's entry was evicted while it was off the agent's radar. Without
-            // this, an element that is still on the page could hold a ref that no longer resolves — the
-            // eviction would surface as "element not found", which is a wrong answer rather than a slow one.
-            // Either way, TOUCH it to the recent end (LRU): an element being surfaced right now must not be
-            // the oldest-drop victim of a mint storm before the agent gets to act on it.
             const weak = this.#fromRef.get(existing);
             this.#fromRef.delete(existing);
             this.#fromRef.set(existing, weak ?? new WeakRef(el));
@@ -205,7 +87,6 @@ export class RefRegistry {
         const ref = asRef(`${REF_PREFIX}${String(this.#seq)}`);
         this.#toRef.set(el, ref);
         this.#fromRef.set(ref, new WeakRef(el));
-        // Keep bounded cheaply on every mint; run the full dead-entry sweep only periodically.
         this.#mintsSinceSweep += 1;
         if (this.#mintsSinceSweep >= SWEEP_EVERY_MINTS) {
             this.#mintsSinceSweep = 0;
@@ -216,14 +97,6 @@ export class RefRegistry {
         }
         return ref;
     }
-    /**
-     * Resolve a ref back to its element, or null if it's gone/detached.
-     *
-     * Takes a plain `string` ON PURPOSE: this is the untrusted-input path — the ref comes from the agent
-     * over the wire, and a miss is answered with null rather than an error. Requiring a branded Ref here
-     * would force a meaningless cast at every wire boundary and buy nothing; the brand's value is on the
-     * MINT (refFor) so our own code cannot pass, say, a sessionId where a handle is expected.
-     */
     resolve(ref) {
         const weak = this.#fromRef.get(ref);
         if (weak === undefined)
@@ -233,13 +106,9 @@ export class RefRegistry {
             this.#fromRef.delete(ref);
             return null;
         }
-        // LRU touch: a ref the agent just resolved is in ACTIVE use — move it to the most-recent end so an
-        // oldest-drop eviction between this resolve and the follow-up act can't reclaim it and turn a live
-        // element into a false "ref no longer resolves". O(1) — Map preserves insertion order.
         this.#fromRef.delete(ref);
         this.#fromRef.set(ref, weak);
         return el;
     }
 }
-/** Process-wide registry shared by snapshot, query, and the action executor. */
 export const refs = new RefRegistry();

package/dist/dom/shadow-registry.d.ts

@@ -1,40 +1,7 @@
-/**
- * Every shadow root this SDK has seen created, open or closed.
- *
- * Two problems are solved by the same record.
- *
- * **Observation.** A `MutationObserver` on `documentElement` does NOT cross a shadow boundary, so a
- * click that changes text inside a web component produced an entirely empty observe window. Measured
- * on a console with a shadow-DOM alert badge: the click landed, the badge changed, and `observe`
- * reported zero DOM events — indistinguishable from an app that ignored the click. The DOM observer
- * needs a list of roots to attach to, and no API enumerates them.
- *
- * **Closed roots.** `element.shadowRoot` is null forever for `mode: 'closed'`, so a closed root is
- * unreadable AFTER the fact — but `attachShadow` still RETURNS it to its caller. Patching that call
- * captures the root at the one instant it is exposed. This only works when the SDK is installed
- * before the component upgrades, which is why hosts are tracked individually rather than assumed:
- * whatever was missed is still declared as a blind spot, and only what was genuinely captured stops
- * being one.
- */
-/**
- * Bookkeeping ceiling. Weak references make the ROOTS collectable; this bounds the entries pointing
- * at them, which are not. Sized far above any real page's live component count.
- */
 export declare const MAX_TRACKED_ROOTS = 4000;
-/** Dead-entry sweeps are O(retained), so they run once per this many roots rather than per root. */
 export declare const SWEEP_EVERY = 250;
-/** Shadow roots captured so far. Includes closed roots when the patch was installed in time. */
 export declare function capturedRoots(): readonly ShadowRoot[];
-/** Whether this element's shadow root was captured — i.e. whether its contents are reachable. */
 export declare function isCaptured(host: Element): boolean;
-/** The captured root for a host, or null. Non-null for closed roots the patch caught in time. */
 export declare function capturedRootOf(host: Element): ShadowRoot | null;
-/** Run `listener` for every root captured from now on. Returns an unsubscribe. */
 export declare function onShadowRoot(listener: (root: ShadowRoot) => void): () => void;
-/**
- * Patch `attachShadow` to record each root as it is created, and sweep the roots that already exist.
- *
- * The sweep can only find OPEN roots (there is no other way in), so a closed root attached before
- * install stays unreachable — correctly, and it is declared as such.
- */
 export declare function installShadowRegistry(): () => void;

package/dist/dom/shadow-registry.js

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