@jxsuite/server 6.1.0 → 8.0.0

package/README.md

@@ -1,6 +1,6 @@
 # `@jxsuite/server`
 
-> Bun-native development server for Jx projects with live reload, proxy resolution, and Studio API.
+> Development server for Jx projects with live reload, proxy resolution, and Studio API, plus the project server, package operations and package service that also run on Node.
 
 ## Overview
 
@@ -73,7 +73,29 @@ OXC-powered tools for the Studio function body editor:
 | ---------- | ----------------------------- |
 | `chokidar` | File watching for live reload |
 
-Bun built-ins used: `Bun.serve`, `Bun.build`, `Bun.Transpiler`.
+| `@npmcli/arborist` | Package operations (npm's installer) |
+| `npm-package-arg` | Validating a package spec before anything is installed |
+| `ws` | WebSockets for `serve()` on Node |
+
+`createDevServer()` and the build pipeline run on Bun (`Bun.serve`, `Bun.build`, `Bun.Transpiler`).
+
+## Running on Node
+
+The desktop app runs the project server on the Node inside Electron, so everything it loads is runtime-neutral, with the Bun implementation chosen by the `bun` export condition:
+
+- **`@jxsuite/server/serve`**: `serve()`, one HTTP and WebSocket server over `Bun.serve` under Bun and `node:http` with `ws` under Node. It is async, because Node binds asynchronously.
+- **`@jxsuite/server/fs-glob`** and **`@jxsuite/server/file-response`**: globbing and file responses that answer as Bun's own built-ins do.
+- **`@jxsuite/server/packages`**: add, remove, install and update-versions, run in-process on npm's Arborist. Install scripts never run, only the public registry is read, and the operation writes `package-lock.json` (a project's `bun.lock` is replaced on its first install).
+- **`@jxsuite/server/packages-service`**: the same operations over HTTP, lockfile-only, for a host with no filesystem of its own. The Jx cloud platform runs it from the [jxsuite/package-manager](https://github.com/jxsuite/package-manager) container image.
+
+## Upgrading to 8.0
+
+8.0 is the release that made the server runtime-neutral. Code that imports these from `@jxsuite/server` needs to change:
+
+- `createProjectServer()`, `startSitePreview()`, `sitePreviewOrigin()` and `stopSitePreviews()` return promises. Await them.
+- `documentGlob()` returns the glob pattern as a string instead of a `Bun.Glob`. Scan it with `scanFiles()` from `@jxsuite/server/fs-glob`.
+- `bunExecutable()` is removed: package operations no longer run a package manager in a subprocess.
+- `installDependencies()`, `addPackage()`, `removePackage()` and `setPackageVersions()` take an options argument and write `package-lock.json` rather than `bun.lock`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "6.1.0",
+  "version": "8.0.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -12,6 +12,12 @@
     "src/"
   ],
   "type": "module",
