@silbercue/chrome 0.2.0

package/build/tools/console-logs.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+export const consoleLogsSchema = z.object({
+    level: z.enum(["info", "warning", "error", "debug"])
+        .optional()
+        .describe("Filter by log level"),
+    pattern: z.string()
+        .optional()
+        .describe("Regex pattern to match against log text"),
+    clear: z.boolean()
+        .optional()
+        .default(false)
+        .describe("Clear the log buffer after returning results"),
+});
+export async function consoleLogsHandler(params, consoleCollector) {
+    const start = performance.now();
+    // 1. Retrieve logs (filtered or all)
+    let logs;
+    try {
+        logs = (params.level || params.pattern)
+            ? consoleCollector.getFiltered(params.level, params.pattern)
+            : consoleCollector.getAll();
+    }
+    catch (err) {
+        // Invalid regex pattern
+        return {
+            content: [{ type: "text", text: `Invalid regex pattern: ${err.message}` }],
+            isError: true,
+            _meta: { elapsedMs: Math.round(performance.now() - start), method: "console_logs" },
+        };
+    }
+    // 2. Clear buffer after retrieval if requested
+    if (params.clear) {
+        consoleCollector.clear();
+    }
+    // 3. Return logs as JSON array
+    return {
+        content: [{ type: "text", text: JSON.stringify(logs) }],
+        _meta: {
+            elapsedMs: Math.round(performance.now() - start),
+            method: "console_logs",
+            count: logs.length,
+        },
+    };
+}

package/build/tools/dom-snapshot.d.ts

@@ -0,0 +1,13 @@
+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 domSnapshotSchema: z.ZodObject<{
+    ref: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    ref?: string | undefined;
+}, {
+    ref?: string | undefined;
+}>;
+export type DomSnapshotParams = z.infer<typeof domSnapshotSchema>;
+export declare function domSnapshotHandler(params: DomSnapshotParams, cdpClient: CdpClient, sessionId?: string, sessionManager?: SessionManager): Promise<ToolResponse>;

package/build/tools/dom-snapshot.js

