@jxsuite/server 4.5.0 → 4.5.1

package/src/refactor/scan.ts

@@ -9,22 +9,17 @@
 
 import { extname } from "node:path";
 import { readFile } from "node:fs/promises";
-import type { FormatRegistry } from "@jxsuite/schema/format-registry";
+import type { FormatRegistry, ValueEdit } from "@jxsuite/schema/format-registry";
+import type { JsonValue } from "@jxsuite/schema/types";
 
 /** Normalise a path to forward slashes (Windows `path` returns backslashes). */
 export const fwd = (p: string) => p.replaceAll("\\", "/");
 
-/** One authored value to replace in a document's own source text. */
-export interface ValueEdit {
-  from: string;
-  to: string;
-}
-
 /** A parsed document and the two ways it might be written back. */
 export interface LoadedDoc {
-  doc: unknown;
+  doc: JsonValue;
   /** Round-trips the whole document. Null when the format declares no `serialize`. */
-  serialize: ((doc: unknown) => Promise<string>) | null;
+  serialize: ((doc: JsonValue) => Promise<string>) | null;
   /**
    * Replaces authored values in the file's own bytes, changing nothing else. Null when the format
    * declares no `rewrite`.
@@ -84,7 +79,8 @@ export async function loadDoc(fp: string, registry: FormatRegistry): Promise<Loa
   if (isJsonPath(fp)) {
     const trailingNewline = raw.endsWith("\n");
     return {
-      doc: JSON.parse(raw) as unknown,
+      // SAFETY: JSON.parse without a reviver only ever yields a JSON value; its `any` says no more.
+      doc: JSON.parse(raw) as JsonValue,
       rewrite: null,
       serialize: (doc) =>
         Promise.resolve(JSON.stringify(doc, null, 2) + (trailingNewline ? "\n" : "")),
@@ -95,22 +91,20 @@ export async function loadDoc(fp: string, registry: FormatRegistry): Promise<Loa
   if (!parseEntry) {
     throw new Error(`No parser for "${ext}"`);
   }
-  const doc = await parseEntry.call("parse", raw);
+  /* SAFETY: read as a JSON tree. A `parse` answer is a JxDocument or a ContentLoaderEntry[]
+     (specs/extensions.md §8), both JSON trees but for leaves such as a frontmatter Date. Every walk
+     over it in refs.ts re-checks each node with Array.isArray / isJsonObject / isString before
+     reading it, so such a leaf is skipped rather than misread. */
+  const doc = (await parseEntry.call("parse", raw)) as JsonValue;
   const serializeEntry = registry.byExtension(ext, "serialize");
   const rewriteEntry = registry.byExtension(ext, "rewrite");
   return {
     doc,
     rewrite: rewriteEntry
-      ? async (edits) => {
-          const out = await rewriteEntry.call("rewrite", raw, edits);
-          return typeof out === "string" ? out : String(out);
-        }
+      ? async (edits) => String(await rewriteEntry.call("rewrite", raw, edits))
       : null,
     serialize: serializeEntry
-      ? async (d) => {
-          const out = await serializeEntry.call("serialize", d);
-          return typeof out === "string" ? out : String(out);
-        }
+      ? async (d) => String(await serializeEntry.call("serialize", d))
       : null,
   };
 }

package/src/refactor/watcher.ts

@@ -6,7 +6,8 @@
  * build/reload); both share the pure `toFsEvent`/`coalesceFsEvents` helpers.
  */
 
-import { watch as chokidarWatch } from "chokidar";
+import { watch } from "chokidar";
+import { errorMessage } from "@jxsuite/schema/parse";
 import { coalesceFsEvents, toFsEvent } from "./fs-events.ts";
 import { invalidateReferenceCache } from "./find-refs.ts";
 import { createWatchIgnore } from "../watch-policy.ts";
@@ -36,7 +37,7 @@ export function createFsWatcher(
   let buffer: FsEventPayload[] = [];
   let timer: ReturnType<typeof setTimeout> | null = null;
 
-  const watcher = chokidarWatch(root, {
+  const watcher = watch(root, {
     /* Left on deliberately: a symlink inside a project is project content, and its events belong
        in the sidebar. It is the link pointing OUT of the root that walks the watcher off into the
        rest of the filesystem, and createWatchIgnore drops exactly those — along with the sockets
@@ -71,9 +72,8 @@ export function createFsWatcher(
      directory holding a few unix sockets took the whole launcher down rather than losing a few
      watches. The filter above means these should now be rare; the listener means they are never
      fatal when they are not. */
-  watcher.on("error", (err) => {
-    const error = err as NodeJS.ErrnoException;
-    console.error(`[fs-watch] ${error.message ?? String(error)}`);
+  watcher.on("error", (cause) => {
+    console.error(`[fs-watch] ${errorMessage(cause)}`);
   });
 
   return {

package/src/resolve.ts

@@ -3,6 +3,7 @@
 import { siteBasePath } from "@jxsuite/schema/asset-paths";
 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";
@@ -11,35 +12,115 @@ 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;
 }
 
-interface ClassInstance {
-  resolve?: () => unknown;
-  value?: unknown;
-  [key: string]: unknown;
+/**
+ * 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;
+}
+
+/** 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;
 }
 
 /**
@@ -93,10 +174,7 @@ function baseDirectory($base: string, root: string, projectRoot: string): string
 }
 
 /** 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.
@@ -104,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;
@@ -123,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 {
@@ -148,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);
 }
 
 /**
@@ -178,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");
   }
@@ -228,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("/")}`;
       }
     }
@@ -257,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));
     }
@@ -319,6 +390,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 +419,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 +427,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 +437,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 +492,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 +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;
@@ -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) {