aether-mcp-server 2.0.1 → 2.1.0

package/README.md

@@ -1,28 +1,25 @@
 # Aether — AI Browser Controller
 
-Aether is an MCP (Model Context Protocol) server that lets AI coding agents inspect and control a real browser through the Chrome DevTools Protocol (CDP). No browser extension needed.
+Give your AI agent a real browser. Aether is an MCP server that lets Claude, Cursor, Kilo Code, Codex, and other AI coding agents inspect and control a live browser through the Chrome DevTools Protocol — no extension needed.
 
 ## Install
 
 ```bash
-npx aether-mcp-server
+npx -y aether-mcp-server
 ```
 
 Or globally:
 
 ```bash
 npm install -g aether-mcp-server
-aether-mcp-server
 ```
 
 ## MCP Client Config
 
-Add this to your MCP client (Cursor, Claude Code, Codex, KiloCode, etc.):
-
 ```json
 {
   "mcpServers": {
-    "aether-browser": {
+    "aether": {
       "command": "npx",
       "args": ["-y", "aether-mcp-server"]
     }
@@ -35,7 +32,7 @@ If installed globally:
 ```json
 {
   "mcpServers": {
-    "aether-browser": {
+    "aether": {
       "command": "aether-mcp-server",
       "args": []
     }
@@ -43,72 +40,52 @@ If installed globally:
 }
 ```
 
-That's it. No cloning. No building. No absolute paths.
+No cloning. No building. No absolute paths.
 
 ## What It Does
 
 - Launches or connects to Chrome, Edge, Brave, or Firefox with remote debugging
-- Exposes MCP tools for navigation, clicking, typing, form filling, screenshots, tabs, logs, cookies, network controls, PDF printing, and page inspection
-- Uses native CDP input events instead of fragile DOM-only hacks
-- Provides Set-of-Marks style visual element references for screenshot-based workflows
-- Resolves elements by selector, text, role, accessible name, label, placeholder, XPath, coordinates, same-origin iframe content, and shadow DOM content
-- Caches compact page snapshots and invalidates them on DOM/navigation/runtime events
+- Click by text, role, label, or placeholder — not fragile CSS selectors
+- Native CDP keyboard and mouse events, not DOM simulation
+- Smart page snapshots that auto-invalidate on DOM changes
+- Set-of-Marks visual element references for screenshot-based workflows
+- Shadow DOM and same-origin iframe support built in
 
 ## Browser Setup
 
-Launch a clean browser automatically:
-
 ```
 launch_browser()
-```
-
-Pick a specific browser:
-
-```
 launch_browser(browser="chrome")
 launch_browser(browser="edge")
 launch_browser(browser="brave")
 ```
 
-Connect to an existing browser with remote debugging:
+Connect to an existing browser:
 
 ```bash
 chrome --remote-debugging-port=9222
 ```
 
-Then:
-
 ```
 connect_browser(mode="connect", port=9222)
 ```
 
 ## Key Tools
 
-- `browser_status` — connection and active tab status
-- `snapshot_compact` — title, URL, readyState, and interactive element list
-- `list_interactive_elements` — element refs for click/fill flows
-- `click_by_ref` — click refs returned by compact snapshots
-- `click_text`, `click_role`, `fill_label` — semantic actions powered by the locator engine
-- `get_state` — optional screenshot, tabs, DOM snapshot, and elements
-- `get_logs`, `get_network_errors` — compact debugging output
-- `act` — broad compatibility action tool
+| Tool | What it does |
+|---|---|
+| `browser_status` | Connection and active tab status |
+| `snapshot_compact` | Fast title, URL, and interactive element list |
+| `list_interactive_elements` | Element refs for click/fill flows |
+| `click_text`, `click_role`, `fill_label` | Semantic actions |
+| `click_by_ref`, `fill_by_selector` | Direct element targeting |
+| `get_state` | Screenshot, tabs, DOM snapshot |
+| `get_logs`, `get_network_errors` | Live debugging output |
+| `act` | Broad compatibility action tool |
 
 ## Project-Local Learning
 
-Aether stores learned lessons and skills in `.aether/` inside your project:
-
-```
-<project>/.aether/
-  memory/
-    lessons.jsonl
-    learned.json
-  skills/
-    <skill-name>/SKILL.md
-    _registry.json
-  memory-config.json
-```
-
-Call `configure_aether_memory` with your project root to enable it. Aether creates `.aether/` and adds it to `.gitignore`.
+Aether stores learned lessons and reusable skills inside your project under `.aether/` — lightweight automation notes that make future runs faster. Call `configure_aether_memory` with your project root to enable it.
 
 ## Environment Variables
 
@@ -120,21 +97,7 @@ Call `configure_aether_memory` with your project root to enable it. Aether creat
 ## Requirements
 
 - Node.js >= 18
-- Chrome, Edge, Brave, or Firefox installed locally
-
-## Architecture
-
-```
-AI Agent / MCP Client
-        |
-        | stdio JSON-RPC
-        v
-Aether MCP Server
-        |
-        | Chrome DevTools Protocol
-        v
-Browser Target
-```
+- Chrome, Edge, Brave, or Firefox
 
 ## License
 

package/dist/cdp-bridge.js

@@ -1,4 +1,7 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CdpBridge = void 0;
 exports.getCdpBridge = getCdpBridge;
@@ -6,6 +9,8 @@ const cdp_client_1 = require("./cdp-client");
 const captcha_solver_1 = require("./captcha-solver");
 const locator_engine_1 = require("./locator-engine");
 const page_snapshot_cache_1 = require("./page-snapshot-cache");
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
 /**
  * Bridge layer that translates old extension-style commands to CDP commands.
  * This allows the MCP server to work without the Chrome extension.
@@ -169,6 +174,15 @@ class CdpBridge {
             case "get_dom_snapshot":
                 await this.ensureConnected();
                 return this.getDomSnapshot(params);
+            case "get_page_text":
+                await this.ensureConnected();
+                return this.getPageText(params);
+            case "save_auth_state":
+                await this.ensureConnected();
+                return this.saveAuthState(params);
+            case "load_auth_state":
+                await this.ensureConnected();
+                return this.loadAuthState(params);
             case "get_tabs":
                 await this.ensureConnected();
                 return this.getTabs(params);
@@ -354,72 +368,6 @@ class CdpBridge {
             elements: snapshot.elements
         };
     }
-    async getCompactElements(maxElements, includeText, withOverlay) {
-        const result = await this.client.sendCommand("Runtime.evaluate", {
-            expression: `
-                (function() {
-                    const max = ${JSON.stringify(maxElements)};
-                    const includeText = ${JSON.stringify(includeText)};
-                    const selectors = [
-                        'a[href]', 'button', 'input:not([type="hidden"])', 'select', 'textarea',
-                        '[onclick]', '[role="button"]', '[role="link"]', '[role="checkbox"]',
-                        '[tabindex]:not([tabindex="-1"])', 'label', 'summary'
-                    ].join(', ');
-
-                    function cssPath(el) {
-                        if (el.id) return '#' + CSS.escape(el.id);
-                        const path = [];
-                        while (el && el.nodeType === Node.ELEMENT_NODE && el !== document.body) {
-                            let selector = el.nodeName.toLowerCase();
-                            if (el.classList && el.classList.length) {
-                                selector += '.' + Array.from(el.classList).slice(0, 2).map(c => CSS.escape(c)).join('.');
-                            }
-                            const parent = el.parentElement;
-                            if (parent) {
-                                const siblings = Array.from(parent.children).filter(child => child.nodeName === el.nodeName);
-                                if (siblings.length > 1) selector += ':nth-of-type(' + (siblings.indexOf(el) + 1) + ')';
-                            }
-                            path.unshift(selector);
-                            el = parent;
-                        }
-                        return path.length ? path.join(' > ') : '';
-                    }
-
-                    return Array.from(document.querySelectorAll(selectors)).map((el, index) => {
-                        const rect = el.getBoundingClientRect();
-                        const computed = window.getComputedStyle(el);
-                        const visible = computed.display !== 'none' && computed.visibility !== 'hidden' && rect.width > 0 && rect.height > 0;
-                        if (!visible) return null;
-                        const selector = cssPath(el);
-                        if (!selector) return null;
-                        const text = ((el.innerText || el.textContent || el.getAttribute('aria-label') || el.getAttribute('placeholder') || '') + '').trim().replace(/\\s+/g, ' ').substring(0, 120);
-                        return {
-                            ref: 'css:' + selector,
-                            index: index + 1,
-                            tag: el.tagName.toLowerCase(),
-                            role: el.getAttribute('role') || '',
-                            type: el.getAttribute('type') || '',
-                            name: el.getAttribute('name') || '',
-                            text: includeText ? text : undefined,
-                            bounds: {
-                                x: Math.round(rect.left),
-                                y: Math.round(rect.top),
-                                width: Math.round(rect.width),
-                                height: Math.round(rect.height)
-                            }
-                        };
-                    }).filter(Boolean).slice(0, max);
-                })()
-            `,
-            returnByValue: true,
-            awaitPromise: true
-        });
-        const elements = result.result?.value || [];
-        if (withOverlay && elements.length > 0) {
-            await this.client.getInteractiveElements(true).catch(() => ({ elements: [], somInjected: false }));
-        }
-        return elements;
-    }
     async clickByRef(params) {
         const ref = String(params.ref || "");
         if (!ref)
@@ -1143,28 +1091,91 @@ class CdpBridge {
             this.snapshotCache.invalidate("click_element_by_selector");
             return "Clicked element by point";
         }
-        // Get element bounds via CDP
-        const result = await this.client.sendCommand("Runtime.evaluate", {
-            expression: `
-                (function() {
-                    const el = document.querySelector(${JSON.stringify(selector)});
-                    if (!el) return null;
-                    el.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' });
-                    const rect = el.getBoundingClientRect();
-                    const computed = window.getComputedStyle(el);
-                    if (computed.display === 'none' || computed.visibility === 'hidden' || rect.width === 0 || rect.height === 0) return null;
-                    return { x: rect.left + rect.width/2, y: rect.top + rect.height/2, w: rect.width };
-                })()
-            `,
-            returnByValue: true,
-        });
-        if (result.result?.value) {
-            const { x, y, w } = result.result.value;
-            await this.client.click(x, y, params.button, w);
-            this.snapshotCache.invalidate("click_element_by_selector");
-            return "Clicked element by selector";
+        // Run the full actionability gate (visible, enabled, in-viewport, stable
+        // bounds, not obscured) before committing the click.
+        const point = await this.resolveActionablePoint(selector, params.timeout ?? 4000);
+        if (!point.ok) {
+            const detail = point.reason === "obscured" && point.obscuredBy
+                ? `${point.reason} by <${point.obscuredBy}>`
+                : point.reason;
+            throw new Error(`Element not actionable (${detail}): ${selector}`);
+        }
+        await this.client.click(point.x, point.y, params.button, point.w);
+        this.snapshotCache.invalidate("click_element_by_selector");
+        return "Clicked element by selector";
+    }
+    /**
+     * Centralized actionability gate. Polls until the selector resolves to an
+     * element that is visible, enabled, scrolled into the viewport, has stable
+     * bounds across frames, and is the topmost element at its own click point
+     * (i.e. not covered by an overlay/cookie banner). Returns the verified click
+     * point, or the blocking reason so the caller can surface it.
+     */
+    async resolveActionablePoint(selector, timeout = 4000) {
+        const start = Date.now();
+        let lastBoxKey = "";
+        let stableHits = 0;
+        let last = { ok: false, reason: "not_found" };
+        while (Date.now() - start < timeout) {
+            const result = await this.client.sendCommand("Runtime.evaluate", {
+                expression: `
+                    (function() {
+                        const el = document.querySelector(${JSON.stringify(selector)});
+                        if (!el) return { ok: false, reason: 'not_found' };
+                        el.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' });
+                        const rect = el.getBoundingClientRect();
+                        const style = window.getComputedStyle(el);
+                        if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0' || rect.width === 0 || rect.height === 0) {
+                            return { ok: false, reason: 'not_visible' };
+                        }
+                        if (el.disabled === true || el.getAttribute('aria-disabled') === 'true' || style.pointerEvents === 'none') {
+                            return { ok: false, reason: 'disabled' };
+                        }
+                        const cx = rect.left + rect.width / 2;
+                        const cy = rect.top + rect.height / 2;
+                        const vw = window.innerWidth || document.documentElement.clientWidth;
+                        const vh = window.innerHeight || document.documentElement.clientHeight;
+                        if (cx < 0 || cy < 0 || cx > vw || cy > vh) {
+                            return { ok: false, reason: 'offscreen' };
+                        }
+                        const top = document.elementFromPoint(cx, cy);
+                        const reachable = top === el || el.contains(top) || (top && top.contains(el));
+                        let obscuredBy = '';
+                        if (!reachable && top) {
+                            obscuredBy = top.tagName.toLowerCase() + (top.id ? '#' + top.id : '');
+                        }
+                        return {
+                            ok: !!reachable,
+                            reason: reachable ? 'ok' : 'obscured',
+                            obscuredBy: obscuredBy,
+                            x: cx,
+                            y: cy,
+                            w: rect.width,
+                            boxKey: Math.round(rect.left) + ',' + Math.round(rect.top) + ',' + Math.round(rect.width) + ',' + Math.round(rect.height)
+                        };
+                    })()
+                `,
+                returnByValue: true,
+            });
+            const state = result.result?.value;
+            if (state) {
+                last = state;
+                if (state.ok) {
+                    if (state.boxKey === lastBoxKey) {
+                        stableHits++;
+                        if (stableHits >= 1) {
+                            return { ok: true, reason: "ok", x: state.x, y: state.y, w: state.w };
+                        }
+                    }
+                    else {
+                        lastBoxKey = state.boxKey;
+                        stableHits = 0;
+                    }
+                }
+            }
+            await new Promise(r => setTimeout(r, 90));
         }
-        throw new Error(`Element not found: ${selector}`);
+        return { ok: false, reason: last?.reason || "timeout", obscuredBy: last?.obscuredBy };
     }
     async type(params) {
         const text = params.text || params.value || "";
@@ -1213,6 +1224,266 @@ class CdpBridge {
     async getDomSnapshot(params) {
         return await this.client.getDOMSnapshot();
     }
+    /**
+     * Extract clean, readable page content as Markdown (or plain text) — a
+     * token-cheap alternative to screenshots or full DOM dumps for reading a page.
+     * Scopes to `selector` when provided, otherwise picks the main content region.
+     */
+    async getPageText(params) {
+        const format = params.format === "text" ? "text" : "markdown";
+        const selector = params.selector ? String(params.selector) : "";
+        const maxLength = Math.max(500, Math.min(Number(params.maxLength ?? 20000), 200000));
+        const includeLinks = params.includeLinks !== false;
+        const extracted = await this.client.evaluate(`
+            (function() {
+                const FORMAT = ${JSON.stringify(format)};
+                const SELECTOR = ${JSON.stringify(selector)};
+                const INCLUDE_LINKS = ${JSON.stringify(includeLinks)};
+                const SKIP = new Set(['SCRIPT','STYLE','NOSCRIPT','SVG','CANVAS','TEMPLATE','IFRAME','OBJECT','EMBED','NAV','FOOTER','HEADER','ASIDE']);
+
+                function pickRoot() {
+                    if (SELECTOR) {
+                        const el = document.querySelector(SELECTOR);
+                        if (el) return el;
+                    }
+                    return document.querySelector('main, article, [role="main"]') || document.body || document.documentElement;
+                }
+
+                function isHidden(el) {
+                    if (el.getAttribute && el.getAttribute('aria-hidden') === 'true') return true;
+                    const style = window.getComputedStyle(el);
+                    if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') return true;
+                    const rect = el.getBoundingClientRect();
+                    return rect.width === 0 && rect.height === 0 && el.tagName !== 'BR' && el.tagName !== 'HR';
+                }
+
+                function inline(node) {
+                    let out = '';
+                    node.childNodes.forEach(function(child) {
+                        if (child.nodeType === Node.TEXT_NODE) {
+                            out += child.textContent.replace(/\\s+/g, ' ');
+                        } else if (child.nodeType === Node.ELEMENT_NODE) {
+                            if (SKIP.has(child.tagName) || isHidden(child)) return;
+                            const tag = child.tagName.toLowerCase();
+                            const inner = inline(child);
+                            if (FORMAT === 'markdown') {
+                                if (tag === 'a' && INCLUDE_LINKS && child.getAttribute('href')) {
+                                    const href = child.getAttribute('href');
+                                    out += inner.trim() ? '[' + inner.trim() + '](' + href + ')' : '';
+                                } else if (tag === 'strong' || tag === 'b') {
+                                    out += inner.trim() ? '**' + inner.trim() + '**' : '';
+                                } else if (tag === 'em' || tag === 'i') {
+                                    out += inner.trim() ? '*' + inner.trim() + '*' : '';
+                                } else if (tag === 'code') {
+                                    out += inner.trim() ? '\`' + inner.trim() + '\`' : '';
+                                } else if (tag === 'br') {
+                                    out += '\\n';
+                                } else {
+                                    out += inner;
+                                }
+                            } else {
+                                out += (tag === 'br') ? '\\n' : inner;
+                            }
+                        }
+                    });
+                    return out;
+                }
+
+                const BLOCK = new Set(['P','DIV','SECTION','ARTICLE','UL','OL','LI','TABLE','TR','BLOCKQUOTE','PRE','H1','H2','H3','H4','H5','H6','HR','FIGURE','FIGCAPTION']);
+                const lines = [];
+
+                function walk(node, depth) {
+                    if (node.nodeType !== Node.ELEMENT_NODE) return;
+                    if (SKIP.has(node.tagName) || isHidden(node)) return;
+                    const tag = node.tagName.toLowerCase();
+
+                    if (/^h[1-6]$/.test(tag)) {
+                        const t = inline(node).trim();
+                        if (t) lines.push(FORMAT === 'markdown' ? '#'.repeat(Number(tag[1])) + ' ' + t : t);
+                        return;
+                    }
+                    if (tag === 'hr') { lines.push(FORMAT === 'markdown' ? '---' : ''); return; }
+                    if (tag === 'pre') {
+                        const t = (node.innerText || node.textContent || '').replace(/\\s+$/,'');
+                        if (t) lines.push(FORMAT === 'markdown' ? '\\n\`\`\`\\n' + t + '\\n\`\`\`\\n' : t);
+                        return;
+                    }
+                    if (tag === 'li') {
+                        const t = inline(node).trim();
+                        if (t) {
+                            const indent = '  '.repeat(Math.max(0, depth));
+                            lines.push(FORMAT === 'markdown' ? indent + '- ' + t : indent + '• ' + t);
+                        }
+                        return;
+                    }
+                    if (tag === 'blockquote') {
+                        const t = inline(node).trim();
+                        if (t) lines.push(FORMAT === 'markdown' ? '> ' + t : t);
+                        return;
+                    }
+                    if (tag === 'tr') {
+                        const cells = Array.from(node.children).map(function(c){ return inline(c).trim(); });
+                        if (cells.some(Boolean)) lines.push(FORMAT === 'markdown' ? '| ' + cells.join(' | ') + ' |' : cells.join('\\t'));
+                        return;
+                    }
+
+                    // Leaf-ish block (no block descendants): emit its inline text once.
+                    const hasBlockChild = Array.from(node.children).some(function(c){ return BLOCK.has(c.tagName); });
+                    if (!hasBlockChild && (tag === 'p' || tag === 'div' || tag === 'section' || tag === 'figcaption' || tag === 'td' || tag === 'th')) {
+                        const t = inline(node).trim();
+                        if (t) lines.push(t);
+                        return;
+                    }
+
+                    const nextDepth = (tag === 'ul' || tag === 'ol') ? depth + 1 : depth;
+                    node.childNodes.forEach(function(child){ walk(child, nextDepth); });
+                }
+
+                const root = pickRoot();
+                walk(root, 0);
+
+                let text = lines.join('\\n\\n').replace(/\\n{3,}/g, '\\n\\n').replace(/[ \\t]+\\n/g, '\\n').trim();
+                return { title: document.title || '', url: location.href, text: text };
+            })()
+        `).catch((e) => ({ title: "", url: "", text: "", error: e?.message }));
+        const text = String(extracted?.text ?? "");
+        const truncated = text.length > maxLength;
+        return {
+            title: extracted?.title ?? "",
+            url: extracted?.url ?? "",
+            format,
+            length: text.length,
+            truncated,
+            text: truncated ? text.slice(0, maxLength) + "\n\n…[truncated]" : text,
+        };
+    }
+    defaultAuthStatePath(custom) {
+        if (custom)
+            return path_1.default.resolve(String(custom));
+        return path_1.default.resolve(process.cwd(), ".aether", "auth-state.json");
+    }
+    // CDP Network.getAllCookies returns Cookie objects with read-only fields
+    // (size, session, …) that Network.setCookies rejects. Keep only CookieParam fields.
+    toCookieParam(c) {
+        const param = {
+            name: c.name,
+            value: c.value,
+            domain: c.domain,
+            path: c.path,
+            secure: c.secure,
+            httpOnly: c.httpOnly,
+        };
+        if (typeof c.expires === "number" && c.expires > 0)
+            param.expires = c.expires;
+        if (c.sameSite)
+            param.sameSite = c.sameSite;
+        if (c.priority)
+            param.priority = c.priority;
+        if (c.sourceScheme)
+            param.sourceScheme = c.sourceScheme;
+        if (typeof c.sourcePort === "number")
+            param.sourcePort = c.sourcePort;
+        if (c.partitionKey)
+            param.partitionKey = c.partitionKey;
+        return param;
+    }
+    /**
+     * Export the current session (cookies + localStorage + sessionStorage of the
+     * active origin) to a JSON file so a logged-in state can be reused later.
+     */
+    async saveAuthState(params) {
+        const filePath = this.defaultAuthStatePath(params.path);
+        const cookiesRes = await this.client.sendCommand("Network.getAllCookies", {})
+            .catch(() => this.client.sendCommand("Storage.getCookies", {}).catch(() => ({ cookies: [] })));
+        const cookies = (cookiesRes?.cookies || []).map((c) => this.toCookieParam(c));
+        const storage = await this.client.evaluate(`
+            (function() {
+                const ls = {}, ss = {};
+                try { for (let i = 0; i < localStorage.length; i++) { const k = localStorage.key(i); ls[k] = localStorage.getItem(k); } } catch (e) {}
+                try { for (let i = 0; i < sessionStorage.length; i++) { const k = sessionStorage.key(i); ss[k] = sessionStorage.getItem(k); } } catch (e) {}
+                return { origin: location.origin, localStorage: ls, sessionStorage: ss };
+            })()
+        `).catch(() => null);
+        const state = {
+            version: 1,
+            savedAt: new Date().toISOString(),
+            cookies,
+            origins: storage ? [storage] : [],
+        };
+        await fs_1.promises.mkdir(path_1.default.dirname(filePath), { recursive: true });
+        await fs_1.promises.writeFile(filePath, JSON.stringify(state, null, 2), "utf8");
+        return {
+            success: true,
+            path: filePath,
+            cookies: cookies.length,
+            origins: state.origins.length,
+            storageKeys: storage ? Object.keys(storage.localStorage).length + Object.keys(storage.sessionStorage).length : 0,
+        };
+    }
+    /**
+     * Restore a session saved by saveAuthState. Cookies are set globally; storage
+     * is restored for the active origin (navigate to the site first), then the tab
+     * is reloaded so the session takes effect.
+     */
+    async loadAuthState(params) {
+        const filePath = this.defaultAuthStatePath(params.path);
+        let raw;
+        try {
+            raw = await fs_1.promises.readFile(filePath, "utf8");
+        }
+        catch (e) {
+            return { success: false, path: filePath, message: `Could not read auth state: ${e?.message}` };
+        }
+        let state;
+        try {
+            state = JSON.parse(raw);
+        }
+        catch (e) {
+            return { success: false, path: filePath, message: `Invalid auth state JSON: ${e?.message}` };
+        }
+        let cookiesSet = 0;
+        if (Array.isArray(state.cookies) && state.cookies.length) {
+            const params2 = state.cookies.map((c) => this.toCookieParam(c));
+            await this.client.setCookies(params2).catch((err) => {
+                console.error("[Aether] setCookies failed during loadAuthState:", err?.message);
+            });
+            cookiesSet = params2.length;
+        }
+        let storageRestored = 0;
+        let storageSkipped = 0;
+        const currentOrigin = await this.client.evaluate("location.origin").catch(() => "");
+        for (const entry of (state.origins || [])) {
+            if (entry.origin && currentOrigin && entry.origin !== currentOrigin) {
+                storageSkipped++;
+                continue;
+            }
+            const data = JSON.stringify({ localStorage: entry.localStorage || {}, sessionStorage: entry.sessionStorage || {} });
+            const ok = await this.client.evaluate(`
+                (function() {
+                    try {
+                        const data = ${data};
+                        for (const k in data.localStorage) localStorage.setItem(k, data.localStorage[k]);
+                        for (const k in data.sessionStorage) sessionStorage.setItem(k, data.sessionStorage[k]);
+                        return true;
+                    } catch (e) { return false; }
+                })()
+            `).catch(() => false);
+            if (ok)
+                storageRestored++;
+        }
+        if (params.reload !== false) {
+            await this.client.reload(false).catch(() => { });
+        }
+        this.snapshotCache.invalidate("load_auth_state");
+        return {
+            success: true,
+            path: filePath,
+            cookiesSet,
+            storageRestored,
+            storageSkipped,
+            note: storageSkipped > 0 ? "Some storage origins were skipped; navigate to that origin before loading to restore them." : undefined,
+        };
+    }
     // ==================== AGENT-CENTRIC APIs ====================
     async agentAction(params) {
         const { action, target, verify, waitFor, timeout } = params;

package/dist/cdp-client.js

@@ -13,6 +13,7 @@ const fs_1 = require("fs");
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const stealth_1 = require("./stealth");
+const element_collector_1 = require("./element-collector");
 class CdpClient {
     ws = null;
     messageId = 0;
@@ -208,7 +209,8 @@ class CdpClient {
             expression: `
                 (function() {
                     const withSoM = ${JSON.stringify(withSoM)};
-                    
+                    ${element_collector_1.SHARED_DOM_HELPERS}
+
                     // Remove existing overlays
                     const oldContainer = document.getElementById('aether-som-container');
                     if (oldContainer) oldContainer.remove();
@@ -245,11 +247,8 @@ class CdpClient {
                         let text = el.innerText || el.textContent || '';
                         text = text.trim().substring(0, 100);
                         
-                        // Get selector
-                        let selector = '';
-                        if (el.id) selector = '#' + CSS.escape(el.id);
-                        else if (el.className && typeof el.className === 'string') selector = '.' + el.className.split(' ')[0];
-                        else selector = el.tagName.toLowerCase();
+                        // Get a stable selector (shared with the locator engine)
+                        const selector = aetherStableSelector(el);
                         
                         if (withSoM && container) {
                             const id = String(validIndex);
@@ -285,7 +284,7 @@ class CdpClient {
                             attributes: {
                                 type: el.getAttribute('type') || '',
                                 href: el.getAttribute('href') || '',
-                                role: el.getAttribute('role') || '',
+                                role: aetherImplicitRole(el),
                                 'aria-label': el.getAttribute('aria-label') || ''
                             }
                         };

package/dist/element-collector.js

@@ -0,0 +1,198 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHARED_DOM_HELPERS = void 0;
+/**
+ * Shared in-page DOM collection helpers.
+ *
+ * These helpers are injected (as source text) into every element-collection
+ * script so that the LocatorEngine, the Set-of-Marks overlay collector, and the
+ * compact snapshot all derive selectors, roles, names, and visibility the SAME
+ * way. Previously each call site had its own divergent copy, so `get_state`,
+ * `list_interactive_elements`, and the semantic click resolver could disagree
+ * about the same element.
+ *
+ * Role/name resolution follows the WAI-ARIA implicit-role mapping and the
+ * accessible-name computation closely enough that role/label targeting matches
+ * what the browser's own accessibility tree reports.
+ */
+exports.SHARED_DOM_HELPERS = `
+    function aetherNorm(value) {
+        return String(value == null ? '' : value).trim().replace(/\\s+/g, ' ');
+    }
+
+    function aetherVisible(el) {
+        if (!el || el.nodeType !== Node.ELEMENT_NODE) return false;
+        const rect = el.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0) return false;
+        const style = window.getComputedStyle(el);
+        return style.display !== 'none' &&
+            style.visibility !== 'hidden' &&
+            style.opacity !== '0';
+    }
+
+    // WAI-ARIA implicit role mapping. Mirrors what the accessibility tree reports
+    // so role-based targeting (click_role, fill_label) lines up with the browser.
+    function aetherImplicitRole(el) {
+        const explicit = (el.getAttribute('role') || '').trim().toLowerCase();
+        if (explicit) return explicit.split(/\\s+/)[0];
+        const tag = el.tagName.toLowerCase();
+        const type = (el.getAttribute('type') || '').toLowerCase();
+        switch (tag) {
+            case 'a':
+            case 'area':
+                return el.hasAttribute('href') ? 'link' : 'generic';
+            case 'button':
+                return 'button';
+            case 'summary':
+                return 'button';
+            case 'select':
+                return (el.multiple || el.size > 1) ? 'listbox' : 'combobox';
+            case 'textarea':
+                return 'textbox';
+            case 'progress':
+                return 'progressbar';
+            case 'output':
+                return 'status';
+            case 'input':
+                switch (type) {
+                    case 'button':
+                    case 'submit':
+                    case 'reset':
+                    case 'image':
+                        return 'button';
+                    case 'checkbox':
+                        return 'checkbox';
+                    case 'radio':
+                        return 'radio';
+                    case 'range':
+                        return 'slider';
+                    case 'number':
+                        return 'spinbutton';
+                    case 'search':
+                        return el.getAttribute('list') ? 'combobox' : 'searchbox';
+                    case 'email':
+                    case 'tel':
+                    case 'text':
+                    case 'url':
+                    case '':
+                        return el.getAttribute('list') ? 'combobox' : 'textbox';
+                    default:
+                        return 'textbox';
+                }
+        }
+        if (el.isContentEditable) return 'textbox';
+        if (/^h[1-6]$/.test(tag)) return 'heading';
+        return tag;
+    }
+
+    function aetherTextById(doc, id) {
+        if (!id) return '';
+        try {
+            const el = doc.getElementById(id);
+            return el ? aetherNorm(el.innerText || el.textContent) : '';
+        } catch (e) {
+            return '';
+        }
+    }
+
+    function aetherLabelFor(el) {
+        const doc = el.ownerDocument;
+        const labelledBy = aetherNorm(
+            (el.getAttribute('aria-labelledby') || '')
+                .split(/\\s+/)
+                .map(function (id) { return aetherTextById(doc, id); })
+                .join(' ')
+        );
+        if (labelledBy) return labelledBy;
+        if (el.id) {
+            try {
+                const direct = doc.querySelector('label[for="' + CSS.escape(el.id) + '"]');
+                if (direct) return aetherNorm(direct.innerText || direct.textContent);
+            } catch (e) {}
+        }
+        const wrapping = el.closest && el.closest('label');
+        return wrapping ? aetherNorm(wrapping.innerText || wrapping.textContent) : '';
+    }
+
+    // Accessible-name computation (simplified): aria-label > aria-labelledby/label >
+    // placeholder > alt > title > control value > visible text.
+    function aetherAccessibleName(el) {
+        return aetherNorm(
+            el.getAttribute('aria-label') ||
+            aetherLabelFor(el) ||
+            el.getAttribute('placeholder') ||
+            el.getAttribute('alt') ||
+            el.getAttribute('title') ||
+            ((el.tagName === 'INPUT' || el.tagName === 'BUTTON') ? el.getAttribute('value') : '') ||
+            el.innerText ||
+            el.textContent ||
+            el.getAttribute('name') ||
+            ''
+        );
+    }
+
+    function aetherIsUnique(root, selector) {
+        try {
+            return root.querySelectorAll(selector).length === 1;
+        } catch (e) {
+            return false;
+        }
+    }
+
+    function aetherStructuralPath(el) {
+        const path = [];
+        let node = el;
+        const stop = el.ownerDocument ? el.ownerDocument.body : null;
+        while (node && node.nodeType === Node.ELEMENT_NODE && node !== stop) {
+            let part = node.nodeName.toLowerCase();
+            if (node.classList && node.classList.length) {
+                part += '.' + Array.from(node.classList).slice(0, 2).map(function (c) { return CSS.escape(c); }).join('.');
+            }
+            const parent = node.parentElement;
+            if (parent) {
+                const same = Array.from(parent.children).filter(function (child) { return child.nodeName === node.nodeName; });
+                if (same.length > 1) part += ':nth-of-type(' + (same.indexOf(node) + 1) + ')';
+            }
+            path.unshift(part);
+            node = parent;
+        }
+        return path.join(' > ');
+    }
+
+    // Prefer stable, intent-revealing selectors (test ids, id, name, aria-label)
+    // and only fall back to a brittle structural path when nothing stable+unique
+    // is available.
+    function aetherStableSelector(el) {
+        if (!el || el.nodeType !== Node.ELEMENT_NODE) return '';
+        const root = el.getRootNode ? el.getRootNode() : el.ownerDocument;
+        const tag = el.tagName.toLowerCase();
+
+        const testAttrs = ['data-testid', 'data-test-id', 'data-test', 'data-cy', 'data-qa', 'data-automation-id'];
+        for (let i = 0; i < testAttrs.length; i++) {
+            const v = el.getAttribute(testAttrs[i]);
+            if (v) {
+                const sel = '[' + testAttrs[i] + '=' + JSON.stringify(v) + ']';
+                if (aetherIsUnique(root, sel)) return sel;
+            }
+        }
+
+        if (el.id) {
+            const sel = '#' + CSS.escape(el.id);
+            if (aetherIsUnique(root, sel)) return sel;
+        }
+
+        const name = el.getAttribute('name');
+        if (name && (tag === 'input' || tag === 'select' || tag === 'textarea' || tag === 'button')) {
+            const sel = tag + '[name=' + JSON.stringify(name) + ']';
+            if (aetherIsUnique(root, sel)) return sel;
+        }
+
+        const aria = el.getAttribute('aria-label');
+        if (aria) {
+            const sel = tag + '[aria-label=' + JSON.stringify(aria) + ']';
+            if (aetherIsUnique(root, sel)) return sel;
+        }
+
+        return aetherStructuralPath(el);
+    }
+`;

package/dist/locator-engine.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LocatorEngine = void 0;
+const element_collector_1 = require("./element-collector");
 const DEFAULT_TIMEOUT = 7000;
 class LocatorEngine {
     client;
@@ -97,40 +98,16 @@ function locatorScript(input) {
                 '[contenteditable="true"]', '[aria-label]', '[placeholder]'
             ].join(', ');
 
-            function norm(value) {
-                return String(value || '').trim().replace(/\\s+/g, ' ');
-            }
+            ${element_collector_1.SHARED_DOM_HELPERS}
 
-            function visible(el) {
-                const rect = el.getBoundingClientRect();
-                const style = window.getComputedStyle(el);
-                return style.display !== 'none' &&
-                    style.visibility !== 'hidden' &&
-                    style.opacity !== '0' &&
-                    rect.width > 0 &&
-                    rect.height > 0;
-            }
-
-            function cssPath(el) {
-                if (!el || el.nodeType !== Node.ELEMENT_NODE) return '';
-                if (el.id) return '#' + CSS.escape(el.id);
-                const path = [];
-                let node = el;
-                while (node && node.nodeType === Node.ELEMENT_NODE && node !== node.ownerDocument.body) {
-                    let part = node.nodeName.toLowerCase();
-                    if (node.classList && node.classList.length) {
-                        part += '.' + Array.from(node.classList).slice(0, 2).map((c) => CSS.escape(c)).join('.');
-                    }
-                    const parent = node.parentElement;
-                    if (parent) {
-                        const same = Array.from(parent.children).filter((child) => child.nodeName === node.nodeName);
-                        if (same.length > 1) part += ':nth-of-type(' + (same.indexOf(node) + 1) + ')';
-                    }
-                    path.unshift(part);
-                    node = parent;
-                }
-                return path.join(' > ');
-            }
+            // Thin aliases so the rest of this resolver reads naturally while the
+            // implementations stay shared with every other collector.
+            const norm = aetherNorm;
+            const visible = aetherVisible;
+            const cssPath = aetherStableSelector;
+            const inferRole = aetherImplicitRole;
+            const labelFor = aetherLabelFor;
+            const textFor = aetherAccessibleName;
 
             function xpath(el) {
                 const parts = [];
@@ -148,55 +125,6 @@ function locatorScript(input) {
                 return '/' + parts.join('/');
             }
 
-            function inferRole(el) {
-                const explicit = (el.getAttribute('role') || '').toLowerCase();
-                if (explicit) return explicit;
-                const tag = el.tagName.toLowerCase();
-                const type = (el.getAttribute('type') || '').toLowerCase();
-                if (tag === 'button' || type === 'button' || type === 'submit' || type === 'reset') return 'button';
-                if (tag === 'a') return 'link';
-                if (tag === 'textarea') return 'textbox';
-                if (tag === 'select') return 'combobox';
-                if (tag === 'input' && ['checkbox', 'radio'].includes(type)) return type;
-                if (tag === 'input') return 'textbox';
-                if (el.isContentEditable) return 'textbox';
-                if (tag === 'summary') return 'button';
-                return tag;
-            }
-
-            function byId(doc, id) {
-                if (!id) return '';
-                const el = doc.getElementById(id);
-                return el ? norm(el.innerText || el.textContent) : '';
-            }
-
-            function labelFor(el) {
-                const doc = el.ownerDocument;
-                const labelledBy = norm((el.getAttribute('aria-labelledby') || '').split(/\\s+/).map((id) => byId(doc, id)).join(' '));
-                if (labelledBy) return labelledBy;
-                if (el.id) {
-                    const direct = doc.querySelector('label[for="' + CSS.escape(el.id) + '"]');
-                    if (direct) return norm(direct.innerText || direct.textContent);
-                }
-                const wrapping = el.closest && el.closest('label');
-                return wrapping ? norm(wrapping.innerText || wrapping.textContent) : '';
-            }
-
-            function textFor(el) {
-                return norm(
-                    el.getAttribute('aria-label') ||
-                    labelFor(el) ||
-                    el.getAttribute('placeholder') ||
-                    el.getAttribute('alt') ||
-                    el.getAttribute('title') ||
-                    el.innerText ||
-                    el.textContent ||
-                    el.getAttribute('value') ||
-                    el.getAttribute('name') ||
-                    ''
-                );
-            }
-
             function scoreField(field, value, exact, includes) {
                 const text = norm(value);
                 const lower = text.toLowerCase();

package/dist/mcp-server.js

@@ -663,6 +663,41 @@ const Tools = [
             required: ["fields"]
         }
     },
+    {
+        name: "get_page_text",
+        description: "READ TOOL. Extract clean, readable page content as Markdown (or plain text). Token-cheap alternative to screenshots or full DOM dumps for reading/understanding a page. Scopes to a CSS selector when given, otherwise auto-detects the main content region.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                format: { type: "string", enum: ["markdown", "text"], description: "Output format. Default markdown." },
+                selector: { type: "string", description: "Optional CSS selector to scope extraction to a region." },
+                includeLinks: { type: "boolean", description: "Render anchors as [text](href) in markdown. Default true." },
+                maxLength: { type: "number", description: "Max characters returned before truncation. Default 20000." }
+            }
+        }
+    },
+    {
+        name: "save_auth_state",
+        description: "SESSION TOOL. Export the current browser session (cookies + localStorage + sessionStorage) to a JSON file so a logged-in session can be reused later with load_auth_state. Avoids repeating logins.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "File path to write the auth state JSON. Defaults to <cwd>/.aether/auth-state.json." },
+                origins: { type: "array", items: { type: "string" }, description: "Optional list of origins to capture storage for. Defaults to the current origin." }
+            }
+        }
+    },
+    {
+        name: "load_auth_state",
+        description: "SESSION TOOL. Restore a previously saved session (cookies + localStorage + sessionStorage) from a JSON file written by save_auth_state. Navigate to the target site first, then load, then reload.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "File path to read the auth state JSON. Defaults to <cwd>/.aether/auth-state.json." },
+                reload: { type: "boolean", description: "Reload the active tab after restoring so storage takes effect. Default true." }
+            }
+        }
+    },
     {
         name: "page_snapshot",
         description: "Capture page context optimized for LLM consumption. Lightweight by default; opt into screenshots, cookies, accessibility tree, or full DOM snapshot when needed.",
@@ -1221,6 +1256,30 @@ function RegisterMcpTools(server, wsServer) {
                 }
                 return { content };
             }
+            if (name === "get_page_text") {
+                const result = await bridge.sendCommand("get_page_text", {
+                    format: a?.format,
+                    selector: a?.selector,
+                    includeLinks: a?.includeLinks,
+                    maxLength: a?.maxLength,
+                });
+                const header = `Title: ${result.title}\nURL: ${result.url}\nFormat: ${result.format} | ${result.length} chars${result.truncated ? " (truncated)" : ""}`;
+                return { content: [{ type: "text", text: `${header}\n\n${result.text}` }] };
+            }
+            if (name === "save_auth_state") {
+                const result = await bridge.sendCommand("save_auth_state", {
+                    path: a?.path,
+                    origins: a?.origins,
+                });
+                return { content: [{ type: "text", text: JSON.stringify(result) }] };
+            }
+            if (name === "load_auth_state") {
+                const result = await bridge.sendCommand("load_auth_state", {
+                    path: a?.path,
+                    reload: a?.reload,
+                });
+                return { content: [{ type: "text", text: JSON.stringify(result) }] };
+            }
             throw new Error(`Unknown tool: ${name}`);
         }
         catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "aether-mcp-server",
-    "version": "2.0.1",
+    "version": "2.1.0",
     "description": "Aether MCP Server - AI Browser Controller",
     "main": "dist/index.js",
     "bin": {