@jxsuite/server 1.2.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -35,21 +35,21 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/collab": "^0.5.0",
-    "@jxsuite/compiler": "^1.3.0",
-    "@jxsuite/create": "^1.2.0",
-    "@jxsuite/import": "^0.38.0",
-    "@jxsuite/protocol": "^0.6.0",
-    "@jxsuite/runtime": "^1.3.0",
-    "@jxsuite/schema": "^1.3.0",
-    "@jxsuite/starters": "^1.2.0",
+    "@jxsuite/collab": "^0.6.0",
+    "@jxsuite/compiler": "^1.5.0",
+    "@jxsuite/create": "^1.2.2",
+    "@jxsuite/import": "^0.38.2",
+    "@jxsuite/protocol": "^1.0.0",
+    "@jxsuite/runtime": "^1.3.2",
+    "@jxsuite/schema": "^1.5.0",
+    "@jxsuite/starters": "^1.2.2",
     "chokidar": "^5.0.0",
     "kysely": "^0.29.4",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@jxsuite/auth": "^0.4.0",
-    "@jxsuite/connector": "^0.4.0",
-    "@jxsuite/parser": "^1.3.0"
+    "@jxsuite/auth": "^0.4.2",
+    "@jxsuite/connector": "^0.4.2",
+    "@jxsuite/parser": "^1.4.1"
   }
 }

package/src/build.ts

@@ -1,5 +1,23 @@
 /** Build.js — Configurable Bun.build pipeline */
 
+import type { BuildConfig } from "bun";
+
+/**
+ * One watched build entry.
+ *
+ * `match` and `label` belong to the watcher; every other key is forwarded verbatim to `Bun.build`,
+ * so a consumer can supply `plugins`, `splitting`, `naming`, `define` and the rest. That forwarding
+ * was always the behaviour (the implementation spreads `...opts`) but was not in the type, so a
+ * caller had no way to know it could keep a watched rebuild byte-identical to its release build —
+ * and the repo's own dev server silently did not.
+ */
+export interface BuildEntry extends Partial<BuildConfig> {
+  entrypoints: string[];
+  outdir: string;
+  match?: ((path: string) => boolean) | RegExp;
+  label?: string;
+}
+
 /**
  * Build all entries with sensible defaults (browser target, ESM, linked sourcemaps).
  *
@@ -10,14 +28,7 @@
  *   label?: string;
  * }[]} builds
  */
