[docs]: add docs for page.waitForSelector()

[seanmcguire12]

why

missing docs for new page.waitForSelector()

what changed

Add API reference documentation for page.waitForSelector() method including:

• Method signature and parameter descriptions
• All options: state, timeout, pierceShadow
• Code examples for various use cases

test plan

---

Summary by cubic

Adds API reference for page.waitForSelector(), with options, defaults, and practical examples. Addresses STG-1125 by filling the missing docs.

• New Features
  • Method signature and parameters: state, timeout, pierceShadow.
• Notes on defaults: state "visible", 30s timeout, shadow DOM piercing; supports iframe hop (>>).
• Examples for visible/hidden/detached, iframe, shadow DOM, XPath, and custom timeouts.

^{Written for commit 7df5f4b. Summary will update on new commits. Review in cubic}

why

what changed

test plan

[changeset-bot]

⚠️ No Changeset found

Latest commit: 7df5f4b

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

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds complete API reference documentation for the page.waitForSelector() method. The documentation includes:

• Method signature matching the implementation in packages/core/lib/v3/understudy/page.ts:1219
• All parameters (selector, state, timeout, pierceShadow) with accurate types and defaults
• Clear descriptions of all four state options (attached, detached, visible, hidden)
• Comprehensive code examples covering common use cases including iframes, shadow DOM, XPath, and different states
• Proper formatting consistent with other method documentation in the file

The documentation is well-structured, accurate, and provides practical examples that align with the test cases in the codebase.

Confidence Score: 5/5

• This PR is safe to merge with no issues found
• This is a documentation-only change that accurately describes the waitForSelector() method. All parameter types, defaults, and behavior descriptions match the actual implementation. The examples are comprehensive and demonstrate real use cases validated by the test suite.
• No files require special attention

Important Files Changed

Filename	Overview
packages/docs/v3/references/page.mdx	Added comprehensive documentation for waitForSelector() method with accurate API reference and practical examples

Sequence Diagram

sequenceDiagram
    participant User
    participant Documentation
    participant Implementation
    
    User->>Documentation: Read waitForSelector() API reference
    Documentation->>User: Shows method signature with options
    Documentation->>User: Shows state options (visible/hidden/attached/detached)
    Documentation->>User: Shows defaults (state=visible, timeout=30000, pierceShadow=true)
    Documentation->>User: Provides code examples
    
    User->>Implementation: Calls page.waitForSelector(selector, options)
    Implementation->>Implementation: Uses MutationObserver for efficiency
    Implementation->>Implementation: Pierces shadow DOM if pierceShadow=true
    Implementation->>Implementation: Supports iframe hop notation with >>
    Implementation->>User: Returns true when condition met

Loading

[greptile-apps]

_{No files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[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 User as User Script
    participant API as Page.waitForSelector()
    participant DOM as Browser DOM

    Note over User,DOM: Visualization of the newly documented logic (No code changes)

    User->>API: waitForSelector(selector, options)
    
    Note right of User: New Docs cover:<br/>state, timeout, pierceShadow
    
    API->>API: Apply Defaults
    Note right of API: state: "visible"<br/>timeout: 30000ms<br/>pierceShadow: true

    loop Until State Met or Timeout
        API->>DOM: Query Selector
        Note over API,DOM: Supports ">>" (iframe) & Shadow DOM
        
        alt Condition Met (e.g. Visible)
            DOM-->>API: Element Found
            API-->>User: Returns true
        else Condition Not Met
            DOM-->>API: null
            API->>API: Wait / MutationObserver
        end

        opt Timeout Exceeded
            API-->>User: Throw Error
        end
    end

Loading