@jxsuite/protocol

The Studio Backend Protocol: the wire types and canonical route table that every Jx Studio backend implements. Jx Studio is backend-agnostic. The editor talks to whatever registered a StudioPlatform adapter (see @jxsuite/studio/platform), and every adapter ultimately speaks the contract defined here. This package is the single source of truth for that contract:

• @jxsuite/protocol/types: the request/response shapes (DirEntry, GitStatusResult, StarterInfo, AiModelsResponse, CfConnection, …). Environment-agnostic, with no DOM and no node, so the types are importable in browsers, Bun, and Cloudflare Workers alike.
• @jxsuite/protocol/routes: STUDIO_ROUTES, the canonical endpoint table with methods, one-line contract summaries, and per-route optionality.

Who implements this

| Backend | Transport | | ------------------------------- | --------------------------------------------------------------------------------------------------------- | | @jxsuite/server (dev server) | The literal /__studio/* HTTP routes (the reference implementation) | | Desktop (Electrobun / Chromium) | Typed RPC / WebSocket JSON-RPC dispatching into the same handlers | | Cloud platforms | HTTP behind a session gateway (e.g. /api/v1/p/:owner/:repo/:branch/studio/*), same sub-paths and shapes |

A backend is free to change the transport and path prefix; the sub-path, method, and body shapes are the contract. STUDIO_PROTOCOL_VERSION bumps when any shape changes incompatibly.

Core vs optional

Optional routes back optional StudioPlatform members. Omitting one is not an error. Studio degrades exactly as each entry's degradation describes (the starter picker empties, the Projects catalogue hides, the Publish panel explains git-push publishing, and so on). coreRouteNames() / optionalRouteNames() split the table programmatically; a conformance test for a new backend can iterate STUDIO_ROUTES and assert every core route is served.

Highlights an implementer should know:

• git/commit commits the staged files if any are staged, otherwise all dirty files. Cloud backends may make commit+push atomic and treat git/push as a sync check (ahead stays 0).
• git/pull returns 409 { code: "pull_conflict", conflicts: [paths] } when local dirty files overlap remote changes.
• format dispatches { format, action: "parse" | "serialize", source? | doc?, options? } through the project's format registry; without it only .json documents open.
• ai/chat accepts { messages, tools, systemPrompt, model } and streams the normalized StreamEvent SSE defined by @jxsuite/ai/streaming-client. ai/models returns AiModelsResponse; report configured: true when the backend holds credentials (Studio then unlocks the assistant without a locally stored key) and managed: true when the platform brokers them.
• cf/proxy is an allowlisted Cloudflare API passthrough (accounts and Pages projects/deployments only). Credentials are injected by the backend and must never be persisted by stateless implementations. On the dev server the credential is a header-borne user token, and on cloud platforms a vaulted OAuth token.
• Errors are { error, code?, detail? } (ErrorBody) with a meaningful HTTP status; code is the machine-readable discriminator Studio switches on (e.g. remote_moved, cf_not_connected, needs_installation_access).

Versioning

The types are published as TypeScript source (like every @jxsuite package) and follow the monorepo's release train. Within the monorepo, packages depend on it via workspace:^. Consumers install @jxsuite/protocol and import its /types and /routes entrypoints; its only runtime dependency is @jxsuite/schema.