@jxsuite/protocol 1.2.1 → 2.1.0

package/README.md

@@ -1,23 +1,23 @@
 # @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
+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`,
+- `@jxsuite/protocol/types`: the request/response shapes (`DirEntry`,
   `GitStatusResult`, `StarterInfo`, `AiModelsResponse`, `CfConnection`, …).
-  Environment-agnostic: no DOM, no node — importable in browsers, Bun, and
-  Cloudflare Workers alike.
-- `@jxsuite/protocol/routes` — `STUDIO_ROUTES`, the canonical endpoint table
+  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                                      |
+| `@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 |
 
@@ -28,7 +28,7 @@ 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
+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
@@ -51,9 +51,10 @@ doc?, options? }` through the project's format registry; without it only
   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 —
-  a header-borne user token on the dev server, a vaulted OAuth token on cloud
-  platforms — and must never be persisted by stateless implementations.
+  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`).

package/package.json

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

package/src/routes.ts

@@ -107,19 +107,54 @@ export const STUDIO_ROUTES = {
   files: route(
     "GET",
     "/__studio/files",
-    "List a directory (DirEntry[]); with ?glob=<pattern>, search matching files project-wide",
+    "List a directory (DirEntry[]) in stable path order; with ?glob=<pattern>, search matching " +
+      "files project-wide",
   ),
   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"),
-  fileRename: route("POST", "/__studio/file/rename", "Rename/move (+ refactor report)"),
+  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). `from`/`to` are server-root-relative; every path in the " +
+      "report is relative to the active project (specs/server.md §4.1)",
+  ),
   references: route(
     "GET",
     "/__studio/references",
     "Where a file or a component tag is used (?path=&tag=, at least one) → ReferencesResult " +
       "{files, filesReferencing, refsTotal} — the read side of the rename refactor's own walker, " +
-      "cached until the backend's watcher sees the tree move (backs findReferences)",
+      "cached until the backend's watcher sees the tree move (backs findReferences). `?path=` is " +
+      "server-root-relative and every path in the answer is relative to the active project; a " +
+      "target outside that project is a 400, never a zero-result 200 (specs/server.md §4.1)",
     'Usage counts are hidden: no "Used on N pages" in the inspector, no Selection: Find Usages, ' +
       "and delete/rename confirmations state no reference count.",
   ),
