@silbercue/chrome 0.2.0

package/build/tools/observe.js

@@ -0,0 +1,339 @@
+import { z } from "zod";
+import { resolveElement } from "./element-utils.js";
+import { RefNotFoundError } from "../cache/a11y-tree.js";
+import { wrapCdpError } from "./error-utils.js";
+// --- Schema ---
+export const observeSchema = z.object({
+    selector: z
+        .string()
+        .describe("CSS selector or element ref (e.g. 'e5') of the element to observe"),
+    duration: z
+        .number()
+        .optional()
+        .describe("Collect all changes for this many ms, then return them. Mutually exclusive with 'until'. Default: 5000"),
+    until: z
+        .string()
+        .optional()
+        .describe("JS expression evaluated on each change — stops when it returns true. Variable 'el' is the observed element. Example: el.textContent === '8'"),
+    then_click: z
+        .string()
+        .optional()
+        .describe("CSS selector to click immediately when 'until' condition is met (for timing-critical actions). Only used with 'until'."),
+    click_first: z
+        .string()
+        .optional()
+        .describe("CSS selector to click AFTER the observer is set up but BEFORE collection starts. Use to trigger the changes you want to observe (e.g. 'Start Mutations' button)."),
+    collect: z
+        .enum(["text", "attributes", "all"])
+        .optional()
+        .default("text")
+        .describe("What to collect: 'text' for textContent changes, 'attributes' for attribute changes, 'all' for both (default: 'text')"),
+    interval: z
+        .number()
+        .optional()
+        .default(100)
+        .describe("Polling interval in ms for change detection fallback (default: 100)"),
+    timeout: z
+        .number()
+        .optional()
+        .default(10000)
+        .describe("Maximum observation time in ms (default: 10000, max: 25000)"),
+});
+// --- Max timeout to stay under CDP 30s limit ---
+const MAX_TIMEOUT_MS = 25000;
+// --- JS function builders ---
+/**
+ * Build the observer function for "collect" mode.
+ * Runs for `duration` ms, collects all text/attribute changes.
+ */
+export function buildCollectFunction(duration, interval, collect, clickFirstSelector) {
+    const observerConfig = buildMutationObserverConfig(collect);
+    const clickFirstCode = clickFirstSelector
+        ? `var cf = document.querySelector(${JSON.stringify(clickFirstSelector)}); if (cf) cf.click();`
+        : "";
+    return `function() {
+  var el = this;
+  var changes = [];
+  var lastText = el.textContent;
+  var lastAttrs = {};
+  var attrs = el.attributes;
+  for (var i = 0; i < attrs.length; i++) lastAttrs[attrs[i].name] = attrs[i].value;
+
+  function checkText() {
+    var text = el.textContent;
+    if (text !== lastText) {
+      changes.push({ type: "text", value: text });
+      lastText = text;
+    }
+  }
+  function checkAttrs() {
+    var a = el.attributes;
+    for (var i = 0; i < a.length; i++) {
+      if (lastAttrs[a[i].name] !== a[i].value) {
+        changes.push({ type: "attribute", name: a[i].name, value: a[i].value, old: lastAttrs[a[i].name] || null });
+        lastAttrs[a[i].name] = a[i].value;
+      }
+    }
+  }
+  function check() {
+    ${collect === "text" ? "checkText();" : collect === "attributes" ? "checkAttrs();" : "checkText(); checkAttrs();"}
+  }
+
+  return new Promise(function(resolve) {
+    var observer = new MutationObserver(check);
+    observer.observe(el, ${JSON.stringify(observerConfig)});
+    var poll = setInterval(check, ${interval});
+    ${clickFirstCode}
+    setTimeout(function() {
+      observer.disconnect();
+      clearInterval(poll);
+      check();
+      resolve({ changes: changes, count: changes.length });
+    }, ${duration});
+  });
+}`;
+}
+/**
+ * Build the observer function for "until" mode.
+ * Waits until a JS condition is met, optionally clicks a target element.
+ */
+export function buildUntilFunction(untilExpression, timeout, interval, collect, thenClickSelector, clickFirstSelector) {
+    const observerConfig = buildMutationObserverConfig(collect);
+    const clickCode = thenClickSelector
+        ? `var clickTarget = document.querySelector(${JSON.stringify(thenClickSelector)});
+    if (clickTarget) clickTarget.click();`
+        : "";
+    const clickFirstCode = clickFirstSelector
+        ? `var cf = document.querySelector(${JSON.stringify(clickFirstSelector)}); if (cf) cf.click();`
+        : "";
+    return `function() {
+  var el = this;
+  var changes = [];
+  var lastText = el.textContent;
+  var lastAttrs = {};
+  var attrs = el.attributes;
+  for (var i = 0; i < attrs.length; i++) lastAttrs[attrs[i].name] = attrs[i].value;
+
+  function checkText() {
+    var text = el.textContent;
+    if (text !== lastText) {
+      changes.push({ type: "text", value: text });
+      lastText = text;
+    }
+  }
+  function checkAttrs() {
+    var a = el.attributes;
+    for (var i = 0; i < a.length; i++) {
+      if (lastAttrs[a[i].name] !== a[i].value) {
+        changes.push({ type: "attribute", name: a[i].name, value: a[i].value, old: lastAttrs[a[i].name] || null });
+        lastAttrs[a[i].name] = a[i].value;
+      }
+    }
+  }
+  function checkChanges() {
+    ${collect === "text" ? "checkText();" : collect === "attributes" ? "checkAttrs();" : "checkText(); checkAttrs();"}
+  }
+
+  return new Promise(function(resolve) {
+    var done = false;
+    function check() {
+      if (done) return;
+      checkChanges();
+      if (${untilExpression}) {
+        done = true;
+        observer.disconnect();
+        clearInterval(poll);
+        clearTimeout(timer);
+        ${clickCode}
+        resolve({ met: true, value: el.textContent, changes: changes, clicked: ${thenClickSelector ? "!!clickTarget" : "false"} });
+      }
+    }
+
+    var observer = new MutationObserver(check);
+    observer.observe(el, ${JSON.stringify(observerConfig)});
+    var poll = setInterval(check, ${interval});
+    ${clickFirstCode}
+    check();
+    var timer = setTimeout(function() {
+      if (done) return;
+      done = true;
+      observer.disconnect();
+      clearInterval(poll);
+      resolve({ met: false, value: el.textContent, changes: changes, clicked: false });
+    }, ${timeout});
+  });
+}`;
+}
+function buildMutationObserverConfig(collect) {
+    const config = { subtree: true };
+    if (collect === "text" || collect === "all") {
+        config.childList = true;
+        config.characterData = true;
+    }
+    if (collect === "attributes" || collect === "all") {
+        config.attributes = true;
+    }
+    return config;
+}
+function formatCollectResponse(result, elapsedMs) {
+    const textChanges = result.changes.filter((c) => c.type === "text").map((c) => c.value);
+    const attrChanges = result.changes.filter((c) => c.type === "attribute");
+    const lines = [];
+    if (textChanges.length > 0) {
+        lines.push(`Text changes (${textChanges.length}): ${textChanges.join(", ")}`);
+    }
+    if (attrChanges.length > 0) {
+        lines.push(`Attribute changes (${attrChanges.length}): ${attrChanges.map((c) => `${c.name}: ${c.old} → ${c.value}`).join(", ")}`);
+    }
+    if (lines.length === 0) {
+        lines.push("No changes detected during observation period.");
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        _meta: {
+            elapsedMs,
+            method: "observe",
+            mode: "collect",
+            changeCount: result.count,
+            textChanges,
+        },
+    };
+}
+function formatUntilResponse(result, elapsedMs, thenClickSelector) {
+    const lines = [];
+    if (result.met) {
+        lines.push(`Condition met after ${elapsedMs}ms — value: "${result.value}"`);
+        if (result.clicked && thenClickSelector) {
+            lines.push(`Clicked ${thenClickSelector}`);
+        }
+    }
+    else {
+        lines.push(`Timeout — condition not met. Current value: "${result.value}"`);
+    }
+    const textChanges = result.changes.filter((c) => c.type === "text").map((c) => c.value);
+    if (textChanges.length > 0) {
+        lines.push(`Changes observed (${textChanges.length}): ${textChanges.join(", ")}`);
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        isError: !result.met ? true : undefined,
+        _meta: {
+            elapsedMs,
+            method: "observe",
+            mode: "until",
+            conditionMet: result.met,
+            clicked: result.clicked,
+            textChanges,
+        },
+    };
+}
+// --- Main handler ---
+export async function observeHandler(params, cdpClient, sessionId, sessionManager) {
+    const start = performance.now();
+    // Validation: need either duration or until
+    if (params.duration === undefined && !params.until) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "observe requires either 'duration' (collect mode) or 'until' (condition mode)",
+                },
+            ],
+            isError: true,
+            _meta: { elapsedMs: 0, method: "observe" },
+        };
+    }
+    if (params.duration !== undefined && params.until) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "observe: 'duration' and 'until' are mutually exclusive — use one or the other",
+                },
+            ],
+            isError: true,
+            _meta: { elapsedMs: 0, method: "observe" },
+        };
+    }
+    if (params.then_click && !params.until) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "observe: 'then_click' requires 'until' — it clicks when the condition is met",
+                },
+            ],
+            isError: true,
+            _meta: { elapsedMs: 0, method: "observe" },
+        };
+    }
+    // Cap timeout at MAX_TIMEOUT_MS to stay under CDP 30s limit
+    const effectiveTimeout = Math.min(params.duration ?? params.timeout, MAX_TIMEOUT_MS);
+    // Resolve the target element
+    let objectId;
+    let resolvedSessionId;
+    try {
+        const resolved = await resolveElement(cdpClient, sessionId, {
+            ref: /^e\d+$/.test(params.selector) ? params.selector : undefined,
+            selector: /^e\d+$/.test(params.selector) ? undefined : params.selector,
+        }, sessionManager);
+        objectId = resolved.objectId;
+        resolvedSessionId = resolved.resolvedSessionId;
+    }
+    catch (err) {
+        const elapsedMs = Math.round(performance.now() - start);
+        if (err instanceof RefNotFoundError) {
+            return {
+                content: [{ type: "text", text: `observe: ${err.message}` }],
+                isError: true,
+                _meta: { elapsedMs, method: "observe" },
+            };
+        }
+        return {
+            content: [{ type: "text", text: wrapCdpError(err, "observe") }],
+            isError: true,
+            _meta: { elapsedMs, method: "observe" },
+        };
+    }
+    // Build and execute the observer function
+    try {
+        let functionDeclaration;
+        if (params.until) {
+            functionDeclaration = buildUntilFunction(params.until, effectiveTimeout, params.interval, params.collect, params.then_click, params.click_first);
+        }
+        else {
+            functionDeclaration = buildCollectFunction(effectiveTimeout, params.interval, params.collect, params.click_first);
+        }
+        const cdpResult = await cdpClient.send("Runtime.callFunctionOn", {
+            objectId,
+            functionDeclaration,
+            returnByValue: true,
+            awaitPromise: true,
+        }, resolvedSessionId);
+        const elapsedMs = Math.round(performance.now() - start);
+        // Check for JS exception
+        if (cdpResult.exceptionDetails) {
+            const desc = cdpResult.exceptionDetails.exception?.description ??
+                cdpResult.exceptionDetails.text ??
+                "Unknown JS error";
+            return {
+                content: [{ type: "text", text: `observe JS error: ${desc}` }],
+                isError: true,
+                _meta: { elapsedMs, method: "observe" },
+            };
+        }
+        const result = cdpResult.result.value;
+        if (params.until) {
+            return formatUntilResponse(result, elapsedMs, params.then_click);
+        }
+        return formatCollectResponse(result, elapsedMs);
+    }
+    catch (err) {
+        const elapsedMs = Math.round(performance.now() - start);
+        return {
+            content: [{ type: "text", text: wrapCdpError(err, "observe") }],
+            isError: true,
+            _meta: { elapsedMs, method: "observe" },
+        };
+    }
+}

