@jxsuite/protocol 2.3.1 → 2.5.0

package/README.md

@@ -17,7 +17,7 @@ A backend is free to change the transport and path prefix; the **sub-path, metho
 
 ## 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.
+Optional routes back optional `StudioPlatform` members, or, like `filesRead`, back no member and let an adapter serve one it already has more cheaply (their `degradation` names the route they stand in for). 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:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/protocol",
-  "version": "2.3.1",
+  "version": "2.5.0",
   "description": "The Studio Backend Protocol — wire types and the canonical route table every Jx Studio backend implements",
   "license": "MIT",
   "repository": {
@@ -27,6 +27,6 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/schema": "^2.2.0"
+    "@jxsuite/schema": "^2.3.0"
   }
 }

package/src/index.ts

@@ -1,7 +1,6 @@
 /**
- * The Studio Backend Protocol package: wire types plus the canonical route
- * table every Jx Studio backend implements. See README.md for the implementer
- * guide.
+ * The Studio Backend Protocol package: wire types plus the canonical route table every Jx Studio
+ * backend implements. See README.md for the implementer guide.
  *
  * @license MIT
  */
@@ -10,3 +9,5 @@ export * from "./problem";
 export * from "./problems";
 export * from "./routes";
 export type * from "./types";
+// The one runtime value types.ts carries: the batch-read limit a backend and a client both size to.
+export { READ_FILES_MAX_PATHS } from "./types";

package/src/routes.ts

@@ -1,10 +1,10 @@
 /**
- * Studio Backend Protocol — the canonical route table. The dev server
- * (@jxsuite/server) is the reference implementation; every other backend
- * (desktop RPC bridge, cloud platforms) serves the same shapes, either at
- * these literal paths or through an equivalent transport. Optional routes
- * back optional StudioPlatform members — Studio degrades without them, as
- * described by each entry's `degradation`.
+ * Studio Backend Protocol — the canonical route table. The dev server (@jxsuite/server) is the
+ * reference implementation; every other backend (desktop RPC bridge, cloud platforms) serves the
+ * same shapes, either at these literal paths or through an equivalent transport. Optional routes
+ * mostly back optional StudioPlatform members — Studio degrades without them, as described by each
+ * entry's `degradation`. A few back no member at all: an adapter uses them to serve members it
+ * already has more cheaply (`filesRead`), and their `degradation` is the route they stand in for.
  *
  * @license MIT
  */
