fix: don't reload OOPIFs (#1273)

# why
- we needed to reload OOPIFs so that our shadow-root piercing JS was
able to intercept the `attachShadow()` call
- this is wasteful, and can cause unpredictable behaviour
# what changed
- swapped iframe reload logic for new logic that clones, and replaces
shadow root nodes
- this triggers the patched `attachShadow()` function
# test plan
- existing unit tests & evals should sufficiently cover shadow root
piercing

Author: seanmcguire12

.changeset/clear-women-float.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+fix: trigger shadow root rerender in OOPIFs by cloning & replacing instead of reloading

packages/core/lib/v3/dom/genDomScripts.ts

@@ -25,3 +25,26 @@ const script = fs.readFileSync(path.join(outDir, "v3-index.js"), "utf8");
 const content = `export const v3ScriptContent = ${JSON.stringify(script)};`;
 
 fs.writeFileSync(path.join(outDir, "scriptV3Content.ts"), content);
+
+esbuild.buildSync({
+  entryPoints: [path.join(here, "rerenderMissingShadows.entry.ts")],
+  bundle: true,
+  format: "iife",
+  platform: "browser",
+  target: "es2020",
+  minify: true,
+  legalComments: "none",
+  outfile: path.join(outDir, "rerender-index.js"),
+});
+
+const rerenderScript = fs.readFileSync(
+  path.join(outDir, "rerender-index.js"),
+  "utf8",
+);
+const rerenderContent = `export const reRenderScriptContent = ${JSON.stringify(
+  rerenderScript,
+)};`;
+fs.writeFileSync(
+  path.join(outDir, "reRenderScriptContent.ts"),
+  rerenderContent,
+);

packages/core/lib/v3/dom/rerenderMissingShadows.entry.ts

@@ -0,0 +1,3 @@
+import { rerenderMissingShadowHosts } from "./rerenderMissingShadows.runtime";
+
+rerenderMissingShadowHosts();

packages/core/lib/v3/dom/rerenderMissingShadows.runtime.ts

@@ -0,0 +1,35 @@
+export function rerenderMissingShadowHosts(): void {
+  try {
+    const piercer = window.__stagehandV3__;
+    if (!piercer || typeof piercer.getClosedRoot !== "function") return;
+
+    const needsReset: Element[] = [];
+    const walker = document.createTreeWalker(document, NodeFilter.SHOW_ELEMENT);
+    while (walker.nextNode()) {
+      const el = walker.currentNode as Element;
+      const tag = el.tagName?.toLowerCase() ?? "";
+      if (!tag.includes("-")) continue;
+      if (typeof customElements?.get !== "function") continue;
+      if (!customElements.get(tag)) continue;
+      const hasOpen = !!el.shadowRoot;
+      const hasClosed = !!piercer.getClosedRoot(el);
+      if (hasOpen || hasClosed) continue;
+      needsReset.push(el);
+    }
+
+    for (const host of needsReset) {
+      try {
+        const clone = host.cloneNode(true);
+        host.replaceWith(clone);
+      } catch {
+        // ignore individual failures
+      }
+    }
+
+    if (piercer.stats && needsReset.length) {
+      console.info("[v3-piercer] rerender", { count: needsReset.length });
+    }
+  } catch (err) {
+    console.info("[v3-piercer] rerender error", { message: String(err ?? "") });
+  }
+}

packages/core/lib/v3/tests/default-page-tracking.spec.ts

@@ -2,6 +2,7 @@ import { test, expect } from "@playwright/test";
 import { V3 } from "../v3";
 import { v3DynamicTestConfig } from "./v3.dynamic.config";
 