package/build/tools/press-key.d.ts

@@ -0,0 +1,33 @@
+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 pressKeySchema: z.ZodObject<{
+    key: z.ZodString;
+    ref: z.ZodOptional<z.ZodString>;
+    selector: z.ZodOptional<z.ZodString>;
+    modifiers: z.ZodOptional<z.ZodArray<z.ZodEnum<["ctrl", "shift", "alt", "meta"]>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    ref?: string | undefined;
+    selector?: string | undefined;
+    modifiers?: ("shift" | "ctrl" | "alt" | "meta")[] | undefined;
+}, {
+    key: string;
+    ref?: string | undefined;
+    selector?: string | undefined;
+    modifiers?: ("shift" | "ctrl" | "alt" | "meta")[] | undefined;
+}>;
+export type PressKeyParams = z.infer<typeof pressKeySchema>;
+interface KeyDef {
+    code: string;
+    keyCode: number;
+    text?: string;
+}
+/** Resolve a key string to its CDP key definition */
+export declare function resolveKey(key: string): {
+    key: string;
+    def: KeyDef;
+};
+export declare function pressKeyHandler(params: PressKeyParams, cdpClient: CdpClient, sessionId?: string, sessionManager?: SessionManager): Promise<ToolResponse>;
+export {};

package/build/tools/press-key.js

