Rename V3Context to BrowserContext

[monadoid]

Renames the internal V3Context implementation to BrowserContext across the service worker, tests, and documentation. This is a naming-only change with no behavior changes.

---

Summary by cubic

Renamed the browser context class from V3Context to BrowserContext across server code and tests. Restored legacy V3 docs and merged latest v4-spike; fulfills Linear STG-2647 with no behavior changes.

• Refactors
  • Renamed class and factory in packages/server/understudy/context.ts to BrowserContext.
  • Updated service worker to call BrowserContext.create.
  • Adjusted clipboard types to accept BrowserContext.
  • Updated tests, mocks, and titles, including the smoke graph in rpc-client-smoke.test.ts.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: bbce9b7

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]

1 issue found across 10 files

Confidence score: 3/5

• In packages/docs/v3/references/context.mdx, the BrowserContext rename currently documents pages(), activePage(), and setActivePage() as synchronous, which can mislead TypeScript users into incorrect call patterns and cause type/runtime mismatches in real usage—update the declarations and code examples to async/Promise signatures to match the SDK.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/docs/v3/references/context.mdx">

<violation number="1" location="packages/docs/v3/references/context.mdx:777">
P2: The renamed `BrowserContext` reference gives TypeScript users incorrect synchronous signatures: `pages()`, `activePage()`, and `setActivePage()` are async in the SDK. Update this declaration and its examples so callers await these methods; otherwise code following the reference will operate on Promises rather than pages.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant SW as Service Worker
    participant CtxFactory as BrowserContext.create()
    participant BC as BrowserContext
    participant CDP as CdpConnection
    participant CT as ChromeTabTargetController
    participant Clip as Understudy Clipboard
    participant Page as Page

    Note over SW,Page: Renamed: V3Context → BrowserContext (no behavior change)

    SW->>CtxFactory: NEW: call BrowserContext.create(cdpUrl, opts)
    CtxFactory->>CDP: connect(wsUrl, websocketFactory, logger)
    CDP-->>CtxFactory: CdpConnection instance
    CtxFactory->>BC: NEW: new BrowserContext(conn, logger, chromeTabs)
    BC-->>CtxFactory: BrowserContext instance
    CtxFactory-->>SW: BrowserContext

    Note over SW,Clip: Service worker uses BrowserContext for page management

    SW->>BC: context.pages()
    BC-->>SW: Page[]
    SW->>BC: context.newPage(url?)
    BC->>CDP: Target.createTarget
    CDP-->>BC: targetId
    BC->>Page: create & register
    BC-->>SW: Page

    SW->>BC: context.activePage()
    BC->>CT: getActiveTargetId()
    CT-->>BC: targetId
    BC->>Page: lookup by targetId
    BC-->>SW: Page

    alt Clipboard operations
        SW->>Clip: paste({ context, resolvePage })
        Clip->>BC: context.pages()
        BC-->>Clip: Page[]
        Clip->>Page: evaluate clipboard
        Page-->>Clip: result
        Clip-->>SW: paste result
    end

    Note over BC,CT: BrowserContext manages CDP connection lifecycle
    BC->>BC: handleTargetCreated / handleTargetDestroyed
    BC->>CDP: on(Target.targetCreated)
    BC->>CDP: on(Target.targetDestroyed)
    BC->>CT: delegate Chrome tab activation
    CT-->>BC: active target resolution

Loading

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

Re-trigger cubic</sub>

[akeimach]

some v3 docs changes in here that shouldn't be. Rest is good

[akeimach]

fabulous