@jxsuite/protocol 2.0.0 → 2.2.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": "2.0.0",
+  "version": "2.2.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.9.0"
+    "@jxsuite/schema": "^2.1.0"
   }
 }

package/src/routes.ts

@@ -107,7 +107,8 @@ 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"),
@@ -140,13 +141,20 @@ export const STUDIO_ROUTES = {
     "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)"),
+  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.",
   ),
@@ -235,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 ─────────────────────────────────────────────────────────────
@@ -259,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

@@ -453,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;
 }
 
@@ -531,26 +536,139 @@ 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). */
   url: string;
   /** Display name for the new project. */
   name: string;
-  /** Destination directory (platform-interpreted: project-relative on the dev server). */
+  /**
+   * Where the project goes, interpreted by the platform that receives it: an absolute path on
+   * desktop, project-relative on the dev server, `owner/repo` on a host whose projects are
+   * repositories. Never a path the caller assumes a filesystem for.
+   */
   directory: string;
   /** Max crawl depth; 0 = single page. */
   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. */
@@ -587,9 +705,61 @@ export interface AiModelsResponse {
 
 // ─── Cloudflare publish surface ──────────────────────────────────────────────
 
-/** Cloudflare connection state (see StudioPlatform.cfConnection). */
+/**
+ * Cloudflare connection state (see StudioPlatform.cfConnection).
+ *
+ * Three answers, not two, and a reader tells them apart by SHAPE:
+ *
+ * - `null` — no credential and no row exists at all; nothing was ever connected here.
+ * - `{connected: false}` — a credential exists but the provider rejected it. That is the dev server's
+ *   stored-token-invalid case, and the publish panel's "Replace token" branch keys on it.
+ * - `{connected: true, needsReconnect: true}` — a brokered row exists whose OAuth grant has lapsed.
+ *   Its access token is gone or unrenewable, so every Cloudflare call will fail until the user goes
+ *   back through the hosted flow.
+ *
+ * Each platform emits a strict subset: **cloud never emits `{connected: false}`** (a broker row it
+ * cannot use is a reconnect, not a bad token) and **the dev server never emits `needsReconnect`**
+ * (it holds a pasted token, not a grant, so there is nothing to lapse). Collapsing the lapsed case
+ * into a healthy one is precisely the defect that let the connect popup close over a dead row while
+ * the user was still typing their Cloudflare password.
+ */
 export interface CfConnection {
   connected: boolean;
   accountId?: string | undefined;
   accountName?: string | undefined;
+  /** A broker row exists but its grant has lapsed — reconnect before any Cloudflare call. */
+  needsReconnect?: boolean | undefined;
+  /** Connected and usable, but no account has been chosen yet (multi-account connect). */
+  needsAccount?: boolean | undefined;
+  code?: "cf_reconnect_required" | "cf_account_required" | undefined;
+  reason?: string | undefined;
+  /**
+   * Whether the broker holds a refresh token for this row. Diagnostic: without one the connection
+   * dies at the access token's expiry and cannot renew itself silently, which is a degraded state
+   * worth naming on screen rather than discovering an hour later.
+   */
+  hasRefreshToken?: boolean | undefined;
+  /** Unix seconds at which the current access token expires (after any silent refresh). */
+  expiresAt?: number | undefined;
 }
+
+/** One Cloudflare account the connected grant can reach (the account picker's row). */
+export interface CfAccountSummary {
+  id: string;
+  name: string;
+}
+
+/**
+ * How an interactive `cfConnect` ended.
+ *
+ * A connect flow has four endings and only one of them is a failure, so they are a union rather
+ * than a nullable connection: `redirect` means the page is already navigating away and the caller
+ * must render nothing, `timeout` means the deadline passed with no confirmation, and `canceled`
+ * means the user closed the popup. Returning `null` for all three made "the user changed their
+ * mind" indistinguishable from "this browser blocked the popup", and the UI apologised for both.
+ */
+export type CfConnectOutcome =
+  | { status: "connected"; connection: CfConnection }
+  | { status: "redirect" }
+  | { status: "timeout" }
+  | { status: "canceled" };