chromeflow 0.7.0 → 0.8.0

package/CLAUDE.md

@@ -143,7 +143,13 @@ the image to Claude only.
   auto-saving DataAnnotation form): some auto-save logic diffs against the last-saved
   value and skips no-op writes. To force a real save on each tick without changing
   visible content, toggle a trailing space — add when absent, remove when present.
-  `fill_input` value comparison handles both directions transparently.
+  `fill_input` value comparison handles both directions transparently. **Caveat:**
+  long-running heartbeats that toggle whitespace on a real form field have been
+  observed to drift other fields' React state out of sync (the re-render reset a
+  separate radio's checked state to the form-level store value). For heartbeat
+  loops, prefer writing to `localStorage` via `execute_script` instead — the
+  auto-save handler usually fires on any input event, but `localStorage` writes
+  don't perturb React state at all.
 - After any radio/checkbox click that reveals new fields, call `get_form_fields()` again —
   the inventory will include the new fields and warn if more hidden ones still exist.
 - If a form has collapsible sections, expand them all before calling `get_form_fields()` so
@@ -228,6 +234,14 @@ click_element("Confirm", until_text_contains="Order placed")
 ```
 If success=false: try `react_set_input` to fire the click via the page's own React handler, or use `execute_script("document.querySelector(...).click()")` directly.
 
+**`click_element` timed out (the WS request, not until-polling)**: the message will say "the click MAY have already fired". On a busy React reconciliation, the click does land but the response read can outrun the 30s WS timeout. Don't blindly retry — re-clicking can toggle React radios OFF or fire a duplicate submit. Verify with `get_page_text`, `wait_for_selector`, or `wait_for_text` first; only retry if the page state confirms the click never took effect.
+
+**Modal never opens / submit handler swallowed by stale validation state**: when a Submit button's onClick opens a modal that never renders (e.g. validation thinks the form is incomplete because the form-level React state is stale, but DOM inputs look filled), use `react_call_prop` to call the bypass handler directly:
+```
+react_call_prop("input[name=justification]", "handleForceSubmitConfirmation", ["my justification text"])
+```
+Walks up the React fiber from the selector, finds the nearest component with a prop function of the given name, and calls it with the JSON-serializable args. Returns the component name and stringified return value so you can verify the right handler ran.
+
 **`set_file_input` not committing on rapid back-to-back uploads:**
 The default 3000ms commit-wait is enough for most uploaders. For batch photo uploads on slow react file handlers (eBay's 25-photo carousel, Stripe Connect document upload), increase `wait_ms` to 6000–8000 OR pass `verify_selector` pointing at the thumbnail/Remove-button that should appear:
 ```

package/dist/index.js

@@ -1,12 +1,22 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { WsBridge } from "./ws-bridge.js";
 import { registerBrowserTools } from "./tools/browser.js";
 import { registerHighlightTools } from "./tools/highlight.js";
 import { registerCaptureTools } from "./tools/capture.js";
 import { registerFlowTools } from "./tools/flow.js";
