@jxsuite/server 8.3.0 → 8.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "8.3.0",
+  "version": "8.5.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -21,6 +21,7 @@
   "exports": {
     ".": "./src/server.ts",
     "./dev": "./src/dev.ts",
+    "./convert": "./src/convert.ts",
     "./ai-api": "./src/ai-api.ts",
     "./data": "./src/data-api.ts",
     "./import-api": "./src/import-api.ts",
@@ -54,17 +55,17 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/ai": "^0.43.0",
-    "@jxsuite/catalog": "^0.1.8",
-    "@jxsuite/collab": "^0.11.6",
-    "@jxsuite/compiler": "^8.2.0",
-    "@jxsuite/create": "^1.5.4",
-    "@jxsuite/import": "^0.42.4",
-    "@jxsuite/protocol": "^6.2.2",
-    "@jxsuite/runtime": "^6.1.0",
-    "@jxsuite/schema": "^5.2.0",
-    "@jxsuite/site": "^2.3.1",
-    "@jxsuite/starters": "^3.3.0",
+    "@jxsuite/ai": "^0.43.2",
+    "@jxsuite/catalog": "^0.1.10",
+    "@jxsuite/collab": "^0.11.8",
+    "@jxsuite/compiler": "^8.4.0",
+    "@jxsuite/create": "^1.6.0",
+    "@jxsuite/import": "^0.43.0",
+    "@jxsuite/protocol": "^6.2.4",
+    "@jxsuite/runtime": "^6.2.1",
+    "@jxsuite/schema": "^5.4.0",
+    "@jxsuite/site": "^2.5.0",
+    "@jxsuite/starters": "^3.3.2",
     "@npmcli/arborist": "^10.0.4",
     "chokidar": "^6.0.0",
     "kysely": "^0.29.8",
@@ -74,9 +75,9 @@
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@jxsuite/auth": "^0.8.4",
-    "@jxsuite/connector": "^0.8.4",
-    "@jxsuite/parser": "^4.3.0",
+    "@jxsuite/auth": "^0.8.6",
+    "@jxsuite/connector": "^0.8.6",
+    "@jxsuite/parser": "^4.3.2",
     "@jxsuite/test-support": "^0.0.0",
     "@types/npm-package-arg": "^6.1.4",
     "@types/npmcli__arborist": "^6.3.3",

package/src/convert.ts

@@ -0,0 +1,300 @@
+/**
+ * `jx convert`: move a document between `.json` and `.jxn`, with every reference repaired, and the
+ * project file between `project.json` and `project.jxn` (site-architecture.md §2.3).
+ *
+ * It is a rename, because that is what makes it safe: writing a new file beside the old one would
+ * leave every `$ref` to it dangling, and the refactor pass is what repairs them. A project file is
+ * named by nothing, so it needs no repair, and writing it beside the old one would leave a folder
+ * holding both, which every host refuses. This runs under Bun for the same reason `jx dev` does, so
+ * `@jxsuite/compiler`'s CLI resolves it from the project and spawns it.
+ *
+ * @docs framework/build/cli
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
+import { buildProjectExtensionRegistry } from "@jxsuite/compiler/format-host";
+import { loadProjectConfig } from "@jxsuite/compiler/site-loader";
+import { countJxnComments, parseJxn, serializeJxn } from "@jxsuite/schema/jxn";
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
+import { errorMessage, parseJxDocument } from "@jxsuite/schema/parse";
+import {
+  isProjectFileName,
+  parseProjectSource,
+  serializeProjectFile,
+} from "@jxsuite/schema/project-file";
+import type { ProjectConfig } from "@jxsuite/schema/types";
+import { applyRename } from "./refactor/index.ts";
+
+/** The formats a document can move between. */
+export type ConvertTarget = "json" | "jxn";
+
+/** What was asked. */
+export interface ConvertOptions {
+  /** Convert a `.jxn` file that has comments, which `.json` has nowhere to keep. */
+  dropComments: boolean;
+  /** Say what would happen, and change nothing. */
+  dryRun: boolean;
+  to: ConvertTarget;
+}
+
+/** What happened to one file. */
+export interface ConvertRow {
+  from: string;
+  /** Other files whose references to this one were repaired. */
+  references: number;
+  /** Why it was left alone, or what is still wrong after moving it. */
+  problem: string | null;
+  to: string;
+}
+
+/** The directories that hold documents, which are conventions the build hard-codes. */
+const DOCUMENT_ROOTS = ["components/", "layouts/", "pages/"];
+
+/**
+ * Where each content collection's files are, project-relative: the part of its `source` before any
+ * `{locale}` or glob. Only a collection reaching into a document root can matter here.
+ */
+function collectionRoots(config: ProjectConfig): string[] {
+  const content = isJsonObject(config.content) ? Object.values(config.content) : [];
+  return content.flatMap((definition) => {
+    const source = isJsonObject(definition) ? definition.source : null;
+    if (!isString(source)) {
+      return [];
+    }
+    const [fixed = ""] = /^[^{*]*/u.exec(source) ?? [];
+    return [fixed.replace(/^\.\//u, "").replace(/\/+$/u, "")];
+  });
+}
+
+/** Every convertible file a path names: itself, or what is under it. */
+function expand(path: string): string[] {
+  // A path that is not there comes through as itself, so `refusal` can say so.
+  if (!existsSync(path) || !statSync(path).isDirectory()) {
+    return [path];
+  }
+  return readdirSync(path, { withFileTypes: true }).flatMap((entry) => {
+    const child = join(path, entry.name);
+    if (entry.isDirectory()) {
+      return expand(child);
+    }
+    return /\.(?:json|jxn)$/iu.test(entry.name) && !entry.name.endsWith(".class.json")
+      ? [child]
+      : [];
+  });
+}
+
+/** Whether a path is the project's own file, which is the one root file that converts. */
+function isProjectFileAt(root: string, path: string): boolean {
+  return isProjectFileName(relative(root, path));
+}
+
+/**
+ * Why the project file cannot be converted, or null when it can. The other name already being there
+ * needs no check here: the folder then holds both, and loading the project has refused it.
+ */
+async function projectFileRefusal(path: string, options: ConvertOptions): Promise<string | null> {
+  const ext = extname(path).toLowerCase();
+  if (ext === `.${options.to}`) {
+    return `already .${options.to}`;
+  }
+  return ext === ".jxn" ? commentRefusal(path, options) : null;
+}
+
+/** Why a `.jxn` file's comments keep it from becoming `.json`, or null when nothing would be lost. */
+async function commentRefusal(path: string, options: ConvertOptions): Promise<string | null> {
+  if (options.dropComments) {
+    return null;
+  }
+  const comments = countJxnComments(await readFile(path, "utf8"));
+  return comments > 0
+    ? `it has ${comments} comment(s), and .json has nowhere to keep them. --drop-comments converts it anyway`
+    : null;
+}
+
+/** Why a file cannot be converted, or null when it can. */
+async function refusal(
+  root: string,
+  path: string,
+  options: ConvertOptions,
+  sources: readonly string[],
+): Promise<string | null> {
+  if (!existsSync(path)) {
+    return "there is no such file";
+  }
+  if (isProjectFileAt(root, path)) {
+    return projectFileRefusal(path, options);
+  }
+  const name = relative(root, path).replaceAll("\\", "/");
+  if (!DOCUMENT_ROOTS.some((prefix) => name.startsWith(prefix))) {
+    return `only ${DOCUMENT_ROOTS.join(", ")} hold documents`;
+  }
+  const ext = extname(path).toLowerCase();
+  if (ext !== ".json" && ext !== ".jxn") {
+    return `${ext || "this file"} is not a native document format`;
+  }
+  if (path.endsWith(".class.json")) {
+    return "a class descriptor stays JSON";
+  }
+  if (ext === `.${options.to}`) {
+    return `already .${options.to}`;
+  }
+  if (sources.some((source) => name === source || name.startsWith(`${source}/`))) {
+    // Both directions: an entry would drop out of its glob, and a neighbour would be enlisted.
+    return "a content collection's file keeps its collection's format";
+  }
+  if (existsSync(targetOf(path, options.to))) {
+    return `${basename(targetOf(path, options.to))} already exists`;
+  }
+  return ext === ".jxn" ? commentRefusal(path, options) : null;
+}
+
+/** The path a file has once converted. */
+function targetOf(path: string, to: ConvertTarget): string {
+  return join(dirname(path), `${basename(path, extname(path))}.${to}`);
+}
+
+/** The file's text in the other format. */
+async function converted(root: string, path: string, to: ConvertTarget): Promise<string> {
+  const text = await readFile(path, "utf8");
+  if (isProjectFileAt(root, path)) {
+    // Canonical form: the comments a `.jxn` had are what `--drop-comments` agreed to lose.
+    return serializeProjectFile(parseProjectSource(text, path), null, targetOf(path, to));
+  }
+  return to === "jxn"
+    ? serializeJxn(parseJxDocument(text, path))
+    : `${JSON.stringify(parseJxn(text, path), null, 2)}\n`;
+}
+
+/**
+ * Convert documents in a project.
+ *
+ * @param root The project root.
+ * @param paths Files and directories, relative to the root.
+ * @param options What was asked.
+ */
+export async function convertDocuments(
+  root: string,
+  paths: readonly string[],
+  options: ConvertOptions,
+): Promise<ConvertRow[]> {
+  const { config } = loadProjectConfig(root);
+  const sources = collectionRoots(config);
+  const { formats } = await buildProjectExtensionRegistry(root, config);
+  const rows: ConvertRow[] = [];
+  for (const path of paths.flatMap((item) => expand(resolve(root, item)))) {
+    const from = relative(root, path);
+    const target = targetOf(path, options.to);
+    const row: ConvertRow = { from, references: 0, problem: null, to: relative(root, target) };
+    rows.push(row);
+    row.problem = await refusal(root, path, options, sources);
+    if (row.problem !== null) {
+      continue;
+    }
+    try {
+      const text = await converted(root, path, options.to);
+      if (options.dryRun) {
+        continue;
+      }
+      /* In place and then renamed, so a failure writing leaves the old name holding the old text or
+         the new, and nothing beside it to be mistaken for the document. */
+      await writeFile(path, text);
+      await rename(path, target);
+      if (isProjectFileAt(root, path)) {
+        continue;
+      }
+      const report = await applyRename({ absFrom: path, absTo: target, registry: formats, root });
+      row.references = report.references.filesChanged;
+      if (report.errors.length > 0) {
+        const unread = report.errors.map((item) => item.path).join(", ");
+        row.problem = `converted, and ${unread} could not be read, so a reference in it may still name the old path`;
+      }
+    } catch (error) {
+      row.problem = errorMessage(error);
+    }
+  }
+  return rows;
+}
+
+/** What `jx convert` was given. */
+export interface ConvertArgs extends ConvertOptions {
+  paths: string[];
+  root: string;
+}
+
+/**
+ * Read `jx convert`'s arguments.
+ *
+ * @param argv The arguments after the command.
+ * @returns What was asked, or null when it does not say.
+ */
+export function parseConvertArgs(argv: readonly string[]): ConvertArgs | null {
+  const paths: string[] = [];
+  let to: string | undefined;
+  let root = process.cwd();
+  const flags = new Set<string>();
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index] ?? "";
+    if (arg === "--to") {
+      index += 1;
+      to = argv[index];
+    } else if (arg === "--root") {
+      index += 1;
+      root = resolve(argv[index] ?? root);
+    } else if (arg.startsWith("--")) {
+      flags.add(arg);
+    } else {
+      paths.push(arg);
+    }
+  }
+  if ((to !== "json" && to !== "jxn") || paths.length === 0) {
+    return null;
+  }
+  return {
+    dropComments: flags.has("--drop-comments"),
+    dryRun: flags.has("--dry-run"),
+    paths,
+    root,
+    to,
+  };
+}
+
+/**
+ * Run `jx convert`.
+ *
+ * @param argv The arguments after the command.
+ * @param print Where the report goes.
+ * @returns The exit code: 1 when anything was left unconverted.
+ */
+export async function runConvert(
+  argv: readonly string[],
+  print: (line: string) => void = console.log,
+): Promise<number> {
+  const args = parseConvertArgs(argv);
+  if (!args) {
+    print("Usage: jx convert <paths…> --to jxn|json [--dry-run] [--drop-comments]");
+    return 2;
+  }
+  let rows: ConvertRow[];
+  try {
+    rows = await convertDocuments(args.root, args.paths, args);
+  } catch (error) {
+    // The project itself does not load, so there is nothing to convert in it.
+    print(errorMessage(error));
+    return 1;
+  }
+  for (const row of rows) {
+    if (row.problem !== null) {
+      print(`${row.from}: ${row.problem}`);
+    } else if (args.dryRun) {
+      print(`${row.from} would become ${row.to}`);
+    } else {
+      print(`${row.from} → ${row.to} (${row.references} file(s) repaired)`);
+    }
+  }
+  return rows.some((row) => row.problem !== null) ? 1 : 0;
+}
+
+if (import.meta.main) {
+  process.exitCode = await runConvert(process.argv.slice(2));
+}

package/src/data-api.ts

@@ -16,7 +16,7 @@
  * (kind "auth") after the connector plan inside {@link pushDataSchema}.
  */
 
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 import { Kysely, sql } from "kysely";
 import { buildProjectExtensionRegistry } from "@jxsuite/compiler/format-host";
@@ -53,6 +53,7 @@ import type {
   SecretsSetResponse,
 } from "@jxsuite/protocol";
 import { problem, problemTypeForStatus } from "./problem.ts";
+import { isSameStamp, projectFileStamp, readProjectFile } from "@jxsuite/schema/project-file/node";
 
 // ─── Local section shapes (structural — the connector owns the full types) ───
 
@@ -125,26 +126,30 @@ class ApiError extends Error {
 
 // ─── Project + registry resolution ───────────────────────────────────────────
 
-/** Per-project registry cache, invalidated when project.json's mtime moves. */
-const registryCache = new Map<string, { mtime: number; registry: Promise<ExtensionRegistry> }>();
+/** Per-project registry cache, invalidated when the project file moves or changes. */
+const registryCache = new Map<
+  string,
+  { mtime: number; path: string; registry: Promise<ExtensionRegistry> }
+>();
 
 /** Reset the registry cache (test hook). */
 export function resetDataApi(): void {
   registryCache.clear();
 }
 
-/** Read the project's config + connector-owned sections; 404 when there is no project.json. */
+/** Read the project's config + connector-owned sections; 404 when there is no project file. */
 function getProject(projectRoot: string): ProjectSections {
-  const path = resolve(projectRoot, "project.json");
-  let config: ProjectConfig;
-  try {
-    /* SAFETY: trust boundary. project.json is the project's own config, held to its per-project
-       schema by the editor and `jx validate`; the connections and data sections are narrowed
-       below, and unreadable or non-JSON text answers the 404 in the catch. */
-    config = JSON.parse(readFileSync(path, "utf8")) as ProjectConfig;
-  } catch (error) {
-    throw new ApiError(404, `No project.json under "${projectRoot}"`, { cause: error });
+  const read = readProjectFile(projectRoot);
+  if (!read) {
+    throw new ApiError(404, `No project file under "${projectRoot}"`);
   }
+  if ("error" in read) {
+    throw new ApiError(
+      404,
+      `The project file under "${projectRoot}" does not parse: ${read.error}`,
+    );
+  }
+  const { config } = read;
   /* Section keys are the connector's host wire contract (the same literals jx-mounts passes to
      the Data mount's options.sections) — JSON introspection, not a connector import.
      SAFETY: `connections` and `data` are the connector extension's sections, which its
@@ -156,16 +161,17 @@ function getProject(projectRoot: string): ProjectSections {
   return { config, connections, tables };
 }
 
-/** Build (or reuse) the project's extension registry, keyed on project.json's mtime. */
+/** Build (or reuse) the project's extension registry, keyed on the project file's stamp. */
 function getRegistry(projectRoot: string, config: ProjectConfig): Promise<ExtensionRegistry> {
-  const projectJsonPath = resolve(projectRoot, "project.json");
-  const mtime = statSync(projectJsonPath).mtimeMs;
+  const stamp = projectFileStamp(projectRoot);
   const cached = registryCache.get(projectRoot);
-  if (cached && cached.mtime === mtime) {
+  if (stamp && cached && isSameStamp(cached, stamp)) {
     return cached.registry;
   }
   const registry = buildProjectExtensionRegistry(projectRoot, config);
-  registryCache.set(projectRoot, { mtime, registry });
+  if (stamp) {
+    registryCache.set(projectRoot, { ...stamp, registry });
+  }
   return registry;
 }
 

package/src/dev.ts

@@ -22,6 +22,7 @@ import { problem } from "./problem.ts";
 import { callServerExport } from "./resolve.ts";
 import { createDevServer } from "./server.ts";
 import { injectSSE } from "./watch.ts";
+import { hasProjectFile } from "@jxsuite/schema/project-file/node";
 
 export interface DevArgs {
   port: number;
@@ -187,7 +188,7 @@ export interface DevServerHandle {
  * @returns {Promise<DevServerHandle>} The listening server
  */
 export async function startDev({ port, root }: DevArgs): Promise<DevServerHandle> {
-  const isSite = existsSync(join(root, "project.json"));
+  const isSite = hasProjectFile(root);
 
   let building = Promise.resolve();
   // What the last build collected, which the server-function route answers from.

package/src/extension-catalog.ts

@@ -31,6 +31,7 @@ import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { createNodeFormatIO, probeExtension } from "@jxsuite/compiler/format-host";
 import type { ExtensionCatalogEntry, ExtensionSectionInfo } from "@jxsuite/protocol";
 import type { JsonValue } from "@jxsuite/schema/types";
+import { projectFilePath } from "@jxsuite/schema/project-file/node";
 
 interface PackageJson {
   dependencies?: Record<string, string>;
@@ -91,7 +92,7 @@ async function loadEntry(
     const registry = await buildExtensionRegistry(
       [name],
       createNodeFormatIO(projectRoot),
-      resolve(projectRoot, "project.json"),
+      projectFilePath(projectRoot),
     );
     const [info] = registry.extensions;
     if (!info) {

package/src/import-api.ts

@@ -30,14 +30,15 @@
  */
 
 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";
+import type { ProjectConfig } from "@jxsuite/schema/types";
+import { parseProjectSource } from "@jxsuite/schema/project-file";
+import { projectFilePath } from "@jxsuite/schema/project-file/node";
 
 export interface ImportApiOptions {
   /**
@@ -86,7 +87,7 @@ type ImportStreamLine =
   | { type: "heartbeat" }
   | { type: "ready"; root: string }
   | ({ type: "progress" } & Omit<ImportProgressEvent, "root">)
-  | { type: "done"; root: string; config: JsonObject; result: ImportDoneSummary }
+  | { type: "done"; root: string; config: ProjectConfig; result: ImportDoneSummary }
   | { type: "error"; error: string };
 
 /** The AI pass's credentials, resolved from the request headers or the environment. */
@@ -298,11 +299,10 @@ async function handleImportSite(req: Request, opts: ImportApiOptions): Promise<R
           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 JsonObject;
+        // The import's emit phase has just written it; text that does not read throws into the
+        // Error line below.
+        const configPath = projectFilePath(result.outDir);
+        const config = parseProjectSource(await readFile(configPath, "utf8"), configPath);
         /*
          * 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

package/src/jx-mounts.ts

@@ -16,15 +16,16 @@
  * The runtime is cached per project root and invalidated when project.json changes on disk.
  */
 
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { resolve } from "node:path";
+import { readFileSync } from "node:fs";
 import { buildProjectExtensionRegistry } from "@jxsuite/compiler/format-host";
 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 { ImplementationExport, MountHandler } from "@jxsuite/schema/format-registry";
-import type { JxDocumentValue, ProjectConfig } from "@jxsuite/schema/types";
+import type { JxDocumentValue } from "@jxsuite/schema/types";
+import { parseProjectSource } from "@jxsuite/schema/project-file";
+import { isSameStamp, projectFileStamp } from "@jxsuite/schema/project-file/node";
 
 interface MountRuntime {
   handlers: { basePath: string; handler: MountHandler }[];
@@ -32,7 +33,10 @@ interface MountRuntime {
 }
 
 /** Per-project runtime cache, invalidated when project.json's mtime moves. */
-const runtimeCache = new Map<string, { mtime: number; runtime: Promise<MountRuntime | null> }>();
+const runtimeCache = new Map<
+  string,
+  { mtime: number; path: string; runtime: Promise<MountRuntime | null> }
+>();
 
 /** Reset the runtime cache (test hook). */
 export function resetJxMounts(): void {
@@ -81,35 +85,34 @@ export async function handleJxMounts(
 
 /** Load (or reuse) the mount runtime for a project root. */
 function getRuntime(projectRoot: string): Promise<MountRuntime | null> {
-  const projectJsonPath = resolve(projectRoot, "project.json");
-  if (!existsSync(projectJsonPath)) {
+  const stamp = projectFileStamp(projectRoot);
+  if (!stamp) {
     return Promise.resolve(null);
   }
-  const { mtimeMs } = statSync(projectJsonPath);
   const cached = runtimeCache.get(projectRoot);
-  if (cached && cached.mtime === mtimeMs) {
+  if (cached && isSameStamp(cached, stamp)) {
     return cached.runtime;
   }
-  const runtime = buildRuntime(projectRoot, projectJsonPath).catch((error) => {
+  const runtime = buildRuntime(projectRoot, stamp.path).catch((error) => {
     console.warn(
       `jx-mounts: failed to build extension mounts for ${projectRoot}:`,
       error instanceof Error ? error.message : String(error),
     );
     return null;
   });
-  runtimeCache.set(projectRoot, { mtime: mtimeMs, runtime });
+  runtimeCache.set(projectRoot, { ...stamp, runtime });
   return runtime;
 }
 
 /** Build the runtime: registry, sections, connector stand-ins, and the ordered mount handlers. */
 async function buildRuntime(
   projectRoot: string,
-  projectJsonPath: string,
+  projectFile: 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;
+  /* Trust boundary. The project file 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 = parseProjectSource(readFileSync(projectFile, "utf8"), projectFile);
   const registry = await buildProjectExtensionRegistry(projectRoot, config);
   const mounts = registry.serverMounts();
   if (mounts.length === 0) {

package/src/refactor/scan.ts

@@ -7,10 +7,20 @@
  * rename that rewrites a file the usage count never looked at is a lie in both directions.
  */
 
-import { extname } from "node:path";
+import { basename, extname } from "node:path";
 import { readFile } from "node:fs/promises";
 import type { FormatRegistry, ValueEdit } from "@jxsuite/schema/format-registry";
-import type { JsonValue } from "@jxsuite/schema/types";
+import { isJsonObject } from "@jxsuite/schema/guards";
+import { rewriteJson } from "@jxsuite/schema/json-layout";
+import {
+  classifyJxn,
+  isJxnPath,
+  parseJxn,
+  parseProject,
+  serializeJxn,
+  serializeProject,
+} from "@jxsuite/schema/jxn";
+import type { JsonValue, JxDocument, ProjectConfig } from "@jxsuite/schema/types";
 
 /** Normalise a path to forward slashes (Windows `path` returns backslashes). */
 export const fwd = (p: string) => p.replaceAll("\\", "/");
@@ -77,13 +87,35 @@ export function documentGlob(registry: FormatRegistry): string {
 export async function loadDoc(fp: string, registry: FormatRegistry): Promise<LoadedDoc> {
   const raw = await readFile(fp, "utf8");
   if (isJsonPath(fp)) {
-    const trailingNewline = raw.endsWith("\n");
     return {
       // 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" : "")),
+      // Over the text it replaces, so a rename changes the references and not the formatting.
+      serialize: (doc) => Promise.resolve(rewriteJson(doc, raw)),
+    };
+  }
+  if (basename(fp) === "project.jxn" && classifyJxn(raw) === "project") {
+    /* The project file, in its own grammar (`site-architecture.md` §2.3): a rename repairs the
+       references it holds, `defaults.layout` among them, and the merge keeps its comments. A page
+       named `project.jxn` declares no project, and is read as the document it is below. */
+    const config: unknown = parseProject(raw, fp);
+    return {
+      doc: isJsonObject(config) ? config : null,
+      rewrite: null,
+      // SAFETY: the configuration this just read, with reference values replaced by reference values.
+      serialize: (doc) => Promise.resolve(serializeProject(doc as ProjectConfig, raw)),
+    };
+  }
+  if (isJxnPath(fp)) {
+    /* The one format whose writer can be told what it is replacing, so repairing a reference in a
+       `.jxn` file changes that reference and leaves its comments where they were. */
+    const document = parseJxn(raw);
+    return {
+      doc: isJsonObject(document) ? document : null,
+      rewrite: null,
+      // SAFETY: the document this just read, with reference values replaced by reference values.
+      serialize: (doc) => Promise.resolve(serializeJxn(doc as JxDocument, raw)),
     };
   }
   const ext = extname(fp);

package/src/resolve.ts

@@ -4,7 +4,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 { readFileSync, statSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { projectDevEnv } from "./dev-vars.ts";
 import { containedPath } from "./net-guard.ts";
@@ -25,6 +25,8 @@ import type {
 } from "@jxsuite/schema/types";
 import type { ProjectDevEnv } from "./dev-vars.ts";
 import { problem } from "./problem.ts";
+import { parseProjectSource } from "@jxsuite/schema/project-file";
+import { isSameStamp, projectFileStamp } from "@jxsuite/schema/project-file/node";
 
 /**
  * Any value a module exports, as the proxies see it before they check it. Nothing about an export
@@ -193,7 +195,10 @@ function baseDirectory($base: string, root: string, projectRoot: string): string
  * 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> }>();
+const projectEntryCache = new Map<
+  string,
+  { mtime: number; path: string; entry: Promise<ProjectEntry | null> }
+>();
 
 /**
  * Lazy-load project context (project.json + extension-loaded sections) for class instantiation.
@@ -255,31 +260,30 @@ async function completeSections(context: ProjectContext): Promise<void> {
 
 /** 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");
-  const mtime = statSync(projectJsonPath, { throwIfNoEntry: false })?.mtimeMs;
-  if (mtime === undefined) {
+  const stamp = projectFileStamp(projectRoot);
+  if (!stamp) {
     return null;
   }
   const cached = projectEntryCache.get(projectRoot);
-  if (cached && cached.mtime === mtime) {
+  if (cached && isSameStamp(cached, stamp)) {
     return cached.entry;
   }
-  const entry = readProjectEntry(projectRoot, projectJsonPath, mtime);
-  projectEntryCache.set(projectRoot, { entry, mtime });
+  const entry = readProjectEntry(projectRoot, stamp.path, stamp.mtime);
+  projectEntryCache.set(projectRoot, { ...stamp, entry });
   return entry;
 }
 
-/** Read one `project.json` generation. Never rejects: any failure answers "no project context". */
+/** Read one project file generation. Never rejects: any failure answers "no project context". */
 async function readProjectEntry(
   projectRoot: string,
-  projectJsonPath: string,
+  projectFile: string,
   mtime: number,
 ): Promise<ProjectEntry | null> {
   try {
-    /* 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;
+    /* Trust boundary. The project file is the project's own config, 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 = parseProjectSource(readFileSync(projectFile, "utf8"), projectFile);
     const registry = await buildProjectExtensionRegistry(projectRoot, config);
     const { mounts } = await loadAssetMounts(registry, config, projectRoot);
     return { config, mounts, mtime, registry };

package/src/server.ts

@@ -42,6 +42,8 @@ import { handleCodeApi } from "./code-api.ts";
 import { handleAiApi } from "./ai-api.ts";
 import { handleImportApi } from "./import-api.ts";
 import { mediaTypeForPath } from "@jxsuite/schema/media-type";
+import { isJxnPath } from "@jxsuite/schema/jxn";
+import { jxnAsJson } from "@jxsuite/site/serve";
 import { problem } from "./problem.ts";
 
 import { resolveNpmPath } from "./npm-path.ts";
@@ -169,12 +171,21 @@ export async function createDevServer(options: {
   const NO_CACHE = { "Cache-Control": "no-cache" };
   /*
    * `Bun.file` already infers a type from the extension, and for almost everything it is right. The
-   * exceptions are the two RFCs Jx has an opinion about: `.md` comes back as bare `text/markdown`
+   * exceptions are the two RFCs Jx has an opinion about, and `.jxn`, which Bun has never heard of:
+   * `.md` comes back as bare `text/markdown`
    * with no `variant`, and `.yaml` comes back as `text/yaml`, the spelling RFC 9512 §5 asks
    * implementations to stop using. `mediaTypeForPath` answers null everywhere else, so the
    * inference stays in charge of the ordinary cases.
    */
-  const fileResponse = (file: ReturnType<typeof Bun.file>) => {
+  const fileResponse = async (file: ReturnType<typeof Bun.file>) => {
+    if (file.name !== undefined && isJxnPath(file.name)) {
+      /* The canvas runtime fetches a `$ref` and reads it as JSON, as a site origin answers it
+         (`@jxsuite/site` `serve.ts`); Studio reads a file's text through `/__studio/file`. */
+      return jxnAsJson(await file.bytes(), file.name, (type) => ({
+        ...NO_CACHE,
+        "Content-Type": type,
+      }));
+    }
     const corrected = file.name === undefined ? null : mediaTypeForPath(file.name);
     return new Response(file, {
       headers: corrected === null ? NO_CACHE : { ...NO_CACHE, "Content-Type": corrected },

package/src/site-output.ts

@@ -30,12 +30,13 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { isJsonObject, isString } from "@jxsuite/schema/guards";
-import type { JsonValue } from "@jxsuite/schema/types";
 
 import { serveContained } from "./net-guard.ts";
+import { parseProjectSource } from "@jxsuite/schema/project-file";
+import { isSameStamp, projectFileStamp } from "@jxsuite/schema/project-file/node";
 
 /** What `project.json` says the build writes to, cached per root against its mtime. */
-const outDirCache = new Map<string, { mtime: number; outDir: string | null }>();
+const outDirCache = new Map<string, { mtime: number; outDir: string | null; path: string }>();
 
 /** Reset the output-directory cache (test hook). */
 export function resetSiteOutput(): void {
@@ -51,32 +52,27 @@ export function resetSiteOutput(): void {
  * file read.
  */
 export function siteOutDir(projectRoot: string): string | null {
-  const configPath = resolve(projectRoot, "project.json");
-  if (!existsSync(configPath)) {
+  // Both project files is no project until the editor's report is acted on, so this declines.
+  const stamp = projectFileStamp(projectRoot);
+  if (!stamp) {
     return null;
   }
-  const { mtimeMs } = statSync(configPath);
   const cached = outDirCache.get(projectRoot);
-  if (cached && cached.mtime === mtimeMs) {
+  if (cached && isSameStamp(cached, stamp)) {
     return cached.outDir;
   }
   let outDir: string | null = null;
   try {
-    // SAFETY: JSON.parse without a reviver only ever yields a JSON value; its `any` says no more.
-    const config = JSON.parse(readFileSync(configPath, "utf8")) as JsonValue;
+    const config: unknown = parseProjectSource(readFileSync(stamp.path, "utf8"), stamp.path);
     const build = isJsonObject(config) ? config.build : undefined;
     const declared = isJsonObject(build) ? build.outDir : undefined;
-    // A `null` document has no settings to read at all, so it declines like an unparseable one.
-    outDir =
-      config === null
-        ? null
-        : resolve(projectRoot, isString(declared) && declared ? declared : "dist");
+    outDir = resolve(projectRoot, isString(declared) && declared ? declared : "dist");
   } catch {
-    // An unparseable project.json is the editor's problem to report, not this server's to guess
+    // An unparseable project file is the editor's problem to report, not this server's to guess
     // At. No output directory means this fallback simply declines, and the request 404s as before.
     outDir = null;
   }
-  outDirCache.set(projectRoot, { mtime: mtimeMs, outDir });
+  outDirCache.set(projectRoot, { ...stamp, outDir });
   return outDir;
 }
 

package/src/studio-api.ts

@@ -48,6 +48,21 @@ import type { JsonObject, JsonPrimitive, JsonValue, ProjectConfig } from "@jxsui
 import { isFunction, isJsonObject, isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { problem } from "./problem.ts";
 import { scanFiles } from "./fs-glob.ts";
+import {
+  PROJECT_FILE_NAMES,
+  classifyProjectFile,
+  parseProjectFile,
+  parseProjectSource,
+  projectFileConflict,
+} from "@jxsuite/schema/project-file";
+import {
+  findEnclosingProjectOnDisk,
+  hasProjectFile,
+  isSameStamp,
+  projectFilePath,
+  projectFileStamp,
+  readProjectFile,
+} from "@jxsuite/schema/project-file/node";
 
 /** Normalise a path to forward slashes (Windows `path` module returns backslashes). */
 const fwd = (p: string) => p.replaceAll("\\", "/");
@@ -96,11 +111,11 @@ interface Cem {
   modules?: CemModule[];
 }
 
-// ─── Extension registry (per project root, invalidated on project.json change) ──
+// ─── Extension registry (per project root, invalidated on a project file change) ──
 
 const extensionRegistryCache = new Map<
   string,
-  { mtime: number; missing: string[]; registry: ExtensionRegistry }
+  { mtime: number; missing: string[]; path: string; registry: ExtensionRegistry }
 >();
 
 /**
@@ -115,26 +130,23 @@ const extensionRegistryCache = new Map<
  * @returns {Promise<ExtensionRegistry>}
  */
 async function getExtensionRegistry(projectRoot: string): Promise<ExtensionRegistry> {
-  const projectJsonPath = resolve(projectRoot, "project.json");
-  let mtime = 0;
+  const stamp = projectFileStamp(projectRoot) ?? { mtime: 0, path: "" };
   let projectConfig: ProjectConfig | undefined;
   try {
-    mtime = statSync(projectJsonPath).mtimeMs;
-    /* SAFETY: buildProjectExtensionRegistry reads only `projectConfig?.extensions` and validates
-       that list itself; every other ProjectConfig member is optional and unread on this path. */
-    projectConfig = JSON.parse(readFileSync(projectJsonPath, "utf8")) as ProjectConfig;
+    // The registry reads only `projectConfig?.extensions`, and checks that list itself.
+    projectConfig = parseProjectSource(readFileSync(stamp.path, "utf8"), stamp.path);
   } catch {
     projectConfig = undefined;
   }
   const cached = extensionRegistryCache.get(projectRoot);
-  if (cached && cached.mtime === mtime && !anyNowInstalled(projectRoot, cached.missing)) {
+  if (cached && isSameStamp(cached, stamp) && !anyNowInstalled(projectRoot, cached.missing)) {
     return cached.registry;
   }
   const { missing, registry } = await buildInstalledExtensionRegistry(projectRoot, projectConfig);
   if (missing.length > 0 && missing.join("\n") !== cached?.missing.join("\n")) {
     console.warn(`[studio] ${missingExtensionsNotice(missing)}`);
   }
-  extensionRegistryCache.set(projectRoot, { missing, mtime, registry });
+  extensionRegistryCache.set(projectRoot, { ...stamp, missing, registry });
   return registry;
 }
 
@@ -211,7 +223,7 @@ export function isOwnedProjectDir(dir: string): boolean {
   if (containedPath(dir, resolve(home)) === null) {
     return false;
   }
-  return existsSync(resolve(dir, "project.json"));
+  return hasProjectFile(dir);
 }
 
 /**
@@ -509,23 +521,26 @@ export async function handleStudioApi(
 
       let isSiteProject = false;
       let projectConfig: ProjectConfig | null = null;
-      try {
-        // SAFETY: JSON.parse without a reviver only ever produces JSON values.
-        const raw = JSON.parse(
-          await readFile(resolve(absDir, "project.json"), "utf8"),
-        ) as JsonValue;
-        if (isJsonObject(raw)) {
-          isSiteProject = true;
-          /* SAFETY: `raw` is a JSON object and every ProjectConfig member is optional; the config
-             is only relayed to the client here, never interpreted. */
-          projectConfig = raw as ProjectConfig;
-        }
-      } catch {}
+      let projectProblem: string | null = null;
+      const read = readProjectFile(absDir);
+      const verdict = read ? classifyProjectFile(read.text, read.path) : null;
+      if (read && "config" in read && verdict === "project") {
+        isSiteProject = true;
+        // Relayed to the client here, never interpreted.
+        projectConfig = read.config;
+      } else if (read && "error" in read && verdict !== "other" && read.text !== "") {
+        /* A file that does not read is believed, as the walk believes it (desktop.md §4.6), and
+           opened with no configuration so the client can show it as text. A folder holding both
+           files has no text to show, and stays what it was. */
+        isSiteProject = true;
+        projectProblem = read.error;
+      }
 
       return Response.json({
         directories,
         isSiteProject,
         projectConfig,
+        ...(projectProblem !== null && { projectProblem }),
         projectRoot,
       });
     } catch (error) {
@@ -543,38 +558,30 @@ export async function handleStudioApi(
       // Walk up looking for project.json. Accept a directory (e.g. the project root itself, as
       // Deep links like ?project=/abs/my-site pass) by starting the walk AT the directory and
       // Treating its project.json as the target file, so callers land on the home page.
-      let absFile = expandTilde(filePath);
-      let dir: string;
+      const absFile = expandTilde(filePath);
       let isDir = false;
       try {
         isDir = statSync(absFile).isDirectory();
       } catch {}
-      if (isDir) {
-        dir = absFile;
-        absFile = resolve(absFile, "project.json");
-      } else {
-        dir = dirname(absFile);
-      }
-      while (dir) {
-        const candidate = resolve(dir, "project.json");
-        if (existsSync(candidate)) {
-          /* SAFETY: the config is relayed to the client verbatim and not interpreted here, so its
-             member types are the client's to check; malformed JSON throws into the catch below. */
-          const config = JSON.parse(readFileSync(candidate, "utf8")) as ProjectConfig;
-          const relPath = fwd(dir);
-          const fileRelPath = fwd(relative(dir, absFile));
-          return Response.json({
-            fileRelPath,
-            projectConfig: config,
-            relPath,
-            sitePath: dir,
-          });
-        }
-        const parent = dirname(dir);
-        if (parent === dir) {
-          break;
-        }
-        dir = parent;
+      // A page named project.json is not a project, and neither is Nx's file of that name.
+      const found = findEnclosingProjectOnDisk(isDir ? absFile : dirname(absFile));
+      if (found?.verdict === "conflict") {
+        return problem("conflict", projectFileConflict(found.root));
+      }
+      if (found) {
+        /* Relayed to the client and not interpreted here. A file that does not read is still the
+           project's (site-architecture.md §2.3): the client opens it with no configuration, says
+           where the file fails and shows it as text, rather than finding no project at all. */
+        const read = parseProjectFile(found.projectFile, readFileSync(found.projectFile, "utf8"));
+        // A folder is asked for as its project file, which the client reads as "go home".
+        const asked = isDir ? join(absFile, basename(found.projectFile)) : absFile;
+        return Response.json({
+          fileRelPath: fwd(relative(found.root, asked)),
+          projectConfig: "config" in read ? read.config : null,
+          ...("error" in read && { projectProblem: read.error }),
+          relPath: fwd(found.root),
+          sitePath: found.root,
+        });
       }
       return Response.json({ sitePath: null });
     } catch (error) {
@@ -585,8 +592,8 @@ export async function handleStudioApi(
   // Discover site projects — find all project.json files under root
   if (path === "/__studio/sites" && req.method === "GET") {
     try {
-      const sites = [];
-      for await (const match of scanFiles("**/project.json", root)) {
+      const sites: { config: ProjectConfig; path: string; problem?: string }[] = [];
+      for await (const match of scanFiles(`**/{${PROJECT_FILE_NAMES.join(",")}}`, root)) {
         if (
           match.includes("node_modules") ||
           fwd(match).includes("dist/") ||
@@ -596,13 +603,18 @@ export async function handleStudioApi(
         }
         const fp = resolve(root, match);
         try {
-          // SAFETY: JSON.parse without a reviver only ever produces JSON values.
-          const raw = JSON.parse(await readFile(fp, "utf8")) as JsonValue;
-          if (isJsonObject(raw)) {
+          const text = await readFile(fp, "utf8");
+          if (classifyProjectFile(text, fp) === "project") {
             const projectDir = fwd(dirname(fp));
-            /* SAFETY: `raw` is a JSON object and every ProjectConfig member is optional; the site
-               list only relays the config to the client. */
-            sites.push({ config: raw as ProjectConfig, path: projectDir });
+            // The site list only relays the config to the client.
+            const config = parseProjectSource(text, fp);
+            const twin = sites.find((site) => site.path === projectDir);
+            if (twin) {
+              // Neither file is the project's, so the list says so rather than choosing.
+              twin.problem = projectFileConflict(projectDir);
+            } else {
+              sites.push({ config, path: projectDir });
+            }
           }
         } catch {}
       }
@@ -692,11 +704,9 @@ export async function handleStudioApi(
       }
       await generateProject(destPath, projectOptions);
 
-      /* SAFETY: generateProject just wrote this project.json from its own template, so it is a
-         project config; it is relayed to the client, not interpreted here. */
-      const config = JSON.parse(
-        await readFile(resolve(destPath, "project.json"), "utf8"),
-      ) as ProjectConfig;
+      // It was just written by generateProject, and is relayed to the client, not interpreted.
+      const configPath = projectFilePath(destPath);
+      const config = parseProjectSource(await readFile(configPath, "utf8"), configPath);
       // Root-relative while the project happens to sit under the server root (the historical
       // Shape every caller already handles); absolute otherwise.
       const inRoot = containedPath(destPath, root) !== null;
@@ -939,7 +949,7 @@ export async function handleStudioApi(
    */
   if (path === "/__studio/build" && req.method === "POST") {
     const dir = activeProjectRoot ?? root;
-    if (!existsSync(resolve(dir, "project.json"))) {
+    if (!hasProjectFile(dir)) {
       return problem("invalidRequest", "Not a site project");
     }
     try {
@@ -971,7 +981,7 @@ export async function handleStudioApi(
    */
   if (path === "/__studio/preview" && req.method === "POST") {
     const dir = activeProjectRoot ?? root;
-    if (!existsSync(resolve(dir, "project.json"))) {
+    if (!hasProjectFile(dir)) {
       return problem("invalidRequest", "Not a site project");
     }
     let body: { route?: string };