@@ -208,12 +243,49 @@ export const STUDIO_ROUTES = {
    * these paths mean the project's SOURCES, and a built page addresses its own OUTPUT by the same
    * paths (`/components/x.js` is the formula module here and the custom element there), so a
    * backend serves the built site somewhere of its own and says where.
+   *
+   * A backend that cannot run the compiler at all — a hosted one executes no project JS and has no
+   * bundler, image pipeline or filesystem — may instead serve the working tree as a site and let
+   * the runtime assemble each page in the reader's browser. `mode` reports which happened, and an
+   * absent `mode` means `built`, so a backend predating the field keeps its meaning.
    */
   buildSite: route(
     "POST",
     "/__studio/build",
-    "Build the site to its output directory → {routes, files, errors, url}",
-    "Open in Browser reports that this target cannot build a preview.",
+    "Build or render the site → {routes, files, errors, mode?, url}",
+    "Build Site reports that this target cannot build.",
+  ),
+
+  /**
+   * Preview the site LIVE at a route, with no build on the path.
+   *
+   * The sibling of `buildSite` and what `Open in Browser` reaches first. Nothing is compiled: the
+   * working tree is composed on demand and the runtime assembles each page in the reader's browser,
+   * so what opens carries edits nobody has saved (see `previewOverlay`).
+   *
+   * `reused` is the answer a caller must honour: `true` means a client already holding this
+   * project's preview took the route, and opening a tab anyway would leave the author with two on
+   * one project.
+   */
+  previewSite: route(
+    "POST",
+    "/__studio/preview",
+    "Preview the working tree at a route → {routes, files, errors, mode, url, reused}",
+    "Open in Browser falls back to buildSite.",
+  ),
+
+  /**
+   * The unsaved bytes a live preview reads before the disk.
+   *
+   * POST publishes one document's bytes, DELETE retracts one (or all, with no path). The editor
+   * owns the lifecycle — it knows which documents are dirty and when a save, a close or a discard
+   * ends that — so a backend stores what it is told and decides nothing.
+   */
+  previewOverlay: route(
+    "POST",
+    "/__studio/preview/overlay",
+    "Publish (POST) or retract (DELETE) a document's unsaved bytes → 204",
+    "A live preview shows the last saved state instead of the editor's.",
   ),
 
   // ─── Packages ─────────────────────────────────────────────────────────────
@@ -232,11 +304,11 @@ export const STUDIO_ROUTES = {
     "Whether node_modules is stale",
     "The install-on-open prompt never shows.",
   ),
-  packagesOutdated: route(
+  packagesVersions: route(
     "GET",
-    "/__studio/packages/outdated",
-    "Dependencies with newer versions (OutdatedInfo[])",
-    "The update affordances are hidden.",
+    "/__studio/packages/versions",
+    "Newest published version of each dependency (PackageVersionInfo[])",
+    "The Latest column stays empty and the update affordances are hidden.",
   ),
   packagesSetVersions: route(
     "POST",

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 {
@@ -398,15 +453,20 @@ export interface PackageInfo {
   dev?: boolean;
 }
 
-/** A dependency with a newer version available, as reported by `bun outdated` / the npm registry. */
-export interface OutdatedInfo {
+/**
+ * A dependency's pinned range beside the newest version published for it on the npm registry.
+ *
+ * Reported for EVERY dependency whose spec is a registry range, whether or not it is behind — "is
+ * this outdated?" is a comparison the caller makes, not a filter the backend applies. That matters
+ * for the Packages table, which shows a Latest column for every row: a backend that only answered
+ * about outdated packages could describe the up-to-date ones only as a blank.
+ */
+export interface PackageVersionInfo {
   name: string;
   /** The version range pinned in package.json (e.g. "^0.19.0"). */
   current: string;
-  /** The newest published version. */
+  /** The newest version published for this package on the registry. */
   latest: string;
-  /** The newest version satisfying the current range, if known. */
-  wanted?: string;
   dev?: boolean;
 }
 
@@ -476,6 +536,40 @@ export interface ImportProgressEvent {
   total?: number;
 }
 
+/**
+ * How many of a site's declared breakpoints the imported project keeps.
+ *
+ * A real site declares as many as it has accumulated frameworks — nine is ordinary — and each one
+ * becomes a canvas size in Studio and a column in every style editor. `limit` is the default
+ * because that is the complaint it answers; `explicit` is for an author who already knows the
+ * widths their project should have. `rounding` decides which DECLARED width backs a kept one, since
+ * the styles flip where the site says they do, not where the author wishes they did.
+ */
+export type BreakpointRounding = "nearest" | "down" | "up";
+
+export interface ImportBreakpointPolicy {
+  mode: "all" | "limit" | "explicit";
+  /** `limit` only — how many to keep, evenly spaced across the declared range. */
+  count?: number;
+  /** `explicit` only — the widths the project should have, in CSS pixels. */
+  widths?: number[];
+  /** `limit` and `explicit` — how a kept width matches a declared one. */
+  rounding?: BreakpointRounding;
+}
+
+/**
+ * The line the import stream sends the moment the destination exists and holds a `project.json`.
+ *
+ * It is what makes an import watchable. The emit phase rewrites that file completely, so nothing
+ * here is a guess about the result — it says the directory is now a PROJECT, so the caller can open
+ * it and see the pages, components and assets arrive in its own file tree over the several minutes
+ * a crawl takes, rather than facing a welcome screen until the run ends.
+ */
+export interface ImportReadyEvent {
+  /** The project root, in the platform's own form. */
+  root: string;
+}
+
 /** Options for the import-site pipeline (StudioPlatform.importSite). */
 export interface ImportSiteOptions {
   /** The live site to clone; must be http(s). */
@@ -488,14 +582,89 @@ export interface ImportSiteOptions {
   depth: number;
   /** Max pages to capture. */
   maxPages: number;
+  /** Which of the site's declared breakpoints the project keeps. Omitted means the default limit. */
+  breakpoints?: ImportBreakpointPolicy;
   /** Refine component/prop names with the LLM (requires a key). */
   aiComponents: boolean;
+  /**
+   * Build the emitted project and screenshot-diff every page against the original.
+   *
+   * Off by default: it runs a full compile and a second browser pass, so it roughly doubles the
+   * run. What it buys is the one number the assistant can act on — a page at 61% fidelity is a
+   * question worth asking, and every other finding is a count of things that were skipped.
+   */
+  verify?: boolean;
+  /**
+   * Pixelmatch's per-pixel COLOUR tolerance, 0..1, for `verify` (default 0.15).
+   *
+   * It decides when two pixels count as the same colour, so it moves the score and never the
+   * outcome. `verifyMinFidelity` is the bar.
+   */
+  verifyThreshold?: number;
+  /**
+   * The average fidelity, 0..100, this run has to reach for `verify` to report `passed`.
+   *
+   * A finding rather than a failure on this transport: the project is written and opened either
+   * way, and the summary says the bar was missed. `jx-import` uses the same number to decide an
+   * exit code, because a script in a pipeline has no reader to tell.
+   */
+  verifyMinFidelity?: number;
   /** OpenAI-compatible credentials, from the user's AI settings. */
   apiKey?: string;
   baseUrl?: string;
   model?: string;
 }
 
+/** Per-page fidelity from the `verify` pass. */
+export interface ImportVerifyPage {
+  route: string;
+  /** 0..100 — the percentage of pixels that matched the original. */
+  fidelity: number;
+  /**
+   * Console errors and uncaught exceptions the rendered page produced.
+   *
+   * What a percentage cannot say. A page that 404s on fifteen images scores badly, and only this
+   * and `failedRequests` name the reason (issue #232).
+   */
+  consoleErrors?: number;
+  /** Requests the rendered page made that failed or answered 4xx/5xx. */
+  failedRequests?: number;
+  /** Why this page has no score at all — it could not be rendered. */
+  error?: string;
+}
+
+/**
+ * What the run produced, carried on the import stream's terminal `done` line.
+ *
+ * It exists because the pipeline computed all of this and the HTTP layer threw it away: the `done`
+ * line carried `{root, config}` and nothing else, so the caller could report that an import had
+ * happened and nothing whatever about what it found. Every field is optional — a backend that does
+ * not send one is not broken, and an older client ignores them.
+ */
+export interface ImportSiteSummary {
+  pages?: { route: string; title: string; nodeCount: number }[];
+  fileCount?: number;
+  /** Soft failures the pipeline recorded: assets that would not download, pages it skipped. */
+  warnings?: string[];
+  /** Present only when `verify` was requested and reference screenshots were captured. */
+  verify?: {
+    averageFidelity: number;
+    reportDir: string;
+    pages?: ImportVerifyPage[];
+    /**
+     * Whether the run met its bar: the project built cleanly, every page rendered, and the average
+     * fidelity reached `minFidelity`. Over HTTP that bar is 0 by default, so `passed: false` from
+     * this backend means the project did not build or a page did not render — not that the clone
+     * merely scored low. The `jx-import` CLI sets a real floor and exits non-zero.
+     */
+    passed?: boolean;
+    /** The bar `passed` was measured against, 0..100. */
+    minFidelity?: number;
+    /** Errors the compiler reported building the emitted project. */
+    buildErrors?: string[];
+  };
+}
+
 // ─── AI proxy ────────────────────────────────────────────────────────────────
 
 /** One entry of the AI proxy's model catalogue. */