@jxsuite/server 0.33.0 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -15,7 +15,9 @@
   "exports": {
     ".": "./src/server.ts",
     "./ai-api": "./src/ai-api.ts",
+    "./import-api": "./src/import-api.ts",
     "./packages": "./src/packages.ts",
+    "./project-server": "./src/project-server.ts",
     "./refactor": "./src/refactor/index.ts",
     "./resolve": "./src/resolve.ts",
     "./types": "./src/types.ts"
@@ -29,11 +31,13 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/compiler": "^0.33.0",
-    "@jxsuite/create": "^0.33.0",
-    "@jxsuite/parser": "^0.33.0",
-    "@jxsuite/runtime": "^0.33.0",
-    "@jxsuite/schema": "^0.33.0",
+    "@jxsuite/compiler": "^0.34.1",
+    "@jxsuite/create": "^0.35.0",
+    "@jxsuite/import": "^0.35.0",
+    "@jxsuite/parser": "^0.35.0",
+    "@jxsuite/runtime": "^0.34.1",
+    "@jxsuite/schema": "^0.34.0",
+    "@jxsuite/starters": "^0.35.0",
     "chokidar": "^5.0.0",
     "zod": "^4.4.3"
   }

package/src/import-api.ts

@@ -0,0 +1,202 @@
+/**
+ * Import-api.ts — the AI-guided site-import endpoint for Jx Studio.
+ *
+ * Handles POST /__studio/import-site: runs @jxsuite/import's importSite pipeline in the backend
+ * (headless Chrome + filesystem) and streams progress back as NDJSON lines over the POST response —
+ * the same streaming-fetch transport the AI chat proxy uses, so every platform (dev server,
+ * Electrobun services server, Chromium loopback server) can mount it unchanged.
+ *
+ * Stream protocol (one JSON object per line):
+ *   {"type":"progress","phase":"...","message":"...","current":n,"total":n}
+ *   {"type":"heartbeat"}                       — keep-alives during silent phases
+ *   {"type":"done","root":"...","config":{…}}  — terminal success
+ *   {"type":"error","error":"..."}             — terminal failure
+ *
+ * LLM key flow (matches ai-api.ts): X-Api-Key / Authorization: Bearer header, falling back to the
+ * OPENAI_API_KEY env var; base URL from X-Api-Base-URL / OPENAI_BASE_URL. When AI component naming
+ * is requested but no key resolves, the import proceeds without the AI pass and emits a warning
+ * line instead of failing.
+ *
+ * @license MIT
+ */
+
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+export interface ImportApiOptions {
+  /**
+   * Validate and absolutize the request's destination directory. Must throw for paths the host does
+   * not allow (the endpoint writes files and drives a browser — never pass through unchecked).
+   */
+  resolveDest: (directory: string) => string;
+  /** Map the final absolute project dir onto the platform's project-root form (default identity). */
+  toRoot?: (destPath: string) => string;
+  /** Explicit browser binary for puppeteer (e.g. the desktop launcher's discovered Chromium). */
+  chromePath?: string;
+}
+
+interface ImportRequestBody {
+  url?: string;
+  directory?: string;
+  depth?: number;
+  maxPages?: number;
+  maxNodesPerPage?: number;
+  aiComponents?: boolean;
+  aiModel?: string;
+}
+
+/** Seconds between keep-alive lines while a phase is silent (browser launch is the longest gap). */
+const HEARTBEAT_INTERVAL_MS = 15_000;
+
+const MAX_DEPTH = 5;
+const MAX_PAGES = 100;
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, Math.trunc(value)));
+}
+
+function getAiConfig(req: Request): { apiKey: string | null; baseUrl: string | undefined } {
+  const authHeader = req.headers.get("Authorization") || "";
+  const apiKeyHeader = req.headers.get("X-Api-Key") || "";
+  const baseUrlHeader = req.headers.get("X-Api-Base-URL") || "";
+
+  let apiKey: string | null = null;
+  if (authHeader.startsWith("Bearer ")) {
+    apiKey = authHeader.slice(7).trim();
+  }
+  if (apiKeyHeader) {
+    apiKey = apiKeyHeader.trim();
+  }
+  if (!apiKey && process.env.OPENAI_API_KEY) {
+    apiKey = process.env.OPENAI_API_KEY;
+  }
+
+  const baseUrl = baseUrlHeader || process.env.OPENAI_BASE_URL || undefined;
+  return { apiKey, baseUrl };
+}
+
+/** Handle POST /__studio/import-site — run the import pipeline, streaming NDJSON progress. */
+async function handleImportSite(req: Request, opts: ImportApiOptions): Promise<Response> {
+  let body: ImportRequestBody;
+  try {
+    body = (await req.json()) as ImportRequestBody;
+  } catch {
+    return Response.json({ error: "Invalid JSON body" }, { status: 400 });
+  }
+
+  const { url, directory } = body;
+  if (!url || !directory) {
+    return Response.json({ error: "url and directory are required" }, { status: 400 });
+  }
+  if (!url.startsWith("http://") && !url.startsWith("https://")) {
+    return Response.json({ error: "url must start with http:// or https://" }, { status: 400 });
+  }
+
+  let destPath: string;
+  try {
+    destPath = opts.resolveDest(directory);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return Response.json({ error: message }, { status: 400 });
+  }
+
+  const depth = clamp(body.depth ?? 1, 0, MAX_DEPTH);
+  const maxPages = clamp(body.maxPages ?? 20, 1, MAX_PAGES);
+  const maxNodesPerPage = clamp(body.maxNodesPerPage ?? 5000, 100, 50_000);
+  const { apiKey, baseUrl } = getAiConfig(req);
+  const toRoot = opts.toRoot ?? ((p: string) => p);
+
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream({
+    async start(controller) {
+      let closed = false;
+      const writeLine = (obj: unknown) => {
+        if (closed) {
+          return;
+        }
+        try {
+          controller.enqueue(encoder.encode(`${JSON.stringify(obj)}\n`));
+        } catch {
+          closed = true;
+        }
+      };
+      const heartbeat = setInterval(() => writeLine({ type: "heartbeat" }), HEARTBEAT_INTERVAL_MS);
+
+      try {
+        // Loaded lazily so the server never pays for puppeteer unless an import runs.
+        const { importSite } = await import("@jxsuite/import/run");
+
+        let ai:
+          | false
+          | { apiKey: string; baseUrl?: string | undefined; model?: string | undefined } = false;
+        if (body.aiComponents) {
+          if (apiKey) {
+            ai = { apiKey, baseUrl, model: body.aiModel };
+          } else {
+            writeLine({
+              type: "progress",
+              phase: "ai",
+              message:
+                "⚠ AI component naming requested but no API key is configured — continuing with heuristic names",
+            });
+          }
+        }
+
+        const result = await importSite(
+          {
+            url,
+            outDir: destPath,
+            maxDepth: depth,
+            maxPages,
+            maxNodesPerPage,
+            ai,
+            signal: req.signal,
+            ...(opts.chromePath === undefined ? {} : { chromePath: opts.chromePath }),
+          },
+          (e) => writeLine({ type: "progress", ...e }),
+        );
+
+        const config = JSON.parse(
+          await readFile(resolve(result.outDir, "project.json"), "utf8"),
+        ) as Record<string, unknown>;
+        writeLine({ type: "done", root: toRoot(result.outDir), config });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        writeLine({ type: "error", error: message });
+      } finally {
+        clearInterval(heartbeat);
+        if (!closed) {
+          closed = true;
+          try {
+            controller.close();
+          } catch {
+            /* Already closed by a client abort. */
+          }
+        }
+      }
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "application/x-ndjson",
+      "Cache-Control": "no-cache",
+    },
+  });
+}
+
+/**
+ * Main handler for the import route.
+ *
+ * @returns Response if handled, null if the route doesn't match
+ */
+export async function handleImportApi(
+  req: Request,
+  url: URL,
+  opts: ImportApiOptions,
+): Promise<Response | null> {
+  if (url.pathname === "/__studio/import-site" && req.method === "POST") {
+    return handleImportSite(req, opts);
+  }
+  return null;
+}

