@jxsuite/server 4.4.5 → 4.5.1

package/src/resolve.ts

@@ -1,44 +1,126 @@
 /** Resolve.js — Generic $src module proxy + timing: "server" function proxy */
 
 import { siteBasePath } from "@jxsuite/schema/asset-paths";
-import { dirname, relative, resolve } from "node:path";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { errorMessage, parseClassDef } from "@jxsuite/schema/parse";
+import { isFunction, isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
+import { projectDevEnv } from "./dev-vars.ts";
 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";
+import type { DynamicMethod } from "@jxsuite/runtime/types";
+import type { ProjectSections } from "@jxsuite/compiler/project-sections";
+import type {
+  JsonObject,
+  JsonPrimitive,
+  JsonValue,
+  JxClassCtorDef,
+  JxClassDef,
+  ProjectConfig,
+} from "@jxsuite/schema/types";
+import type { ProjectDevEnv } from "./dev-vars.ts";
 import { problem } from "./problem.ts";
 
-interface ModuleNamespace {
-  default?: Record<string, unknown>;
-  [key: string]: unknown;
+/**
+ * Any value a module exports, as the proxies see it before they check it. Nothing about an export
+ * is known statically (it is project or package code loaded by path), so the type only says what
+ * reading it can yield: a function, an object whose members can be read in turn, or a primitive.
+ */
+type ExportedValue =
+  | ExportedFunction
+  | ExportedConstructor
+  | ExportedObject
+  | JsonPrimitive
+  | bigint
+  | symbol
+  | undefined;
+
+/** A function export as it is called. Its real signature is the contract of whoever calls it. */
+type ExportedFunction = (...args: never[]) => ExportedValue | Promise<ExportedValue>;
+
+/** A class export as it is constructed. Its real signature is the contract of whoever builds it. */
+type ExportedConstructor = new (...args: never[]) => object;
+
+/** A non-primitive export. Reading any member of it yields another {@link ExportedValue}. */
+interface ExportedObject {
+  readonly [member: string]: ExportedValue;
+}
+
+/**
+ * A loaded module's namespace object. `default` is read as an object because the proxies only ever
+ * read a named member off it, which is defined for any non-nullish value.
+ */
+interface ModuleNamespace extends ExportedObject {
+  readonly default?: ExportedObject;
+}
+
+/**
+ * The project context a class receives as `config._project`: the config, the root, and every
+ * extension-loaded section under its section key (the compiler's `_project` shape).
+ */
+type ProjectContext = ProjectSections & { config: ProjectConfig; root: string };
+
+/** A cached project context, its extension asset mounts, and the `project.json` mtime it is for. */
+interface ProjectEntry {
+  mtime: number;
+  context: ProjectContext;
+  mounts: AssetMount[];
+}
+
+/** A value the resolve proxy hands a class constructor under one config key. */
+type ConfigValue = JsonValue | ProjectContext | undefined;
+
+/**
+ * The `config` a class is constructed with: the request's own members, plus the injected project
+ * context and an empty document scope.
+ */
+interface ResolveConfig {
+  [key: string]: ConfigValue;
+  _project?: ProjectContext;
 }
 
-interface ClassInstance {
-  resolve?: () => unknown;
-  value?: unknown;
-  [key: string]: unknown;
+/** A class `/__jx_resolve__` constructs from an `$implementation` module. */
+type ResolvableClass = new (config: ResolveConfig) => ResolvableInstance;
+
+/**
+ * What the resolve proxy reads off a constructed instance, in the order spec.md §12.3 fixes:
+ * `resolve()` when it is a method, else `value` when the instance has one, else the instance.
+ */
+interface ResolvableInstance {
+  readonly resolve?: ExportedValue;
+  readonly value?: ExportedValue;
 }
 
+/**
+ * What a server function may answer: a JSON value, sent as the response body (`undefined` →
+ * `null`).
+ */
+type ServerFunctionResult = JsonValue | undefined;
+
+/** A `timing: "server"` function: `fn(args, env)`, the production contract the compiler emits. */
+type ServerFunction = (
+  args: JsonObject,
+  env: ProjectDevEnv,
+) => ServerFunctionResult | Promise<ServerFunctionResult>;
+
 interface ResolveBody {
   $src?: string;
   $prototype?: string;
   $export?: string;
   $base?: string;
-  [key: string]: unknown;
+  [key: string]: JsonValue | undefined;
 }
 
 interface ServerFunctionBody {
   $src?: string;
   $export?: string;
   $base?: string;
-  arguments?: Record<string, unknown>;
-  [key: string]: unknown;
+  arguments?: JsonObject;
+  [key: string]: JsonValue | undefined;
 }
 
 /**
@@ -56,11 +138,43 @@ function isImportable(p: string, root: string, activeProjectRoot: string | null)
   return false;
 }
 
+/**
+ * The directory holding the document a `$base` names, which a relative `$src` resolves against.
+ *
+ * Hosts spell a base two ways. A page served at a site URL (`jx dev`, the live preview) names a
+ * path under `root`, and a single leading slash always means that, even when the path would also
+ * read as an absolute one: a root `/app` may hold a site directory `app/`. Studio's canvas
+ * addresses a project by its absolute filesystem path instead (`documentBase` in
+ * `packages/studio`), so its base arrives as `//abs/project/pages/x.json`, or
+ * `/C:/project/pages/x.json` on Windows: the spelling the static file lanes map back to the file
+ * (`serveProjectFile`). A `file:` URL's path is a filesystem path too. Those spellings name the
+ * path itself only when it lies under `root` or the active project, so any other path keeps meaning
+ * a site URL. The pathname is percent-decoded first, because a URL encodes a space in a directory
+ * name and the filesystem does not.
+ *
+ * @param {string} $base - The document URL the runtime sent
+ * @param {string} root - The root a site URL names a path under
+ * @param {string} projectRoot - The active project, which may sit outside `root`
+ * @returns {string} An absolute directory
+ */
+function baseDirectory($base: string, root: string, projectRoot: string): string {
+  const url = new URL($base);
+  const pathname = decodeURIComponent(url.pathname);
+  const urlDir = pathname.slice(0, pathname.lastIndexOf("/") + 1);
+  const spellsPath = urlDir.startsWith("//") || /^\/[A-Za-z]:/.test(urlDir);
+  const fsDir = spellsPath ? urlDir.slice(1) : url.protocol === "file:" ? urlDir : null;
+  if (
+    fsDir !== null &&
+    isAbsolute(fsDir) &&
+    (containedPath(fsDir, root) !== null || containedPath(fsDir, projectRoot) !== null)
+  ) {
+    return resolve(fsDir);
+  }
+  return resolve(root, `.${urlDir}`);
+}
+
 /** Per-project context cache, invalidated when project.json changes on disk. */
-const projectContextCache = new Map<
-  string,
-  { mtime: number; context: Record<string, unknown>; mounts: AssetMount[] }
->();
+const projectContextCache = new Map<string, ProjectEntry>();
 
 /**
  * Lazy-load project context (project.json + extension-loaded sections) for class instantiation.
@@ -68,15 +182,15 @@ const projectContextCache = new Map<
  * `_project` shape.
  *
  * @param {string} projectRoot
- * @returns {Promise<Record<string, unknown> | null>} `{ config, root, ...sections }` or null
+ * @returns {Promise<ProjectContext | null>} `{ config, root, ...sections }` or null
  */
-async function loadProjectContext(projectRoot: string) {
+async function loadProjectContext(projectRoot: string): Promise<ProjectContext | null> {
   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) {
+async function loadProjectEntry(projectRoot: string): Promise<ProjectEntry | null> {
   const projectJsonPath = resolve(projectRoot, "project.json");
   if (!existsSync(projectJsonPath)) {
     return null;
@@ -87,12 +201,15 @@ async function loadProjectEntry(projectRoot: string) {
     if (cached && cached.mtime === mtimeMs) {
       return cached;
     }
+    /* SAFETY: trust boundary. project.json is the project's own config file, which the editor
+       and `jx validate` hold to its per-project schema. Any failure reading it below is caught
+       here and answers "no project context". */
     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 };
-    const entry = { context, mounts, mtime: mtimeMs };
+    const context: ProjectContext = { config, root: projectRoot, ...sections };
+    const entry: ProjectEntry = { context, mounts, mtime: mtimeMs };
     projectContextCache.set(projectRoot, entry);
     return entry;
   } catch {
@@ -112,8 +229,7 @@ async function loadProjectEntry(projectRoot: string) {
  */
 export async function projectSiteBase(projectRoot: string): Promise<string> {
   const entry = await loadProjectEntry(projectRoot);
-  const config = entry?.context.config as ProjectConfig | undefined;
-  return siteBasePath(config?.url);
+  return siteBasePath(entry?.context.config.url);
 }
 
 /**
@@ -142,12 +258,16 @@ export async function handleResolve(
 ) {
   let body: ResolveBody;
   try {
+    /* SAFETY: trust boundary. The body parsed as JSON, and this route's caller is the runtime's
+       `$prototype` proxy, which posts the entry's own JSON members with string `$`-keys. A body
+       that breaks that throws in this handler, as it always has. */
     body = (await req.json()) as ResolveBody;
   } catch {
     return problem("invalidRequest", "Invalid JSON body");
   }
 
-  const { $src, $prototype, $export: xport, $base, ...config } = body;
+  const { $src, $prototype, $export: xport, $base, ...members } = body;
+  const config: ResolveConfig = members;
   if (!$src) {
     return problem("invalidRequest", "Missing $src");
   }
@@ -192,7 +312,7 @@ export async function handleResolve(
     const docDir = docUrlPath.slice(0, docUrlPath.lastIndexOf("/") + 1);
     const docAbsDir = resolve(root, `.${docDir}`);
     for (const [k, v] of Object.entries(config)) {
-      if (typeof v === "string" && (v.startsWith("./") || v.startsWith("../"))) {
+      if (isString(v) && (v.startsWith("./") || v.startsWith("../"))) {
         config[k] = `./${relative(process.cwd(), resolve(docAbsDir, v)).split("\\").join("/")}`;
       }
     }
@@ -221,38 +341,25 @@ export async function handleResolve(
           return problem("pathOutsideProject", "$implementation escapes the project root");
         }
         const exportName = xport ?? classDef.title ?? $prototype;
-        const mod = (await import(implPath)) as ModuleNamespace;
+        const mod = await importModule(implPath);
         const ExportedClass =
           exportName === undefined ? undefined : (mod[exportName] ?? mod.default?.[exportName]);
-        if (typeof ExportedClass !== "function") {
+        if (!isExportedFunction(ExportedClass)) {
           return new Response(`Export "${exportName}" not found in "${classDef.$implementation}"`, {
             status: 500,
           });
         }
-        const ClassCtor = ExportedClass as new (config: unknown) => ClassInstance;
-        const instance = new ClassCtor(config);
-        const value =
-          typeof instance.resolve === "function"
-            ? await instance.resolve()
-            : "value" in instance
-              ? instance.value
-              : instance;
-        return Response.json(value);
+        /* SAFETY: trust boundary. A class file's `$implementation` names the module exporting the
+           class it describes, whose constructor takes one config object (spec.md §12.3, §12.4).
+           It is a function, checked above; one that is not constructible throws here, inside the
+           try whose catch answers a problem. */
+        const ClassCtor = ExportedClass as ResolvableClass;
+        return Response.json(await instanceResult(new ClassCtor(config)));
       }
 
       // Self-contained: construct class from schema
       const DynClass = classFromSchema(classDef);
-      const instance = new DynClass(config) as {
-        resolve?: () => unknown;
-        value?: unknown;
-      };
-      const value =
-        typeof instance.resolve === "function"
-          ? await instance.resolve()
-          : "value" in instance
-            ? instance.value
-            : instance;
-      return Response.json(value);
+      return Response.json(await instanceResult(new DynClass(config)));
     } catch (error) {
       return problem("internalError", errorMessage(error));
     }
@@ -267,15 +374,26 @@ export async function handleResolve(
 }
 
 /**
- * Handle POST /**jx_server** — proxy timing: "server" function calls. In dev mode, the runtime
- * sends these instead of hitting the production Hono handler.
+ * Handle POST `/__jx_server__` — proxy timing: "server" function calls. It is the only way an
+ * interpreting runtime calls a server function (spec.md §11.4): the runtime never imports the
+ * module in the browser, it posts the call here, and the function runs server-side with `env`.
+ *
+ * A relative `$src` resolves against the directory of the document `$base` names (`baseDirectory`):
+ * a site URL's path under `root`, or the absolute path Studio's canvas sends. The imported module
+ * stays cached for as long as the host runs, so an edit to it takes effect when the host restarts.
  *
  * @param {Request} req
- * @param {string} root
+ * @param {string} root - The root a site-URL `$base`, or a `$src` without one, resolves under
+ * @param {string} [projectRoot] - The active project: the function's `env` carries its `.dev.vars`,
+ *   and a module under it is importable as one under `root` is. `root` when omitted
  */
-export async function handleServerFunction(req: Request, root: string) {
+export async function handleServerFunction(req: Request, root: string, projectRoot = root) {
   let body: ServerFunctionBody;
   try {
+    /* SAFETY: trust boundary. The body parsed as JSON, and this route's caller is the runtime's
+       server-function proxy, which posts `{ $src, $export, $base, arguments }` with string
+       `$`-keys and an object of arguments. A body that breaks that throws in this handler, as it
+       always has. */
     body = (await req.json()) as ServerFunctionBody;
   } catch {
     return problem("invalidRequest", "Invalid JSON body");
@@ -288,24 +406,20 @@ export async function handleServerFunction(req: Request, root: string) {
 
   let moduleAbsPath;
   try {
-    if ($base) {
-      const docUrlPath = new URL($base).pathname;
-      const docDir = docUrlPath.slice(0, docUrlPath.lastIndexOf("/") + 1);
-      moduleAbsPath = resolve(resolve(root, `.${docDir}`), $src);
-    } else {
-      moduleAbsPath = resolve(root, $src);
-    }
+    moduleAbsPath = $base
+      ? resolve(baseDirectory($base, root, projectRoot), $src)
+      : resolve(root, $src);
   } catch (error) {
     return problem("invalidRequest", `Cannot resolve $src: ${errorMessage(error)}`);
   }
 
-  if (!isImportable(moduleAbsPath, root, null)) {
+  if (!isImportable(moduleAbsPath, root, projectRoot)) {
     return new Response(`$src "${$src}" escapes the project root`, { status: 403 });
   }
 
   let mod: ModuleNamespace;
   try {
-    mod = (await import(moduleAbsPath)) as ModuleNamespace;
+    mod = await importModule(moduleAbsPath);
   } catch (error) {
     return new Response(`Failed to import "${$src}": ${errorMessage(error)}`, {
       status: 500,
@@ -313,25 +427,63 @@ export async function handleServerFunction(req: Request, root: string) {
   }
 
   const fn = mod[xport] ?? mod.default?.[xport];
-  if (typeof fn !== "function") {
+  if (!isExportedFunction(fn)) {
     return new Response(`Export "${xport}" not found in "${$src}"`, {
       status: 500,
     });
   }
 
   try {
-    // Match the production contract `fn(args, env)` (compiler emits `fn(args, c.env)`): the dev
-    // Proxy runs server-side, so `process.env` is the analogous environment binding.
-    const result = await (fn as (args: Record<string, unknown>, env: unknown) => unknown)(
-      args,
-      process.env,
-    );
+    /* Match the production contract `fn(args, env)` (compiler emits `fn(args, c.env)`): the dev
+       proxy runs server-side, so its `env` is the extension mounts' own, `process.env` merged under
+       the project's `.dev.vars` plus `JX_PROJECT_ROOT` (server.md §3.3). */
+    /* SAFETY: trust boundary. A `timing: "server"` module exports its functions with the signature
+       `fn(args, env)` and a JSON answer (spec.md §11.4); this one is a function, checked above. */
+    const serverFn = fn as ServerFunction;
+    const result = await serverFn(args, projectDevEnv(projectRoot));
     return Response.json(result ?? null);
   } catch (error) {
     return problem("internalError", errorMessage(error));
   }
 }
 
+/**
+ * Whether an export is a function. Every function is callable, constructible or both, which is all
+ * the narrowed type claims; which of the two a proxy needs is that proxy's own contract.
+ */
+function isExportedFunction(value: ExportedValue): value is ExportedFunction | ExportedConstructor {
+  return isFunction(value);
+}
+
+/** Import a module by absolute path, as its namespace object. */
+async function importModule(path: string): Promise<ModuleNamespace> {
+  /* SAFETY: a dynamic import() resolves to the module's namespace object, whose own members are its
+     exports; every member the proxies read off one is checked to be a function before use. */
+  return (await import(path)) as ModuleNamespace;
+}
+
+/** What a constructed class answers with: its `resolve()` result, else its `value`, else itself. */
+async function instanceResult(
+  instance: ResolvableInstance,
+): Promise<ExportedValue | ResolvableInstance> {
+  if (isFunction(instance.resolve)) {
+    return await instance.resolve();
+  }
+  return "value" in instance ? instance.value : instance;
+}
+
+/**
+ * Whether a class document's `$defs.constructor` is its own constructor definition, rather than the
+ * `Object.prototype.constructor` function every object parsed from JSON inherits.
+ *
+ * @param rawCtor What `$defs.constructor` reads as
+ */
+function isCtorDef(
+  rawCtor: NonNullable<JxClassDef["$defs"]>["constructor"],
+): rawCtor is JxClassCtorDef {
+  return isNonNullObject(rawCtor);
+}
+
 /**
  * Dynamically construct a class from a .class.json schema definition. Server-side variant — no
  * private field limitations.
@@ -340,26 +492,24 @@ export async function handleServerFunction(req: Request, root: string) {
  */
 function classFromSchema(classDef: JxClassDef) {
   const fields = classDef.$defs?.fields ?? {};
-  // JSON objects inherit Object.prototype.constructor — only an own object value counts.
   const rawCtor = classDef.$defs?.constructor;
-  const ctor = typeof rawCtor === "object" ? rawCtor : undefined;
+  const ctor = isCtorDef(rawCtor) ? rawCtor : undefined;
   const methods = classDef.$defs?.methods ?? {};
 
   // oxlint-disable-next-line typescript/no-extraneous-class -- methods are attached to the prototype dynamically below
   class DynClass {
-    constructor(config = {}) {
-      const self = this as Record<string, unknown>;
-      const cfg = config as Record<string, unknown>;
+    constructor(config: ResolveConfig = {}) {
+      // Each field lands as an own property by assignment, as `this[id] = value` would put it.
       for (const [key, field] of Object.entries(fields)) {
         const id = field.identifier ?? key;
-        if (cfg[id] !== undefined) {
-          self[id] = cfg[id];
+        if (config[id] !== undefined) {
+          Object.assign(this, { [id]: config[id] });
         } else if (field.initializer !== undefined) {
-          self[id] = field.initializer;
+          Object.assign(this, { [id]: field.initializer });
         } else if (field.default !== undefined) {
-          self[id] = structuredClone(field.default);
+          Object.assign(this, { [id]: structuredClone(field.default) });
         } else {
-          self[id] = null;
+          Object.assign(this, { [id]: null });
         }
       }
       if (ctor?.body) {
@@ -376,27 +526,29 @@ function classFromSchema(classDef: JxClassDef) {
         return p.$ref.split("/").pop() ?? "arg";
       }
       const n = p.identifier ?? p.name;
-      return typeof n === "string" ? n : "arg";
+      return isString(n) ? n : "arg";
     });
     const bodyStr = Array.isArray(method.body) ? method.body.join("\n") : (method.body ?? "");
 
     if (method.role === "accessor") {
       const descriptor: PropertyDescriptor = {};
       if (method.getter) {
-        descriptor.get = new Function(method.getter.body ?? "") as () => unknown;
+        // SAFETY: `new Function(body)` with no parameter names builds the zero-argument getter.
+        descriptor.get = new Function(method.getter.body ?? "") as DynamicMethod;
       }
       if (method.setter) {
         const sp = (method.setter.parameters ?? []).map((p) => p.$ref?.split("/").pop() ?? "v");
-        descriptor.set = new Function(...sp, method.setter.body ?? "") as (v: unknown) => void;
+        // SAFETY: `new Function(...sp, body)` builds a function over the setter's own parameters.
+        descriptor.set = new Function(...sp, method.setter.body ?? "") as DynamicMethod;
       }
       Object.defineProperty(DynClass.prototype, name, {
         ...descriptor,
         configurable: true,
       });
     } else if (method.scope === "static") {
-      (DynClass as DynamicClass)[name] = new Function(...params, bodyStr);
+      Object.assign(DynClass, { [name]: new Function(...params, bodyStr) });
     } else {
-      (DynClass as DynamicClass).prototype[name] = new Function(...params, bodyStr);
+      Object.assign(DynClass.prototype, { [name]: new Function(...params, bodyStr) });
     }
   }
 

package/src/server.ts

@@ -42,6 +42,24 @@ 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
@@ -52,14 +70,6 @@ import { problem } from "./problem.ts";
  * @param {string} urlPath - URL pathname (e.g. "/pages/@jxsuite/parser/Foo.class.json")
  * @returns {string | null} Absolute file path or null
  */
-interface PackageJson {
-  exports?: Record<string, string | { import?: string; default?: string }>;
-  customElements?: string;
-  module?: string;
-  main?: string;
-  [key: string]: unknown;
-}
-
 function resolveNpmPath(rootDir: string, urlPath: string) {
   let root = rootDir;
   let segments = urlPath.split("/").filter(Boolean);
@@ -121,10 +131,9 @@ function resolveNpmPath(rootDir: string, urlPath: string) {
   // If there's a subpath, check package.json exports first
   if (subpath) {
     try {
-      const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8")) as PackageJson;
-      const exportKey = `./${subpath}`;
-      const exportVal = pkgJson.exports?.[exportKey];
-      if (typeof exportVal === "string") {
+      const pkgJson = readManifest(pkgJsonPath);
+      const exportVal = manifestField(manifestField(pkgJson, "exports"), `./${subpath}`);
+      if (isString(exportVal)) {
         const mapped = join(pkgDir, exportVal);
         if (existsSync(mapped)) {
           return mapped;
@@ -138,9 +147,9 @@ function resolveNpmPath(rootDir: string, urlPath: string) {
     }
     // CEM-relative: subpath may be relative to the custom elements manifest directory
     try {
-      const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8")) as PackageJson;
-      if (pkgJson.customElements) {
-        const cemDir = pkgJson.customElements.replace(/\/[^/]+$/, "");
+      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;
@@ -151,16 +160,20 @@ function resolveNpmPath(rootDir: string, urlPath: string) {
 
   // Bare package (no subpath): resolve entry point
   try {
-    const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8")) as PackageJson;
-    const exp = pkgJson.exports?.["."];
-    const entry =
-      (typeof exp === "object" ? (exp.import ?? exp.default) : exp) ??
-      pkgJson.module ??
-      pkgJson.main;
-    if (entry && typeof entry === "string") {
-      const resolved = join(pkgDir, entry);
-      if (existsSync(resolved)) {
-        return resolved;
+    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 {}
@@ -170,6 +183,9 @@ function resolveNpmPath(rootDir: string, urlPath: string) {
 
 export { resolveNpmPath };
 
+/** The watcher options `createDevServer` passes through when `watch` is an object. */
+type DevWatchOptions = NonNullable<Parameters<typeof createWatcher>[2]>;
+
 /**
  * Create and start a Jx development server.
  *
@@ -209,7 +225,7 @@ export async function createDevServer(options: {
     match?: ((path: string) => boolean) | RegExp;
     label?: string;
   }[];
-  watch?: boolean | object;
+  watch?: boolean | DevWatchOptions;
   studio?: boolean;
   middleware?: (req: Request, url: URL) => Response | null | Promise<Response | null>;
 }) {
@@ -248,7 +264,7 @@ export async function createDevServer(options: {
   let handleSSE = null;
   let fsWatcher: ReturnType<typeof createWatcher>["watcher"] | null = null;
   if (watch !== false) {
-    const watchOpts = typeof watch === "object" ? watch : {};
+    const watchOpts = watch === true ? {} : watch;
     const watcher = createWatcher(absRoot, builds, watchOpts);
     ({ handleSSE } = watcher);
     fsWatcher = watcher.watcher;
@@ -359,9 +375,11 @@ export async function createDevServer(options: {
         return handleResolve(req, absRoot, activeProjectRoot);
       }
 
-      // Timing: "server" function proxy
+      /* Timing: "server" function proxy. Its `env` carries the active project's `.dev.vars`, as the
+         extension mounts' does below, and a module under that project imports even when it sits
+         outside absRoot, as the static lanes below serve it. */
       if (path === "/__jx_server__" && req.method === "POST") {
-        return handleServerFunction(req, absRoot);
+        return handleServerFunction(req, absRoot, activeProjectRoot ?? absRoot);
       }
 
       // Extension server mounts (/_jx/data etc.) — registry-driven, same wire contract as the
@@ -386,6 +404,10 @@ export async function createDevServer(options: {
         // (`isOwnedProjectDir`), so a hostile activate cannot widen the filesystem API to arbitrary
         // Directories.
         if (path === "/__studio/activate" && req.method === "POST") {
+          /* SAFETY: trust boundary. The body parsed as JSON, and this route's caller is Studio's
+             project activation, which posts `{ root }` with a path or nothing. A body of another
+             shape throws in this handler (resolve() refuses a non-string root, and a `null` body
+             has no members), which Bun answers with a 500, as it always has. */
           const body = (await req.json()) as { root?: string };
           const raw = body.root || null;
           if (!raw) {