@jxsuite/server 4.4.5 → 4.5.1

package/src/dev.ts

@@ -124,6 +124,9 @@ export async function startDev({ port, root }: DevArgs): Promise<DevServerHandle
     await rebuild();
   }
 
+  /* SAFETY: createDevServer always calls Bun.serve with a hostname and TCP port, never a unix
+     socket, so the returned Server's `port` (typed `number | undefined` for the socket case) is a
+     number; its promise-returning `stop()` satisfies `() => void`. */
   return (await createDevServer({
     port,
     root,

package/src/extension-catalog.ts

@@ -25,12 +25,11 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { listCatalog } from "@jxsuite/catalog";
-import { buildExtensionRegistry } from "@jxsuite/schema/extension-registry";
+import { buildExtensionRegistry, EXTENSION_MANIFEST } from "@jxsuite/schema/extension-registry";
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { createNodeFormatIO, probeExtension } from "@jxsuite/compiler/format-host";
 import type { ExtensionCatalogEntry, ExtensionSectionInfo } from "@jxsuite/protocol";
-
-/** The well-known manifest filename, mirroring `@jxsuite/schema`'s `EXTENSION_MANIFEST`. */
-const MANIFEST = "jx-extension.json";
+import type { JsonValue } from "@jxsuite/schema/types";
 
 interface PackageJson {
   dependencies?: Record<string, string>;
@@ -45,6 +44,9 @@ function readPackageJson(projectRoot: string): PackageJson | null {
     return null;
   }
   try {
+    /* SAFETY: package.json is the npm manifest the project's installer reads, so its
+       `dependencies`/`devDependencies` are objects keyed by package name (only their keys are read
+       here); text that is not JSON throws into the catch below. */
     return JSON.parse(readFileSync(path, "utf8")) as PackageJson;
   } catch {
     // A project mid-edit should cost the catalogue its discovered half, not the whole response.
@@ -60,6 +62,14 @@ function declaredDependencies(projectRoot: string): string[] {
     : [...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})];
 }
 
+/** What the registry reports for one extension that loaded. */
+interface LoadedEntry {
+  description?: string;
+  formats: string[];
+  sections: ExtensionSectionInfo[];
+  title?: string;
+}
+
 /**
  * Load one extension through the REGISTRY rather than reading its manifest directly.
  *
@@ -75,10 +85,7 @@ function declaredDependencies(projectRoot: string): string[] {
 async function loadEntry(
   projectRoot: string,
   name: string,
-): Promise<
-  | { description?: string; formats: string[]; sections: ExtensionSectionInfo[]; title?: string }
-  | { problem: string }
-> {
+): Promise<LoadedEntry | { problem: string }> {
   try {
     const registry = await buildExtensionRegistry(
       [name],
@@ -94,20 +101,25 @@ async function loadEntry(
     for (const cls of info.classes) {
       if (cls.project) {
         const { key, title } = cls.project;
-        sections.push({ key, ...(typeof title === "string" ? { title } : {}) });
+        const section: ExtensionSectionInfo = { key };
+        // The descriptor is the package's own JSON, so its declared string type is not trusted
+        if (isString(title)) {
+          section.title = title;
+        }
+        sections.push(section);
       }
       for (const ext of cls.extensions) {
         formats.add(ext);
       }
     }
-    return {
-      formats: [...formats].toSorted(),
-      sections,
-      ...(info.manifest.title === undefined ? {} : { title: info.manifest.title }),
-      ...(info.manifest.description === undefined
-        ? {}
-        : { description: info.manifest.description }),
-    };
+    const loaded: LoadedEntry = { formats: [...formats].toSorted(), sections };
+    if (info.manifest.title !== undefined) {
+      loaded.title = info.manifest.title;
+    }
+    if (info.manifest.description !== undefined) {
+      loaded.description = info.manifest.description;
+    }
+    return loaded;
   } catch (error) {
     return { problem: error instanceof Error ? error.message : String(error) };
   }
@@ -131,7 +143,9 @@ function declaresJxField(projectRoot: string, name: string): boolean {
     return false;
   }
   try {
-    return typeof (JSON.parse(readFileSync(path, "utf8")) as PackageJson).jx === "string";
+    // SAFETY: JSON.parse without a reviver only yields JSON values; its `any` says nothing more.
+    const manifest = JSON.parse(readFileSync(path, "utf8")) as JsonValue;
+    return isJsonObject(manifest) && isString(manifest.jx);
   } catch {
     return false;
   }
@@ -155,7 +169,7 @@ export async function buildExtensionCatalog(projectRoot: string): Promise<Extens
   for (const meta of listCatalog()) {
     seen.add(meta.name);
     const found = probeExtension(projectRoot, meta.name);
-    entries.push({
+    const entry: ExtensionCatalogEntry = {
       description: meta.description,
       docs: meta.docs,
       installed: found.project,
@@ -163,12 +177,19 @@ export async function buildExtensionCatalog(projectRoot: string): Promise<Extens
       sections: meta.sections,
       source: "first-party",
       title: meta.title,
-      ...(meta.formats ? { formats: meta.formats } : {}),
-      ...(meta.requires ? { requires: meta.requires } : {}),
-      // Bundled means "resolves without a project install": the host answers for it, and the
-      // Project does not have to.
-      ...(found.host && !found.project ? { bundled: true } : {}),
-    });
+    };
+    if (meta.formats) {
+      entry.formats = meta.formats;
+    }
+    if (meta.requires) {
+      entry.requires = meta.requires;
+    }
+    // Bundled means "resolves without a project install": the host answers for it, and the
+    // Project does not have to.
+    if (found.host && !found.project) {
+      entry.bundled = true;
+    }
+    entries.push(entry);
   }
 
   for (const name of declaredDependencies(projectRoot)) {
@@ -183,7 +204,7 @@ export async function buildExtensionCatalog(projectRoot: string): Promise<Extens
           installed: true,
           name,
           problem:
-            `declares "jx" but does not export "./${MANIFEST}", so no host can resolve its ` +
+            `declares "jx" but does not export "./${EXTENSION_MANIFEST}", so no host can resolve its ` +
             `manifest — add that entry to its exports map`,
           sections: [],
           source: "project",
@@ -202,16 +223,25 @@ export async function buildExtensionCatalog(projectRoot: string): Promise<Extens
       });
       continue;
     }
-    entries.push({
+    const entry: ExtensionCatalogEntry = {
       installed: true,
       name,
       sections: loaded.sections,
       source: "project",
-      ...(loaded.title === undefined ? {} : { title: loaded.title }),
-      ...(loaded.description === undefined ? {} : { description: loaded.description }),
-      ...(loaded.formats.length > 0 ? { formats: loaded.formats } : {}),
-      ...(found.host ? { bundled: true } : {}),
-    });
+    };
+    if (loaded.title !== undefined) {
+      entry.title = loaded.title;
+    }
+    if (loaded.description !== undefined) {
+      entry.description = loaded.description;
+    }
+    if (loaded.formats.length > 0) {
+      entry.formats = loaded.formats;
+    }
+    if (found.host) {
+      entry.bundled = true;
+    }
+    entries.push(entry);
   }
 
   return entries;

package/src/import-api.ts

@@ -7,15 +7,18 @@
  * 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":"ready","root":"..."}              — the destination exists and is openable
- *   {"type":"heartbeat"}                       — keep-alives during silent phases
- *   {"type":"done","root":"...","config":{…},"result":{…}}  — terminal success
- *   {"type":"error","error":"..."}             — terminal failure
+ *
+ * ```text
+ * {"type":"progress","phase":"...","message":"...","current":n,"total":n}
+ * {"type":"ready","root":"..."}              — the destination exists and is openable
+ * {"type":"heartbeat"}                       — keep-alives during silent phases
+ * {"type":"done","root":"...","config":{…},"result":{…}}  — terminal success
+ * {"type":"error","error":"..."}             — terminal failure
+ * ```
  *
  * `ready` arrives seconds in, before the browser launches; `done` arrives minutes later. They are
- * two lines rather than one because they answer different questions — "where is it" and "what did it
- * find" — and a caller that waits for the second to learn the first spends the whole crawl with
+ * two lines rather than one because they answer different questions — "where is it" and "what did
+ * it find" — and a caller that waits for the second to learn the first spends the whole crawl with
  * nothing to show.
  *
  * LLM key flow (matches ai-api.ts): X-Api-Key / Authorization: Bearer header, falling back to the
@@ -30,7 +33,11 @@ import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { problem } from "./problem.ts";
 import type { BreakpointPolicy, BreakpointRounding } from "@jxsuite/import/breakpoint-plan";
+import type { ImportProgressEvent } from "@jxsuite/import/pipeline";
+import type { ImportSiteOptions, ImportSiteResult } from "@jxsuite/import/run";
+import { IMPORT_MAX_PAGES } from "@jxsuite/protocol";
 import type { ImportBreakpointPolicy } from "@jxsuite/protocol";
+import type { JsonObject } from "@jxsuite/schema/types";
 
 export interface ImportApiOptions {
   /**
@@ -44,6 +51,14 @@ export interface ImportApiOptions {
   chromePath?: string;
 }
 
+/**
+ * The breakpoint policy as a request body carries it: the protocol shape, except that nothing has
+ * confirmed `mode` is one of the three until `readBreakpointPolicy` checks it.
+ */
+interface RequestedBreakpointPolicy extends Omit<ImportBreakpointPolicy, "mode"> {
+  mode?: string;
+}
+
 interface ImportRequestBody {
   url?: string;
   directory?: string;
@@ -55,14 +70,35 @@ interface ImportRequestBody {
   verify?: boolean;
   verifyThreshold?: number;
   verifyMinFidelity?: number;
-  breakpoints?: ImportBreakpointPolicy;
+  breakpoints?: RequestedBreakpointPolicy;
+}
+
+/** What the `done` line reports about the run. */
+interface ImportDoneSummary {
+  pages: ImportSiteResult["pages"];
+  fileCount: number;
+  warnings: string[];
+  verify?: NonNullable<ImportSiteResult["verify"]>;
+}
+
+/** One NDJSON line of the import stream (the protocol in this module's header). */
+type ImportStreamLine =
+  | { type: "heartbeat" }
+  | { type: "ready"; root: string }
+  | ({ type: "progress" } & Omit<ImportProgressEvent, "root">)
+  | { type: "done"; root: string; config: JsonObject; result: ImportDoneSummary }
+  | { type: "error"; error: string };
+
+/** The AI pass's credentials, resolved from the request headers or the environment. */
+interface AiConfig {
+  apiKey: string | null;
+  baseUrl: string | undefined;
 }
 
 /** 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;
 
 /** Pixelmatch colour-tolerance bounds for the optional verify pass. */
 const MIN_THRESHOLD = 0.01;
@@ -92,7 +128,7 @@ function clamp(value: number, min: number, max: number): number {
  * `mode` that is not one of the three.
  */
 function readBreakpointPolicy(
-  policy: ImportBreakpointPolicy | undefined,
+  policy: RequestedBreakpointPolicy | undefined,
 ): BreakpointPolicy | undefined {
   if (!policy) {
     return undefined;
@@ -118,7 +154,7 @@ function readBreakpointPolicy(
   return undefined;
 }
 
-function getAiConfig(req: Request): { apiKey: string | null; baseUrl: string | undefined } {
+function getAiConfig(req: Request): AiConfig {
   const authHeader = req.headers.get("Authorization") || "";
   const apiKeyHeader = req.headers.get("X-Api-Key") || "";
   const baseUrlHeader = req.headers.get("X-Api-Base-URL") || "";
@@ -142,6 +178,9 @@ function getAiConfig(req: Request): { apiKey: string | null; baseUrl: string | u
 async function handleImportSite(req: Request, opts: ImportApiOptions): Promise<Response> {
   let body: ImportRequestBody;
   try {
+    /* SAFETY: Studio's import dialog posts this body (`ImportSiteRequest` in @jxsuite/protocol);
+       `url` and `directory` are required and checked just below, every number is re-clamped, and
+       the breakpoint policy is re-read field by field in readBreakpointPolicy. */
     body = (await req.json()) as ImportRequestBody;
   } catch {
     return problem("invalidRequest", "Invalid JSON body");
@@ -188,7 +227,7 @@ async function handleImportSite(req: Request, opts: ImportApiOptions): Promise<R
         ),
       }
     : false;
-  const maxPages = clamp(body.maxPages ?? 20, 1, MAX_PAGES);
+  const maxPages = clamp(body.maxPages ?? 20, 1, IMPORT_MAX_PAGES);
   const maxNodesPerPage = clamp(body.maxNodesPerPage ?? 5000, 100, 50_000);
   const breakpoints = readBreakpointPolicy(body.breakpoints);
   const { apiKey, baseUrl } = getAiConfig(req);
@@ -197,15 +236,16 @@ async function handleImportSite(req: Request, opts: ImportApiOptions): Promise<R
   const encoder = new TextEncoder();
   const stream = new ReadableStream({
     async start(controller) {
-      let closed = false;
-      const writeLine = (obj: unknown) => {
-        if (closed) {
+      // Held in an object because writeLine closes it from inside a callback
+      const sink = { closed: false };
+      const writeLine = (line: ImportStreamLine) => {
+        if (sink.closed) {
           return;
         }
         try {
-          controller.enqueue(encoder.encode(`${JSON.stringify(obj)}\n`));
+          controller.enqueue(encoder.encode(`${JSON.stringify(line)}\n`));
         } catch {
-          closed = true;
+          sink.closed = true;
         }
       };
       const heartbeat = setInterval(() => writeLine({ type: "heartbeat" }), HEARTBEAT_INTERVAL_MS);
@@ -230,59 +270,61 @@ async function handleImportSite(req: Request, opts: ImportApiOptions): Promise<R
           }
         }
 
-        const result = await importSite(
-          {
-            url,
-            outDir: destPath,
-            maxDepth: depth,
-            maxPages,
-            maxNodesPerPage,
-            ai,
-            verify,
-            signal: req.signal,
-            ...(breakpoints === undefined ? {} : { breakpoints }),
-            ...(opts.chromePath === undefined ? {} : { chromePath: opts.chromePath }),
-          },
-          (e) => {
-            /* The seed event carries the root, and it is the ONE thing a caller cannot wait for the
+        const importOptions: ImportSiteOptions = {
+          url,
+          outDir: destPath,
+          maxDepth: depth,
+          maxPages,
+          maxNodesPerPage,
+          ai,
+          verify,
+          signal: req.signal,
+        };
+        if (breakpoints !== undefined) {
+          importOptions.breakpoints = breakpoints;
+        }
+        if (opts.chromePath !== undefined) {
+          importOptions.chromePath = opts.chromePath;
+        }
+        const result = await importSite(importOptions, (e) => {
+          /* The seed event carries the root, and it is the ONE thing a caller cannot wait for the
                terminal line to learn: it arrives seconds in, and `done` arrives minutes later. It
                is re-emitted as its own line rather than left inside a progress message, because a
                root parsed out of prose is a root that breaks when the prose is reworded. */
-            if (e.phase === "seed" && e.root) {
-              writeLine({ type: "ready", root: toRoot(e.root) });
-            }
-            const { root: _root, ...progress } = e;
-            writeLine({ type: "progress", ...progress });
-          },
-        );
+          if (e.phase === "seed" && e.root) {
+            writeLine({ type: "ready", root: toRoot(e.root) });
+          }
+          const { root: _root, ...progress } = e;
+          writeLine({ type: "progress", ...progress });
+        });
 
+        /* SAFETY: importSite's emit phase has just written project.json as a Jx project config,
+           which is a JSON object; text that is not JSON throws into the error line below. */
         const config = JSON.parse(
           await readFile(resolve(result.outDir, "project.json"), "utf8"),
-        ) as Record<string, unknown>;
+        ) as JsonObject;
         /*
          * The result travels with the `done` line. It used to be discarded here: the pipeline had
          * computed the page list, the file count, the warnings and (with verify) a per-page
          * fidelity score, and the caller learned only that an import had happened. A caller that
          * cannot see what a run found cannot report it, and cannot ask about it either.
          */
-        writeLine({
-          type: "done",
-          root: toRoot(result.outDir),
-          config,
-          result: {
-            pages: result.pages,
-            fileCount: result.fileCount,
-            warnings: result.warnings,
-            ...(result.verify ? { verify: result.verify } : {}),
-          },
-        });
+        const summary: ImportDoneSummary = {
+          pages: result.pages,
+          fileCount: result.fileCount,
+          warnings: result.warnings,
+        };
+        if (result.verify) {
+          summary.verify = result.verify;
+        }
+        writeLine({ type: "done", root: toRoot(result.outDir), config, result: summary });
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         writeLine({ type: "error", error: message });
       } finally {
         clearInterval(heartbeat);
-        if (!closed) {
-          closed = true;
+        if (!sink.closed) {
+          sink.closed = true;
           try {
             controller.close();
           } catch {

package/src/jx-mounts.ts

@@ -7,7 +7,8 @@
  *
  * Dev conveniences over the production worker:
  *
- * - `env` is process.env merged under the project's `.dev.vars` plus `JX_PROJECT_ROOT`;
+ * - `env` is process.env merged under the project's `.dev.vars` plus `JX_PROJECT_ROOT`
+ *   (`projectDevEnv`, which the server-function proxy shares);
  * - Connector classes with `local: "<provider>"` are stood in by the registry's class for that
  *   provider (e.g. D1 → sqlite at `<project>/.jx/data/<connection>.sqlite`);
  * - Mount options set `autoSync: true`, so table schemas sync additively on first touch.
@@ -18,16 +19,16 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { buildProjectExtensionRegistry } from "@jxsuite/compiler/format-host";
-import { loadDevVars } from "./dev-vars.ts";
+import { isString } from "@jxsuite/schema/guards";
+import { projectDevEnv } from "./dev-vars.ts";
+import type { ProjectDevEnv } from "./dev-vars.ts";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
-import type { FormatEntry } from "@jxsuite/schema/format-registry";
-import type { ProjectConfig } from "@jxsuite/schema/types";
-
-type MountHandler = (request: Request, env: Record<string, unknown>) => Promise<Response>;
+import type { ImplementationExport, MountHandler } from "@jxsuite/schema/format-registry";
+import type { JxDocumentValue, ProjectConfig } from "@jxsuite/schema/types";
 
 interface MountRuntime {
   handlers: { basePath: string; handler: MountHandler }[];
-  env: Record<string, unknown>;
+  env: ProjectDevEnv;
 }
 
 /** Per-project runtime cache, invalidated when project.json's mtime moves. */
@@ -105,6 +106,9 @@ async function buildRuntime(
   projectRoot: string,
   projectJsonPath: string,
 ): Promise<MountRuntime | null> {
+  /* SAFETY: trust boundary. project.json is the project's own config, held to its per-project
+     schema by the editor and `jx validate`; the sections are only relayed to the mounts that own
+     them, and any throw lands in getRuntime's catch, which disables the mounts with a warning. */
   const config = JSON.parse(readFileSync(projectJsonPath, "utf8")) as ProjectConfig;
   const registry = await buildProjectExtensionRegistry(projectRoot, config);
   const mounts = registry.serverMounts();
@@ -112,7 +116,7 @@ async function buildRuntime(
     return null;
   }
 
-  const sections: Record<string, unknown> = {};
+  const sections: Record<string, JxDocumentValue | undefined> = {};
   for (const contribution of registry.projectContributions()) {
     const { key } = contribution.project!;
     if (key in config) {
@@ -121,22 +125,19 @@ async function buildRuntime(
   }
 
   const connectors = await resolveConnectorStandins(registry);
-  const env: Record<string, unknown> = {
-    ...process.env,
-    ...loadDevVars(projectRoot),
-    JX_PROJECT_ROOT: projectRoot,
-  };
+  const env = projectDevEnv(projectRoot);
 
-  // One shared mutable context, passed to every mount in order (specs/extensions.md §11).
-  const ctx: Record<string, unknown> = {};
+  /* One shared mutable context, passed to every mount in order (specs/extensions.md §11). Its
+     members belong to the mounts; this host never reads them. */
+  const ctx = {};
   const handlers: MountRuntime["handlers"] = [];
   for (const entry of mounts) {
     const { basePath } = entry.server!;
-    const handler = (await entry.call(
+    const handler = await entry.call(
       "mount",
       { autoSync: true, basePath, connectors, sections },
       ctx,
-    )) as MountHandler;
+    );
     handlers.push({ basePath, handler });
   }
   return { env, handlers };
@@ -148,30 +149,26 @@ async function buildRuntime(
  * that provider instead of its own (specs/extensions.md §12). Shared with the data-api push seam so
  * section-owner deploySchema contributions (e.g. auth) see the same stand-ins as the mounts.
  *
+ * Each provider is its implementation module's export (specs/extensions.md §6.1): this host only
+ * routes it, and the mounts and deploy steps that receive it are the ones that call it. A module
+ * exporting no such export yields a nullish entry, which the receiving mount reports as an
+ * unavailable provider.
+ *
  * @param {ExtensionRegistry} registry
- * @returns {Promise<Record<string, unknown>>}
+ * @returns {Promise<Record<string, ImplementationExport | null | undefined>>}
  */
 export async function resolveConnectorStandins(
   registry: ExtensionRegistry,
-): Promise<Record<string, unknown>> {
+): Promise<Record<string, ImplementationExport | null | undefined>> {
   const entries = registry.connectors();
-  const out: Record<string, unknown> = {};
+  const out: Record<string, ImplementationExport | null | undefined> = {};
   for (const entry of entries) {
     const provider = String(entry.connector!.provider);
     const { local } = entry.connector!;
-    const target =
-      typeof local === "string"
-        ? (entries.find((e) => e.connector!.provider === local) ?? entry)
-        : entry;
-    out[provider] = await implementationClass(target);
+    const target = isString(local)
+      ? (entries.find((e) => e.connector!.provider === local) ?? entry)
+      : entry;
+    out[provider] = await target.implementationExport();
   }
   return out;
 }
-
-/** Import a connector entry's implementation module and pick the export named by its title. */
-async function implementationClass(entry: FormatEntry): Promise<unknown> {
-  const mod = await entry.implementation();
-  const title = (entry.classDef.title as string | undefined) ?? entry.name;
-  const fromDefault = (mod.default as Record<string, unknown> | undefined)?.[title];
-  return mod[title] ?? fromDefault ?? mod.default;
-}

package/src/live-preview.ts

@@ -42,11 +42,11 @@ import { extname, join, resolve } from "node:path";
 import { serveSite, siteContext, siteHeaders } from "@jxsuite/site/serve";
 import { SERVABLE_ROOTS } from "@jxsuite/site/paths";
 import { buildSiteStyleCSS } from "@jxsuite/site/site-style";
-import type { AssetIO, SiteContext } from "@jxsuite/site/serve";
+import type { AssetIO, SiteContext, SiteTree } from "@jxsuite/site/serve";
 import { readProjectConfig } from "@jxsuite/site/compose";
 import type { DocumentParser, SiteIO } from "@jxsuite/site/compose";
-import { buildProjectFormatRegistry } from "@jxsuite/compiler/format-host";
-import type { JxDocument } from "@jxsuite/schema/types";
+import { buildProjectExtensionRegistry } from "@jxsuite/compiler/format-host";
+import { isNonNullObject } from "@jxsuite/schema/guards";
 import { createSseHub } from "./sse.ts";
 import type { SseHub } from "./sse.ts";
 import { LIVE_NAMESPACE, PREVIEW_CLIENT_JS } from "./preview-client.ts";
@@ -203,12 +203,13 @@ function documentParser(projectRoot: string): DocumentParser {
         paths: () => [],
         read: (file) => readTreeFile(projectRoot, file),
       });
-      const registry = await buildProjectFormatRegistry(projectRoot, config);
-      const entry = registry.byExtension(extname(path), "parse");
+      const { formats } = await buildProjectExtensionRegistry(projectRoot, config);
+      const entry = formats.byExtension(extname(path), "parse");
       if (!entry) {
         return null;
       }
-      return (await entry.call("parse", text, { path })) as JxDocument;
+      // A page format answers a JxDocument; one that throws instead is caught below.
+      return await entry.parseDocument(text, { path });
     } catch {
       /* A format that throws is a broken project, not a broken preview: returning null lets the
          composer report the page by name rather than taking the whole origin down. */
@@ -231,7 +232,7 @@ async function readTreeFile(projectRoot: string, path: string): Promise<string |
 }
 
 /** Reading the tree, overlay first — which is what makes this the canvas rather than the disk. */
-function makeIO(projectRoot: string, paths: string[]): { io: SiteIO; assets: AssetIO } {
+function makeIO(projectRoot: string, paths: string[]): SiteTree {
   const io: SiteIO = {
     parse: documentParser(projectRoot),
     paths: () => paths,
@@ -273,11 +274,12 @@ function invalidate(entry: Running) {
 
 /** `project.json`'s `style` as a stylesheet, or empty when the project declares none. */
 function siteStyleCss(context: SiteContext): string {
-  const { style } = context.config as { style?: Record<string, unknown> };
-  if (!style || typeof style !== "object") {
+  const { style } = context.config;
+  // Project.json is hand-edited JSON, so a declared `style` may still be a non-object
+  if (!style || !isNonNullObject(style)) {
     return "";
   }
-  const media = (context.config as { $media?: Record<string, string> }).$media ?? {};
+  const media = context.config.$media ?? {};
   /* Identity transposition: a browser tab IS the viewport, so `100vh` already means what it says.
      The canvas passes a real transposer because its viewport is an iframe it sizes to content. */
   return buildSiteStyleCSS(style, media, (value) => value);
@@ -314,6 +316,9 @@ async function handle(entry: Running, projectRoot: string, req: Request): Promis
     if (surface === "ack" && req.method === "POST") {
       let body: { gen?: number };
       try {
+        /* SAFETY: PREVIEW_CLIENT_JS is this route's only client and posts `{ gen }` with the
+           generation it applied; `gen` is only compared with `===`, so a stray value merely fails
+           to settle the pending acknowledgement. */
         body = (await req.json()) as { gen?: number };
       } catch {
         return problem("invalidRequest", "Invalid JSON body");
@@ -520,6 +525,7 @@ function enforceOverlayBudget(overlay: Overlay): void {
     total += value.length;
   }
   while (total > OVERLAY_MAX_BYTES && overlay.files.size > 1) {
+    // SAFETY: the loop runs only while `files.size > 1`, so the key iterator has a first entry.
     const oldest = overlay.files.keys().next().value as string;
     total -= overlay.files.get(oldest)?.length ?? 0;
     overlay.files.delete(oldest);