@jxsuite/studio 6.1.0 → 6.1.2

package/src/platforms/default-platform.ts

@@ -38,6 +38,11 @@ export interface CloudSignal {
   project: CloudProject | null;
 }
 
+declare global {
+  /** Published by the cloud shell's boot module before the studio bundle evaluates. */
+  var __jxCloud: CloudSignal | undefined;
+}
+
 /**
  * Why Studio will not fall back to the dev-server adapter, most specific evidence first.
  *
@@ -86,13 +91,14 @@ const BACKENDLESS_SCHEMES: ReadonlySet<string> = new Set(["views:", "file:"]);
 
 /** Read the boot environment from the live globals and document. */
 export function bootEnvironment(): BootEnvironment {
-  const doc = (globalThis as { document?: Document }).document;
+  // A DOM-less host (a test runner, a worker) has no document or location to read.
+  const doc = typeof document === "undefined" ? undefined : document;
   const meta = `meta[name="${BOOT_META.name}"][content="${BOOT_META.content}"]`;
   return {
-    cloud: (globalThis as unknown as { __jxCloud?: CloudSignal }).__jxCloud != null,
+    cloud: globalThis.__jxCloud != null,
     declared: doc?.querySelector(meta) != null,
     launcher: launcherSignal(),
-    protocol: (globalThis as { location?: Location }).location?.protocol ?? "",
+    protocol: typeof location === "undefined" ? "" : location.protocol,
   };
 }
 
@@ -159,6 +165,6 @@ export function resolveDefaultPlatform(): StudioPlatform {
   if (refusal) {
     throw new PlatformUnavailableError(refusal);
   }
-  const cloud = (globalThis as unknown as { __jxCloud?: CloudSignal }).__jxCloud;
+  const cloud = globalThis.__jxCloud;
   return cloud ? createCloudPlatform(cloud.project) : createDevServerPlatform();
 }

package/src/platforms/devserver.ts

@@ -13,9 +13,9 @@ import { canPickDirectory, pickDirectoryPath } from "../services/directory-picke
 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 { isFunction } from "@jxsuite/schema/guards";
