chromeflow 0.2.3 → 0.4.0

package/CLAUDE.md

@@ -34,15 +34,19 @@ Do NOT ask "should I open the browser?" — just do it. The user expects seamles
 ## Guided flow pattern
 
 ```
-1. open_page(url)                            — navigate to the right page (add new_tab=true to keep current tab open)
+1. open_page(url)                            — navigate to the right page (add new_tab=true to keep current tab open; add background=true to keep the current tab focused if its form auto-saves on blur)
 2. For each step:
    a. Claude acts directly:
         click_element("Save")               — press buttons/links Claude can press
-        get_page_text() or wait_for_selector(".success") — ALWAYS confirm after click; click_element returns after 600ms regardless of outcome
-        fill_form([{label, value}, ...])    — fill multiple fields in one call; prefer over repeated fill_input
-        fill_input("Product name", "Pro")   — fill a single field (works on React, CodeMirror, and contenteditable)
+        click_element("Save", until_selector=".success-toast")  — when synthetic clicks may silently no-op on a React-heavy site, require an observable post-click condition (or until_url_contains / until_text_contains)
+        get_page_text() or wait_for_selector(".success") — confirm after click without an until-clause; click_element returns after 600ms regardless of outcome unless until_* was used
+        fill_form([{label, value}, ...], exact=true)  — fill multiple fields in one call; pass exact=true on dense forms to refuse fuzzy text-walk matches
+        fill_input("Product name", "Pro")   — fill a single field (works on React, CodeMirror, and contenteditable). Always check the response — it names the matched element so you can spot wrong-field matches
+        fill_input("Rate", "5", exact=true) — exact-match mode for short generic labels that may collide with neighbouring fields
+        react_set_input("input[name=email]", "x@y") — for inputs where fill_input fails (or for iframe-hosted inputs via frame=...) — handles the prototype-from-instance gotcha automatically
         type_text("hello world")            — type via trusted keyboard events (use when fill_input fails isTrusted checks)
-        set_file_input("Upload", "/abs/path/to/file.zip") — upload a file to a file input (even hidden inputs)
+        type_text("description", frame="iframe.se-rte")  — type into a same-origin iframe's contenteditable (eBay description editor pattern)
+        set_file_input("Upload", "/abs/path/to/file.zip") — upload a file; returns success only after the upload is observably committed (no manual sleep needed between rapid uploads)
         clear_overlays()                    — call this immediately after fill_input/fill_form succeeds
         scroll_to_element("label text")     — jump directly to a known field; prefer this over scroll_page when the target is known
         scroll_page("down")                 — reveal off-screen content when target location is unknown
@@ -50,7 +54,7 @@ Do NOT ask "should I open the browser?" — just do it. The user expects seamles
         get_page_text()                     — read errors/status after actions
         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
+        execute_script("return await fetch('/api/x').then(r => r.json())")  — top-level await is supported, no window.__variable + sleep dance needed
    c. When an element can't be found or clicked:
         scroll_page("down") and retry      — always try this first
         get_elements()                      — get EXACT DOM coords when needed
@@ -154,19 +158,48 @@ screenshot to check what happened.
 **Multiple elements with the same label** (e.g. many "Remove" buttons):
 `click_element("Remove", nth=3)` — use `nth` (1-based) to target the specific one by order top-to-bottom. Check `get_form_fields` or `get_page_text` first to determine which index corresponds to the right section.
 
+**`fill_input` matched the wrong field** (always read the response — it names the matched element):
+- If you wanted "Ad rate" and got back `<input name="title">`, the fuzzy text walker latched onto a neighbour. Retry with `exact=true` and a more specific hint, or use `react_set_input(selector, value)` with a precise CSS selector.
+- The match-strength is reported as `aria-eq`, `placeholder-eq`, `name-eq`, `id-eq`, `label-text-eq`, or fuzzier kinds. Anything labeled `fuzzy-text-walk` or `*-includes` is the lowest-confidence kind — verify the matched element really was what you wanted.
+
 **`fill_input` not found or rejected by the page:**
 1. `click_element(hint)` to focus the field, then retry `fill_input`
-2. If the site rejects programmatic input (isTrusted check, shadow DOM, custom editors):
+2. `react_set_input("input[name=...]", value)` — uses the input's own prototype to set the value, dispatches input/change. Handles the "Illegal invocation" iframe gotcha and the prototype-from-instance ceremony for you.
+3. If the site rejects programmatic input (isTrusted check, shadow DOM, custom editors):
    - `click_element(hint)` to focus the field
    - `execute_script("document.execCommand('selectAll')")` to clear existing content
    - `type_text("new value")` — uses CDP trusted keyboard events that pass isTrusted checks
-3. `find_and_highlight(hint, "Click here — I'll fill it in")` (no `valueToType`) then
+4. For iframe-hosted contenteditable rich-text editors (eBay's description, etc.):
+   - `type_text("body content", frame="iframe.selector")` — same-origin only. Focuses the iframe's contenteditable, types via CDP, dispatches input/change in the iframe's context so React reads the new value.
+5. `find_and_highlight(hint, "Click here — I'll fill it in")` (no `valueToType`) then
    `wait_for_click()` — the user's click focuses the field and `fill_input`'s active-element
    fallback fills it automatically
-4. Call `clear_overlays()` after `fill_input` succeeds
-5. Only use `valueToType` when the user must personally type the value (password, personal data)
+6. Call `clear_overlays()` after `fill_input` succeeds
+7. Only use `valueToType` when the user must personally type the value (password, personal data)
 
-**Waiting for async results** (build, save, deploy): `wait_for_selector(selector, timeout)` — never poll with screenshots.
+**`click_element` returned success but the page didn't change** (common on React-heavy sites where synthetic clicks no-op):
+Pass an `until_*` clause to require an observable post-click condition. `click_element` returns success=false if the condition isn't met within `until_timeout_ms` (default 5000):
+```
+click_element("List with displayed fees", until_url_contains="/listing-published")
+click_element("Save", until_selector=".success-toast")
+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.
+
+**`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:
+```
+set_file_input("Photos", "/path/1.jpg", verify_selector=".photo-thumbnail:nth-of-type(1)")
+set_file_input("Photos", "/path/2.jpg", verify_selector=".photo-thumbnail:nth-of-type(2)")
+```
+The page-level file count is reported in the response — use it to spot uploaders that consume-and-reset the input vs uploaders that keep the file there.
+
+**Waiting for async results** (build, save, deploy): `wait_for_selector(selector, timeout)` — never poll with screenshots. `wait_for_selector` pierces open shadow roots, so a selector inside a web component (Outlier task UI, Lit/Stencil widget) matches without ceremony.
+
+**Waiting for a shadow host's tree to attach** (e.g. SPA route flips where `<my-host>` appears 10s before its shadow content hydrates, and `wait_for_selector("my-host")` resolves while `host.shadowRoot` is still null): pass `shadow_root=true`. The wait then requires the matched element's `.shadowRoot` to be non-null, not just for the host element to exist.
+```
+wait_for_selector("iframe", shadow_root=true)   — wait until the iframe both exists AND has an attached shadowRoot
+```
 
 **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.
 
@@ -179,26 +212,25 @@ set_dialog_response(type="confirm", value="true")          — next confirm() re
 Then trigger the action (e.g. `click_element("Save As")`). The response is consumed once.
 
 **React Select / custom styled dropdowns** (e.g. "Select..." components on DataAnnotation):
-`click_element` and `fill_input` do NOT work on these — they intercept native events. Use
-`execute_script` with the hidden combobox input approach (most reliable):
+`click_element` and `fill_input` do NOT work on these — they intercept native events. The cleanest path is `react_set_input` (which handles the prototype-from-instance setter for you) followed by a click on the filtered option:
+
+```
+1. react_set_input('input[id*="react-select-3-input"]', "Target Option")
+   — sets the hidden combobox input via its own prototype's value-setter and dispatches the input event React's onChange listens for
+2. (300ms pause for the dropdown to filter)
+3. execute_script("document.querySelector('[id*=\"react-select-3-option-0\"]').click()")
+4. Verify the control shows the selected value:
+   execute_script("document.querySelector('[class*=\"singleValue\"]').textContent.trim()")
+```
+
+If you must hand-roll this with `execute_script` (older React-Select versions, weird custom wrappers), prefer reading the prototype FROM the instance to avoid "Illegal invocation" inside iframes:
 
 ```js
