@jxsuite/server 4.5.0 → 6.0.0

package/src/resolve.ts

@@ -3,7 +3,8 @@
 import { siteBasePath } from "@jxsuite/schema/asset-paths";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { errorMessage, parseClassDef } from "@jxsuite/schema/parse";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { isFunction, isNonNullObject, isString } from "@jxsuite/schema/guards";
+import { readFileSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { projectDevEnv } from "./dev-vars.ts";
 import { containedPath } from "./net-guard.ts";
@@ -11,35 +12,123 @@ 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 { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
+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;
 }
 
-interface ClassInstance {
-  resolve?: () => unknown;
-  value?: unknown;
-  [key: string]: unknown;
+/**
+ * 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 };
+
+/**
+ * One `project.json` generation: its config, extension registry and asset mounts, loaded together
+ * because they are cheap, and the extension-loaded sections, loaded only when a class asks for
+ * them.
+ */
+interface ProjectEntry {
+  mtime: number;
+  config: ProjectConfig;
+  registry: ExtensionRegistry;
+  mounts: AssetMount[];
+  /** The full `_project` context, started by the first {@link loadProjectContext} and shared. */
+  context?: Promise<ProjectContext> | undefined;
+}
+
+/** 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;
+}
+
+/** 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;
 }
 
 /**
@@ -92,11 +181,19 @@ function baseDirectory($base: string, root: string, projectRoot: string): string
   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[] }
->();
+/**
+ * Per-project cache, invalidated when project.json changes on disk. It holds the PROMISE, keyed by
+ * the mtime it was started for, so concurrent requests on a cold cache share one load.
+ *
+ * Both halves of that are load-bearing. Every project file the canvas fetches asks for the asset
+ * mounts, and the canvas fetches a document's `$elements` in parallel: before the promise was
+ * cached, each of them started its own load, so a page with 25 components ran 25 at once. And the
+ * sections are not part of it: a content section loads every entry of every collection, which for a
+ * 910-entry knowledge base is ten seconds of parsing, so serving a JSON file next to it waited ten
+ * seconds for data it never reads. Both together put a component fetch past the canvas's register
+ * timeout on every cold open.
+ */
+const projectEntryCache = new Map<string, { mtime: number; entry: Promise<ProjectEntry | null> }>();
 
 /**
  * Lazy-load project context (project.json + extension-loaded sections) for class instantiation.
@@ -104,33 +201,86 @@ 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;
+  if (!entry) {
+    return null;
+  }
+  entry.context ??= loadProjectSections(projectRoot, entry.config, entry.registry, {
+    lazy: true,
+  }).then((sections) => ({ config: entry.config, root: projectRoot, ...sections }));
+  try {
+    return await entry.context;
+  } catch {
+    // A failed load is not remembered: the next class to ask tries again.
+    entry.context = undefined;
+    return null;
+  }
+}
+
+/**
+ * Whether a class reads `_project` through its sections' on-demand methods, by declaring `static
+ * projectOnDemand = true` (specs/extensions.md §8). The sections here are loaded lazily, so a class
+ * that reads one synchronously (a `content.get(type)`) would find nothing it had not loaded; such a
+ * class is handed every section whole instead, exactly what it was always given.
+ */
+function readsProjectOnDemand(ExportedClass: ExportedFunction | ExportedConstructor): boolean {
+  return "projectOnDemand" in ExportedClass && ExportedClass.projectOnDemand === true;
+}
+
+/** A section an owner loaded on demand: `complete()` makes it whole (extensions.md §8). */
+interface OnDemandSection {
+  complete: () => Promise<void>;
+}
+
+/** Whether a project-context value is a section loaded on demand, by its `complete` method. */
+function isOnDemandSection(
+  value: ProjectContext[string],
+): value is ProjectContext[string] & OnDemandSection {
+  return isNonNullObject(value) && "complete" in value && isFunction(value.complete);
 }
 
-/** Load (or reuse) the cached project context plus its extension asset mounts. */
-async function loadProjectEntry(projectRoot: string) {
+/** Make every section of a project context whole, for a class that reads them synchronously. */
+async function completeSections(context: ProjectContext): Promise<void> {
+  for (const value of Object.values(context)) {
+    if (isOnDemandSection(value)) {
+      await value.complete();
+    }
+  }
+}
+
+/** Load (or reuse) the cached project config, extension registry and asset mounts. */
+async function loadProjectEntry(projectRoot: string): Promise<ProjectEntry | null> {
   const projectJsonPath = resolve(projectRoot, "project.json");
-  if (!existsSync(projectJsonPath)) {
+  const mtime = statSync(projectJsonPath, { throwIfNoEntry: false })?.mtimeMs;
+  if (mtime === undefined) {
     return null;
   }
+  const cached = projectEntryCache.get(projectRoot);
+  if (cached && cached.mtime === mtime) {
+    return cached.entry;
+  }
+  const entry = readProjectEntry(projectRoot, projectJsonPath, mtime);
+  projectEntryCache.set(projectRoot, { entry, mtime });
+  return entry;
+}
+
+/** Read one `project.json` generation. Never rejects: any failure answers "no project context". */
+async function readProjectEntry(
+  projectRoot: string,
+  projectJsonPath: string,
+  mtime: number,
+): Promise<ProjectEntry | null> {
   try {
-    const { mtimeMs } = statSync(projectJsonPath);
-    const cached = projectContextCache.get(projectRoot);
-    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 };
-    projectContextCache.set(projectRoot, entry);
-    return entry;
+    return { config, mounts, mtime, registry };
   } catch {
     return null;
   }
@@ -148,8 +298,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?.config.url);
 }
 
 /**
@@ -178,12 +327,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");
   }
@@ -228,7 +381,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("/")}`;
       }
     }
@@ -257,38 +410,31 @@ 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);
+        if (config._project && !readsProjectOnDemand(ExportedClass)) {
+          await completeSections(config._project);
+        }
+        /* 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
+      // Self-contained: construct class from schema. Its JSON bodies cannot await a section.
+      if (config._project) {
+        await completeSections(config._project);
+      }
       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));
     }
@@ -319,6 +465,10 @@ export async function handleResolve(
 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");
@@ -344,7 +494,7 @@ export async function handleServerFunction(req: Request, root: string, projectRo
 
   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,
@@ -352,7 +502,7 @@ export async function handleServerFunction(req: Request, root: string, projectRo
   }
 
   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,
     });
@@ -362,16 +512,53 @@ export async function handleServerFunction(req: Request, root: string, projectRo
     /* 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). */
-    const result = await (fn as (args: Record<string, unknown>, env: unknown) => unknown)(
-      args,
-      projectDevEnv(projectRoot),
-    );
+    /* 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.
@@ -380,26 +567,24 @@ export async function handleServerFunction(req: Request, root: string, projectRo
  */
 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) {
@@ -416,27 +601,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;
@@ -388,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) {
@@ -534,7 +554,11 @@ export async function createDevServer(options: {
 
         // Resolve npm-style bare specifiers via node_modules.
         // Bundle on-demand so internal bare specifiers (e.g. lit/...) resolve.
-        const resolved = resolveNpmPath(absRoot, path);
+        /* The open project's own packages first: it pins the versions its pages are built with,
+           and a project outside the served root has no other way to reach them. */
+        const resolved =
+          (activeProjectRoot ? resolveNpmPath(activeProjectRoot, path) : null) ??
+          resolveNpmPath(absRoot, path);
         if (resolved) {
           const cacheKey = resolved;
           if (!bundleCache.has(cacheKey)) {