chromeflow 0.1.21 → 0.1.23

package/CLAUDE.md

@@ -44,15 +44,16 @@ Do NOT ask "should I open the browser?" — just do it. The user expects seamles
 
 ```
 1. show_guide_panel(title, steps[])          — show the full plan upfront
-2. open_page(url)                            — navigate to the right page
+2. open_page(url)                            — navigate to the right page (add new_tab=true to keep current tab open)
    mark_step_done(0)                         — ALWAYS mark step 0 done right after open_page succeeds
 3. For each step:
    a. Claude acts directly:
         click_element("Save")               — press buttons/links Claude can press
         wait_for_selector(".success") or get_page_text() — ALWAYS confirm after click; click_element returns after 600ms regardless of outcome
-        fill_input("Product name", "Pro")   — fill fields Claude knows the answer to
+        fill_input("Product name", "Pro")   — fill fields Claude knows the answer to (works on React, CodeMirror, and contenteditable)
         clear_overlays()                    — call this immediately after fill_input succeeds
         scroll_page("down")                 — reveal off-screen content then retry
+        scroll_to_element("label text")     — jump directly to a known field instead of guessing pixel scroll amount
    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)
@@ -100,6 +101,17 @@ After a secret key or API key is revealed:
 
 Use the absolute path for `envPath` — it's the Claude Code working directory + `/.env`.
 
+## Working with complex forms
+- Before filling a large or unfamiliar form, call `get_form_fields()` to get a full inventory of every field (type, label, current value, vertical position). This prevents missing fields and avoids positional guesswork.
+- `fill_input` works on React-controlled inputs, contenteditable (Stripe, Notion), and **CodeMirror 6 editors** — it auto-detects all three. No `execute_script` workaround needed.
+- `scroll_to_element("label text or #selector")` scrolls a specific field into view without guessing pixel offsets.
+- For multi-session tasks (long forms that may exceed context), call `save_page_state()` as a checkpoint. A future session can call `restore_page_state()` to reload all field values from the saved snapshot.
+
+## Working with multiple tabs
+- `open_page(url, new_tab=true)` opens a URL without losing the current tab.
+- `list_tabs()` shows all open tabs with their index, title, and URL.
+- `switch_to_tab("1")` switches by tab number; `switch_to_tab("form")` matches by URL or title substring.
+
 ## Error handling
 - After any action → `get_page_text()` to check for errors (not `take_screenshot`)
 - After `click_element("Save")` / form submission → use `get_page_text()` or `wait_for_selector` to confirm. Never use `wait_for_navigation` — most form saves don't navigate.

package/README.md

@@ -25,12 +25,11 @@ This:
 - Adds a hint to `~/.claude/CLAUDE.md` so Claude will suggest `npx chromeflow setup` in any project that isn't yet configured
 - Pre-approves Chromeflow tools in `.claude/settings.local.json` (no per-action prompts)
 
-**2. Load the Chrome extension** (one time):
+**2. Install the Chrome extension** (one time):
 
-The setup wizard opens `chrome://extensions` for you. Then:
-1. Enable **Developer mode** (top-right toggle)
-2. Click **Load unpacked**
-3. Select the path printed by the setup wizard
+The setup wizard opens the Chrome Web Store for you — click **Add to Chrome**.
+
+Or install directly: [chromewebstore.google.com/detail/chromeflow/lkdchdgkbkodliefobkkhiegjdiidime](https://chromewebstore.google.com/detail/chromeflow/lkdchdgkbkodliefobkkhiegjdiidime)
 
 The extension persists across Chrome restarts. You only do this once.
 
@@ -88,7 +87,7 @@ npm run dev:mcp   # watches mcp-server
 npm run dev:ext   # watches extension
 ```
 
-After rebuilding the extension, click **Update** on `chrome://extensions`.
+After rebuilding the extension, reload it from `chrome://extensions`.
 
 ## Requirements
 

package/dist/setup.js

@@ -183,13 +183,14 @@ function patchSettingsLocalJson(cwd) {
   writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
   return "updated";
 }
-function tryOpenExtensionsPage() {
+const STORE_URL = "https://chromewebstore.google.com/detail/chromeflow/lkdchdgkbkodliefobkkhiegjdiidime";
+function tryOpenStorePage() {
   try {
-    execSync('open -a "Google Chrome" "chrome://extensions"', { stdio: "ignore" });
+    execSync(`open "${STORE_URL}"`, { stdio: "ignore" });
     return true;
   } catch {
     try {
-      execSync('xdg-open "chrome://extensions"', { stdio: "ignore" });
+      execSync(`xdg-open "${STORE_URL}"`, { stdio: "ignore" });
       return true;
     } catch {
       return false;
@@ -241,17 +242,14 @@ async function runSetup() {
   } else {
     console.log("\u2713 Added chromeflow tools to .claude/settings.local.json (no approval prompts)");
   }
-  console.log("\nChrome extension (one-time manual step):");
-  const opened = tryOpenExtensionsPage();
+  console.log("\nChrome extension (one-time step):");
+  const opened = tryOpenStorePage();
   if (opened) {
-    console.log("  Opened chrome://extensions in Chrome.");
+    console.log("  Opened Chrome Web Store \u2014 click 'Add to Chrome' to install.");
   } else {
-    console.log("  Open chrome://extensions in Chrome.");
+    console.log(`  Install from the Chrome Web Store:
+  ${STORE_URL}`);
   }
-  const extensionDistPath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "extension", "dist");
-  console.log("  1. Enable Developer mode (top-right toggle)");
-  console.log("  2. Click 'Load unpacked'");
-  console.log(`  3. Select: ${extensionDistPath}`);
   const globalResult = patchGlobalClaudeMd();
   if (globalResult === "already-present") {
     console.log("\u2713 ~/.claude/CLAUDE.md already has chromeflow hint");

package/dist/tools/browser.js

@@ -2,12 +2,45 @@ import { z } from "zod";
 function registerBrowserTools(server, bridge) {
   server.tool(
     "open_page",
-    "Navigate the user's active Chrome tab to a URL",
-    { url: z.string().url().describe("The URL to navigate to") },
-    async ({ url }) => {
-      await bridge.request({ type: "navigate", url });
+    "Navigate to a URL. By default reuses the active tab. Set new_tab=true to open alongside the current tab without losing it.",
+    {
+      url: z.string().url().describe("The URL to navigate to"),
+      new_tab: z.boolean().optional().describe("Open in a new tab instead of replacing the current one (default false)")
+    },
+    async ({ url, new_tab }) => {
+      await bridge.request({ type: "navigate", url, newTab: new_tab ?? false });
       return {
-        content: [{ type: "text", text: `Navigated to ${url}` }]
+        content: [{ type: "text", text: `Navigated to ${url}${new_tab ? " (new tab)" : ""}` }]
+      };
+    }
+  );
+  server.tool(
+    "switch_to_tab",
+    `Switch the active tab to a different open tab. Use this after open_page(new_tab=true) to switch back to the original tab, or to jump between tabs.
+Accepts: a tab number (1-based), a URL substring, or a title substring.
+Example: switch_to_tab("1") to go to the first tab, switch_to_tab("form") to find a tab whose URL or title contains "form".`,
+    {
+      query: z.string().describe("Tab number (1-based), URL substring, or title substring to match")
+    },
+    async ({ query }) => {
+      await bridge.request({ type: "switch_to_tab", query });
+      return {
+        content: [{ type: "text", text: `Switched to tab matching "${query}"` }]
+      };
+    }
+  );
+  server.tool(
+    "list_tabs",
+    "List all open tabs in the current window with their index, title, and URL. Use this before switch_to_tab if you're not sure which tab to switch to.",
+    {},
+    async () => {
+      const response = await bridge.request({ type: "list_tabs" });
+      if (response.type !== "tabs_response") throw new Error("Unexpected response");
+      const tabs = response.tabs;
+      const lines = tabs.map((t) => `${t.index}. ${t.active ? "[active] " : ""}${t.title} \u2014 ${t.url}`);
+      return {
+        content: [{ type: "text", text: `Open tabs:
+${lines.join("\n")}` }]
       };
     }
   );
@@ -72,6 +105,30 @@ Use these exact x/y values in highlight_region.` }]
       };
     }
   );
+  server.tool(
+    "get_form_fields",
+    `Get a full inventory of all form fields on the page: inputs, textareas, selects, and CodeMirror editors.
+Run this once at the start of a complex form to understand what fields exist, their labels, current values, and vertical positions.
+Returns fields sorted by their y-position on the page (top to bottom).
+Unlike get_elements, this includes ALL fields (even far below the fold) and is not limited to 60 items.`,
+    {},
+    async () => {
+      const response = await bridge.request({ type: "get_form_fields" });
+      if (response.type !== "form_fields_response") throw new Error("Unexpected response");
+      const fields = response.fields;
+      if (fields.length === 0) {
+        return { content: [{ type: "text", text: "No form fields found on page." }] };
+      }
+      const lines = fields.map((f) => {
+        const val = f.value ? ` [currently: "${f.value}"]` : "";
+        return `${f.index}. [${f.type}] "${f.label}"${val} \u2014 y:${f.y}`;
+      });
+      return {
+        content: [{ type: "text", text: `Form fields (${fields.length} total, sorted top-to-bottom):
+${lines.join("\n")}` }]
+      };
+    }
+  );
   server.tool(
     "execute_script",
     `Execute JavaScript in the current page's context and return the result as a string.

package/dist/tools/capture.js

@@ -1,5 +1,8 @@
 import { z } from "zod";
 import { appendFileSync, readFileSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+const PAGE_STATE_FILE = join(tmpdir(), "chromeflow_page_state.json");
 function registerCaptureTools(server, bridge) {
   server.tool(
     "fill_input",
@@ -72,6 +75,44 @@ Only use take_screenshot when you need to locate an element's pixel position for
       };
     }
   );
+  server.tool(
+    "save_page_state",
+    `Snapshot the current values of all form fields (inputs, textareas, checkboxes, selects, CodeMirror editors) to a local file.
+Use this before a context window runs out or any time you want a checkpoint mid-form.
+A future session can call restore_page_state to pick up exactly where you left off.`,
+    {},
+    async () => {
+      const response = await bridge.request({ type: "save_page_state" });
+      if (response.type !== "save_state_response") throw new Error("Unexpected response");
+      const state = response.state;
+      writeFileSync(PAGE_STATE_FILE, JSON.stringify(state, null, 2), "utf-8");
+      return {
+        content: [{ type: "text", text: `Saved ${state.length} field values to ${PAGE_STATE_FILE}. Call restore_page_state in a future session to reload them.` }]
+      };
+    }
+  );
+  server.tool(
+    "restore_page_state",
+    `Restore form field values from a previously saved snapshot (created by save_page_state).
+Use this at the start of a new session when resuming a long form-filling task.
+The snapshot is read from the local temp file written by save_page_state.`,
+    {},
+    async () => {
+      let state;
+      try {
+        state = JSON.parse(readFileSync(PAGE_STATE_FILE, "utf-8"));
+      } catch {
+        return {
+          content: [{ type: "text", text: `No saved page state found at ${PAGE_STATE_FILE}. Call save_page_state first.` }]
+        };
+      }
+      const response = await bridge.request({ type: "restore_page_state", state });
+      const msg = response.message ?? "Done";
+      return {
+        content: [{ type: "text", text: msg }]
+      };
+    }
+  );
   server.tool(
     "write_to_env",
     "Write a key=value pair to a .env file. Use this after capturing an API key or ID from the page.",

package/dist/tools/flow.js

@@ -95,6 +95,19 @@ to 15 seconds so the page is checked gently rather than hammered every 500ms.`,
       };
     }
   );
+  server.tool(
+    "scroll_to_element",
+    `Scroll an element into view by CSS selector or label/text match.
+Use this instead of guessing scroll amounts when you know which field or section you need to reach.
+Examples: scroll_to_element("#submit-btn"), scroll_to_element("Billing address"), scroll_to_element(".cm-editor")`,
+    {
+      query: z.string().describe("CSS selector (e.g. '#my-input', '.section-header') or visible text / label to search for")
+    },
+    async ({ query }) => {
+      await bridge.request({ type: "scroll_to_element", query });
+      return { content: [{ type: "text", text: `Scrolled to element matching "${query}".` }] };
+    }
+  );
   server.tool(
     "mark_step_done",
     "Mark a step in the guide panel as completed (shows a green check). Call this after wait_for_click resolves.",

package/package.json

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