@jxsuite/protocol 2.3.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/protocol",
-  "version": "2.3.0",
+  "version": "2.4.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/routes.ts

@@ -83,7 +83,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",
@@ -119,6 +119,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.
    *

package/src/types.ts

@@ -758,6 +758,13 @@ export interface AiModelsResponse {
   defaultModel?: string;
   /** Set when the upstream provider was unreachable and defaults were returned. */
   upstreamError?: number | string;
+  /**
+   * The upstream's own error message, when {@link upstreamError} is set. Populated from whatever
+   * envelope the upstream used — OpenAI's `{error}`, or an array-shaped one like Cloudflare's
+   * `{errors: [{message}]}` — so a caller can show the real reason (e.g. "No route for that URI")
+   * instead of a bare status code.
+   */
+  upstreamMessage?: string;
   /**
    * Why the backend holds no working credentials, when it holds none.
    *
@@ -765,9 +772,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 ──────────────────────────────────────────────