@jxsuite/studio 2.0.0 → 2.1.0

package/src/platform.ts

@@ -10,6 +10,12 @@
  * init.js) before studio.js loads.
  *
  * See spec/desktop.md §3 for the full StudioPlatform interface.
+ *
+ * **Every call is counted.** `getPlatform()` hands out a counting proxy, not the raw adapter, so
+ * "is Studio waiting on I/O?" is one number rather than thirty hand-instrumented methods
+ * (`probe.idle()` condition 4, spec §13.5). Wrapping at the READ point rather than at
+ * `registerPlatform` is deliberate: desktop pre-registers its adapter on `window.__jxPlatform`
+ * without ever calling the registrar, and this is the seam both paths share.
  */
 
 import type { StudioPlatform } from "./types";
@@ -21,12 +27,100 @@ export function registerPlatform(platform: StudioPlatform) {
   g.__jxPlatform = platform;
 }
 
+// ─── In-flight accounting ─────────────────────────────────────────────────────
+
+/** Method name → how many of its calls have not settled. Entries are deleted at zero. */
+const inFlight = new Map<string, number>();
+
+/**
+ * One entry per platform call whose promise has not settled, named by its method.
+ *
+ * Repeats are meaningful: two concurrent `gitStatus` reads are two reasons the shell is not
+ * settled, and the rejection message that names them is the whole point of §13.4 — 115 sleeps were
+ * 115 places that could not fail.
+ */
+export function platformInFlight(): string[] {
+  const names: string[] = [];
+  for (const [method, count] of inFlight) {
+    for (let i = 0; i < count; i++) {
+      names.push(method);
+    }
+  }
+  return names;
+}
+
+function enter(method: string): void {
+  inFlight.set(method, (inFlight.get(method) ?? 0) + 1);
+}
+
+function leave(method: string): void {
+  const count = (inFlight.get(method) ?? 1) - 1;
+  if (count > 0) {
+    inFlight.set(method, count);
+  } else {
+    inFlight.delete(method);
+  }
+}
+
+/**
+ * Wrap an adapter so every promise-returning member is counted while it is outstanding.
+ *
+ * Synchronous members are passed through untouched — they cannot be outstanding. Wrappers are
+ * memoised per property so `platform.readFile === platform.readFile`, which matters because call
+ * sites cache and compare these (`live-context.ts` tests `typeof platform[key] === "function"` to
+ * derive `capability.*`, and a fresh closure per read would allocate on every predicate).
+ */
+function countingPlatform(platform: StudioPlatform): StudioPlatform {
+  const wrappers = new Map<PropertyKey, { raw: unknown; wrapper: unknown }>();
+  return new Proxy(platform, {
+    get(target, property) {
+      // `this` stays the raw adapter: a proxy receiver would re-enter this trap for every internal
+      // Property read the method makes, counting nothing and costing everything.
+      const value = Reflect.get(target, property) as unknown;
+      if (typeof value !== "function" || typeof property !== "string") {
+        return value;
+      }
+      // Keyed by the FUNCTION, not just the name: an adapter whose method is replaced later (a
+      // Lazily-installed capability, a test swapping one out) must not keep answering through a
+      // Wrapper closed over the old implementation.
+      const cached = wrappers.get(property);
+      if (cached && cached.raw === value) {
+        return cached.wrapper;
+      }
+      const method = property;
+      const wrapper = (...args: unknown[]): unknown => {
+        const result = (value as (...a: unknown[]) => unknown).apply(target, args);
+        if (typeof (result as PromiseLike<unknown> | null)?.then !== "function") {
+          return result;
+        }
+        enter(method);
+        const settle = () => {
+          leave(method);
+        };
+        // Both arms: a rejected platform call is a call that FINISHED. Leaving it counted would
+        // Wedge every later `idle()` behind an error the caller already handled.
+        (result as PromiseLike<unknown>).then(settle, settle);
+        return result;
+      };
+      wrappers.set(property, { raw: value, wrapper });
+      return wrapper;
+    },
+  });
+}
+
+/** The adapter the counting proxy currently wraps, so re-registration re-wraps and nothing else. */
+let counted: { raw: StudioPlatform; wrapped: StudioPlatform } | null = null;
+
 /** @returns {StudioPlatform} */
 export function getPlatform() {
-  if (!g.__jxPlatform) {
+  const raw = g.__jxPlatform;
+  if (!raw) {
     throw new Error("No platform registered. Call registerPlatform() before starting Studio.");
   }
-  return g.__jxPlatform;
+  if (counted?.raw !== raw) {
+    counted = { raw, wrapped: countingPlatform(raw) };
+  }
+  return counted.wrapped;
 }
 
 /** @returns {boolean} */

package/src/platforms/cloud.ts

@@ -11,6 +11,8 @@
  * gitClone, resolveClass, component discovery, code services.
  */
 
+import { negotiateCollab } from "@jxsuite/collab/negotiate";
+import type { CollabNegotiation } from "@jxsuite/collab/negotiate";
 import type { WsCollabConnection } from "@jxsuite/collab/client";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 import type {
@@ -25,11 +27,13 @@ import type {
   PackageInfo,
   ProjectListEntry,
   ProjectSchemasResponse,
+  ReferencesResult,
   RenameResult,
   RepoInfo,
   StarterInfo,
   StudioPlatform,
 } from "../types";
+import { problemDetail, problemSlug } from "@jxsuite/protocol";
 
 export interface CloudProject {
   owner: string;
@@ -52,7 +56,13 @@ interface SessionEventWire {
   sha?: string;
 }
 
-/** Message-level failure body every platform route uses. */
+/**
+ * Message-level failure body every platform route uses.
+ *
+ * `error` is the pre-RFC-9457 name and is read through `problemDetail`, which also reads a problem
+ * document's `detail` — so this one reader covers a backend that has migrated and one that has
+ * not.
+ */
 interface ErrorBody {
   error?: string;
   code?: string;
@@ -60,8 +70,7 @@ interface ErrorBody {
 
 async function errorMessage(res: Response, fallback: string): Promise<string> {
   try {
-    const body = (await res.json()) as ErrorBody;
-    return body.error ?? fallback;
+    return problemDetail(await res.json()) ?? fallback;
   } catch {
     return fallback;
   }
@@ -164,6 +173,8 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
    * promise so concurrent first opens share the connection instead of racing two sockets.
    */
   let collabConnection: Promise<WsCollabConnection> | null = null;
+  /** Lazy subprotocol negotiation from the gateway's capability probe (null = not asked yet). */
+  let collabNegotiation: Promise<CollabNegotiation> | null = null;
 
   function api(path: string, init?: RequestInit): Promise<Response> {
     if (!project) {
@@ -309,6 +320,25 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
       );
     },
 
+    /**
+     * Usage counts, computed SERVER-SIDE. The walker lives in `@jxsuite/server`, which the cloud
+     * target already runs against the ProjectSession's working tree, so cloud is not a host that
+     * degrades to "unknown" — it answers the same query the desktop does, over the same engine.
+     */
+    async findReferences(target: { path?: string; tagName?: string }): Promise<ReferencesResult> {
+      const params = new URLSearchParams();
+      if (target.path) {
+        params.set("path", target.path);
+      }
+      if (target.tagName) {
+        params.set("tag", target.tagName);
+      }
+      return okJson<ReferencesResult>(
+        await api(`/references?${params.toString()}`),
+        `Failed to find references: ${target.path ?? target.tagName ?? ""}`,
+      );
+    },
+
     async createDirectory(_path: string) {
       // Directories exist implicitly in the virtual tree (created on write).
     },
@@ -318,11 +348,29 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
      * path, per the shared ProjectSession working tree). Backends without the endpoint (or with the
      * flag off) refuse the upgrade and Studio degrades to solo editing. The wire client's
      * evaluation defers behind the dynamic import until a doc opens.
+     *
+     * A plain GET on the same URL is the subprotocol negotiation, and this adapter did not make one
+     * before. **A probe that does not answer is not a refusal here.** The gateway is deployed
+     * separately from this bundle, so a 404 or a network error means "older gateway", and treating
+     * that as no-collab would take working co-editing away from every session pointed at one. It
+     * connects as it always has, offering nothing — which is also the only handshake-safe answer to
+     * a server that would echo nothing (RFC 6455 §4.1).
      */
     async collab(docPath: string) {
       if (!project || typeof WebSocket === "undefined" || typeof location === "undefined") {
         return null;
       }
+      collabNegotiation ??= api("/collab")
+        .then(async (res) =>
+          res.ok ? negotiateCollab(await res.json()) : { offer: [], refused: null },
+        )
+        .catch(() => ({ offer: [], refused: null }));
+      const negotiated = await collabNegotiation;
+      if (negotiated.refused !== null) {
+        console.warn(`Collaboration unavailable: ${negotiated.refused}`);
+        return null;
+      }
+      const { offer } = negotiated;
       collabConnection ??= (async () => {
         const { createWsCollabConnection } = await import("@jxsuite/collab/client");
         const scheme = location.protocol === "https:" ? "wss" : "ws";
@@ -331,6 +379,7 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
             // The DO has no GitHub token on a WS message; a plain read hydrates + caches the row.
             await api(`/file?path=${encodeURIComponent(path)}`);
           },
+          protocols: offer,
           url: `${scheme}://${location.host}${base}/collab`,
         });
       })();
@@ -681,6 +730,9 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
       if (target && typeof window !== "undefined") {
         window.open(editUrl(target), "_blank", "noopener");
       }
+      // `_blank` always makes a tab; a browser tab already showing this project is not something
+      // The page can see, let alone raise.
+      return { focused: false };
     },
 
     /**
@@ -720,10 +772,17 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
         // Preserve the structured 403 (needs_installation_access + installUrl) so the New
         // Project modal can render an install link instead of flattened text.
         const body = (await res.json().catch(() => null)) as
-          | (ErrorBody & { installUrl?: string })
+          | (ErrorBody & { installUrl?: string; type?: string })
           | null;
-        throw Object.assign(new Error(body?.error ?? "Failed to create project"), {
-          ...(body?.code ? { code: body.code } : {}),
+        /*
+         * `code` survives as the machine-readable discriminator the modal branches on, and a
+         * problem document supplies it from its `type` — `problemSlug` derives the same string the
+         * old `code` field carried, so the modal's branch is unchanged either way.
+         */
+        throw Object.assign(new Error(problemDetail(body) ?? "Failed to create project"), {
+          ...((problemSlug(body?.type) ?? body?.code)
+            ? { code: problemSlug(body?.type) ?? body?.code }
+            : {}),
           ...(body?.installUrl ? { installUrl: body.installUrl } : {}),
         });
       }
@@ -900,9 +959,13 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
             settle(await fetchCfConnection());
             return;
           }
