[docs]: add docs for ignoreSelectors

[seanmcguire12]

why

• to add docs for new ignoreSelectors param in observe()

what changed

• adds new param to reference section
• adds an example snippet in 'the basics' section

---

Summary by cubic

Added docs for the new ignoreSelectors option in observe() to let users exclude page regions from observation. Updated the reference with type and behavior, plus a basics example using XPath and a note on how it interacts with selector.

^{Written for commit 35f9577. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 35f9577

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	May 7, 2026, 6:43 PM

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

[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 Dev as Developer
    participant Docs as Documentation Site
    participant Stagehand as Stagehand SDK
    participant Page as Browser Page
    
    Note over Dev,Page: Core Runtime Flow for ignoreSelectors
    
    Dev->>Docs: Read observe() reference docs
    Docs->>Dev: Show ignoreSelectors: string[] parameter
    
    Dev->>Docs: Read basics example
    Docs->>Dev: Show example with XPath selectors
    
    Note over Dev,Page: Runtime Execution
    
    Dev->>Stagehand: stagehand.observe(instruction, { ignoreSelectors, selector })
    
    Stagehand->>Page: Capture page DOM snapshot
    
    loop For each selector in ignoreSelectors
        Page->>Page: Find matching elements
        Page->>Page: Remove matched nodes and their descendants
    end
    
    alt If selector also provided
        Page->>Page: Scope observation to single resolved subtree
        Note over Page: selector keeps single-target scoping
    else No selector provided
        Note over Page: Observation uses filtered full page
    end
    
    Stagehand->>Page: Analyze filtered snapshot
    Page-->>Stagehand: Return observed actions
    Stagehand-->>Dev: Return action results
    
    Note over Dev,Page: ignoreSelectors vs selector interaction
    Note over Dev,Page: ignoreSelectors removes ALL matches + descendants
    Note over Page: selector still scopes to 1 subtree

Loading