[Docs] Tighten up prose

[akeimach]

why

Found and fixed up some places where the docs could be more direct

what changed

test plan

---

Summary by cubic

Tightened v4 docs for clarity and added Stagehand instance properties to make common handles easy to find. Clarifies iframe-crossing selectors, closed-root limits, multitab behavior, logging/observability, and Browserbase extension/debugging details, aligning with STG-2794.

• New Features

  • Stagehand reference: Added “Properties” for TypeScript and Python with stagehand.browser and stagehand.initialized, plus examples.

• Refactors

  • Locators: Documented iframe hop syntax with >> and deep XPath; Stagehand resolves iframes and shadow DOM automatically; clarified that targets inside iframes or closed roots require a navigated http(s) page (not about:blank/data:).
  • Multitab: Stagehand follows new tabs automatically.
  • Browserbase: When browserbase.launch() runs without an extensionId, Stagehand uploads its extension, starts the session against it, and deletes the upload on browser.close() when keepAlive is disabled; --enable-unsafe-extension-debugging is required so the SDK can attach a CDP session to the extension service worker.
  • Logging/observability: Shorter wording; record callback drives all destinations; track per-run token usage and inference timing; clearer Browserbase monitoring phrasing.

^{Written for commit 995d58b. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 995d58b

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

[cubic-dev-ai]

All reported issues were addressed across 10 files

Architecture diagram

sequenceDiagram
    participant Dev as Developer
    participant Doc as Documentation Site
    participant SB as Stagehand SDK
    participant BB as Browserbase API
    participant Model as Model Gateway

    Note over Dev,Doc: Documentation-Focused Flow

    Dev->>Doc: Reads "Introduction" page
    Doc-->>Dev: Describes Stagehand as "SDK + AI browser driver" with deterministic & AI primitives

    Dev->>Doc: Reads "AI Rules" page
    Doc-->>Dev: Provides rules for AI coding assistants to generate correct Stagehand code

    Dev->>Doc: Reads "Multiple Tabs" page
    Doc-->>Dev: Stagehand automatically follows new tabs opened by page

    Dev->>Doc: Reads "Browser" page
    Note over Doc: Browserbase launch flow
    Doc-->>Dev: Stagehand runs as a browser extension
    Doc-->>Dev: browserbase.launch() uploads extension, starts session, deletes on close()

    Dev->>Doc: Reads "Logging" page
    Doc-->>Dev: Configure via logging option on Stagehand.create()

    alt Pretty (default) logging
        SB->>Dev: Formatted console output
    else Structured logging
        SB->>SB: Token counters aggregated per session
        SB-->>Dev: Sends records via callback to external sinks
    end

    Dev->>Doc: Reads "Observability" page
    Doc-->>Dev: Track token usage and inference timing per run
    Doc-->>Dev: Browserbase dashboard provides live views, recordings, session metadata

    Dev->>Doc: Reads "Models" page
    Doc-->>Dev: Browserbase handles retries, backoff, and rate limits via Model Gateway

    Dev->>Doc: Reads "Locator" page
    Note over Doc: Selector behavior
    Doc-->>Dev: Selectors pierce shadow DOM including closed roots
    Doc-->>Dev: Selectors cross iframe boundaries using >> separator
    Doc-->>Dev: Closed roots require navigated page (http/https URL)

    Dev->>Doc: Reads "Stagehand Instance" page
    Doc-->>Dev: Properties: stagehand.browser (handle, not auto-closed) and stagehand.initialized (false after close)

    Note over SB,BB: Runtime Interaction (Implied)
    SB->>BB: Browserbase session with Stagehand extension
    alt Session active
        BB-->>SB: Extension loaded, session live
        SB->>Model: LLM inference via Model Gateway
        Model-->>SB: Response with retry/backoff handling
    else Session closed
        BB-->>SB: Extension deleted, resources released
    end

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 10 files

Architecture diagram

sequenceDiagram
    participant User as Developer
    participant App as User App
    participant Stagehand as Stagehand SDK Instance
    participant BrowserExt as Browser Extension (Stagehand)
    participant CDP as CDP Session
    participant BrowserContext as Browser Context
    participant BrowserbaseAPI as Browserbase API
    participant LLM as LLM Provider (Model Gateway)
    participant Logger as Log/Observability System

    Note over User,Logger: Stagehand v4 Runtime Architecture

    User->>App: Configure Stagehand
    App->>Stagehand: Stagehand.create(config)
    Stagehand->>Stagehand: Store config (logging, models, viewport)

    alt Local Browser
        Stagehand->>BrowserExt: Launch with --enable-unsafe-extension-debugging
        BrowserExt->>CDP: Attach CDP to extension service worker
    else Browserbase Session
        Stagehand->>BrowserbaseAPI: browserbase.launch()
        BrowserbaseAPI->>BrowserbaseAPI: Upload extension to account
        BrowserbaseAPI-->>Stagehand: Session started
        Stagehand->>BrowserExt: Extension runs in session
        Note over BrowserbaseAPI: Extension deleted on browser.close()
    end

    Stagehand-->>App: stagehand instance (with .browser, .initialized)

    Note over App,LLM: Agent Execution Flow

    App->>Stagehand: stagehand.act("click checkout")
    Stagehand->>Stagehand: Resolve target (empty/current page)
    alt Multitab Workflow
        Note over Stagehand,BrowserContext: NEW: Stagehand follows new tabs automatically
        Stagehand->>BrowserContext: Monitor for popup tabs
        BrowserContext-->>Stagehand: New tab detected
        Stagehand->>Stagehand: Switch context to new tab
    end

    Stagehand->>BrowserExt: Execute locator crossing iframes/shadow roots
    BrowserExt->>BrowserContext: Resolve "iframe#checkout >> button.submit"
    BrowserContext-->>BrowserExt: Target element found
    alt Closed Shadow Root or iframe
        BrowserContext->>BrowserContext: Require http(s) URL (not about:blank/data)
        alt about:blank/data URL
            BrowserContext-->>Stagehand: Locator fail (privileged API unavailable)
        else http(s) URL
            BrowserContext-->>BrowserExt: Element resolved
        end
    end

    Stagehand->>LLM: Inference request (via Browserbase Model Gateway)
    LLM-->>Stagehand: Model response
    Stagehand->>Stagehand: Track token usage & inference timing per run
    Stagehand->>BrowserContext: Execute browser action
    BrowserContext-->>Stagehand: Action result

    Stagehand->>Logger: Emit log record with level, format
    Logger->>Logger: Record callback drives all destinations
    alt Logging Off
        Logger->>Logger: Suppress callback and console
    end

    App->>Stagehand: stagehand.close()
    Stagehand->>BrowserExt: Cleanup extension (Browserbase: delete on browser.close())
    Stagehand-->>App: stagehand.initialized = false

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>