@silbercue/chrome 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Silbercue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# SilbercueChrome
+
+[![GitHub Release](https://img.shields.io/github/v/release/Silbercue/silbercuechrome)](https://github.com/Silbercue/silbercuechrome/releases)
+[![npm version](https://img.shields.io/npm/v/@silbercue%2Fchrome)](https://www.npmjs.com/package/@silbercue/chrome)
+[![Free — 18 tools](https://img.shields.io/badge/Free-18_tools-brightgreen)](https://github.com/Silbercue/silbercuechrome#free-vs-pro)
+[![Pro — 21+ tools](https://img.shields.io/badge/Pro-21%2B_tools-blueviolet)](https://polar.sh/silbercuechrome)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+
+The fastest, most token-efficient MCP server for Chrome browser automation. Direct CDP, a11y-tree refs, multi-tab ready. **24/24 on the hardest benchmark at 20s scripted, beating Playwright MCP and claude-in-chrome.**
+
+Built for [Claude Code](https://claude.ai/claude-code), [Cursor](https://cursor.sh), and any MCP-compatible client.
+
+> **Looking for an alternative to Playwright MCP, Browser MCP, or claude-in-chrome?** SilbercueChrome talks to Chrome directly via the DevTools Protocol — no Playwright dependency, no Chrome extension bridge, no single-tab limit. One command to install, zero config, and the best benchmark score in the category. [See comparison below](#benchmarks).
+
+## Why SilbercueChrome?
+
+Every Chrome MCP server has the same problem: **too many tokens, too few reliable refs.** Screenshots eat 10-30x more tokens than text trees. Selector-based refs break the second the DOM rerenders. Extension bridges (Browser MCP) get stuck on the connected tab. Playwright wrappers spin up a new browser instance for every session.
+
+SilbercueChrome fixes this. It talks directly to Chrome via CDP (same protocol Playwright and Puppeteer use internally), returns an accessibility-tree-based reference map, and caches it across calls so `click(ref: 'e5')` and `type(ref: 'e7', ...)` survive scrolls and DOM updates.
+
+| What you get | Playwright MCP | Browser MCP | claude-in-chrome | browser-use | **SilbercueChrome** |
+|---|---|---|---|---|---|
+| Hardest benchmark (24 tests, LLM-driven) | 24/24 (~570s) | **cannot finish** | 24/24 (1140s) | 17/24 (~1049s) | **24/24 Pro: 555s · Free: 755-900s** |
+| Scripted benchmark (24 tests) | — | — | — | — | **24/24 in ~20s** |
+| Multi-tab support | Yes | **No (single tab)** | Yes | Partial | **Yes** |
+| Connection | New browser | Extension bridge | Extension | Subprocess | **Direct CDP (pipe or WebSocket)** |
+| Ref system | Playwright refs | Playwright refs | CSS selectors | Screenshots | **A11y-tree refs (stable across DOM changes)** |
+| Read page | Screenshot + DOM | Snapshot | DOM dump | Screenshot-heavy | **`read_page` — 10-30x fewer tokens** |
+| Drag & drop | Yes | No | Partial | No | **Yes (native CDP mouse events)** |
+| Shadow DOM + iframe | Yes | Yes | Partial | No | **Yes (with OOPIF session support)** |
+| Keyboard shortcuts | Yes | Yes | Partial | No | **Yes (`press_key` with real CDP keyboard events)** |
+| localStorage/cookies | Yes | No | Partial | No | **Yes (via `evaluate`)** |
+| Multi-step plan execution | — | — | — | — | **`run_plan` — server-side plan executor with variables, conditions, suspend/resume** |
+| Zero-config install | Yes | Yes | Built-in | Yes | **Yes (one `claude mcp add` line)** |
+
+### Where SilbercueChrome really shines
+
+> ![killer feat](https://img.shields.io/badge/killer%20feat-%23FFD700?style=flat-square) **24/24 on the hardest benchmark in 20 seconds (scripted), 555s LLM-driven** — beats every alternative in the category
+
+The test-hardest suite covers 24 patterns that break most browser MCPs: infinite scroll, Shadow DOM, nested iframes, drag & drop, canvas clicks, keyboard shortcuts, contenteditable, async timing races, 10K-element DOMs, localStorage chains, mutation observers, modal form chains. SilbercueChrome Pro clears all 24 in ~555s LLM-driven (scripted: ~21s). Free tier runs 20s scripted / 755-900s LLM. Playwright MCP takes ~570s LLM. claude-in-chrome takes 1140s. browser-use fails 7 tests architecturally.
+
+> ![killer feat](https://img.shields.io/badge/killer%20feat-%23FFD700?style=flat-square) **`read_page` with a11y-tree refs — 10-30x cheaper than screenshots**
+
+Instead of pushing an 800KB screenshot every turn, `read_page` returns the accessibility tree with stable `e5`-style refs. Agents read text, find elements, and chain `click(ref: 'e5')` / `type(ref: 'e7', ...)` — all in 30KB responses. Screenshots stay available for visual verification via `screenshot`, but the LLM stops defaulting to them for element discovery.
+
+> ![killer feat](https://img.shields.io/badge/killer%20feat-%23FFD700?style=flat-square) **True multi-tab — `virtual_desk`, `switch_tab`, parallel tabs in `run_plan`** <img src="https://img.shields.io/badge/Pro-blueviolet?style=flat-square" align="center">
+
+Browser MCP binds to a single "connected" tab via its Chrome extension — cross-tab operations are architecturally impossible. SilbercueChrome uses CDP `Target` API to enumerate, open, close, and switch between tabs. `virtual_desk` lists every open tab with stable IDs. `switch_tab` moves between them without touching the user's active tab. `run_plan` even supports parallel tab execution.
+
+> ![strong](https://img.shields.io/badge/strong-%23C0C0C0?style=flat-square) **`fill_form` — one call for a complete form**
+
+Other MCPs make you emit N `type` calls for an N-field form. `fill_form` takes a single `fields[]` array with refs and values, handles text inputs, `<select>` (by value or label), checkboxes, and radios in one CDP round-trip, and reports per-field status.
+
+> ![strong](https://img.shields.io/badge/strong-%23C0C0C0?style=flat-square) **`observe` — watch DOM changes without writing JavaScript**
+
+Two modes: `collect` (watch for N ms, return every text/attribute change) and `until` (wait for a condition, then auto-click). Use `click_first` to trigger the action that causes changes — the observer is set up *before* the click, so nothing is missed. Replaces the typical `setInterval`/`MutationObserver`/`evaluate` dance.
+
+> ![strong](https://img.shields.io/badge/strong-%23C0C0C0?style=flat-square) **`run_plan` — server-side multi-step automation**
+
+Execute a sequence of tool steps server-side with variables (`$varName`), conditions (`if`), `saveAs`, error strategies (`abort`/`continue`/`screenshot`), and suspend/resume for long-running workflows. Parallel tab execution is a Pro feature.
+
+## Quick Start
+
+### Install in Claude Code
+
+One command — installs globally for all projects:
+
+```bash
+claude mcp add --scope user silbercuechrome npx -y @silbercue/chrome@latest
+```
+
+Restart Claude Code. First tool call auto-launches Chrome **visible** (no headless, no port setup). Done.
+
+### Install in Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "silbercuechrome": {
+      "command": "npx",
+      "args": ["-y", "@silbercue/chrome@latest"]
+    }
+  }
+}
+```
+
+### Install in other MCP clients
+
+Any client that supports stdio MCP servers: `npx -y @silbercue/chrome@latest` with no arguments.
+
+### Uninstall
+
+```bash
+claude mcp remove --scope user silbercuechrome
+```
+
+## Free vs Pro
+
+The Free tier gives you 18 tools covering 24/24 benchmark tests in the scripted runner. Pro adds `virtual_desk`, `switch_tab`, `dom_snapshot`, and advanced `run_plan` features (parallel tabs, operator hooks, ambient context) plus faster internals.
+
+| | Free | Pro |
+|---|---|---|
+| Tools | 18 | 21+ |
+| Page understanding | `read_page` | `read_page` + `dom_snapshot` (spatial queries) |
+| Tab management | `navigate`, `tab_status` | + `virtual_desk`, `switch_tab`, parallel tabs in `run_plan` |
+| Interaction | `click`, `type`, `fill_form`, `press_key`, `scroll`, `file_upload`, `handle_dialog` | Same |
+| Observation | `screenshot`, `wait_for`, `observe`, `console_logs`, `network_monitor` | Same + ambient page context hooks |
+| Scripting | `run_plan` (sequential) | `run_plan` (sequential + parallel + operator hooks) |
+| Last resort | `evaluate` | `evaluate` + anti-pattern scanner hints |
+| Benchmark score | 24/24 | 24/24 |
+| Benchmark time (scripted) | ~20s | ~21s |
+| Benchmark time (LLM-driven) | 755-900s | ~555s |
+
+Pro costs $19 USD one-time. [Get a license on Polar.sh](https://polar.sh/silbercuechrome), then activate via the built-in license command or `SILBERCUECHROME_LICENSE_KEY=SC-PRO-...` env var.
+
+## Tools
+
+### Reading & Observation
+
+| Tool | Description |
+|---|---|
+| `read_page` | Accessibility tree with stable `e`-refs — primary way to understand the page. 10-30x cheaper than screenshots. Filter by `interactive` (default) or `all` (include static text). |
+| `screenshot` | WebP capture, max 800px, <100KB. Use for visual verification only — you cannot use screenshots to drive click/type, refs come from `read_page`. |
+| `console_logs` | Retrieve browser console output with level/pattern filters |
+| `network_monitor` | Start/stop/query network requests with filtering |
+| `observe` | Watch DOM changes: `collect` (buffer changes over time) or `until` (wait for condition, then auto-click) |
+| `wait_for` | Wait for element visible, network idle, or JS expression true |
+| `tab_status` | Active tab's cached URL/title/ready/errors — mid-workflow sanity check |
+
+### Interaction
+
+| Tool | Description |
+|---|---|
+| `click` | Real CDP mouse events (mouseMoved/Pressed/Released). Click by ref, selector, text, or `x`+`y` coordinates. Response includes DOM diff (NEW/REMOVED/CHANGED). |
+| `type` | Type into an input by ref/selector |
+| `fill_form` | Fill a complete form in one call — text, `<select>`, checkbox, radio. Per-field status, partial errors don't abort. |
+| `press_key` | Real CDP keyboard events — Enter, Escape, Tab, arrows, shortcuts (Ctrl+K, etc.) |
+| `scroll` | Scroll page, element into view, or inside a specific container (sidebar, modal body) |
+| `file_upload` | Upload file(s) to an `<input type="file">` |
+| `handle_dialog` | Configure `alert`/`confirm`/`prompt` handling before triggering actions |
+
+### Navigation
+
+| Tool | Description |
+|---|---|
+| `navigate` | Load a URL in the active tab. Waits for settle. First call per session is auto-redirected to `virtual_desk` to prevent blindly overwriting the user's tab. |
+
+### Scripting
+
+| Tool | Description |
+|---|---|
+| `run_plan` | Execute a multi-step plan server-side. Variables (`$varName`), conditions (`if`), `saveAs`, error strategies (`abort`/`continue`/`screenshot`), suspend/resume. Parallel tabs require Pro. |
+| `configure_session` | View/set session defaults (tab, timeout) and accept auto-promote suggestions |
+| `evaluate` | Execute JS in the page context. Use for COMPUTE or side effects no tool covers — not for element discovery (use `read_page` instead). Anti-pattern scanner warns when you reach for `querySelector` or `.click()`. |
+
+### Pro tier (additional)
+
+| Tool | Description |
+|---|---|
+| `virtual_desk` <img src="https://img.shields.io/badge/Pro-blueviolet?style=flat-square" align="center"> | Lists all tabs with stable IDs. Call first in every session. |
+| `switch_tab` <img src="https://img.shields.io/badge/Pro-blueviolet?style=flat-square" align="center"> | Open, switch to, or close tabs by ID from `virtual_desk` |
+| `dom_snapshot` <img src="https://img.shields.io/badge/Pro-blueviolet?style=flat-square" align="center"> | Bounding boxes, computed styles, paint order, colors. For spatial questions `read_page` cannot answer. |
+
+## Benchmarks
+
+Measured on `https://mcp-test.second-truth.com` — 24 tests in 4 levels (Basics, Intermediate, Advanced, Hardest). Each run is independent, values on the benchmark page are randomized per page-load, and all runs started in a fresh Claude Code session out of `/tmp` (no project context bias).
+
+| MCP | Passed | Time (LLM) | Time (scripted) |
+|---|---|---|---|
+| **SilbercueChrome Pro** | **24/24** | **555s** | **21s** |
+| **SilbercueChrome Free** | **24/24** | **755-900s** | **20s** |
+| Playwright MCP | 24/24 | ~570s | — |
+| claude-in-chrome | 24/24 | 1140s | — |
+| browser-use | 17/24 | ~1049s | — |
+| Browser MCP | — | could not complete | — |
+
+browser-use fails 7 tests architecturally: infinite scroll (no container-internal scrolling), drag & drop, canvas click, keyboard shortcuts, contenteditable bold, localStorage+cookie chain, mutation observer. Browser MCP's single-tab extension bridge cannot complete the `Tab switch, read, return` pattern and becomes unstable over longer runs. See [`test-hardest/BENCHMARK-PROTOCOL.md`](test-hardest/BENCHMARK-PROTOCOL.md) for the full protocol and raw JSON runs.
+
+## Architecture
+
+```
+SilbercueChrome (Node.js MCP server, @silbercue/chrome)
+├── @modelcontextprotocol/sdk (stdio transport)
+├── CDP Client
+│   ├── WebSocket transport (existing Chrome on :9222)
+│   └── Pipe transport (auto-launched Chrome with --remote-debugging-pipe)
+├── Auto-Launch: Chrome + optimal flags, visible by default
+├── A11y-tree cache + Selector cache
+├── Session Manager (OOPIF support for iframes and Shadow DOM)
+├── Tab State Cache (URL/title/ready across tabs)
+└── 18 Free-tier tools + 3+ Pro-tier tools
+    Reading · Interaction · Navigation · Scripting · Observation
+```
+
+Connection priority:
+1. **Auto-Launch (default, zero-config)** — starts Chrome as a child process via `--remote-debugging-pipe`, visible as a window, with all flags set for reliable screenshots and keyboard focus.
+2. **WebSocket (optional)** — if you already run Chrome with `--remote-debugging-port=9222`, SilbercueChrome connects to that instead. Use this to control your own browser with its extensions and login sessions.
+
+## Requirements
+
+- Node.js >= 18
+- Google Chrome, Chromium, or any Chromium-based browser (auto-detected on macOS/Linux/Windows; override with `CHROME_PATH`)
+
+## Environment Variables
+
+| Variable | Values | Default | Description |
+|---|---|---|---|
+| `SILBERCUE_CHROME_AUTO_LAUNCH` | `true` / `false` | `true` | Auto-launch Chrome if no running instance found |
+| `SILBERCUE_CHROME_HEADLESS` | `true` / `false` | `false` | Opt-in headless mode for CI/server environments |
+| `SILBERCUE_CHROME_PROFILE` | path | — | Chrome user profile directory (auto-launch only) |
+| `CHROME_PATH` | path | — | Path to Chrome binary (overrides auto-detection) |
+| `SILBERCUECHROME_LICENSE_KEY` | license key | — | Pro license key (e.g. `SC-PRO-...`) |
+
+## License
+
+The core server and all 18 Free-tier tools are **MIT licensed** — see [LICENSE](LICENSE). Use them however you want, commercially or otherwise.
+
+Pro tools (3+ gated tools, parallel tab execution, ambient context, operator hooks, faster internals) require a [paid license](https://polar.sh/silbercuechrome). The license validation code is in the separate private Pro repository.
+
+## Contributing
+
+Issues and pull requests welcome at [github.com/Silbercue/silbercuechrome](https://github.com/Silbercue/silbercuechrome).
+
+## Privacy
+
+SilbercueChrome runs entirely on your machine. All browser automation happens locally via CDP. No telemetry, no remote calls, no data sent to any third party.

package/build/cache/a11y-tree.d.ts

@@ -0,0 +1,252 @@
+import type { CdpClient } from "../cdp/cdp-client.js";
+import type { SessionManager } from "../cdp/session-manager.js";
+interface AXValue {
+    type: string;
+    value: unknown;
+}
+interface AXProperty {
+    name: string;
+    value: AXValue;
+}
+export interface AXNode {
+    nodeId: string;
+    ignored: boolean;
+    role?: AXValue;
+    name?: AXValue;
+    description?: AXValue;
+    value?: AXValue;
+    properties?: AXProperty[];
+    childIds?: string[];
+    parentId?: string;
+    backendDOMNodeId?: number;
+    frameId?: string;
+}
+export interface TreeOptions {
+    depth?: number;
+    ref?: string;
+    filter?: "interactive" | "all" | "landmark" | "visual";
+    max_tokens?: number;
+    /** Bypass precomputed cache and fetch fresh data from CDP (fixes stale data after SPA navigation) */
+    fresh?: boolean;
+}
+export interface TreeResult {
+    text: string;
+    refCount: number;
+    depth: number;
+    tokenCount: number;
+    pageUrl: string;
+    hasVisualData?: boolean;
+    downsampled?: boolean;
+    originalTokens?: number;
+    downsampleLevel?: number;
+    /** FR-022: Number of content nodes (StaticText, paragraph, cell, etc.) with visible text that were hidden by filter:interactive. */
+    hiddenContentCount?: number;
+}
+export type ElementClassification = "widget-state" | "clickable" | "disabled" | "static";
+export interface DOMChange {
+    type: "added" | "removed" | "changed";
+    ref: string;
+    role: string;
+    before?: string;
+    after: string;
+}
+export type SnapshotMap = Map<number, string>;
+export interface ClosestRefSuggestion {
+    ref: string;
+    role: string;
+    name: string;
+}
+export declare class A11yTreeProcessor {
+    private refMap;
+    private reverseMap;
+    private nodeInfoMap;
+    private sessionNodeMap;
+    private nextRef;
+    private lastUrl;
+    private _precomputedNodes;
+    private _precomputedUrl;
+    private _precomputedSessionId;
+    private _precomputedDepth;
+    private _cacheVersion;
+    /** Story 13.1: Current cache version — increments on every state change */
+    get cacheVersion(): number;
+    reset(): void;
+    /** Invalidiert den Precomputed-Cache (z.B. nach Navigation oder Reconnect) */
+    invalidatePrecomputed(): void;
+    /** Hintergrund-Refresh: Laedt A11y-Tree und speichert als Cache */
+    refreshPrecomputed(cdpClient: CdpClient, sessionId: string, sessionManager?: SessionManager): Promise<void>;
+    /** Prueft ob ein gueltiger Precomputed-Cache vorliegt */
+    hasPrecomputed(sessionId: string): boolean;
+    /**
+     * H1: Remove all node references for a detached OOPIF session.
+     * Called when an OOPIF frame navigates away or is destroyed.
+     */
+    removeNodesForSession(sessionId: string): void;
+    resolveRef(ref: string): number | undefined;
+    getNodeInfo(backendNodeId: number): {
+        role: string;
+        name: string;
+    } | undefined;
+    /**
+     * 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: string): {
+        ref: string;
+        backendNodeId: number;
+    } | null;
+    /** Returns true if the ref map has been populated (i.e. getTree was called at least once). */
+    hasRefs(): boolean;
+    /** Number of currently assigned refs (for DOM fingerprinting, Story 7.5) */
+    get refCount(): number;
+    /** Current page URL (for on-the-fly fingerprint computation, Story 7.5 H1 fix) */
+    get currentUrl(): string;
+    getRefForBackendNodeId(backendNodeId: number): string | undefined;
+    private fetchVisualData;
+    /**
+     * 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.
+     */
+    private _enrichNodeMetadata;
+    private computeIsClickable;
+    private getSnapshotString;
+    findClosestRef(ref: string, roleFilter?: Set<string>): ClosestRefSuggestion | null;
+    getTree(cdpClient: CdpClient, sessionId: string, options?: TreeOptions, sessionManager?: SessionManager): Promise<TreeResult>;
+    private downsampleTree;
+    private truncateToFit;
+    /** C2: Trim body lines from the end (content first) until budget is met */
+    private trimBodyToFit;
+    private renderNodeDownsampled;
+    private renderChildrenDownsampled;
+    private countVisibleChildren;
+    private getVisibleChildren;
+    private countDescendantElements;
+    /** H3: Check if a node has any interactive descendants (recursive) */
+    private hasInteractiveDescendants;
+    private shortContainerRole;
+    private formatDownsampledHeader;
+    private getSubtree;
+    /** H2: Downsample a subtree (same algorithm as downsampleTree but for a single root) */
+    private downsampleSubtree;
+    /** BUG-001: Find the nearest heading sibling before this node in parent's children */
+    private findSectionHeading;
+    private renderNode;
+    /**
+     * 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.
+     */
+    private static readonly AGGREGATE_MIN_COUNT;
+    /**
+     * 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).
+     */
+    private _aggregateAnchors;
+    /**
+     * 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.
+     */
+    private _aggregateSuppressed;
+    /**
+     * 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.
+     */
+    private aggregationKey;
+    /**
+     * 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.
+     */
+    private isRenderableLeaf;
+    /**
+     * 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.
+     */
+    private prepareAggregateGroups;
+    /** Reset the per-render aggregation state set up by prepareAggregateGroups. */
+    private clearAggregateGroups;
+    /**
+     * 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.
+     */
+    private emitAggregateLine;
+    private renderChildren;
+    /** 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. */
+    private countHiddenContentNodes;
+    private getRole;
+    private passesFilter;
+    private formatLine;
+    private formatHeader;
+    private getPageTitle;
+    private getAvailableRefsRange;
+    private suggestClosestRef;
+    /**
+     * Story 13a.2: Classify a ref for pre-click ambient context decision.
+     * Returns classification based on cached AXNode properties (0 CDP calls).
+     */
+    classifyRef(ref: string): ElementClassification;
+    /**
+     * 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?: number): string[];
+    /**
+     * 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(): SnapshotMap;
+    /**
+     * FR-002: Compute diff between two snapshot maps.
+     * Returns only meaningful changes (role+name), ignoring nodes without names.
+     */
+    static diffSnapshots(before: SnapshotMap, after: SnapshotMap): DOMChange[];
+    /**
+     * 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: DOMChange[], url?: string): string | null;
+    /**
+     * Story 13a.2: Enriched compact snapshot with headings, alerts, status
+     * plus interactive elements. ZERO CDP calls — purely in-memory.
+     */
+    getCompactSnapshot(maxTokens?: number): string | null;
+}
+export declare class RefNotFoundError extends Error {
+    constructor(message: string);
+}
+export declare const a11yTree: A11yTreeProcessor;
+export {};