-          timer = window.setTimeout(() => void poll(), 1500);
+          timer = window.setTimeout(() => {
+            void poll();
+          }, 1500);
         };
-        timer = window.setTimeout(() => void poll(), 1500);
+        timer = window.setTimeout(() => {
+          void poll();
+        }, 1500);
       });
     },
 

package/src/platforms/devserver.ts

@@ -10,6 +10,8 @@
 
 import { streamImport } from "../services/import-client";
 import { canPickDirectory, pickDirectoryPath } from "../services/directory-picker";
+import { negotiateCollab } from "@jxsuite/collab/negotiate";
+import type { CollabNegotiation } from "@jxsuite/collab/negotiate";
 import type { WsCollabConnection } from "@jxsuite/collab/client";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 import type {
@@ -28,11 +30,14 @@ import type {
   ImportProgressEvent,
   ImportSiteOptions,
   ProjectSchemasResponse,
+  ReferencesResult,
   RenameResult,
   SecretsSetRequest,
   SecretsSetResponse,
+  SiteBuildResult,
   StarterInfo,
 } from "../types";
+import { problemDetail, problemMessage } from "@jxsuite/protocol";
 
 /** A directory entry from the server, tolerating extra wire fields. */
 type WireDirEntry = DirEntry & Record<string, unknown>;
@@ -61,8 +66,12 @@ interface SiteEntry {
  */
 export function createDevServerPlatform() {
   let _projectRoot = "";
-  /** Lazy /__studio/collab capability probe (null = not asked yet). */
-  let _collabProbe: Promise<boolean> | null = null;
+  /**
+   * Lazy /__studio/collab capability probe (null = not asked yet). Its result is the subprotocol
+   * negotiation, not a boolean: the probe is the only place the client can learn what envelope the
+   * server speaks without risking the handshake (see `@jxsuite/collab/negotiate`).
+   */
+  let _collabProbe: Promise<CollabNegotiation | null> | null = null;
   /**
    * One multiplexed collab socket per page; per-doc handles come from openDoc. Memoized as a
    * promise so concurrent first opens share the connection instead of racing two sockets.
@@ -142,7 +151,7 @@ export function createDevServerPlatform() {
       if (!res.ok) {
         const body = (await readJson<ErrorBody>(res).catch(() => ({}))) as ErrorBody;
         throw new Error(
-          `Could not open ${r}: ${body.error || `activation failed (${res.status})`}`,
+          `Could not open ${r}: ${problemDetail(body) ?? `activation failed (${res.status})`}`,
         );
       }
     },
@@ -281,7 +290,7 @@ export function createDevServerPlatform() {
       });
       if (!res.ok) {
         const data = await readJson<ErrorBody>(res);
-        throw new Error(data.error || "Failed to create project");
+        throw new Error(problemDetail(data) ?? "Failed to create project");
       }
       return await res.json();
     },
@@ -425,6 +434,39 @@ export function createDevServerPlatform() {
       return report;
     },
 
+    /**
+     * Where a file / component tag is used, over the same walker the rename above writes through.
+     * The engine caches the sweep server-side and drops it from the dev server's own file watcher,
+     * so the three renderings never disagree and never re-scan the project per keystroke.
+     *
+     * @param {{ path?: string; tagName?: string }} target
+     */
+    async findReferences(target: { path?: string; tagName?: string }): Promise<ReferencesResult> {
+      const params = new URLSearchParams();
+      if (target.path) {
+        params.set("path", serverPath(target.path));
+      }
+      if (target.tagName) {
+        params.set("tag", target.tagName);
+      }
+      const res = await fetch(`/__studio/references?${params.toString()}`);
+      if (!res.ok) {
+        throw new Error(`Failed to find references: ${target.path ?? target.tagName ?? ""}`);
+      }
+      const result = await readJson<ReferencesResult>(res);
+      // Server-root-relative report paths → project-relative, as renameFile already does.
+      if (typeof result.path === "string") {
+        result.path = stripRoot(result.path);
+      }
+      for (const f of result.files ?? []) {
+        f.path = stripRoot(f.path);
+      }
+      for (const e of result.errors ?? []) {
+        e.path = stripRoot(e.path);
+      }
+      return result;
+    },
+
     /**
      * Subscribe to filesystem change events over the dev server's SSE stream. Listens for the named
      * "fs" event (the preview iframe's default `onmessage` ignores it), strips paths to
@@ -467,6 +509,12 @@ export function createDevServerPlatform() {
      * server-root-relative path). Probes capability once — older servers without the endpoint
      * degrade to solo editing; the wire client's evaluation defers behind the dynamic import until
      * a doc opens.
+     *
+     * The same probe carries the subprotocol negotiation. A server that advertises no `protocols`
+     * predates it and gets no offer, because an offer it cannot echo would fail the handshake
+     * outright (RFC 6455 §4.1); a server that advertises an envelope this build does not speak is
+     * refused here, where the reason can be said, rather than in a room where the two would merge
+     * divergent histories.
      */
     async collab(docPath: string) {
       if (typeof WebSocket === "undefined" || typeof location === "undefined") {
@@ -474,16 +522,23 @@ export function createDevServerPlatform() {
       }
       if (_collabProbe === null) {
         _collabProbe = fetch("/__studio/collab")
-          .then((res) => res.ok)
-          .catch(() => false);
+          .then(async (res) => (res.ok ? negotiateCollab(await res.json()) : null))
+          .catch(() => null);
       }
-      if (!(await _collabProbe)) {
+      const negotiation = await _collabProbe;
+      if (negotiation === null) {
         return null;
       }
+      if (negotiation.refused !== null) {
+        console.warn(`Collaboration unavailable: ${negotiation.refused}`);
+        return null;
+      }
+      const { offer } = negotiation;
       _collabConnection ??= (async () => {
         const { createWsCollabConnection } = await import("@jxsuite/collab/client");
         const scheme = location.protocol === "https:" ? "wss" : "ws";
         return createWsCollabConnection({
+          protocols: offer,
           url: `${scheme}://${location.host}/__studio/collab`,
         });
       })();
@@ -707,7 +762,7 @@ export function createDevServerPlatform() {
       );
       if (!res.ok) {
         const data = await readJson<ErrorBody>(res);
-        throw new Error(data.error || "Failed to list connections");
+        throw new Error(problemDetail(data) ?? "Failed to list connections");
       }
       return await readJson<DataConnectionsResponse>(res);
     },
@@ -724,7 +779,7 @@ export function createDevServerPlatform() {
       );
       const data = await readJson<DataConnectionTestResult & ErrorBody>(res);
       if (!res.ok) {
-        throw new Error(data.error || "Connection test failed");
+        throw new Error(problemDetail(data) ?? "Connection test failed");
       }
       return data;
     },
@@ -738,7 +793,7 @@ export function createDevServerPlatform() {
       });
       const data = await readJson<DataPushResult & ErrorBody>(res);
       if (!res.ok) {
-        throw new Error(data.error || "Schema push failed");
+        throw new Error(problemDetail(data) ?? "Schema push failed");
       }
       return data;
     },
@@ -764,7 +819,7 @@ export function createDevServerPlatform() {
       const res = await fetch(`/__studio/data/rows?${params}`);
       const data = await readJson<DataRowsResult & ErrorBody>(res);
       if (!res.ok) {
-        throw new Error(data.error || "Failed to load rows");
+        throw new Error(problemDetail(data) ?? "Failed to load rows");
       }
       return data;
     },
@@ -777,7 +832,7 @@ export function createDevServerPlatform() {
       });
       const data = await readJson<{ row: Record<string, unknown> } & ErrorBody>(res);
       if (!res.ok) {
-        throw new Error(data.error || "Insert failed");
+        throw new Error(problemDetail(data) ?? "Insert failed");
       }
       return data;
     },
