@jxsuite/server 6.1.0 → 8.0.0

package/src/server.ts

@@ -13,7 +13,7 @@
  *   proxying, and studio filesystem integration as a single createDevServer() call.
  */
 
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { buildAll } from "./build.ts";
 import { createCollabRegistry } from "./collab.ts";
 import { createWatcher, injectSSE } from "./watch.ts";
@@ -40,148 +40,11 @@ import { handleCodeApi } from "./code-api.ts";
 import { handleAiApi } from "./ai-api.ts";
 import { handleImportApi } from "./import-api.ts";
 import { mediaTypeForPath } from "@jxsuite/schema/media-type";
-import { existsSync, readFileSync } from "node:fs";
 import { problem } from "./problem.ts";
-import { isJsonObject, isNonNullObject, isString } from "@jxsuite/schema/guards";
-import type { JsonValue } from "@jxsuite/schema/types";
 
-/**
- * Read `key` off a parsed `package.json` value, or `undefined` when the value is not an object.
- *
- * Every lookup below reads through this one, so a manifest of the wrong shape (an `exports` that is
- * a string, a `main` that is an array) yields "absent" rather than a member of something else.
- */
-function manifestField(value: JsonValue | undefined, key: string): JsonValue | undefined {
-  return isJsonObject(value) ? value[key] : undefined;
-}
-
-/** Read and parse a package's `package.json`. Throws when the file is not JSON. */
-function readManifest(pkgJsonPath: string): JsonValue {
-  // SAFETY: JSON.parse without a reviver only ever yields a JSON value; its `any` says no more.
-  return JSON.parse(readFileSync(pkgJsonPath, "utf8")) as JsonValue;
-}
-
-/**
- * Resolve an npm-style bare specifier from a URL path via node_modules. Handles scoped packages
- * (@scope/pkg/subpath) and respects package.json exports. Strips leading directory segments (e.g.
- * /pages/@scope/pkg/file → @scope/pkg/file).
- *
- * @param {string} root - Absolute project root
- * @param {string} urlPath - URL pathname (e.g. "/pages/@jxsuite/parser/Foo.class.json")
- * @returns {string | null} Absolute file path or null
- */
-function resolveNpmPath(rootDir: string, urlPath: string) {
-  let root = rootDir;
-  let segments = urlPath.split("/").filter(Boolean);
-
-  // If "node_modules" appears in the path, use everything before it as a subdirectory
-  // Prefix and everything after as the package specifier.
-  // E.g. /examples/demo/node_modules/@scope/pkg → root=root/examples/demo, pkg=@scope/pkg
-  const nmIdx = segments.indexOf("node_modules");
-  if (nmIdx !== -1) {
-    if (nmIdx > 0) {
-      root = join(root, ...segments.slice(0, nmIdx));
-    }
-    segments = segments.slice(nmIdx + 1);
-  }
-
-  // Find the package start — either @scope/pkg or unscoped pkg
-  let start = -1;
-  let isScoped = false;
-  for (let i = 0; i < segments.length; i++) {
-    if (segments[i]!.startsWith("@")) {
-      start = i;
-      isScoped = true;
-      break;
-    }
-  }
-
-  let pkgDir = "";
-  let subpath = "";
-
-  if (isScoped) {
-    if (start < 0 || start + 1 >= segments.length) {
-      return null;
-    }
-    const scope = segments[start]!;
-    const pkg = segments[start + 1]!;
-    subpath = segments.slice(start + 2).join("/");
-    pkgDir = join(root, "node_modules", scope, pkg);
-  } else {
-    // Unscoped: try each segment as a package name in node_modules
-    for (let i = 0; i < segments.length; i++) {
-      const candidate = join(root, "node_modules", segments[i]!);
-      if (existsSync(join(candidate, "package.json"))) {
-        start = i;
-        pkgDir = candidate;
-        subpath = segments.slice(i + 1).join("/");
-        break;
-      }
-    }
-    if (start < 0) {
-      return null;
-    }
-  }
-
-  const pkgJsonPath = join(pkgDir, "package.json");
-  if (!existsSync(pkgJsonPath)) {
-    return null;
-  }
-
-  // If there's a subpath, check package.json exports first
-  if (subpath) {
-    try {
-      const pkgJson = readManifest(pkgJsonPath);
-      const exportVal = manifestField(manifestField(pkgJson, "exports"), `./${subpath}`);
-      if (isString(exportVal)) {
-        const mapped = join(pkgDir, exportVal);
-        if (existsSync(mapped)) {
-          return mapped;
-        }
-      }
-    } catch {}
-    // Fall back to direct path
-    const direct = join(pkgDir, subpath);
-    if (existsSync(direct)) {
-      return direct;
-    }
-    // CEM-relative: subpath may be relative to the custom elements manifest directory
-    try {
-      const customElements = manifestField(readManifest(pkgJsonPath), "customElements");
-      if (isString(customElements) && customElements) {
-        const cemDir = customElements.replace(/\/[^/]+$/, "");
-        const cemRelative = join(pkgDir, cemDir, subpath);
-        if (existsSync(cemRelative)) {
-          return cemRelative;
-        }
-      }
-    } catch {}
-  }
-
-  // Bare package (no subpath): resolve entry point
-  try {
-    const pkgJson = readManifest(pkgJsonPath);
-    const exp = manifestField(manifestField(pkgJson, "exports"), ".");
-    // An explicit `null` entry declines the package's entry point outright: no `module`/`main`.
-    if (exp !== null) {
-      const conditional = isNonNullObject(exp)
-        ? (manifestField(exp, "import") ?? manifestField(exp, "default"))
-        : exp;
-      const entry =
-        conditional ?? manifestField(pkgJson, "module") ?? manifestField(pkgJson, "main");
-      if (isString(entry) && entry) {
-        const resolved = join(pkgDir, entry);
-        if (existsSync(resolved)) {
-          return resolved;
-        }
-      }
-    }
-  } catch {}
-
-  return null;
-}
+import { resolveNpmPath } from "./npm-path.ts";
 