-// 1. Find the hidden combobox input (each React Select has one: input[id*="react-select-N-input"])
 var input = document.querySelector('input[id*="react-select-3-input"]');
 input.focus();
-
-// 2. Set value via native setter to trigger React's onChange
-var setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set;
+var setter = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(input), 'value').set;
 setter.call(input, 'Target Option');
-input.dispatchEvent(new Event('input', {bubbles: true}));
-
-// 3. Wait 300ms for the dropdown to filter, then click the first matching option
-// (run this as a separate execute_script call after a brief pause)
-var option = document.querySelector('[id*="react-select-3-option-0"]');
-if (option) option.click();
-
-// 4. Verify — the control div should show the selected value
-document.querySelector('[class*="singleValue"]').textContent.trim();
+input.dispatchEvent(new Event('input', { bubbles: true }));
 ```
 
 Fallback if the combobox approach doesn't work (older React Select versions):

package/dist/tools/browser.js

@@ -6,15 +6,18 @@ import { execSync } from "child_process";
 function registerBrowserTools(server, bridge) {
   server.tool(
     "open_page",
-    "Navigate to a URL. By default reuses the active tab. Set new_tab=true to open alongside the current tab without losing it. After navigating, call get_page_text to read the page \u2014 do NOT take a screenshot.",
+    `Navigate to a URL. By default reuses the active tab. Set new_tab=true to open alongside the current tab without losing it. After navigating, call get_page_text to read the page \u2014 do NOT take a screenshot.
+
+Set background=true (only with new_tab=true) to open the new tab WITHOUT switching focus to it. Use this when the current tab has a partially-filled form whose page auto-saves on focus loss (e.g. eBay seller listings) \u2014 switching away would trigger the auto-save and corrupt the in-progress draft.`,
     {
       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)")
+      new_tab: z.boolean().optional().describe("Open in a new tab instead of replacing the current one (default false)"),
+      background: z.boolean().optional().describe("If new_tab=true, do not switch focus to the new tab. Default false. Ignored when new_tab is false.")
     },
-    async ({ url, new_tab }) => {
-      await bridge.request({ type: "navigate", url, newTab: new_tab ?? false });
+    async ({ url, new_tab, background }) => {
+      await bridge.request({ type: "navigate", url, newTab: new_tab ?? false, background: background ?? false });
       return {
-        content: [{ type: "text", text: `Navigated to ${url}${new_tab ? " (new tab)" : ""}` }]
+        content: [{ type: "text", text: `Navigated to ${url}${new_tab ? background ? " (new background tab)" : " (new tab)" : ""}` }]
       };
     }
   );
@@ -259,15 +262,21 @@ Unlike fill_input (which sets .value programmatically), this produces real keyst
 - fill_input fails because the site validates event.isTrusted (e.g. Outlier, DataAnnotation code editors)
 - The target is a shadow DOM input, custom web component, or heavily guarded editor
 - You need to type into a CodeMirror/Monaco/Ace editor that rejects programmatic value changes
+- The target lives inside a same-origin iframe (e.g. eBay's "se-rte" rich-text description editor) \u2014 pass the iframe's CSS selector via the \`frame\` parameter
 
 Usage: first click_element or execute_script to focus the target field, then call type_text with the content.
-To clear existing content before typing, use execute_script("document.execCommand('selectAll')") first.`,
+To clear existing content before typing, use execute_script("document.execCommand('selectAll')") first.
+
+For iframe contenteditables: pass \`frame\` (a CSS selector for the iframe). type_text descends into the iframe, focuses its first editable element, types via CDP, then dispatches input/change in the iframe's context so React picks up the change. Same-origin iframes only \u2014 cross-origin iframes will return an error.`,
     {
-      text: z.string().describe("The text to type into the focused element")
+      text: z.string().describe("The text to type into the focused element"),
+      frame: z.string().optional().describe(
+        "CSS selector for an iframe whose contents you want to type into (e.g. 'iframe.se-rte-frame__summary'). Same-origin only. Before typing, the first contenteditable/input inside the iframe is focused; after typing, input/change events are dispatched in the iframe's context."
+      )
     },