@@ -0,0 +1,259 @@
+import { z } from "zod";
+import { a11yTree } from "../cache/a11y-tree.js";
+import { wrapCdpError } from "./error-utils.js";
+import { EMULATED_WIDTH, EMULATED_HEIGHT } from "../cdp/emulation.js";
+import { CLICKABLE_TAGS, CLICKABLE_ROLES, COMPUTED_STYLES } from "./visual-constants.js";
+// --- Schema ---
+export const domSnapshotSchema = z.object({
+    ref: z
+        .string()
+        .optional()
+        .describe("Element ref (e.g. 'e42') to get subtree snapshot for"),
+});
+// --- Constants ---
+const INTERACTIVE_TAGS = new Set([
+    "A", "BUTTON", "INPUT", "SELECT", "TEXTAREA",
+    "IMG", "H1", "H2", "H3", "H4", "H5", "H6", "LABEL",
+]);
+const INTERACTIVE_ROLES = new Set([
+    "button", "link", "checkbox", "tab", "menuitem",
+    "radio", "switch", "slider", "option", "treeitem",
+    "textbox", "searchbox", "combobox", "spinbutton",
+    "menuitemcheckbox", "menuitemradio",
+]);
+const MAX_ELEMENTS = 150;
+const MIN_SIZE = 10;
+// --- Helpers ---
+function getStringAt(strings, index) {
+    if (index < 0 || index >= strings.length)
+        return "";
+    return strings[index];
+}
+function extractRole(attributes, strings) {
+    // attributes = [nameIdx, valueIdx, nameIdx, valueIdx, ...]
+    for (let i = 0; i < attributes.length - 1; i += 2) {
+        if (getStringAt(strings, attributes[i]) === "role") {
+            return getStringAt(strings, attributes[i + 1]);
+        }
+    }
+    return "";
+}
+function hasExplicitRole(attributes, strings) {
+    for (let i = 0; i < attributes.length - 1; i += 2) {
+        if (getStringAt(strings, attributes[i]) === "role")
+            return true;
+    }
+    return false;
+}
+// --- Handler ---
+export async function domSnapshotHandler(params, cdpClient, sessionId, sessionManager) {
+    const start = performance.now();
+    const method = "dom_snapshot";
+    try {
+        // Ensure A11y refs exist — only trigger getTree if it has never been loaded
+        if (!a11yTree.hasRefs()) {
+            try {
+                await a11yTree.getTree(cdpClient, sessionId, {}, sessionManager);
+            }
+            catch {
+                // Non-fatal: proceed without refs if a11y tree fetch fails
+            }
+        }
+        // CDP call
+        const snapshot = await cdpClient.send("DOMSnapshot.captureSnapshot", {
+            computedStyles: [...COMPUTED_STYLES],
+            includeDOMRects: true,
+            includeBlendedBackgroundColors: true,
+            includePaintOrder: true,
+        }, sessionId);
+        if (!snapshot.documents || snapshot.documents.length === 0) {
+            const elapsedMs = Math.round(performance.now() - start);
+            return {
+                content: [{ type: "text", text: "[]" }],
+                _meta: { elapsedMs, method, elementCount: 0, filteredFrom: 0 },
+            };
+        }
+        const doc = snapshot.documents[0];
+        const strings = snapshot.strings;
+        const totalNodes = doc.nodes.backendNodeId.length;
+        // Resolve subtree constraint if ref is given
+        let subtreeAncestorIndex;
+        let subtreeDescendants;
+        if (params.ref) {
+            const targetBackendNodeId = a11yTree.resolveRef(params.ref);
+            if (targetBackendNodeId === undefined) {
+                const elapsedMs = Math.round(performance.now() - start);
+                return {
+                    content: [{ type: "text", text: `Element ${params.ref} not found.` }],
+                    isError: true,
+                    _meta: { elapsedMs, method },
+                };
+            }
+            // Find the node index for this backendNodeId
+            for (let i = 0; i < doc.nodes.backendNodeId.length; i++) {
+                if (doc.nodes.backendNodeId[i] === targetBackendNodeId) {
+                    subtreeAncestorIndex = i;
+                    break;
+                }
+            }
+            if (subtreeAncestorIndex === undefined) {
+                const elapsedMs = Math.round(performance.now() - start);
+                return {
+                    content: [{ type: "text", text: `Element ${params.ref} not found in DOM snapshot.` }],
+                    isError: true,
+                    _meta: { elapsedMs, method },
+                };
+            }
+            // Collect all descendants via parent→children index, then BFS
+            const childrenOf = new Map();
+            for (let i = 0; i < doc.nodes.parentIndex.length; i++) {
+                const parent = doc.nodes.parentIndex[i];
+                if (parent < 0)
+                    continue;
+                let children = childrenOf.get(parent);
+                if (!children) {
+                    children = [];
+                    childrenOf.set(parent, children);
+                }
+                children.push(i);
+            }
+            subtreeDescendants = new Set();
+            const queue = [subtreeAncestorIndex];
+            while (queue.length > 0) {
+                const idx = queue.pop();
+                subtreeDescendants.add(idx);
+                const kids = childrenOf.get(idx);
+                if (kids) {
+                    for (const kid of kids)
+                        queue.push(kid);
+                }
+            }
+        }
+        // Build layout index map: nodeIndex → layoutIndex
+        const layoutMap = new Map();
+        for (let li = 0; li < doc.layout.nodeIndex.length; li++) {
+            layoutMap.set(doc.layout.nodeIndex[li], li);
+        }
+        // --- 6-Stage Filter Pipeline ---
+        const pipeline = [];
+        for (let ni = 0; ni < totalNodes; ni++) {
+            // Subtree filter: skip nodes not in subtree
+            if (subtreeDescendants && !subtreeDescendants.has(ni))
+                continue;
+            // Stage 1: Simplification — tag whitelist + explicit role
+            const tag = getStringAt(strings, doc.nodes.nodeName[ni]);
+            const attrs = doc.nodes.attributes[ni] ?? [];
+            const role = extractRole(attrs, strings);
+            if (!INTERACTIVE_TAGS.has(tag) && !hasExplicitRole(attrs, strings) && !INTERACTIVE_ROLES.has(role)) {
+                continue;
+            }
+            // Must have layout data
+            const li = layoutMap.get(ni);
+            if (li === undefined)
+                continue;
+            // Stage 2: Visibility Filter
+            const styleProps = doc.layout.styles[li] ?? [];
+            // computedStyles order matches COMPUTED_STYLES: display, visibility, color, bg-color, font-size, position, z-index
+            const displayVal = getStringAt(strings, styleProps[0]);
+            const visibilityVal = getStringAt(strings, styleProps[1]);
+            if (displayVal === "none" || visibilityVal === "hidden")
+                continue;
+            // Stage 3: BBox Filter
+            const boundsArr = doc.layout.bounds[li];
+            if (!boundsArr || boundsArr.length < 4)
+                continue;
+            const [x, y, w, h] = boundsArr;
+            if (w < 1 || h < 1)
+                continue;
+            if (x + w < 0 || y + h < 0 || x > EMULATED_WIDTH || y > EMULATED_HEIGHT)
+                continue;
+            // Stage 4: Size Filter (skip for explicitly requested ref subtree root)
+            const isSubtreeRoot = subtreeAncestorIndex !== undefined && ni === subtreeAncestorIndex;
+            if (!isSubtreeRoot && (w < MIN_SIZE || h < MIN_SIZE))
+                continue;
+            // Stage 5: Ref assignment
+            const backendNodeId = doc.nodes.backendNodeId[ni];
+            const ref = a11yTree.getRefForBackendNodeId(backendNodeId);
+            if (!ref)
+                continue;
+            // Get a11y node info for name
+            const nodeInfo = a11yTree.getNodeInfo(backendNodeId);
+            // Collect styles
+            const colorVal = getStringAt(strings, styleProps[2]);
+            const bgColorVal = getStringAt(strings, styleProps[3]);
+            const fontSizeVal = getStringAt(strings, styleProps[4]);
+            // styleProps[5] = position, styleProps[6] = z-index
+            const zIndexVal = getStringAt(strings, styleProps[6]);
+            const styles = {};
+            if (colorVal)
+                styles.color = colorVal;
+            if (bgColorVal)
+                styles.bg = bgColorVal;
+            if (fontSizeVal)
+                styles.fontSize = fontSizeVal;
+            // isClickable heuristic (Task 4)
+            const isClickable = CLICKABLE_TAGS.has(tag) || CLICKABLE_ROLES.has(role);
+            const paintOrder = doc.layout.paintOrders[li] ?? 0;
+            const zIndex = (zIndexVal && zIndexVal !== "auto") ? parseInt(zIndexVal, 10) : null;
+            pipeline.push({
+                nodeIndex: ni,
+                layoutIndex: li,
+                tag: tag.toLowerCase(),
+                role: role || (nodeInfo?.role ?? ""),
+                name: nodeInfo?.name ?? "",
+                ref,
+                bounds: {
+                    x: Math.round(x),
+                    y: Math.round(y),
+                    w: Math.round(w),
+                    h: Math.round(h),
+                },
+                styles,
+                isClickable,
+                paintOrder,
+                zIndex,
+            });
+        }
+        // Stage 6: Token Budget Guard
+        let elements = pipeline;
+        if (elements.length > MAX_ELEMENTS) {
+            // Prioritize interactive elements, then by paintOrder
+            elements.sort((a, b) => {
+                if (a.isClickable !== b.isClickable)
+                    return a.isClickable ? -1 : 1;
+                return b.paintOrder - a.paintOrder;
+            });
+            elements = elements.slice(0, MAX_ELEMENTS);
+        }
+        // Format compact output
+        const output = elements.map((el) => ({
+            ref: el.ref,
+            tag: el.tag,
+            role: el.role,
+            name: el.name,
+            bounds: el.bounds,
+            styles: el.styles,
+            isClickable: el.isClickable,
+            paintOrder: el.paintOrder,
+            zIndex: el.zIndex,
+        }));
+        const elapsedMs = Math.round(performance.now() - start);
+        return {
+            content: [{ type: "text", text: JSON.stringify(output) }],
+            _meta: {
+                elapsedMs,
+                method,
+                elementCount: output.length,
+                filteredFrom: totalNodes,
+            },
+        };
+    }
+    catch (err) {
+        const elapsedMs = Math.round(performance.now() - start);
+        return {
+            content: [{ type: "text", text: wrapCdpError(err, "dom_snapshot") }],
+            isError: true,
+            _meta: { elapsedMs, method },
+        };
+    }
+}

