feat(domains): migrate scroll with W3C deltaY semantics and dialog guard

3 files changed, 55 insertions, 70 deletions

diff --git a/src/domains/scroll.ts b/src/domains/scroll.ts
new file mode 100644
index 0000000..db80af7
--- /dev/null
+++ b/src/domains/scroll.ts
@@ -0,0 +1,53 @@
+import { Type } from "typebox";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+
+const ScrollArgs = Type.Object({
+  x: Type.Optional(Type.Number({ description: "X coordinate where to scroll. Default: viewport center" })),
+  y: Type.Optional(Type.Number({ description: "Y coordinate where to scroll. Default: viewport center" })),
+  deltaX: Type.Optional(Type.Number({ default: 0, description: "Horizontal scroll delta (CSS pixels). Positive = right." })),
+  deltaY: Type.Optional(Type.Number({
+    default: -300,
+    description: "Vertical scroll delta (CSS pixels). Positive = up (matches W3C wheel events). Default: -300 (scroll down).",
+  })),
+});
+
+export const scrollTool = defineBrowserTool({
+  name: "browser_scroll",
+  label: "Browser Scroll",
+  description:
+    "Scroll the page at given coordinates. deltaY follows W3C wheel-event convention: positive = scroll up, negative = scroll down. Default scrolls down (deltaY = -300).",
+  promptSnippet: "Scroll the page (deltaY positive=up, negative=down)",
+  promptGuidelines: [
+    "Default behavior scrolls down 300px (deltaY=-300). Pass a positive deltaY to scroll up.",
+    "Pass x/y to target a specific scrollable region (e.g., a div with overflow); otherwise scrolls the page at viewport center.",
+  ],
+  parameters: ScrollArgs,
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const info = await client.pageInfo();
+    if (!info.success) return err({ kind: "cdp_error", message: info.error.message });
+    if ("dialog" in info.data) {
+      return err({
+        kind: "invalid_state",
+        message: `Dialog open: ${info.data.dialog.type} — ${info.data.dialog.message}`,
+      });
+    }
+    const cx = args.x ?? Math.round(info.data.width / 2);
+    const cy = args.y ?? Math.round(info.data.height / 2);
+    const dx = args.deltaX ?? 0;
+    const dy = args.deltaY ?? -300;
+    // Establish compositor mouse position before mouseWheel; without this,
+    // CDP sometimes drops the wheel event with a timeout. Fix preserved
+    // from v0.2.0.
+    const moved = await client.session().call("Input.dispatchMouseEvent", { type: "mouseMoved", x: cx, y: cy });
+    if (!moved.success) return err({ kind: "cdp_error", message: moved.error.message });
+    const wheel = await client.session().call("Input.dispatchMouseEvent", {
+      type: "mouseWheel", x: cx, y: cy, deltaX: dx, deltaY: dy,
+    });
+    if (!wheel.success) return err({ kind: "cdp_error", message: wheel.error.message });
+    return ok({
+      text: `Scrolled at (${cx}, ${cy}) by (${dx}, ${dy})`,
+      details: { x: cx, y: cy, deltaX: dx, deltaY: dy },
+    });
+  },
+});
diff --git a/src/registry.ts b/src/registry.ts
index e2b13b4..a635042 100644
--- a/src/registry.ts
+++ b/src/registry.ts
@@ -3,12 +3,14 @@ import type { BrowserClient } from "./client";
 import { type AnyBrowserToolDefinition, registerBrowserTool } from "./util/tool";
 import { clickTool } from "./domains/click";
 import { typeTool, pressKeyTool, dispatchKeyTool } from "./domains/keyboard";
+import { scrollTool } from "./domains/scroll";
 
 const TOOLS: ReadonlyArray<AnyBrowserToolDefinition> = [
   clickTool,
   typeTool,
   pressKeyTool,
   dispatchKeyTool,
+  scrollTool,
 ];
 
 export const registerAllTools = (pi: ExtensionAPI, client: BrowserClient): void => {
diff --git a/src/tools.ts b/src/tools.ts
index 834d9c3..b1ef044 100644
--- a/src/tools.ts
+++ b/src/tools.ts
@@ -319,76 +319,6 @@ export function registerTools(pi: ExtensionAPI, daemon: BrowserDaemon): void {
   });
 
   // ═══════════════════════════════════════════════════════════════════════════
-  // browser_scroll
-  // ═══════════════════════════════════════════════════════════════════════════
-  pi.registerTool({
-    name: "browser_scroll",
-    label: "Browser Scroll",
-    description:
-      "Scroll the page at given coordinates (or center of viewport if not specified). Default scrolls down 300px.",
-    promptSnippet: "Scroll the page by deltaY/deltaX pixels at coordinates",
-    promptGuidelines: [
-      "Use browser_scroll to scroll pages. Default deltaY=-300 scrolls down.",
-      "Positive deltaY scrolls up, negative scrolls down.",
-      "Capture browser_screenshot after scrolling to see the new viewport content.",
-      "If mouseWheel scroll doesn't work on a specific element, try browser_execute_js to scroll a container directly: e.scrollTop += 300 or e.scrollIntoView().",
-    ],
-    parameters: Type.Object({
-      deltaY: Type.Optional(Type.Number({ description: "Vertical scroll delta in pixels. Negative = down, positive = up. Default: -300" })),
-      deltaX: Type.Optional(Type.Number({ description: "Horizontal scroll delta in pixels. Default: 0" })),
-      x: Type.Optional(Type.Number({ description: "X position to scroll from. Default: viewport center" })),
-      y: Type.Optional(Type.Number({ description: "Y position to scroll from. Default: viewport center" })),
-    }),
-    async execute(_id, params) {
-      try {
-        await daemon.ensureAlive();
-        const dy = params.deltaY ?? -300;
-        const dx = params.deltaX ?? 0;
-
-        // Default to center of viewport if not specified
-        let cx = params.x;
-        let cy = params.y;
-        if (cx === undefined || cy === undefined) {
-          try {
-            const info = await daemon.getPageInfo();
-            if (!("dialog" in info)) {
-              if (cx === undefined) cx = Math.round(info.width / 2);
-              if (cy === undefined) cy = Math.round(info.height / 2);
-            }
-          } catch {
-            cx = cx ?? 500;
-            cy = cy ?? 400;
-          }
-        }
-
-        // Establish mouse position before wheel — Chrome requires a prior
-        // mouseMoved for mouseWheel to hit the correct element.
-        await daemon.cdp("Input.dispatchMouseEvent", {
-          type: "mouseMoved",
-          x: cx,
-          y: cy,
-        });
-
-        await daemon.cdp("Input.dispatchMouseEvent", {
-          type: "mouseWheel",
-          x: cx,
-          y: cy,
-          deltaX: dx,
-          deltaY: dy,
-        });
-
-        return { content: [{ type: "text" as const, text: `Scrolled by (${dx}, ${dy}) at (${cx}, ${cy})` }], details: undefined };
-      } catch (err) {
-        return {
-          isError: true,
-          content: [{ type: "text" as const, text: `Scroll failed: ${err instanceof Error ? err.message : String(err)}` }],
-          details: undefined,
-        };
-      }
-    },
-  });
-
-  // ═══════════════════════════════════════════════════════════════════════════
   // browser_upload_file
   // ═══════════════════════════════════════════════════════════════════════════
   pi.registerTool({