[docs]: add docs for cookie handling

[seanmcguire12]

why

• adds documentation for the following new functions:
  • context.addCookies()
  • context.clearCookies()
  • context.cookies()

note:

• hold off on merging until after release

---

Summary by cubic

Add V3 docs for cookie management in context: cookies(), addCookies(), and clearCookies, with examples and type definitions to help users manage auth and state. Connects to Linear STG-1409; merge after the release that includes these APIs.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4ad34e1

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 comprehensive documentation for cookie handling functionality in the context API, including three new methods: context.cookies() for retrieving cookies with optional URL filtering, context.addCookies() for setting cookies with flexible URL or domain/path specification, and context.clearCookies() for clearing cookies with optional filtering by name, domain, or path.

The documentation is thorough and well-structured with:

• Complete type definitions matching the actual implementation
• Multiple code examples demonstrating different usage patterns
• Clear parameter descriptions with proper default values
• Appropriate warnings about sameSite: "None" security requirements
• A new "Cookie Management" tab in the code examples section showing practical authentication scenarios

Confidence Score: 5/5

• This PR is safe to merge with no risk - documentation-only change with accurate content
• Documentation-only PR that accurately documents three new cookie management methods. The type definitions in the docs match the actual TypeScript interfaces in packages/core/lib/v3/types/public/context.ts, and the method signatures match the implementations in packages/core/lib/v3/understudy/context.ts. Code examples follow established patterns and include appropriate warnings about security requirements.
• No files require special attention

Important Files Changed

Filename	Overview
packages/docs/v3/references/context.mdx	Added comprehensive documentation for three new cookie management methods (cookies(), addCookies(), clearCookies()) with accurate type definitions, code examples, and usage patterns

_{Last reviewed commit: 4ad34e1}

[greptile-apps]

_{1 file 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 SH as Stagehand
    participant Ctx as V3Context
    participant BE as Browser Engine (Local/Remote)
    participant Page as Browser Page

    Note over User,BE: Context Initialization
    User->>SH: init()
    SH->>Ctx: Create Context
    Ctx->>BE: Launch/Connect Browser Session
    Ctx->>Page: Open initial page(s)
    
    Note over User,BE: NEW: Cookie Management Flow

    rect rgb(23, 37, 84)
    Note right of User: Set Cookies
    User->>Ctx: NEW: addCookies(cookies[])
    Ctx->>Ctx: Validate (Must have URL OR Domain+Path)
    alt Validation Failed
        Ctx-->>User: Throw ValidationError
    else Validation Passed
        Ctx->>BE: Inject cookies into session
        BE-->>Ctx: Success
        Ctx-->>User: void
    end
    end

    rect rgb(5, 46, 22)
    Note right of User: Read Cookies
    User->>Ctx: NEW: cookies(urls?)
    Ctx->>BE: Get session cookies
    BE-->>Ctx: Cookie[]
    opt If urls provided
        Ctx->>Ctx: Filter cookies by domain/path/secure
    end
    Ctx-->>User: Return Cookie[]
    end

    rect rgb(69, 26, 3)
    Note right of User: Clear Cookies
    User->>Ctx: NEW: clearCookies(options?)
    Ctx->>BE: Remove cookies from session
    Note over Ctx,BE: Matches by Name, Domain, or Path
    BE-->>Ctx: Success
    Ctx-->>User: void
    end

    Note over Page,BE: Page interactions automatically use Context cookies
    User->>Page: goto(url)
    Page->>BE: Request with Context Cookies
    BE-->>Page: Response (Set-Cookie headers update Context)

Loading