package/build/tools/element-utils.d.ts

@@ -0,0 +1,23 @@
+import type { CdpClient } from "../cdp/cdp-client.js";
+import type { SessionManager } from "../cdp/session-manager.js";
+export interface ResolvedElement {
+    backendNodeId: number;
+    objectId: string;
+    role: string;
+    name: string;
+    resolvedVia: "ref" | "css";
+    resolvedSessionId: string;
+}
+export interface ElementTarget {
+    ref?: string;
+    selector?: string;
+}
+/**
+ * Resolve an element target (ref or CSS selector) to a ResolvedElement.
+ * When both ref and selector are given, ref takes priority.
+ * Throws RefNotFoundError when a ref cannot be resolved.
+ * When sessionManager is provided, routes to the correct OOPIF session.
+ */
+export declare function resolveElement(cdpClient: CdpClient, sessionId: string, target: ElementTarget, sessionManager?: SessionManager): Promise<ResolvedElement>;
+export declare function buildRefNotFoundError(ref: string, roleFilter?: Set<string>): string;
+export { RefNotFoundError } from "../cache/a11y-tree.js";

package/build/tools/element-utils.js

@@ -0,0 +1,133 @@
+import { a11yTree, RefNotFoundError } from "../cache/a11y-tree.js";
+import { selectorCache } from "../cache/selector-cache.js";
+import { wrapCdpError } from "./error-utils.js";
+import { debug } from "../cdp/debug.js";
+// --- Element Resolution ---
+/**
+ * Resolve an element target (ref or CSS selector) to a ResolvedElement.
+ * When both ref and selector are given, ref takes priority.
+ * Throws RefNotFoundError when a ref cannot be resolved.
+ * When sessionManager is provided, routes to the correct OOPIF session.
+ */
+export async function resolveElement(cdpClient, sessionId, target, sessionManager) {
+    // Ref path (preferred)
+    if (target.ref) {
+        // --- Selector-Cache Check (Story 7.5) ---
+        const cached = selectorCache.get(target.ref);
+        if (cached) {
+            // M1 fix: Verify cached sessionId still matches current session
+            const currentSessionForNode = sessionManager?.getSessionForNode(cached.backendNodeId) ?? sessionId;
+            const sessionMatch = cached.sessionId === currentSessionForNode;
+            if (!sessionMatch) {
+                debug("SelectorCache: session mismatch for %s (cached=%s, current=%s), treating as miss", target.ref, cached.sessionId, currentSessionForNode);
+                // Fall through to normal resolution — session changed
+            }
+            else {
+                try {
+                    const resolved = await cdpClient.send("DOM.resolveNode", { backendNodeId: cached.backendNodeId }, currentSessionForNode);
+                    const info = a11yTree.getNodeInfo(cached.backendNodeId);
+                    debug("SelectorCache: hit for %s (backendNodeId=%d)", target.ref, cached.backendNodeId);
+                    return {
+                        backendNodeId: cached.backendNodeId,
+                        objectId: resolved.object.objectId,
+                        role: info?.role ?? "",
+                        name: info?.name ?? "",
+                        resolvedVia: "ref",
+                        resolvedSessionId: currentSessionForNode,
+                    };
+                }
+                catch {
+                    // Stale cache entry — node no longer in DOM. Remove and fall through.
+                    debug("SelectorCache: stale entry for %s, invalidating", target.ref);
+                    selectorCache.invalidate();
+                }
+            }
+        }
+        // --- Normal Ref Resolution ---
+        const backendNodeId = a11yTree.resolveRef(target.ref);
+        if (backendNodeId === undefined) {
+            throw new RefNotFoundError(`Element ${target.ref} not found.`);
+        }
+        // Determine the correct session for this node (main or OOPIF)
+        const targetSessionId = sessionManager?.getSessionForNode(backendNodeId) ?? sessionId;
+        // Safety net: ensure DOM domain is enabled before resolveNode.
+        // DOM.getDocument implicitly enables DOM and is idempotent.
+        try {
+            await cdpClient.send("DOM.getDocument", { depth: 0 }, targetSessionId);
+        }
+        catch {
+            // Best-effort — resolveNode may still work with backendNodeId
+        }
+        // Get objectId via DOM.resolveNode — may fail for stale refs (node removed from DOM)
+        let resolved;
+        try {
+            resolved = await cdpClient.send("DOM.resolveNode", { backendNodeId }, targetSessionId);
+        }
+        catch (err) {
+            // M1: Distinguish CDP connection errors from stale refs
+            const wrapped = wrapCdpError(err, "resolveElement");
+            if (wrapped.startsWith("CDP connection lost")) {
+                throw new Error(wrapped);
+            }
+            // Distinguish "DOM not enabled" from actual stale refs
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes("DOM agent needs to be enabled")) {
+                throw new Error(`DOM domain not enabled for session — this is a server bug, not a stale ref. Try calling read_page first or report this issue.`);
+            }
+            throw new RefNotFoundError(`Element ${target.ref} not found (stale ref — node no longer in DOM).`);
+        }
+        // Get role/name directly from nodeInfoMap via backendNodeId
+        const info = a11yTree.getNodeInfo(backendNodeId);
+        // Cache the resolved ref for future lookups (Story 7.5)
+        // H1 fix: Pass URL + nodeCount so set() can compute on-the-fly fingerprint
+        // when no fingerprint is active yet (first resolution after navigation)
+        selectorCache.set(target.ref, backendNodeId, targetSessionId, a11yTree.currentUrl, a11yTree.refCount);
+        return {
+            backendNodeId,
+            objectId: resolved.object.objectId,
+            role: info?.role ?? "",
+            name: info?.name ?? "",
+            resolvedVia: "ref",
+            resolvedSessionId: targetSessionId,
+        };
+    }
+    // CSS path — always main frame (CSS selectors don't work cross-frame)
+    const doc = await cdpClient.send("DOM.getDocument", { depth: 0 }, sessionId);
+    const queryResult = await cdpClient.send("DOM.querySelector", { nodeId: doc.root.nodeId, selector: target.selector }, sessionId);
+    if (queryResult.nodeId === 0) {
+        throw new Error(`Element not found for selector '${target.selector}'`);
+    }
+    const desc = await cdpClient.send("DOM.describeNode", { nodeId: queryResult.nodeId }, sessionId);
+    // Get objectId
+    const resolved = await cdpClient.send("DOM.resolveNode", { backendNodeId: desc.node.backendNodeId }, sessionId);
+    return {
+        backendNodeId: desc.node.backendNodeId,
+        objectId: resolved.object.objectId,
+        role: "", // role not reliably available via CSS path
+        name: "", // name not reliably available via CSS path
+        resolvedVia: "css",
+        resolvedSessionId: sessionId,
+    };
+}
+// --- Contextual Error Messages ---
+/**
+ * Build a contextual "did you mean?" error message for a missing ref.
+ * When roleFilter is provided, only suggests elements matching those roles.
+ */
+// Roles that are useless as suggestions when their name is empty (BUG-013)
+const CONTAINER_ROLES = new Set(["generic", "group", "none", "Section", "div"]);
+export function buildRefNotFoundError(ref, roleFilter) {
+    const suggestion = a11yTree.findClosestRef(ref, roleFilter);
+    // FR-004 + BUG-013: Detect stale / useless suggestions.
+    // — no suggestion at all
+    // — suggestion ref equals the requested ref (safety-net)
+    // — suggestion is an unnamed container (e.g. generic '') — not actionable
+    const isUseless = !suggestion ||
+        suggestion.ref === ref ||
+        (!suggestion.name && CONTAINER_ROLES.has(suggestion.role));
+    if (isUseless) {
+        return `Element ${ref} not found — refs may be stale after page navigation or DOM changes. Use read_page to get fresh refs, or use a CSS selector instead.`;
+    }
+    return `Element ${ref} not found. Did you mean ${suggestion.ref} (${suggestion.role} '${suggestion.name}')?`;
+}
+export { RefNotFoundError } from "../cache/a11y-tree.js";

