chromeflow 0.2.0 → 0.2.1

package/CLAUDE.md

@@ -48,7 +48,8 @@ Do NOT ask "should I open the browser?" — just do it. The user expects seamles
         scroll_page("down")                 — reveal off-screen content when target location is unknown
    b. Check results with text, not vision:
         get_page_text()                     — read errors/status after actions
-        wait_for_selector(".success")       — wait for async changes (builds, modals)
+        wait_for_selector(".success")       — wait for a new element to appear
+        wait_for_change(".toast")          — wait for an existing element's content to mutate, then read it (uses MutationObserver, cheaper than polling)
         execute_script("document.title")    — query DOM state programmatically
    c. When an element can't be found or clicked:
         scroll_page("down") and retry      — always try this first
@@ -167,6 +168,8 @@ screenshot to check what happened.
 
 **Waiting for async results** (build, save, deploy): `wait_for_selector(selector, timeout)` — never poll with screenshots.
 
+**Waiting for an existing region to update** (e.g. click Save, then get the confirmation toast; send a chat message, then get the reply): `wait_for_change(selector)` uses a MutationObserver on the element's subtree and returns its new text content as soon as the mutation settles. Prefer this over `wait_for_selector` + `get_page_text` when the element already exists and you just need its next state — one call instead of two, no polling.
+
 **Pre-filling `prompt()` and `confirm()` dialogs**: When a page action will trigger a JS
 dialog (e.g. "Save As" calling `prompt()`), call `set_dialog_response` BEFORE the action:
 ```

package/dist/setup.js

@@ -175,7 +175,9 @@ const CHROMEFLOW_TOOLS = [
   // v0.1.46+
   "type_text",
   // v0.1.57+
-  "inspect_request_headers"
+  "inspect_request_headers",
+  // v0.2.1+
+  "wait_for_change"
 ].map((t) => `mcp__chromeflow__${t}`);
 function patchSettingsLocalJson(cwd) {
   const claudeDir = join(cwd, ".claude");

package/dist/tools/flow.js

@@ -97,6 +97,53 @@ to 15 seconds so the page is checked gently rather than hammered every 500ms.`,
       };
     }
   );
+  server.tool(
+    "wait_for_change",
+    `Block until the element matching \`selector\` mutates, then return its text content.
+Uses a MutationObserver \u2014 no polling, no screenshots. Ideal after an action where you expect
+a specific UI region to update: click Save, then wait_for_change(".toast") to capture the
+confirmation. wait_for_change(".chat-messages") after sending a message to get the reply.
+
+The element must exist at call time (use wait_for_selector first if needed). After the first
+mutation fires, waits a brief settle window (default 150ms) for the update to batch, then
+returns the element's current text with secrets redacted.
+
+Only observes changes within the matched element's subtree. Mutations in deeper shadow roots
+or in sibling elements are not detected. For form inputs whose \`value\` changes without a
+DOM mutation, this won't fire \u2014 use execute_script to read the value directly.`,
+    {
+      selector: z.string().describe(
+        `CSS selector of the element whose changes you want to observe (e.g. '.toast', '.chat-messages', '[role="alert"]')`
+      ),
+      timeout: z.number().optional().describe("Max seconds to wait for a mutation (default 30)"),
+      settle: z.number().optional().describe(
+        "Milliseconds to wait AFTER the first mutation for subsequent mutations to batch (default 150). Increase to 500-1000 if the page renders in multiple rapid steps."
+      )
+    },
+    async ({ selector, timeout = 30, settle }) => {
+      const timeoutMs = timeout * 1e3;
+      const settleMs = settle ?? 150;
+      const response = await bridge.request(
+        { type: "wait_for_change", selector, timeout: timeoutMs, settle: settleMs },
+        timeoutMs + 5e3
+      );
+      const r = response;
+      if (!r.ok) {
+        return { content: [{ type: "text", text: r.message ?? `wait_for_change timed out on "${selector}"` }] };
+      }
+      const preview = (r.text ?? "").slice(0, 5e3);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Element "${selector}" changed.
+
+${preview}`
+          }
+        ]
+      };
+    }
+  );
   server.tool(
     "scroll_to_element",
     `Scroll an element into view by CSS selector or label/text match.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chromeflow",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Browser guidance MCP server for Claude Code — highlights, clicks, fills, and captures from the web so you don't have to.",
   "type": "module",
   "bin": {