-export async function buildAll(
-  builds: {
-    entrypoints: string[];
-    outdir: string;
-    match?: ((path: string) => boolean) | RegExp;
-    label?: string;
-  }[],
-) {
+export async function buildAll(builds: BuildEntry[]) {
   for (const entry of builds) {
     const { match: _match, label, ...opts } = entry;
     const result = await Bun.build({
@@ -48,15 +59,7 @@ export async function buildAll(
  * @param {string} changedFile
  * @returns {Promise<{ rebuilt: string[]; success: boolean }>}
  */
-export async function rebuild(
-  builds: {
-    entrypoints: string[];
-    outdir: string;
-    match?: ((path: string) => boolean) | RegExp;
-    label?: string;
-  }[],
-  changedFile: string,
-) {
+export async function rebuild(builds: BuildEntry[], changedFile: string) {
   const rebuilt = [];
   let ok = true;
   for (const entry of builds) {

package/src/code-api.ts

@@ -7,7 +7,8 @@
 
 import { tmpdir } from "node:os";
 import { errorMessage } from "@jxsuite/schema/parse";
-import { join, resolve } from "node:path";
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
 import { unlink } from "node:fs/promises";
 import { format } from "oxfmt";
 
@@ -26,11 +27,32 @@ interface CodeApiBody {
   args?: string[];
 }
 
-const OXLINT_BIN = resolve(
-  import.meta.dir,
-  "../../node_modules/.bin",
-  process.platform === "win32" ? "oxlint.exe" : "oxlint",
-);
+const OXLINT_NAME = process.platform === "win32" ? "oxlint.exe" : "oxlint";
+
+/**
+ * Locate the oxlint CLI: explicit JX_OXLINT_BIN override (empty value = disable lint outright),
+ * then a walk up from this module probing node_modules/.bin (finds the workspace root in the
+ * monorepo and the hoisted bin for npm consumers), then PATH. Null when oxlint is unavailable —
+ * e.g. the packaged desktop app, where the lint endpoint quietly returns no diagnostics.
+ */
+export function resolveOxlintBin(startDir: string = import.meta.dir): string | null {
+  const override = process.env.JX_OXLINT_BIN;
+  if (override !== undefined) {
+    return override || null;
+  }
+  let dir = startDir;
+  for (;;) {
+    const candidate = join(dir, "node_modules", ".bin", OXLINT_NAME);
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return Bun.which("oxlint", { PATH: process.env.PATH ?? "" });
+    }
+    dir = parent;
+  }
+}
 
 // ─── Wrapper utilities ───────────────────────────────────────────────────────
 
@@ -151,6 +173,12 @@ export async function handleCodeApi(req: Request, url: URL) {
       return Response.json({ diagnostics: [] });
     }
 
+    const oxlintBin = resolveOxlintBin();
+    if (!oxlintBin) {
+      // No oxlint anywhere (packaged desktop app) — lint quietly disables.
+      return Response.json({ diagnostics: [] });
+    }
+
     const wrapped = wrapBody(code, args);
     const headerLen = wrapped.indexOf("\n") + 1;
     const tmpFile = join(
@@ -160,7 +188,7 @@ export async function handleCodeApi(req: Request, url: URL) {
 
     try {
       await Bun.write(tmpFile, wrapped);
-      const proc = Bun.spawn([OXLINT_BIN, "--format=json", "-A", "no-unused-vars", tmpFile], {
+      const proc = Bun.spawn([oxlintBin, "--format=json", "-A", "no-unused-vars", tmpFile], {
         stderr: "pipe",
         stdout: "pipe",
       });

package/src/net-guard.ts

@@ -18,6 +18,8 @@
 
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { realpathSync } from "node:fs";
+import { resolveAssetUrl } from "@jxsuite/schema/asset-paths";
+import type { AssetMount } from "@jxsuite/schema/asset-paths";
 
 export const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
 
@@ -151,14 +153,28 @@ export async function serveContained(absPath: string, root: string): Promise<Res
 }
 
 /**
- * Try to serve a project file at its natural URL: absolute-under-root, then root-relative, then
- * public/. Each candidate goes through containedPath (realpath). `decodedPath` is the once-decoded
- * URL pathname (leading slash, forward slashes).
+ * Try to serve a project file at its natural URL: an extension asset mount, then
+ * absolute-under-root, then root-relative, then public/. Each candidate goes through containedPath
+ * (realpath). `decodedPath` is the once-decoded URL pathname (leading slash, forward slashes).
+ *
+ * Mounts come first and are contained against their own directory rather than the project root:
+ * they exist precisely to publish directories that may sit outside it (extensions.md §8.5).
  */
 export async function serveProjectFile(
   decodedPath: string,
   root: string,
+  mounts: readonly AssetMount[] = [],
 ): Promise<Response | null> {
+  for (const mount of [...mounts].toSorted((a, b) => b.urlPrefix.length - a.urlPrefix.length)) {
+    const mounted = resolveAssetUrl([mount], decodedPath);
+    if (!mounted) {
+      continue;
+    }
+    const res = await serveContained(mounted, mount.dir);
+    if (res) {
+      return res;
+    }
+  }
   // Map the URL pathname back to a filesystem path. On Windows the browser requests an absolute
   // Path as /C:/Users/… (leading slash + forward slashes); drop the slash before the drive letter.
   // A POSIX absolute path arrives as //abs/path.

package/src/project-server.ts

@@ -27,7 +27,7 @@
 
 import { resolve, sep } from "node:path";
 import { handleJxMounts } from "./jx-mounts.ts";
-import { handleResolve, handleServerFunction } from "./resolve.ts";
+import { handleResolve, handleServerFunction, projectAssetMounts } from "./resolve.ts";
 import { handleAiApi } from "./ai-api.ts";
 import { handleImportApi } from "./import-api.ts";
 import { resolveNpmPath } from "./server.ts";
@@ -206,8 +206,9 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
         return handleServerFunction(req, root);
       }
 
-      // 6. Project files at natural URLs.
-      const fileRes = await serveProjectFile(normPath, root);
+      // 6. Project files at natural URLs, including extension asset mounts (§8.5) — that is what
+      // Lets a canvas preview show an image a content entry references relative to itself.
+      const fileRes = await serveProjectFile(normPath, root, await projectAssetMounts(root));
       if (fileRes) {
         return fileRes;
       }

package/src/resolve.ts

@@ -7,6 +7,8 @@ import { createRequire } from "node:module";
 import { containedPath } from "./net-guard.ts";
 import { buildProjectExtensionRegistry } from "@jxsuite/compiler/format-host";
 import { loadProjectSections } from "@jxsuite/compiler/project-sections";
+import { loadAssetMounts } from "@jxsuite/compiler/asset-mounts";
+import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { DynamicClass } from "@jxsuite/runtime/types";
 import type { JxClassDef, ProjectConfig } from "@jxsuite/schema/types";
 
@@ -53,7 +55,10 @@ function isImportable(p: string, root: string, activeProjectRoot: string | null)
 }
 
 /** Per-project context cache, invalidated when project.json changes on disk. */
-const projectContextCache = new Map<string, { mtime: number; context: Record<string, unknown> }>();
+const projectContextCache = new Map<
+  string,
+  { mtime: number; context: Record<string, unknown>; mounts: AssetMount[] }
+>();
 
 /**
  * Lazy-load project context (project.json + extension-loaded sections) for class instantiation.
@@ -64,6 +69,12 @@ const projectContextCache = new Map<string, { mtime: number; context: Record<str
  * @returns {Promise<Record<string, unknown> | null>} `{ config, root, ...sections }` or null
  */
 async function loadProjectContext(projectRoot: string) {
+  const entry = await loadProjectEntry(projectRoot);
+  return entry?.context ?? null;
+}
+
+/** Load (or reuse) the cached project context plus its extension asset mounts. */
+async function loadProjectEntry(projectRoot: string) {
   const projectJsonPath = resolve(projectRoot, "project.json");
   if (!existsSync(projectJsonPath)) {
     return null;
@@ -72,19 +83,33 @@ async function loadProjectContext(projectRoot: string) {
     const { mtimeMs } = statSync(projectJsonPath);
     const cached = projectContextCache.get(projectRoot);
     if (cached && cached.mtime === mtimeMs) {
-      return cached.context;
+      return cached;
     }
     const config = JSON.parse(readFileSync(projectJsonPath, "utf8")) as ProjectConfig;
     const registry = await buildProjectExtensionRegistry(projectRoot, config);
     const sections = await loadProjectSections(projectRoot, config, registry);
+    const { mounts } = await loadAssetMounts(registry, config, projectRoot);
     const context = { config, root: projectRoot, ...sections };
-    projectContextCache.set(projectRoot, { context, mtime: mtimeMs });
-    return context;
+    const entry = { context, mounts, mtime: mtimeMs };
+    projectContextCache.set(projectRoot, entry);
+    return entry;
   } catch {
     return null;
   }
 }
 
+/**
+ * Extension asset mounts for a project (specs/extensions.md §8.5) — the directories the dev server
+ * serves at their site URLs, so content-relative images resolve exactly as they will once built.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<AssetMount[]>} Mounts, or an empty list when there is no project here
+ */
+export async function projectAssetMounts(projectRoot: string): Promise<AssetMount[]> {
+  const entry = await loadProjectEntry(projectRoot);
+  return entry?.mounts ?? [];
+}
+
 /**
  * Handle POST /**jx_resolve** — proxy $prototype + $src entries.
  *

package/src/server.ts

@@ -13,14 +13,24 @@
  *   proxying, and studio filesystem integration as a single createDevServer() call.
  */
 
-import { join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { buildAll } from "./build.ts";
 import { createCollabRegistry } from "./collab.ts";
 import { createWatcher, injectSSE } from "./watch.ts";
 import { handleJxMounts } from "./jx-mounts.ts";
-import { handleResolve, handleServerFunction } from "./resolve.ts";
-import { assertAccessible, handleStudioApi } from "./studio-api.ts";
-import { containedPath, decodeAndNormalizePath, originHostGate } from "./net-guard.ts";
+import { handleResolve, handleServerFunction, projectAssetMounts } from "./resolve.ts";
+import {
+  assertAccessible,
+  assertCreatableParent,
+  handleStudioApi,
+  isOwnedProjectDir,
+} from "./studio-api.ts";
+import {
+  containedPath,
+  decodeAndNormalizePath,
+  originHostGate,
+  serveProjectFile,
+} from "./net-guard.ts";
 import { handleCodeApi } from "./code-api.ts";
 import { handleAiApi } from "./ai-api.ts";
 import { handleImportApi } from "./import-api.ts";
@@ -212,6 +222,14 @@ export async function createDevServer(options: {
   }
   const absRoot = resolve(root);
 
+  /**
+   * Projects created through Studio's New Project modal, which land wherever the user pointed the
+   * Location field — normally outside `absRoot`. Remembering them lets the very next
+   * `/__studio/activate` open what was just created without widening the filesystem API to
+   * arbitrary directories.
+   */
+  const createdRoots: string[] = [];
+
   // ─── Build pipeline ─────────────────────────────────────────────────────────
 
   if (builds.length > 0) {
@@ -326,8 +344,10 @@ export async function createDevServer(options: {
         }
 
         // Activate project — tells the server which project root to use for static file fallback.
-        // Contain the requested root: it must be under absRoot or an explicitly allowed root, so a
-        // Hostile activate cannot widen the filesystem API to arbitrary directories.
+        // Contain the requested root: it must be under absRoot, an explicitly allowed root, a
+        // Project this server just created, or an existing project of the account's own
+        // (`isOwnedProjectDir`), so a hostile activate cannot widen the filesystem API to arbitrary
+        // Directories.
         if (path === "/__studio/activate" && req.method === "POST") {
           const body = (await req.json()) as { root?: string };
           const raw = body.root || null;
@@ -338,7 +358,9 @@ export async function createDevServer(options: {
           const requested = resolve(absRoot, raw);
           const permitted =
             containedPath(requested, absRoot) !== null ||
-            allowedRoots.some((allowed) => containedPath(requested, resolve(allowed)) !== null);
+            allowedRoots.some((allowed) => containedPath(requested, resolve(allowed)) !== null) ||
+            createdRoots.some((created) => containedPath(requested, created) !== null) ||
+            isOwnedProjectDir(requested);
           if (!permitted) {
             return Response.json({ ok: false, error: "root not permitted" }, { status: 403 });
           }
@@ -352,14 +374,26 @@ export async function createDevServer(options: {
           return aiRes;
         }
 
-        // AI-guided site import (/__studio/import-site) — NDJSON progress stream
+        // AI-guided site import (/__studio/import-site) — NDJSON progress stream. An ABSOLUTE
+        // Directory is a destination the user chose in the New Project modal, so it is vetted the
+        // Same way a create is (specs/server.md §4.2). A RELATIVE one predates that field and stays
+        // Contained to the server root — resolving it there and then widening the check to the
+        // Creatable roots would let "../escape" out.
         const importRes = await handleImportApi(req, url, {
           resolveDest: (dir) => {
+            if (isAbsolute(dir)) {
+              assertCreatableParent(dirname(dir), absRoot, allowedRoots);
+              createdRoots.push(dir);
+              return dir;
+            }
             const dest = resolve(absRoot, dir);
             assertAccessible(dest, absRoot, activeProjectRoot);
             return dest;
           },
-          toRoot: (dest) => relative(absRoot, dest).replaceAll("\\", "/"),
+          toRoot: (dest) =>
+            containedPath(dest, absRoot) === null
+              ? dest
+              : relative(absRoot, dest).replaceAll("\\", "/"),
         });
         if (importRes) {
           return importRes;
@@ -370,7 +404,10 @@ export async function createDevServer(options: {
           return codeRes;
         }
 
-        const res = await handleStudioApi(req, url, absRoot, activeProjectRoot);
+        const res = await handleStudioApi(req, url, absRoot, activeProjectRoot, {
+          allowedRoots,
+          onProjectCreated: (created) => createdRoots.push(created),
+        });
         if (res) {
           return res;
         }
@@ -403,6 +440,20 @@ export async function createDevServer(options: {
         }
       }
 
+      // Extension asset mounts (§8.5) publish directories that may sit outside the project root,
+      // Such as an external content source's co-located images. They resolve here exactly as they
+      // Will once the site is built, so dev and production render the same URLs.
+      if (activeProjectRoot) {
+        const mountRes = await serveProjectFile(
+          path,
+          activeProjectRoot,
+          await projectAssetMounts(activeProjectRoot),
+        );
+        if (mountRes) {
+          return new Response(mountRes.body, { headers: NO_CACHE });
+        }
+      }
+
       const rootSafe = containedPath(resolve(absRoot, `.${path}`), absRoot);
       const file = rootSafe ? Bun.file(rootSafe) : null;
       if (!file || !(await file.exists())) {

package/src/studio-api.ts

@@ -10,7 +10,9 @@
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { LOCATION_ID_FILE } from "@jxsuite/protocol/routes";
 import {
   buildExtensionsPayload,
   buildProjectExtensionRegistry,
@@ -175,6 +177,57 @@ export function assertAccessible(filePath: string, root: string, activeProjectRo
   throw new Error("Path outside project root");
 }
 
+/**
+ * Check that a NEW project may be scaffolded under `parent` (specs/server.md §4.2).
+ *
+ * Deliberately wider than {@link assertAccessible}: a new project is normally created _outside_ the
+ * server root — the whole point of the modal's Location field — so root containment cannot apply.
+ * What it still refuses is a destination the user did not name (relative paths) and anything
+ * outside the places a person keeps projects: the server root, any configured `allowedRoots`, and
+ * the account's home directory. That keeps a hostile page on the loopback origin from scaffolding
+ * into system paths while leaving every realistic location reachable.
+ *
+ * @param {string} parent
+ * @param {string} root
+ * @param {string[]} allowedRoots
+ */
+export function assertCreatableParent(parent: string, root: string, allowedRoots: string[] = []) {
+  if (!parent || !isAbsolute(parent)) {
+    throw new Error("Destination folder must be an absolute path");
+  }
+  const bases = [root, ...allowedRoots, homedir()].filter(Boolean);
+  if (bases.some((base) => containedPath(parent, resolve(base)) !== null)) {
+    return;
+  }
+  throw new Error(
+    "Destination folder is outside the permitted roots (the server root, an allowed root, or your home directory)",
+  );
+}
+
+/**
+ * True when `dir` is a Jx project this account already owns: an absolute directory holding a
+ * `project.json`, somewhere under the user's home directory (specs/server.md §4.2).
+ *
+ * Existing projects live outside the server root as a matter of course — the dev server serving
+ * this monorepo is not where anyone keeps their sites — so root containment alone would leave
+ * `?project=/abs/path`, the Open Project picker, and the recent-projects list unable to activate
+ * anything but a project inside the checkout. This admits those without opening the filesystem API
+ * to arbitrary directories: a hostile page on the loopback origin still cannot bind the server to
+ * `/etc` or another account's files, only to a project the account already has on disk.
+ *
+ * @param {string} dir
+ */
+export function isOwnedProjectDir(dir: string): boolean {
+  const home = homedir();
+  if (!home || !dir || !isAbsolute(dir)) {
+    return false;
+  }
+  if (containedPath(dir, resolve(home)) === null) {
+    return false;
+  }
+  return existsSync(resolve(dir, "project.json"));
+}
+
 const statusMap: Record<string, string> = {
   A: "A",
   C: "C",
@@ -253,6 +306,18 @@ export function parseGitStatus(out: string) {
   return { ahead, behind, branch, files };
 }
 
+/** Host hooks for the routes that reach outside the server root (project creation). */
+export interface StudioApiOptions {
+  /** Extra roots a new project may be created under, mirroring `createDevServer.allowedRoots`. */
+  allowedRoots?: string[];
+  /**
+   * Called with the absolute root of a project this API just created, so the host can permit a
+   * subsequent `/__studio/activate` on it — a project created outside the server root is otherwise
+   * unreachable by the very request that made it.
+   */
+  onProjectCreated?: (projectRoot: string) => void;
+}
+
 /**
  * Handle /__studio/* requests.
  *
@@ -260,6 +325,7 @@ export function parseGitStatus(out: string) {
  * @param {URL} url
  * @param {string} root
  * @param {string | null} [activeProjectRoot]
+ * @param {StudioApiOptions} [opts]
  * @returns {Promise<Response | null>}
  */
 export async function handleStudioApi(
@@ -267,6 +333,7 @@ export async function handleStudioApi(
   url: URL,
   root: string,
   activeProjectRoot: string | null = null,
+  opts: StudioApiOptions = {},
 ) {
   const path = url.pathname;
 
@@ -416,6 +483,74 @@ export async function handleStudioApi(
     }
   }
 
+  /*
+   * 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 Response.json({ error: "Missing or invalid name/id" }, { status: 400 });
+    }
+    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 Response.json({ error: errorMessage(error) }, { status: 500 });
+    }
+  }
+
   // Discover site projects — find all project.json files under root
   if (path === "/__studio/sites" && req.method === "GET") {
     try {
@@ -453,6 +588,7 @@ export async function handleStudioApi(
         url?: string;
         adapter?: "static" | "cloudflare-pages" | "cloudflare-workers" | "node" | "bun";
         directory?: string;
+        destination?: { kind?: string; parent?: string };
         starter?: string;
         template?: string;
         design?: DesignOptions;
@@ -463,6 +599,7 @@ export async function handleStudioApi(
         url: siteUrl,
         adapter,
         directory,
+        destination,
         starter,
         template,
         design,
@@ -470,12 +607,32 @@ export async function handleStudioApi(
       if (!name || !directory) {
         return Response.json({ error: "name and directory are required" }, { status: 400 });
       }
+      // The destination is the user's to choose (specs/server.md §4.2). Without one the project
+      // Would silently land under the server root — which, when the dev server is the jx checkout,
+      // Means scaffolding into the monorepo. Refuse instead of guessing.
+      if (destination?.kind !== "path" || !destination.parent) {
+        return Response.json({ error: "A destination folder is required." }, { status: 400 });
+      }
+      // `directory` names the project FOLDER, not a path: a separator or dot-segment would walk out
+      // Of the parent that was just vetted below, which is exactly what the vetting is for.
+      if (/[/\\]/.test(directory) || directory === "." || directory === "..") {
+        return Response.json(
+          { error: "Directory must be a folder name, not a path" },
+          { status: 400 },
+        );
+      }
       const { isTemplateId } = await import("@jxsuite/create/templates");
       if (template !== undefined && !isTemplateId(template)) {
         return Response.json({ error: `Unknown template: "${template}"` }, { status: 400 });
       }
-      const destPath = resolve(root, directory);
-      assertAccessible(destPath, root, activeProjectRoot);
+      // A bad destination is client input, so answer 400 rather than letting the guard's throw fall
+      // Through to the catch-all 500 below.
+      try {
+        assertCreatableParent(destination.parent, root, opts.allowedRoots);
+      } catch (error) {
+        return Response.json({ error: errorMessage(error) }, { status: 400 });
+      }
+      const destPath = resolve(destination.parent, directory);
 
       const { generateProject } = await import("@jxsuite/create/generate");
       await generateProject(destPath, {
@@ -491,8 +648,12 @@ export async function handleStudioApi(
       const config = JSON.parse(
         await readFile(resolve(destPath, "project.json"), "utf8"),
       ) as ProjectConfig;
-      const projectRoot = fwd(relative(root, destPath));
-      return Response.json({ config, root: projectRoot });
+      // 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.
+      const inRoot = containedPath(destPath, root) !== null;
+      opts.onProjectCreated?.(destPath);
+      return Response.json({ config, root: inRoot ? fwd(relative(root, destPath)) : destPath });
     } catch (error) {
       return Response.json({ error: errorMessage(error) }, { status: 500 });
     }