+  "imports": {
+    "#serve": {
+      "bun": "./src/serve.bun.ts",
+      "default": "./src/serve.node.ts"
+    }
+  },
   "exports": {
     ".": "./src/server.ts",
     "./dev": "./src/dev.ts",
@@ -29,7 +35,14 @@
     "./resolve": "./src/resolve.ts",
     "./types": "./src/types.ts",
     "./jx-mounts": "./src/jx-mounts.ts",
-    "./dev-vars": "./src/dev-vars.ts"
+    "./dev-vars": "./src/dev-vars.ts",
+    "./fs-glob": "./src/fs-glob.ts",
+    "./serve": {
+      "bun": "./src/serve.bun.ts",
+      "default": "./src/serve.node.ts"
+    },
+    "./file-response": "./src/file-response.ts",
+    "./packages-service": "./src/packages-service.ts"
   },
   "publishConfig": {
     "provenance": true
@@ -41,25 +54,32 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/ai": "^0.40.0",
-    "@jxsuite/catalog": "^0.1.2",
-    "@jxsuite/collab": "^0.11.2",
-    "@jxsuite/compiler": "^6.1.0",
-    "@jxsuite/create": "^1.4.0",
-    "@jxsuite/import": "^0.41.0",
-    "@jxsuite/protocol": "^4.0.0",
-    "@jxsuite/runtime": "^5.2.0",
-    "@jxsuite/schema": "^4.0.0",
-    "@jxsuite/site": "^2.2.0",
-    "@jxsuite/starters": "^3.1.0",
+    "@jxsuite/ai": "^0.41.1",
+    "@jxsuite/catalog": "^0.1.4",
+    "@jxsuite/collab": "^0.11.4",
+    "@jxsuite/compiler": "^8.0.0",
+    "@jxsuite/create": "^1.5.0",
+    "@jxsuite/import": "^0.42.0",
+    "@jxsuite/protocol": "^6.0.0",
+    "@jxsuite/runtime": "^6.0.1",
+    "@jxsuite/schema": "^5.0.0",
+    "@jxsuite/site": "^2.2.2",
+    "@jxsuite/starters": "^3.1.2",
+    "@npmcli/arborist": "^10.0.4",
     "chokidar": "^6.0.0",
     "kysely": "^0.29.7",
+    "npm-package-arg": "^14.0.0",
     "oxfmt": "^0.74.0",
+    "ws": "^8.22.0",
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@jxsuite/auth": "^0.8.0",
-    "@jxsuite/connector": "^0.8.0",
-    "@jxsuite/parser": "^4.1.0"
+    "@jxsuite/auth": "^0.8.2",
+    "@jxsuite/connector": "^0.8.2",
+    "@jxsuite/parser": "^4.1.2",
+    "@jxsuite/test-support": "^0.0.0",
+    "@types/npm-package-arg": "^6.1.4",
+    "@types/npmcli__arborist": "^6.3.3",
+    "@types/ws": "^8.18.1"
   }
 }

package/src/collab.ts

@@ -24,7 +24,7 @@ import {
   selectSubprotocol,
 } from "@jxsuite/collab/negotiate";
 import { assertAccessible } from "./studio-api";
-import type { ServerWebSocket, WebSocketHandler } from "bun";
+import type { ServeServer, ServeSocket, ServeWebSocketHandler } from "./serve.ts";
 import type { HostConnection } from "@jxsuite/collab/room";
 import { problem } from "./problem.ts";
 
