@ticktockbent/charlotte 0.6.0 → 0.6.2

package/dist/tools/interaction.js

@@ -2,322 +2,15 @@ import * as fs from "node:fs/promises";
 import { z } from "zod";
 import { CharlotteError, CharlotteErrorCode } from "../types/errors.js";
 import { logger } from "../utils/logger.js";
-import { renderActivePage, renderAfterAction, resolveElement, formatPageResponse, handleToolError, coercedBoolean, } from "./tool-helpers.js";
-/** Maps short modifier names to Puppeteer KeyInput values. */
-const MODIFIER_KEY_MAP = {
-    ctrl: "Control",
-    shift: "Shift",
-    alt: "Alt",
-    meta: "Meta",
-};
-/**
- * Click an element by backend node ID using CDP to get coordinates,
- * or more simply by resolving to an XPath/selector and using page.click.
- *
- * The most reliable approach: use CDP to get the element's coordinates, then click at those coords.
- */
-async function clickElementByBackendNodeId(page, backendNodeId, clickType = "left", modifiers = []) {
-    // Get the element's box model to find clickable coordinates
-    const cdpSession = await page.createCDPSession();
-    try {
-        // First, scroll the element into view
-        await cdpSession.send("DOM.scrollIntoViewIfNeeded", { backendNodeId });
-        // Get box model for coordinates
-        const { model } = await cdpSession.send("DOM.getBoxModel", {
-            backendNodeId,
-        });
-        if (!model) {
-            throw new CharlotteError(CharlotteErrorCode.ELEMENT_NOT_FOUND, "Element has no visible box model — it may be hidden or zero-sized.", "Call charlotte:observe to check the element's state.");
-        }
-        // content quad: [x1,y1, x2,y2, x3,y3, x4,y4]
-        const contentQuad = model.content;
-        const centerX = (contentQuad[0] + contentQuad[2] + contentQuad[4] + contentQuad[6]) / 4;
-        const centerY = (contentQuad[1] + contentQuad[3] + contentQuad[5] + contentQuad[7]) / 4;
-        // Hold down modifier keys before the click
-        for (const modifier of modifiers) {
-            const modifierKey = MODIFIER_KEY_MAP[modifier];
-            await page.keyboard.down(modifierKey);
-        }
-        try {
-            if (clickType === "right") {
-                await page.mouse.click(centerX, centerY, { button: "right" });
-            }
-            else if (clickType === "double") {
-                await page.mouse.click(centerX, centerY, { clickCount: 2 });
-            }
-            else {
-                await page.mouse.click(centerX, centerY);
-            }
-        }
-        finally {
-            // Release modifier keys in reverse order (always release even if click fails)
-            for (const modifier of [...modifiers].reverse()) {
-                const modifierKey = MODIFIER_KEY_MAP[modifier];
-                await page.keyboard.up(modifierKey);
-            }
-        }
-    }
-    finally {
-        await cdpSession.detach();
-    }
-}
-/**
- * Wait for any navigation triggered by an action, or fall back to a brief settle pause.
- *
- * Listens for the `framenavigated` CDP event to detect if a click caused navigation.
- * If navigation is detected within `detectionWindowMs`, waits for the page load event
- * (up to `loadTimeoutMs`). If no navigation fires, returns after `settleMs`.
- *
- * Also races against dialog events — if the action triggers a JavaScript dialog
- * (alert, confirm, prompt, beforeunload), the action promise will block indefinitely.
- * This function detects that and returns early so the caller can surface `pending_dialog`.
- */
-export async function waitForPossibleNavigation(page, action, { detectionWindowMs = 500, loadTimeoutMs = 10000, settleMs = 50 } = {}) {
-    let navigationDetected = false;
-    let dialogDetected = false;
-    // Listen for navigation start via page event (fires on any navigation)
-    const navigationStartPromise = new Promise((resolve) => {
-        const handler = () => {
-            navigationDetected = true;
-            page.off("framenavigated", handler);
-            resolve();
-        };
-        page.on("framenavigated", handler);
-        // Clean up listener if no navigation fires within detection window
-        setTimeout(() => {
-            page.off("framenavigated", handler);
-            resolve();
-        }, detectionWindowMs);
-    });
-    // Listen for dialog (blocks the action from completing)
-    const dialogPromise = new Promise((resolve) => {
-        const handler = () => {
-            dialogDetected = true;
-            page.off("dialog", handler);
-            resolve();
-        };
-        page.on("dialog", handler);
-        // Clean up on timeout — if no dialog fires, we don't need this listener
-        setTimeout(() => {
-            page.off("dialog", handler);
-            resolve();
-        }, detectionWindowMs);
-    });
-    // Race: action vs dialog
-    const actionPromise = action();
-    await Promise.race([
-        actionPromise.then(() => "action"),
-        dialogPromise.then(() => "dialog"),
-    ]);
-    if (dialogDetected) {
-        // Dialog is blocking the action. Don't await actionPromise — it will
-        // resolve later when the dialog is handled via charlotte:dialog.
-        // Guard against unhandled rejection from the fire-and-forget promise.
-        actionPromise.catch(() => {
-            logger.debug("Post-dialog action promise rejected (expected)");
-        });
-        return;
-    }
-    // Action completed normally — check for navigation
-    await navigationStartPromise;
-    if (navigationDetected) {
-        // Navigation occurred — wait for the page to finish loading
-        try {
-            await page.waitForNavigation({ waitUntil: "load", timeout: loadTimeoutMs });
-        }
-        catch {
-            // Page may have already finished loading before we called waitForNavigation,
-            // or the load timed out. Either way, render what we have.
-            logger.debug("Post-navigation load wait ended (page may already be loaded)");
-        }
-    }
-    else {
-        // No navigation — brief settle for in-page DOM updates
-        await new Promise((resolve) => setTimeout(resolve, settleMs));
-    }
-}
-/**
- * Focus an element by backend node ID using CDP.
- */
-async function focusElementByBackendNodeId(page, backendNodeId) {
-    const cdpSession = await page.createCDPSession();
-    try {
-        await cdpSession.send("DOM.focus", { backendNodeId });
-    }
-    finally {
-        await cdpSession.detach();
-    }
-}
-/**
- * Hover over an element by backend node ID.
- */
-async function hoverElementByBackendNodeId(page, backendNodeId) {
-    const cdpSession = await page.createCDPSession();
-    try {
-        await cdpSession.send("DOM.scrollIntoViewIfNeeded", { backendNodeId });
-        const { model } = await cdpSession.send("DOM.getBoxModel", {
-            backendNodeId,
-        });
-        if (!model) {
-            throw new CharlotteError(CharlotteErrorCode.ELEMENT_NOT_FOUND, "Element has no visible box model for hover.");
-        }
-        const contentQuad = model.content;
-        const centerX = (contentQuad[0] + contentQuad[2] + contentQuad[4] + contentQuad[6]) / 4;
-        const centerY = (contentQuad[1] + contentQuad[3] + contentQuad[5] + contentQuad[7]) / 4;
-        await page.mouse.move(centerX, centerY);
-    }
-    finally {
-        await cdpSession.detach();
-    }
-}
-/**
- * Get the center coordinates of an element by backend node ID.
- * Scrolls the element into view first.
- */
-async function getElementCenter(page, backendNodeId) {
-    const cdpSession = await page.createCDPSession();
-    try {
-        await cdpSession.send("DOM.scrollIntoViewIfNeeded", { backendNodeId });
-        const { model } = await cdpSession.send("DOM.getBoxModel", {
-            backendNodeId,
-        });
-        if (!model) {
-            throw new CharlotteError(CharlotteErrorCode.ELEMENT_NOT_FOUND, "Element has no visible box model — it may be hidden or zero-sized.", "Call charlotte:observe to check the element's state.");
-        }
-        const contentQuad = model.content;
-        return {
-            x: (contentQuad[0] + contentQuad[2] + contentQuad[4] + contentQuad[6]) / 4,
-            y: (contentQuad[1] + contentQuad[3] + contentQuad[5] + contentQuad[7]) / 4,
-        };
-    }
-    finally {
-        await cdpSession.detach();
-    }
-}
-/**
- * Drag one element to another using mouse primitives.
- * Sequence: move to source → mousedown → move to target → mouseup
- * Includes intermediate move steps and delays to ensure drag events fire reliably.
- */
-async function dragElementToElement(page, sourceBackendNodeId, targetBackendNodeId) {
-    const sourceCenter = await getElementCenter(page, sourceBackendNodeId);
-    const targetCenter = await getElementCenter(page, targetBackendNodeId);
-    // Move to source and press down
-    await page.mouse.move(sourceCenter.x, sourceCenter.y);
-    await page.mouse.down();
-    // Intermediate move to trigger dragstart (some browsers need movement to begin a drag)
-    await page.mouse.move(sourceCenter.x + (targetCenter.x - sourceCenter.x) * 0.25, sourceCenter.y + (targetCenter.y - sourceCenter.y) * 0.25, { steps: 5 });
-    await new Promise((resolve) => setTimeout(resolve, 50));
-    // Move to target
-    await page.mouse.move(targetCenter.x, targetCenter.y, { steps: 10 });
-    await new Promise((resolve) => setTimeout(resolve, 50));
-    // Release
-    await page.mouse.up();
-}
-/**
- * Type text into an input element. Uses CDP to focus, optionally clears, then types via keyboard.
- */
-async function typeIntoElement(page, backendNodeId, text, clearFirst, pressEnter) {
-    // Focus the element
-    await focusElementByBackendNodeId(page, backendNodeId);
-    if (clearFirst) {
-        // Select all text then delete — works cross-platform
-        await page.keyboard.down("Control");
-        await page.keyboard.press("a");
-        await page.keyboard.up("Control");
-        await page.keyboard.press("Backspace");
-    }
-    // Type the text character by character
-    await page.keyboard.type(text);
-    if (pressEnter) {
-        await page.keyboard.press("Enter");
-    }
-}
-/**
- * Select a value in a <select> element using CDP to set the value and dispatch change events.
- */
-async function selectOptionByBackendNodeId(page, backendNodeId, value) {
-    const cdpSession = await page.createCDPSession();
-    try {
-        // Resolve the node to get a remote object reference
-        const { object } = await cdpSession.send("DOM.resolveNode", {
-            backendNodeId,
-        });
-        if (!object?.objectId) {
-            throw new CharlotteError(CharlotteErrorCode.ELEMENT_NOT_FOUND, "Could not resolve select element.");
-        }
-        // Use Runtime.callFunctionOn to set the value and fire events
-        await cdpSession.send("Runtime.callFunctionOn", {
-            objectId: object.objectId,
-            functionDeclaration: `function(targetValue) {
-        const options = Array.from(this.options);
-        const matchByValue = options.find(o => o.value === targetValue);
-        const matchByText = options.find(o => o.textContent.trim() === targetValue);
-        const match = matchByValue || matchByText;
-        if (match) {
-          this.value = match.value;
-          this.dispatchEvent(new Event('input', { bubbles: true }));
-          this.dispatchEvent(new Event('change', { bubbles: true }));
-        } else {
-          throw new Error('Option "' + targetValue + '" not found');
-        }
-      }`,
-            arguments: [{ value }],
-        });
-    }
-    finally {
-        await cdpSession.detach();
-    }
-}
-/**
- * Submit a form by backend node ID — calls form.submit() via CDP.
- */
-async function submitFormByBackendNodeId(page, backendNodeId) {
-    const cdpSession = await page.createCDPSession();
-    try {
-        const { object } = await cdpSession.send("DOM.resolveNode", {
-            backendNodeId,
-        });
-        if (!object?.objectId) {
-            throw new CharlotteError(CharlotteErrorCode.ELEMENT_NOT_FOUND, "Could not resolve form element.");
-        }
-        await cdpSession.send("Runtime.callFunctionOn", {
-            objectId: object.objectId,
-            functionDeclaration: `function() {
-        this.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));
-      }`,
-        });
-    }
-    finally {
-        await cdpSession.detach();
-    }
-}
-/**
- * Set files on a file input element using CDP DOM.setFileInputFiles.
- * Validates that the target element is actually an <input type="file">.
- */
-async function setFileInputFiles(page, backendNodeId, filePaths) {
-    const cdpSession = await page.createCDPSession();
-    try {
-        const { node } = await cdpSession.send("DOM.describeNode", { backendNodeId });
-        const isFileInput = node.nodeName === "INPUT" &&
-            (node.attributes ?? []).some((attr, i, arr) => attr === "type" && arr[i + 1] === "file");
-        if (!isFileInput) {
-            throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, "Element is not a file input.", "Use charlotte:find to locate file_input elements.");
-        }
-        await cdpSession.send("DOM.setFileInputFiles", {
-            files: filePaths,
-            backendNodeId,
-        });
-    }
-    finally {
-        await cdpSession.detach();
-    }
-}
+import { ensureReady, renderActivePage, renderAfterAction, resolveElement, formatPageResponse, handleToolError, coercedBoolean, } from "./tool-helpers.js";
+import { MODIFIER_KEY_MAP, clickElementByBackendNodeId, focusElementByBackendNodeId, hoverElementByBackendNodeId, dragElementToElement, typeIntoElement, selectOptionByBackendNodeId, submitFormByBackendNodeId, setFileInputFiles, waitForPossibleNavigation, } from "./interaction-helpers.js";
+import { registerWaitForTools } from "./wait-for.js";
+// Re-export for backward compatibility (used by dialog and popup integration tests)
+export { waitForPossibleNavigation } from "./interaction-helpers.js";
 export function registerInteractionTools(server, deps) {
     const tools = {};
-    // ─── charlotte:click ───
-    tools["charlotte:click"] = server.registerTool("charlotte:click", {
+    // ─── charlotte_click ───
+    tools["charlotte_click"] = server.registerTool("charlotte_click", {
         description: "Click an interactive element on the page. Returns full page representation after the click.",
         inputSchema: {
             element_id: z.string().describe("Target element ID from page representation"),
@@ -332,7 +25,7 @@ export function registerInteractionTools(server, deps) {
         },
     }, async ({ element_id, click_type, modifiers }) => {
         try {
-            await deps.browserManager.ensureConnected();
+            await ensureReady(deps);
             const { page, backendNodeId } = await resolveElement(deps, element_id);
             const clickVariant = click_type ?? "left";
             const activeModifiers = modifiers ?? [];
@@ -349,8 +42,8 @@ export function registerInteractionTools(server, deps) {
             return handleToolError(error);
         }
     });
-    // ─── charlotte:click_at ───
-    tools["charlotte:click_at"] = server.registerTool("charlotte:click_at", {
+    // ─── charlotte_click_at ───
+    tools["charlotte_click_at"] = server.registerTool("charlotte_click_at", {
         description: "Click at specific page coordinates. Use when target elements are not in the accessibility tree (custom widgets, canvas, non-semantic interactive divs). Dispatches real CDP-level mouse events. Returns full page representation after the click.",
         inputSchema: {
             x: z.number().describe("X coordinate in page pixels"),
@@ -366,7 +59,7 @@ export function registerInteractionTools(server, deps) {
         },
     }, async ({ x, y, click_type, modifiers }) => {
         try {
-            await deps.browserManager.ensureConnected();
+            await ensureReady(deps);
             const page = deps.pageManager.getActivePage();
             const clickVariant = click_type ?? "left";
             const activeModifiers = modifiers ?? [];
@@ -413,8 +106,8 @@ export function registerInteractionTools(server, deps) {
             return handleToolError(error);
         }
     });
-    // ─── charlotte:type ───
-    tools["charlotte:type"] = server.registerTool("charlotte:type", {
+    // ─── charlotte_type ───
+    tools["charlotte_type"] = server.registerTool("charlotte_type", {
         description: "Type text into an input element. Returns full page representation after typing.",
         inputSchema: {
             element_id: z.string().describe("Target input element ID"),
@@ -425,20 +118,30 @@ export function registerInteractionTools(server, deps) {
             press_enter: coercedBoolean
                 .optional()
                 .describe("Press Enter after typing (default: false)"),
+            slowly: coercedBoolean
+                .optional()
+                .describe("Type one character at a time with a delay between keystrokes. Use for sites with autocomplete, search-as-you-type, or per-key validation (default: false)"),
+            character_delay: z
+                .number()
+                .min(1)
+                .optional()
+                .describe("Milliseconds between keystrokes (implies slowly: true). Default when slowly is true: 50ms"),
         },
-    }, async ({ element_id, text, clear_first, press_enter }) => {
+    }, async ({ element_id, text, clear_first, press_enter, slowly, character_delay }) => {
         try {
-            await deps.browserManager.ensureConnected();
+            await ensureReady(deps);
             const { page, backendNodeId } = await resolveElement(deps, element_id);
             const shouldClearFirst = clear_first ?? true;
             const shouldPressEnter = press_enter ?? false;
+            const delayMs = character_delay ?? (slowly ? 50 : undefined);
             logger.info("Typing into element", {
                 element_id,
                 textLength: text.length,
                 clearFirst: shouldClearFirst,
                 pressEnter: shouldPressEnter,
+                characterDelay: delayMs,
             });
-            await typeIntoElement(page, backendNodeId, text, shouldClearFirst, shouldPressEnter);
+            await typeIntoElement(page, backendNodeId, text, shouldClearFirst, shouldPressEnter, delayMs);
             const representation = await renderAfterAction(deps);
             return formatPageResponse(representation);
         }
@@ -446,8 +149,8 @@ export function registerInteractionTools(server, deps) {
             return handleToolError(error);
         }
     });
-    // ─── charlotte:select ───
-    tools["charlotte:select"] = server.registerTool("charlotte:select", {
+    // ─── charlotte_select ───
+    tools["charlotte_select"] = server.registerTool("charlotte_select", {
         description: "Select an option in a select/dropdown element. Returns full page representation after selection.",
         inputSchema: {
             element_id: z.string().describe("Target select element ID"),
@@ -455,7 +158,7 @@ export function registerInteractionTools(server, deps) {
         },
     }, async ({ element_id, value }) => {
         try {
-            await deps.browserManager.ensureConnected();
+            await ensureReady(deps);
             const { page, backendNodeId } = await resolveElement(deps, element_id);
             logger.info("Selecting option", { element_id, value });
             await selectOptionByBackendNodeId(page, backendNodeId, value);
@@ -466,15 +169,15 @@ export function registerInteractionTools(server, deps) {
             return handleToolError(error);
         }
     });
-    // ─── charlotte:toggle ───
-    tools["charlotte:toggle"] = server.registerTool("charlotte:toggle", {
+    // ─── charlotte_toggle ───
+    tools["charlotte_toggle"] = server.registerTool("charlotte_toggle", {
         description: "Toggle a checkbox or switch element. Returns full page representation after toggle.",
         inputSchema: {
             element_id: z.string().describe("Target checkbox or switch element ID"),
         },
     }, async ({ element_id }) => {
         try {
-            await deps.browserManager.ensureConnected();
+            await ensureReady(deps);
             const { page, backendNodeId } = await resolveElement(deps, element_id);
             logger.info("Toggling element", { element_id });
             // Toggle by clicking the element
@@ -487,20 +190,20 @@ export function registerInteractionTools(server, deps) {
             return handleToolError(error);
         }
     });
-    // ─── charlotte:submit ───
-    tools["charlotte:submit"] = server.registerTool("charlotte:submit", {
+    // ─── charlotte_submit ───
+    tools["charlotte_submit"] = server.registerTool("charlotte_submit", {
         description: "Submit a form. Can submit by form ID or by clicking its submit button. Returns full page representation after submission.",
         inputSchema: {
             form_id: z.string().describe("Form ID from page representation"),
         },
     }, async ({ form_id }) => {
         try {
-            await deps.browserManager.ensureConnected();
+            await ensureReady(deps);
             // Find the form in the current representation
             const representation = await renderActivePage(deps, { detail: "minimal" });
             const form = representation.forms.find((f) => f.id === form_id);
             if (!form) {
-                throw new CharlotteError(CharlotteErrorCode.ELEMENT_NOT_FOUND, `Form '${form_id}' not found on page.`, "Call charlotte:observe to get current page state and verify form IDs.");
+                throw new CharlotteError(CharlotteErrorCode.ELEMENT_NOT_FOUND, `Form '${form_id}' not found on page.`, "Call charlotte_observe to get current page state and verify form IDs.");
             }
             const page = deps.pageManager.getActivePage();
             // If the form has a submit button, click it
@@ -528,8 +231,8 @@ export function registerInteractionTools(server, deps) {
             return handleToolError(error);
         }
     });
-    // ─── charlotte:scroll ───
-    tools["charlotte:scroll"] = server.registerTool("charlotte:scroll", {
+    // ─── charlotte_scroll ───
+    tools["charlotte_scroll"] = server.registerTool("charlotte_scroll", {
         description: "Scroll the page or a specific container. Returns full page representation after scrolling.",
         inputSchema: {
             direction: z.enum(["up", "down", "left", "right"]).describe("Scroll direction"),
@@ -541,14 +244,15 @@ export function registerInteractionTools(server, deps) {
         },
     }, async ({ direction, amount, element_id }) => {
         try {
-            await deps.browserManager.ensureConnected();
+            await ensureReady(deps);
             const page = deps.pageManager.getActivePage();
             const scrollAmount = amount ?? "page";
             logger.info("Scrolling", { direction, amount: scrollAmount, element_id });
             // Calculate pixel distance
             const viewport = page.viewport();
-            const viewportWidth = viewport?.width ?? 1280;
-            const viewportHeight = viewport?.height ?? 720;
+            const { defaultViewport } = deps.config;
+            const viewportWidth = viewport?.width ?? defaultViewport.width;
+            const viewportHeight = viewport?.height ?? defaultViewport.height;
             let pixelDistance;
             if (scrollAmount === "page") {
                 pixelDistance =
@@ -617,15 +321,15 @@ export function registerInteractionTools(server, deps) {
             return handleToolError(error);
         }
     });
-    // ─── charlotte:hover ───
-    tools["charlotte:hover"] = server.registerTool("charlotte:hover", {
+    // ─── charlotte_hover ───
+    tools["charlotte_hover"] = server.registerTool("charlotte_hover", {
         description: "Hover over an element to trigger hover states. Returns full page representation after hover.",
         inputSchema: {
             element_id: z.string().describe("Target element ID"),
         },
     }, async ({ element_id }) => {
         try {
-            await deps.browserManager.ensureConnected();
+            await ensureReady(deps);
             const { page, backendNodeId } = await resolveElement(deps, element_id);
             logger.info("Hovering element", { element_id });
             await hoverElementByBackendNodeId(page, backendNodeId);
@@ -636,8 +340,8 @@ export function registerInteractionTools(server, deps) {
             return handleToolError(error);
         }
     });
-    // ─── charlotte:drag ───
-    tools["charlotte:drag"] = server.registerTool("charlotte:drag", {
+    // ─── charlotte_drag ───
+    tools["charlotte_drag"] = server.registerTool("charlotte_drag", {
         description: "Drag an element to another element. Uses mouse primitives to simulate drag-and-drop. Returns full page representation after the drag.",
         inputSchema: {
             source_id: z.string().describe("Element ID of the drag source"),
@@ -645,7 +349,7 @@ export function registerInteractionTools(server, deps) {
         },
     }, async ({ source_id, target_id }) => {
         try {
-            await deps.browserManager.ensureConnected();
+            await ensureReady(deps);
             const { page, backendNodeId: sourceNodeId } = await resolveElement(deps, source_id);
             const { backendNodeId: targetNodeId } = await resolveElement(deps, target_id);
             logger.info("Dragging element", { source_id, target_id });
@@ -659,8 +363,8 @@ export function registerInteractionTools(server, deps) {
             return handleToolError(error);
         }
     });
-    // ─── charlotte:key ───
-    tools["charlotte:key"] = server.registerTool("charlotte:key", {
+    // ─── charlotte_key ───
+    tools["charlotte_key"] = server.registerTool("charlotte_key", {
         description: "Send keyboard input to the page or a specific element. Supports single key with modifiers, or a sequence of keys. Use for keyboard-driven UIs (games, terminals, code editors) and non-input elements with keydown listeners.",
         inputSchema: {
             key: z
@@ -687,7 +391,7 @@ export function registerInteractionTools(server, deps) {
         },
     }, async ({ key, keys, modifiers, element_id, delay }) => {
         try {
-            await deps.browserManager.ensureConnected();
+            await ensureReady(deps);
             const page = deps.pageManager.getActivePage();
             // Validate: exactly one of key or keys must be provided
             if (key && keys) {
@@ -734,8 +438,8 @@ export function registerInteractionTools(server, deps) {
             return handleToolError(error);
         }
     });
-    // ─── charlotte:upload ───
-    tools["charlotte:upload"] = server.registerTool("charlotte:upload", {
+    // ─── charlotte_upload ───
+    tools["charlotte_upload"] = server.registerTool("charlotte_upload", {
         description: "Set files on a file input element. Validates that files exist and that the target is a file input. Returns full page representation after upload.",
         inputSchema: {
             element_id: z.string().describe("Target file input element ID"),
@@ -743,7 +447,7 @@ export function registerInteractionTools(server, deps) {
         },
     }, async ({ element_id, paths }) => {
         try {
-            await deps.browserManager.ensureConnected();
+            await ensureReady(deps);
             const { page, backendNodeId } = await resolveElement(deps, element_id);
             // Validate all files exist before sending to CDP
             for (const filePath of paths) {
@@ -763,166 +467,82 @@ export function registerInteractionTools(server, deps) {
             return handleToolError(error);
         }
     });
-    // ─── charlotte:wait_for ───
-    tools["charlotte:wait_for"] = server.registerTool("charlotte:wait_for", {
-        description: "Wait for a condition to be met on the page. Returns page representation when the condition is satisfied, or a TIMEOUT error.",
+    // ─── charlotte_fill_form ───
+    const FILLABLE_TYPES = new Set([
+        "text_input", "textarea", "select", "checkbox", "radio", "toggle", "date_input", "color_input",
+    ]);
+    tools["charlotte_fill_form"] = server.registerTool("charlotte_fill_form", {
+        description: "Fill multiple form fields in a single call. Auto-detects element types (text input, select, checkbox, etc.) and applies the appropriate action. Returns a single page representation with delta covering all changes. Validates all fields before mutating any — if one field is invalid, no fields are changed.",
         inputSchema: {
-            element_id: z.string().optional().describe("Wait for specific element to appear/change"),
-            state: z
-                .enum(["visible", "hidden", "enabled", "disabled", "exists", "removed"])
-                .optional()
-                .describe("Target element state to wait for"),
-            text: z.string().optional().describe("Wait for text to appear on the page"),
-            selector: z.string().optional().describe("Wait for CSS selector to match"),
-            js: z.string().optional().describe("Wait for JS expression to return truthy"),
-            timeout: z.number().optional().describe("Max wait in ms (default: 10000)"),
+            fields: z
+                .array(z.object({
+                element_id: z.string().describe("Element ID of the form field"),
+                value: z.string().describe("Value to set: text for inputs/textareas, option value or text for selects. For checkbox/radio/toggle the element is clicked (toggling its state) and value is ignored."),
+            }))
+                .min(1)
+                .describe("Array of {element_id, value} pairs to fill"),
         },
-    }, async ({ element_id, state, text, selector, js, timeout }) => {
+    }, async ({ fields }) => {
         try {
-            await deps.browserManager.ensureConnected();
-            const page = deps.pageManager.getActivePage();
-            const waitTimeout = timeout ?? 10000;
-            // Validate that at least one condition is provided
-            if (!element_id && !text && !selector && !js) {
-                throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, "At least one wait condition is required (element_id, text, selector, or js).");
+            await ensureReady(deps);
+            // Render to get element types from the interactive array
+            const representation = await renderActivePage(deps, { detail: "minimal" });
+            // Validate all fields up front before performing any actions
+            const resolvedFields = [];
+            for (const field of fields) {
+                // Check type before resolving — gives better errors for non-fillable elements
+                const element = representation.interactive.find((el) => el.id === field.element_id);
+                if (!element) {
+                    // Fall through to resolveElement for proper "not found" with suggestions
+                    await resolveElement(deps, field.element_id);
+                    // If resolveElement didn't throw, the element exists but isn't interactive
+                    throw new CharlotteError(CharlotteErrorCode.ELEMENT_NOT_FOUND, `Element '${field.element_id}' is not an interactive form field.`, "Call charlotte_find to locate form fields by role or text.");
+                }
+                if (!FILLABLE_TYPES.has(element.type)) {
+                    const hint = element.type === "file_input"
+                        ? "Use charlotte_upload for file inputs."
+                        : "fill_form supports: text_input, textarea, select, checkbox, radio, toggle, date_input, color_input.";
+                    throw new CharlotteError(CharlotteErrorCode.ELEMENT_NOT_INTERACTIVE, `Element '${field.element_id}' is type '${element.type}' which cannot be filled.`, hint);
+                }
+                const resolved = await resolveElement(deps, field.element_id);
+                resolvedFields.push({
+                    backendNodeId: resolved.backendNodeId,
+                    type: element.type,
+                    value: field.value,
+                    page: resolved.page,
+                });
             }
-            logger.info("Waiting for condition", {
-                element_id,
-                state,
-                text,
-                selector,
-                js,
-                timeout: waitTimeout,
-            });
-            // Build a composite wait condition
-            const satisfied = await pollWaitForCondition(deps, page, { element_id, state, text, selector, js }, waitTimeout);
-            if (!satisfied) {
-                const representation = await renderAfterAction(deps);
-                const timeoutError = new CharlotteError(CharlotteErrorCode.TIMEOUT, `Wait condition not met within ${waitTimeout}ms.`, "The current page state is included in the response. Consider increasing timeout or adjusting your condition.");
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                ...timeoutError.toResponse(),
-                                page: representation,
-                            }),
-                        },
-                    ],
-                    isError: true,
-                };
+            logger.info("Filling form fields", { fieldCount: resolvedFields.length });
+            // Fill each field using the appropriate action
+            for (const field of resolvedFields) {
+                switch (field.type) {
+                    case "text_input":
+                    case "textarea":
+                    case "date_input":
+                    case "color_input":
+                        await typeIntoElement(field.page, field.backendNodeId, field.value, true, false);
+                        break;
+                    case "select":
+                        await selectOptionByBackendNodeId(field.page, field.backendNodeId, field.value);
+                        break;
+                    case "checkbox":
+                    case "radio":
+                    case "toggle":
+                        await clickElementByBackendNodeId(field.page, field.backendNodeId, "left");
+                        break;
+                }
             }
-            const representation = await renderAfterAction(deps);
-            return formatPageResponse(representation);
+            // Single render after all fields are filled
+            const result = await renderAfterAction(deps);
+            return formatPageResponse(result);
         }
         catch (error) {
             return handleToolError(error);
         }
     });
+    // ─── charlotte_wait_for (delegated to wait-for.ts) ───
+    const waitForTools = registerWaitForTools(server, deps);
+    Object.assign(tools, waitForTools);
     return tools;
 }
-/**
- * Poll for complex wait_for conditions that may involve element state checks.
- */
-async function pollWaitForCondition(deps, page, condition, timeoutMs) {
-    const pollInterval = 100;
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        let allSatisfied = true;
-        // Check element_id + state condition
-        if (condition.element_id) {
-            const targetState = condition.state ?? "exists";
-            const elementSatisfied = await checkElementCondition(deps, condition.element_id, targetState);
-            if (!elementSatisfied)
-                allSatisfied = false;
-        }
-        // Check text condition
-        if (allSatisfied && condition.text) {
-            const textFound = await page.evaluate((searchText) => {
-                return document.body?.innerText?.includes(searchText) ?? false;
-            }, condition.text);
-            if (!textFound)
-                allSatisfied = false;
-        }
-        // Check selector condition
-        if (allSatisfied && condition.selector) {
-            const selectorMatched = await page.$(condition.selector);
-            if (!selectorMatched)
-                allSatisfied = false;
-        }
-        // Check JS condition via CDP Runtime.evaluate (matches evaluate.ts pattern)
-        if (allSatisfied && condition.js) {
-            const cdpSession = await page.createCDPSession();
-            try {
-                const evalResult = await cdpSession.send("Runtime.evaluate", {
-                    expression: condition.js,
-                    returnByValue: true,
-                    awaitPromise: true,
-                    timeout: Math.max(0, deadline - Date.now()),
-                });
-                const isTruthy = !evalResult.exceptionDetails && !!evalResult.result.value;
-                if (!isTruthy)
-                    allSatisfied = false;
-            }
-            catch {
-                allSatisfied = false;
-            }
-            finally {
-                await cdpSession.detach().catch(() => { });
-            }
-        }
-        if (allSatisfied)
-            return true;
-        const remainingTime = deadline - Date.now();
-        if (remainingTime <= 0)
-            break;
-        await new Promise((resolve) => setTimeout(resolve, Math.min(pollInterval, remainingTime)));
-    }
-    return false;
-}
-/**
- * Check if an element meets a specific state condition.
- */
-async function checkElementCondition(deps, elementId, targetState) {
-    switch (targetState) {
-        case "exists": {
-            const backendNodeId = deps.elementIdGenerator.resolveId(elementId);
-            return backendNodeId !== null;
-        }
-        case "removed": {
-            const backendNodeId = deps.elementIdGenerator.resolveId(elementId);
-            if (backendNodeId !== null) {
-                // Re-render to check if it's truly still there
-                await renderActivePage(deps, { detail: "minimal" });
-                return deps.elementIdGenerator.resolveId(elementId) === null;
-            }
-            return true;
-        }
-        case "visible":
-        case "hidden":
-        case "enabled":
-        case "disabled": {
-            // Re-render to get fresh state
-            const representation = await renderActivePage(deps, { detail: "minimal" });
-            const element = representation.interactive.find((el) => el.id === elementId);
-            if (!element) {
-                // Element doesn't exist — "hidden" and "disabled" are satisfied, others not
-                return targetState === "hidden" || targetState === "disabled";
-            }
-            switch (targetState) {
-                case "visible":
-                    return element.state.visible === true;
-                case "hidden":
-                    return element.state.visible === false;
-                case "enabled":
-                    return element.state.enabled === true;
-                case "disabled":
-                    return element.state.enabled === false;
-            }
-            return false;
-        }
-        default:
-            return false;
-    }
-}
 //# sourceMappingURL=interaction.js.map