+test.describe.configure({ mode: "parallel" });
 test.describe("V3 default page tracking", () => {
   let v3: V3;
 
@@ -40,7 +41,7 @@ test.describe("V3 default page tracking", () => {
     const root = await ctx.awaitActivePage();
     await root!.goto(
       "https://browserbase.github.io/stagehand-eval-sites/sites/five-tab/",
-      { waitUntil: "networkidle", timeoutMs: 15000 },
+      { waitUntil: "load", timeoutMs: 15000 },
     );
     // 2) Click button on the page to open a new tab → page2.html
     await root.locator("xpath=/html/body/button").click();

packages/core/lib/v3/understudy/cdp.ts

@@ -93,7 +93,7 @@ export class CdpConnection implements CDPSessionLike {
     await this.send("Target.setAutoAttach", {
       autoAttach: true,
       flatten: true,
-      waitForDebuggerOnStart: true,
+      waitForDebuggerOnStart: false,
       filter: [
         { type: "worker", exclude: true },
         { type: "shared_worker", exclude: true },

packages/core/lib/v3/understudy/context.ts

@@ -133,12 +133,15 @@ export class V3Context {
     }
   }
 
-  private async ensurePiercer(session: CDPSessionLike): Promise<void> {
+  private async ensurePiercer(session: CDPSessionLike): Promise<boolean> {
     const key = this.sessionKey(session);
-    if (this._piercerInstalled.has(key)) return;
+    if (this._piercerInstalled.has(key)) return true;
 
-    await installV3PiercerIntoSession(session);
-    this._piercerInstalled.add(key);
+    const installed = await installV3PiercerIntoSession(session);
+    if (installed) {
+      this._piercerInstalled.add(key);
+    }
+    return installed;
   }
 
   /** Mark a page target as the most-recent one (active). */
@@ -286,11 +289,7 @@ export class V3Context {
     this.conn.on<Protocol.Target.AttachedToTargetEvent>(
       "Target.attachedToTarget",
       async (evt) => {
-        await this.onAttachedToTarget(
-          evt.targetInfo,
-          evt.sessionId,
-          evt.waitingForDebugger === true,
-        );
+        await this.onAttachedToTarget(evt.targetInfo, evt.sessionId);
       },
     );
 
@@ -365,38 +364,25 @@ export class V3Context {
   private async onAttachedToTarget(
     info: Protocol.Target.TargetInfo,
     sessionId: SessionId,
-    waitingForDebugger?: boolean, // Chrome paused this target at doc-start?
   ): Promise<void> {
     const session = this.conn.getSession(sessionId);
     if (!session) return;
 
     // Init guard
     if (this._sessionInit.has(sessionId)) return;
     this._sessionInit.add(sessionId);
+    await session.send("Runtime.runIfWaitingForDebugger").catch(() => {});
+
+    // Register for Runtime events before enabling it so we don't miss initial contexts.
+    executionContexts.attachSession(session);
+
+    const piercerReady = await this.ensurePiercer(session);
+    if (!piercerReady) return;
 
-    // Page domain first so frame events flow
-    const pageEnabled = await session
-      .send("Page.enable")
-      .then(() => true)
-      .catch(() => false);
-    if (!pageEnabled) {
-      if (waitingForDebugger) {
-        await session.send("Runtime.runIfWaitingForDebugger").catch(() => {});
-      }
-      return;
-    }
     await session
       .send("Page.setLifecycleEventsEnabled", { enabled: true })
       .catch(() => {});
 
-    // Proactively resume ASAP so navigation isn't stuck at about:blank
-    await session.send("Runtime.runIfWaitingForDebugger").catch(() => {});
-
-    // Capture main-world creations & inject piercer after resume
-    executionContexts.attachSession(session);
-    await session.send("Runtime.enable").catch(() => {});
-    await this.ensurePiercer(session);
-
     // Top-level handling
     if (isTopLevelPage(info)) {
       const page = await Page.create(
@@ -422,10 +408,6 @@ export class V3Context {
       this._pushActive(info.targetId);
       this.installFrameEventBridges(sessionId, page);
 
-      // Resume only if Chrome actually paused
-      if (waitingForDebugger) {
-        await session.send("Runtime.runIfWaitingForDebugger").catch(() => {});
-      }
       return;
     }
 
@@ -458,73 +440,18 @@ export class V3Context {
         owner.adoptOopifSession(session, childMainId);
         this.sessionOwnerPage.set(sessionId, owner);
         this.installFrameEventBridges(sessionId, owner);
+        // Prime the execution-context registry so later lookups succeed even if
+        // the frame navigates before we issue a command.
+        void executionContexts
+          .waitForMainWorld(session, childMainId)
+          .catch(() => {});
       } else {
         this.pendingOopifByMainFrame.set(childMainId, sessionId);
       }
     } catch {
       // page.getFrameTree failed. Most likely was an ad iframe
       // that opened & closed before we could attach. ignore
     }
-
-    /* TODO: for child OOPIFs, we rely on reloads for our script to be applied.
-     *  This is not ideal. We should figure out a way to pause them, and inject them
-     *  from the beginning.
-     */
-    // --- If Chrome did NOT pause this iframe (waitingForDebugger=false),
-    //     we missed doc-start. Do a one-time, best-effort child reload
-    //     so Page.addScriptToEvaluateOnNewDocument applies at creation time.
-    if (info.type === "iframe" && !waitingForDebugger) {
-      try {
-        // Ensure lifecycle events are enabled to observe load
-        await session
-          .send("Page.setLifecycleEventsEnabled", { enabled: true })
-          .catch(() => {});
-
-        const loadWait = new Promise<void>((resolve) => {
-          const handler = (evt: Protocol.Page.LifecycleEventEvent) => {
-            if (evt.name === "load") {
-              session.off("Page.lifecycleEvent", handler);
-              resolve();
-            }
-          };
-          session.on("Page.lifecycleEvent", handler);
-        });
-
-        // Cannot use Page.reload on child targets → use Runtime.evaluate
-        await session
-          .send<Protocol.Runtime.EvaluateResponse>("Runtime.evaluate", {
-            expression: "location.reload()",
-            returnByValue: true,
-            awaitPromise: false,
-          })
-          .catch(() => {});
-
-        // Wait up to ~3s for the child to finish loading (best effort)
-        await Promise.race([
-          loadWait,
-          new Promise<void>((r) => setTimeout(r, 3000)),
-        ]);
-
-        // After reload, our addScriptToEvaluateOnNewDocument runs at doc-start.
-        // We can optionally re-evaluate the piercer (idempotent), but not required.
-        await this.ensurePiercer(session);
-      } catch (e) {
-        v3Logger({
-          category: "ctx",
-          message: "child reload attempt failed (continuing)",
-          level: 2,
-          auxiliary: {
-            sessionId: { value: String(sessionId), type: "string" },
-            err: { value: String(e), type: "string" },
-          },
-        });
-      }
-    }
-
-    // Resume only if Chrome actually paused (rare for iframes in your logs)
-    if (waitingForDebugger) {
-      await session.send("Runtime.runIfWaitingForDebugger").catch(() => {});
-    }
   }
 
   /**

packages/core/lib/v3/understudy/piercer.ts

@@ -2,11 +2,17 @@ import type { Protocol } from "devtools-protocol";
 import { v3Logger } from "../logger";
 import type { CDPSessionLike } from "./cdp";
 import { v3ScriptContent } from "../dom/build/scriptV3Content";
+import { reRenderScriptContent } from "../dom/build/reRenderScriptContent";
 
 export async function installV3PiercerIntoSession(
   session: CDPSessionLike,
-): Promise<void> {
-  await session.send("Page.enable").catch(() => {});
+): Promise<boolean> {
+  const pageEnabled = await session
+    .send("Page.enable")
+    .then(() => true)
+    .catch(() => false);
+  if (!pageEnabled) return false;
+
   await session.send("Runtime.enable").catch(() => {});
   try {
     await session.send<Protocol.Page.AddScriptToEvaluateOnNewDocumentResponse>(
@@ -15,9 +21,9 @@ export async function installV3PiercerIntoSession(
     );
   } catch (e) {
     const msg = String((e as Error)?.message ?? e ?? "");
-    // If the session vanished during attach (common with short‑lived OOPIFs),
-    // swallow and return; re‑installs will happen on future sessions/loads.
-    if (msg.includes("Session with given id not found")) return;
+    // If the session vanished during attach (common with short-lived OOPIFs),
+    // swallow and report failure so callers can early-return.
+    if (msg.includes("Session with given id not found")) return false;
     // For other errors, keep going but don't throw — the next evaluate is idempotent.
   }
   await session
@@ -27,6 +33,18 @@ export async function installV3PiercerIntoSession(
       awaitPromise: true,
     })
     .catch(() => {});
+
+  // After the piercer is in place, re-render any custom elements whose
+  // shadow roots were created before we patched attachShadow so their
+  // closed roots are recreated under the hook.
+  await session
+    .send<Protocol.Runtime.EvaluateResponse>("Runtime.evaluate", {
+      expression: reRenderScriptContent,
+      returnByValue: true,
+      awaitPromise: false,
+    })
+    .catch(() => {});
+  return true;
 }
 
 /** (Optional) stream patch logs in your node console during bring-up */