Cloud Web Studio¶

Cloud Web is the Open Cowork Studio running in the browser for cloud workspaces. It is not a separate UI. The single renderer at packages/app/src powers both Desktop (Electron, over the real window.coworkApi IPC bridge) and Cloud Web (the browser, over a typed CoworkAPI shim at packages/app/src/browser/cowork-api.ts). The shim is backed by the cloud HTTP + SSE API, so the browser build of the renderer runs unchanged against the same tenant-scoped sessions, projections, workflows, artifacts, policy, and gateway records used by Desktop Cloud and Gateway. The cloud server serves the renderer at GET / and must not expose server-only stores, secret adapters, runtime adapters, or OpenCode SDK surfaces to the browser.

The canonical workspace and sync promises live in Product Contract. This page is the release contract for the browser surface.

Route/API Matrix¶

The browser surface and its cloud backing are documented below. The cloud HTTP API (packages/cloud-server/src/http-routes) and the browser CoworkAPI shim (packages/app/src/browser/cowork-api.ts) enforce required role, backing endpoint ids, loading/empty/error states, disabled-state behavior, pagination or cursor notes, and redaction requirements. Cloud HTTP server and renderer tests fail if a route omits its limit/cursor mode, raw-secret policy, or loading/empty/error state contract.

Desktop/Cloud Studio Parity Matrix¶

Because Desktop and Cloud Web run the same renderer, visual and behavioral parity is intrinsic — there is no second implementation to drift. The only differences are the capabilities the browser shim cannot provide (local filesystem, local stdio MCP processes, native dialogs, machine runtime config), which the renderer detects through workspace.support() and the shim's WORKSPACE_SUPPORT_APIS. The matrix below documents which shared Desktop concepts are available, cloud-only, or desktop-only so the product boundary stays explicit.

Admin/Settings Surface Matrix¶

Cloud Web admin route summaries, rendered admin surface cards, and locked-control copy are owned by the renderer's admin/settings surfaces. The matrix below documents every admin surface, its desktop analog, and its sensitive boundary so the admin path stays a secondary surface and its authorization stays server-side.

End-User Studio Contract¶

Cloud Web must keep parity with Desktop Cloud for cloud workspaces:

• start and continue Cloud chats
• hydrate from the full Cloud SessionView projection
• render messages, task runs, tool calls, approvals, questions, todos, artifacts, cost, status, and errors
• send prompts through durable Cloud commands
• answer approvals and questions through Cloud APIs
• reconnect SSE from durable projection cursors
• browse artifact metadata and fetch bodies only on explicit action
• run playbooks through the Cloud workflow API
• review connected channel coworkers, bindings, and delivery status without exposing admin controls or delivery payloads
• show custom coworker, skill, and MCP metadata with policy verdicts

The browser must not create a second projection model. It consumes Cloud snapshots and events through the shared API contract.

Shared IA Contract¶

Cloud Web and Desktop share the same Studio IA because they are the same renderer. The shared layout primitives expose stable data-workbench-* hooks for tests:

• data-workbench-pane="threads" marks the thread list/sidebar.
• data-workbench-pane="conversation" marks the active chat surface.
• data-workbench-pane="review" marks the contextual review pane.
• data-action-cluster="true" marks the consolidated chat/action toolbar.
• data-diff-view="true" marks review-first artifact and diff surfaces.

The renderer uses WorkbenchLayout, ActionCluster, and DiffView from @open-cowork/ui on both surfaces. The Cloud review pane presents runtime status and sanitized artifacts; artifact metadata remains review-first and fetches bodies only after explicit view or download actions. Desktop-only actions, such as local runtime or git-native controls, stay absent or disabled in Cloud because the browser shim reports them as unsupported through workspace.support().

Unified Renderer¶

Cloud Web is the browser build of the desktop renderer (packages/app/src). pnpm cloud:build runs pnpm --filter @open-cowork/desktop build:browser to emit the renderer's browser bundle (apps/desktop/dist-browser), and the cloud server serves it at GET / through packages/cloud-server/src/browser-renderer-app.ts. The entry document loads hashed module/asset scripts and installs the browser CoworkAPI shim (packages/app/src/browser/cowork-api.ts), which derives the endpoint base from window.location, reads the CSRF token from /auth/me, and talks only to the same-origin cloud /api, /auth, and SSE event routes under the server's CSP nonce boundary.