-    async ({ text }) => {
+    async ({ text, frame }) => {
       const timeoutMs = Math.max(3e4, text.length * 90 + 15e3);
-      const response = await bridge.request({ type: "type_text", text }, timeoutMs);
+      const response = await bridge.request({ type: "type_text", text, frame }, timeoutMs);
       const r = response;
       return {
         content: [{ type: "text", text: r.message ?? (r.success ? "Text typed successfully" : "Failed to type text") }]
@@ -278,29 +287,65 @@ To clear existing content before typing, use execute_script("document.execComman
     "set_file_input",
     `Upload a file to a file input field. Works even when the input is visually hidden behind a custom drag-and-drop zone.
 Uses Chrome DevTools Protocol to set the file \u2014 the only way to bypass the browser's file-input script restriction.
-hint: label text or name of the file input (or empty string to target the first file input on the page).
-file_path: absolute path to the file on the local filesystem (e.g. /Users/you/Downloads/task.zip).
-After calling this, verify the upload was accepted: use execute_script to check that the input's files.length > 0, or use get_page_text to look for a success indicator (e.g. a Remove button appearing). If not accepted, call set_file_input again \u2014 occasional React timing issues may require a retry.`,
+
+Returns success=true ONLY if an observable change is detected within wait_ms: either the page-level file count goes up, or the file is consumed by the page's React handler (input is reset), or verify_selector matches a new element on the page. Otherwise success=false with a clear message \u2014 typically because the page rejected the file (size/type) or the React handler hasn't run yet.
+
+For rapid batch uploads (multiple set_file_input calls in a row), this commit-wait prevents the second CDP call from overwriting the first before React reads it \u2014 no manual sleep needed between calls.
+
+hint: label text, name, or CSS selector of the file input (or empty string to target the first file input on the page).
+file_path: absolute path to the file on the local filesystem (e.g. /Users/you/Downloads/task.zip).`,
     {
       hint: z.string().describe("Label text, name, or surrounding text of the file input. Use empty string to target the first file input on the page."),
-      file_path: z.string().describe("Absolute path to the file to upload (e.g. /Users/you/Downloads/task.zip)")
+      file_path: z.string().describe("Absolute path to the file to upload (e.g. /Users/you/Downloads/task.zip)"),
+      wait_ms: z.number().int().min(0).optional().describe("How long to wait for an observable change after setting the file (default 3000). Increase for slow uploaders that take a moment to render thumbnails."),
+      verify_selector: z.string().optional().describe('Optional CSS selector that should appear after a successful upload (e.g. ".photo-thumbnail", "[data-uploaded=true]"). When matched, set_file_input returns success immediately.')
     },
-    async ({ hint, file_path }) => {
-      const response = await bridge.request({ type: "set_file_input", hint, filePath: file_path });
+    async ({ hint, file_path, wait_ms, verify_selector }) => {
+      const wsTimeout = Math.max(3e4, (wait_ms ?? 3e3) + 1e4);
+      const response = await bridge.request(
+        { type: "set_file_input", hint, filePath: file_path, waitMs: wait_ms, verifySelector: verify_selector },
+        wsTimeout
+      );
       const r = response;
       return {
         content: [{ type: "text", text: r.message ?? (r.success ? "File set successfully" : "Failed to set file") }]
       };
     }
   );
+  server.tool(
+    "react_set_input",
+    `Set the value of a React-controlled input via the native value-setter, dispatching the input/change events that React's onChange handler listens for.
+
+Use this instead of writing your own \`Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set\` script \u2014 this helper handles the prototype-from-instance gotcha automatically (inputs inside iframes have their own HTMLInputElement constructor, and using the outer-window prototype throws "Illegal invocation").
+
+Common cases:
+- A standard input that fill_input fails on because the page validates event.isTrusted or uses an exotic React Hook Form setup.
+- An input inside a same-origin iframe (pass frame="iframe.selector").
+- A hidden React-Select combobox input (selector='input[id*="react-select-3-input"]').
+
+Returns the matched element's tag/name/id/type so you can verify it was the right field, and the read-back value so you can spot when React rejected the new value.`,
+    {
+      selector: z.string().describe("CSS selector of the input to set (e.g. 'input[name=email]', '#promoted-rate-input')"),
+      value: z.string().describe("The value to set"),
+      frame: z.string().optional().describe('Optional CSS selector for a same-origin iframe whose contents contain the input (e.g. "iframe.se-rte-frame"). Cross-origin iframes are not supported.')
+    },
+    async ({ selector, value, frame }) => {
+      const response = await bridge.request({ type: "react_set_input", selector, value, frame });
+      const r = response;
+      return {
+        content: [{ type: "text", text: r.message ?? (r.success ? "Set" : "Failed to set") }]
+      };
+    }
+  );
   server.tool(
     "execute_script",
     `Execute JavaScript in the current page's context and return the result as a string.
 Use this to read framework state, check DOM properties, or interact with page APIs that aren't reachable via text.
 Prefer get_page_text for reading visible content. Use this for programmatic DOM queries (e.g. checking an element's attribute, reading a value not visible in text).
 Top-level return statements are supported (e.g. multi-statement scripts with \`return value;\`).
+Top-level \`await\` is supported \u2014 write \`return await fetch(url).then(r => r.json())\` directly without the window.__variable + sleep + re-read pattern. Detected automatically when the code contains the \`await\` keyword.
 If the page called alert()/confirm()/prompt() since the last check, the message will appear as PAGE ALERT in the result \u2014 read it and act on it.
-NOTE: Pages with strict Content Security Policy (e.g. Stripe, GitHub) will block eval and return a CSP error \u2014 do not retry, use get_page_text or fill_input instead.`,
+NOTE: Pages with strict Content Security Policy (e.g. Stripe, GitHub) will fall through to a CDP path that bypasses CSP \u2014 but the script still runs, so retries usually aren't needed.`,
     {
       code: z.string().describe(
         "JavaScript expression or multi-statement script to evaluate in the page. Top-level `return` is supported."

package/dist/tools/capture.js

@@ -9,14 +9,19 @@ function registerCaptureTools(server, bridge) {
     `Fill a form input field with a value automatically.
 Use this for fields Claude knows the answer to (product name, price, description, tier name, URLs, etc.).
 DO NOT use for: email address, password, payment/billing info, phone number \u2014 highlight those instead and tell the user what to enter.
-After filling, call wait_for_click only if the user needs to review/confirm; otherwise proceed directly to the next step.`,
+After filling, call wait_for_click only if the user needs to review/confirm; otherwise proceed directly to the next step.
+
+The response always includes the matched element's identifying attributes (e.g. \`<input name="title" id="..." placeholder="...">\`) and the match-strength (aria-eq, name-eq, fuzzy-text-walk, etc.). VERIFY this is the field you intended \u2014 fuzzy-text-walk matches are the lowest-confidence kind and have historically caused fill_input to land on the wrong field on dense forms.
+
+Pass \`exact: true\` to refuse fuzzy text-walk matches entirely. Use this for short generic labels like "Rate", "Price", or "Amount" on dense forms with many similarly-labeled fields. If no exact match exists, fill_input returns success=false instead of silently filling the wrong field.`,
     {
       textHint: z.string().describe("The label, placeholder, or nearby text identifying the input (e.g. 'Product name', 'Amount', 'Description')"),
       value: z.string().describe("The value to fill in"),
-      nth: z.number().int().min(1).optional().describe("Which match to fill when multiple inputs share the same label (1 = first/topmost, default 1)")
+      nth: z.number().int().min(1).optional().describe("Which match to fill when multiple inputs share the same label (1 = first/topmost, default 1)"),
+      exact: z.boolean().optional().describe("If true, only match aria-label/placeholder/name/id/label-text equal to the hint \u2014 refuse fuzzy text-walk matches. Default false.")
     },
-    async ({ textHint, value, nth }) => {
-      const response = await bridge.request({ type: "fill_input", textHint, value, nth });
+    async ({ textHint, value, nth, exact }) => {
+      const response = await bridge.request({ type: "fill_input", textHint, value, nth, exact });
       if (response.type !== "fill_response") throw new Error("Unexpected response");
       const r = response;
       return {

package/dist/tools/flow.js

@@ -18,22 +18,36 @@ function registerFlowTools(server, bridge) {
 Use this whenever Claude can press a button without needing user input \u2014 e.g. "Save", "Continue", "Create product", "Add pricing", "Confirm", "Next".
 After clicking, use get_page_text to check the result \u2014 only use take_screenshot if you need pixel positions.
 Do NOT use for: elements that require the user to make a personal choice, consent to terms, or enter sensitive data.
-When multiple elements share the same label (e.g. many "Remove" buttons), use nth to target a specific one (1 = first/topmost, 2 = second, etc.).`,
+When multiple elements share the same label (e.g. many "Remove" buttons), use nth to target a specific one (1 = first/topmost, 2 = second, etc.).
+
+Verifying the click took effect: on React-heavy sites the synthetic click sometimes returns success but the handler never ran. Pass an "until" condition that should hold AFTER the click \u2014 click_element will then poll for it and return success only if the page actually changed:
+- until_selector: a CSS selector that should appear (e.g. ".success-toast", "#confirm-modal")
+- until_url_contains: a substring that should appear in the URL (e.g. "/listing-published")
+- until_text_contains: a substring that should appear anywhere in page text (e.g. "Listing created")
+If the until-condition is not met within until_timeout_ms (default 5000ms), click_element returns success=false with a clear message so the caller can retry or take a different path.`,
     {
       textHint: z.string().describe(
         "The visible label of the button or link (e.g. 'Save product', 'Continue', 'Add a product', 'Create')"
       ),
-      nth: z.number().int().min(1).optional().describe("Which match to click when multiple elements share the same label (1 = first/topmost, default 1)")
+      nth: z.number().int().min(1).optional().describe("Which match to click when multiple elements share the same label (1 = first/topmost, default 1)"),
+      until_selector: z.string().optional().describe('Wait until this CSS selector appears on the page after the click (e.g. ".success-toast"). Returns success=false if it does not appear within until_timeout_ms.'),
+      until_url_contains: z.string().optional().describe('Wait until the URL contains this substring after the click (e.g. "/checkout/complete"). Returns success=false if it does not.'),
+      until_text_contains: z.string().optional().describe('Wait until the visible page text contains this substring after the click (e.g. "Listing published"). Returns success=false if it does not.'),
+      until_timeout_ms: z.number().int().min(500).optional().describe("How long to wait for the until-condition, in milliseconds (default 5000). Only used if one of until_* is set.")
     },
-    async ({ textHint, nth }) => {
-      const response = await bridge.request({ type: "click_element", textHint, nth });
+    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
+      );
       const r = response;
       if (!r.success) {
         return {
           content: [
             {
               type: "text",
-              text: `Could not click "${textHint}": ${r.message}. Call take_screenshot() to locate the element visually.`
+              text: `Could not click "${textHint}": ${r.message}`
             }
           ]
         };
@@ -78,7 +92,15 @@ If the click causes page navigation, this resolves when the new page finishes lo
 Examples: wait for a build to finish, a success/error message to appear, a modal to open.
 After it resolves, use get_page_text to read the result rather than taking a screenshot.
 For long-running server-side processes (e.g. a query job that may take minutes), set poll_interval
-to 15 seconds so the page is checked gently rather than hammered every 500ms.`,
+to 15 seconds so the page is checked gently rather than hammered every 500ms.
+
+Pierces open shadow roots automatically \u2014 selectors for elements inside web components
+(Outlier task UI, Lit/Stencil widgets) match without needing a shadow-DOM-aware caller.
+
+Pass \`shadow_root: true\` when the matched element is itself a shadow host whose tree
+hasn't attached yet \u2014 common after SPA route transitions where the host element appears
+seconds before its shadow content hydrates. Without this, wait_for_selector("the-host")
+resolves on the empty host and the next execute_script(host.shadowRoot) returns null.`,
     {
       selector: z.string().describe(
         `CSS selector to wait for (e.g. '.deploy-ready', '[data-status="error"]', '.toast-error')`
@@ -86,14 +108,21 @@ to 15 seconds so the page is checked gently rather than hammered every 500ms.`,
       timeout: z.number().optional().describe("Max seconds to wait (default 30)"),
       poll_interval: z.number().optional().describe(
         "How often to check for the selector, in seconds (default 0.5). Set to 15 when waiting for a slow server-side process."
+      ),
+      shadow_root: z.boolean().optional().describe(
+        "If true, also require the matched element to have an attached shadowRoot (not null). Use after SPA navigations where the shadow host appears before its tree hydrates. Default false."
       )
     },
-    async ({ selector, timeout = 30, poll_interval }) => {
+    async ({ selector, timeout = 30, poll_interval, shadow_root }) => {
       const timeoutMs = timeout * 1e3;
       const pollMs = poll_interval ? poll_interval * 1e3 : void 0;
-      await bridge.request({ type: "wait_for_selector", selector, timeout: timeoutMs, refresh: pollMs }, timeoutMs + 5e3);
+      await bridge.request(
+        { type: "wait_for_selector", selector, timeout: timeoutMs, refresh: pollMs, shadow_root },
+        timeoutMs + 5e3
+      );
+      const suffix = shadow_root ? " (with attached shadowRoot)" : "";
       return {
-        content: [{ type: "text", text: `Selector "${selector}" found on page.` }]
+        content: [{ type: "text", text: `Selector "${selector}" found on page${suffix}.` }]
       };
     }
   );
@@ -163,17 +192,22 @@ Examples: scroll_to_element("#submit-btn"), scroll_to_element("Billing address")
     `Fill multiple form fields in a single call by targeting each field by its label text.
 Use this instead of calling fill_input repeatedly \u2014 it fills all fields in one round trip and returns a per-field success report.
 Ideal for forms with many textareas or inputs where each fill would otherwise require a separate tool call.
-fields is an array of {label, value} pairs. label should match the field's visible label, placeholder, or aria-label.`,
+fields is an array of {label, value} pairs. label should match the field's visible label, placeholder, or aria-label.
+
+Each per-field result includes the matched element description (e.g. \`<input name="title" id="..." placeholder="...">\`) so Claude can spot when fill_form picked the wrong field.
+
+Pass \`exact: true\` for forms with short generic labels (like "Rate" or "Amount") that may collide with similarly-labeled neighbours \u2014 fields without an exact aria-label/placeholder/name/id/label-text match will return success=false instead of silently filling the wrong field.`,
     {
       fields: z.array(
         z.object({
           label: z.string().describe("Visible label, placeholder, or aria-label of the field"),
           value: z.string().describe("Value to fill in")
         })
-      ).describe("List of fields to fill")
+      ).describe("List of fields to fill"),
+      exact: z.boolean().optional().describe("If true, refuse fuzzy text-walk matches for every field. Default false.")
     },
-    async ({ fields }) => {
-      const response = await bridge.request({ type: "fill_form", fields });
+    async ({ fields, exact }) => {
+      const response = await bridge.request({ type: "fill_form", fields, exact });
       const r = response;
       const lines = r.results.map((f) => `${f.success ? "\u2713" : "\u2717"} "${f.label}": ${f.message}`);
       return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chromeflow",
-  "version": "0.2.3",
+  "version": "0.4.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": {