@@ -790,7 +845,7 @@ export function createDevServerPlatform() {
       });
       const data = await readJson<{ row: Record<string, unknown> } & ErrorBody>(res);
       if (!res.ok) {
-        throw new Error(data.error || "Update failed");
+        throw new Error(problemDetail(data) ?? "Update failed");
       }
       return data;
     },
@@ -807,7 +862,7 @@ export function createDevServerPlatform() {
       const res = await fetch(`/__studio/data/rows?${params}`, { method: "DELETE" });
       const data = await readJson<{ ok: boolean } & ErrorBody>(res);
       if (!res.ok) {
-        throw new Error(data.error || "Delete failed");
+        throw new Error(problemDetail(data) ?? "Delete failed");
       }
       return data;
     },
@@ -817,7 +872,7 @@ export function createDevServerPlatform() {
       const res = await fetch(`/__studio/secrets?dir=${encodeURIComponent(serverPath("."))}`);
       if (!res.ok) {
         const data = await readJson<ErrorBody>(res);
-        throw new Error(data.error || "Failed to list secrets");
+        throw new Error(problemDetail(data) ?? "Failed to list secrets");
       }
       const data = await readJson<{ names: string[] }>(res);
       return data.names;
@@ -832,7 +887,7 @@ export function createDevServerPlatform() {
       });
       const data = await readJson<SecretsSetResponse & ErrorBody>(res);
       if (!res.ok) {
-        throw new Error(data.error || "Failed to write secrets");
+        throw new Error(problemDetail(data) ?? "Failed to write secrets");
       }
       return data;
     },
