@jxsuite/protocol 1.2.1 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/protocol",
-  "version": "1.2.1",
+  "version": "2.0.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": "^1.8.1"
+    "@jxsuite/schema": "^1.9.0"
   }
 }

package/src/routes.ts

@@ -112,7 +112,34 @@ export const STUDIO_ROUTES = {
   fileRead: route("GET", "/__studio/file", "Read a file's text content"),
   fileWrite: route("PUT", "/__studio/file", "Write a file's text content"),
   fileDelete: route("DELETE", "/__studio/file", "Delete a file"),
-  fileUpload: route("POST", "/__studio/file/upload", "Upload binary content to a path"),
+  fileUpload: route(
+    "POST",
+    "/__studio/file/upload",
+    "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 as its own BYTES, at its own URL.
+   *
+   * `fileRead` answers `{ path, content }`, which is right for the editor and useless to the
+   * renderer: `@jxsuite/runtime` resolves a component `$ref` with `fetch(url).then(r => r.json())`
+   * and expects the DOCUMENT, and an `<img src>` cannot be a JSON envelope at all. So a backend
+   * whose origin does not serve the site's own URL space serves this instead, declares `assetSpace:
+   * "repo"`, and Studio addresses every project file under it.
+   *
+   * The path is appended to the prefix, so this is the one route whose `path` is a PREFIX rather
+   * than a whole path. It was a textual assertion on both sides of the cloud seam before it was a
+   * route; naming it here is what makes that assertion a contract.
+   */
+  documentRaw: route(
+    "GET",
+    "/__studio/raw/",
+    "A project file as its own bytes, at its own URL — the mount a canvas renders against when " +
+      "the editor origin does not serve the site's URL space. The project-relative path is " +
+      "appended to this prefix",
+    "The canvas cannot address project files by URL, so a host whose origin does not serve the " +
+      "site URL space renders no component $refs and no images.",
+  ),
   fileRename: route("POST", "/__studio/file/rename", "Rename/move (+ refactor report)"),
   references: route(
     "GET",

package/src/types.ts

@@ -68,6 +68,43 @@ export interface RenameResult {
   error?: string;
 }
 
+/**
+ * What an upload actually stored.
+ *
+ * `path` is the ANSWER, not an echo. A backend may store the bytes somewhere other than the path
+ * asked for — a store that de-duplicates by content hash, one that appends a collision suffix, one
+ * that normalizes a name — and the client has to write a reference to what was really written. The
+ * upload response used to be untyped (`Promise<unknown>`), and every caller ignored it and used the
+ * requested path, so any such backend produced a document pointing at a file that is not there.
+ *
+ * `size` is what the backend recorded, when it says: the client already knows the bytes it sent, so
+ * a differing value is the backend telling you it transformed them.
+ */
+export interface UploadResult {
+  /** Project-relative path the bytes were stored at. */
+  path: string;
+  /** Stored size in bytes, when the backend reports one. */
+  size?: number;
+}
+
+/**
+ * What a backend will accept as an upload, when it says.
+ *
+ * Every field is optional and absence means "no declared limit" — a client must not invent one,
+ * because a limit it made up is a file the user cannot upload for no reason it can name. A DECLARED
+ * limit is different: it lets the client refuse before spending the round trip, and name the number
+ * in the refusal.
+ */
+export interface AssetCapabilities {
+  /** Largest single upload the backend accepts, in bytes. */
+  maxUploadBytes?: number;
+  /**
+   * Media types and extensions the backend accepts, in `<input accept>` syntax (`"image/*,.pdf"`).
+   * Narrows the client's own default; it never widens it.
+   */
+  accept?: string;
+}
+
 /** One kind of reference in one file, with how many times it occurs there. */
 export interface ReferenceHit {
   /**
@@ -389,6 +426,24 @@ export interface SecretsSetResponse {
   names: string[];
 }
 
+// ─── User settings (desktop launchers; specs/desktop.md §3.1) ───────────────
+
+/**
+ * A set of changes to the user-level settings store.
+ *
+ * A patch rather than the whole map, and for the same reason {@link SecretsSetRequest} is one: a key
+ * named by neither `set` nor `remove` must be left exactly as it was found. Writing the whole map
+ * let any window overwrite the shared store with its own view of it — and on the chromium launcher
+ * every window is a separate process with a separate browser profile, so a window holding no
+ * settings could clear the credentials another had just stored.
+ */
+export interface SettingsPatch {
+  /** Keys to store, with their new values. */
+  set?: Record<string, string>;
+  /** Keys to forget. */
+  remove?: string[];
+}
+
 // ─── Packages ────────────────────────────────────────────────────────────────
 
 export interface PackageInfo {