chromeflow 0.3.0 → 0.5.0

package/CLAUDE.md

@@ -126,6 +126,17 @@ use `take_and_copy_screenshot()` — it saves a PNG to ~/Downloads and copies it
 - `set_file_input` accepts CSS selectors as the hint (e.g. `#import-problem-file`,
   `.upload-input`) in addition to label text. Use selectors when file inputs are hidden
   behind custom UIs and have no visible label.
+- **Replacing an already-uploaded file**: after `set_file_input` succeeds, the input
+  becomes invisible and a "Remove" span/button typically appears near the upload area.
+  To replace the file: `click_element("Remove", nth=N)` (the right `nth` if there are
+  multiple), then call `set_file_input(hint, newPath)` again — the same hidden input is
+  recycled and accepts the new file. Verify with `get_form_fields()` between the two
+  steps so you're sure the input has reappeared.
+- **Forcing auto-save on idempotent text edits** (e.g. keep-alive loop on an
+  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.
 - 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
@@ -144,6 +155,12 @@ use `take_and_copy_screenshot()` — it saves a PNG to ~/Downloads and copies it
 - `switch_to_tab("1")` switches by tab number; `switch_to_tab("form")` matches by URL or title substring.
 - Before navigating away from a partially-filled form, call `save_page_state()` so the form
   can be restored if the tab reloads or the page loses its state on return.
+- **In long-lived self-rescheduling loops**, the active tab can silently drift mid-session
+  (the user navigates manually while AFK, or another tab steals focus). At the start of
+  every loop iteration, call `list_tabs` and verify the active tab's URL matches your
+  expected target — if not, `switch_to_tab(<URL or title substring>)` before running
+  `execute_script` or any other tab-scoped tool. Without this guard, scripts run on the
+  wrong tab and fail with confusing "undefined" errors that look like page bugs.
 
 ## Error handling
 
@@ -194,7 +211,12 @@ set_file_input("Photos", "/path/2.jpg", verify_selector=".photo-thumbnail:nth-of
 ```
 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.
+**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.
 
@@ -265,10 +287,25 @@ document.body.style.zoom = '1';
 1. Retry the exact same `execute_script` call
 2. If still failing, use `find_and_highlight` to show the user a download button to click manually
 
-**Shadow DOM `[role=radio]` / custom radios silently no-op**: On sites like Outlier,
-`element.click()` on a shadow-DOM radio often doesn't flip `aria-checked`. Two things
-must be true: (a) the element must be scrolled into view FIRST (`scrollIntoView({block:'center'})`),
-and (b) the full pointer-event chain must fire — not just `click()`:
+**React-controlled native radios/checkboxes that don't update `checked`**: `click_element`
+auto-handles this for native `<input type=radio>` and `<input type=checkbox>` inputs
+(including labels that wrap or `for=` reference them). The flow:
+- If a radio is already `checked=true`, `click_element` skips the click — re-clicking can
+  toggle it OFF on React forms whose `onChange` interprets the click as a deselect. The
+  response says `"X — radio already checked, click skipped"`.
+- If the standard click fires but the input's `checked` state didn't change as expected
+  (radio still unchecked, or checkbox didn't toggle), `click_element` automatically
+  dispatches the full pointer-event chain (`pointerdown → mousedown → pointerup → mouseup
+  → click`) on the input. The response says `"now checked (after pointer-chain fallback)"`.
+
+You only need to drop into `execute_script` for the no-native-input case below.
+
+**Shadow DOM `[role=radio]` / role-only custom radios silently no-op**: On sites like
+Outlier where the radio is a `[role=radio]` div with no underlying `<input>`,
+`click_element`'s native-input fallback can't help — the click target has no `.checked`
+property to verify. Two things must be true: (a) the element must be scrolled into view
+FIRST (`scrollIntoView({block:'center'})`), and (b) the full pointer-event chain must
+fire — not just `click()`:
 ```js
 ['pointerdown','mousedown','pointerup','mouseup','click'].forEach(t =>
   el.dispatchEvent(new MouseEvent(t, {bubbles: true, cancelable: true}))

package/dist/tools/flow.js

@@ -92,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')`
@@ -100,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}.` }]
       };
     }
   );

package/package.json

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