docs: add page.waitForSelector() documentation

[chromiebot]

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 1e90c4a. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1e90c4a

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 Summary

Added complete API reference documentation for the page.waitForSelector() method.

• Documented method signature with selector string and optional WaitForSelectorOptions
• Detailed all state options: attached, detached, visible (default), and hidden
• Documented default timeout (30000ms) and pierceShadow behavior (enabled by default)
• Included comprehensive code examples covering various use cases: basic waiting, custom timeouts, state transitions, iframe support, shadow DOM piercing, and XPath selectors
• All documentation aligns with the actual implementation in page.ts and waitForSelector.ts

Confidence Score: 5/5

• This PR is safe to merge with no risk
• Documentation-only PR that accurately reflects the existing implementation. All parameter types, defaults, and behavior match the source code. Examples follow established patterns and custom style guide requirements.
• No files require special attention

Important Files Changed

Filename	Overview
packages/docs/v3/references/page.mdx	Added comprehensive documentation for page.waitForSelector() method with accurate parameter descriptions, examples, and usage patterns

Sequence Diagram

sequenceDiagram
    participant User
    participant Page
    participant Frame
    participant waitForSelector
    participant MutationObserver
    participant DOM

    User->>Page: waitForSelector(selector, options)
    Page->>Page: Parse options (state, timeout, pierceShadow)
    Page->>Frame: resolveLocatorTarget(selector)
    Frame-->>Page: targetFrame, finalSelector
    Page->>Frame: evaluate(waitForSelector script)
    Frame->>waitForSelector: Execute in page context
    waitForSelector->>DOM: findElement(selector, pierceShadow)
    
    alt Element found and matches state
        DOM-->>waitForSelector: Element
        waitForSelector-->>Frame: true
        Frame-->>Page: true
        Page-->>User: Promise<true>
    else Element not found or wrong state
        waitForSelector->>MutationObserver: Setup observers (document + shadow roots)
        MutationObserver->>DOM: Monitor changes
        loop Until condition met or timeout
            DOM->>MutationObserver: DOM mutation event
            MutationObserver->>waitForSelector: Trigger check
            waitForSelector->>DOM: findElement(selector, pierceShadow)
            alt Condition met
                DOM-->>waitForSelector: Element in desired state
                waitForSelector->>MutationObserver: Disconnect
                waitForSelector-->>Frame: true
                Frame-->>Page: true
                Page-->>User: Promise<true>
            else Timeout exceeded
                waitForSelector->>MutationObserver: Disconnect
                waitForSelector-->>Frame: Error
                Frame-->>Page: Error
                Page-->>User: Promise rejected
            end
        end
    end

Loading

[cubic-dev-ai]

No issues found across 1 file