package/src/project-server.ts

@@ -0,0 +1,434 @@
+/**
+ * Shared project server factory. Generalizes the chromium variant's ad-hoc in-process Bun.serve
+ * into one createProjectServer() used by the chromium desktop launcher (and, in Phase 7,
+ * electrobun).
+ *
+ * It serves three surfaces from a single loopback-bound Bun.serve:
+ *
+ * - The studio shell + canvas iframe doc + iframe bundle, under a non-colliding studio namespace (so
+ *   a project's own asset tree never collides);
+ * - Project files at their natural URLs (absolute-under-root, root-relative, and public/), each
+ *   contained against path traversal and symlink escape;
+ * - The canonical resolve routes (the jx-resolve and jx-server POST endpoints) plus the WS-RPC
+ *   dispatch, both gated by a per-server token.
+ *
+ * SECURITY MODEL (see the spec's SECURITY block):
+ *
+ * - Loopback bind (127.0.0.1) is the PRIMARY control: other local processes / LAN pages cannot read a
+ *   loopback page's location, so they cannot steal the URL token.
+ * - The token is the HARD gate on every privileged surface — the WS upgrade and the two HTTP resolve
+ *   routes (which both do dynamic import() and are therefore RCE-capable).
+ * - Origin/Host is BEST-EFFORT defense-in-depth: a loopback Origin host {127.0.0.1, localhost, ::1}
+ *   or an absent Origin is accepted; the privileged HTTP routes additionally reject a Host header
+ *   that is not loopback (anti-DNS-rebinding).
+ * - File reads and the project write-path are contained with a lexical relative() check plus a
+ *   realpath re-check (symlink containment).
+ */
+
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { realpathSync } from "node:fs";
+import { handleResolve, handleServerFunction } from "./resolve.ts";
+import { handleAiApi } from "./ai-api.ts";
+import { handleImportApi } from "./import-api.ts";
+import { resolveNpmPath } from "./server.ts";
+import type { ImportApiOptions } from "./import-api.ts";
+
+/** A resolved per-window session: its project root plus its RPC handler map. */
+export interface ProjectServerSession {
+  projectRoot: string | null;
+  handlers: Record<string, (params: unknown) => Promise<unknown>>;
+}
+
+export interface CreateProjectServerOptions {
+  /**
+   * Resolve the session for a given window id (the `win` query param / stashed socket data).
+   * chromium passes `() => defaultSession`; electrobun (Phase 7) swaps it for a per-window lookup.
+   * A missing/unknown window returns `null`, which the routes treat as a 404 fail-closed.
+   */
+  resolveSession: (winId: string | null) => ProjectServerSession | null;
+  /** Absolute dir holding the studio shell + canvas.html + dist/. */
+  studioDir: string;
+  /** Per-server RPC token. Defaults to a fresh random UUID. */
+  rpcToken?: string;
+  /** Bind hostname. Defaults to loopback 127.0.0.1. */
+  hostname?: string;
+  /** Bind port. Defaults to 0 (ephemeral). */
+  port?: number;
+  /**
+   * Enable the AI-guided site-import endpoint (POST `/__studio__/import-site`). Absent disables the
+   * route. It writes to the filesystem, so it is gated with the rpcToken like `/__jx_resolve__`.
+   */
+  importApi?: ImportApiOptions;
+}
+
+export interface ProjectServerHandle {
+  server: ReturnType<typeof Bun.serve>;
+  url: string;
+  wsUrl: string;
+  rpcToken: string;
+  canvasUrl: string;
+  stop: () => void;
+}
+
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+
+/** True when a hostname (no port) is a loopback host. Used for best-effort Origin/Host checks. */
+function isLoopbackHost(host: string | null | undefined): boolean {
+  if (!host) {
+    return false;
+  }
+  // Strip a trailing :port (but keep bracketed IPv6 intact for the literal set).
+  let h = host;
+  if (h.startsWith("[")) {
+    const end = h.indexOf("]");
+    h = end === -1 ? h : h.slice(0, end + 1);
+  } else {
+    const colon = h.indexOf(":");
+    if (colon !== -1) {
+      h = h.slice(0, colon);
+    }
+  }
+  return LOOPBACK_HOSTS.has(h.toLowerCase());
+}
+
+/**
+ * Best-effort loopback Origin/Host check (defense-in-depth, not the hard gate).
+ *
+ * Accept when the Origin's host is loopback OR Origin is absent (Bun-native / test clients send no
+ * Origin). Do NOT hardcode-match one literal origin — localhost and 127.0.0.1 are distinct origins,
+ * and a too-strict check would 403 legitimate clients.
+ */
+function originIsLoopbackOrAbsent(req: Request): boolean {
+  const origin = req.headers.get("origin");
+  if (!origin) {
+    return true;
+  }
+  try {
+    return isLoopbackHost(new URL(origin).hostname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reject a Host header that is present and NOT loopback (defeats DNS-rebinding, where Host is the
+ * attacker domain). An absent Host (Bun-native clients) is accepted.
+ */
+function hostIsLoopbackOrAbsent(req: Request): boolean {
+  const host = req.headers.get("host");
+  if (!host) {
+    return true;
+  }
+  return isLoopbackHost(host);
+}
+
+/** Normalize a path for cross-platform containment comparison (separators + case on Windows). */
+function normalizeForCompare(p: string): string {
+  const slashed = p.replaceAll("\\", "/");
+  return process.platform === "win32" ? slashed.toLowerCase() : slashed;
+}
+
+/**
+ * Contain `absPath` within `root`: a lexical relative() check followed by a realpath re-check so a
+ * symlink inside the tree cannot point outside it. Returns the (possibly realpath'd) absolute path
+ * when contained, or null otherwise. The caller must already have decoded the URL pathname.
+ */
+function containedPath(absPath: string, root: string): string | null {
+  // (1) Lexical containment.
+  const rel = relative(root, absPath);
+  if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    return null;
+  }
+  // (2) realpath BOTH and re-check the realpath is still under realRoot (symlink containment).
+  let realRoot: string;
+  let realPath: string;
+  try {
+    realRoot = realpathSync(root);
+  } catch {
+    // Root itself is unresolvable: fall back to lexical-only containment.
+    return absPath;
+  }
+  try {
+    realPath = realpathSync(absPath);
+  } catch {
+    // Target does not exist yet — lexical containment already passed; let the caller's existence
+    // Check decide. (Reads will 404; the write-path resolves its own parent separately.)
+    return absPath;
+  }
+  const nRoot = normalizeForCompare(realRoot);
+  const nPath = normalizeForCompare(realPath);
+  if (nPath === nRoot || nPath.startsWith(nRoot.endsWith("/") ? nRoot : `${nRoot}/`)) {
+    return realPath;
+  }
+  return null;
+}
+
+/**
+ * Serve a file under studioDir (or any root) if it both exists and is contained. Returns the
+ * Response, or null when missing/traversed (caller decides the fallthrough status).
+ */
+async function serveContained(absPath: string, root: string): Promise<Response | null> {
+  const safe = containedPath(absPath, root);
+  if (!safe) {
+    return null;
+  }
+  const file = Bun.file(safe);
+  if (await file.exists()) {
+    return new Response(file);
+  }
+  return null;
+}
+
+/**
+ * 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).
+ */
+async function serveProjectFile(decodedPath: string, root: string): Promise<Response | null> {
+  // 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.
+  const fsPath = decodedPath.startsWith("//")
+    ? decodedPath.slice(1)
+    : decodedPath.replace(/^\/([A-Za-z]:)/, "$1");
+
+  // 1. Absolute path that falls under the project root.
+  if (normalizeForCompare(fsPath).startsWith(normalizeForCompare(root))) {
+    const res = await serveContained(fsPath, root);
+    if (res) {
+      return res;
+    }
+  }
+
+  // 2. Root-relative.
+  const relRes = await serveContained(resolve(root, `.${decodedPath}`), root);
+  if (relRes) {
+    return relRes;
+  }
+
+  // 3. public/ subdirectory.
+  const pubRes = await serveContained(resolve(root, "public", `.${decodedPath}`), root);
+  if (pubRes) {
+    return pubRes;
+  }
+
+  return null;
+}
+
+/**
+ * Create and start a shared project server bound to loopback.
+ *
+ * @param options See {@link CreateProjectServerOptions}.
+ * @returns A handle with the bound url/wsUrl, the rpcToken, the canvas iframe URL, and stop().
+ */
+export function createProjectServer(options: CreateProjectServerOptions): ProjectServerHandle {
+  const {
+    resolveSession,
+    studioDir,
+    rpcToken = crypto.randomUUID(),
+    hostname = "127.0.0.1",
+    port = 0,
+  } = options;
+
+  // Bundle cache for npm bare specifiers (mirrors server.ts).
+  const bundleCache = new Map<string, string>();
+
+  const server = Bun.serve<{ winId: string | null }>({
+    hostname,
+    port,
+    // Keep SSE/AI streams alive (mirrors the dev server's generous idle timeout).
+    idleTimeout: 120,
+    async fetch(req, srv) {
+      const url = new URL(req.url);
+      // Decode the pathname ONCE, then run ALL containment on the decoded path. Reject a path that
+      // Still contains an encoded dot/slash after one decode (over-encoding bypass attempt).
+      let path: string;
+      try {
+        path = decodeURIComponent(url.pathname);
+      } catch {
+        return new Response("Bad request", { status: 400 });
+      }
+      if (/%2e|%2f/i.test(path)) {
+        return new Response("Not found", { status: 404 });
+      }
+      // Collapse runs of leading slashes to a single one. The natural-URL branch re-expands a POSIX
+      // //abs prefix explicitly, so a single leading slash here is the right normal form.
+      const normPath = path.replace(/^\/{2,}/, "/");
+
+      const winId = url.searchParams.get("win");
+
+      // 1. WebSocket upgrade — token + loopback Origin/Host are the hard gate.
+      const upgrade = req.headers.get("upgrade");
+      if (upgrade && upgrade.toLowerCase() === "websocket") {
+        const token = url.searchParams.get("token");
+        if (token !== rpcToken || !originIsLoopbackOrAbsent(req) || !hostIsLoopbackOrAbsent(req)) {
+          return new Response("Forbidden", { status: 403 });
+        }
+        if (srv.upgrade(req, { data: { winId } })) {
+          return;
+        }
+        return new Response("Upgrade failed", { status: 400 });
+      }
+
+      // 2. AI SSE — keep the existing handleAiApi behavior (rewrite the studio-ai prefix).
+      if (normPath.startsWith("/__studio__/ai/")) {
+        const aiUrl = new URL(req.url);
+        aiUrl.pathname = normPath.replace("/__studio__/ai/", "/__studio/ai/");
+        const aiResponse = await handleAiApi(req, aiUrl);
+        if (aiResponse) {
+          return aiResponse;
+        }
+      }
+
+      // 2b. AI-guided site import — writes to the filesystem and drives a browser, so token +
+      //     Loopback Origin/Host are the hard gate (same as the RCE-capable routes below).
+      if (normPath === "/__studio__/import-site" && req.method === "POST") {
+        const { importApi } = options;
+        if (!importApi) {
+          return new Response("Not found", { status: 404 });
+        }
+        const token = url.searchParams.get("token");
+        if (token !== rpcToken || !originIsLoopbackOrAbsent(req) || !hostIsLoopbackOrAbsent(req)) {
+          return new Response("Forbidden", { status: 403 });
+        }
+        const importUrl = new URL(req.url);
+        importUrl.pathname = "/__studio/import-site";
+        const importRes = await handleImportApi(req, importUrl, importApi);
+        if (importRes) {
+          return importRes;
+        }
+      }
+
+      // 3. Studio assets under the non-colliding /__studio__/ namespace.
+      if (normPath.startsWith("/__studio__/")) {
+        const assetRel = normPath.slice("/__studio__/".length);
+        const assetPath = resolve(studioDir, `.${sep}${assetRel}`);
+        const res = await serveContained(assetPath, studioDir);
+        if (res) {
+          // Never leak the tokened URL cross-origin via Referer, while keeping same-origin requests
+          // Normal. MUST be `same-origin`, not `no-referrer`: under `no-referrer` Chromium serializes
+          // The Origin header of the canvas iframe's own same-origin POSTs as `null` (Fetch spec
+          // Origin-serialization respects referrer policy), which fails originIsLoopbackOrAbsent and
+          // Self-403s /__jx_resolve__ + /__jx_server__ from the very document this server serves.
+          const headers = new Headers(res.headers);
+          headers.set("Referrer-Policy", "same-origin");
+          return new Response(res.body, { headers, status: res.status });
+        }
+        return new Response("Not found", { status: 404 });
+      }
+
+      // 4. Resolve the session (fail-closed).
+      const session = resolveSession(winId);
+      if (!session) {
+        return new Response("Unknown window", { status: 404 });
+      }
+      const root = session.projectRoot;
+      if (!root) {
+        return new Response("No project", { status: 404 });
+      }
+
+      // 5. Privileged HTTP routes (RCE-capable: dynamic import()). Gate with token + loopback
+      //    Origin/Host BEFORE dispatch.
+      if (
+        (normPath === "/__jx_resolve__" || normPath === "/__jx_server__") &&
+        req.method === "POST"
+      ) {
+        const token = url.searchParams.get("token");
+        if (token !== rpcToken || !originIsLoopbackOrAbsent(req) || !hostIsLoopbackOrAbsent(req)) {
+          return new Response("Forbidden", { status: 403 });
+        }
+        if (normPath === "/__jx_resolve__") {
+          return handleResolve(req, root, root);
+        }
+        return handleServerFunction(req, root);
+      }
+
+      // 6. Project files at natural URLs.
+      const fileRes = await serveProjectFile(normPath, root);
+      if (fileRes) {
+        return fileRes;
+      }
+
+      // 7. npm bare specifiers via node_modules (on-demand bundle, mirrors server.ts).
+      const resolved = resolveNpmPath(root, normPath);
+      if (resolved) {
+        if (!bundleCache.has(resolved)) {
+          try {
+            const result = await Bun.build({
+              entrypoints: [resolved],
+              format: "esm",
+              minify: false,
+            });
+            if (result.success && result.outputs.length > 0) {
+              bundleCache.set(resolved, await result.outputs[0]!.text());
+            }
+          } catch (error) {
+            console.error("Bundle failed for", resolved, error);
+          }
+        }
+        const bundled = bundleCache.get(resolved);
+        if (bundled) {
+          return new Response(bundled, {
+            headers: { "Content-Type": "application/javascript; charset=utf-8" },
+          });
+        }
+      }
+
+      return new Response("Not found", { status: 404 });
+    },
+
+    websocket: {
+      async message(ws, raw) {
+        let msg: { id: number; method: string; params?: unknown };
+        try {
+          msg = JSON.parse(raw as string) as { id: number; method: string; params?: unknown };
+        } catch {
+          ws.send(JSON.stringify({ error: "Invalid JSON", id: 0 }));
+          return;
+        }
+
+        // Re-resolve the session FRESH each message (fail-closed for Phase 7 multi-window).
+        const session = resolveSession(ws.data.winId);
+        if (!session) {
+          ws.send(JSON.stringify({ error: "Unknown window", id: msg.id }));
+          ws.close();
+          return;
+        }
+
+        const handler = session.handlers[msg.method];
+        if (!handler) {
+          ws.send(JSON.stringify({ error: `Unknown method: ${msg.method}`, id: msg.id }));
+          return;
+        }
+
+        try {
+          const result = await handler(msg.params);
+          ws.send(JSON.stringify({ id: msg.id, result: result ?? null }));
+        } catch (error: unknown) {
+          ws.send(
+            JSON.stringify({
+              error: error instanceof Error ? error.message : String(error),
+              id: msg.id,
+            }),
+          );
+        }
+      },
+    },
+  });
+
+  const boundHost = hostname.includes(":") ? `[${hostname}]` : hostname;
+  const url = `http://${boundHost}:${server.port}`;
+  const wsUrl = `ws://${boundHost}:${server.port}`;
+  const canvasUrl = `${url}/__studio__/canvas.html`;
+
+  return {
+    server,
+    url,
+    wsUrl,
+    rpcToken,
+    canvasUrl,
+    stop: () => {
+      void server.stop(true);
+    },
+  };
+}

package/src/server.ts

@@ -13,13 +13,14 @@
  *   proxying, and studio filesystem integration as a single createDevServer() call.
  */
 
-import { join, resolve } from "node:path";
+import { join, relative, resolve } from "node:path";
 import { buildAll } from "./build.ts";
 import { createWatcher, injectSSE } from "./watch.ts";
 import { handleResolve, handleServerFunction } from "./resolve.ts";
-import { handleStudioApi } from "./studio-api.ts";
+import { assertAccessible, handleStudioApi } from "./studio-api.ts";
 import { handleCodeApi } from "./code-api.ts";
 import { handleAiApi } from "./ai-api.ts";
+import { handleImportApi } from "./import-api.ts";
 import { existsSync, readFileSync } from "node:fs";
 
 /**
@@ -212,6 +213,14 @@ export async function createDevServer(options: {
   // Bundle cache for npm packages (bare specifier → bundled JS)
   const bundleCache = new Map<string, string>();
 
+  // Dev-server cache policy: always revalidate. Without any Cache-Control the browser HEURISTICALLY
+  // Caches responses (there are no validators either), so a plain reload can serve a stale
+  // Studio.js/canvas bundle — which shows up as half-updated UI after a rebuild (the iframe assets
+  // Are query-cache-busted per mount, the parent bundle is not).
+  const NO_CACHE = { "Cache-Control": "no-cache" };
+  const fileResponse = (file: ReturnType<typeof Bun.file>) =>
+    new Response(file, { headers: NO_CACHE });
+
   // Active studio project root (set via /__studio/activate, used for static file fallback)
   let activeProjectRoot: string | null = null;
 
@@ -259,6 +268,19 @@ export async function createDevServer(options: {
           return aiRes;
         }
 
+        // AI-guided site import (/__studio/import-site) — NDJSON progress stream
+        const importRes = await handleImportApi(req, url, {
+          resolveDest: (dir) => {
+            const dest = resolve(absRoot, dir);
+            assertAccessible(dest, absRoot, activeProjectRoot);
+            return dest;
+          },
+          toRoot: (dest) => relative(absRoot, dest).replaceAll("\\", "/"),
+        });
+        if (importRes) {
+          return importRes;
+        }
+
         const codeRes = await handleCodeApi(req, url);
         if (codeRes) {
           return codeRes;
@@ -289,7 +311,7 @@ export async function createDevServer(options: {
       if (activeProjectRoot && normSep(fsPath).startsWith(normSep(activeProjectRoot))) {
         const file = Bun.file(fsPath);
         if (await file.exists()) {
-          return new Response(file);
+          return fileResponse(file);
         }
       }
 
@@ -299,12 +321,12 @@ export async function createDevServer(options: {
         if (activeProjectRoot) {
           const projectFile = Bun.file(resolve(activeProjectRoot, `.${path}`));
           if (await projectFile.exists()) {
-            return new Response(projectFile);
+            return fileResponse(projectFile);
           }
           // Mirror production: public/ contents are served at root
           const publicFile = Bun.file(resolve(activeProjectRoot, "public", `.${path}`));
           if (await publicFile.exists()) {
-            return new Response(publicFile);
+            return fileResponse(publicFile);
           }
         }
 
@@ -331,6 +353,7 @@ export async function createDevServer(options: {
           if (bundled) {
             return new Response(bundled, {
               headers: {
+                ...NO_CACHE,
                 "Content-Type": "application/javascript; charset=utf-8",
               },
             });
@@ -346,11 +369,11 @@ export async function createDevServer(options: {
       if (handleSSE && path.endsWith(".html") && !path.startsWith("/packages/studio/")) {
         const html = await file.text();
         return new Response(injectSSE(html), {
-          headers: { "Content-Type": "text/html; charset=utf-8" },
+          headers: { ...NO_CACHE, "Content-Type": "text/html; charset=utf-8" },
         });
       }
 
-      return new Response(file);
+      return fileResponse(file);
     },
 
     port,

package/src/studio-api.ts

@@ -22,6 +22,7 @@ import {
 } from "./packages.ts";
 import type { FormatRegistry } from "@jxsuite/schema/format-registry";
 import type { ClassJsonDef } from "./types.ts";
+import type { DesignOptions } from "@jxsuite/create/generate";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 
 /** Normalise a path to forward slashes (Windows `path` module returns backslashes). */
@@ -150,7 +151,7 @@ async function getFormatRegistry(projectRoot: string): Promise<FormatRegistry> {
  * @param {string} root
  * @param {string | null} activeProjectRoot
  */
-function assertAccessible(filePath: string, root: string, activeProjectRoot: string | null) {
+export function assertAccessible(filePath: string, root: string, activeProjectRoot: string | null) {
   const rel = relative(root, filePath);
   if (!rel.startsWith("..") && !rel.startsWith("/")) {
     return;
@@ -331,9 +332,21 @@ export async function handleStudioApi(
       return Response.json({ error: "Missing path param" }, { status: 400 });
     }
     try {
-      // Walk up from file's directory looking for project.json
-      const absFile = expandTilde(filePath);
-      let dir = dirname(absFile);
+      // Walk up looking for project.json. Accept a directory (e.g. the project root itself, as
+      // Deep links like ?project=/abs/my-site pass) by starting the walk AT the directory and
+      // Treating its project.json as the target file, so callers land on the home page.
+      let absFile = expandTilde(filePath);
+      let dir: string;
+      let isDir = false;
+      try {
+        isDir = statSync(absFile).isDirectory();
+      } catch {}
+      if (isDir) {
+        dir = absFile;
+        absFile = resolve(absFile, "project.json");
+      } else {
+        dir = dirname(absFile);
+      }
       while (dir) {
         const candidate = resolve(dir, "project.json");
         if (existsSync(candidate)) {
@@ -424,11 +437,27 @@ export async function handleStudioApi(
         url?: string;
         adapter?: "static" | "cloudflare-pages" | "cloudflare-workers" | "node" | "bun";
         directory?: string;
+        starter?: string;
+        template?: string;
+        design?: DesignOptions;
       };
-      const { name, description, url: siteUrl, adapter, directory } = body;
+      const {
+        name,
+        description,
+        url: siteUrl,
+        adapter,
+        directory,
+        starter,
+        template,
+        design,
+      } = body;
       if (!name || !directory) {
         return Response.json({ error: "name and directory are required" }, { 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);
 
@@ -438,6 +467,9 @@ export async function handleStudioApi(
         ...(adapter !== undefined ? { adapter } : {}),
         ...(description !== undefined ? { description } : {}),
         ...(siteUrl !== undefined ? { url: siteUrl } : {}),
+        ...(starter !== undefined ? { starter } : {}),
+        ...(template !== undefined && isTemplateId(template) ? { template } : {}),
+        ...(design !== undefined ? { design } : {}),
       });
 
       const config = JSON.parse(
@@ -450,6 +482,16 @@ export async function handleStudioApi(
     }
   }
 
+  // List available starter templates (for the New Project picker)
+  if (path === "/__studio/starters" && req.method === "GET") {
+    try {
+      const { listStarters } = await import("@jxsuite/starters");
+      return Response.json(listStarters());
+    } catch (error) {
+      return Response.json({ error: errorMessage(error) }, { status: 500 });
+    }
+  }
+
   // List files
   if (path === "/__studio/files" && req.method === "GET") {
     const dir = url.searchParams.get("dir") || activeProjectRoot || root;