chromeflow 0.3.0 → 0.4.0

package/CLAUDE.md

@@ -194,7 +194,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.
 

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.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": {