@@ -66,20 +66,15 @@ export interface CollabSocketData {
 export interface CollabRegistry {
   /**
    * Handle a request to /__studio/collab: WebSocket upgrades become collab connections; a plain GET
-   * answers the capability probe. Returns undefined when the upgrade was accepted (Bun sends the
-   * 101 itself).
+   * answers the capability probe. Returns undefined when the upgrade was accepted (the server sends
+   * the 101 itself).
    */
   handleRequest: (
     req: Request,
-    server: {
-      upgrade: (
-        req: Request,
-        opts: { data: CollabSocketData; headers?: Record<string, string> },
-      ) => boolean;
-    },
+    server: Pick<ServeServer<CollabSocketData>, "upgrade">,
   ) => Response | undefined;
-  /** Bun.serve websocket handlers backing the upgraded connections. */
-  websocket: WebSocketHandler<CollabSocketData>;
+  /** The websocket handlers backing the upgraded connections (`serve.ts`). */
+  websocket: ServeWebSocketHandler<CollabSocketData>;
   /** Watcher hook: a file changed on disk (absolute path). Echoes of our write-back are ignored. */
   handleExternalChange: (absPath: string) => void;
   /** Flush pending write-backs and tear everything down. */
@@ -253,17 +248,17 @@ export function createCollabRegistry(opts: {
     },
 
     websocket: {
-      close(ws: ServerWebSocket<CollabSocketData>) {
+      close(ws: ServeSocket<CollabSocketData>) {
         ws.data.connection?.close();
         ws.data.connection = null;
       },
-      message(ws: ServerWebSocket<CollabSocketData>, message: string | Buffer) {
+      message(ws: ServeSocket<CollabSocketData>, message: string | Buffer) {
         if (isString(message)) {
           return;
         }
         ws.data.connection?.handleMessage(new Uint8Array(message));
       },
-      open(ws: ServerWebSocket<CollabSocketData>) {
+      open(ws: ServeSocket<CollabSocketData>) {
         connectionCounter += 1;
         const login = `local-${connectionCounter}`;
         ws.data.connection = host.connect(

package/src/dev.ts

@@ -13,7 +13,13 @@
  */
 
 import { existsSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
 import { join, normalize, resolve, sep } from "node:path";
+import { errorMessage } from "@jxsuite/schema/parse";
+import type { JsonObject } from "@jxsuite/schema/types";
+import { projectDevEnv } from "./dev-vars.ts";
+import { problem } from "./problem.ts";
+import { callServerExport } from "./resolve.ts";
 import { createDevServer } from "./server.ts";
 import { injectSSE } from "./watch.ts";
 
@@ -90,6 +96,84 @@ export function createDistMiddleware(
   };
 }
 
+/** One server entry the last build collected: the export, and where the site worker imports it from. */
+export interface ServerEntry {
+  exportName: string;
+  /** A `./` path from the project root, or a bare specifier, exactly as the worker bundle reads it. */
+  src: string;
+}
+
+/** The route every server function is served at, before the deployment base `server.ts` strips. */
+const SERVER_FUNCTION_ROUTE = "/_jx/server/";
+
+/**
+ * The arguments object a call posted. The worker reads its body the same way: anything that is not
+ * JSON is an empty argument object, so a function never sees the failure of a malformed request.
+ */
+async function readArguments(req: Request): Promise<JsonObject> {
+  try {
+    /* SAFETY: trust boundary. The body is whatever JSON the caller posted, and a compiled page posts
+       the entry's `arguments` object. The function receives it exactly as the worker passes it. */
+    return (await req.json()) as JsonObject;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Middleware that stands in for the site worker's server-function routes (server.md §2): answers
+ * `POST /_jx/server/<export>` for each entry the last build collected, and `null` for anything
+ * else, so the request falls through to the next middleware.
+ *
+ * It answers as the worker does, because a built page calls both the same way: the function's
+ * return value as JSON, `null` for `undefined`, and `{ ok: false, error }` with status 500 when it
+ * cannot be called. The function receives `env` as the extension mounts do (`projectDevEnv`:
+ * `process.env` under the project's `.dev.vars`), so it reads the same secrets in development.
+ *
+ * Each module is resolved as the worker bundle resolves it, from the project root: a `./` path
+ * against the root, any other specifier through the project's own `package.json`. It applies no
+ * containment check, because the module path comes from the build and never from the request;
+ * containment stays in the `/__jx_server__` proxy, where the request names the module.
+ *
+ * @param {string} root - Absolute project root
+ * @param {() => readonly ServerEntry[]} entries - The last build's collected entries, read per
+ *   request
+ * @returns {(req: Request, url: URL) => Promise<Response | null>}
+ */
+export function createServerFunctionMiddleware(
+  root: string,
+  entries: () => readonly ServerEntry[],
+): (req: Request, url: URL) => Promise<Response | null> {
+  const requireFromProject = createRequire(resolve(root, "package.json"));
+  return async (req, url) => {
+    if (req.method !== "POST" || !url.pathname.startsWith(SERVER_FUNCTION_ROUTE)) {
+      return null;
+    }
+    const name = url.pathname.slice(SERVER_FUNCTION_ROUTE.length);
+    const entry = entries().find((candidate) => candidate.exportName === name);
+    if (!entry) {
+      return problem("notFound", `The last build collected no server function "${name}"`);
+    }
+
+    let modulePath: string;
+    try {
+      modulePath =
+        entry.src.startsWith("./") || entry.src.startsWith("../")
+          ? resolve(root, entry.src)
+          : requireFromProject.resolve(entry.src);
+    } catch (error) {
+      return Response.json({ error: errorMessage(error), ok: false }, { status: 500 });
+    }
+
+    const args = await readArguments(req);
+    const result = await callServerExport(modulePath, entry.exportName, args, projectDevEnv(root));
+    if (result.ok) {
+      return Response.json(result.value ?? null);
+    }
+    return Response.json({ error: result.message, ok: false }, { status: 500 });
+  };
+}
+
 export interface DevServerHandle {
   port: number;
   stop: () => void;
@@ -106,10 +190,13 @@ export async function startDev({ port, root }: DevArgs): Promise<DevServerHandle
   const isSite = existsSync(join(root, "project.json"));
 
   let building = Promise.resolve();
+  // What the last build collected, which the server-function route answers from.
+  let serverEntries: readonly ServerEntry[] = [];
   const rebuild = () => {
     building = building.then(async () => {
       const { buildSite } = await import("@jxsuite/compiler/site");
       const result = await buildSite(root, { verbose: false });
+      ({ serverEntries } = result);
       if (result.errors.length > 0) {
         for (const err of result.errors) {
           console.error(`  build error: ${err}`);
@@ -124,6 +211,13 @@ export async function startDev({ port, root }: DevArgs): Promise<DevServerHandle
     await rebuild();
   }
 
+  // The built pages call the site worker's routes, and `jx dev` has no worker, so it answers them
+  // From the entries the last build collected, ahead of the built pages.
+  const serverFunctions = createServerFunctionMiddleware(root, () => serverEntries);
+  const distPages = createDistMiddleware(root);
+  const siteMiddleware = async (req: Request, url: URL) =>
+    (await serverFunctions(req, url)) ?? (await distPages(req, url));
+
   /* SAFETY: createDevServer always calls Bun.serve with a hostname and TCP port, never a unix
      socket, so the returned Server's `port` (typed `number | undefined` for the socket case) is a
      number; its promise-returning `stop()` satisfies `() => void`. */
@@ -131,7 +225,7 @@ export async function startDev({ port, root }: DevArgs): Promise<DevServerHandle
     port,
     root,
     ...(isSite && {
-      middleware: createDistMiddleware(root),
+      middleware: siteMiddleware,
       watch: { preReload: () => rebuild(), reloadOnAnyChange: true },
     }),
   })) as DevServerHandle;

package/src/extension-catalog.ts

@@ -8,10 +8,11 @@
  *    `extensions/` tree, so core keeps no dependency on an extension package (§2).
  * 2. The project's own dependencies, scanned for anything exporting a `jx-extension.json`.
  *
- * Both are then annotated with two facts only a backend holds: whether the PROJECT resolves the
- * package, and whether THIS HOST does. Those are probed rather than declared, because what a
- * desktop build stages and what a Worker bundles are different facts and neither is knowable from a
- * package list — which is also why the catalogue is a platform capability instead of a constant.
+ * Both are then annotated with the one fact only a backend holds: whether the PROJECT resolves the
+ * package. It is probed rather than declared, and it is the only resolution asked about: an
+ * extension resolves from the project's own install and never from this host, first-party ones
+ * included (specs/extensions.md §3), so enabling one the project lacks is always
+ * install-then-enable.
  *
  * **`installed` is answered here rather than by the client**, because `listPackages` does not mean
  * one thing across backends: the dev server's own packages route drops a declared dependency it
@@ -184,11 +185,6 @@ export async function buildExtensionCatalog(projectRoot: string): Promise<Extens
     if (meta.requires) {
       entry.requires = meta.requires;
     }
-    // Bundled means "resolves without a project install": the host answers for it, and the
-    // Project does not have to.
-    if (found.host && !found.project) {
-      entry.bundled = true;
-    }
     entries.push(entry);
   }
 
@@ -238,9 +234,6 @@ export async function buildExtensionCatalog(projectRoot: string): Promise<Extens
     if (loaded.formats.length > 0) {
       entry.formats = loaded.formats;
     }
-    if (found.host) {
-      entry.bundled = true;
-    }
     entries.push(entry);
   }
 

package/src/file-response.ts

@@ -0,0 +1,140 @@
+/**
+ * File responses on `node:fs`, answering what `new Response(Bun.file(path))` answered.
+ *
+ * The desktop backend runs on Electron's Node (specs/desktop.md §7.1), so the servers it reaches
+ * cannot hand `Bun.file` to a `Response`. `openAsBlob` is the shared equivalent: a lazily read,
+ * file-backed `Blob` whose `type` becomes the response's `Content-Type`. What it lacks is Bun's
+ * inference of that type from the extension, which {@link HOST_MEDIA_TYPES} reproduces for every
+ * extension a project or the Studio assets serve; `tests/file-response.test.ts` holds each entry
+ * equal to `Bun.file(...).type`. The corrections Jx makes to a host's table (`mediaTypeForPath`)
+ * are applied by callers on top of this, exactly as they were on top of Bun's.
+ *
+ * @docs studio/desktop
+ */
+import { openAsBlob, statSync } from "node:fs";
+import { extname } from "node:path";
+
+/** The type `Bun.file` infers for an extension, where it is not `application/octet-stream`. */
+export const HOST_MEDIA_TYPES = new Map<string, string>([
+  [".7z", "application/x-7z-compressed"],
+  [".aac", "audio/x-aac"],
+  [".ai", "application/postscript"],
+  [".apng", "image/apng"],
+  [".atom", "application/atom+xml"],
+  [".avif", "image/avif"],
+  [".bmp", "image/x-ms-bmp"],
+  [".cjs", "text/javascript;charset=utf-8"],
+  [".class", "application/java-vm"],
+  [".css", "text/css;charset=utf-8"],
+  [".csv", "text/csv"],
+  [".dmg", "application/x-apple-diskimage"],
+  [".doc", "application/msword"],
+  [".docx", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"],
+  [".eot", "application/vnd.ms-fontobject"],
+  [".eps", "application/postscript"],
+  [".epub", "application/epub+zip"],
+  [".exe", "application/x-msdownload"],
+  [".flac", "audio/x-flac"],
+  [".gif", "image/gif"],
+  [".glb", "model/gltf-binary"],
+  [".gltf", "model/gltf+json"],
+  [".gz", "application/gzip"],
+  [".hbs", "text/x-handlebars-template"],
+  [".heic", "image/heic"],
+  [".htm", "text/html;charset=utf-8"],
+  [".html", "text/html;charset=utf-8"],
+  [".ico", "image/x-icon"],
+  [".ics", "text/calendar"],
+  [".iso", "application/x-iso9660-image"],
+  [".jpeg", "image/jpeg"],
+  [".jpg", "image/jpeg"],
+  [".js", "text/javascript;charset=utf-8"],
+  [".json", "application/json;charset=utf-8"],
+  [".jsonld", "application/ld+json"],
+  [".jsx", "text/javascript;charset=utf-8"],
+  [".log", "text/plain;charset=utf-8"],
+  [".m4a", "audio/x-m4a"],
+  [".map", "application/json;charset=utf-8"],
+  [".markdown", "text/markdown"],
+  [".md", "text/markdown"],
+  [".mdx", "text/mdx"],
+  [".mjs", "text/javascript;charset=utf-8"],
+  [".mov", "video/quicktime"],
+  [".mp3", "audio/mpeg"],
+  [".mp4", "video/mp4"],
+  [".mts", "text/javascript;charset=utf-8"],
+  [".oga", "audio/ogg"],
+  [".ogg", "audio/ogg"],
+  [".ogv", "video/ogg"],
+  [".opus", "audio/ogg"],
+  [".otf", "font/otf"],
+  [".pdf", "application/pdf"],
+  [".php", "application/x-httpd-php"],
+  [".png", "image/png"],
+  [".ppt", "application/vnd.ms-powerpoint"],
+  [".pptx", "application/vnd.openxmlformats-officedocument.presentationml.presentation"],
+  [".psd", "image/vnd.adobe.photoshop"],
+  [".rar", "application/x-rar-compressed"],
+  [".rss", "application/rss+xml"],
+  [".rtf", "text/rtf"],
+  [".sh", "application/x-sh"],
+  [".srt", "application/x-subrip"],
+  [".svg", "image/svg+xml"],
+  [".tar", "application/x-tar"],
+  [".tif", "image/tiff"],
+  [".tiff", "image/tiff"],
+  [".toml", "application/toml"],
+  [".ts", "text/javascript;charset=utf-8"],
+  [".tsv", "text/tab-separated-values"],
+  [".tsx", "text/javascript;charset=utf-8"],
+  [".ttf", "font/ttf"],
+  [".txt", "text/plain;charset=utf-8"],
+  [".vtt", "text/vtt"],
+  [".wasm", "application/wasm"],
+  [".wav", "audio/x-wav"],
+  [".weba", "audio/webm"],
+  [".webm", "video/webm"],
+  [".webmanifest", "application/manifest+json"],
+  [".webp", "image/webp"],
+  [".woff", "font/woff"],
+  [".woff2", "font/woff2"],
+  [".xls", "application/vnd.ms-excel"],
+  [".xlsx", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"],
+  [".xml", "application/xml"],
+  [".yaml", "text/yaml"],
+  [".yml", "text/yaml"],
+  [".zip", "application/zip"],
+]);
+
+const FALLBACK_MEDIA_TYPE = "application/octet-stream";
+
+/** The media type Bun would infer for `path` from its extension (case-insensitive). */
+export function hostMediaType(path: string): string {
+  return HOST_MEDIA_TYPES.get(extname(path).toLowerCase()) ?? FALLBACK_MEDIA_TYPE;
+}
+
+/** True when `path` names a regular file (Bun's `exists()` is false for a directory). */
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The file at `path` as a lazily read `Blob` typed by its extension, or null when there is no
+ * regular file there.
+ */
+export async function openFile(path: string): Promise<Blob | null> {
+  if (!isFile(path)) {
+    return null;
+  }
+  return openAsBlob(path, { type: hostMediaType(path) });
+}
+
+/** A response streaming the file at `path`, or null when there is no regular file there. */
+export async function fileResponse(path: string, init?: ResponseInit): Promise<Response | null> {
+  const blob = await openFile(path);
+  return blob ? new Response(blob, init) : null;
+}

package/src/fs-glob.ts

@@ -0,0 +1,45 @@
+/**
+ * File globbing on `node:fs`, answering what `Bun.Glob#scan({ cwd, dot: false })` answered.
+ *
+ * The desktop backend runs on Electron's Node (specs/desktop.md §7.1), so nothing it reaches may
+ * call `Bun.Glob`. `fs.promises.glob` is the shared API, and two of its defaults differ from Bun's:
+ * it yields directories as well as files, and it yields a symbolic link as itself. A third
+ * difference is in the matcher, below. Bun's scan yields regular files only and does not follow
+ * links, so both are filtered here. `tests/fs-glob.test.ts` holds the two answers equal on the same
+ * tree.
+ *
+ * Paths are relative to `cwd` with the platform's own separator, as Bun's were.
+ */
+import type { Dirent } from "node:fs";
+import { glob, opendir } from "node:fs/promises";
+import { join, relative } from "node:path";
+
+/** Bun's scan neither yields nor descends through a symbolic link, file or directory. */
+function isLink(entry: Dirent): boolean {
+  return entry.isSymbolicLink();
+}
+
+/**
+ * Bun expands a one-alternative brace (`*.{json}`) and Node's matcher keeps it literal, so a
+ * pattern built from a list that happens to hold one extension would match nothing. Unwrap those.
+ */
+function unwrapSingleBraces(pattern: string): string {
+  return pattern.replaceAll(/\{([^{},]*)\}/g, "$1");
+}
+
+/**
+ * Every regular file under `cwd` matching `pattern`, skipping dot-prefixed names.
+ *
+ * @yields {string} Each match, relative to `cwd`
+ */
+export async function* scanFiles(pattern: string, cwd: string): AsyncGenerator<string> {
+  // Bun's scan throws for a root it cannot read; Node's glob yields nothing. Opening it first throws.
+  const dir = await opendir(cwd);
+  await dir.close();
+  const options = { cwd, exclude: isLink, withFileTypes: true } as const;
+  for await (const entry of glob(unwrapSingleBraces(pattern), options)) {
+    if (entry.isFile()) {
+      yield relative(cwd, join(entry.parentPath, entry.name));
+    }
+  }
+}

package/src/live-preview.ts

@@ -54,6 +54,9 @@ import { handleResolve, handleServerFunction } from "./resolve.ts";
 import { handleJxMounts } from "./jx-mounts.ts";
 import { loopbackGate, originHostGate } from "./net-guard.ts";
 import { problem } from "./problem.ts";
+import { scanFiles } from "./fs-glob.ts";
+import { serve } from "#serve";
+import { bundleToString } from "@jxsuite/compiler/bundler";
 
 /** A running live preview for one project. */
 export interface LivePreview {
@@ -116,7 +119,7 @@ function overlayFor(projectRoot: string): Overlay {
 }
 
 interface Running extends LivePreview {
-  server: { stop: (closeActiveConnections?: boolean) => void };
+  server: { stop: (closeActiveConnections?: boolean) => Promise<void> };
   hub: SseHub;
   /** This origin's own resolver credential, distinct from any editing server's. */
   token: string;
@@ -132,6 +135,8 @@ interface Running extends LivePreview {
 
 /** One origin per project root — a second Open in Browser reuses the first one's port. */
 const running = new Map<string, Running>();
+/** Origins mid-bind, so two starts racing for one project share a server. */
+const starting = new Map<string, Promise<Running>>();
 
 /** The runtime bundle is the same bytes for every project, so it is read once per process. */
 let runtimeBundle: string | null = null;
@@ -162,11 +167,10 @@ async function loadRuntimeBundle(): Promise<string> {
   } catch {
     // No published dist on this install; fall through and build one.
   }
-  const result = await Bun.build({
-    entrypoints: [require_.resolve("@jxsuite/runtime")],
+  runtimeBundle = await bundleToString(require_.resolve("@jxsuite/runtime"), {
+    minify: false,
     target: "browser",
   });
-  runtimeBundle = await result.outputs[0]!.text();
   return runtimeBundle;
 }
 
@@ -178,7 +182,7 @@ async function treePaths(projectRoot: string, overlay: Map<string, string>): Pro
     if (!existsSync(dir)) {
       continue;
     }
-    for await (const match of new Bun.Glob("**/*").scan({ cwd: dir, dot: false })) {
+    for await (const match of scanFiles("**/*", dir)) {
       found.add(`${root}${match.replaceAll("\\", "/")}`);
     }
   }
@@ -419,7 +423,20 @@ export async function startLivePreview(projectRoot: string): Promise<LivePreview
     await ensureCache(existing, projectRoot);
     return report(existing, projectRoot);
   }
+  let pending = starting.get(projectRoot);
+  if (!pending) {
+    pending = listen(projectRoot).finally(() => starting.delete(projectRoot));
+    starting.set(projectRoot, pending);
+  }
+  const entry = await pending;
+  /* Counted before answering, because the caller reports it to the author and "0 pages" from a site
+     with pages is worse than the moment it costs to walk the tree. */
+  await ensureCache(entry, projectRoot);
+  return report(entry, projectRoot);
+}
 
+/** Bind the live preview origin for `projectRoot` and register it. */
+async function listen(projectRoot: string): Promise<Running> {
   const entry: Running = {
     burstStartedAt: null,
     cache: null,
@@ -431,11 +448,11 @@ export async function startLivePreview(projectRoot: string): Promise<LivePreview
     port: 0,
     reloadTimer: null,
     routes: 0,
-    server: { stop: () => {} },
+    server: { stop: async () => {} },
     token: crypto.randomUUID(),
   };
 
-  const server = Bun.serve({
+  const server = await serve({
     fetch: (req) => handle(entry, projectRoot, req),
     hostname: "127.0.0.1",
     /* The composed page is assembled per request and the stream is long-lived; the dev server's
@@ -449,10 +466,7 @@ export async function startLivePreview(projectRoot: string): Promise<LivePreview
   entry.origin = server.url.origin;
   entry.port = Number(server.url.port);
   running.set(projectRoot, entry);
-  /* Counted before answering, because the caller reports it to the author and "0 pages" from a site
-     with pages is worse than the moment it costs to walk the tree. */
-  await ensureCache(entry, projectRoot);
-  return report(entry, projectRoot);
+  return entry;
 }
 
 /** What a caller hands back to Studio. */
@@ -616,7 +630,7 @@ export function stopLivePreviews(): void {
     if (entry.reloadTimer) {
       clearTimeout(entry.reloadTimer);
     }
-    entry.server.stop(true);
+    void entry.server.stop(true);
   }
   running.clear();
 }

package/src/net-guard.ts

@@ -21,6 +21,7 @@ import { realpathSync } from "node:fs";
 import { resolveAssetUrl } from "@jxsuite/schema/asset-paths";
 import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import { problem } from "./problem.ts";
+import { fileResponse } from "./file-response.ts";
 
 export const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
 
@@ -300,11 +301,7 @@ export async function serveContained(absPath: string, root: string): Promise<Res
   if (!safe) {
     return null;
   }
-  const file = Bun.file(safe);
-  if (await file.exists()) {
-    return new Response(file);
-  }
-  return null;
+  return fileResponse(safe);
 }
 
 /**