-import { runSetup, runUpdate, runUninstall } from "./setup.js";
+import { runSetup, runUpdate, runUninstall, runDoctor } from "./setup.js";
+const PACKAGE_VERSION = (() => {
+  try {
+    const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
+    return JSON.parse(readFileSync(pkgPath, "utf8")).version;
+  } catch {
+    return "unknown";
+  }
+})();
 if (process.argv[2] === "setup") {
   runSetup().catch((err) => {
     console.error(err);
@@ -22,6 +32,11 @@ if (process.argv[2] === "setup") {
     console.error(err);
     process.exit(1);
   });
+} else if (process.argv[2] === "doctor") {
+  runDoctor(PACKAGE_VERSION).catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
 } else {
   main().catch((err) => {
     console.error("[chromeflow] Fatal error:", err);
@@ -32,12 +47,20 @@ async function main() {
   const bridge = new WsBridge();
   const server = new McpServer({
     name: "chromeflow",
-    version: "0.1.14"
+    version: PACKAGE_VERSION
   });
   registerBrowserTools(server, bridge);
   registerHighlightTools(server, bridge);
   registerCaptureTools(server, bridge);
   registerFlowTools(server, bridge);
+  const registered = server._registeredTools ?? {};
+  const toolNames = Object.keys(registered).sort();
+  console.error(`[chromeflow] v${PACKAGE_VERSION} \u2014 registered ${toolNames.length} tools`);
+  if (toolNames.length > 0) {
+    console.error(`[chromeflow] tools: ${toolNames.join(", ")}`);
+  } else {
+    console.error(`[chromeflow] WARNING: no tools registered. Try \`npx chromeflow doctor\`.`);
+  }
   server.prompt(
     "chromeflow-status",
     "Check if the chromeflow Chrome extension is connected and which tab is active",
@@ -88,5 +111,5 @@ ${tabList}`
   );
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error("[chromeflow] MCP server running. Waiting for Claude...");
+  console.error(`[chromeflow] v${PACKAGE_VERSION} MCP server running. Waiting for Claude...`);
 }

package/dist/setup.js

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "fs";
 import { homedir } from "os";
 import { join, resolve, dirname } from "path";
 import { fileURLToPath } from "url";
@@ -180,7 +180,11 @@ const CHROMEFLOW_TOOLS = [
   // v0.6.0+
   "find_text",
   "find_input",
-  "wait_for_text"
+  "wait_for_text",
+  // v0.6.5+
+  "react_set_input",
+  // v0.8.0+
+  "react_call_prop"
 ].map((t) => `mcp__chromeflow__${t}`);
 function patchSettingsLocalJson(cwd) {
   const claudeDir = join(cwd, ".claude");
@@ -385,7 +389,104 @@ async function runUpdate() {
   }
   console.log("Done.\n");
 }
+function readGlobalChromeflowVersion() {
+  try {
+    const root = execSync("npm root -g", { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    const pkgPath = join(root, "chromeflow", "package.json");
+    if (!existsSync(pkgPath)) return null;
+    return JSON.parse(readFileSync(pkgPath, "utf8")).version;
+  } catch {
+    return null;
+  }
+}
+function listNpxCachedChromeflowVersions() {
+  const cacheDir = join(HOME, ".npm", "_npx");
+  if (!existsSync(cacheDir)) return [];
+  const out = [];
+  let entries;
+  try {
+    entries = readdirSync(cacheDir);
+  } catch {
+    return [];
+  }
+  for (const hash of entries) {
+    const pkgPath = join(cacheDir, hash, "node_modules", "chromeflow", "package.json");
+    if (!existsSync(pkgPath)) continue;
+    try {
+      const v = JSON.parse(readFileSync(pkgPath, "utf8")).version;
+      out.push({ hash, version: v });
+    } catch {
+    }
+  }
+  return out;
+}
+async function fetchLatestPublishedVersion() {
+  try {
+    const res = await fetch("https://registry.npmjs.org/chromeflow/latest");
+    if (!res.ok) return null;
+    const json = await res.json();
+    return json.version ?? null;
+  } catch {
+    return null;
+  }
+}
+function compareSemver(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const da = pa[i] ?? 0;
+    const db = pb[i] ?? 0;
+    if (da !== db) return da - db;
+  }
+  return 0;
+}
+async function runDoctor(runningVersion) {
+  console.log("\nChromeflow Doctor\n" + "\u2500".repeat(40));
+  const installScript = fileURLToPath(import.meta.url);
+  console.log(`Running version:  ${runningVersion}`);
+  console.log(`Running from:     ${installScript}`);
+  const globalVersion = readGlobalChromeflowVersion();
+  console.log(`Global install:   ${globalVersion ?? "(none \u2014 not installed via `npm install -g chromeflow`)"}`);
+  const npxCaches = listNpxCachedChromeflowVersions();
+  if (npxCaches.length === 0) {
+    console.log(`npx cache:        (empty)`);
+  } else {
+    console.log(`npx cache (${npxCaches.length} ${npxCaches.length === 1 ? "entry" : "entries"}):`);
+    for (const c of npxCaches) console.log(`  ${c.hash}: ${c.version}`);
+  }
+  const latest = await fetchLatestPublishedVersion();
+  console.log(`Latest on npm:    ${latest ?? "(unable to reach https://registry.npmjs.org)"}`);
+  const allKnown = [runningVersion];
+  if (globalVersion) allKnown.push(globalVersion);
+  for (const c of npxCaches) allKnown.push(c.version);
+  const stale = latest ? allKnown.some((v) => v !== "unknown" && compareSemver(v, latest) < 0) : false;
+  if (stale) {
+    console.log("\n\u26A0 Stale chromeflow install detected.");
+    console.log("  Reinstall recipe:");
+    console.log("    npm uninstall -g chromeflow");
+    console.log("    rm -rf ~/.npm/_npx");
+    console.log("    npm install -g chromeflow@latest");
+    console.log("  Then restart Claude Code so the MCP server picks up the new version.");
+  } else if (latest && compareSemver(runningVersion, latest) === 0) {
+    console.log("\n\u2713 chromeflow is up to date.");
+  } else if (!latest) {
+    console.log("\n? Could not check the registry; skipping freshness check.");
+  } else {
+    console.log("\n\u2713 Running version is current.");
+  }
+  console.log("\nTools shipped in this build (from setup manifest):");
+  const toolNames = CHROMEFLOW_TOOLS.map((t) => t.replace("mcp__chromeflow__", ""));
+  console.log("  " + toolNames.join(", "));
+  console.log(`  (${toolNames.length} tools)`);
+  console.log("\nIf chromeflow tools are missing in Claude Code:");
+  console.log("  1. Restart Claude Code (the MCP server is started at session start).");
+  console.log("  2. If still missing, run the reinstall recipe above.");
+  console.log("  3. Confirm the MCP startup log shows the version banner");
+  console.log(`     ([chromeflow] v${latest ?? "X.Y.Z"} \u2014 registered N tools).`);
+  console.log("");
+}
 export {
+  runDoctor,
   runSetup,
   runUninstall,
   runUpdate

package/dist/tools/browser.js

@@ -323,6 +323,39 @@ Returns the matched element's tag/name/id/type so you can verify it was the righ
       };
     }
   );
+  server.tool(
+    "react_call_prop",
+    `Walk up the React fiber from a DOM element and call a named prop on the nearest component that has it. Use this as an escape hatch when the UI swallows clicks or a modal never renders \u2014 e.g. calling handleForceSubmitConfirmation directly to bypass a stuck submit modal.
+
+Common cases:
+- A submit button whose onClick opens a modal that never appears (validation thinks the form is incomplete because the form-level state is stale, even though the inputs look filled). Walk up to the page-level component and call the bypass handler directly.
+- An onChange handler that the synthetic-event path didn't reach (when click_element fired but React's form-level store wasn't updated).
+
+args MUST be JSON-serializable (primitives, arrays, plain objects). Functions, DOM nodes, and Promises cannot be passed in.
+
+Returns the component name (when available), the fiber depth where the prop was found, and a stringified version of the return value. If the prop function returned a Promise, react_call_prop awaits it before returning.`,
+    {
+      selector: z.string().describe(`CSS selector of any element inside the target component's subtree (e.g. 'input[name="justification"]', '#submit-button')`),
+      prop_name: z.string().describe("Name of the prop function to call (e.g. 'handleForceSubmitConfirmation', 'onChange', 'onSubmit')"),
+      args: z.array(z.any()).optional().describe("Arguments to pass; must be JSON-serializable (primitives, arrays, plain objects). Default: empty."),
+      max_depth: z.number().int().min(1).optional().describe("How many fiber levels to walk up before giving up (default 30)"),
+      frame: z.string().optional().describe('Optional CSS selector for a same-origin iframe whose contents contain the element (e.g. "iframe.se-rte-frame"). Cross-origin iframes are not supported.')
+    },
+    async ({ selector, prop_name, args = [], max_depth = 30, frame }) => {
+      const response = await bridge.request({
+        type: "react_call_prop",
+        selector,
+        prop_name,
+        args,
+        max_depth,
+        frame
+      }, 3e4);
+      const r = response;
+      return {
+        content: [{ type: "text", text: r.message ?? (r.success ? "Called" : "Failed to call prop") }]
+      };
+    }
+  );
   server.tool(
     "execute_script",
     `Execute JavaScript in the current page's context and return the result. Use for reading framework state or DOM properties not visible in text \u2014 prefer get_page_text for visible content. Top-level \`return\` and \`await\` are supported.

package/dist/tools/flow.js

@@ -37,10 +37,30 @@ If the until-condition is not met within until_timeout_ms (default 5000ms), clic
     },
     async ({ textHint, nth, until_selector, until_url_contains, until_text_contains, until_timeout_ms }) => {
       const wsTimeout = Math.max(3e4, (until_timeout_ms ?? 0) + 1e4);
-      const response = await bridge.request(
-        { type: "click_element", textHint, nth, until_selector, until_url_contains, until_text_contains, until_timeout_ms },
-        wsTimeout
-      );
+      let response;
+      try {
+        response = await bridge.request(
+          { type: "click_element", textHint, nth, until_selector, until_url_contains, until_text_contains, until_timeout_ms },
+          wsTimeout
+        );
+      } catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        if (errMsg.includes("timed out")) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Could not confirm click on "${textHint}": ${errMsg}. The click MAY have already fired \u2014 the page just took longer than ${wsTimeout}ms to respond. Verify with get_page_text or wait_for_selector before retrying. Re-clicking can toggle the wrong way on React-controlled radios.`
+              }
+            ]
+          };
+        }
+        return {
+          content: [
+            { type: "text", text: `Could not click "${textHint}": ${errMsg}` }
+          ]
+        };
+      }
       const r = response;
       if (!r.success) {
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chromeflow",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "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": {