@silbercue/chrome 0.2.0

package/build/cache/a11y-tree.js

@@ -0,0 +1,1956 @@
+import { wrapCdpError } from "../tools/error-utils.js";
+import { CLICKABLE_TAGS, CLICKABLE_ROLES, COMPUTED_STYLES } from "../tools/visual-constants.js";
+import { EMULATED_WIDTH, EMULATED_HEIGHT } from "../cdp/emulation.js";
+import { debug } from "../cdp/debug.js";
+/** Strip hash fragment from URL for navigation comparison.
+ *  Hash-only changes (anchor navigation) should NOT reset refs. */
+function stripHash(url) {
+    const idx = url.indexOf("#");
+    return idx === -1 ? url : url.slice(0, idx);
+}
+// --- Constants ---
+/** BUG-009: Safety cap to prevent oversized responses that MCP clients truncate silently.
+ *  ~200KB chars ≈ 50K tokens. Large enough for normal pages, prevents 855KB+ responses. */
+const DEFAULT_MAX_TOKENS = 50_000;
+const INTERACTIVE_ROLES = new Set([
+    "button",
+    "link",
+    "textbox",
+    "searchbox",
+    "combobox",
+    "checkbox",
+    "radio",
+    "switch",
+    "slider",
+    "spinbutton",
+    "tab",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "option",
+    "treeitem",
+]);
+// Story 13a.2: Roles included in enriched compact snapshot for LLM orientation
+const CONTEXT_ROLES = new Set([
+    "heading",
+    "alert",
+    "status",
+]);
+const CONTAINER_ROLES = new Set([
+    "generic", "group", "region", "list", "listbox",
+    "navigation", "complementary", "main", "banner",
+    "contentinfo", "form", "search", "toolbar", "tablist",
+    "menu", "menubar", "tree", "grid", "table",
+    "rowgroup", "row", "treegrid",
+]);
+const CONTENT_ROLES = new Set([
+    "heading", "paragraph", "text", "StaticText", "img",
+    "figure", "blockquote", "code", "listitem", "cell",
+    "columnheader", "rowheader", "caption", "definition",
+    "term", "note", "math", "status", "log", "marquee",
+    "timer", "alert",
+]);
+function classifyElement(role) {
+    if (INTERACTIVE_ROLES.has(role))
+        return "interactive";
+    if (CONTENT_ROLES.has(role))
+        return "content";
+    return "container"; // Default: everything else is container
+}
+/** Token estimation for structured A11y output.
+ *  Ratio ~3.5 chars/token accounts for short tokens (brackets, refs, keywords).
+ *  FR-H8: Tighter ratio ensures max_tokens is a reliable upper bound. */
+function estimateTokens(text) {
+    if (text.length === 0)
+        return 0;
+    return Math.ceil(text.length / 3.5);
+}
+const LANDMARK_ROLES = new Set([
+    "banner",
+    "navigation",
+    "main",
+    "complementary",
+    "contentinfo",
+    "search",
+    "form",
+    "region",
+]);
+// Story 13a.2: Extract NodeInfo from AXNode including widget-state properties
+function extractNodeInfo(node) {
+    const info = {
+        role: node.role?.value ?? "",
+        name: node.name?.value ?? "",
+    };
+    if (node.properties) {
+        for (const prop of node.properties) {
+            switch (prop.name) {
+                case "expanded":
+                    info.expanded = prop.value.value;
+                    break;
+                case "hasPopup":
+                    info.hasPopup = prop.value.value;
+                    break;
+                case "checked":
+                    info.checked = prop.value.value;
+                    break;
+                case "pressed":
+                    info.pressed = prop.value.value;
+                    break;
+                case "disabled":
+                    info.disabled = prop.value.value;
+                    break;
+                case "focusable":
+                    info.focusable = prop.value.value;
+                    break;
+                case "level":
+                    info.level = prop.value.value;
+                    break;
+            }
+        }
+    }
+    return info;
+}
+export class A11yTreeProcessor {
+    refMap = new Map(); // backendDOMNodeId → refNumber
+    reverseMap = new Map(); // refNumber → backendDOMNodeId
+    // Story 13a.2: Extended with widget-state props for pre-click classification
+    nodeInfoMap = new Map(); // backendDOMNodeId → NodeInfo
+    sessionNodeMap = new Map(); // sessionId → Set<backendDOMNodeId>
+    nextRef = 1;
+    lastUrl = "";
+    // Precomputed cache state (Story 7.4)
+    _precomputedNodes = null;
+    _precomputedUrl = "";
+    _precomputedSessionId = "";
+    _precomputedDepth = 3;
+    // Story 13.1: Ambient Page Context — cache version counter
+    // Increments on every cache change (refresh, reset, invalidation).
+    // Registry compares this against _lastSentVersion to decide whether to attach page context.
+    _cacheVersion = 0;
+    /** Story 13.1: Current cache version — increments on every state change */
+    get cacheVersion() {
+        return this._cacheVersion;
+    }
+    reset() {
+        this.refMap.clear();
+        this.reverseMap.clear();
+        this.nodeInfoMap.clear();
+        this.sessionNodeMap.clear();
+        this.nextRef = 1;
+        this.lastUrl = "";
+        this._cacheVersion++;
+        this.invalidatePrecomputed();
+    }
+    /** Invalidiert den Precomputed-Cache (z.B. nach Navigation oder Reconnect) */
+    invalidatePrecomputed() {
+        this._precomputedNodes = null;
+        this._precomputedUrl = "";
+        this._precomputedSessionId = "";
+        this._precomputedDepth = 3;
+        this._cacheVersion++;
+    }
+    /** Hintergrund-Refresh: Laedt A11y-Tree und speichert als Cache */
+    async refreshPrecomputed(cdpClient, sessionId, sessionManager) {
+        // 1. URL pruefen — wenn sich die Basis-URL (ohne Hash) geaendert hat, reset() aufrufen
+        //    Hash-only-Aenderungen (z.B. /#step-alpha → /#step-beta) behalten Refs,
+        //    da das DOM bei Anchor-Navigation identisch bleibt.
+        const urlResult = await cdpClient.send("Runtime.evaluate", { expression: "document.URL", returnByValue: true }, sessionId);
+        const currentUrl = urlResult.result.value;
+        if (stripHash(currentUrl) !== stripHash(this.lastUrl)) {
+            this.reset();
+        }
+        this.lastUrl = currentUrl;
+        // 2. A11y-Tree via CDP laden (same depth as default getTree)
+        const result = await cdpClient.send("Accessibility.getFullAXTree", { depth: 3 }, sessionId);
+        if (!result.nodes || result.nodes.length === 0)
+            return;
+        // 3. Ref-IDs zuweisen (STABIL — bestehende Refs bleiben, neue bekommen neue Nummern)
+        for (const node of result.nodes) {
+            if (node.ignored || node.backendDOMNodeId === undefined)
+                continue;
+            if (!this.refMap.has(node.backendDOMNodeId)) {
+                const refNum = this.nextRef++;
+                this.refMap.set(node.backendDOMNodeId, refNum);
+                this.reverseMap.set(refNum, node.backendDOMNodeId);
+            }
+            this.nodeInfoMap.set(node.backendDOMNodeId, extractNodeInfo(node));
+            if (!this.sessionNodeMap.has(sessionId)) {
+                this.sessionNodeMap.set(sessionId, new Set());
+            }
+            this.sessionNodeMap.get(sessionId).add(node.backendDOMNodeId);
+            sessionManager?.registerNode(node.backendDOMNodeId, sessionId);
+        }
+        // 4. Cache speichern
+        this._precomputedNodes = result.nodes;
+        this._precomputedUrl = currentUrl;
+        this._precomputedSessionId = sessionId;
+        this._precomputedDepth = 3;
+        this._cacheVersion++;
+        // 5. Register root node for Accessibility.nodesUpdated tracking (Story 13a.2 fix).
+        // getFullAXTree does NOT populate Chrome's nodes_requested_ set, so nodesUpdated
+        // never fires. A single getRootAXNode call registers the root — 1 extra CDP call.
+        try {
+            await cdpClient.send("Accessibility.getRootAXNode", {}, sessionId);
+        }
+        catch {
+            // Non-critical — nodesUpdated won't work but everything else still does
+            debug("A11yTreeProcessor: getRootAXNode failed (nodesUpdated tracking disabled)");
+        }
+        // 6. FR-004 + FR-005: Enrich nodes with HTML attributes and click listeners
+        await this._enrichNodeMetadata(cdpClient, sessionId);
+        // Phase 3: FR-001 — detect scrollable containers (1 CDP call total)
+        try {
+            const scrollResult = await cdpClient.send("Runtime.evaluate", {
+                expression: `JSON.stringify([...document.querySelectorAll('*')].filter(el => { const s = getComputedStyle(el); return (s.overflowY === 'auto' || s.overflowY === 'scroll') && el.scrollHeight > el.clientHeight; }).map(el => el.id).filter(Boolean))`,
+                returnByValue: true,
+            }, sessionId);
+            const scrollableIds = JSON.parse(scrollResult.result.value || "[]");
+            for (const id of scrollableIds) {
+                for (const [backendNodeId, info] of this.nodeInfoMap) {
+                    if (info.htmlId === id) {
+                        info.isScrollable = true;
+                        break;
+                    }
+                }
+            }
+        }
+        catch {
+            // Non-critical — scrollable annotation is nice-to-have
+        }
+        debug("A11yTreeProcessor: precomputed cache refreshed, %d nodes cached (v%d)", result.nodes.length, this._cacheVersion);
+    }
+    /** Prueft ob ein gueltiger Precomputed-Cache vorliegt */
+    hasPrecomputed(sessionId) {
+        return this._precomputedNodes !== null
+            && this._precomputedSessionId === sessionId;
+    }
+    /**
+     * H1: Remove all node references for a detached OOPIF session.
+     * Called when an OOPIF frame navigates away or is destroyed.
+     */
+    removeNodesForSession(sessionId) {
+        const nodeIds = this.sessionNodeMap.get(sessionId);
+        if (!nodeIds)
+            return;
+        for (const backendNodeId of nodeIds) {
+            const refNum = this.refMap.get(backendNodeId);
+            if (refNum !== undefined) {
+                this.reverseMap.delete(refNum);
+            }
+            this.refMap.delete(backendNodeId);
+            this.nodeInfoMap.delete(backendNodeId);
+        }
+        this.sessionNodeMap.delete(sessionId);
+    }
+    resolveRef(ref) {
+        const match = ref.match(/^e(\d+)$/);
+        if (!match)
+            return undefined;
+        const refNum = parseInt(match[1], 10);
+        return this.reverseMap.get(refNum);
+    }
+    getNodeInfo(backendNodeId) {
+        return this.nodeInfoMap.get(backendNodeId);
+    }
+    /**
+     * UX-001: Find an element by visible text (name). Returns ref string and backendNodeId.
+     * Matching priority: exact → case-insensitive exact → partial substring.
+     * Within each tier, interactive roles (button, link, etc.) are preferred.
+     */
+    findByText(text) {
+        if (!text || this.reverseMap.size === 0)
+            return null;
+        const lower = text.toLowerCase();
+        const exact = [];
+        const iexact = [];
+        const partial = [];
+        for (const [refNum, backendNodeId] of this.reverseMap) {
+            const info = this.nodeInfoMap.get(backendNodeId);
+            if (!info || !info.name)
+                continue;
+            const interactive = INTERACTIVE_ROLES.has(info.role) || !!info.isClickable;
+            if (info.name === text) {
+                exact.push({ refNum, backendNodeId, interactive });
+            }
+            else if (info.name.toLowerCase() === lower) {
+                iexact.push({ refNum, backendNodeId, interactive });
+            }
+            else if (info.name.toLowerCase().includes(lower)) {
+                partial.push({ refNum, backendNodeId, interactive });
+            }
+        }
+        // Pick best candidate: prefer interactive, then lowest refNum (most stable)
+        const pick = (candidates) => {
+            const interactive = candidates.filter(c => c.interactive);
+            const best = (interactive.length > 0 ? interactive : candidates)
+                .sort((a, b) => a.refNum - b.refNum)[0];
+            return best ? { ref: `e${best.refNum}`, backendNodeId: best.backendNodeId } : null;
+        };
+        return pick(exact) ?? pick(iexact) ?? pick(partial);
+    }
+    /** Returns true if the ref map has been populated (i.e. getTree was called at least once). */
+    hasRefs() {
+        return this.refMap.size > 0;
+    }
+    /** Number of currently assigned refs (for DOM fingerprinting, Story 7.5) */
+    get refCount() {
+        return this.refMap.size;
+    }
+    /** Current page URL (for on-the-fly fingerprint computation, Story 7.5 H1 fix) */
+    get currentUrl() {
+        return this.lastUrl;
+    }
+    getRefForBackendNodeId(backendNodeId) {
+        const refNum = this.refMap.get(backendNodeId);
+        return refNum !== undefined ? `e${refNum}` : undefined;
+    }
+    async fetchVisualData(cdpClient, sessionId) {
+        const snapshot = await cdpClient.send("DOMSnapshot.captureSnapshot", {
+            computedStyles: [...COMPUTED_STYLES],
+            includeDOMRects: true,
+            includeBlendedBackgroundColors: true,
+            includePaintOrder: true,
+        }, sessionId);
+        const visualMap = new Map();
+        if (!snapshot.documents || snapshot.documents.length === 0) {
+            return visualMap;
+        }
+        const doc = snapshot.documents[0];
+        const strings = snapshot.strings;
+        // Build layout index map: nodeIndex → layoutIndex
+        const layoutMap = new Map();
+        for (let li = 0; li < doc.layout.nodeIndex.length; li++) {
+            layoutMap.set(doc.layout.nodeIndex[li], li);
+        }
+        const totalNodes = doc.nodes.backendNodeId.length;
+        for (let ni = 0; ni < totalNodes; ni++) {
+            const backendNodeId = doc.nodes.backendNodeId[ni];
+            // Only process nodes that have a ref (i.e., are in the A11y tree)
+            if (!this.refMap.has(backendNodeId))
+                continue;
+            const li = layoutMap.get(ni);
+            // No layout → hidden element
+            if (li === undefined) {
+                visualMap.set(backendNodeId, {
+                    bounds: { x: 0, y: 0, w: 0, h: 0 },
+                    isClickable: this.computeIsClickable(ni, backendNodeId, doc, strings),
+                    isVisible: false,
+                });
+                continue;
+            }
+            // Read bounds
+            const boundsArr = doc.layout.bounds[li];
+            if (!boundsArr || boundsArr.length < 4)
+                continue;
+            const [x, y, w, h] = boundsArr;
+            // Read computed styles: display, visibility are at indices 0, 1
+            const styleProps = doc.layout.styles[li] ?? [];
+            const displayVal = this.getSnapshotString(strings, styleProps[0]);
+            const visibilityVal = this.getSnapshotString(strings, styleProps[1]);
+            // isVisible calculation
+            const isVisible = displayVal !== "none" &&
+                visibilityVal !== "hidden" &&
+                w >= 1 && h >= 1 &&
+                x + w > 0 && y + h > 0 &&
+                x < EMULATED_WIDTH && y < EMULATED_HEIGHT;
+            const isClickable = this.computeIsClickable(ni, backendNodeId, doc, strings);
+            visualMap.set(backendNodeId, {
+                bounds: {
+                    x: Math.round(x),
+                    y: Math.round(y),
+                    w: Math.round(w),
+                    h: Math.round(h),
+                },
+                isClickable,
+                isVisible,
+            });
+        }
+        return visualMap;
+    }
+    /**
+     * FR-H5: Enrich nodeInfoMap with HTML attributes (IDs, onclick) and event listeners.
+     * Phase 1: DOM.describeNode for HTML IDs + inline onclick detection
+     * Phase 2: DOMDebugger.getEventListeners for non-interactive nodes (mousedown, click, pointerdown)
+     * Called from both refreshPrecomputed() and getTree() so read_page always has full data.
+     */
+    async _enrichNodeMetadata(cdpClient, sessionId) {
+        const POTENTIALLY_CLICKABLE_ROLES = new Set(["columnheader", "rowheader", "cell", "generic", "listitem"]);
+        try {
+            const interactiveNodes = [];
+            const checkClickNodes = [];
+            for (const [backendNodeId, info] of this.nodeInfoMap) {
+                if (INTERACTIVE_ROLES.has(info.role) || CONTEXT_ROLES.has(info.role)) {
+                    interactiveNodes.push(backendNodeId);
+                }
+                else if (POTENTIALLY_CLICKABLE_ROLES.has(info.role)) {
+                    interactiveNodes.push(backendNodeId);
+                    checkClickNodes.push(backendNodeId);
+                }
+            }
+            // Phase 1: Batch DOM.describeNode — extract HTML IDs + inline onclick
+            if (interactiveNodes.length > 0 && interactiveNodes.length <= 500) {
+                await Promise.allSettled(interactiveNodes.map(async (backendNodeId) => {
+                    try {
+                        const desc = await cdpClient.send("DOM.describeNode", { backendNodeId, depth: 0 }, sessionId);
+                        const attrs = desc.node?.attributes;
+                        if (!attrs)
+                            return;
+                        const info = this.nodeInfoMap.get(backendNodeId);
+                        if (!info)
+                            return;
+                        for (let i = 0; i < attrs.length; i += 2) {
+                            if (attrs[i] === "id" && attrs[i + 1]) {
+                                info.htmlId = attrs[i + 1];
+                            }
+                            if (attrs[i] === "onclick") {
+                                info.isClickable = true;
+                            }
+                            if (attrs[i] === "target" && attrs[i + 1]) {
+                                info.linkTarget = attrs[i + 1];
+                            }
+                        }
+                    }
+                    catch { /* ignore — text nodes etc. don't support describeNode */ }
+                }));
+            }
+            // Phase 2: DOMDebugger.getEventListeners for non-interactive nodes without onclick attribute.
+            // Detects addEventListener, React synthetic events, jQuery — anything that registered a click handler.
+            const clickCandidates = checkClickNodes.filter(id => !this.nodeInfoMap.get(id)?.isClickable);
+            if (clickCandidates.length > 0 && clickCandidates.length <= 200) {
+                await Promise.allSettled(clickCandidates.map(async (backendNodeId) => {
+                    try {
+                        const resolved = await cdpClient.send("DOM.resolveNode", { backendNodeId }, sessionId);
+                        const objectId = resolved.object?.objectId;
+                        if (!objectId)
+                            return;
+                        const result = await cdpClient.send("DOMDebugger.getEventListeners", { objectId }, sessionId);
+                        if (result.listeners?.some(l => l.type === "click" || l.type === "mousedown" || l.type === "pointerdown")) {
+                            const info = this.nodeInfoMap.get(backendNodeId);
+                            if (info)
+                                info.isClickable = true;
+                        }
+                        await cdpClient.send("Runtime.releaseObject", { objectId }, sessionId).catch(() => { });
+                    }
+                    catch { /* ignore — some nodes can't be resolved */ }
+                }));
+            }
+            // Phase 3: FR-H5 — Enrich unnamed clickable generics with innerText.
+            // Separate pass with fresh resolveNode to avoid stale objectId issues.
+            const unnamedClickables = [...this.nodeInfoMap.entries()]
+                .filter(([, info]) => info.isClickable && !info.name && POTENTIALLY_CLICKABLE_ROLES.has(info.role));
+            if (unnamedClickables.length > 0 && unnamedClickables.length <= 100) {
+                await Promise.allSettled(unnamedClickables.map(async ([backendNodeId, info]) => {
+                    try {
+                        const resolved = await cdpClient.send("DOM.resolveNode", { backendNodeId }, sessionId);
+                        const oid = resolved.object?.objectId;
+                        if (!oid)
+                            return;
+                        // FR-021: Fetch truncated text AND full length so formatLine can show a truncation marker.
+                        // Separator \x00 avoids JSON/object marshalling overhead — one string roundtrip, simple split.
+                        const textResult = await cdpClient.send("Runtime.callFunctionOn", { functionDeclaration: "function(){const t=(this.innerText||this.textContent||'');return t.slice(0,80)+'\\x00'+t.length}", objectId: oid, returnByValue: true }, sessionId);
+                        if (textResult.result.value) {
+                            const sep = textResult.result.value.indexOf("\x00");
+                            if (sep >= 0) {
+                                const truncated = textResult.result.value.slice(0, sep);
+                                const fullLength = parseInt(textResult.result.value.slice(sep + 1), 10);
+                                if (truncated) {
+                                    info.name = truncated;
+                                    if (Number.isFinite(fullLength) && fullLength > truncated.length) {
+                                        info.nameFullLength = fullLength;
+                                    }
+                                }
+                            }
+                            else {
+                                info.name = textResult.result.value; // Legacy fallback
+                            }
+                        }
+                        await cdpClient.send("Runtime.releaseObject", { objectId: oid }, sessionId).catch(() => { });
+                    }
+                    catch { /* non-critical */ }
+                }));
+            }
+        }
+        catch {
+            // Non-critical — IDs and clickability are nice-to-have
+        }
+    }
+    computeIsClickable(nodeIndex, backendNodeId, doc, strings) {
+        // Tag from DOMSnapshot
+        const tag = this.getSnapshotString(strings, doc.nodes.nodeName[nodeIndex]);
+        if (CLICKABLE_TAGS.has(tag))
+            return true;
+        // Role from A11y tree nodeInfoMap
+        const nodeInfo = this.nodeInfoMap.get(backendNodeId);
+        if (nodeInfo && CLICKABLE_ROLES.has(nodeInfo.role))
+            return true;
+        return false;
+    }
+    getSnapshotString(strings, index) {
+        if (index === undefined || index < 0 || index >= strings.length)
+            return "";
+        return strings[index];
+    }
+    findClosestRef(ref, roleFilter) {
+        const match = ref.match(/^e(\d+)$/);
+        if (!match || this.reverseMap.size === 0)
+            return null;
+        const requested = parseInt(match[1], 10);
+        // Build candidate list, optionally filtered by role
+        const candidates = [];
+        for (const [refNum, backendNodeId] of this.reverseMap.entries()) {
+            const info = this.nodeInfoMap.get(backendNodeId);
+            const role = info?.role ?? "";
+            if (roleFilter && !roleFilter.has(role))
+                continue;
+            candidates.push({ refNum, backendNodeId, role, name: info?.name ?? "" });
+        }
+        if (candidates.length === 0)
+            return null;
+        let closest = candidates[0];
+        let minDist = Math.abs(requested - closest.refNum);
+        for (const c of candidates) {
+            const dist = Math.abs(requested - c.refNum);
+            if (dist < minDist) {
+                closest = c;
+                minDist = dist;
+            }
+        }
+        return {
+            ref: `e${closest.refNum}`,
+            role: closest.role,
+            name: closest.name,
+        };
+    }
+    async getTree(cdpClient, sessionId, options = {}, sessionManager) {
+        const depth = options.depth ?? 3;
+        const filter = options.filter ?? "interactive";
+        // FR-002: Separate CDP fetch depth from display depth.
+        // Interactive/visual filters need deeper fetch to find elements nested beyond display depth.
+        // "all" fetches depth+2 so leaf nodes' text children (StaticText) are always included —
+        // without this, elements like <strong> at the depth limit appear empty.
+        // "landmark" uses moderate depth.
+        const cdpFetchDepth = (filter === "interactive" || filter === "visual")
+            ? Math.max(depth, 10)
+            : filter === "landmark"
+                ? Math.max(depth, 6)
+                : depth + 2;
+        // Navigation detection — reset refs on real navigation (path change),
+        // but preserve refs on hash-only changes (anchor navigation).
+        const urlResult = await cdpClient.send("Runtime.evaluate", { expression: "document.URL", returnByValue: true }, sessionId);
+        const currentUrl = urlResult.result.value;
+        if (stripHash(currentUrl) !== stripHash(this.lastUrl)) {
+            this.refMap.clear();
+            this.reverseMap.clear();
+            this.nodeInfoMap.clear();
+            this.nextRef = 1;
+            this.invalidatePrecomputed();
+        }
+        this.lastUrl = currentUrl;
+        // Precomputed cache check — bypass CDP call if cache is valid (Story 7.4)
+        // Subtree queries (options.ref) always load fresh — cached tree may not have full depth
+        // M1: Depth mismatch → cache miss (cached depth must be >= requested depth)
+        // Story 13a.2 fix: fresh=true bypasses cache (read_page after SPA navigation)
+        let nodes;
+        if (!options.fresh
+            && this._precomputedNodes
+            && this._precomputedSessionId === sessionId
+            && currentUrl === this._precomputedUrl
+            && !options.ref
+            && cdpFetchDepth <= this._precomputedDepth) {
+            nodes = this._precomputedNodes;
+            debug("A11yTreeProcessor: precomputed cache hit");
+        }
+        else {
+            // Fetch A11y tree from CDP — main frame (fallback / cache miss)
+            // FR-002: Use cdpFetchDepth (not display depth) so interactive/visual filters find deeply nested elements
+            const result = await cdpClient.send("Accessibility.getFullAXTree", { depth: cdpFetchDepth }, sessionId);
+            nodes = result.nodes;
+            // H1: Prime precomputed cache on fallback (AC #5)
+            // Only prime if this is a full-tree query (no ref) with valid nodes
+            if (!options.ref && nodes && nodes.length > 0) {
+                this._precomputedNodes = nodes;
+                this._precomputedUrl = currentUrl;
+                this._precomputedSessionId = sessionId;
+                this._precomputedDepth = cdpFetchDepth;
+                debug("A11yTreeProcessor: cache primed from fallback, %d nodes", nodes.length);
+            }
+        }
+        if (!nodes || nodes.length === 0) {
+            const emptyText = this.formatHeader("", 0, filter, depth);
+            return {
+                text: emptyText,
+                refCount: 0,
+                depth,
+                tokenCount: estimateTokens(emptyText),
+                pageUrl: this.lastUrl,
+                ...(filter === "visual" ? { hasVisualData: false } : {}),
+            };
+        }
+        // Build nodeId → AXNode map
+        const nodeMap = new Map();
+        for (const node of nodes) {
+            nodeMap.set(node.nodeId, node);
+        }
+        // Assign refs to all non-ignored nodes with backendDOMNodeId (main frame)
+        for (const node of nodes) {
+            if (node.ignored || node.backendDOMNodeId === undefined)
+                continue;
+            if (!this.refMap.has(node.backendDOMNodeId)) {
+                const refNum = this.nextRef++;
+                this.refMap.set(node.backendDOMNodeId, refNum);
+                this.reverseMap.set(refNum, node.backendDOMNodeId);
+            }
+            // Always update nodeInfoMap with latest role/name
+            this.nodeInfoMap.set(node.backendDOMNodeId, extractNodeInfo(node));
+            // Track which session owns this node (H1: for cleanup on detach)
+            if (!this.sessionNodeMap.has(sessionId)) {
+                this.sessionNodeMap.set(sessionId, new Set());
+            }
+            this.sessionNodeMap.get(sessionId).add(node.backendDOMNodeId);
+            // Register node with SessionManager for main frame
+            sessionManager?.registerNode(node.backendDOMNodeId, sessionId);
+        }
+        // Fetch OOPIF A11y trees if SessionManager is available
+        const oopifSections = [];
+        if (sessionManager) {
+            const sessions = sessionManager.getAllSessions();
+            const oopifSessions = sessions.filter((s) => !s.isMain);
+            if (oopifSessions.length > 0) {
+                const oopifResults = await Promise.all(oopifSessions.map(async (s) => {
+                    try {
+                        const oopifResult = await cdpClient.send("Accessibility.getFullAXTree", { depth: cdpFetchDepth }, s.sessionId);
+                        return { url: s.url, nodes: oopifResult.nodes ?? [], sessionId: s.sessionId };
+                    }
+                    catch (err) {
+                        // M1: OOPIF may have been detached between getAllSessions and fetch
+                        wrapCdpError(err, "A11yTreeProcessor.getTree(OOPIF)");
+                        return { url: s.url, nodes: [], sessionId: s.sessionId };
+                    }
+                }));
+                for (const oopifResult of oopifResults) {
+                    if (oopifResult.nodes.length > 0) {
+                        oopifSections.push(oopifResult);
+                        // Assign refs and register nodes for OOPIF
+                        for (const node of oopifResult.nodes) {
+                            // Add to nodeMap with session-prefixed keys to avoid collisions
+                            nodeMap.set(`${oopifResult.sessionId}:${node.nodeId}`, node);
+                            if (node.ignored || node.backendDOMNodeId === undefined)
+                                continue;
+                            if (!this.refMap.has(node.backendDOMNodeId)) {
+                                const refNum = this.nextRef++;
+                                this.refMap.set(node.backendDOMNodeId, refNum);
+                                this.reverseMap.set(refNum, node.backendDOMNodeId);
+                            }
+                            this.nodeInfoMap.set(node.backendDOMNodeId, {
+                                role: node.role?.value ?? "",
+                                name: node.name?.value ?? "",
+                            });
+                            // Track which session owns this node (H1: for cleanup on detach)
+                            if (!this.sessionNodeMap.has(oopifResult.sessionId)) {
+                                this.sessionNodeMap.set(oopifResult.sessionId, new Set());
+                            }
+                            this.sessionNodeMap.get(oopifResult.sessionId).add(node.backendDOMNodeId);
+                            sessionManager.registerNode(node.backendDOMNodeId, oopifResult.sessionId);
+                        }
+                    }
+                }
+            }
+        }
+        // FR-H5: Enrich nodes with HTML attributes + event listener detection.
+        // Runs in getTree() so read_page(filter: "interactive") sees clickable divs/listItems.
+        await this._enrichNodeMetadata(cdpClient, sessionId);
+        // Fetch visual data only for "visual" filter — zero overhead for other filters
+        let visualMap;
+        let visualDataFailed = false;
+        if (filter === "visual") {
+            try {
+                visualMap = await this.fetchVisualData(cdpClient, sessionId);
+            }
+            catch {
+                // M1: DOMSnapshot may fail on certain pages — fall back to tree without visual data
+                visualMap = undefined;
+                visualDataFailed = true;
+            }
+        }
+        // Handle subtree query
+        if (options.ref) {
+            // For subtree, search across all nodes (main + OOPIF)
+            const allNodes = [...nodes];
+            for (const section of oopifSections) {
+                allNodes.push(...section.nodes);
+            }
+            // Build a combined nodeMap for subtree
+            const combinedNodeMap = new Map();
+            for (const node of allNodes) {
+                combinedNodeMap.set(node.nodeId, node);
+            }
+            return this.getSubtree(options.ref, combinedNodeMap, allNodes, filter, depth, visualMap, visualDataFailed, options.max_tokens);
+        }
+        // Get page title from root node
+        const pageTitle = this.getPageTitle(nodes);
+        // Build tree text from root (main frame)
+        const root = nodes[0];
+        const lines = [];
+        // Ticket-1: Pre-scan the whole tree (main + OOPIFs) to identify groups
+        // of ≥10 same-class leaves that should collapse into summary lines.
+        // Must run BEFORE renderNode so anchors/suppressed ids are visible to
+        // every walk path.
+        this.prepareAggregateGroups(root, nodeMap, oopifSections, filter);
+        this.renderNode(root, nodeMap, 0, filter, lines, visualMap);
+        // Append OOPIF sections
+        for (const section of oopifSections) {
+            const oopifNodeMap = new Map();
+            for (const node of section.nodes) {
+                oopifNodeMap.set(node.nodeId, node);
+            }
+            lines.push(`--- iframe: ${section.url} ---`);
+            if (section.nodes.length > 0) {
+                this.renderNode(section.nodes[0], oopifNodeMap, 0, filter, lines, visualMap);
+            }
+        }
+        this.clearAggregateGroups();
+        // H5: Count only actual element lines, not separator lines (--- iframe: ... ---)
+        const refCount = lines.filter((l) => !l.startsWith("--- ")).length;
+        // FR-022: Count content nodes (StaticText/paragraph/etc.) hidden by filter:interactive,
+        // so read-page.ts can append a hint pointing the LLM at filter:'all' instead of evaluate.
+        const hiddenContentCount = filter === "interactive"
+            ? this.countHiddenContentNodes(root, nodeMap, oopifSections)
+            : undefined;
+        const text = this.formatHeader(pageTitle, refCount, filter, depth)
+            + (lines.length > 0 ? "\n\n" + lines.join("\n") : "");
+        // Token-Budget Downsampling — explicit max_tokens or BUG-009 safety cap
+        const effectiveMaxTokens = options.max_tokens ?? DEFAULT_MAX_TOKENS;
+        const currentTokens = estimateTokens(text);
+        if (currentTokens > effectiveMaxTokens) {
+            const downsampled = this.downsampleTree(root, nodeMap, filter, effectiveMaxTokens, oopifSections, visualMap);
+            const dsHeader = this.formatDownsampledHeader(pageTitle, downsampled.refCount, filter, depth, currentTokens, downsampled.level);
+            // C2: Final budget check — trim body if header+body exceeds budget
+            let dsBody = downsampled.lines.join("\n");
+            const fullText = dsHeader + (dsBody ? "\n\n" + dsBody : "");
+            if (estimateTokens(fullText) > effectiveMaxTokens && dsBody) {
+                const headerTokens = estimateTokens(dsHeader + "\n\n");
+                const bodyBudget = effectiveMaxTokens - headerTokens;
+                const trimmed = this.trimBodyToFit(downsampled.lines, bodyBudget);
+                dsBody = trimmed.join("\n");
+            }
+            const dsText = dsHeader + (dsBody ? "\n\n" + dsBody : "");
+            return {
+                text: dsText,
+                refCount: downsampled.refCount,
+                depth,
+                tokenCount: estimateTokens(dsText),
+                pageUrl: this.lastUrl,
+                downsampled: true,
+                originalTokens: currentTokens,
+                downsampleLevel: downsampled.level,
+                ...(filter === "visual" ? { hasVisualData: !visualDataFailed } : {}),
+                ...(hiddenContentCount !== undefined ? { hiddenContentCount } : {}),
+            };
+        }
+        return {
+            text,
+            refCount,
+            depth,
+            tokenCount: currentTokens,
+            pageUrl: this.lastUrl,
+            ...(filter === "visual" ? { hasVisualData: !visualDataFailed } : {}),
+            ...(hiddenContentCount !== undefined ? { hiddenContentCount } : {}),
+        };
+    }
+    // --- Downsampling Pipeline (D2Snap) ---
+    downsampleTree(root, nodeMap, filter, maxTokens, oopifSections, visualMap) {
+        // Try levels 0-4 sequentially until budget is met
+        for (let level = 0; level <= 4; level++) {
+            const lines = [];
+            this.renderNodeDownsampled(root, nodeMap, 0, filter, lines, level, visualMap);
+            // Append OOPIF sections
+            for (const section of oopifSections) {
+                const oopifNodeMap = new Map();
+                for (const node of section.nodes) {
+                    oopifNodeMap.set(node.nodeId, node);
+                }
+                lines.push(`--- iframe: ${section.url} ---`);
+                if (section.nodes.length > 0) {
+                    this.renderNodeDownsampled(section.nodes[0], oopifNodeMap, 0, filter, lines, level, visualMap);
+                }
+            }
+            const refCount = lines.filter((l) => !l.startsWith("--- ")).length;
+            // Estimate tokens including a header estimate (~60 chars)
+            const estimatedTotal = estimateTokens(lines.join("\n")) + 15;
+            if (estimatedTotal <= maxTokens) {
+                return { lines, refCount, level };
+            }
+        }
+        // Level 4 still too large → truncate as last resort
+        const lines = [];
+        this.renderNodeDownsampled(root, nodeMap, 0, filter, lines, 4, visualMap);
+        // Append OOPIF sections
+        for (const section of oopifSections) {
+            const oopifNodeMap = new Map();
+            for (const node of section.nodes) {
+                oopifNodeMap.set(node.nodeId, node);
+            }
+            lines.push(`--- iframe: ${section.url} ---`);
+            if (section.nodes.length > 0) {
+                this.renderNodeDownsampled(section.nodes[0], oopifNodeMap, 0, filter, lines, 4, visualMap);
+            }
+        }
+        return this.truncateToFit(lines, maxTokens);
+    }
+    truncateToFit(lines, maxTokens) {
+        // C3: Prioritize elements: dialogs/modals > interactive > content
+        const dialogLines = [];
+        const interactiveLines = [];
+        const contentLines = [];
+        // Track dialog context: lines inside a dialog subtree get dialog priority
+        let insideDialog = false;
+        let dialogIndent = -1;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const indent = line.search(/\S/);
+            // Detect dialog/modal boundaries
+            const roleMatch = line.match(/\[e\d+\]\s+(\S+)/);
+            const role = roleMatch ? roleMatch[1] : "";
+            if (role === "dialog" || role === "alertdialog") {
+                insideDialog = true;
+                dialogIndent = indent;
+                dialogLines.push({ line, idx: i });
+                continue;
+            }
+            // If we were inside a dialog and indentation decreased back to/beyond dialog level, we left the dialog
+            if (insideDialog && indent <= dialogIndent && i > 0) {
+                insideDialog = false;
+                dialogIndent = -1;
+            }
+            if (insideDialog) {
+                dialogLines.push({ line, idx: i });
+            }
+            else if (/\[e\d+\]/.test(line) && INTERACTIVE_ROLES.has(role)) {
+                // Demote option elements to content priority — they fill token budget
+                // without adding actionable value (the combobox itself shows the current value)
+                if (role === "option") {
+                    contentLines.push({ line, idx: i });
+                }
+                else {
+                    interactiveLines.push({ line, idx: i });
+                }
+            }
+            else {
+                contentLines.push({ line, idx: i });
+            }
+        }
+        // Build result: dialogs first, then interactive, then content
+        const result = [];
+        let tokensSoFar = 15; // header estimate
+        const addedIndices = new Set();
+        // Phase 0: Add all dialog/modal elements (highest priority — always visible)
+        for (const { line, idx } of dialogLines) {
+            const lineTokens = estimateTokens(line + "\n");
+            if (tokensSoFar + lineTokens > maxTokens - 15)
+                break;
+            result.push(line);
+            addedIndices.add(idx);
+            tokensSoFar += lineTokens;
+        }
+        // Phase 1: Add interactive elements
+        for (const { line, idx } of interactiveLines) {
+            const lineTokens = estimateTokens(line + "\n");
+            if (tokensSoFar + lineTokens > maxTokens - 15)
+                break;
+            result.push(line);
+            addedIndices.add(idx);
+            tokensSoFar += lineTokens;
+        }
+        // Phase 2: Fill remaining budget with content lines
+        for (const { line, idx } of contentLines) {
+            const lineTokens = estimateTokens(line + "\n");
+            if (tokensSoFar + lineTokens > maxTokens - 15)
+                break;
+            result.push(line);
+            addedIndices.add(idx);
+            tokensSoFar += lineTokens;
+        }
+        // Add truncation marker if lines were omitted
+        const omitted = lines.length - addedIndices.size;
+        if (omitted > 0) {
+            result.push(`... (truncated, ${omitted} elements omitted)`);
+        }
+        // Re-sort by original index to maintain document order
+        const sortedResult = result
+            .filter((l) => !l.startsWith("..."))
+            .map((l) => {
+            // Find original index
+            const origIdx = lines.indexOf(l);
+            return { line: l, idx: origIdx };
+        })
+            .sort((a, b) => a.idx - b.idx)
+            .map((entry) => entry.line);
+        // Append truncation marker at the end
+        if (omitted > 0) {
+            sortedResult.push(`... (truncated, ${omitted} elements omitted)`);
+        }
+        const refCount = sortedResult.filter((l) => !l.startsWith("--- ") && !l.startsWith("...")).length;
+        return { lines: sortedResult, refCount, level: 4 };
+    }
+    /** C2: Trim body lines from the end (content first) until budget is met */
+    trimBodyToFit(lines, bodyBudgetTokens) {
+        if (bodyBudgetTokens <= 0)
+            return [];
+        // Separate interactive and content lines
+        const interactiveIndices = new Set();
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const roleMatch = line.match(/\[e\d+\]\s+(\S+)/);
+            const role = roleMatch ? roleMatch[1] : "";
+            if (INTERACTIVE_ROLES.has(role)) {
+                interactiveIndices.add(i);
+            }
+        }
+        // Try removing content lines from the end first
+        const result = [...lines];
+        while (estimateTokens(result.join("\n")) > bodyBudgetTokens && result.length > 0) {
+            // Find last non-interactive line to remove
+            let removedContent = false;
+            for (let i = result.length - 1; i >= 0; i--) {
+                const roleMatch = result[i].match(/\[e\d+\]\s+(\S+)/);
+                const role = roleMatch ? roleMatch[1] : "";
+                if (!INTERACTIVE_ROLES.has(role)) {
+                    result.splice(i, 1);
+                    removedContent = true;
+                    break;
+                }
+            }
+            // If only interactive lines remain and still over budget, remove from end
+            if (!removedContent) {
+                result.pop();
+            }
+        }
+        return result;
+    }
+    renderNodeDownsampled(node, nodeMap, indentLevel, filter, lines, level, visualMap) {
+        if (node.ignored) {
+            this.renderChildrenDownsampled(node, nodeMap, indentLevel, filter, lines, level, visualMap);
+            return;
+        }
+        const role = this.getRole(node);
+        const elementClass = classifyElement(role);
+        const passesFilter = this.passesFilter(node, role, filter);
+        if (!passesFilter) {
+            // Not passing filter — skip but process children at same indent
+            this.renderChildrenDownsampled(node, nodeMap, indentLevel, filter, lines, level, visualMap);
+            return;
+        }
+        if (node.backendDOMNodeId === undefined) {
+            this.renderChildrenDownsampled(node, nodeMap, indentLevel, filter, lines, level, visualMap);
+            return;
+        }
+        const refNum = this.refMap.get(node.backendDOMNodeId);
+        if (refNum === undefined) {
+            this.renderChildrenDownsampled(node, nodeMap, indentLevel, filter, lines, level, visualMap);
+            return;
+        }
+        const indent = "  ".repeat(indentLevel);
+        if (elementClass === "interactive") {
+            // Interactive: ALWAYS fully preserved
+            let line = this.formatLine(indent, refNum, role, node, nodeMap);
+            if (visualMap) {
+                const vi = visualMap.get(node.backendDOMNodeId);
+                if (vi && vi.bounds.w > 0 && vi.bounds.h > 0) {
+                    line += ` [${vi.bounds.x},${vi.bounds.y} ${vi.bounds.w}x${vi.bounds.h}]`;
+                    if (vi.isClickable)
+                        line += " click";
+                    if (vi.isVisible)
+                        line += " vis";
+                }
+                else {
+                    line += " [hidden]";
+                }
+            }
+            lines.push(line);
+            this.renderChildrenDownsampled(node, nodeMap, indentLevel + 1, filter, lines, level, visualMap);
+        }
+        else if (elementClass === "content") {
+            if (level < 4) {
+                // Content at levels 0-3: unchanged
+                let line = this.formatLine(indent, refNum, role, node, nodeMap);
+                if (visualMap) {
+                    const vi = visualMap.get(node.backendDOMNodeId);
+                    if (vi && vi.bounds.w > 0 && vi.bounds.h > 0) {
+                        line += ` [${vi.bounds.x},${vi.bounds.y} ${vi.bounds.w}x${vi.bounds.h}]`;
+                        if (vi.isClickable)
+                            line += " click";
+                        if (vi.isVisible)
+                            line += " vis";
+                    }
+                    else {
+                        line += " [hidden]";
+                    }
+                }
+                lines.push(line);
+                this.renderChildrenDownsampled(node, nodeMap, indentLevel + 1, filter, lines, level, visualMap);
+            }
+            else {
+                // Content at level 4: compact Markdown
+                const name = node.name?.value ?? "";
+                if (role === "heading") {
+                    lines.push(`${indent}# ${name} (e${refNum})`);
+                }
+                else if (role === "listitem") {
+                    const truncName = name.length > 100 ? name.slice(0, 97) + "..." : name;
+                    lines.push(`${indent}- ${truncName} (e${refNum})`);
+                }
+                else {
+                    // paragraph, StaticText, img, etc.
+                    const truncName = name.length > 100 ? name.slice(0, 97) + "..." : name;
+                    if (truncName) {
+                        lines.push(`${indent}${truncName} (e${refNum})`);
+                    }
+                }
+                // Still render children for content nodes (they may have interactive children)
+                this.renderChildrenDownsampled(node, nodeMap, indentLevel + 1, filter, lines, level, visualMap);
+            }
+        }
+        else {
+            // Container
+            if (level === 0) {
+                // Level 0: no merging, render normally
+                let line = this.formatLine(indent, refNum, role, node, nodeMap);
+                if (visualMap) {
+                    const vi = visualMap.get(node.backendDOMNodeId);
+                    if (vi && vi.bounds.w > 0 && vi.bounds.h > 0) {
+                        line += ` [${vi.bounds.x},${vi.bounds.y} ${vi.bounds.w}x${vi.bounds.h}]`;
+                        if (vi.isClickable)
+                            line += " click";
+                        if (vi.isVisible)
+                            line += " vis";
+                    }
+                    else {
+                        line += " [hidden]";
+                    }
+                }
+                lines.push(line);
+                this.renderChildrenDownsampled(node, nodeMap, indentLevel + 1, filter, lines, level, visualMap);
+            }
+            else if (level === 1) {
+                // Level 1: remove empty containers (no children)
+                const childCount = this.countVisibleChildren(node, nodeMap);
+                if (childCount === 0) {
+                    // H3: Even if no visible direct children, check for interactive descendants
+                    if (this.hasInteractiveDescendants(node, nodeMap)) {
+                        this.renderChildrenDownsampled(node, nodeMap, indentLevel, filter, lines, level, visualMap);
+                    }
+                    return;
+                }
+                let line = this.formatLine(indent, refNum, role, node, nodeMap);
+                if (visualMap) {
+                    const vi = visualMap.get(node.backendDOMNodeId);
+                    if (vi && vi.bounds.w > 0 && vi.bounds.h > 0) {
+                        line += ` [${vi.bounds.x},${vi.bounds.y} ${vi.bounds.w}x${vi.bounds.h}]`;
+                        if (vi.isClickable)
+                            line += " click";
+                        if (vi.isVisible)
+                            line += " vis";
+                    }
+                    else {
+                        line += " [hidden]";
+                    }
+                }
+                lines.push(line);
+                this.renderChildrenDownsampled(node, nodeMap, indentLevel + 1, filter, lines, level, visualMap);
+            }
+            else if (level === 2) {
+                // Level 2: single-child containers merged (child takes container's level)
+                const children = this.getVisibleChildren(node, nodeMap);
+                if (children.length === 0) {
+                    // H3: Check for interactive descendants before removing
+                    if (this.hasInteractiveDescendants(node, nodeMap)) {
+                        this.renderChildrenDownsampled(node, nodeMap, indentLevel, filter, lines, level, visualMap);
+                    }
+                    return;
+                }
+                if (children.length === 1) {
+                    // Merge: child at container's indent level
+                    this.renderNodeDownsampled(children[0], nodeMap, indentLevel, filter, lines, level, visualMap);
+                    return;
+                }
+                // Multiple children: keep container but render children
+                let line = this.formatLine(indent, refNum, role, node, nodeMap);
+                if (visualMap) {
+                    const vi = visualMap.get(node.backendDOMNodeId);
+                    if (vi && vi.bounds.w > 0 && vi.bounds.h > 0) {
+                        line += ` [${vi.bounds.x},${vi.bounds.y} ${vi.bounds.w}x${vi.bounds.h}]`;
+                        if (vi.isClickable)
+                            line += " click";
+                        if (vi.isVisible)
+                            line += " vis";
+                    }
+                    else {
+                        line += " [hidden]";
+                    }
+                }
+                lines.push(line);
+                this.renderChildrenDownsampled(node, nodeMap, indentLevel + 1, filter, lines, level, visualMap);
+            }
+            else {
+                // Level 3-4: container chains flattened, containers as one-line summary
+                const childCount = this.countDescendantElements(node, nodeMap, filter);
+                if (childCount === 0) {
+                    // H3: Even with 0 filtered descendants, check for interactive ones
+                    if (this.hasInteractiveDescendants(node, nodeMap)) {
+                        this.renderChildrenDownsampled(node, nodeMap, indentLevel, filter, lines, level, visualMap);
+                    }
+                    return;
+                }
+                const name = node.name?.value ?? "";
+                const shortRole = this.shortContainerRole(role);
+                const nameStr = name ? `: ${name}` : "";
+                lines.push(`${indent}[${shortRole}${nameStr}, ${childCount} items]`);
+                // Children rendered at indentLevel + 1
+                this.renderChildrenDownsampled(node, nodeMap, indentLevel + 1, filter, lines, level, visualMap);
+            }
+        }
+    }
+    renderChildrenDownsampled(node, nodeMap, indentLevel, filter, lines, level, visualMap) {
+        if (!node.childIds)
+            return;
+        for (const childId of node.childIds) {
+            const child = nodeMap.get(childId);
+            if (child) {
+                this.renderNodeDownsampled(child, nodeMap, indentLevel, filter, lines, level, visualMap);
+            }
+        }
+    }
+    countVisibleChildren(node, nodeMap) {
+        if (!node.childIds)
+            return 0;
+        let count = 0;
+        for (const childId of node.childIds) {
+            const child = nodeMap.get(childId);
+            if (child && !child.ignored)
+                count++;
+        }
+        return count;
+    }
+    getVisibleChildren(node, nodeMap) {
+        if (!node.childIds)
+            return [];
+        const children = [];
+        for (const childId of node.childIds) {
+            const child = nodeMap.get(childId);
+            if (child && !child.ignored)
+                children.push(child);
+        }
+        return children;
+    }
+    countDescendantElements(node, nodeMap, filter) {
+        if (!node.childIds)
+            return 0;
+        let count = 0;
+        for (const childId of node.childIds) {
+            const child = nodeMap.get(childId);
+            if (!child || child.ignored)
+                continue;
+            const role = this.getRole(child);
+            if (this.passesFilter(child, role, filter))
+                count++;
+            count += this.countDescendantElements(child, nodeMap, filter);
+        }
+        return count;
+    }
+    /** H3: Check if a node has any interactive descendants (recursive) */
+    hasInteractiveDescendants(node, nodeMap) {
+        if (!node.childIds)
+            return false;
+        for (const childId of node.childIds) {
+            const child = nodeMap.get(childId);
+            if (!child)
+                continue;
+            const role = this.getRole(child);
+            if (INTERACTIVE_ROLES.has(role) && !child.ignored)
+                return true;
+            if (this.hasInteractiveDescendants(child, nodeMap))
+                return true;
+        }
+        return false;
+    }
+    shortContainerRole(role) {
+        const shortcuts = {
+            navigation: "nav",
+            complementary: "aside",
+            contentinfo: "footer",
+            banner: "header",
+            generic: "div",
+            group: "group",
+            region: "region",
+            form: "form",
+            search: "search",
+            toolbar: "toolbar",
+            tablist: "tabs",
+            menu: "menu",
+            menubar: "menubar",
+            list: "list",
+            listbox: "listbox",
+            tree: "tree",
+            grid: "grid",
+            table: "table",
+            main: "main",
+            rowgroup: "rowgroup",
+            row: "row",
+            treegrid: "treegrid",
+        };
+        return shortcuts[role] ?? role;
+    }
+    formatDownsampledHeader(title, count, filter, depth, originalTokens, level) {
+        const titlePart = title ? `Page: ${title}` : "Page";
+        return `${titlePart} — ${count} ${filter} elements (depth ${depth}, downsampled L${level} from ~${originalTokens} tokens)`;
+    }
+    getSubtree(ref, nodeMap, nodes, filter, depth, visualMap, visualDataFailed = false, maxTokens) {
+        const backendId = this.resolveRef(ref);
+        if (backendId === undefined) {
+            const availableRefs = this.getAvailableRefsRange();
+            const suggestion = this.suggestClosestRef(ref);
+            let errorText = `Element ${ref} not found.`;
+            if (availableRefs)
+                errorText += ` Available refs: ${availableRefs}.`;
+            if (suggestion)
+                errorText += ` Did you mean ${suggestion}?`;
+            throw new RefNotFoundError(errorText);
+        }
+        // Find the AXNode with this backendDOMNodeId
+        const targetNode = nodes.find((n) => n.backendDOMNodeId === backendId);
+        if (!targetNode) {
+            throw new RefNotFoundError(`Element ${ref} not found in current tree.`);
+        }
+        const lines = [];
+        this.renderNode(targetNode, nodeMap, 0, filter, lines, visualMap);
+        const refCount = lines.length;
+        const header = `Subtree for ${ref} — ${refCount} elements`;
+        const text = header + "\n\n" + lines.join("\n");
+        // H2: Apply downsampling when max_tokens is set and subtree exceeds budget
+        if (maxTokens) {
+            const currentTokens = estimateTokens(text);
+            if (currentTokens > maxTokens) {
+                // Downsample the subtree using the same pipeline
+                const downsampled = this.downsampleSubtree(targetNode, nodeMap, filter, maxTokens, visualMap);
+                const dsHeader = `Subtree for ${ref} — ${downsampled.refCount} elements (downsampled L${downsampled.level} from ~${currentTokens} tokens)`;
+                // C2: Final budget check on subtree too
+                let dsBody = downsampled.lines.join("\n");
+                const fullText = dsHeader + (dsBody ? "\n\n" + dsBody : "");
+                if (estimateTokens(fullText) > maxTokens && dsBody) {
+                    const headerTokens = estimateTokens(dsHeader + "\n\n");
+                    const bodyBudget = maxTokens - headerTokens;
+                    const trimmed = this.trimBodyToFit(downsampled.lines, bodyBudget);
+                    dsBody = trimmed.join("\n");
+                }
+                const dsText = dsHeader + (dsBody ? "\n\n" + dsBody : "");
+                return {
+                    text: dsText,
+                    refCount: downsampled.refCount,
+                    depth,
+                    tokenCount: estimateTokens(dsText),
+                    pageUrl: this.lastUrl,
+                    downsampled: true,
+                    originalTokens: currentTokens,
+                    downsampleLevel: downsampled.level,
+                    ...(filter === "visual" ? { hasVisualData: !visualDataFailed } : {}),
+                };
+            }
+        }
+        return {
+            text,
+            refCount,
+            depth,
+            tokenCount: estimateTokens(text),
+            pageUrl: this.lastUrl,
+            ...(filter === "visual" ? { hasVisualData: !visualDataFailed } : {}),
+        };
+    }
+    /** H2: Downsample a subtree (same algorithm as downsampleTree but for a single root) */
+    downsampleSubtree(root, nodeMap, filter, maxTokens, visualMap) {
+        for (let level = 0; level <= 4; level++) {
+            const lines = [];
+            this.renderNodeDownsampled(root, nodeMap, 0, filter, lines, level, visualMap);
+            const refCount = lines.filter((l) => !l.startsWith("--- ")).length;
+            const estimatedTotal = estimateTokens(lines.join("\n")) + 15;
+            if (estimatedTotal <= maxTokens) {
+                return { lines, refCount, level };
+            }
+        }
+        // Level 4 still too large — truncate as last resort
+        const lines = [];
+        this.renderNodeDownsampled(root, nodeMap, 0, filter, lines, 4, visualMap);
+        return this.truncateToFit(lines, maxTokens);
+    }
+    /** BUG-001: Find the nearest heading sibling before this node in parent's children */
+    findSectionHeading(node, nodeMap) {
+        if (!node.parentId)
+            return null;
+        const parent = nodeMap.get(node.parentId);
+        if (!parent?.childIds)
+            return null;
+        const myIdx = parent.childIds.indexOf(node.nodeId);
+        for (let i = myIdx - 1; i >= 0; i--) {
+            const sibling = nodeMap.get(parent.childIds[i]);
+            if (!sibling)
+                continue;
+            const siblingRole = this.getRole(sibling);
+            if (siblingRole === "heading") {
+                const name = sibling.name?.value;
+                if (name)
+                    return name;
+            }
+        }
+        return null;
+    }
+    renderNode(node, nodeMap, indentLevel, filter, lines, visualMap) {
+        if (node.ignored) {
+            // Ignored nodes: skip but process children at same indent level
+            this.renderChildren(node, nodeMap, indentLevel, filter, lines, visualMap);
+            return;
+        }
+        const role = this.getRole(node);
+        const passesFilter = this.passesFilter(node, role, filter);
+        // Ticket-1 global aggregation: suppressed members produce no line AND
+        // no recursion — they are guaranteed leaves by prepareAggregateGroups.
+        if (node.backendDOMNodeId !== undefined &&
+            this._aggregateSuppressed?.has(node.backendDOMNodeId)) {
+            return;
+        }
+        // Anchor members emit the collapse summary at their position instead of
+        // the normal formatLine output, then return (leaves have no children
+        // worth rendering).
+        if (node.backendDOMNodeId !== undefined) {
+            const anchor = this._aggregateAnchors?.get(node.backendDOMNodeId);
+            if (anchor) {
+                this.emitAggregateLine(anchor, indentLevel, lines);
+                return;
+            }
+        }
+        if (passesFilter && node.backendDOMNodeId !== undefined) {
+            const refNum = this.refMap.get(node.backendDOMNodeId);
+            if (refNum !== undefined) {
+                const indent = "  ".repeat(indentLevel);
+                let line = this.formatLine(indent, refNum, role, node, nodeMap);
+                // Append visual info if visualMap is provided
+                if (visualMap) {
+                    const vi = visualMap.get(node.backendDOMNodeId);
+                    if (vi && vi.bounds.w > 0 && vi.bounds.h > 0) {
+                        line += ` [${vi.bounds.x},${vi.bounds.y} ${vi.bounds.w}x${vi.bounds.h}]`;
+                        if (vi.isClickable)
+                            line += " click";
+                        if (vi.isVisible)
+                            line += " vis";
+                    }
+                    else {
+                        line += " [hidden]";
+                    }
+                }
+                lines.push(line);
+            }
+        }
+        // Always render children (even if this node didn't pass filter)
+        const nextIndent = passesFilter ? indentLevel + 1 : indentLevel;
+        this.renderChildren(node, nodeMap, nextIndent, filter, lines, visualMap);
+    }
+    /**
+     * Ticket-1 / Token-Aggregation: minimum number of same-class leaf elements
+     * inside the rendered subtree before they are collapsed into one summary
+     * line at the first occurrence. Set to 10 so we never aggregate small or
+     * medium lists (button bars, nav menus, dialog actions) but reliably catch
+     * large generated lists like the 240-button benchmark page, even when they
+     * are interleaved with headings/paragraphs/links.
+     */
+    static AGGREGATE_MIN_COUNT = 10;
+    /**
+     * Ticket-1: Per-render state built by {@link prepareAggregateGroups}. Keys
+     * the first backendDOMNodeId of a ≥10-member aggregation bucket to the
+     * info needed to emit the summary line. Null when no aggregation pass has
+     * been executed (e.g. during subtree renders or tests that bypass getTree).
+     */
+    _aggregateAnchors = null;
+    /**
+     * Ticket-1: All non-first member backendDOMNodeIds for ≥10-member buckets.
+     * renderNode skips any node whose backendDOMNodeId is in this set — the
+     * line they would have produced is already covered by the anchor's
+     * summary line.
+     */
+    _aggregateSuppressed = null;
+    /**
+     * Ticket-1: Build a stable aggregation key for a leaf element. Two
+     * sibling leaves share an aggregation class iff their keys are equal:
+     *
+     *   - Identical role.
+     *   - Either an identical name (e.g. 50× "Submit") OR an identical
+     *     name prefix once a trailing run of digits is stripped
+     *     (e.g. "Action 1" / "Action 240" → key "button::Action ").
+     *
+     * Returns null when the element shouldn't participate in aggregation
+     * (no role at all). Empty/missing names are treated as their own key
+     * so unnamed buttons within a row still group together.
+     */
+    aggregationKey(role, name) {
+        if (!role)
+            return null;
+        if (!name)
+            return `${role}::`;
+        const m = name.match(/^(.+?)(\d+)$/);
+        if (m)
+            return `${role}::${m[1]}`;
+        return `${role}::${name}`;
+    }
+    /**
+     * Ticket-1: A child is a "renderable leaf" for aggregation purposes if
+     * it would emit exactly one line under the current filter and carries
+     * no descendants that would also render. We only need to look one level
+     * deep — text wrappers like <span> / <strong> inside a <button> are
+     * either ignored or non-interactive and never produce their own line.
+     */
+    isRenderableLeaf(node, nodeMap, filter) {
+        if (node.ignored)
+            return false;
+        if (node.backendDOMNodeId === undefined)
+            return false;
+        if (this.refMap.get(node.backendDOMNodeId) === undefined)
+            return false;
+        const role = this.getRole(node);
+        if (!this.passesFilter(node, role, filter))
+            return false;
+        if (!node.childIds || node.childIds.length === 0)
+            return true;
+        for (const childId of node.childIds) {
+            const child = nodeMap.get(childId);
+            if (!child || child.ignored)
+                continue;
+            if (child.backendDOMNodeId === undefined)
+                continue;
+            const childRole = this.getRole(child);
+            if (this.passesFilter(child, childRole, filter)) {
+                // The child would render its own line → parent is not a leaf.
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Ticket-1: Walk the renderable subtree (main + OOPIFs) and compute which
+     * leaves should be collapsed into summary lines. Leaves are bucketed by
+     * aggregation key; any bucket with ≥{@link AGGREGATE_MIN_COUNT} members
+     * becomes a collapse group. The first member in DOM order becomes the
+     * "anchor" (its position emits the summary line) and the rest land in
+     * the suppressed set so renderNode skips them.
+     *
+     * This runs independently of the ≥10-consecutive-siblings assumption,
+     * which is why it catches the T4.7 benchmark case where 120 "Action N"
+     * buttons are interleaved with headings, paragraphs, and inputs inside
+     * 60 sections that share a single DOM parent.
+     */
+    prepareAggregateGroups(root, nodeMap, oopifSections, filter) {
+        const buckets = new Map();
+        const walk = (node, map) => {
+            if (!node.ignored &&
+                node.backendDOMNodeId !== undefined &&
+                this.isRenderableLeaf(node, map, filter)) {
+                const role = this.getRole(node);
+                const name = node.name?.value ?? "";
+                const key = this.aggregationKey(role, name);
+                if (key !== null) {
+                    let bucket = buckets.get(key);
+                    if (!bucket) {
+                        bucket = [];
+                        buckets.set(key, bucket);
+                    }
+                    bucket.push(node);
+                    // Leaves by definition have no renderable descendants — skip recursion.
+                    return;
+                }
+            }
+            if (node.childIds) {
+                for (const childId of node.childIds) {
+                    const child = map.get(childId);
+                    if (child)
+                        walk(child, map);
+                }
+            }
+        };
+        walk(root, nodeMap);
+        for (const section of oopifSections) {
+            const oopifMap = new Map();
+            for (const n of section.nodes)
+                oopifMap.set(n.nodeId, n);
+            if (section.nodes.length > 0)
+                walk(section.nodes[0], oopifMap);
+        }
+        this._aggregateAnchors = new Map();
+        this._aggregateSuppressed = new Set();
+        for (const bucket of buckets.values()) {
+            if (bucket.length < A11yTreeProcessor.AGGREGATE_MIN_COUNT)
+                continue;
+            const first = bucket[0];
+            const last = bucket[bucket.length - 1];
+            const firstId = first.backendDOMNodeId;
+            const firstRef = this.refMap.get(firstId);
+            const lastRef = this.refMap.get(last.backendDOMNodeId);
+            if (firstRef === undefined || lastRef === undefined)
+                continue;
+            this._aggregateAnchors.set(firstId, {
+                count: bucket.length,
+                role: this.getRole(first),
+                firstName: first.name?.value ?? "",
+                lastName: last.name?.value ?? "",
+                firstRef,
+                lastRef,
+            });
+            for (let i = 1; i < bucket.length; i++) {
+                this._aggregateSuppressed.add(bucket[i].backendDOMNodeId);
+            }
+        }
+    }
+    /** Reset the per-render aggregation state set up by prepareAggregateGroups. */
+    clearAggregateGroups() {
+        this._aggregateAnchors = null;
+        this._aggregateSuppressed = null;
+    }
+    /**
+     * Ticket-1: Emit the summary line for a collapse-group anchor. Format is
+     * intentionally compact and still carries the addressable ref band so the
+     * LLM can click({ ref: "eN" }) on any individual element inside it.
+     */
+    emitAggregateLine(anchor, indentLevel, lines) {
+        const indent = "  ".repeat(indentLevel);
+        let line = `${indent}[e${anchor.firstRef}..e${anchor.lastRef}] ${anchor.count}× ${anchor.role}`;
+        if (anchor.firstName && anchor.lastName && anchor.firstName !== anchor.lastName) {
+            line += ` "${anchor.firstName}" .. "${anchor.lastName}"`;
+        }
+        else if (anchor.firstName) {
+            line += ` "${anchor.firstName}"`;
+        }
+        lines.push(line);
+    }
+    renderChildren(node, nodeMap, indentLevel, filter, lines, visualMap) {
+        if (!node.childIds)
+            return;
+        for (const childId of node.childIds) {
+            const child = nodeMap.get(childId);
+            if (child) {
+                this.renderNode(child, nodeMap, indentLevel, filter, lines, visualMap);
+            }
+        }
+    }
+    /** FR-022: Count content nodes with visible text that would be hidden by filter:interactive.
+     *  Used to append a hint in read-page.ts that points the LLM at filter:'all' instead of evaluate. */
+    countHiddenContentNodes(root, nodeMap, oopifSections) {
+        let count = 0;
+        const walk = (node, map) => {
+            if (node.ignored) {
+                // Still walk ignored children — they may wrap visible content
+            }
+            else {
+                const role = node.role?.value ?? "";
+                if (CONTENT_ROLES.has(role)) {
+                    const name = node.name?.value ?? "";
+                    // Only count nodes with actual visible text content
+                    if (name && name.trim().length > 0) {
+                        count++;
+                    }
+                }
+            }
+            if (node.childIds) {
+                for (const childId of node.childIds) {
+                    const child = map.get(childId);
+                    if (child)
+                        walk(child, map);
+                }
+            }
+        };
+        walk(root, nodeMap);
+        for (const section of oopifSections) {
+            const oopifNodeMap = new Map();
+            for (const n of section.nodes)
+                oopifNodeMap.set(n.nodeId, n);
+            if (section.nodes.length > 0)
+                walk(section.nodes[0], oopifNodeMap);
+        }
+        return count;
+    }
+    getRole(node) {
+        return node.role?.value ?? "";
+    }
+    passesFilter(node, role, filter) {
+        if (filter === "all")
+            return true;
+        if (filter === "landmark")
+            return LANDMARK_ROLES.has(role);
+        // interactive and visual filters use the same element selection
+        if (INTERACTIVE_ROLES.has(role))
+            return true;
+        // FR-005: Elements with onclick handlers (e.g. sortable table headers)
+        if (node.backendDOMNodeId !== undefined) {
+            const info = this.nodeInfoMap.get(node.backendDOMNodeId);
+            if (info?.isClickable)
+                return true;
+        }
+        // Check focusable property
+        if (node.properties) {
+            for (const prop of node.properties) {
+                if (prop.name === "focusable" && prop.value.value === true)
+                    return true;
+            }
+        }
+        return false;
+    }
+    formatLine(indent, refNum, role, node, nodeMap) {
+        // FR-004: Append HTML id if available
+        const backendNodeId = node.backendDOMNodeId;
+        const htmlId = backendNodeId !== undefined ? this.nodeInfoMap.get(backendNodeId)?.htmlId : undefined;
+        const idSuffix = htmlId ? `#${htmlId}` : "";
+        let line = `${indent}[e${refNum}] ${role}${idSuffix}`;
+        // FR-H5: Prefer AXNode name, fall back to nodeInfoMap (enriched by Phase 3 for clickable generics)
+        const name = node.name?.value
+            || (backendNodeId !== undefined ? this.nodeInfoMap.get(backendNodeId)?.name : undefined);
+        if (name) {
+            line += ` "${name}"`;
+            // FR-021: Signal truncation so the LLM knows hidden text exists (reached for evaluate otherwise)
+            if (backendNodeId !== undefined) {
+                const fullLen = this.nodeInfoMap.get(backendNodeId)?.nameFullLength;
+                if (fullLen && fullLen > name.length) {
+                    const extra = fullLen - name.length;
+                    line += ` …[+${extra} chars; use filter:"all" with ref to read subtree]`;
+                }
+            }
+        }
+        const value = node.value?.value;
+        if (value !== undefined && value !== "") {
+            line += ` value="${value}"`;
+        }
+        // BUG-001: Annotate tables with nearest heading for disambiguation
+        if (role === "table" && nodeMap) {
+            const sectionHeading = this.findSectionHeading(node, nodeMap);
+            if (sectionHeading) {
+                line += ` (section: "${sectionHeading}")`;
+            }
+        }
+        // FR-003: iframe content hint
+        if (role === "Iframe") {
+            line += " (use evaluate to access iframe content)";
+        }
+        // FR-008: Canvas is opaque — direct LLM to use screenshot(som: true)
+        if (role === "canvas" || role === "Canvas") {
+            line += " ⚠ Canvas content is pixels, not DOM. Use screenshot(som: true) to see what's inside.";
+        }
+        // URL for links — shorten to path to save tokens
+        if (role === "link" && node.properties) {
+            for (const prop of node.properties) {
+                if (prop.name === "url" && prop.value.value) {
+                    line += ` → ${shortenUrl(String(prop.value.value))}`;
+                    break;
+                }
+            }
+            // FR-002: target=_blank annotation
+            if (backendNodeId !== undefined) {
+                const linkInfo = this.nodeInfoMap.get(backendNodeId);
+                if (linkInfo?.linkTarget === "_blank") {
+                    line += " (opens new tab)";
+                }
+            }
+        }
+        // Disabled marker
+        if (node.properties) {
+            for (const prop of node.properties) {
+                if (prop.name === "disabled" && prop.value.value === true) {
+                    line += " (disabled)";
+                    break;
+                }
+            }
+        }
+        // FR-H6: Tab selected state — helps LLM understand which tab panel is visible
+        if (role === "tab" && node.properties) {
+            for (const prop of node.properties) {
+                if (prop.name === "selected" && prop.value.value === true) {
+                    line += " (selected)";
+                    break;
+                }
+            }
+        }
+        // FR-006: contenteditable annotation
+        if (node.properties) {
+            for (const prop of node.properties) {
+                if (prop.name === "editable" && prop.value.value && prop.value.value !== "inherit") {
+                    line += " (editable)";
+                    break;
+                }
+            }
+        }
+        // FR-001: scrollable container annotation
+        if (backendNodeId !== undefined) {
+            const scrollInfo = this.nodeInfoMap.get(backendNodeId);
+            if (scrollInfo?.isScrollable) {
+                line += " (scrollable)";
+            }
+        }
+        return line;
+    }
+    formatHeader(title, count, filter, depth) {
+        const titlePart = title ? `Page: ${title}` : "Page";
+        return `${titlePart} — ${count} ${filter} elements (depth ${depth})`;
+    }
+    getPageTitle(nodes) {
+        // Root node (WebArea) usually has the page title as name
+        if (nodes.length > 0) {
+            const root = nodes[0];
+            if (!root.ignored) {
+                const name = root.name?.value;
+                if (name)
+                    return name;
+            }
+        }
+        return "";
+    }
+    getAvailableRefsRange() {
+        if (this.reverseMap.size === 0)
+            return null;
+        const refs = [...this.reverseMap.keys()].sort((a, b) => a - b);
+        return `e${refs[0]}-e${refs[refs.length - 1]}`;
+    }
+    suggestClosestRef(ref) {
+        const match = ref.match(/^e(\d+)$/);
+        if (!match || this.reverseMap.size === 0)
+            return null;
+        const requested = parseInt(match[1], 10);
+        const refs = [...this.reverseMap.keys()].sort((a, b) => a - b);
+        let closest = refs[0];
+        let minDist = Math.abs(requested - closest);
+        for (const r of refs) {
+            const dist = Math.abs(requested - r);
+            if (dist < minDist) {
+                closest = r;
+                minDist = dist;
+            }
+        }
+        return `e${closest}`;
+    }
+    /**
+     * Story 13a.2: Classify a ref for pre-click ambient context decision.
+     * Returns classification based on cached AXNode properties (0 CDP calls).
+     */
+    classifyRef(ref) {
+        const match = ref.match(/^e?(\d+)$/);
+        if (!match)
+            return "static";
+        const refNum = parseInt(match[1], 10);
+        const backendNodeId = this.reverseMap.get(refNum);
+        if (backendNodeId === undefined)
+            return "static";
+        const info = this.nodeInfoMap.get(backendNodeId);
+        if (!info)
+            return "static";
+        if (info.disabled)
+            return "disabled";
+        // hasPopup can be "false" (string) — only classify as widget-state for truthy popup types
+        if (info.expanded !== undefined
+            || (info.hasPopup !== undefined && info.hasPopup !== "false")
+            || info.checked !== undefined
+            || info.pressed !== undefined)
+            return "widget-state";
+        if (INTERACTIVE_ROLES.has(info.role) || info.isClickable)
+            return "clickable";
+        return "static";
+    }
+    /**
+     * FR-008: Return a compact list of known interactive elements for error hints.
+     * Used when a CSS selector fails to provide the LLM with actionable alternatives.
+     * ZERO CDP calls — purely in-memory from cached nodeInfoMap.
+     */
+    getInteractiveElements(limit = 8) {
+        if (this.reverseMap.size === 0)
+            return [];
+        const lines = [];
+        const sortedRefs = [...this.reverseMap.entries()].sort((a, b) => a[0] - b[0]);
+        for (const [refNum, backendNodeId] of sortedRefs) {
+            const info = this.nodeInfoMap.get(backendNodeId);
+            if (!info || !(INTERACTIVE_ROLES.has(info.role) || info.isClickable))
+                continue;
+            const name = info.name ? ` '${info.name}'` : "";
+            const idSuffix = info.htmlId ? `#${info.htmlId}` : "";
+            lines.push(`[e${refNum}] ${info.role}${idSuffix}${name}`);
+            if (lines.length >= limit)
+                break;
+        }
+        return lines;
+    }
+    /**
+     * FR-002: Lightweight snapshot map for DOM-Diff.
+     * Returns Map<refNum, "role\0name"> for all nodes with a name.
+     * ZERO CDP calls — purely in-memory.
+     */
+    getSnapshotMap() {
+        const map = new Map();
+        for (const [refNum, backendNodeId] of this.reverseMap) {
+            const info = this.nodeInfoMap.get(backendNodeId);
+            if (!info || (!info.name && !CONTEXT_ROLES.has(info.role) && !INTERACTIVE_ROLES.has(info.role) && !info.isClickable))
+                continue;
+            map.set(refNum, `${info.role}\0${info.name ?? ""}`);
+        }
+        return map;
+    }
+    /**
+     * FR-002: Compute diff between two snapshot maps.
+     * Returns only meaningful changes (role+name), ignoring nodes without names.
+     */
+    static diffSnapshots(before, after) {
+        const changes = [];
+        // Changed or removed
+        for (const [refNum, beforeVal] of before) {
+            const afterVal = after.get(refNum);
+            if (afterVal === undefined) {
+                // Node removed
+                const [role, name] = beforeVal.split("\0");
+                if (name) { // Only report if it had visible content
+                    changes.push({ type: "removed", ref: `e${refNum}`, role, after: "", before: name });
+                }
+            }
+            else if (afterVal !== beforeVal) {
+                // Node changed
+                const [roleBefore, nameBefore] = beforeVal.split("\0");
+                const [roleAfter, nameAfter] = afterVal.split("\0");
+                // Only report if the *name* (visible text) actually changed
+                if (nameBefore !== nameAfter) {
+                    changes.push({
+                        type: "changed",
+                        ref: `e${refNum}`,
+                        role: roleAfter || roleBefore,
+                        before: nameBefore,
+                        after: nameAfter,
+                    });
+                }
+            }
+        }
+        // Added
+        for (const [refNum, afterVal] of after) {
+            if (!before.has(refNum)) {
+                const [role, name] = afterVal.split("\0");
+                if (name) { // Only report if it has visible content
+                    changes.push({ type: "added", ref: `e${refNum}`, role, after: name });
+                }
+            }
+        }
+        return changes;
+    }
+    /**
+     * FR-002: Format DOM changes as compact context string for LLM.
+     * Prioritizes alerts/status, then shows changes near the action, caps at ~30 lines.
+     */
+    static formatDomDiff(changes, url) {
+        if (changes.length === 0)
+            return null;
+        // Sort: alerts/status first, then added, then changed, then removed
+        const priority = (c) => {
+            if (c.role === "alert" || c.role === "status")
+                return 0;
+            if (c.type === "added")
+                return 1;
+            if (c.type === "changed")
+                return 2;
+            return 3;
+        };
+        changes.sort((a, b) => priority(a) - priority(b));
+        const lines = [];
+        const urlSuffix = url ? ` — ${shortenUrl(url)}` : "";
+        lines.push(`--- Action Result (${changes.length} changes)${urlSuffix} ---`);
+        const maxLines = 30;
+        for (const c of changes.slice(0, maxLines)) {
+            const refTag = INTERACTIVE_ROLES.has(c.role) || CONTEXT_ROLES.has(c.role)
+                ? `[${c.ref}] ` : "";
+            if (c.type === "added") {
+                const roleLabel = c.role === "alert" || c.role === "status" ? c.role : c.role;
+                lines.push(` NEW    ${refTag}${roleLabel} "${c.after}"`);
+            }
+            else if (c.type === "changed") {
+                lines.push(` CHANGED ${refTag}${c.role} "${c.before}" → "${c.after}"`);
+            }
+            else {
+                lines.push(` REMOVED ${refTag}${c.role} "${c.before}"`);
+            }
+        }
+        if (changes.length > maxLines) {
+            lines.push(`... (${changes.length - maxLines} more changes)`);
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Story 13a.2: Enriched compact snapshot with headings, alerts, status
+     * plus interactive elements. ZERO CDP calls — purely in-memory.
+     */
+    getCompactSnapshot(maxTokens = 2000) {
+        if (this.reverseMap.size === 0)
+            return null;
+        const contextLines = [];
+        const interactiveLines = [];
+        let tokensSoFar = 0;
+        const sortedRefs = [...this.reverseMap.entries()].sort((a, b) => a[0] - b[0]);
+        for (const [refNum, backendNodeId] of sortedRefs) {
+            const info = this.nodeInfoMap.get(backendNodeId);
+            if (!info)
+                continue;
+            let line = null;
+            // Story 13a.2: Context roles (headings, alerts, status) for orientation
+            if (CONTEXT_ROLES.has(info.role)) {
+                if (info.role === "heading" && info.name) {
+                    const lvl = info.level ?? 1;
+                    line = `[h${lvl}] "${info.name}"`;
+                }
+                else if ((info.role === "alert" || info.role === "status") && info.name) {
+                    line = `[${info.role}] "${info.name}"`;
+                }
+                if (line) {
+                    const lineTokens = Math.ceil(line.length / 4);
+                    if (tokensSoFar + lineTokens <= maxTokens) {
+                        contextLines.push(line);
+                        tokensSoFar += lineTokens;
+                    }
+                }
+                continue;
+            }
+            // Interactive elements (existing behavior) + FR-005: onclick-clickable elements
+            if (!INTERACTIVE_ROLES.has(info.role) && !info.isClickable)
+                continue;
+            const name = info.name ? ` '${info.name}'` : "";
+            const idSuffix = info.htmlId ? `#${info.htmlId}` : "";
+            line = `[e${refNum}] ${info.role}${idSuffix}${name}`;
+            const lineTokens = Math.ceil(line.length / 4);
+            if (tokensSoFar + lineTokens > maxTokens) {
+                const remaining = sortedRefs.filter(([, id]) => INTERACTIVE_ROLES.has(this.nodeInfoMap.get(id)?.role ?? "")).length - interactiveLines.length;
+                interactiveLines.push(`... (${remaining} more)`);
+                break;
+            }
+            interactiveLines.push(line);
+            tokensSoFar += lineTokens;
+        }
+        if (contextLines.length === 0 && interactiveLines.length === 0)
+            return null;
+        const url = this.lastUrl ? ` — ${shortenUrl(this.lastUrl)}` : "";
+        const parts = [];
+        const counts = interactiveLines.length > 0 ? `${interactiveLines.length} interactive` : `${contextLines.length} context`;
+        parts.push(`--- Page Context (${counts})${url} ---`);
+        if (contextLines.length > 0)
+            parts.push(...contextLines);
+        if (interactiveLines.length > 0)
+            parts.push(...interactiveLines);
+        return parts.join("\n");
+    }
+}
+function shortenUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.pathname + parsed.search + parsed.hash;
+    }
+    catch {
+        return url;
+    }
+}
+export class RefNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RefNotFoundError";
+    }
+}
+export const a11yTree = new A11yTreeProcessor();