@teaflask/assistant 0.3.0 → 0.6.0

package/dist/reader/read-page.js

@@ -1,32 +1,12 @@
-// One builtin.read_page request in, one landable result out: snapshot
-// the page the mount lives in, render it, fit it under the tool-results
-// door's size cap, and — on a repeat read — deliver the unified diff
-// against the previous read when that is the cheaper payload. The
-// baseline lives here at module level, per thread: the handler map's
-// identity churns with its React deps, and a baseline that died on every
-// re-render would never produce a diff. An empty diff (is_diff with ""
-// content) means the page is unchanged since the previous read.
 import { boundedTextOf, doorCostOfText } from "../transport/door-budget.js";
 import { unifiedDiffOf } from "./line-diff.js";
 import { pageHeaderOf, renderedTreeOf } from "./render.js";
 import { DEFAULT_MAX_DEPTH, resolvedSnapshotRootOf, snapshotTreeOf, } from "./snapshot.js";
-// The content budget under the door's 20k serialized cap, measured in
-// the door's own metric (door-budget.ts): 16k leaves headroom for the
-// result's url/title/flag siblings, mirroring the action-response bound.
 const READ_PAGE_CONTENT_MAX_CHARS = 16_000;
-// When the full-depth tree overflows, re-render shallower until it fits.
 const DEPTH_LADDER = [30, 20, 12, 8, 5, 3];
 const TRUNCATION_NOTICE = "… [truncated: the page holds more than fits here]";
 const MAX_TITLE_LENGTH = 300;
 const MAX_URL_LENGTH = 2_000;
-/**
- * An expected, recoverable read refusal — a stale ref, a selector that
- * matches nothing, a page with no body yet. Its message is the reader's
- * own model-actionable sentence (usually "take a fresh full read"), and
- * the handler delivers it verbatim: wrapping it in give-up prose would
- * cancel the retry the sentence asks for. A reader crash is anything
- * else.
- */
 export class SnapshotUnavailableError extends Error {
 }
 const _baselineByThread = new Map();