@@ -28,7 +28,10 @@ export type StudioRouteMethod = "GET" | "POST" | "PUT" | "DELETE";
 export interface StudioRoute {
   path: string;
   method: StudioRouteMethod;
-  /** True when a backend may omit the route (its PAL member is optional). */
+  /**
+   * True when a backend may omit the route: its PAL member is optional, or it has no member and an
+   * adapter falls back to another route.
+   */
   optional: boolean;
   /** One-line contract summary. */
   summary: string;
@@ -83,7 +86,7 @@ export const STUDIO_ROUTES = {
     "GET",
     "/__studio/locate-directory",
     `Resolve the absolute path of a showDirectoryPicker() folder by the id in its ${LOCATION_ID_FILE}`,
-    "The New Project Location field loses its Browse… button and is typed by hand.",
+    "Browse… reports that the folder could not be placed; the Location is typed by hand.",
   ),
   createProject: route(
     "POST",
@@ -111,6 +114,31 @@ export const STUDIO_ROUTES = {
       "files project-wide",
   ),
   fileRead: route("GET", "/__studio/file", "Read a file's text content"),
+  /**
+   * Many reads in ONE round trip, for a backend whose every request is a network hop.
+   *
+   * The first optional route with no `StudioPlatform` member behind it: the PAL keeps `readFile`,
+   * and an adapter for such a backend coalesces the reads issued in one tick into this call itself
+   * (specs/desktop.md §3.1, §10.1). Callers never see it, so a backend without it costs latency and
+   * nothing else — which is why the dev server, whose reads are loopback, does not serve it.
+   *
+   * The answer is partial by design, never a 400: past `READ_FILES_MAX_PATHS` paths or the
+   * backend's byte budget, the rest come back in `omitted` for the client to ask again, and the
+   * first path is always answered so that asking again makes progress. Each answered path carries
+   * its own outcome, because one missing file is not a failed batch. It is a READ: a read-only
+   * session may call it, and whatever a single `fileRead` does on the backend's side (a cloud
+   * session fetches and stores the file it serves) this does per path too.
+   */
+  filesRead: route(
+    "POST",
+    "/__studio/files/read",
+    "Read many files' text content {paths} → ReadFilesResult {files: [path, {content} | " +
+      "{error: {status, code?, message}}][], omitted}. At most READ_FILES_MAX_PATHS (200) paths " +
+      "and a backend byte budget per call: the excess is listed in `omitted` (never a 400) and " +
+      "the first path is always answered. Per-path errors: 404 missing/deleted, 415 binary, 413 " +
+      "too large, 502 upstream. Allowed for read-only sessions; keeps fileRead's server-side effects",
+    "Adapters fall back to one fileRead per path.",
+  ),
   fileWrite: route("PUT", "/__studio/file", "Write a file's text content"),
   fileDelete: route("DELETE", "/__studio/file", "Delete a file"),
   fileUpload: route(
@@ -119,6 +147,31 @@ export const STUDIO_ROUTES = {
     "Upload binary content to a path → UploadResult {path, size?}. `path` is the answer, not an " +
       "echo: a store that de-duplicates, suffixes, or normalizes names reports what it really wrote",
   ),
+  /**
+   * A project file's raw BYTES, as an answer rather than as a URL.
+   *
+   * `fileRead` cannot serve this and never could: it answers `readFile(abs, "utf8")`, and Bun
+   * replaces every byte sequence that is not valid UTF-8 with U+FFFD — so a JPEG round-trips
+   * through it as mojibake, silently and losslessly-looking. A caller that wants to DECODE a
+   * project image (Studio's image editor) needs the bytes intact.
+   *
+   * Distinct from {@link documentRaw}, which serves files at a URL a `<img src>` or a `fetch` in
+   * the canvas realm can name. That is the right shape for rendering and the wrong one for reading:
+   * on the desktop the canvas origin is a cross-origin loopback, and `server.md` §4.2 bans CORS
+   * outright, so nothing in the shell can read those bytes back. This route is addressed by the
+   * PAL, not by a document, which is what lets every backend answer it the same way.
+   *
+   * `Cache-Control: no-store`, deliberately unlike `fileRead`'s `max-age=5`: the caller is an
+   * editor about to overwrite the file, and five seconds of staleness is an edit applied to the
+   * wrong bytes.
+   */
+  fileBytes: route(
+    "GET",
+    "/__studio/file/bytes",
+    "A project file's raw bytes, undecoded — the read side of `fileUpload`, for a caller that must " +
+      "not go through UTF-8",
+    "Studio can only read a project file as text, so any surface that must decode one stays hidden.",
+  ),
   /**
    * A project file as its own BYTES, at its own URL.
    *
@@ -450,7 +503,10 @@ export function coreRouteNames(): StudioRouteName[] {
   );
 }
 
-/** Names of the optional routes (each backs an optional StudioPlatform member). */
+/**
+ * Names of the optional routes (each backs an optional StudioPlatform member, or is an adapter's
+ * optimisation with a fallback).
+ */
 export function optionalRouteNames(): StudioRouteName[] {
   return (Object.keys(STUDIO_ROUTES) as StudioRouteName[]).filter(
     (name) => STUDIO_ROUTES[name].optional,

package/src/types.ts

@@ -1,8 +1,7 @@
 /**
- * Studio Backend Protocol — wire types. Every shape a Studio backend serves
- * (or a `StudioPlatform` adapter consumes) lives here so client adapters and
- * server implementations (the dev server, the desktop RPC bridge, cloud
- * platforms) share one contract. Environment-agnostic: no DOM, no node —
+ * Studio Backend Protocol — wire types. Every shape a Studio backend serves (or a `StudioPlatform`
+ * adapter consumes) lives here so client adapters and server implementations (the dev server, the
+ * desktop RPC bridge, cloud platforms) share one contract. Environment-agnostic: no DOM, no node —
  * importable in browsers, Bun, and Cloudflare Workers alike.
  *
  * @license MIT
@@ -87,6 +86,45 @@ export interface UploadResult {
   size?: number;
 }
 
+/**
+ * The most paths one `filesRead` request may name. A backend answers at most this many and lists
+ * the rest under {@link ReadFilesResult.omitted}, so a client that sends more is not refused — it is
+ * answered in part, and asks again.
+ *
+ * The one runtime value in this file: a client sizes its batches to it, so it has to exist at
+ * runtime rather than only in a summary string.
+ */
+export const READ_FILES_MAX_PATHS = 200;
+
+/** Body of `POST /__studio/files/read` (`filesRead`): the project-relative paths to read. */
+export interface ReadFilesRequest {
+  paths: string[];
+}
+
+/**
+ * One path's answer inside a {@link ReadFilesResult}: its text, or why it has none.
+ *
+ * Per path rather than per request, because one unreadable file in a batch of two hundred is not a
+ * failed batch. `status` borrows the HTTP code the single-file read would have answered (404
+ * missing or deleted, 415 binary, 413 too large, 502 upstream), so a client can treat both routes'
+ * failures alike.
+ */
+export type ReadFilesOutcome =
+  | { content: string }
+  | { error: { status: number; code?: string; message: string } };
+
+/**
+ * Answer of `POST /__studio/files/read`. `files` pairs each answered path with its outcome;
+ * `omitted` lists the requested paths this response did not get to (a path or byte budget ran out).
+ * Omission is never an error and never a 400: the client asks for those paths again. A backend
+ * always answers the FIRST requested path, which is what guarantees that asking again makes
+ * progress.
+ */
+export interface ReadFilesResult {
+  files: [path: string, outcome: ReadFilesOutcome][];
+  omitted: string[];
+}
+
 /**
  * What a backend will accept as an upload, when it says.
  *
@@ -772,9 +810,10 @@ export interface AiModelsResponse {
    * lapsed", and those are different sentences on screen — the second one explains a thing that
    * used to work. `cf_upstream_error` is the third case and deliberately arrives WITH `configured:
    * true`: Cloudflare being briefly unreachable is not a reason to send someone round an OAuth flow
-   * that fixes nothing.
+   * that fixes nothing. `cf_account_required` is a live grant with no account chosen (ai.md §2.1):
+   * re-authorizing lands back in the same state, so it calls for the account picker instead.
    */
-  code?: "cf_not_connected" | "cf_reconnect_required" | "cf_upstream_error";
+  code?: "cf_not_connected" | "cf_reconnect_required" | "cf_account_required" | "cf_upstream_error";
 }
 
 // ─── Cloudflare publish surface ──────────────────────────────────────────────