The renderer is written entirely against the typed CoworkAPI surface (from @open-cowork/shared). On Electron the preload supplies that object over IPC; in the browser the shim supplies the identical object backed by cloud HTTP + SSE, so no feature code branches on environment. Electron-only methods (native dialogs, runtime restart, desktop pairing, local FS imports, app reset) have no cloud equivalent and the shim implements them as signature-satisfying stubs that no-op or reject with a clear "unavailable in the browser build" message. New feature work uses the shared CoworkAPI contract (defined in packages/shared/src) through the browser client packages/app/src/browser/cowork-api.ts rather than direct fetch, EventSource, or window.coworkApi access.

/api/sessions cursors are opaque, scoped to the authenticated tenant, user, and active filters, and invalid or mismatched cursors fail closed with 400. Workspace SSE refreshes rehydrate the same number of loaded pages rather than collapsing a large thread list back to page one.

Admin Contract¶

Admin and operator surfaces must avoid direct database or shell access for normal operations:

• members, invite mode, roles, and status
• profile, capability, project-source, runtime, and gateway policy summaries
• BYOK provider status and write-only key rotation
• API tokens for Desktop and Gateway clients
• billing and entitlement status
• quota windows, usage totals, and usage event samples
• org-scoped managed worker pools and worker health summaries
• headless agents, channel bindings, and delivery backlog
• redacted audit logs and diagnostics

Sensitive mutations must be role-checked by the Cloud API and auditable. Browser disabled controls are only ergonomic hints; authorization remains server-side.

Browser Quality Gates¶

Because Cloud Web is the same renderer as Desktop, its UI is covered by the renderer suite and the cloud HTTP/continuation suites. Cloud Web changes should run:

pnpm test:renderer

For release-sensitive changes also run:

pnpm lint
pnpm typecheck
pnpm test
pnpm test:cloud-continuation
pnpm cloud:smoke
pnpm docs:build
git diff --check

These gates cover renderer behavior and accessibility, the cloud HTTP route and redaction contract, backend cursor validation, package-boundary checks that keep the renderer out of server-only modules, and a production cloud-bundle build + import smoke so the browser renderer build keeps shipping in the cloud image.

Visual QA Checklist¶

For visual or surface-organization changes, compare Cloud Web and Desktop side-by-side before merge. The expected match is product language and workflow parity, not pixel-perfect screenshots.

The matrix below must cover every Cloud Web route at desktop, tablet, and mobile widths. Because Desktop and Cloud Web are the same renderer, a desktop-verified surface only needs the browser to confirm the cloud shim's boundaries (no local filesystem, no stdio MCPs, server-side authorization) and responsive layout.

Studio Production Visual QA Matrix¶

• App shell, sidebar, topbar, active route, status text, and density use the same dark product language.
• Cards, panels, tables, rows, badges, notices, empty states, focus rings, and destructive/primary/secondary controls read like Desktop primitives.
• Projects, chat, runtime status, approvals, questions, coworkers, tools, skills, playbooks, channels, artifacts, and Knowledge map to the Desktop/Cloud parity matrix.
• Org, members, policy, BYOK, connections, gateway, billing, audit, usage, and diagnostics map to the admin/settings surface matrix.
• GET / returns the renderer entry document, which loads hashed /assets/* module scripts under the server CSP nonce and boots against the cloud API.
• Loading, empty, error, disabled, confirmation, and one-time reveal states stay visible and consistent without exposing secrets.
• Desktop-only boundaries remain explicit: no local host paths, local stdio MCP process controls, machine runtime config, or browser-owned OpenCode runtime.
• Responsive desktop and mobile views have no horizontal overflow, clipped controls, or unreachable keyboard focus targets.
• /assets/fonts/*.woff2 requests return 200 font/woff2 and computed fonts resolve to Mona Sans / Schibsted Grotesk in the real-browser smoke.
• The renderer's hashed /assets/* module and stylesheet routes are served with long-lived immutable cache headers, and the real-browser smoke verifies the nonce'd entry document loads and mounts the renderer.

Production Audit Checklist¶

This checklist is the closeout audit for Studio parity work before the roadmap can be considered complete. Since Desktop and Cloud Web are the same renderer, most rows are satisfied by the renderer suite plus the cloud HTTP/redaction suite.

Knowledge/OpenWiki Integration¶

Knowledge now ships as an app-owned native module: Cloud Web exposes a Knowledge route, the Chat route includes a Capture to knowledge CTA, and both Desktop and Cloud Web consume the same Cloud/API-client contract for Spaces, versioned pages, pending proposals, review decisions, page history, and graph context.

This phase deliberately does not embed or depend on a local OpenWiki checkout. Do not couple Cloud Web, Desktop, Gateway, or the Cloud API to a local OpenWiki checkout. External OpenWiki embedding remains a later roadmap phase; until that roadmap replaces this contract, Knowledge stays a native Open Cowork product module layered around OpenCode sessions rather than a second runtime.