package/build/tools/error-utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Wrap CDP connection errors into user-friendly error messages.
+ * Used across all tools to provide consistent error messages during reconnect scenarios.
+ *
+ * @param elementHint - Optional identifier for the element involved (e.g. ref "e5" or selector "#btn").
+ *   Used to enrich "not visible" errors so the LLM knows which element failed.
+ */
+export declare function wrapCdpError(err: unknown, toolName: string, elementHint?: string): string;

package/build/tools/error-utils.js

@@ -0,0 +1,27 @@
+/**
+ * Wrap CDP connection errors into user-friendly error messages.
+ * Used across all tools to provide consistent error messages during reconnect scenarios.
+ *
+ * @param elementHint - Optional identifier for the element involved (e.g. ref "e5" or selector "#btn").
+ *   Used to enrich "not visible" errors so the LLM knows which element failed.
+ */
+export function wrapCdpError(err, toolName, elementHint) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("CdpClient is closed") ||
+        message.includes("CdpClient closed") ||
+        message.includes("Transport is not connected") ||
+        message.includes("Transport closed unexpectedly")) {
+        return "CDP connection lost. The server is attempting to reconnect. Retry your request in a few seconds.";
+    }
+    if (message.includes("Session with given id not found") ||
+        message.includes("No target with given id found")) {
+        return `${toolName} failed: ${message}. Use virtual_desk to discover available tabs and reconnect.`;
+    }
+    // FR-003: Element exists in DOM but has no visual layout (display:none, hidden tab, etc.)
+    if (message.includes("Node does not have a layout object") ||
+        message.includes("Could not compute content quads")) {
+        const elem = elementHint ?? "target element";
+        return `${toolName} failed: Element ${elem} exists in the DOM but is not visible (no layout — likely display:none, hidden, or inside an inactive tab/panel). Use a CSS selector targeting the visible instance, or check if the element needs to be revealed first (e.g. switch tab, expand section).`;
+    }
+    return `${toolName} failed: ${message}`;
+}