@@ -0,0 +1,155 @@
+import { z } from "zod";
+import { resolveElement, buildRefNotFoundError, RefNotFoundError } from "./element-utils.js";
+// --- Schema ---
+export const pressKeySchema = z.object({
+    key: z
+        .string()
+        .describe("Key to press — e.g. 'Enter', 'Escape', 'Tab', 'a', 'ArrowDown', 'F1'. For printable characters use the character itself."),
+    ref: z
+        .string()
+        .optional()
+        .describe("Element ref to focus before pressing key (e.g. 'e5')"),
+    selector: z
+        .string()
+        .optional()
+        .describe("CSS selector to focus before pressing key (e.g. '#search-input')"),
+    modifiers: z
+        .array(z.enum(["ctrl", "shift", "alt", "meta"]))
+        .optional()
+        .describe("Modifier keys to hold during key press (e.g. ['ctrl', 'shift'] for Ctrl+Shift+key)"),
+});
+const SPECIAL_KEYS = {
+    Enter: { code: "Enter", keyCode: 13, text: "\r" },
+    Tab: { code: "Tab", keyCode: 9 },
+    Escape: { code: "Escape", keyCode: 27 },
+    Backspace: { code: "Backspace", keyCode: 8 },
+    Delete: { code: "Delete", keyCode: 46 },
+    Space: { code: "Space", keyCode: 32, text: " " },
+    " ": { code: "Space", keyCode: 32, text: " " },
+    ArrowUp: { code: "ArrowUp", keyCode: 38 },
+    ArrowDown: { code: "ArrowDown", keyCode: 40 },
+    ArrowLeft: { code: "ArrowLeft", keyCode: 37 },
+    ArrowRight: { code: "ArrowRight", keyCode: 39 },
+    Home: { code: "Home", keyCode: 36 },
+    End: { code: "End", keyCode: 35 },
+    PageUp: { code: "PageUp", keyCode: 33 },
+    PageDown: { code: "PageDown", keyCode: 34 },
+    F1: { code: "F1", keyCode: 112 },
+    F2: { code: "F2", keyCode: 113 },
+    F3: { code: "F3", keyCode: 114 },
+    F4: { code: "F4", keyCode: 115 },
+    F5: { code: "F5", keyCode: 116 },
+    F6: { code: "F6", keyCode: 117 },
+    F7: { code: "F7", keyCode: 118 },
+    F8: { code: "F8", keyCode: 119 },
+    F9: { code: "F9", keyCode: 120 },
+    F10: { code: "F10", keyCode: 121 },
+    F11: { code: "F11", keyCode: 122 },
+    F12: { code: "F12", keyCode: 123 },
+};
+const MODIFIER_BITS = {
+    alt: 1,
+    ctrl: 2,
+    meta: 4,
+    shift: 8,
+};
+/** Resolve a key string to its CDP key definition */
+export function resolveKey(key) {
+    // Special key (Enter, Escape, etc.)
+    if (SPECIAL_KEYS[key]) {
+        return { key, def: SPECIAL_KEYS[key] };
+    }
+    // Single character
+    if (key.length === 1) {
+        const upper = key.toUpperCase();
+        const code = upper.charCodeAt(0);
+        // a-z / A-Z
+        if (code >= 65 && code <= 90) {
+            return {
+                key,
+                def: { code: `Key${upper}`, keyCode: code, text: key },
+            };
+        }
+        // 0-9
+        if (code >= 48 && code <= 57) {
+            return {
+                key,
+                def: { code: `Digit${key}`, keyCode: code, text: key },
+            };
+        }
+        // Other printable characters
+        return {
+            key,
+            def: { code: "", keyCode: key.charCodeAt(0), text: key },
+        };
+    }
+    // Unknown key — pass through as-is
+    return { key, def: { code: key, keyCode: 0 } };
+}
+// --- Handler ---
+export async function pressKeyHandler(params, cdpClient, sessionId, sessionManager) {
+    const start = performance.now();
+    // Focus target element if ref or selector provided
+    let effectiveSessionId = sessionId;
+    if (params.ref || params.selector) {
+        try {
+            const target = params.ref ? { ref: params.ref } : { selector: params.selector };
+            const element = await resolveElement(cdpClient, sessionId, target, sessionManager);
+            effectiveSessionId = element.resolvedSessionId;
+            await cdpClient.send("Runtime.callFunctionOn", {
+                functionDeclaration: "function() { this.focus(); }",
+                objectId: element.objectId,
+                returnByValue: false,
+            }, element.resolvedSessionId);
+        }
+        catch (err) {
+            if (err instanceof RefNotFoundError && params.ref) {
+                return {
+                    content: [{ type: "text", text: buildRefNotFoundError(params.ref) }],
+                    isError: true,
+                    _meta: { elapsedMs: Math.round(performance.now() - start), method: "press_key" },
+                };
+            }
+            throw err;
+        }
+    }
+    const { key, def } = resolveKey(params.key);
+    const modBits = (params.modifiers ?? []).reduce((acc, m) => acc | MODIFIER_BITS[m], 0);
+    // Suppress text output when modifier keys are held (Ctrl+K should not type "k")
+    const hasModifier = modBits > 0;
+    const text = hasModifier ? undefined : def.text;
+    // keyDown
+    await cdpClient.send("Input.dispatchKeyEvent", {
+        type: text ? "keyDown" : "rawKeyDown",
+        modifiers: modBits,
+        key,
+        code: def.code,
+        windowsVirtualKeyCode: def.keyCode,
+        ...(text ? { text } : {}),
+    }, effectiveSessionId);
+    // char event for printable characters (without modifiers)
+    if (text) {
+        await cdpClient.send("Input.dispatchKeyEvent", {
+            type: "char",
+            modifiers: modBits,
+            key,
+            code: def.code,
+            text,
+        }, effectiveSessionId);
+    }
+    // keyUp
+    await cdpClient.send("Input.dispatchKeyEvent", {
+        type: "keyUp",
+        modifiers: modBits,
+        key,
+        code: def.code,
+        windowsVirtualKeyCode: def.keyCode,
+    }, effectiveSessionId);
+    const elapsedMs = Math.round(performance.now() - start);
+    const modStr = params.modifiers?.length ? params.modifiers.join("+") + "+" : "";
+    const targetStr = params.ref ? ` on ${params.ref}` : params.selector ? ` on ${params.selector}` : "";
+    return {
+        content: [{ type: "text", text: `Pressed ${modStr}${params.key}${targetStr}` }],
+        _meta: { elapsedMs, method: "press_key" },
+    };
+}