@@ -850,7 +905,7 @@ export function createDevServerPlatform() {
       });
       const data = await readJson<{ error?: string; result?: unknown }>(res);
       if (!res.ok) {
-        throw new Error(data.error || "Format action failed");
+        throw new Error(problemDetail(data) ?? "Format action failed");
       }
       return data.result;
     },
@@ -930,7 +985,7 @@ export function createDevServerPlatform() {
       });
       if (!res.ok) {
         const body = await readJson<ErrorBody>(res);
-        throw new Error(body.error);
+        throw new Error(problemMessage(body));
       }
       return await res.json();
     },
@@ -944,7 +999,7 @@ export function createDevServerPlatform() {
       });
       if (!res.ok) {
         const body = await readJson<ErrorBody>(res);
-        throw new Error(body.error);
+        throw new Error(problemMessage(body));
       }
       return await res.json();
     },
@@ -958,7 +1013,7 @@ export function createDevServerPlatform() {
       });
       if (!res.ok) {
         const body = await readJson<ErrorBody>(res);
-        throw new Error(body.error);
+        throw new Error(problemMessage(body));
       }
       return await res.json();
     },
@@ -972,7 +1027,7 @@ export function createDevServerPlatform() {
       });
       if (!res.ok) {
         const body = await readJson<ErrorBody>(res);
-        throw new Error(body.error);
+        throw new Error(problemMessage(body));
       }
       return await res.json();
     },
