@silbercue/chrome 0.2.0

package/build/server.d.ts

@@ -0,0 +1 @@
+export declare function startServer(): Promise<void>;

package/build/server.js

@@ -0,0 +1,245 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ChromeLauncher, resolveAutoLaunch } from "./cdp/chrome-launcher.js";
+import { SessionManager } from "./cdp/session-manager.js";
+import { DialogHandler } from "./cdp/dialog-handler.js";
+import { ConsoleCollector } from "./cdp/console-collector.js";
+import { NetworkCollector } from "./cdp/network-collector.js";
+import { DomWatcher } from "./cdp/dom-watcher.js";
+import { DEVICE_METRICS_OVERRIDE, EMULATED_WIDTH, EMULATED_HEIGHT, setHeadless } from "./cdp/emulation.js";
+import { ToolRegistry } from "./registry.js";
+import { injectOverlay, removeOverlay, setTierLabel, setLicenseInfo } from "./overlay/session-overlay.js";
+import { TabStateCache } from "./cache/tab-state-cache.js";
+import { SessionDefaults } from "./cache/session-defaults.js";
+import { a11yTree } from "./cache/a11y-tree.js";
+import { selectorCache } from "./cache/selector-cache.js";
+import { FreeTierLicenseStatus } from "./license/license-status.js";
+import { loadFreeTierConfig } from "./license/free-tier-config.js";
+import { getProHooks } from "./hooks/pro-hooks.js";
+export async function startServer() {
+    // 1. Connect to Chrome (Story 1.3: WebSocket first, then Auto-Launch)
+    const profilePath = process.env.SILBERCUE_CHROME_PROFILE || undefined;
+    const headlessEnv = process.env.SILBERCUE_CHROME_HEADLESS === "true";
+    const autoLaunch = resolveAutoLaunch(process.env, headlessEnv);
+    const launcher = new ChromeLauncher({ profilePath, headless: headlessEnv, autoLaunch });
+    const connection = await launcher.connect();
+    const { cdpClient } = connection;
+    // Use detected headless from connection (auto-detected from Chrome's /json/version for WebSocket)
+    const headless = connection.headless;
+    setHeadless(headless);
+    if (profilePath) {
+        if (connection.transportType === "pipe") {
+            console.error(`SilbercueChrome using Chrome profile: ${profilePath}`);
+        }
+        else {
+            console.error(`SilbercueChrome warning: profilePath "${profilePath}" ignored — connected via WebSocket to existing Chrome`);
+        }
+    }
+    // 2. Attach to a page target (browser-level connection needs a page session)
+    const { targetInfos } = await cdpClient.send("Target.getTargets");
+    let pageTarget = targetInfos.find((t) => t.type === "page");
+    if (!pageTarget) {
+        const { targetId } = await cdpClient.send("Target.createTarget", {
+            url: "about:blank",
+        });
+        pageTarget = { targetId, type: "page", url: "about:blank" };
+    }
+    const { sessionId } = await cdpClient.send("Target.attachToTarget", {
+        targetId: pageTarget.targetId,
+        flatten: true,
+    });
+    // 3. Activate CDP domains on the page session
+    await cdpClient.send("Runtime.enable", {}, sessionId);
+    await cdpClient.send("Page.enable", {}, sessionId);
+    await cdpClient.send("Page.setLifecycleEventsEnabled", { enabled: true }, sessionId);
+    await cdpClient.send("Accessibility.enable", {}, sessionId);
+    // BUG-015 fix: Keep renderer alive when window is occluded on macOS.
+    // setFocusEmulationEnabled calls WebContents::IncrementCapturerCount(stay_hidden=false),
+    // which keeps visible_capturer_count_ > 0 → renderer stays in kVisible state.
+    if (!headless) {
+        await cdpClient.send("Emulation.setFocusEmulationEnabled", { enabled: true }, sessionId);
+    }
+    if (headless) {
+        await cdpClient.send("Emulation.setDeviceMetricsOverride", DEVICE_METRICS_OVERRIDE, sessionId);
+    }
+    else {
+        // Headed mode: resize browser window instead of emulating viewport.
+        // Emulation.setDeviceMetricsOverride causes a gray bar below the content.
+        try {
+            const { windowId } = await cdpClient.send("Browser.getWindowForTarget", { targetId: pageTarget.targetId });
+            await cdpClient.send("Browser.setWindowBounds", {
+                windowId,
+                bounds: { width: EMULATED_WIDTH, height: EMULATED_HEIGHT + 85 }, // +85 for Chrome UI (tabs, address bar)
+            });
+        }
+        catch {
+            // Fallback to emulation if Browser.setWindowBounds fails (e.g. remote connection)
+            await cdpClient.send("Emulation.setDeviceMetricsOverride", DEVICE_METRICS_OVERRIDE, sessionId);
+        }
+    }
+    // 3b. Inject session overlay (visual indicator for controlled tab)
+    await injectOverlay(cdpClient, sessionId);
+    // 4. Create TabStateCache and attach to CDP events
+    const tabStateCache = new TabStateCache({ ttlMs: 30_000 });
+    tabStateCache.setActiveTarget(pageTarget.targetId);
+    tabStateCache.attachToClient(cdpClient, sessionId);
+    // 4b. Create SessionManager for OOPIF support
+    const sessionManager = new SessionManager(cdpClient, sessionId);
+    // H1: Wire up OOPIF detach callback to clean A11yTreeProcessor ref-maps
+    sessionManager.onOopifDetach((detachedSessionId) => {
+        a11yTree.removeNodesForSession(detachedSessionId);
+    });
+    await sessionManager.init();
+    // 4c. Create DialogHandler for automatic dialog handling (Story 6.1)
+    const dialogHandler = new DialogHandler(cdpClient, sessionId);
+    dialogHandler.init();
+    // 4d. Create ConsoleCollector for console log buffering (Story 7.1)
+    const consoleCollector = new ConsoleCollector(cdpClient, sessionId);
+    consoleCollector.init();
+    // 4e. Create NetworkCollector for network request monitoring (Story 7.2)
+    // NOT started here — on-demand via action: "start"
+    const networkCollector = new NetworkCollector(cdpClient, sessionId);
+    // 4f. Create SessionDefaults for session parameter defaults (Story 7.3)
+    const sessionDefaults = new SessionDefaults();
+    // 4g. Create DomWatcher for precomputed A11y-Tree (Story 7.4)
+    const domWatcher = new DomWatcher(cdpClient, sessionId, { debounceMs: 500 });
+    domWatcher.onRefresh(async () => {
+        await a11yTree.refreshPrecomputed(cdpClient, sessionId, sessionManager);
+        // Update selector cache fingerprint after tree refresh (Story 7.5)
+        const urlResult = await cdpClient.send("Runtime.evaluate", { expression: "document.URL", returnByValue: true }, sessionId);
+        const fp = selectorCache.computeFingerprint(urlResult.result.value, a11yTree.refCount);
+        selectorCache.updateFingerprint(fp);
+    });
+    domWatcher.onInvalidate(() => {
+        a11yTree.invalidatePrecomputed();
+        // H2 fix: Invalidate selector cache on navigation (not on every DOM mutation).
+        // DOM mutations use fingerprint mismatch for self-healing instead.
+        selectorCache.invalidate();
+    });
+    // BUG-010: Invalidate precomputed A11y-tree immediately on DOM mutations
+    // (selector cache uses fingerprint self-healing, so only A11y cache needs immediate invalidation)
+    domWatcher.onMutationInvalidate(() => {
+        a11yTree.invalidatePrecomputed();
+    });
+    await domWatcher.init();
+    // 6. Create MCP server and register tools
+    const server = new McpServer({
+        name: "silbercuechrome",
+        version: "0.1.0",
+    }, {
+        instructions: [
+            "SilbercueChrome controls a real Chrome browser via CDP.",
+            "",
+            "Workflow: virtual_desk → switch_tab (or navigate) → read_page → click/type/fill_form using refs.",
+            "",
+            "Token-efficiency rules:",
+            "- read_page (accessibility tree with refs like 'e5') is 10-30x cheaper than screenshot.",
+            "- Screenshots CANNOT drive click/type — only read_page returns usable element refs.",
+            "- fill_form beats multiple type calls for any form with 2+ fields.",
+            "- evaluate is a last resort — prefer read_page, click, type, fill_form, observe.",
+        ].join("\n"),
+    });
+    // Story 15.5: License status via ProHooks (Pro-Repo injiziert LicenseValidator)
+    const hooks = getProHooks();
+    let licenseStatus = new FreeTierLicenseStatus();
+    if (hooks.provideLicenseStatus) {
+        try {
+            licenseStatus = await hooks.provideLicenseStatus();
+        }
+        catch {
+            // Fallback to Free Tier
+        }
+    }
+    const freeTierConfig = loadFreeTierConfig();
+    // Set overlay tier label and license info
+    setTierLabel(licenseStatus.isPro());
+    setLicenseInfo(undefined, undefined, undefined);
+    // Story 13a.2: Pass waitForAXChange callback to Registry for post-click detection
+    const registry = new ToolRegistry(server, cdpClient, sessionId, tabStateCache, () => connection.status, sessionManager, dialogHandler, licenseStatus, freeTierConfig, consoleCollector, networkCollector, sessionDefaults, (ms) => domWatcher.waitForAXChange(ms));
+    registry.registerAll();
+    // 5. Register reconnect handler for automatic re-wiring (Story 5.2)
+    // H1 fix: Registered AFTER registry creation to avoid TDZ reference
+    connection.onReconnect(async (reconn) => {
+        const newCdpClient = reconn.cdpClient;
+        // 1. Attach to page target (same as initial startup)
+        const { targetInfos: newTargets } = await newCdpClient.send("Target.getTargets");
+        let newPageTarget = newTargets.find((t) => t.type === "page");
+        if (!newPageTarget) {
+            const { targetId } = await newCdpClient.send("Target.createTarget", { url: "about:blank" });
+            newPageTarget = { targetId, type: "page", url: "about:blank" };
+        }
+        const { sessionId: newSessionId } = await newCdpClient.send("Target.attachToTarget", {
+            targetId: newPageTarget.targetId,
+            flatten: true,
+        });
+        // 2. Enable CDP domains on the new session
+        await newCdpClient.send("Runtime.enable", {}, newSessionId);
+        await newCdpClient.send("Page.enable", {}, newSessionId);
+        await newCdpClient.send("Page.setLifecycleEventsEnabled", { enabled: true }, newSessionId);
+        await newCdpClient.send("Accessibility.enable", {}, newSessionId);
+        // BUG-015 fix: Keep renderer alive on reconnect (same as initial setup)
+        if (!headless) {
+            await newCdpClient.send("Emulation.setFocusEmulationEnabled", { enabled: true }, newSessionId);
+        }
+        if (headless) {
+            await newCdpClient.send("Emulation.setDeviceMetricsOverride", DEVICE_METRICS_OVERRIDE, newSessionId);
+        }
+        // 2b. Re-inject session overlay after reconnect
+        await injectOverlay(newCdpClient, newSessionId);
+        // 3. Re-wire TabStateCache: detach from old, attach to new
+        tabStateCache.detachFromClient();
+        tabStateCache.setActiveTarget(newPageTarget.targetId);
+        tabStateCache.attachToClient(newCdpClient, newSessionId);
+        // 4. Re-wire ToolRegistry
+        registry.updateClient(newCdpClient, newSessionId);
+        // 5. Re-initialize SessionManager for OOPIF support
+        await sessionManager.reinit(newCdpClient, newSessionId);
+        // 6. Re-initialize DialogHandler for dialog handling
+        dialogHandler.reinit(newCdpClient, newSessionId);
+        // 7. Re-initialize ConsoleCollector for console log buffering
+        consoleCollector.reinit(newCdpClient, newSessionId);
+        // 8. Re-initialize NetworkCollector for network request monitoring
+        networkCollector.reinit(newCdpClient, newSessionId);
+        // 9. Re-initialize DomWatcher for precomputed A11y-Tree (Story 7.4)
+        // H3: Rebind callbacks BEFORE reinit() to avoid race condition where
+        // reinit()->init() fires events that invoke stale closures
+        a11yTree.invalidatePrecomputed();
+        // 10. Invalidate SelectorCache on reconnect (Story 7.5)
+        selectorCache.invalidate();
+        domWatcher.onRefresh(async () => {
+            await a11yTree.refreshPrecomputed(newCdpClient, newSessionId, sessionManager);
+            // Update selector cache fingerprint after tree refresh (Story 7.5)
+            const urlResult = await newCdpClient.send("Runtime.evaluate", { expression: "document.URL", returnByValue: true }, newSessionId);
+            const fp = selectorCache.computeFingerprint(urlResult.result.value, a11yTree.refCount);
+            selectorCache.updateFingerprint(fp);
+        });
+        domWatcher.onInvalidate(() => {
+            a11yTree.invalidatePrecomputed();
+            selectorCache.invalidate();
+        });
+        // BUG-010: Rebind mutation invalidation callback on reconnect
+        domWatcher.onMutationInvalidate(() => {
+            a11yTree.invalidatePrecomputed();
+        });
+        await domWatcher.reinit(newCdpClient, newSessionId);
+    });
+    // 7. Start stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("SilbercueChrome MCP server running on stdio");
+    // 8. Graceful shutdown
+    const shutdown = async () => {
+        await removeOverlay(cdpClient, sessionId).catch(() => { });
+        domWatcher.detach();
+        networkCollector.detach();
+        consoleCollector.detach();
+        dialogHandler.detach();
+        sessionManager.detach();
+        tabStateCache.detachFromClient();
+        await server.close();
+        await connection.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}

package/build/tools/click.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import type { CdpClient } from "../cdp/cdp-client.js";
+import type { SessionManager } from "../cdp/session-manager.js";
+import type { ToolResponse } from "../types.js";
+export declare const clickSchema: z.ZodObject<{
+    ref: z.ZodOptional<z.ZodString>;
+    selector: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+    x: z.ZodOptional<z.ZodNumber>;
+    y: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    text?: string | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    ref?: string | undefined;
+    selector?: string | undefined;
+}, {
+    text?: string | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    ref?: string | undefined;
+    selector?: string | undefined;
+}>;
+export type ClickParams = z.infer<typeof clickSchema>;
+export type ClickMethod = "cdp" | "js-rect" | "js-click" | "coordinates";
+/**
+ * Story 16.5: Optional human-mouse-move callback injected via the
+ * `enhanceTool` Pro-Hook. When present, this replaces the raw
+ * `Input.dispatchMouseEvent("mouseMoved",...)` with a Bezier-curve mouse
+ * movement from the Pro-Repo Human Touch module. The Free-Repo does NOT
+ * contain any Human-Touch logic — it only knows how to delegate.
+ */
+export type HumanMouseMoveFn = (cdpClient: CdpClient, sessionId: string, fromX: number, fromY: number, toX: number, toY: number) => Promise<void>;
+export declare function clickHandler(params: ClickParams, cdpClient: CdpClient, sessionId?: string, sessionManager?: SessionManager): Promise<ToolResponse>;

package/build/tools/click.js

@@ -0,0 +1,293 @@
+import { z } from "zod";
+import { resolveElement, buildRefNotFoundError, RefNotFoundError } from "./element-utils.js";
+import { wrapCdpError } from "./error-utils.js";
+import { a11yTree } from "../cache/a11y-tree.js";
+import { isHeadless } from "../cdp/emulation.js";
+// --- Schema (Task 2) ---
+export const clickSchema = z.object({
+    ref: z
+        .string()
+        .optional()
+        .describe("A11y-Tree element ref (e.g. 'e5') — preferred over selector"),
+    selector: z
+        .string()
+        .optional()
+        .describe("CSS selector (e.g. '#submit-btn') — fallback when ref is not available"),
+    text: z
+        .string()
+        .optional()
+        .describe("Visible text to match (e.g. 'Submit'). Finds element by name in the A11y tree — no prior read_page needed. Prefers interactive elements (buttons, links)."),
+    x: z
+        .number()
+        .optional()
+        .describe("X coordinate (viewport pixels) — for canvas or pixel-precise clicks. Use with y instead of ref/selector."),
+    y: z
+        .number()
+        .optional()
+        .describe("Y coordinate (viewport pixels) — for canvas or pixel-precise clicks. Use with x instead of ref/selector."),
+});
+async function dispatchClick(cdpClient, sessionId, backendNodeId, objectId, humanMouseMove) {
+    // Step 1: Reset scroll to origin before clicking.
+    // When Emulation.setDeviceMetricsOverride is active, Input.dispatchMouseEvent
+    // hit-tests at document coordinates (viewport + scrollY) instead of viewport
+    // coordinates. Scrolling to 0 ensures viewport coords = document coords.
+    await cdpClient.send("Runtime.evaluate", { expression: "window.scrollTo(0,0)" }, sessionId);
+    // Step 2: Scroll element into view (from scroll 0)
+    await cdpClient.send("DOM.scrollIntoViewIfNeeded", { backendNodeId }, sessionId);
+    // Step 3: Get viewport-relative center — try getContentQuads, fallback chain
+    let x;
+    let y;
+    let clickMethod = "cdp";
+    try {
+        const quadsResult = await cdpClient.send("DOM.getContentQuads", { backendNodeId }, sessionId);
+        if (!quadsResult.quads || quadsResult.quads.length === 0) {
+            throw new Error("Element has no visible layout quads");
+        }
+        // Quad is [x1,y1, x2,y2, x3,y3, x4,y4] — average all 4 corners for center
+        const q = quadsResult.quads[0];
+        x = (q[0] + q[2] + q[4] + q[6]) / 4;
+        y = (q[1] + q[3] + q[5] + q[7]) / 4;
+    }
+    catch {
+        // Fallback 1: getBoundingClientRect via Runtime.callFunctionOn
+        // Handles Shadow-DOM nodes and post-mutation stale layouts (BUG-005, BUG-007, BUG-012)
+        try {
+            const rectResult = await cdpClient.send("Runtime.callFunctionOn", {
+                functionDeclaration: `function() {
+            var rect = this.getBoundingClientRect();
+            return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+          }`,
+                objectId,
+                returnByValue: true,
+            }, sessionId);
+            x = rectResult.result.value.x;
+            y = rectResult.result.value.y;
+            clickMethod = "js-rect";
+        }
+        catch {
+            // Fallback 2: Pure JS click — no coordinates needed
+            await cdpClient.send("Runtime.callFunctionOn", {
+                functionDeclaration: `function() { this.click(); }`,
+                objectId,
+                returnByValue: false,
+            }, sessionId);
+            return { method: "js-click", x: 0, y: 0 };
+        }
+    }
+    // Step 4: Dispatch mouse events — mouseMoved → mousePressed → mouseReleased
+    // mouseMoved establishes mouseenter/mouseover context (BUG-002)
+    // Story 16.5: If humanMouseMove callback is injected (via Pro-Hook),
+    // delegate the mouse-move sequence to it. Otherwise: raw CDP dispatch.
+    if (humanMouseMove) {
+        await humanMouseMove(cdpClient, sessionId, 0, 0, x, y);
+    }
+    else {
+        await cdpClient.send("Input.dispatchMouseEvent", { type: "mouseMoved", x, y, button: "none", buttons: 0 }, sessionId);
+    }
+    await cdpClient.send("Input.dispatchMouseEvent", { type: "mousePressed", x, y, button: "left", buttons: 1, clickCount: 1 }, sessionId);
+    await cdpClient.send("Input.dispatchMouseEvent", { type: "mouseReleased", x, y, button: "left", buttons: 0, clickCount: 1 }, sessionId);
+    return { method: clickMethod, x, y };
+}
+// --- Main handler (Task 6) ---
+export async function clickHandler(params, cdpClient, sessionId, sessionManager) {
+    const start = performance.now();
+    // Story 16.5: Extract optional humanMouseMove callback injected by the
+    // `enhanceTool` Pro-Hook. The field is NOT part of the Zod schema — it is
+    // read from the raw params map via type-guard and stripped from the params
+    // object before downstream code uses it (so it never leaks into CDP calls
+    // or schema-validation paths).
+    const rawParams = params;
+    const maybeHuman = rawParams.humanMouseMove;
+    const humanMouseMove = typeof maybeHuman === "function" ? maybeHuman : undefined;
+    if ("humanMouseMove" in rawParams) {
+        const { humanMouseMove: _humanMouseMove, ...rest } = rawParams;
+        void _humanMouseMove;
+        params = rest;
+    }
+    // FR-D: Coordinate-based click — skip element resolution entirely
+    if (params.x !== undefined && params.y !== undefined) {
+        try {
+            const x = params.x;
+            const y = params.y;
+            // Snapshot tab count before click (FR-E: new tab detection)
+            let beforeTabIds;
+            try {
+                const { targetInfos } = await cdpClient.send("Target.getTargets");
+                beforeTabIds = new Set(targetInfos.filter(t => t.type === "page").map(t => t.targetId));
+            }
+            catch { /* non-critical */ }
+            // FR-01: Auto-scroll + headless adjustment in a single atomic evaluate.
+            // If coordinates exceed viewport dimensions, the LLM passed document/page
+            // coordinates (e.g. from a full_page screenshot). Scroll to center the target,
+            // then return the final scroll position for coordinate adjustment.
+            const snap = await cdpClient.send("Runtime.evaluate", {
+                expression: `((x,y)=>{const w=window.innerWidth,h=window.innerHeight,oob=x<0||y<0||x>=w||y>=h;if(oob)window.scrollTo(Math.max(0,x-Math.round(w/2)),Math.max(0,y-Math.round(h/2)));return{sx:Math.round(window.scrollX),sy:Math.round(window.scrollY),w,h,oob}})(${x},${y})`,
+                returnByValue: true,
+            }, sessionId);
+            const { sx, sy, w: vw, h: vh, oob: autoScrolled } = snap.result.value;
+            // Viewport-relative coordinates (subtract scroll offset applied by auto-scroll)
+            const viewportX = autoScrolled ? x - sx : x;
+            const viewportY = autoScrolled ? y - sy : y;
+            // FR-01 fallback: if viewport coords are still out of bounds after scroll
+            // (page shorter than expected, overflow:hidden, etc.), warn immediately.
+            if (autoScrolled && (viewportX < 0 || viewportY < 0 || viewportX >= vw || viewportY >= vh)) {
+                const elapsedMs = Math.round(performance.now() - start);
+                return {
+                    content: [{ type: "text", text: `click at (${x}, ${y}) failed: coordinates are outside page bounds (page scrolled to ${sy}px but target is at ${y}px). The page may be shorter than expected — use read_page or screenshot to verify element positions.` }],
+                    isError: true,
+                    _meta: { elapsedMs, method: "click", clickMethod: "coordinates", autoScrolled },
+                };
+            }
+            // FR-H: Headless mode — Emulation.setDeviceMetricsOverride causes hit-testing
+            // at document coords, so add scroll offset to convert viewport → document space.
+            let dispatchX = viewportX;
+            let dispatchY = viewportY;
+            if (isHeadless()) {
+                dispatchX += sx;
+                dispatchY += sy;
+            }
+            // Dispatch mouse events at coordinates via CDP
+            // Story 16.5: If humanMouseMove callback is injected, delegate the move.
+            if (humanMouseMove) {
+                await humanMouseMove(cdpClient, sessionId, 0, 0, dispatchX, dispatchY);
+            }
+            else {
+                await cdpClient.send("Input.dispatchMouseEvent", { type: "mouseMoved", x: dispatchX, y: dispatchY, button: "none", buttons: 0 }, sessionId);
+            }
+            await cdpClient.send("Input.dispatchMouseEvent", { type: "mousePressed", x: dispatchX, y: dispatchY, button: "left", buttons: 1, clickCount: 1 }, sessionId);
+            await cdpClient.send("Input.dispatchMouseEvent", { type: "mouseReleased", x: dispatchX, y: dispatchY, button: "left", buttons: 0, clickCount: 1 }, sessionId);
+            // FR-E: Check for new tabs after click
+            const newTabHint = await detectNewTab(cdpClient, beforeTabIds);
+            const elapsedMs = Math.round(performance.now() - start);
+            const scrollHint = autoScrolled ? ` (auto-scrolled from page position)` : "";
+            return {
+                content: [{ type: "text", text: `Clicked at (${x}, ${y})${scrollHint}${newTabHint}` }],
+                _meta: { elapsedMs, method: "click", clickMethod: "coordinates", autoScrolled },
+            };
+        }
+        catch (err) {
+            const elapsedMs = Math.round(performance.now() - start);
+            return {
+                content: [{ type: "text", text: wrapCdpError(err, "click", `(${params.x}, ${params.y})`) }],
+                isError: true,
+                _meta: { elapsedMs, method: "click" },
+            };
+        }
+    }
+    // UX-001: Resolve text to ref before validation
+    if (params.text && !params.ref && !params.selector) {
+        // Ensure a11y tree is populated — fetch fresh if needed
+        if (!a11yTree.hasRefs()) {
+            try {
+                await a11yTree.getTree(cdpClient, sessionId, { depth: 3, filter: "interactive", fresh: true }, sessionManager);
+            }
+            catch { /* best-effort — findByText will return null */ }
+        }
+        const match = a11yTree.findByText(params.text);
+        if (match) {
+            params.ref = match.ref;
+        }
+        else {
+            const elements = a11yTree.getInteractiveElements(8);
+            const hint = elements.length > 0
+                ? "\nAvailable interactive elements:\n  " + elements.join("\n  ")
+                : "\nNo interactive elements found — try read_page first.";
+            return {
+                content: [{ type: "text", text: `No element found with text "${params.text}".${hint}` }],
+                isError: true,
+                _meta: { elapsedMs: Math.round(performance.now() - start), method: "click" },
+            };
+        }
+    }
+    // Validation (Task 2.4)
+    if (!params.ref && !params.selector) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "click requires either 'ref' (e.g. 'e5'), 'selector' (e.g. '#submit-btn'), 'text' (e.g. 'Submit'), or coordinates (x + y)",
+                },
+            ],
+            isError: true,
+            _meta: { elapsedMs: 0, method: "click" },
+        };
+    }
+    try {
+        // FR-E: Snapshot tab count before click (new tab detection)
+        let beforeTabIds;
+        try {
+            const { targetInfos } = await cdpClient.send("Target.getTargets");
+            beforeTabIds = new Set(targetInfos.filter(t => t.type === "page").map(t => t.targetId));
+        }
+        catch { /* non-critical */ }
+        // Resolve element via shared utility (with OOPIF routing)
+        const target = params.ref ? { ref: params.ref } : { selector: params.selector };
+        const element = await resolveElement(cdpClient, sessionId, target, sessionManager);
+        // Dispatch click using the resolved session (may be OOPIF or main)
+        const clickResult = await dispatchClick(cdpClient, element.resolvedSessionId, element.backendNodeId, element.objectId, humanMouseMove);
+        // FR-E: Check for new tabs after click
+        const newTabHint = await detectNewTab(cdpClient, beforeTabIds);
+        // Story 13a.2: Classify clicked element for ambient context decision
+        const elementClass = params.ref ? a11yTree.classifyRef(params.ref) : "clickable";
+        const elapsedMs = Math.round(performance.now() - start);
+        const suffix = clickResult.method !== "cdp" ? `, fallback: ${clickResult.method}` : "";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Clicked ${params.ref ?? params.selector} (${element.resolvedVia}${suffix})${newTabHint}`,
+                },
+            ],
+            _meta: {
+                elapsedMs,
+                method: "click",
+                resolvedVia: element.resolvedVia,
+                clickMethod: clickResult.method,
+                clickX: clickResult.x,
+                clickY: clickResult.y,
+                elementClass,
+            },
+        };
+    }
+    catch (err) {
+        if (err instanceof RefNotFoundError && params.ref) {
+            const errorText = buildRefNotFoundError(params.ref);
+            return {
+                content: [{ type: "text", text: errorText }],
+                isError: true,
+                _meta: { elapsedMs: 0, method: "click" },
+            };
+        }
+        const elapsedMs = Math.round(performance.now() - start);
+        const elementHint = params.ref ?? params.selector;
+        let errorText = wrapCdpError(err, "click", elementHint);
+        // FR-008: When CSS selector not found, suggest available interactive elements
+        const message = err instanceof Error ? err.message : String(err);
+        if (params.selector && message.includes("Element not found for selector")) {
+            const elements = a11yTree.getInteractiveElements(8);
+            if (elements.length > 0) {
+                errorText += "\nAvailable interactive elements:\n  " + elements.join("\n  ");
+            }
+        }
+        return {
+            content: [{ type: "text", text: errorText }],
+            isError: true,
+            _meta: { elapsedMs, method: "click" },
+        };
+    }
+}
+// --- FR-E: New tab detection ---
+async function detectNewTab(cdpClient, beforeTabIds) {
+    if (!beforeTabIds)
+        return "";
+    try {
+        const { targetInfos } = await cdpClient.send("Target.getTargets");
+        const newTabs = targetInfos.filter(t => t.type === "page" && !beforeTabIds.has(t.targetId));
+        if (newTabs.length > 0) {
+            const tab = newTabs[0];
+            return `\n⮕ New tab opened: ${tab.url || "about:blank"} — use switch_tab to access it`;
+        }
+    }
+    catch { /* non-critical */ }
+    return "";
+}

package/build/tools/configure-session.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import type { SessionDefaults } from "../cache/session-defaults.js";
+import type { ToolResponse } from "../types.js";
+export declare const configureSessionSchema: z.ZodObject<{
+    defaults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    autoPromote: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    defaults?: Record<string, unknown> | undefined;
+    autoPromote?: boolean | undefined;
+}, {
+    defaults?: Record<string, unknown> | undefined;
+    autoPromote?: boolean | undefined;
+}>;
+export type ConfigureSessionParams = z.infer<typeof configureSessionSchema>;
+export declare function configureSessionHandler(params: ConfigureSessionParams, sessionDefaults: SessionDefaults): Promise<ToolResponse>;

package/build/tools/configure-session.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+export const configureSessionSchema = z.object({
+    defaults: z.record(z.unknown())
+        .optional()
+        .describe("Set session defaults. Keys: param names (tab, timeout, etc.). Values: default values. null removes a default."),
+    autoPromote: z.boolean()
+        .optional()
+        .describe("If true, apply all current auto-promote suggestions as defaults"),
+});
+export async function configureSessionHandler(params, sessionDefaults) {
+    const start = performance.now();
+    // H4 fix: Process defaults and autoPromote independently (no early return)
+    let applied;
+    // defaults gesetzt → Defaults aktualisieren
+    if (params.defaults) {
+        for (const [key, value] of Object.entries(params.defaults)) {
+            sessionDefaults.setDefault(key, value);
+        }
+    }
+    // autoPromote: true → alle Vorschlaege als Defaults uebernehmen
+    if (params.autoPromote) {
+        applied = sessionDefaults.applyAllSuggestions();
+    }
+    // Build response based on what was requested
+    if (params.defaults !== undefined || params.autoPromote) {
+        const payload = {
+            defaults: sessionDefaults.getAllDefaults(),
+        };
+        if (applied !== undefined) {
+            payload.applied = applied;
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(payload) }],
+            _meta: { elapsedMs: Math.round(performance.now() - start), method: "configure_session" },
+        };
+    }
+    // Keine Parameter → aktuelle Defaults + Vorschlaege abfragen
+    return {
+        content: [{ type: "text", text: JSON.stringify({
+                    defaults: sessionDefaults.getAllDefaults(),
+                    autoPromote: sessionDefaults.getSuggestions(),
+                }) }],
+        _meta: { elapsedMs: Math.round(performance.now() - start), method: "configure_session" },
+    };
+}

package/build/tools/console-logs.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { ConsoleCollector } from "../cdp/console-collector.js";
+import type { ToolResponse } from "../types.js";
+export declare const consoleLogsSchema: z.ZodObject<{
+    level: z.ZodOptional<z.ZodEnum<["info", "warning", "error", "debug"]>>;
+    pattern: z.ZodOptional<z.ZodString>;
+    clear: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    clear: boolean;
+    level?: "error" | "info" | "warning" | "debug" | undefined;
+    pattern?: string | undefined;
+}, {
+    level?: "error" | "info" | "warning" | "debug" | undefined;
+    clear?: boolean | undefined;
+    pattern?: string | undefined;
+}>;
+export type ConsoleLogsParams = z.infer<typeof consoleLogsSchema>;
+export declare function consoleLogsHandler(params: ConsoleLogsParams, consoleCollector: ConsoleCollector): Promise<ToolResponse>;