-export { resolveNpmPath };
+export { resolveNpmPath } from "./npm-path.ts";
 
 /** The watcher options `createDevServer` passes through when `watch` is an object. */
 type DevWatchOptions = NonNullable<Parameters<typeof createWatcher>[2]>;
@@ -200,7 +63,7 @@ type DevWatchOptions = NonNullable<Parameters<typeof createWatcher>[2]>;
  * }[]} [options.builds]
  *   - Bun.build entries with optional match regex
  * @param {boolean | object} [options.watch] - Watch config or false to disable. Default is `true`
- * @param {boolean} [options.studio] - Enable /**studio/* endpoints. Default is `true`
+ * @param {boolean} [options.studio] - Enable /*_studio/_ endpoints. Default is `true`
  * @param {Function} [options.middleware] - Custom route handler (req, url) => Response|null
  * @returns {Promise<object>} The Bun.serve server object
  */
@@ -395,7 +258,12 @@ export async function createDevServer(options: {
       if (enableStudio && path.startsWith("/__studio/")) {
         // Realtime co-editing: WebSocket upgrade or capability probe
         if (path === "/__studio/collab") {
-          return collabRegistry.handleRequest(req, bunServer);
+          return collabRegistry.handleRequest(req, {
+            upgrade: (upgradeReq, { data, headers }) =>
+              headers === undefined
+                ? bunServer.upgrade(upgradeReq, { data })
+                : bunServer.upgrade(upgradeReq, { data, headers: { ...headers } }),
+          });
         }
 
         // Activate project — tells the server which project root to use for static file fallback.

package/src/site-preview.ts

@@ -28,6 +28,7 @@
 
 import { serveSiteOutput, siteOutDir } from "./site-output.ts";
 import { problem } from "./problem.ts";
+import { serve } from "#serve";
 
 /** A running preview server for one project. */
 export interface SitePreview {
@@ -37,27 +38,38 @@ export interface SitePreview {
 }
 
 interface Running extends SitePreview {
-  server: { stop: (closeActiveConnections?: boolean) => void };
+  server: { stop: (closeActiveConnections?: boolean) => Promise<void> };
 }
 
-/** One server per project root — a second `Open in Browser` reuses the first one's port. */
-const running = new Map<string, Running>();
+/**
+ * One server per project root — a second `Open in Browser` reuses the first one's port. Held as the
+ * start's promise, so two calls racing the bind share one server rather than starting two.
+ */
+const running = new Map<string, Promise<Running>>();
 
 /**
  * Start (or reuse) the preview server for `projectRoot`, or `null` when there is nothing to serve:
  * not a site project, or a site nobody has built yet. A caller that has just built gets a server;
  * one that has not gets the honest answer rather than a port that 404s everything.
  */
-export function startSitePreview(projectRoot: string): SitePreview | null {
+export async function startSitePreview(projectRoot: string): Promise<SitePreview | null> {
   const outDir = siteOutDir(projectRoot);
   if (!outDir) {
     return null;
   }
-  const existing = running.get(projectRoot);
-  if (existing) {
-    return { origin: existing.origin, port: existing.port };
+  let starting = running.get(projectRoot);
+  if (!starting) {
+    starting = listen(projectRoot);
+    running.set(projectRoot, starting);
+    starting.catch(() => running.delete(projectRoot));
   }
-  const server = Bun.serve({
+  const { origin, port } = await starting;
+  return { origin, port };
+}
+
+/** Bind the preview server for `projectRoot`. */
+async function listen(projectRoot: string): Promise<Running> {
+  const server = await serve({
     fetch: async (req: Request) => {
       const url = new URL(req.url);
       let decoded: string;
@@ -83,24 +95,27 @@ export function startSitePreview(projectRoot: string): SitePreview | null {
   });
   // `server.url` rather than `server.port`: the origin is the thing being handed to a browser, and
   // Reading it from the server that is actually listening cannot disagree with it.
-  const entry: Running = {
-    origin: server.url.origin,
-    port: Number(server.url.port),
-    server,
-  };
-  running.set(projectRoot, entry);
-  return { origin: entry.origin, port: entry.port };
+  return { origin: server.url.origin, port: Number(server.url.port), server };
 }
 
 /** The origin already serving `projectRoot`, without starting one. */
-export function sitePreviewOrigin(projectRoot: string): string | null {
-  return running.get(projectRoot)?.origin ?? null;
+export async function sitePreviewOrigin(projectRoot: string): Promise<string | null> {
+  const starting = running.get(projectRoot);
+  if (!starting) {
+    return null;
+  }
+  const entry = await starting;
+  return entry.origin;
 }
 
 /** Stop every preview server (process teardown, and the hook tests close their ports with). */
-export function stopSitePreviews(): void {
-  for (const entry of running.values()) {
-    entry.server.stop(true);
-  }
+export async function stopSitePreviews(): Promise<void> {
+  const entries = [...running.values()];
   running.clear();
+  await Promise.all(
+    entries.map(async (starting) => {
+      const entry = await starting.catch(() => null);
+      await entry?.server.stop(true);
+    }),
+  );
 }

package/src/studio-api.ts

@@ -11,12 +11,13 @@ import { basename, dirname, extname, isAbsolute, join, relative, resolve } from
 import { componentMetaFrom } from "@jxsuite/schema/component-meta";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { mkdir, readFile, readdir, rename, rmdir, stat, unlink, writeFile } from "node:fs/promises";
-import { existsSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { LOCATION_ID_FILE } from "@jxsuite/protocol/routes";
 import {
+  anyNowInstalled,
   buildExtensionsPayload,
-  buildProjectExtensionRegistry,
+  buildInstalledExtensionRegistry,
+  missingExtensionsNotice,
 } from "@jxsuite/compiler/format-host";
 import { readBundledProjectSchemas } from "@jxsuite/compiler/schema-command";
 import { handleDataApi } from "./data-api.ts";
@@ -31,10 +32,11 @@ import {
 import { applyRename } from "./refactor/apply.ts";
 import { findReferences } from "./refactor/find-refs.ts";
 import {
-  bunExecutable,
+  addPackage,
   dependenciesNeedInstall,
   installDependencies,
   packageVersions,
+  removePackage,
   setPackageVersions,
 } from "./packages.ts";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
@@ -44,6 +46,7 @@ import type { DesignOptions, ProjectOptions } from "@jxsuite/create/generate";
 import type { JsonObject, JsonPrimitive, JsonValue, ProjectConfig } from "@jxsuite/schema/types";
 import { isFunction, isJsonObject, isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { problem } from "./problem.ts";
+import { scanFiles } from "./fs-glob.ts";
 
 /** Normalise a path to forward slashes (Windows `path` module returns backslashes). */
 const fwd = (p: string) => p.replaceAll("\\", "/");
@@ -94,12 +97,19 @@ interface Cem {
 
 // ─── Extension registry (per project root, invalidated on project.json change) ──
 
-const extensionRegistryCache = new Map<string, { mtime: number; registry: ExtensionRegistry }>();
+const extensionRegistryCache = new Map<
+  string,
+  { mtime: number; missing: string[]; registry: ExtensionRegistry }
+>();
 
 /**
  * Build (or reuse) a project's extension registry (built from its project.json `extensions` array).
  * An empty registry is returned when there is no project.json — only .json files are handled then.
  *
+ * The editor's registry: an enabled package the project has not installed is skipped and said once,
+ * not thrown per request (specs/extensions.md §3). A registry that skipped one is rebuilt as soon
+ * as it resolves, because an install does not touch `project.json` and so moves no mtime.
+ *
  * @param {string} projectRoot
  * @returns {Promise<ExtensionRegistry>}
  */
@@ -116,11 +126,14 @@ async function getExtensionRegistry(projectRoot: string): Promise<ExtensionRegis
     projectConfig = undefined;
   }
   const cached = extensionRegistryCache.get(projectRoot);
-  if (cached && cached.mtime === mtime) {
+  if (cached && cached.mtime === mtime && !anyNowInstalled(projectRoot, cached.missing)) {
     return cached.registry;
   }
-  const registry = await buildProjectExtensionRegistry(projectRoot, projectConfig);
-  extensionRegistryCache.set(projectRoot, { mtime, registry });
+  const { missing, registry } = await buildInstalledExtensionRegistry(projectRoot, projectConfig);
+  if (missing.length > 0 && missing.join("\n") !== cached?.missing.join("\n")) {
+    console.warn(`[studio] ${missingExtensionsNotice(missing)}`);
+  }
+  extensionRegistryCache.set(projectRoot, { missing, mtime, registry });
   return registry;
 }
 
@@ -568,108 +581,11 @@ export async function handleStudioApi(
     }
   }
 
-  // Find a project directory by name — searches $HOME for the first matching directory with a
-  // Project.json. Dev-mode workaround for when showDirectoryPicker() can't provide absolute paths.
-  if (path === "/__studio/find-project" && req.method === "GET") {
-    const name = url.searchParams.get("name");
-    if (!name) {
-      return problem("invalidRequest", "Missing name");
-    }
-    try {
-      const home = process.env.HOME || process.env.USERPROFILE || "";
-      if (!home) {
-        return Response.json({ path: null });
-      }
-      const glob = new Bun.Glob(`**/${name}/project.json`);
-      try {
-        for await (const match of glob.scan({ cwd: home, dot: false })) {
-          if (match.includes("node_modules") || match.includes(".Trash")) {
-            continue;
-          }
-          const abs = resolve(home, dirname(match));
-          return Response.json({ path: abs });
-        }
-      } catch {}
-      return Response.json({ path: null });
-    } catch (error) {
-      return problem("internalError", errorMessage(error));
-    }
-  }
-
-  /*
-   * Recover the absolute path of a directory the browser picked with `showDirectoryPicker()`.
-   *
-   * A `FileSystemDirectoryHandle` exposes only `.name`, never a filesystem path (§8.2), and unlike
-   * /__studio/find-project there is no `project.json` to search for — the whole point is that the
-   * folder is empty. So the client tags the folder with a hidden LOCATION_ID_FILE holding a random
-   * id and asks us which directory carries that id.
-   *
-   * Identity lives in the file's CONTENTS, not its name: matching the id is exact where matching a
-   * path shape is only probable — two folders can share a basename, and a file left behind by a
-   * crashed session can still be on disk. A candidate whose contents do not equal `id` is skipped,
-   * so a stale tag can never redirect a create. The winning file is deleted here, the moment it has
-   * served its purpose, rather than being left for the client to tidy up.
-   */
-  if (path === "/__studio/locate-directory" && req.method === "GET") {
-    const name = url.searchParams.get("name");
-    const id = url.searchParams.get("id");
-    // `name` is interpolated into a glob; the id is only ever compared, never used as a pattern.
-    if (!name || !id || !/^[a-f0-9]{32}$/.test(id) || !/^[^/\\]+$/.test(name)) {
-      return problem("invalidRequest", "Missing or invalid name/id");
-    }
-    try {
-      const home = process.env.HOME || process.env.USERPROFILE || "";
-      if (!home) {
-        return Response.json({ path: null });
-      }
-      /** The tagged directory when this candidate holds our id, else null. */
-      const claim = (dir: string): string | null => {
-        const file = resolve(dir, LOCATION_ID_FILE);
-        try {
-          if (readFileSync(file, "utf8").trim() !== id) {
-            return null;
-          }
-        } catch {
-          return null;
-        }
-        try {
-          unlinkSync(file);
-        } catch {
-          // Read-only or already gone; the client's own cleanup is the backstop.
-        }
-        return dir;
-      };
-
-      // The home directory itself is a legitimate pick, and no `**/<name>/` glob can match it.
-      const atHome = claim(home);
-      if (atHome) {
-        return Response.json({ path: atHome });
-      }
-      // `dot: true` — the tag is a dotfile, so a dot-blind scan would never see it.
-      const glob = new Bun.Glob(`**/${name}/${LOCATION_ID_FILE}`);
-      try {
-        for await (const match of glob.scan({ cwd: home, dot: true })) {
-          if (match.includes("node_modules") || match.includes(".Trash")) {
-            continue;
-          }
-          const claimed = claim(resolve(home, dirname(match)));
-          if (claimed) {
-            return Response.json({ path: claimed });
-          }
-        }
-      } catch {}
-      return Response.json({ path: null });
-    } catch (error) {
-      return problem("internalError", errorMessage(error));
-    }
-  }
-
   // Discover site projects — find all project.json files under root
   if (path === "/__studio/sites" && req.method === "GET") {
     try {
-      const glob = new Bun.Glob("**/project.json");
       const sites = [];
-      for await (const match of glob.scan({ cwd: root, dot: false })) {
+      for await (const match of scanFiles("**/project.json", root)) {
         if (
           match.includes("node_modules") ||
           fwd(match).includes("dist/") ||
@@ -781,8 +697,7 @@ export async function handleStudioApi(
         await readFile(resolve(destPath, "project.json"), "utf8"),
       ) as ProjectConfig;
       // Root-relative while the project happens to sit under the server root (the historical
-      // Shape every caller already handles); absolute otherwise, which is the same shape
-      // /__studio/find-project returns for an external project.
+      // Shape every caller already handles); absolute otherwise.
       const inRoot = containedPath(destPath, root) !== null;
       opts.onProjectCreated?.(destPath);
       return Response.json({ config, root: inRoot ? fwd(relative(root, destPath)) : destPath });
@@ -824,9 +739,8 @@ export async function handleStudioApi(
 
     try {
       if (pattern) {
-        const glob = new Bun.Glob(pattern);
         const files = [];
-        for await (const match of glob.scan({ cwd: absDir, dot: false })) {
+        for await (const match of scanFiles(pattern, absDir)) {
           const fp = resolve(absDir, match);
           try {
             const s = await stat(fp);
@@ -881,9 +795,9 @@ export async function handleStudioApi(
     try {
       const registry = await getFormatRegistry(scanRoot);
       const componentExts = registry.documentExtensions("component").map((e: string) => e.slice(1));
-      const glob = new Bun.Glob(`**/*.{${["json", ...componentExts].join(",")}}`);
       const components = [];
-      for await (const match of glob.scan({ cwd: scanRoot, dot: false })) {
+      const pattern = `**/*.{${["json", ...componentExts].join(",")}}`;
+      for await (const match of scanFiles(pattern, scanRoot)) {
         if (
           match.includes("node_modules") ||
           fwd(match).includes("dist/") ||
@@ -1032,7 +946,7 @@ export async function handleStudioApi(
       // `clean: false` — this runs on the way to opening a page, and wiping the output directory
       // First would mean every asset 404s for as long as the build takes.
       const result = await buildSite(dir, { clean: false, verbose: false });
-      const preview = startSitePreview(dir);
+      const preview = await startSitePreview(dir);
       const built = { errors: result.errors, files: result.files, routes: result.routes };
       // `url` follows the build fields, and only when a preview origin exists.
       return Response.json(preview ? { ...built, url: preview.origin } : built);
@@ -1208,9 +1122,9 @@ export async function handleStudioApi(
   // Add an npm package
   if (path === "/__studio/packages/add" && req.method === "POST") {
     try {
-      /* SAFETY: `name` reaches argv, so it is re-checked with isString below; `dir` is only
-         path-resolved and `dev` only tested for truthiness, and a wrongly typed `dir` throws in
-         isAbsolute inside this try and answers 500. */
+      /* SAFETY: `name` is re-checked with isString below; `dir` is only path-resolved and `dev`
+         only tested for truthiness, and a wrongly typed `dir` throws in isAbsolute inside this try
+         and answers 500. */
       const body = (await req.json()) as { name?: string; dir?: string; dev?: boolean };
       const { name } = body;
       if (!name || !isString(name)) {
@@ -1218,19 +1132,9 @@ export async function handleStudioApi(
       }
       const dir = body.dir || activeProjectRoot;
       const cwd = dir ? (isAbsolute(dir) ? dir : resolve(root, dir)) : root;
-      const args = ["add", name];
-      if (body.dev) {
-        args.splice(1, 0, "-d");
-      }
-      const proc = Bun.spawn([bunExecutable(), ...args], {
-        cwd,
-        stderr: "pipe",
-        stdout: "pipe",
-      });
-      const exitCode = await proc.exited;
-      if (exitCode !== 0) {
-        const stderr = await new Response(proc.stderr).text();
-        return problem("internalError", stderr || `bun add exited with ${exitCode}`);
+      const result = await addPackage(cwd, name, body.dev === true);
+      if (!result.ok) {
+        return problem("internalError", result.log ?? "Adding the package failed");
       }
       return Response.json({ ok: true });
     } catch (error) {
@@ -1241,8 +1145,8 @@ export async function handleStudioApi(
   // Remove an npm package
   if (path === "/__studio/packages/remove" && req.method === "POST") {
     try {
-      /* SAFETY: `name` reaches argv, so it is re-checked with isString below; a wrongly typed
-         `dir` throws in isAbsolute inside this try and answers 500. */
+      /* SAFETY: `name` is re-checked with isString below; a wrongly typed `dir` throws in
+         isAbsolute inside this try and answers 500. */
       const body = (await req.json()) as { name?: string; dir?: string };
       const { name } = body;
       if (!name || !isString(name)) {
@@ -1250,15 +1154,9 @@ export async function handleStudioApi(
       }
       const dir = body.dir || activeProjectRoot;
       const cwd = dir ? (isAbsolute(dir) ? dir : resolve(root, dir)) : root;
-      const proc = Bun.spawn([bunExecutable(), "remove", name], {
-        cwd,
-        stderr: "pipe",
-        stdout: "pipe",
-      });
-      const exitCode = await proc.exited;
-      if (exitCode !== 0) {
-        const stderr = await new Response(proc.stderr).text();
-        return problem("internalError", stderr || `bun remove exited with ${exitCode}`);
+      const result = await removePackage(cwd, name);
+      if (!result.ok) {
+        return problem("internalError", result.log ?? "Removing the package failed");
       }
       return Response.json({ ok: true });
     } catch (error) {
@@ -1266,7 +1164,7 @@ export async function handleStudioApi(
     }
   }
 
-  // Install all dependencies (bun install)
+  // Install all dependencies
   if (path === "/__studio/packages/install" && req.method === "POST") {
     try {
       /* SAFETY: `dir` is the only member read and is only path-resolved; a wrongly typed `dir`
@@ -1555,9 +1453,8 @@ export async function handleStudioApi(
     }
 
     try {
-      const glob = new Bun.Glob(`**/${name}`);
       const matches = [];
-      for await (const match of glob.scan({ cwd: root, dot: false })) {
+      for await (const match of scanFiles(`**/${name}`, root)) {
         // Skip node_modules / dist / hidden dirs
         if (match.includes("node_modules") || fwd(match).includes("dist/")) {
           continue;
@@ -1753,16 +1650,11 @@ export async function handleStudioApi(
           }
         }
       } else {
-        // Npm/bare specifier — use createRequire from project root, fall back to server package
+        // Npm/bare specifier — the project's own install, never the server's
+        // (specs/extensions.md §3): before the project's install this answers "not resolvable".
         const projectRoot = activeProjectRoot || root;
         const { createRequire } = await import("node:module");
-        const projRequire = createRequire(resolve(projectRoot, "package.json"));
-        try {
-          moduleAbsPath = projRequire.resolve(src);
-        } catch {
-          const serverRequire = createRequire(import.meta.url);
-          moduleAbsPath = serverRequire.resolve(src);
-        }
+        moduleAbsPath = createRequire(resolve(projectRoot, "package.json")).resolve(src);
       }
     } catch (error) {
       return Response.json({

package/src/watch-policy.ts

@@ -11,9 +11,9 @@
  *   it did.
  *
  * Both were reached at once by a launcher that adopted `$HOME` as a project root. That defect is
- * fixed where it was made (`packages/desktop/src/chromium/index.ts`), but a watcher must survive
- * being pointed at an ordinary directory rather than depend on never being pointed at one — so the
- * rules live here, stated once, because `watch.ts` (dev server) and `refactor/watcher.ts` (desktop
+ * fixed where it was made (the since-removed desktop launcher), but a watcher must survive being
+ * pointed at an ordinary directory rather than depend on never being pointed at one — so the rules
+ * live here, stated once, because `watch.ts` (dev server) and `refactor/watcher.ts` (desktop
  * session) both need them and neither owns the other.
  *
  * Symlinks are contained rather than banned: a link resolving back inside the root is project