package/build/tools/read-page.d.ts

@@ -0,0 +1,22 @@
+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 readPageSchema: z.ZodObject<{
+    depth: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    ref: z.ZodOptional<z.ZodString>;
+    filter: z.ZodDefault<z.ZodOptional<z.ZodEnum<["interactive", "all", "landmark", "visual"]>>>;
+    max_tokens: z.ZodEffects<z.ZodOptional<z.ZodNumber>, number | undefined, number | undefined>;
+}, "strip", z.ZodTypeAny, {
+    filter: "interactive" | "all" | "landmark" | "visual";
+    depth: number;
+    ref?: string | undefined;
+    max_tokens?: number | undefined;
+}, {
+    filter?: "interactive" | "all" | "landmark" | "visual" | undefined;
+    depth?: number | undefined;
+    ref?: string | undefined;
+    max_tokens?: number | undefined;
+}>;
+export type ReadPageParams = z.infer<typeof readPageSchema>;
+export declare function readPageHandler(params: ReadPageParams, cdpClient: CdpClient, sessionId?: string, sessionManager?: SessionManager): Promise<ToolResponse>;

package/build/tools/read-page.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import { a11yTree, RefNotFoundError } from "../cache/a11y-tree.js";
+import { wrapCdpError } from "./error-utils.js";
+export const readPageSchema = z.object({
+    depth: z.number().optional().default(3).describe("Nesting depth — how many tree levels to display (default: 3). Controls indentation, not visibility. Hidden sections (display: none) require clicking tabs/buttons to reveal."),
+    ref: z.string().optional().describe("Element ref (e.g. 'e5') to get subtree for"),
+    filter: z
+        .enum(["interactive", "all", "landmark", "visual"])
+        .optional()
+        .default("interactive")
+        .describe("Filter mode: interactive (default), all, landmark, or visual (adds bounds/click/visibility)"),
+    max_tokens: z.number().int().optional().transform(v => v !== undefined && v < 500 ? 500 : v).describe("Token budget — page content is automatically downsampled to fit. Omit for full output."),
+});
+export async function readPageHandler(params, cdpClient, sessionId, sessionManager) {
+    const start = performance.now();
+    const method = "read_page";
+    try {
+        const result = await a11yTree.getTree(cdpClient, sessionId, {
+            depth: params.depth,
+            ref: params.ref,
+            filter: params.filter,
+            max_tokens: params.max_tokens,
+            fresh: true, // Story 13a.2 fix: always fetch fresh data — precomputed cache may be stale after SPA navigation
+        }, sessionManager);
+        let responseText = result.text;
+        // FR-016: Warn when a subtree request returns a single leaf node — likely stale ref
+        if (params.ref && result.refCount <= 1) {
+            const trimmed = result.text.trim();
+            const isLeaf = /^(\[e\d+\]\s+)?(StaticText|img|separator|none)\b/.test(trimmed) ||
+                trimmed.split("\n").length <= 2;
+            if (isLeaf) {
+                responseText += `\n\n⚠ This ref points to a single leaf node — the DOM may have changed since read_page was last called. Consider calling read_page without ref for a fresh view.`;
+            }
+        }
+        // FR-03: Token metadata as structured footer — prevents LLM from needing extra calls
+        const metaParts = [`~${result.tokenCount} tokens`, `${result.refCount} refs`];
+        if (result.downsampled) {
+            metaParts.push(`downsampled from ~${result.originalTokens}`);
+        }
+        responseText += `\n\n[${metaParts.join(" | ")}]`;
+        // Truncation warning — when downsampled, hint that overlays may be hidden
+        if (result.downsampled && params.max_tokens) {
+            responseText += `\n⚠ Truncated to ~${params.max_tokens} tokens. Overlays/modals are prioritized but some elements may be hidden — retry without max_tokens or use screenshot to check for modals.`;
+        }
+        // FR-H6: Detect hidden interactive elements — hint when page has hidden sections
+        if (params.filter === "interactive" && result.refCount > 0) {
+            try {
+                const hiddenResult = await cdpClient.send("Runtime.evaluate", {
+                    expression: `(() => { let h = 0; for (const el of document.querySelectorAll('button,a[href],input:not([type="hidden"]),select,textarea,[role="button"],[role="tab"],[role="link"]')) { if (el.offsetParent === null) { const p = getComputedStyle(el).position; if (p !== "fixed" && p !== "sticky") h++; } } return h; })()`,
+                    returnByValue: true,
+                }, sessionId);
+                const hiddenCount = hiddenResult?.result?.value;
+                if (typeof hiddenCount === "number" && hiddenCount >= 5) {
+                    responseText += `\n\nNote: ${hiddenCount} interactive elements are hidden (display: none). Click tabs/buttons to reveal hidden sections.`;
+                }
+            }
+            catch {
+                // Best-effort — ignore errors
+            }
+        }
+        // FR-022: Hint that visible text content (table cells, codes, labels) is filtered out by 'interactive'.
+        // Prevents the LLM from reaching for evaluate/querySelector to read visible text.
+        if (params.filter === "interactive" && (result.hiddenContentCount ?? 0) >= 5) {
+            responseText += `\n\nNote: ${result.hiddenContentCount} text/content nodes (table cells, paragraphs, static text) are not shown by filter:"interactive". If you need to read visible text content, call read_page(ref: "eN", filter: "all") on the subtree — don't fall back to evaluate/querySelector.`;
+        }
+        const elapsedMs = Math.round(performance.now() - start);
+        return {
+            content: [{ type: "text", text: responseText }],
+            _meta: {
+                elapsedMs,
+                method,
+                refCount: result.refCount,
+                depth: result.depth,
+                tokenCount: result.tokenCount,
+                pageUrl: result.pageUrl,
+                ...(result.hasVisualData !== undefined ? { hasVisualData: result.hasVisualData } : {}),
+                ...(result.downsampled ? {
+                    downsampled: true,
+                    originalTokens: result.originalTokens,
+                    downsampleLevel: result.downsampleLevel,
+                } : {}),
+            },
+        };
+    }
+    catch (err) {
+        const elapsedMs = Math.round(performance.now() - start);
+        if (err instanceof RefNotFoundError) {
+            return {
+                content: [{ type: "text", text: err.message }],
+                isError: true,
+                _meta: { elapsedMs, method },
+            };
+        }
+        return {
+            content: [{ type: "text", text: wrapCdpError(err, "read_page") }],
+            isError: true,
+            _meta: { elapsedMs, method },
+        };
+    }
+}