@@ -52,8 +32,6 @@ export function _resetBaselinesForTests() {
     _baselineByThread.clear();
 }
 function _readRequestOf(action, probe) {
-    // Wire defense only: the knobs are model-supplied and optional, and a
-    // wrong-typed knob degrades to its default rather than failing a read.
     return {
         probe,
         ignoreSelectors: _stringListOf(action?.ignore_selectors),
@@ -66,11 +44,6 @@ function _readRequestOf(action, probe) {
     };
 }
 function _fittedTreeTextOf(request) {
-    // Resolve the root once and pin the element: the ladder below renders
-    // the same read several times, each render rebuilds the ref registry,
-    // and a ref whose element changed identity since minting would resolve
-    // on the first render and be gone by the second — a read must not fail
-    // on payload size where the same request succeeds when small.
     const rooting = resolvedSnapshotRootOf(request);
     if (rooting.error !== null) {
         throw new SnapshotUnavailableError(rooting.error);
@@ -94,12 +67,6 @@ function _fittedTreeTextOf(request) {
             };
         }
     }
-    // Even the shallowest rung overflows: deliver the full outline cut on
-    // line boundaries. Re-render it first so the ref registry matches the
-    // refs this outline shows — every ladder rung above rebuilt the registry
-    // as it ran, so it currently holds the shallowest rung's refs, not the
-    // deep ones a ref_id follow-up read would look up. Refs are stable, so
-    // this reproduces fullText exactly while restoring the full registry.
     const fullTextAgain = `${header}\n${_renderedSnapshotOf(pinned)}`;
     return {
         text: _lineBoundedTextOf(fullTextAgain),
@@ -119,9 +86,6 @@ function _cheaperOfDiffAndFull(threadId, scope, fitted) {
     if (baseline?.scope !== scope || baseline.shape !== fitted.shape) {
         return { text: fitted.text, isDiff: false };
     }
-    // Two line-bounded renders share a shape, but the cut point slides
-    // with any earlier change — tail sections would flap in and out of the
-    // diff as removals that never happened. Those reads deliver in full.
     if (fitted.shape === "line-bounded") {
         return { text: fitted.text, isDiff: false };
     }
@@ -132,10 +96,6 @@ function _cheaperOfDiffAndFull(threadId, scope, fitted) {
     return { text: fitted.text, isDiff: false };
 }
 function _scopeKeyOf(request) {
-    // Everything that shapes the rendered view except the probe — including
-    // the page itself: a client-side navigation keeps this module alive, and
-    // diffing the new page against the old one would read the old page's
-    // unique content as removals.
     return JSON.stringify({
         url: document.location.href,
         interactive: request.interactive,
@@ -149,7 +109,6 @@ function _scopeKeyOf(request) {
 function _lineBoundedTextOf(text) {
     const noticeCost = doorCostOfText(`\n${TRUNCATION_NOTICE}`);
     const bounded = boundedTextOf(text, READ_PAGE_CONTENT_MAX_CHARS - noticeCost);
-    // Cut on a line boundary so the outline stays parseable to the end.
     const lastLineBreak = bounded.lastIndexOf("\n");
     const wholeLines = lastLineBreak > 0 ? bounded.slice(0, lastLineBreak) : bounded;
     return `${wholeLines}\n${TRUNCATION_NOTICE}`;
@@ -169,4 +128,3 @@ function _stringListOf(value) {
     }
     return value.filter((member) => typeof member === "string" && member !== "");
 }
-//# sourceMappingURL=read-page.js.map

package/dist/reader/redaction.d.ts

@@ -1,14 +1,3 @@
 export declare const REDACTED_VALUE = "[redacted]";
-/**
- * The value a textbox-like element shows, redacted where it must be:
- * null when the element holds no readable value at all.
- */
 export declare function textboxValueOf(element: Element): string | null;
-/**
- * Whether a field's autocomplete declares a secret (card numbers,
- * passwords, one-time codes). One predicate for both directions: the
- * snapshot redacts what it reads, and prefill refuses what it would
- * write — the two guards must never disagree about what a secret is.
- */
 export declare function theFieldHoldsASecret(element: HTMLInputElement | HTMLTextAreaElement): boolean;
-//# sourceMappingURL=redaction.d.ts.map

package/dist/reader/redaction.js

@@ -1,7 +1,3 @@
-// What a text control's current value contributes to the snapshot — and
-// the always-on redaction gate in front of it. Passwords and fields
-// whose autocomplete declares a secret (card numbers, one-time codes)
-// never enter a snapshot; there is deliberately no way to turn this off.
 import { isContentEditableElement } from "./roles.js";
 export const REDACTED_VALUE = "[redacted]";
 const SENSITIVE_AUTOCOMPLETE_VALUES = new Set([
@@ -11,13 +7,8 @@ const SENSITIVE_AUTOCOMPLETE_VALUES = new Set([
     "new-password",
     "one-time-code",
 ]);
-/**
- * The value a textbox-like element shows, redacted where it must be:
- * null when the element holds no readable value at all.
- */
 export function textboxValueOf(element) {
     if (isContentEditableElement(element)) {
-        // Not every engine implements innerText (jsdom); fall back honestly.
         const rendered = Reflect.get(element, "innerText");
         if (typeof rendered === "string") {
             return rendered;
@@ -30,10 +21,6 @@ export function textboxValueOf(element) {
     }
     if (element instanceof HTMLInputElement) {
         const type = element.type;
-        // hidden inputs hold machine state the user never sees — CSRF tokens,
-        // session blobs — so they never contribute a value, redacted or not
-        // (they surface at all only under show_hidden). checkbox/radio/file
-        // carry no readable text value either.
         if (type === "checkbox" ||
             type === "radio" ||
             type === "file" ||
@@ -49,12 +36,6 @@ export function textboxValueOf(element) {
     }
     return element.value;
 }
-/**
- * Whether a field's autocomplete declares a secret (card numbers,
- * passwords, one-time codes). One predicate for both directions: the
- * snapshot redacts what it reads, and prefill refuses what it would
- * write — the two guards must never disagree about what a secret is.
- */
 export function theFieldHoldsASecret(element) {
     const autocomplete = (element.getAttribute("autocomplete") ?? "")
         .trim()
@@ -62,10 +43,7 @@ export function theFieldHoldsASecret(element) {
     if (autocomplete === "") {
         return false;
     }
-    // autocomplete is a token list ("billing cc-number"); any secret token
-    // marks the field, and every cc-exp variant counts.
     return autocomplete
         .split(/\s+/)
         .some((token) => SENSITIVE_AUTOCOMPLETE_VALUES.has(token) || token.startsWith("cc-exp"));
 }
-//# sourceMappingURL=redaction.js.map

package/dist/reader/render.d.ts

@@ -1,4 +1,3 @@
 import type { SnapshotNode } from "./snapshot.js";
 export declare function pageHeaderOf(title: string, url: string): string;
 export declare function renderedTreeOf(root: SnapshotNode): string;
-//# sourceMappingURL=render.d.ts.map

package/dist/reader/render.js

@@ -1,9 +1,3 @@
-// The snapshot's text form: an indented outline the model reads top to
-// bottom, one `- role "name" [ref=eN] [flags]` line per node, string
-// children as `- text: "…"` rows, and a two-line page header. Selects
-// render their options inline — the accessibility walk never descends
-// into them, but the choice list is exactly what a "what am I looking
-// at" answer needs.
 import { boundedTextOf } from "../transport/door-budget.js";
 const MAX_TITLE_LENGTH = 300;
 const MAX_URL_LENGTH = 2_000;
@@ -121,4 +115,3 @@ function _escapedText(text) {
 function _indentOf(depth) {
     return "  ".repeat(depth);
 }
-//# sourceMappingURL=render.js.map

package/dist/reader/roles.d.ts

@@ -1,15 +1,8 @@
 export declare const ARIA_SELECTED_ROLES: Set<string>;
 export declare const ARIA_CHECKED_ROLES: Set<string>;
 export declare const ARIA_DISABLED_ROLES: Set<string>;
-/** The element's effective role: explicit when valid, implicit otherwise. */
 export declare function roleOf(element: Element): string;
-/** The first valid token of role="…", or null when none names a role. */
 export declare function explicitRoleOf(element: Element): string | null;
-/** The heading/listitem/row/treeitem level, or null when the role has none. */
 export declare function ariaLevelOf(element: Element, role: string): number | null;
-/** aria-* boolean tri-state: true / false / absent. */
 export declare function ariaBooleanOf(attribute: string | null): boolean | undefined;
-/** Editable regions read as textboxes. The attribute fallback covers
- * engines that don't reflect the contentEditable property (jsdom). */
 export declare function isContentEditableElement(element: Element): boolean;
-//# sourceMappingURL=roles.d.ts.map

package/dist/reader/roles.js

@@ -1,11 +1,3 @@
-// Role resolution for the page reader: which ARIA role a rendered
-// element effectively carries. Explicit role attributes win when they
-// name a real role; everything else falls back to the tag's implicit
-// role. role="presentation"/"none" deliberately fall back too — sites
-// slap presentation on styled tables and lists whose semantics the
-// reader still wants. Pure attribute logic, no layout reads.
-// Tag → implicit ARIA role, consulted when the element is not an input
-// and not contentEditable.
 const IMPLICIT_ROLE_BY_TAG = {
     a: "link",
     button: "button",
@@ -37,8 +29,6 @@ const IMPLICIT_ROLE_BY_TAG = {
     p: "paragraph",
     label: "label",
 };
-// An explicit role="…" is honored only when it names a role in this
-// allowlist (first valid token wins).
 const VALID_ARIA_ROLES = new Set([
     "alert",
     "alertdialog",
@@ -124,7 +114,6 @@ const VALID_ARIA_ROLES = new Set([
     "treegrid",
     "treeitem",
 ]);
-// Roles whose nodes carry the bracketed state that matches the set.
 const ARIA_LEVEL_ROLES = new Set(["heading", "listitem", "row", "treeitem"]);
 export const ARIA_SELECTED_ROLES = new Set([
     "gridcell",
@@ -188,7 +177,6 @@ const NATIVE_HEADING_LEVELS = {
     h5: 5,
     h6: 6,
 };
-/** The element's effective role: explicit when valid, implicit otherwise. */
 export function roleOf(element) {
     const explicit = explicitRoleOf(element);
     if (explicit === null) {
@@ -199,7 +187,6 @@ export function roleOf(element) {
     }
     return explicit;
 }
-/** The first valid token of role="…", or null when none names a role. */
 export function explicitRoleOf(element) {
     const tokens = (element.getAttribute("role") ?? "")
         .split(" ")
@@ -207,7 +194,6 @@ export function explicitRoleOf(element) {
         .filter((token) => token !== "");
     return tokens.find((token) => VALID_ARIA_ROLES.has(token)) ?? null;
 }
-/** The heading/listitem/row/treeitem level, or null when the role has none. */
 export function ariaLevelOf(element, role) {
     if (!ARIA_LEVEL_ROLES.has(role)) {
         return null;
@@ -221,7 +207,6 @@ export function ariaLevelOf(element, role) {
     const declared = Number(element.getAttribute("aria-level"));
     return Number.isInteger(declared) && declared >= 1 ? declared : null;
 }
-/** aria-* boolean tri-state: true / false / absent. */
 export function ariaBooleanOf(attribute) {
     if (attribute === null) {
         return undefined;
@@ -248,8 +233,6 @@ function _implicitRoleOf(element) {
     }
     return IMPLICIT_ROLE_BY_TAG[tag] ?? "generic";
 }
-/** Editable regions read as textboxes. The attribute fallback covers
- * engines that don't reflect the contentEditable property (jsdom). */
 export function isContentEditableElement(element) {
     if (element instanceof HTMLElement) {
         const reflected = element.contentEditable;
@@ -260,4 +243,3 @@ export function isContentEditableElement(element) {
     const attribute = element.getAttribute("contenteditable");
     return (attribute === "" || attribute === "true" || attribute === "plaintext-only");
 }
-//# sourceMappingURL=roles.js.map

package/dist/reader/snapshot-compaction.d.ts

@@ -1,11 +1,5 @@
 import type { SnapshotNode } from "./snapshot.js";
-/** Merge adjacent string children, fold bare paragraphs into the run,
- * and drop a lone text child that just repeats the node's name. */
 export declare function _mergeStringChildren(node: SnapshotNode): void;
-/** Drop hidden ref-less subtrees and unwrap anonymous wrappers whose
- * only content is a single ref-bearing child. */
 export declare function _unwrapBareGenerics(node: SnapshotNode, showHidden: boolean): void;
-/** Fold a ref-bearing node's few text-only children into its own name. */
 export declare function _foldTextLeaves(node: SnapshotNode): void;
 export declare function _duplicateRefOf(node: SnapshotNode): string | null;
-//# sourceMappingURL=snapshot-compaction.d.ts.map

package/dist/reader/snapshot-compaction.js

@@ -1,9 +1,4 @@
-// The compaction passes over a walked tree: merge text runs, unwrap
-// anonymous wrappers, fold text leaves into their parent's name, and
-// refuse a tree that minted one ref twice.
 import { _normalizedNodeName } from "./snapshot-node.js";
-/** Merge adjacent string children, fold bare paragraphs into the run,
- * and drop a lone text child that just repeats the node's name. */
 export function _mergeStringChildren(node) {
     for (const child of node.children) {
         if (typeof child !== "string") {
@@ -46,8 +41,6 @@ function _isBareTextParagraph(node) {
         !node.scrollable &&
         node.children.every((child) => typeof child === "string"));
 }
-/** Drop hidden ref-less subtrees and unwrap anonymous wrappers whose
- * only content is a single ref-bearing child. */
 export function _unwrapBareGenerics(node, showHidden) {
     const result = [];
     for (const child of node.children) {
@@ -56,10 +49,6 @@ export function _unwrapBareGenerics(node, showHidden) {
             continue;
         }
         _unwrapBareGenerics(child, showHidden);
-        // Hidden ref-less noise is pruned from a default read (only the
-        // branded checkbox/radio escape reaches here, and it carries a ref)
-        // — but a show_hidden read exists precisely to surface hidden text
-        // and structure, so there the drop would gut the knob.
         if (!showHidden &&
             child.hidden &&
             child.refId === null &&
@@ -94,7 +83,6 @@ function _hasRefInSubtree(node) {
     return node.children.some((child) => typeof child !== "string" && _hasRefInSubtree(child));
 }
 const TEXT_LEAF_ROLES = new Set(["generic", "heading", "paragraph", "label"]);
-/** Fold a ref-bearing node's few text-only children into its own name. */
 export function _foldTextLeaves(node) {
     for (const child of node.children) {
         if (typeof child !== "string") {
@@ -150,10 +138,6 @@ function _mergedTextOf(parts) {
     return merged.trim();
 }
 function _wordsMeetAtTheSeam(left, right) {
-    // Raw boundary characters, not trimmed ends: a fragment that already
-    // carries its own boundary space ("Welcome " + "back") must not gain a
-    // second one — the doubled space would also defeat the repeats-the-name
-    // dedup above.
     if (/\s$/u.test(left) || /^\s/u.test(right)) {
         return false;
     }
@@ -180,4 +164,3 @@ export function _duplicateRefOf(node) {
     };
     return walk(node);
 }
-//# sourceMappingURL=snapshot-compaction.js.map

package/dist/reader/snapshot-node.d.ts

@@ -2,4 +2,3 @@ import type { SnapshotNode, WalkContext } from "./snapshot.js";
 export declare function _snapshotNodeOf(element: Element, context: WalkContext, refFor: (element: Element, role: string, name: string) => string): SnapshotNode | null;
 export declare function _normalizedNodeName(name: string): string;
 export declare function _fragmentNode(): SnapshotNode;
-//# sourceMappingURL=snapshot-node.d.ts.map

package/dist/reader/snapshot-node.js

@@ -1,6 +1,3 @@
-// One element becomes one node: role, name, state bits, and a ref when
-// the element is addressable. The ref mint is the caller's — the ref
-// registries stay single-homed in snapshot.ts.
 import { accessibleNameOf } from "./accessible-name.js";
 import { CONTENT_REF_ROLES, INTERACTIVE_REF_ROLES, interactivitySignalsOf, isScrollable, } from "./interactivity.js";
 import { textboxValueOf } from "./redaction.js";
@@ -23,7 +20,7 @@ export function _snapshotNodeOf(element, context, refFor) {
         (CONTENT_REF_ROLES.has(roleLower) && name.length > 0);
     const refId = shouldHaveRef ? refFor(element, role, name) : null;
     if (role === "generic" && refId === null && !hidden) {
-        return null; // an anonymous wrapper adds nothing; its children speak
+        return null;
     }
     const hints = interactivity.interactive && !interactivity.isInteractiveTag
         ? interactivity.hints
@@ -114,4 +111,3 @@ export function _fragmentNode() {
         children: [],
     };
 }
-//# sourceMappingURL=snapshot-node.js.map

package/dist/reader/snapshot-root.d.ts

@@ -1,7 +1,4 @@
 export declare const IGNORE_ATTRIBUTE = "data-teaflask-ignore";
-/** The slice of SnapshotOptions that addresses a root — all root
- * resolution needs, so ref-addressed capabilities resolve without
- * inventing a probe or read knobs. */
 export interface RootAddress {
     rootElement: Element | null;
     refId: string | null;
@@ -16,4 +13,3 @@ export declare function _resolvedRootOf(options: RootAddress, elementByRef: Read
     error: string;
 };
 export declare function _theSubtreeIsCurated(element: Element, ignoreSelectors: string[]): boolean;
-//# sourceMappingURL=snapshot-root.d.ts.map

package/dist/reader/snapshot-root.js

@@ -1,6 +1,3 @@
-// Root resolution for a read: a pinned element, a remembered ref, a
-// selector match, or the body — refused when the root sits inside a
-// curated (opted-out) subtree.
 import { roleOf } from "./roles.js";
 import { parentAcrossShadowBoundaryOf } from "./visibility.js";
 export const IGNORE_ATTRIBUTE = "data-teaflask-ignore";
@@ -37,10 +34,6 @@ export function _resolvedRootOf(options, elementByRef) {
     return { root: body, error: null };
 }
 function _rootUnlessCurated(root, options) {
-    // The full-page walk enforces curation top-down — a curated subtree is
-    // never entered, so nothing below it is reachable. A scoped read roots
-    // BELOW the top, so it must check its own ancestry, or a descendant
-    // selector (".private h2") would read inside an opted-out region.
     for (let current = root; current !== null; current = parentAcrossShadowBoundaryOf(current)) {
         if (_theSubtreeIsCurated(current, options.ignoreSelectors)) {
             return {
@@ -65,8 +58,6 @@ function _safeQuerySelector(selector) {
     return _firstElementWithImplicitRole(selector);
 }
 function _firstElementWithImplicitRole(selector) {
-    // [role="button"]-shaped selectors should also find elements whose
-    // role is implicit (a bare <button> has no role attribute to match).
     const match = /^\[role=["'](\w+)["']\]$/.exec(selector);
     if (match === null) {
         return null;
@@ -88,8 +79,7 @@ export function _theSubtreeIsCurated(element, ignoreSelectors) {
             return element.matches(selector);
         }
         catch {
-            return false; // an invalid selector never breaks a read
+            return false;
         }
     });
 }
-//# sourceMappingURL=snapshot-root.js.map

package/dist/reader/snapshot.d.ts

@@ -6,24 +6,12 @@ export { IGNORE_ATTRIBUTE };
 export declare const DEFAULT_MAX_DEPTH = 50;
 export interface SnapshotOptions {
     probe: LayoutProbe;
-    /** Grant-configured opt-out selectors; invalid ones are ignored. */
     ignoreSelectors: string[];
     maxDepth: number;
-    /** Interactive-elements-only view (with skipped text hoisted). */
     interactive: boolean;
-    /** Keep invisible elements, marked [hidden]. */
     showHidden: boolean;
-    /** Root the snapshot at a selector match instead of the body. */
     selector: string | null;
-    /** Root the snapshot at a previously-minted ref. */
     refId: string | null;
-    /**
-     * A pre-resolved root, taking precedence over refId/selector. The
-     * size-fitting ladder re-renders one read several times, and each
-     * render rebuilds the ref registry — re-resolving a refId mid-ladder
-     * would fail if the walk just re-minted the element under a new ref,
-     * so the orchestrator resolves once and pins the element.
-     */
     rootElement: Element | null;
 }
 export interface SnapshotNode {
@@ -56,8 +44,6 @@ export interface WalkContext {
     nameCache: AccessibleNameCache;
 }
 export declare function snapshotTreeOf(options: SnapshotOptions): SnapshotOutcome;
-/** Resolve a read's root without walking — for pinning it across the
- * orchestrator's repeated renders of one read. */
 export declare function resolvedSnapshotRootOf(options: SnapshotOptions): {
     root: Element;
     error: null;
@@ -65,13 +51,6 @@ export declare function resolvedSnapshotRootOf(options: SnapshotOptions): {
     root: null;
     error: string;
 };
-/**
- * Resolve a previously-minted ref to its live element — for a capability
- * that addresses the page by ref (highlight, prefill) instead of reading
- * it. Liveness and the in-page curation opt-out are checked the same way
- * a refId-rooted read checks them, and the error is the reader's own
- * model-actionable sentence.
- */
 export declare function resolvedElementOfRef(refId: string): {
     element: Element;
     error: null;
@@ -79,4 +58,3 @@ export declare function resolvedElementOfRef(refId: string): {
     element: null;
     error: string;
 };
-//# sourceMappingURL=snapshot.d.ts.map

package/dist/reader/snapshot.js

@@ -1,18 +1,3 @@
-// The snapshot walk: DOM + shadow DOM in, a compact semantic tree out.
-// Elements earn a place by meaning something — interactive, scrollable,
-// landmark, named, or a non-generic role — and everything else
-// contributes only its text. Curation is opt-out and enforced here, at
-// the walk: a data-teaflask-ignore attribute or a grant-configured
-// selector silently prunes the subtree, and redaction (redaction.ts)
-// guards every value read. Iframes render as leaf nodes: a same-JS
-// bundle cannot see into cross-origin frames, and same-origin recursion
-// is deliberately deferred (the f-prefix ref grammar stays reserved for
-// it — this function is the seam).
-//
-// Ref-ids are minted monotonically and remembered per element across
-// snapshots (WeakMap badge): an unchanged button keeps its ref from read
-// to read, which is what keeps repeat-read diffs small and will let a
-// future capability address elements by ref.
 import { accessibleNameOf, } from "./accessible-name.js";
 import { interactivitySignalsOf, isLandmark, isScrollable, } from "./interactivity.js";
 import { roleOf } from "./roles.js";
@@ -30,11 +15,8 @@ const SKIP_TAGS = new Set([
     "title",
     "noscript",
 ]);
-// Monotonic across snapshots on purpose: a ref is never reissued to a
-// different element, and an unchanged element keeps its badge.
 let _refCounter = 0;
 const _refBadgeByElement = new WeakMap();
-// The last snapshot's ref → element registry, for refId-rooted reads.
 const _elementByRef = new Map();
 export function snapshotTreeOf(options) {
     const context = {
@@ -62,19 +44,9 @@ export function snapshotTreeOf(options) {
     }
     return { tree: fragment, error: null };
 }
-// --- root resolution -------------------------------------------------------
-/** Resolve a read's root without walking — for pinning it across the
- * orchestrator's repeated renders of one read. */
 export function resolvedSnapshotRootOf(options) {
     return _resolvedRootOf(options, _elementByRef);
 }
-/**
- * Resolve a previously-minted ref to its live element — for a capability
- * that addresses the page by ref (highlight, prefill) instead of reading
- * it. Liveness and the in-page curation opt-out are checked the same way
- * a refId-rooted read checks them, and the error is the reader's own
- * model-actionable sentence.
- */
 export function resolvedElementOfRef(refId) {
     const address = {
         rootElement: null,
@@ -88,14 +60,11 @@ export function resolvedElementOfRef(refId) {
     }
     return { element: rooting.root, error: null };
 }
-// --- the walk --------------------------------------------------------------
 function _traverse(element, depth, parentNode, context) {
     const { options, oracle } = context;
     const includeAsRoot = options.refId === null && element === document.body;
     const traversable = _shouldTraverse(element, context);
     if (!traversable && !includeAsRoot) {
-        // No name hoisting here: a non-traversable subtree is hidden or
-        // curated, and curated content must not leak through its name.
         return;
     }
     const hidden = !oracle.isVisible(element);
@@ -111,8 +80,6 @@ function _traverse(element, depth, parentNode, context) {
         }
     }
     else if (options.interactive && element.childElementCount === 0) {
-        // A hoisted content name already carries the leaf's text (and its
-        // pseudo content) — descending as well would emit the text twice.
         if (_hoistSkippedLeafName(element, parentNode, context)) {
             return;
         }
@@ -124,7 +91,6 @@ function _traverse(element, depth, parentNode, context) {
     if (_descendsIntoChildren(element) && depth < options.maxDepth) {
         for (const child of lightAndShadowChildNodesOf(element)) {
             if (child.nodeType === Node.TEXT_NODE) {
-                // A textbox's value is already seeded; its text would duplicate it.
                 if (targetNode.role !== "textbox" && child.nodeValue !== null) {
                     targetNode.children.push(child.nodeValue);
                 }
@@ -140,11 +106,6 @@ function _traverse(element, depth, parentNode, context) {
     }
 }
 function _descendsIntoChildren(element) {
-    // A <select> renders its own options (render.ts reads element.options
-    // directly) and an <iframe> holds a separate document — walking into
-    // either only does work whose nodes are discarded downstream, and a
-    // select would leak option text as string children the renderer never
-    // shows.
     const tag = element.tagName.toLowerCase();
     return tag !== "iframe" && tag !== "select";
 }
@@ -156,12 +117,7 @@ function _shouldTraverse(element, context) {
     if (_theSubtreeIsCurated(element, context.options.ignoreSelectors)) {
         return false;
     }
-    // No aria-hidden special case: the visibility oracle reads aria-hidden
-    // (inherited) as hidden, so default reads prune these subtrees below
-    // and show_hidden keeps them, marked — same as any other hidden thing.
     if (!context.options.showHidden && !context.oracle.isVisible(element)) {
-        // Branded-control escape: many designs hide the real radio/checkbox
-        // and render a styled twin; the input still matters.
         if (element instanceof HTMLInputElement) {
             const type = element.type;
             if (type === "radio" || type === "checkbox") {
@@ -189,8 +145,6 @@ function _shouldIncludeNode(element, context) {
     }
     return role !== "generic" && role !== "image";
 }
-/** Push a skipped leaf's accessible name as loose text; true when one
- * was pushed (naming-prohibited roles contribute nothing). */
 function _hoistSkippedLeafName(element, parentNode, context) {
     const name = _normalizedNodeName(accessibleNameOf(element, context.options.probe, context.nameCache));
     if (name === "") {
@@ -199,7 +153,6 @@ function _hoistSkippedLeafName(element, parentNode, context) {
     parentNode.children.push(name);
     return true;
 }
-// --- the ref mint -----------------------------------------------------------
 function _refFor(element, role, name) {
     const badge = _refBadgeByElement.get(element);
     if (badge?.role === role && badge.name === name) {
@@ -212,4 +165,3 @@ function _refFor(element, role, name) {
     _elementByRef.set(ref, element);
     return ref;
 }
-//# sourceMappingURL=snapshot.js.map

package/dist/reader/visibility.d.ts

@@ -4,12 +4,5 @@ export interface VisibilityOracle {
     isOffscreen(element: Element): boolean;
 }
 export declare function visibilityOracleOf(probe: LayoutProbe): VisibilityOracle;
-/** The parent, crossing a shadow root's boundary to its host. */
 export declare function parentAcrossShadowBoundaryOf(element: Element): Element | null;
-/**
- * Light-DOM children followed by shadow-DOM children, flat. Slotted
- * content is traversed at its light-DOM location — the flat view is what
- * the user perceives; no assignedNodes() projection.
- */
 export declare function lightAndShadowChildNodesOf(element: Element): Node[];
-//# sourceMappingURL=visibility.d.ts.map