fix(core): respect v3 piercer debug option

[EfeDurmaz16]

Summary

• Uses opts.debug ?? false instead of always enabling V3 piercer debug logging
• Adds regression coverage for default-silent and debug-enabled behavior

Fixes #1996.

Verification

• pnpm --filter @browserbasehq/stagehand run build
• pnpm --dir packages/core exec vitest run --config vitest.config.ts dist/esm/tests/unit/v3-piercer-debug.test.js

---

Summary by cubic

Fixes v3 shadow piercer logging to respect the debug option. Default behavior is now silent; logs only when debug: true is passed.

• Bug Fixes
  • Use opts.debug ?? false in installV3ShadowPiercer.
  • Add unit tests for default silent mode and debug-enabled logging.

^{Written for commit 16feb5b. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 16feb5b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

This PR is from an external contributor and must be approved by a stagehand team member with write access before CI can run.
Approving the latest commit mirrors it into an internal PR owned by the approver.
If new commits are pushed later, the internal PR stays open but is marked stale until someone approves the latest external commit and refreshes it.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 16feb5b8b1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Stop enabling piercer debug in the injected entry

Changing this default does not silence the runtime path used by normal V3 sessions: scripts/build-dom-scripts.ts bundles lib/v3/dom/piercer.entry.ts into v3ScriptContent, understudy/piercer.ts injects/evaluates that script, and the entry still calls installV3ShadowPiercer({ debug: true, tagExisting: false }). In those sessions the new default is bypassed, so [v3-piercer] console logs continue even when debug is not requested; the added unit test only covers direct calls to installV3ShadowPiercer().

Useful? React with 👍 / 👎.

[cubic-dev-ai]

No issues found across 2 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Client as Client Page
    participant V3Piercer as V3 Shadow Piercer
    participant Console as console.info
    participant Test as Test Suite

    Note over Client,Test: V3 Shadow Piercer Debug Logging Flow

    Client->>V3Piercer: installV3ShadowPiercer(opts)
    V3Piercer->>V3Piercer: opts.debug ?? false -> DEBUG

    alt DEBUG = false (default)
        Client->>V3Piercer: element.attachShadow({ mode: "closed" })
        V3Piercer->>V3Piercer: Patch attachShadow, no logging
        V3Piercer-->>Client: ShadowRoot
        Note over V3Piercer,Console: No console.info call
    else DEBUG = true
        Client->>V3Piercer: element.attachShadow({ mode: "closed" })
        V3Piercer->>V3Piercer: Patch attachShadow, log info
        V3Piercer->>Console: info("v3 piercer patched shadow...")
        Console-->>V3Piercer: (logged)
        V3Piercer-->>Client: ShadowRoot
    end

    Note over Test: Regression Tests

    Test->>Test: installDomGlobals()
    Test->>V3Piercer: installV3ShadowPiercer() (no opts)
    Test->>Test: new TestElement().attachShadow(...)
    Test->>Test: expect(console.info).not.toHaveBeenCalled()

    Test->>Test: installDomGlobals()
    Test->>V3Piercer: installV3ShadowPiercer({ debug: true })
    Test->>Test: new TestElement().attachShadow(...)
    Test->>Test: expect(console.info).toHaveBeenCalled()

Loading