[docs]: add docs for setDomainPolicy

[seanmcguire12]

why

• adds documentation for setDomainPolicy()

what changed

---

Summary by cubic

Adds docs for context.setDomainPolicy() and context.getDomainPolicy() to control HTTP(S) requests by domain across a context, with examples and error details. Addresses Linear STG-2426.

• New Features
  • Documented setDomainPolicy(policy: DomainPolicy | null) and getDomainPolicy() with TypeScript signatures, behavior, scope (pages, iframes, subresources), and how to clear.
  • Clarified domain-only patterns: exact vs wildcard, subdomain rules (*.example.com doesn’t match example.com), case-insensitive matching, duplicate patterns ignored, and no schemes/paths/ports; blockedDomains overrides allowedDomains; non-HTTP(S) unaffected; blocked requests show Chrome “BlockedByClient”.
  • Added a “Domain Policy” example tab using @browserbasehq/stagehand, and updated API reference with new errors (StagehandInvalidArgumentError, StagehandSetDomainPolicyError) plus V3Context and DomainPolicy interface snippets.

^{Written for commit 644f32e. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 3be4cbb

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

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
stagehand	🟢 Ready	View Preview	Jun 29, 2026, 7:05 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[cubic-dev-ai]

No issues found across 1 file

Confidence score: 5/5

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

Architecture diagram

sequenceDiagram
    participant UserCode as User Script
    participant Context as V3Context
    participant Network as Network Domain Manager
    participant CDP as Chrome DevTools Protocol
    participant CDPSession as CDP Session(s)
    
    Note over UserCode,CDPSession: Domain Policy Flow
    
    UserCode->>Context: setDomainPolicy(policy)
    Context->>Context: Validate policy (DomainPolicy | null)
    alt Invalid policy (e.g. URL with path)
        Context-->>UserCode: StagehandInvalidArgumentError
    else Valid policy
        Context->>Network: Apply domain policy (allowedDomains + blockedDomains)
        Network->>Network: Normalize patterns (lowercase, deduplicate)
        Network->>CDPSession: Configure network blocking (one or more sessions)
        alt All sessions updated successfully
            CDPSession-->>Network: OK
            Network-->>Context: Success
            Context-->>UserCode: Resolved
        else Some sessions fail
            CDPSession-->>Network: Error
            Network-->>Context: Partial failure
            Context-->>UserCode: StagehandSetDomainPolicyError (with failures[])
        end
    end
    
    Note over UserCode,CDPSession: Runtime Request Flow
    
    UserCode->>Context: page.goto("https://example.com")
    Context->>CDP: Navigate request
    CDP->>Network: Check policy for "example.com"
    alt Domain allowed (no matching blockedDomains, matches allowedDomains)
        Network-->>CDP: Allow
        CDP-->>Context: Page loaded
        Context-->>UserCode: Page object
    else Domain blocked (matches blockedDomains or rejects allowedDomains)
        Network-->>CDP: BlockedByClient
        CDP-->>Context: Request blocked
        Context-->>UserCode: Error (BlockedByClient)
    end
    
    Note over UserCode,CDPSession: New Target (popup/window.open)
    
    UserCode->>Context: action opens popup
    Context->>Network: Check policy for new target domain
    alt Domain allowed
        Context->>CDPSession: Attach to new target
        CDPSession-->>Context: Target active
        Context-->>UserCode: Page object
    else Domain blocked (race-sensitive)
        Context->>CDPSession: Close target (fallback)
        CDPSession-->>Context: Target closed
        Context-->>UserCode: Error
    end
    
    Note over UserCode,CDPSession: Subresource Checks
    
    UserCode->>Context: iframe.src="https://ads.example.com"
    Context->>CDP: Load iframe content
    CDP->>Network: Check policy for "ads.example.com"
    alt Domain blocked (overrides allowedDomains)
        Network-->>CDP: BlockedByClient
        CDP-->>Context: Subresource blocked
    else Domain allowed
        Network-->>CDP: Allow
        CDP-->>Context: Content loaded
    end
    
    Note over UserCode,CDPSession: Policy Read
    
    UserCode->>Context: getDomainPolicy()
    Context->>Context: Return stored DomainPolicy | null
    Context-->>UserCode: DomainPolicy object
    
    Note over UserCode,CDPSession: Clear Policy
    
    UserCode->>Context: setDomainPolicy(null)
    Context->>Network: Remove domain policy
    Network->>CDPSession: Disable network blocking
    CDPSession-->>Network: OK
    Network-->>Context: Policy cleared
    Context-->>UserCode: Resolved

Loading

_{Re-trigger cubic}