From 16feb5b8b1d8fca8d4659d0b7af5d4e3e4260cd6 Mon Sep 17 00:00:00 2001
From: EfeDurmaz16 <efebarandurmaz05@gmail.com>
Date: Wed, 6 May 2026 02:03:38 +0300
Subject: [PATCH 1/2] fix(core): respect v3 piercer debug option

---
 packages/core/lib/v3/dom/piercer.runtime.ts   |  3 +-
 .../core/tests/unit/v3-piercer-debug.test.ts  | 49 +++++++++++++++++++
 2 files changed, 50 insertions(+), 2 deletions(-)
 create mode 100644 packages/core/tests/unit/v3-piercer-debug.test.ts

diff --git a/packages/core/lib/v3/dom/piercer.runtime.ts b/packages/core/lib/v3/dom/piercer.runtime.ts
index 56db4e9a7..975eb51b5 100644
--- a/packages/core/lib/v3/dom/piercer.runtime.ts
+++ b/packages/core/lib/v3/dom/piercer.runtime.ts
@@ -31,8 +31,7 @@ declare global {
 }
 
 export function installV3ShadowPiercer(opts: V3ShadowPatchOptions = {}): void {
-  // hardcoded debug (remove later if desired)
-  const DEBUG = true;
+  const DEBUG = opts.debug ?? false;
 
   type PatchedFn = Element["attachShadow"] & {
     __v3Patched?: boolean;
diff --git a/packages/core/tests/unit/v3-piercer-debug.test.ts b/packages/core/tests/unit/v3-piercer-debug.test.ts
new file mode 100644
index 000000000..95faf7990
--- /dev/null
+++ b/packages/core/tests/unit/v3-piercer-debug.test.ts
@@ -0,0 +1,49 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { installV3ShadowPiercer } from "../../lib/v3/dom/piercer.runtime";
+
+class TestElement {
+  tagName = "TEST-ELEMENT";
+
+  attachShadow(_init: ShadowRootInit): ShadowRoot {
+    return {} as ShadowRoot;
+  }
+}
+
+function installDomGlobals() {
+  vi.stubGlobal("Element", TestElement);
+  vi.stubGlobal("location", { href: "https://example.com" });
+  vi.stubGlobal("window", {
+    top: undefined,
+    __stagehandV3Injected: undefined,
+    __stagehandV3__: undefined,
+  });
+  window.top = window;
+}
+
+describe("installV3ShadowPiercer debug logging", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("does not log by default", () => {
+    installDomGlobals();
+    const info = vi.spyOn(console, "info").mockImplementation(() => {});
+
+    installV3ShadowPiercer();
+    new TestElement().attachShadow({ mode: "closed" });
+
+    expect(info).not.toHaveBeenCalled();
+  });
+
+  it("logs when debug is enabled", () => {
+    installDomGlobals();
+    const info = vi.spyOn(console, "info").mockImplementation(() => {});
+
+    installV3ShadowPiercer({ debug: true });
+    new TestElement().attachShadow({ mode: "closed" });
+
+    expect(info).toHaveBeenCalled();
+  });
+});

From eb9315f5c81af8203b37b83fd03f66750d572e24 Mon Sep 17 00:00:00 2001
From: EfeDurmaz16 <efebarandurmaz05@gmail.com>
Date: Sat, 16 May 2026 01:09:37 +0300
Subject: [PATCH 2/2] chore: add piercer debug changeset

Signed-off-by: EfeDurmaz16 <efebarandurmaz05@gmail.com>
---
 .changeset/fix-piercer-debug.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/fix-piercer-debug.md

diff --git a/.changeset/fix-piercer-debug.md b/.changeset/fix-piercer-debug.md
new file mode 100644
index 000000000..3d7189aee
--- /dev/null
+++ b/.changeset/fix-piercer-debug.md
@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+fix(core): respect v3 piercer debug option