package/build/tools/evaluate.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import type { CdpClient } from "../cdp/cdp-client.js";
+import type { ToolResponse } from "../types.js";
+/**
+ * Detects top-level const/let/class declarations and wraps the expression in
+ * an IIFE to avoid "Identifier has already been declared" errors across
+ * repeated Runtime.evaluate calls (which share the global scope).
+ *
+ * The last ExpressionStatement is automatically returned so callers still
+ * get the evaluation result.
+ */
+export declare function wrapInIIFE(expression: string): string;
+export declare const evaluateSchema: z.ZodObject<{
+    expression: z.ZodString;
+    await_promise: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    expression: string;
+    await_promise: boolean;
+}, {
+    expression: string;
+    await_promise?: boolean | undefined;
+}>;
+/**
+ * FR-024: Detect common evaluate anti-patterns where a dedicated tool would be better.
+ * Returns a hint string appended to the evaluate result, or null if no pattern matched.
+ * Intent: "what you did isn't wrong, but there's a more reliable tool for this".
+ *
+ * Design: be specific enough to avoid false positives on legitimate DOM work
+ * (e.g. `document.querySelector('.card').style.width = '200px'` is NOT an
+ * anti-pattern — it's a style edit that no other tool covers).
+ */
+export declare function detectEvaluateAntiPattern(expression: string): string | null;
+export type EvaluateParams = z.infer<typeof evaluateSchema>;
+export declare function evaluateHandler(params: EvaluateParams, cdpClient: CdpClient, sessionId?: string): Promise<ToolResponse>;