@@ -981,7 +1036,7 @@ export function createDevServerPlatform() {
       const res = await fetch("/__studio/git/pull", { method: "POST" });
       if (!res.ok) {
         const body = await readJson<ErrorBody>(res);
-        throw new Error(body.error);
+        throw new Error(problemMessage(body));
       }
       return await res.json();
     },
@@ -990,7 +1045,7 @@ export function createDevServerPlatform() {
       const res = await fetch("/__studio/git/fetch", { method: "POST" });
       if (!res.ok) {
         const body = await readJson<ErrorBody>(res);
-        throw new Error(body.error);
+        throw new Error(problemMessage(body));
       }
       return await res.json();
     },
@@ -1004,7 +1059,7 @@ export function createDevServerPlatform() {
       });
       if (!res.ok) {
         const body = await readJson<ErrorBody>(res);
-        throw new Error(body.error);
+        throw new Error(problemMessage(body));
       }
       return await res.json();
     },
@@ -1018,7 +1073,7 @@ export function createDevServerPlatform() {
       });
       if (!res.ok) {
         const body = await readJson<ErrorBody>(res);
-        throw new Error(body.error);
+        throw new Error(problemMessage(body));
       }
       return await res.json();
     },
@@ -1055,7 +1110,7 @@ export function createDevServerPlatform() {
       });
       if (!res.ok) {
         const body = await readJson<ErrorBody>(res);
-        throw new Error(body.error);
+        throw new Error(problemMessage(body));
       }
       return await res.json();
     },
@@ -1069,7 +1124,7 @@ export function createDevServerPlatform() {
       });
       if (!res.ok) {
         const body = await readJson<ErrorBody>(res);
-        throw new Error(body.error);
+        throw new Error(problemMessage(body));
       }
       return await res.json();
     },
@@ -1078,8 +1133,16 @@ export function createDevServerPlatform() {
       const res = await fetch("/__studio/git/init", { method: "POST" });
       if (!res.ok) {
         const body = await readJson<ErrorBody>(res);
-        throw new Error(body.error);
+        throw new Error(problemMessage(body));
+      }
+    },
+    async buildSite() {
+      const res = await fetch("/__studio/build", { method: "POST" });
+      if (!res.ok) {
+        const body = await readJson<ErrorBody>(res);
+        throw new Error(problemDetail(body) ?? "The site could not be built.");
       }
+      return (await res.json()) as SiteBuildResult;
     },
 
     /**
@@ -1094,7 +1157,7 @@ export function createDevServerPlatform() {
       });
       if (!res.ok) {
         const body = await readJson<ErrorBody>(res);
-        throw new Error(body.error);
+        throw new Error(problemMessage(body));
       }
     },