From 5c2f895b7111f03c3bf2fb779c542b9e2aefe066 Mon Sep 17 00:00:00 2001
From: kagura-agent <kagura.agent.ai@gmail.com>
Date: Thu, 30 Apr 2026 09:30:22 +0800
Subject: [PATCH] fix: respect opts.debug in installV3ShadowPiercer (fixes
 #1996)

Replace hardcoded `const DEBUG = true` with `const DEBUG = opts.debug ?? false`
so callers can control debug logging via V3ShadowPatchOptions.
---
 .changeset/fix-shadow-piercer-debug.md      | 5 +++++
 packages/core/lib/v3/dom/piercer.runtime.ts | 3 +--
 2 files changed, 6 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/fix-shadow-piercer-debug.md

diff --git a/.changeset/fix-shadow-piercer-debug.md b/.changeset/fix-shadow-piercer-debug.md
new file mode 100644
index 0000000000..914599d5a3
--- /dev/null
+++ b/.changeset/fix-shadow-piercer-debug.md
@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Respect `opts.debug` in `installV3ShadowPiercer` instead of hardcoding `DEBUG = true`
diff --git a/packages/core/lib/v3/dom/piercer.runtime.ts b/packages/core/lib/v3/dom/piercer.runtime.ts
index 56db4e9a7b..975eb51b5f 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;