+import type { JsonObject, JsonValue, JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
 import type {
-  CreateProjectDestination,
   DataConnectionsResponse,
   DataConnectionTestResult,
   DataPushResult,
@@ -35,20 +35,22 @@ import type {
   ProjectSchemasResponse,
   ReferencesResult,
   RenameResult,
-  SecretsSetRequest,
+  KeyValuePatch,
   SecretsSetResponse,
   SiteBuildResult,
   SitePreviewResult,
   StarterInfo,
+  StudioPlatform,
 } from "../types";
 import { problemDetail, problemMessage } from "@jxsuite/protocol";
+import type { CfProxyEnvelope } from "./cloud";
 import type { UploadResult } from "@jxsuite/protocol";
 
-/** A directory entry from the server, tolerating extra wire fields. */
-type WireDirEntry = DirEntry & Record<string, unknown>;
-
 /** Parse a fetch Response body as JSON, asserting the expected shape at the boundary. */
 async function readJson<T>(res: Response): Promise<T> {
+  /* SAFETY: every route read here is a `/__studio/*` route of @jxsuite/server (specs/server.md §4),
+     whose replies have the shapes ../types and the wire interfaces in this file describe, and each
+     caller names the type of the route it called. */
   return (await res.json()) as T;
 }
 
@@ -56,11 +58,46 @@ interface ErrorBody {
   error?: string;
 }
 
+/** One entry of the `/__studio/sites` glob: a site's folder and its parsed project.json. */
 interface SiteEntry {
-  config: unknown;
+  config: ProjectConfig | null;
   path: string;
 }
 
+/**
+ * `GET /__studio/project-info`: what the server knows about a folder. The route sends more than
+ * Studio reads (`projectRoot` among them), and those members ride along untouched.
+ */
+interface ProjectInfoReply {
+  isSiteProject: boolean;
+  projectConfig?: ProjectConfig | null;
+  directories?: string[];
+  [member: string]: JsonValue | ProjectConfig | undefined;
+}
+
+/** The body of an `fs` event on the `/__reload` stream (the server's watcher batches them). */
+interface FsEventBatch {
+  events?: FsEvent[];
+}
+
+/** `showDirectoryPicker()` (WICG File System Access), which only Chromium-based browsers expose. */
+type ShowDirectoryPicker = (options: { mode: string }) => Promise<FileSystemDirectoryHandle>;
+
+/** True when the window implements the File System Access directory picker. */
+function hasDirectoryPicker(
+  host: Window,
+): host is Window & { showDirectoryPicker: ShowDirectoryPicker } {
+  return "showDirectoryPicker" in host && isFunction(host.showDirectoryPicker);
+}
+
+/** The options object {@link StudioPlatform.createProject} takes. */
+type CreateProjectOptions = Parameters<StudioPlatform["createProject"]>[0];
+
+/** What a row insert or update answers: the row as stored. */
+interface DataRowWrite {
+  row: JsonObject;
+}
+
 /**
  * Create a DevServerPlatform instance.
  *
@@ -98,6 +135,50 @@ export function createDevServerPlatform() {
    */
   let _collabConnection: Promise<WsCollabConnection> | null = null;
 
+  /**
+   * Bind the server to `root` — the binding its rootless routes and its static fallback (every
+   * media thumbnail, every canvas image) resolve against.
+   *
+   * **The binding is one per SERVER, not per tab.** So an empty root posts nothing: a Studio tab
+   * opened with no project used to post `{ root: "" }` at boot, which unbound the server for every
+   * other tab and turned their images into 404s. And a tab re-claims it (see
+   * {@link reclaimBinding}) whenever it could have been taken.
+   */
+  async function postActivate(root: string): Promise<void> {
+    if (!root) {
+      return;
+    }
+    const res = await fetch("/__studio/activate", {
+      body: JSON.stringify({ root }),
+      headers: { "Content-Type": "application/json" },
+      method: "POST",
+    });
+    if (!res.ok) {
+      const body = await readJson<ErrorBody>(res).catch((): ErrorBody => ({}));
+      throw new Error(
+        `Could not open ${root}: ${problemDetail(body) ?? `activation failed (${res.status})`}`,
+      );
+    }
+  }
+
+  /**
+   * Re-bind the server to this tab's project. Two events can take the binding away without this tab
+   * hearing of it: another Studio tab activating ITS project, and a restarted `bun run dev`, which
+   * comes back bound to nothing. So a tab re-claims it when the author comes back to it (focus) and
+   * when the reload stream reconnects (a restart). Only a tab with a project claims anything.
+   */
+  function reclaimBinding(): void {
+    if (!_projectRoot) {
+      return;
+    }
+    _activation = postActivate(_projectRoot).catch((error) => {
+      console.error("Project re-activation failed:", error);
+    });
+  }
+  if (typeof window !== "undefined") {
+    window.addEventListener("focus", reclaimBinding);
+  }
+
   /**
    * Prefix a project-relative path with the active project root for server API calls.
    *
@@ -127,6 +208,36 @@ export function createDevServerPlatform() {
     return p.startsWith(`${_projectRoot}/`) ? p.slice(_projectRoot.length + 1) : p;
   }
 
+  /**
+   * Native folder chooser for the New Project modal's Browse… button. Present only when the browser
+   * implements `showDirectoryPicker` (Chromium-based); elsewhere the member stays undefined and the
+   * modal falls back to a typed Location field.
+   *
+   * The picked handle carries no filesystem path, so it is resolved by the id the picker tags the
+   * folder with (see `@jxsuite/studio/directory-picker`). Resolves `null` only when the user
+   * dismisses the chooser; every other failure rejects with a sentence the modal shows under
+   * Location. So `locate` keeps the helper's contract: `null` is "no folder holds this id" (the
+   * route's 200 `{ path: null }`), and a non-ok answer throws the problem the server sent rather
+   * than posing as a miss. A network failure (`TypeError: Failed to fetch`, e.g. a page that is not
+   * being served by the dev server at all) propagates as is, and the picker names it.
+   */
+  const directoryPicking: Pick<StudioPlatform, "pickDirectory"> = {};
+  if (canPickDirectory()) {
+    directoryPicking.pickDirectory = async (): Promise<string | null> =>
+      pickDirectoryPath(async ({ id, name }) => {
+        const res = await fetch(
+          `/__studio/locate-directory?name=${encodeURIComponent(name)}&id=${encodeURIComponent(id)}`,
+        );
+        if (!res.ok) {
+          // A proxy, or a `views://` host with no dev server behind it, may answer in HTML.
+          const body = await readJson<JsonValue>(res).catch(() => null);
+          throw new Error(problemMessage(body, res.status));
+        }
+        const found = await readJson<{ path?: string | null }>(res);
+        return found.path ?? null;
+      });
+  }
+
   return {
     id: "devserver",
 
@@ -145,7 +256,7 @@ export function createDevServerPlatform() {
         // Fire-and-forget: callers that need the binding in place before reading await activate()
         // Themselves. The rejection is reported rather than dropped — an unactivated root leaves
         // Every rootless endpoint (git especially) operating on the server's OWN root.
-        _activation = this.activate(_projectRoot).catch((error: unknown) => {
+        _activation = this.activate(_projectRoot).catch((error) => {
           console.error("Project activation failed:", error);
         });
       }
@@ -162,35 +273,21 @@ export function createDevServerPlatform() {
      * @param {string} [root]
      */
     async activate(root?: string) {
-      const r = root ?? _projectRoot;
-      const res = await fetch("/__studio/activate", {
-        body: JSON.stringify({ root: r }),
-        headers: { "Content-Type": "application/json" },
-        method: "POST",
-      });
-      if (!res.ok) {
-        const body = (await readJson<ErrorBody>(res).catch(() => ({}))) as ErrorBody;
-        throw new Error(
-          `Could not open ${r}: ${problemDetail(body) ?? `activation failed (${res.status})`}`,
-        );
-      }
+      await postActivate(root ?? _projectRoot);
     },
 
     // ─── Project opening ──────────────────────────────────────────────────
 
     async openProject() {
       // Use Chrome's showDirectoryPicker API
-      if (!("showDirectoryPicker" in window)) {
+      const host = window;
+      if (!hasDirectoryPicker(host)) {
         throw new Error("showDirectoryPicker not available — use a Chromium-based browser");
       }
 
       let dirHandle;
       try {
-        dirHandle = await (
-          window as unknown as {
-            showDirectoryPicker: (opts: { mode: string }) => Promise<FileSystemDirectoryHandle>;
-          }
-        ).showDirectoryPicker({ mode: "readwrite" });
+        dirHandle = await host.showDirectoryPicker({ mode: "readwrite" });
       } catch (error) {
         // User cancelled the picker
         if (error instanceof Error && error.name === "AbortError") {
@@ -208,6 +305,9 @@ export function createDevServerPlatform() {
       }
 
       const file = await siteHandle.getFile();
+      /* SAFETY: the user picked this folder as a project, and project.json is that project's own
+         config file; it is matched below against the server's parse of the same file, and every
+         adapter hands project.json to Studio as the ProjectConfig the session edits. */
       const config = JSON.parse(await file.text()) as ProjectConfig;
 
       // Resolve server-relative path by matching against known sites
@@ -264,12 +364,7 @@ export function createDevServerPlatform() {
           ? await readJson<{ name: string; root: string }>(projectRes)
           : { name: "project", root: "." };
         const info = infoRes.ok
-          ? await readJson<{
-              isSiteProject: boolean;
-              projectConfig?: ProjectConfig | null;
-              directories?: string[];
-              [key: string]: unknown;
-            }>(infoRes)
+          ? await readJson<ProjectInfoReply>(infoRes)
           : { isSiteProject: false };
         return { info, meta };
       } catch {
@@ -282,27 +377,8 @@ export function createDevServerPlatform() {
     /**
      * Scaffold a project at `destination.parent/directory`. The dev server refuses the request
      * outright when no destination is supplied — it will not fall back to its own root.
-     *
-     * @param {{
-     *   name: string;
-     *   description?: string;
-     *   url?: string;
-     *   adapter?: string;
-     *   directory: string;
-     *   destination: CreateProjectDestination;
-     * }} opts
      */
-    async createProject(opts: {
-      name: string;
-      description?: string;
-      url?: string;
-      adapter?: string;
-      directory: string;
-      destination: CreateProjectDestination;
-      starter?: string;
-      template?: string;
-      design?: Record<string, unknown>;
-    }) {
+    async createProject(opts: CreateProjectOptions) {
       const res = await fetch("/__studio/create-project", {
         body: JSON.stringify(opts),
         headers: { "Content-Type": "application/json" },
@@ -315,37 +391,7 @@ export function createDevServerPlatform() {
       return await res.json();
     },
 
-    /**
-     * Native folder chooser for the New Project modal's Browse… button. Present only when the
-     * browser implements `showDirectoryPicker` (Chromium-based); elsewhere the member stays
-     * undefined and the modal falls back to a typed Location field.
-     *
-     * The picked handle carries no filesystem path, so it is resolved by the id the picker tags the
-     * folder with (see `@jxsuite/studio/directory-picker`). Resolves `null` only when the user
-     * dismisses the chooser; every other failure rejects with a sentence the modal shows under
-     * Location. So `locate` keeps the helper's contract: `null` is "no folder holds this id" (the
-     * route's 200 `{ path: null }`), and a non-ok answer throws the problem the server sent rather
-     * than posing as a miss. A network failure (`TypeError: Failed to fetch`, e.g. a page that is
-     * not being served by the dev server at all) propagates as is, and the picker names it.
-     */
-    ...(canPickDirectory()
-      ? {
-          async pickDirectory(): Promise<string | null> {
-            return pickDirectoryPath(async ({ id, name }) => {
-              const res = await fetch(
-                `/__studio/locate-directory?name=${encodeURIComponent(name)}&id=${encodeURIComponent(id)}`,
-              );
-              if (!res.ok) {
-                // A proxy, or a `views://` host with no dev server behind it, may answer in HTML.
-                const body: unknown = await res.json().catch(() => null);
-                throw new Error(problemMessage(body, res.status));
-              }
-              const found = await readJson<{ path?: string | null }>(res);
-              return found.path ?? null;
-            });
-          },
-        }
-      : {}),
+    ...directoryPicking,
 
     /** List starter templates from the dev server. */
     async listStarters(): Promise<StarterInfo[]> {
@@ -374,7 +420,7 @@ export function createDevServerPlatform() {
       if (!res.ok) {
         throw new Error(`Failed to list directory: ${dir}`);
       }
-      const entries = await readJson<WireDirEntry[]>(res);
+      const entries = await readJson<DirEntry[]>(res);
       for (const e of entries) {
         e.path = stripRoot(e.path);
       }
@@ -432,10 +478,14 @@ export function createDevServerPlatform() {
       if (!res.ok) {
         throw new Error(`Upload failed: ${path}`);
       }
-      const body = (await res.json()) as Partial<UploadResult>;
+      const body = await readJson<Partial<UploadResult>>(res);
       // The dev server echoes the path today; falling back to the request keeps a backend that says
       // Nothing working rather than writing `undefined` into a document.
-      return { path: body.path ?? path, ...(body.size === undefined ? {} : { size: body.size }) };
+      const uploaded: UploadResult = { path: body.path ?? path };
+      if (body.size !== undefined) {
+        uploaded.size = body.size;
+      }
+      return uploaded;
     },
 
     /** @param {string} path */
@@ -514,13 +564,17 @@ export function createDevServerPlatform() {
       es.addEventListener("open", () => {
         opens += 1;
         if (opens > 1) {
+          // A reconnect is usually a restarted server, which comes back bound to no project.
+          reclaimBinding();
           options?.onResync?.("reconnect");
         }
       });
-      es.addEventListener("fs", (ev: MessageEvent) => {
-        let payload: { events?: FsEvent[] };
+      es.addEventListener("fs", (ev: MessageEvent<string>) => {
+        let payload: FsEventBatch;
         try {
-          payload = JSON.parse(ev.data as string) as { events?: FsEvent[] };
+          /* SAFETY: `fs` events on /__reload are sent only by @jxsuite/server's watcher, as
+             broadcastEvent("fs", { events }) over its batched FsEvent buffer (server watch.ts). */
+          payload = JSON.parse(ev.data) as FsEventBatch;
         } catch {
           return;
         }
@@ -562,7 +616,7 @@ export function createDevServerPlatform() {
       }
       if (_collabProbe === null) {
         _collabProbe = fetch("/__studio/collab")
-          .then(async (res) => (res.ok ? negotiateCollab(await res.json()) : null))
+          .then(async (res) => (res.ok ? negotiateCollab(await readJson<JsonValue>(res)) : null))
           .catch(() => null);
       }
       const negotiation = await _collabProbe;
@@ -659,7 +713,7 @@ export function createDevServerPlatform() {
       if (!res.ok) {
         return false;
       }
-      const data = (await res.json()) as { needsInstall?: boolean };
+      const data = await readJson<{ needsInstall?: boolean }>(res);
       return Boolean(data.needsInstall);
     },
 
@@ -686,11 +740,8 @@ export function createDevServerPlatform() {
 
     // ─── Code services (optional) ─────────────────────────────────────────
 
-    /**
-     * @param {string} action
-     * @param {unknown} payload
-     */
-    async codeService(action: string, payload: unknown) {
+    /** Run one code-service action on the server; null when the route fails or is absent. */
+    async codeService(action: string, payload: Parameters<StudioPlatform["codeService"]>[1]) {
       try {
         const res = await fetch(`/__studio/code/${action}`, {
           body: JSON.stringify(payload),
@@ -753,7 +804,7 @@ export function createDevServerPlatform() {
       if (!res.ok) {
         return [];
       }
-      const entries = await readJson<WireDirEntry[]>(res);
+      const entries = await readJson<DirEntry[]>(res);
       for (const e of entries) {
         e.path = stripRoot(e.path);
       }
@@ -876,26 +927,26 @@ export function createDevServerPlatform() {
       return data;
     },
 
-    async dataInsertRow(req: DataRowInsert): Promise<{ row: Record<string, unknown> }> {
+    async dataInsertRow(req: DataRowInsert): Promise<DataRowWrite> {
       const res = await fetch(`/__studio/data/rows?dir=${encodeURIComponent(serverPath("."))}`, {
         body: JSON.stringify(req),
         headers: { "Content-Type": "application/json" },
         method: "POST",
       });
-      const data = await readJson<{ row: Record<string, unknown> } & ErrorBody>(res);
+      const data = await readJson<DataRowWrite & ErrorBody>(res);
       if (!res.ok) {
         throw new Error(problemDetail(data) ?? "Insert failed");
       }
       return data;
     },
 
-    async dataUpdateRow(req: DataRowUpdate): Promise<{ row: Record<string, unknown> }> {
+    async dataUpdateRow(req: DataRowUpdate): Promise<DataRowWrite> {
       const res = await fetch(`/__studio/data/rows?dir=${encodeURIComponent(serverPath("."))}`, {
         body: JSON.stringify(req),
         headers: { "Content-Type": "application/json" },
         method: "PUT",
       });
-      const data = await readJson<{ row: Record<string, unknown> } & ErrorBody>(res);
+      const data = await readJson<DataRowWrite & ErrorBody>(res);
       if (!res.ok) {
         throw new Error(problemDetail(data) ?? "Update failed");
       }
@@ -931,7 +982,7 @@ export function createDevServerPlatform() {
     },
 
     /** Write/remove secrets in the dev server's .dev.vars; names-only response. */
-    async setSecrets(req: SecretsSetRequest): Promise<SecretsSetResponse> {
+    async setSecrets(req: KeyValuePatch): Promise<SecretsSetResponse> {
       const res = await fetch(`/__studio/secrets?dir=${encodeURIComponent(serverPath("."))}`, {
         body: JSON.stringify(req),
         headers: { "Content-Type": "application/json" },
@@ -947,15 +998,17 @@ export function createDevServerPlatform() {
     /**
      * Invoke a format capability (parse/serialize) server-side.
      *
-     * @param {Record<string, unknown>} payload — { format, action, source?, doc?, options? }
+     * @param payload — { format, action, source?, doc?, options? }
      */
-    async formatAction(payload: Record<string, unknown>) {
+    async formatAction(payload: Parameters<NonNullable<StudioPlatform["formatAction"]>>[0]) {
       const res = await fetch("/__studio/format", {
         body: JSON.stringify({ ...payload, dir: serverPath(".") }),
         headers: { "Content-Type": "application/json" },
         method: "POST",
       });
-      const data = await readJson<{ error?: string; result?: unknown }>(res);
+      /* The format route answers `{ result }` on success (the document a format class's `parse`
+         built, or the text its `serialize` wrote) and a problem document otherwise. */
+      const data = await readJson<JsonObject & { result: JxMutableNode | string }>(res);
       if (!res.ok) {
         throw new Error(problemDetail(data) ?? "Format action failed");
       }
@@ -981,14 +1034,13 @@ export function createDevServerPlatform() {
       if (!res.ok) {
         return null;
       }
-      const { schema } = await readJson<{ schema: unknown }>(res);
+      const { schema } = await readJson<{ schema: JsonValue }>(res);
       return schema;
     },
 
     // ─── Class resolution (dev-proxy) ─────────────────────────────────────
 
-    /** @param {Record<string, unknown>} body */
-    async resolveClass(body: Record<string, unknown>) {
+    async resolveClass(body: Parameters<NonNullable<StudioPlatform["resolveClass"]>>[0]) {
       const res = await fetch("/__jx_resolve__", {
         body: JSON.stringify(body),
         headers: { "content-type": "application/json" },
@@ -997,7 +1049,7 @@ export function createDevServerPlatform() {
       if (!res.ok) {
         throw new Error(`Class resolution failed: ${res.status}`);
       }
-      return await readJson<unknown>(res);
+      return await readJson<JsonValue>(res);
     },
 
     // ─── Git operations ──────────────────────────────────────────────────
@@ -1194,7 +1246,7 @@ export function createDevServerPlatform() {
         const body = await readJson<ErrorBody>(res);
         throw new Error(problemDetail(body) ?? "The site could not be built.");
       }
-      return (await res.json()) as SiteBuildResult;
+      return await readJson<SiteBuildResult>(res);
     },
 
     /**
@@ -1213,7 +1265,7 @@ export function createDevServerPlatform() {
         const body = await readJson<ErrorBody>(res);
         throw new Error(problemDetail(body) ?? "The site could not be previewed.");
       }
-      return (await res.json()) as SitePreviewResult;
+      return await readJson<SitePreviewResult>(res);
     },
 
     async setPreviewOverlay(path: string, contents: string) {
@@ -1265,12 +1317,7 @@ export function createDevServerPlatform() {
         headers: { "Content-Type": "application/json", "X-CF-Token": token },
         body: JSON.stringify({ path: apiPath, method: init?.method ?? "GET", body: init?.body }),
       });
-      const envelope = (await res.json()) as {
-        success?: boolean;
-        result?: unknown;
-        errors?: { message: string }[];
-        error?: string;
-      };
+      const envelope = await readJson<CfProxyEnvelope>(res);
       if (!res.ok || envelope.success === false) {
         const message =
           envelope.errors?.map((e) => e.message).join("; ") ?? envelope.error ?? res.statusText;
@@ -1287,10 +1334,13 @@ export function createDevServerPlatform() {
         return null;
       }
       try {
-        const accounts = (await this.cfApi?.("/accounts")) as { id: string; name: string }[];
-        if (!accounts?.length) {
+        const result = await this.cfApi("/accounts");
+        if (!Array.isArray(result) || result.length === 0) {
           return { connected: false };
         }
+        /* SAFETY: cfApi resolved the v4 envelope's `result`, and Cloudflare documents GET /accounts
+           as answering an array of account objects, each with a string `id` and `name`. */
+        const accounts = result as { id: string; name: string }[];
         const chosen = accounts.find((a) => a.id === getCfAccountId()) ?? accounts[0]!;
         setCfAccountId(chosen.id);
         return { connected: true, accountId: chosen.id, accountName: chosen.name };
@@ -1308,14 +1358,11 @@ export function createDevServerPlatform() {
         return [];
       }
       const sites = await readJson<SiteEntry[]>(res);
-      return sites.map((site) => {
-        const config = site.config as { name?: string } | null;
-        return {
-          name: config?.name || site.path.split("/").at(-1) || site.path,
-          root: site.path,
-          description: site.path,
-        };
-      });
+      return sites.map((site) => ({
+        name: site.config?.name || site.path.split("/").at(-1) || site.path,
+        root: site.path,
+        description: site.path,
+      }));
     },
 
     // ─── AI Assistant (Stack B: OpenAI-compatible SSE proxy) ───────────────────

package/src/platforms/read-batcher.ts

@@ -21,6 +21,7 @@
 
 import { READ_FILES_MAX_PATHS } from "@jxsuite/protocol";
 import type { ReadFilesResult } from "@jxsuite/protocol";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 
 /**
  * What one batch request came back as.
@@ -57,14 +58,20 @@ export interface ReadBatcher {
 
 interface Waiter {
   resolve: (content: string) => void;
-  reject: (error: unknown) => void;
+  /** Rejects with whatever the transport or `fetchOne` rejected with, unchanged. */
+  reject: (cause: unknown) => void;
 }
 
 /** Path → every caller waiting on it. Same-path reads in one window share ONE request and result. */
 type Pending = Map<string, Waiter[]>;
 
-function isObject(value: unknown): value is object {
-  return typeof value === "object" && value !== null;
+/**
+ * A row's outcome as the batcher reads it. Every protocol outcome fits it, but the rows come off
+ * the wire unchecked, so `content` may be any value and either member may be missing.
+ */
+interface WireOutcome {
+  content?: unknown;
+  error?: { message?: string } | undefined;
 }
 
 /**
@@ -108,7 +115,7 @@ export function createReadBatcher(options: ReadBatcherOptions): ReadBatcher {
           waiter.resolve(content);
         }
       },
-      (error: unknown) => {
+      (error) => {
         for (const waiter of waiters) {
           waiter.reject(error);
         }
@@ -182,7 +189,7 @@ export function createReadBatcher(options: ReadBatcherOptions): ReadBatcher {
     }
     /* Anything that is not an object cannot be a ReadFilesResult (a `null` body, a bare string).
        The route did not answer this chunk, so it is served singly — the same as a failed call. */
-    if (answer === "retry-singly" || answer === "unsupported" || !isObject(answer)) {
+    if (answer === "retry-singly" || answer === "unsupported" || !isNonNullObject(answer)) {
       if (answer === "unsupported") {
         batching = false;
       }
@@ -213,14 +220,15 @@ export function createReadBatcher(options: ReadBatcherOptions): ReadBatcher {
       }
       chunk.delete(path);
       answered += 1;
-      if (typeof (outcome as { content?: unknown } | undefined)?.content === "string") {
-        const { content } = outcome as { content: string };
+      const wire: WireOutcome | undefined = outcome;
+      const content = wire?.content;
+      if (isString(content)) {
         for (const waiter of waiters) {
           waiter.resolve(content);
         }
       } else {
         // Per path: one missing file (404), one binary file (415) fails ITS readers and no others.
-        const message = (outcome as { error?: { message?: string } } | undefined)?.error?.message;
+        const message = wire?.error?.message;
         const error = new Error(message || `Failed to read file: ${path}`);
         for (const waiter of waiters) {
           waiter.reject(error);

package/src/project-list.ts

@@ -3,6 +3,7 @@
  * member (dev server sites, cloud platforms). Hydrated once at boot (studio.ts) like the
  * recent-projects cache; the welcome screen reads it synchronously.
  */
+import { isFunction } from "@jxsuite/schema/guards";
 import { getPlatform, hasPlatform } from "./platform";
 import type { ProjectListEntry } from "./types";
 
@@ -10,7 +11,7 @@ let cache: ProjectListEntry[] = [];
 
 /** True when the active platform exposes a project catalogue. */
 export function platformListsProjects(): boolean {
-  return hasPlatform() && typeof getPlatform().listProjects === "function";
+  return hasPlatform() && isFunction(getPlatform().listProjects);
 }
 
 /** Refresh the cache from the platform; resolves to [] when unsupported or failing. */