@jxsuite/server 4.0.0 → 4.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -18,6 +18,7 @@
     "./ai-api": "./src/ai-api.ts",
     "./data": "./src/data-api.ts",
     "./import-api": "./src/import-api.ts",
+    "./catalog": "./src/extension-catalog.ts",
     "./packages": "./src/packages.ts",
     "./project-server": "./src/project-server.ts",
     "./oauth-loopback": "./src/oauth-loopback.ts",
@@ -39,22 +40,23 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/collab": "^0.8.4",
-    "@jxsuite/compiler": "^3.0.0",
-    "@jxsuite/create": "^1.3.8",
-    "@jxsuite/import": "^0.40.0",
-    "@jxsuite/protocol": "^2.1.0",
-    "@jxsuite/runtime": "^3.0.0",
-    "@jxsuite/schema": "^2.0.0",
-    "@jxsuite/site": "^1.0.0",
-    "@jxsuite/starters": "^1.6.5",
+    "@jxsuite/catalog": "^0.1.0",
+    "@jxsuite/collab": "^0.9.0",
+    "@jxsuite/compiler": "^4.0.0",
+    "@jxsuite/create": "^1.3.10",
+    "@jxsuite/import": "^0.40.2",
+    "@jxsuite/protocol": "^2.3.0",
+    "@jxsuite/runtime": "^4.0.0",
+    "@jxsuite/schema": "^2.2.0",
+    "@jxsuite/site": "^2.0.0",
+    "@jxsuite/starters": "^1.8.0",
     "chokidar": "^5.0.0",
     "kysely": "^0.29.5",
-    "zod": "^4.4.3"
+    "zod": "^4.6.4"
   },
   "devDependencies": {
-    "@jxsuite/auth": "^0.5.6",
-    "@jxsuite/connector": "^0.5.6",
-    "@jxsuite/parser": "^1.6.0"
+    "@jxsuite/auth": "^0.6.0",
+    "@jxsuite/connector": "^0.6.0",
+    "@jxsuite/parser": "^1.8.0"
   }
 }

package/src/ai-api.ts

@@ -38,7 +38,14 @@ interface ToolCallDelta {
 interface OpenAIStreamChunk {
   choices?: {
     index?: number;
-    delta?: { content?: string; tool_calls?: ToolCallDelta[] };
+    delta?: {
+      content?: string;
+      /** Thinking models' chain-of-thought: DeepSeek/Volcengine spell it this way… */
+      reasoning_content?: string;
+      /** …and OpenRouter this way. Both carry the same thing. */
+      reasoning?: string;
+      tool_calls?: ToolCallDelta[];
+    };
     finish_reason?: string | null;
   }[];
 }
@@ -350,6 +357,15 @@ export async function handleChat(req: Request): Promise<Response> {
               writeSSE(controller, { type: "delta", content: delta.content });
             }
 
+            /* Chain-of-thought, under either of the two names providers give it. Forwarded rather
+               than dropped: DeepSeek's thinking mode requires every prior turn's reasoning back on
+               any request carrying `tools`, so a proxy that swallows these frames makes the NEXT
+               round a 400 the client cannot repair. */
+            const reasoning = delta.reasoning_content ?? delta.reasoning;
+            if (typeof reasoning === "string" && reasoning) {
+              writeSSE(controller, { type: "reasoning", content: reasoning });
+            }
+
             // Tool calls
             if (delta.tool_calls) {
               for (const tc of delta.tool_calls) {

package/src/extension-catalog.ts

@@ -0,0 +1,218 @@
+/**
+ * Catalog — what THIS backend can offer a project (specs/extensions.md §9.2).
+ *
+ * The available half of the pair whose enabled half is `buildExtensionsPayload`. Two sources, and
+ * the split is the point:
+ *
+ * 1. The shipped first-party catalogue (`@jxsuite/catalog`), which is data generated from the
+ *    `extensions/` tree, so core keeps no dependency on an extension package (§2).
+ * 2. The project's own dependencies, scanned for anything exporting a `jx-extension.json`.
+ *
+ * Both are then annotated with two facts only a backend holds: whether the PROJECT resolves the
+ * package, and whether THIS HOST does. Those are probed rather than declared, because what a
+ * desktop build stages and what a Worker bundles are different facts and neither is knowable from a
+ * package list — which is also why the catalogue is a platform capability instead of a constant.
+ *
+ * **`installed` is answered here rather than by the client**, because `listPackages` does not mean
+ * one thing across backends: the dev server's own packages route drops a declared dependency it
+ * cannot resolve under `node_modules`, while desktop's reads the manifest and keeps it. A surface
+ * deciding "do I need to install this first?" from that would be right on one backend and wrong on
+ * the other.
+ *
+ * @docs extending/extensions/first-party
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { listCatalog } from "@jxsuite/catalog";
+import { buildExtensionRegistry } from "@jxsuite/schema/extension-registry";
+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";
+
+interface PackageJson {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  jx?: string;
+}
+
+/** Read a project's package.json, or null when it has none or it will not parse. */
+function readPackageJson(projectRoot: string): PackageJson | null {
+  const path = resolve(projectRoot, "package.json");
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as PackageJson;
+  } catch {
+    // A project mid-edit should cost the catalogue its discovered half, not the whole response.
+    return null;
+  }
+}
+
+/** Every dependency name a project declares, runtime and dev alike. */
+function declaredDependencies(projectRoot: string): string[] {
+  const pkg = readPackageJson(projectRoot);
+  return pkg === null
+    ? []
+    : [...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})];
+}
+
+/**
+ * Load one extension through the REGISTRY rather than reading its manifest directly.
+ *
+ * Discovery and enablement then agree by construction: this is the same loader `project.json` will
+ * run, so a package that builds here is one that will build there, and a package that throws here
+ * throws with the message that names the fix. `FormatEntry`'s constructor is pure data and never
+ * imports an implementation module, so this stays JSON reads.
+ *
+ * @param {string} projectRoot
+ * @param {string} name - Bare package specifier
+ * @returns {Promise<{ sections; formats; title?; description? } | { problem: string }>}
+ */
+async function loadEntry(
+  projectRoot: string,
+  name: string,
+): Promise<
+  | { description?: string; formats: string[]; sections: ExtensionSectionInfo[]; title?: string }
+  | { problem: string }
+> {
+  try {
+    const registry = await buildExtensionRegistry(
+      [name],
+      createNodeFormatIO(projectRoot),
+      resolve(projectRoot, "project.json"),
+    );
+    const [info] = registry.extensions;
+    if (!info) {
+      return { problem: `"${name}" did not load as an extension` };
+    }
+    const sections: ExtensionSectionInfo[] = [];
+    const formats = new Set<string>();
+    for (const cls of info.classes) {
+      if (cls.project) {
+        const { key, title } = cls.project;
+        sections.push({ key, ...(typeof title === "string" ? { title } : {}) });
+      }
+      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 }),
+    };
+  } catch (error) {
+    return { problem: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/**
+ * Whether a package that failed to resolve nonetheless MEANT to be an extension.
+ *
+ * `"jx"` is not what a host resolves — the registry goes through the exports map and nothing else,
+ * which is why the probe is authoritative. But reading it separates "this package got its exports
+ * map wrong" from "this package is not an extension", and that is the difference between a silent
+ * omission and a row that says what is broken. It is the first job the field has ever had.
+ *
+ * @param {string} projectRoot
+ * @param {string} name
+ * @returns {boolean}
+ */
+function declaresJxField(projectRoot: string, name: string): boolean {
+  const path = resolve(projectRoot, "node_modules", name, "package.json");
+  if (!existsSync(path)) {
+    return false;
+  }
+  try {
+    return typeof (JSON.parse(readFileSync(path, "utf8")) as PackageJson).jx === "string";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The catalogue for one project: the shipped first-party entries, then anything its own
+ * dependencies declare.
+ *
+ * Every first-party entry is returned whether or not the project has it, because the whole purpose
+ * is to advertise what could be turned on. A discovered entry is only ever one the project already
+ * depends on.
+ *
+ * @param {string} projectRoot - Absolute path to the project
+ * @returns {Promise<ExtensionCatalogEntry[]>}
+ */
+export async function buildExtensionCatalog(projectRoot: string): Promise<ExtensionCatalogEntry[]> {
+  const entries: ExtensionCatalogEntry[] = [];
+  const seen = new Set<string>();
+
+  for (const meta of listCatalog()) {
+    seen.add(meta.name);
+    const found = probeExtension(projectRoot, meta.name);
+    entries.push({
+      description: meta.description,
+      docs: meta.docs,
+      installed: found.project,
+      name: meta.name,
+      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 } : {}),
+    });
+  }
+
+  for (const name of declaredDependencies(projectRoot)) {
+    if (seen.has(name)) {
+      continue;
+    }
+    seen.add(name);
+    const found = probeExtension(projectRoot, name);
+    if (!found.project) {
+      if (declaresJxField(projectRoot, name)) {
+        entries.push({
+          installed: true,
+          name,
+          problem:
+            `declares "jx" but does not export "./${MANIFEST}", so no host can resolve its ` +
+            `manifest — add that entry to its exports map`,
+          sections: [],
+          source: "project",
+        });
+      }
+      continue;
+    }
+    const loaded = await loadEntry(projectRoot, name);
+    if ("problem" in loaded) {
+      entries.push({
+        installed: true,
+        name,
+        problem: loaded.problem,
+        sections: [],
+        source: "project",
+      });
+      continue;
+    }
+    entries.push({
+      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 } : {}),
+    });
+  }
+
+  return entries;
+}

package/src/refactor/apply.ts

@@ -122,7 +122,7 @@ export async function applyRename(opts: ApplyRenameOptions): Promise<RenameRepor
     }
     const fp = fwd(resolve(opts.root, match));
     try {
-      const { doc, serialize } = await loadDoc(fp, opts.registry);
+      const { doc, rewrite, serialize } = await loadDoc(fp, opts.registry);
       const docNewDir = dirname(fp);
       const docOldDir = isUnder(fp, absTo) ? dirname(absFrom + fp.slice(absTo.length)) : docNewDir;
 
@@ -139,11 +139,29 @@ export async function applyRename(opts: ApplyRenameOptions): Promise<RenameRepor
       if (changes.length === 0 && tagCount === 0) {
         continue;
       }
-      if (!serialize) {
+      /*
+       * Two ways to write a document back, and the narrower one is not a fallback for a broken
+       * format — it is the only honest promise a load-only format can make. A CSV collection has a
+       * parser and deliberately no serializer, so a reference living in one used to be COUNTED and
+       * then reported as a remainder the author had to repair by hand (issue 246). `rewrite`
+       * replaces the authored values in the file's own bytes and changes nothing else, which is all
+       * a rename ever needed.
+       *
+       * `serialize` still wins where it exists: a full round trip can express a change a list of
+       * value edits cannot. A TAG rename is exactly such a change, so a document carrying one and
+       * no serializer is still named in the report rather than half-written.
+       */
+      const written =
+        serialize === null
+          ? tagCount === 0 && rewrite !== null
+            ? await rewrite(changes)
+            : null
+          : await serialize(doc);
+      if (written === null) {
         report.errors.push({ error: `No serializer for "${match}"`, path: fwd(match) });
         continue;
       }
-      await writeFile(fp, await serialize(doc));
+      await writeFile(fp, written);
 
       if (changes.length > 0) {
         report.references.files.push({ changes, count: changes.length, path: fwd(match) });

package/src/refactor/mounts.ts

@@ -19,6 +19,14 @@
  * dropped: its files are not addressable by a project-relative path, so no rename can reach them
  * and no reference to them can be counted. `projectPathsForSiteUrl` declines the same case by
  * name.
+ *
+ * That drop is deliberate and is not the near half of a bug. A collection's `source` may point
+ * outside the project (site-architecture.md §9.3), and its media renders — the compiler and the dev
+ * server both publish it at the mount URL — but the editing host's file API is project-scoped by
+ * containment check, so no surface can list, open or ask about the file either. Nothing therefore
+ * reports a confident zero about it, which is the failure the lane math exists to prevent. Reaching
+ * such a file means giving it a mount-relative identity in that file API, not widening this filter;
+ * see §9.3, which records the decision (issue 244).
  */
 
 import { relative } from "node:path";

package/src/refactor/paths.ts

@@ -179,7 +179,7 @@ const FILE_SEGMENT_RE = /^[^.][^/]*\.[A-Za-z0-9]{0,7}[A-Za-z][A-Za-z0-9]{0,7}$/;
 /**
  * True when a string is shaped like a file a document could reference.
  *
- * The walker in refs.ts knows nine keys that carry references by name. The commonest media
+ * The walker in refs.ts knows eleven keys that carry references by name. The commonest media
  * reference in a real project is under none of them — a schema-typed component prop (`$props.bg`),
  * a content entry's frontmatter (`cover:`), `project.json`'s `defaults.layout` — so the walker
  * falls back to SHAPE for every other key, and this is the shape test.
@@ -210,6 +210,19 @@ export function looksLikeFileRef(value: string): boolean {
   return FILE_SEGMENT_RE.test(last);
 }
 
+/**
+ * Restore a trailing slash the path math dropped, when the author wrote one.
+ *
+ * `normalizeSegments` discards empty segments, so `./content/posts/` resolves and re-emits as
+ * `./content/posts`. For a file that is invisible; for a DIRECTORY reference — a content
+ * collection's `source` — it is a gratuitous edit to a line the rename had no business restyling,
+ * and `rewriteRef`'s contract is to preserve the authored style. A bare `/` is left alone: it is
+ * already only a slash.
+ */
+function keepTrailingSlash(out: string, core: string): string {
+  return core.endsWith("/") && core !== "/" && !out.endsWith("/") ? `${out}/` : out;
+}
+
 /** Context describing a single rename, shared by every reference rewrite within one document. */
 export interface RemapCtx {
   /** Absolute POSIX project root. */
@@ -269,7 +282,7 @@ export function rewriteRef(
   } else {
     out = rel;
   }
-  out += suffix;
+  out = keepTrailingSlash(out, core) + suffix;
   return out === core + suffix ? null : out;
 }
 
@@ -301,7 +314,7 @@ function rewriteSiteUrl(core: string, suffix: string, ctx: RemapCtx): string | n
     if (url === null) {
       continue;
     }
-    const out = url + suffix;
+    const out = keepTrailingSlash(url, core) + suffix;
     return out === core + suffix ? null : out;
   }
   return null;

package/src/refactor/refs.ts

@@ -14,6 +14,12 @@
  * `rewriteRef`'s resolve-and-compare gate in paths.ts: a reference is only rewritten (or counted as
  * a usage) when it actually resolves to the file in question.
  *
+ * **A reference is not always a value.** Three of the four visit helpers offer a value under a
+ * container-plus-position; {@link visitKeys} offers a map's KEYS, because `project.json`'s `copy`
+ * map names the files it copies there. Everything downstream is unchanged — a key is renamed by the
+ * same visitor returning the same kind of string — but the fourth shape had to exist before the
+ * walk could see the reference at all (issue 242).
+ *
  * The visitor seam is what stops the read side from being a second, drifting copy of the key list.
  * A new reference-bearing key added below is a key the usage count sees on the same commit.
  *
@@ -40,8 +46,10 @@ export interface RewriteResult {
  *
  * @param value — the raw authored reference, exactly as written.
  * @param refType — which key carried it (`$ref`, `$layout`, `attr`, `imports`, `$elements`, `url`,
- *   or `path` for a value matched by shape rather than by key name).
- * @param rootRelativeBare — whether a bare value resolves against the project root (`$layout`).
+ *   `source`, `copy` for a map KEY naming a copied file, or `path` for a value matched by shape
+ *   rather than by key name).
+ * @param rootRelativeBare — whether a bare value resolves against the project root (`$layout`,
+ *   `copy`).
  * @returns A replacement string to write back, or `null` to leave the document untouched.
  */
 export type RefVisitor = (
@@ -82,6 +90,41 @@ function visitScalar(
   }
 }
 
+/**
+ * Offer every KEY of a map to the visitor, renaming in place and preserving insertion order.
+ *
+ * The fourth visit helper, and the only one whose reference is not a value. `project.json`'s `copy`
+ * map names its sources in its keys (`{"assets/brochure.pdf": "brochure.pdf"}`), so a walk that
+ * only ever offered values could not see them at all — renaming a copied file reported zero
+ * references and rewrote nothing (issue 242).
+ *
+ * Order is preserved by rebuilding rather than by deleting one key and re-adding it: a plain
+ * `delete` + set moves the renamed entry to the end, which is a diff on a file nobody edited. When
+ * a rename collides with an existing key the later entry wins, exactly as an authored duplicate
+ * would.
+ */
+function visitKeys(
+  container: Record<string, unknown>,
+  refType: string,
+  visit: RefVisitor,
+  rootRelativeBare: boolean,
+): void {
+  const entries = Object.entries(container);
+  const renamed = entries.map(([key, value]): [string, unknown] => {
+    const out = visit(key, refType, rootRelativeBare);
+    return [out === null ? key : out, value];
+  });
+  if (renamed.every(([key], i) => key === entries[i]![0])) {
+    return;
+  }
+  for (const [key] of entries) {
+    delete container[key];
+  }
+  for (const [key, value] of renamed) {
+    container[key] = value;
+  }
+}
+
 /** Offer a string array member (e.g. an `$elements` entry) to the visitor. */
 function visitIndexed(arr: unknown[], index: number, refType: string, visit: RefVisitor): void {
   const value = arr[index];
@@ -203,6 +246,35 @@ export function walkDocRefs(node: unknown, visit: RefVisitor): void {
         walkStyle(value, visit);
         break;
       }
+      case "copy": {
+        /*
+         * `project.json`'s declarative copy map (site-architecture.md §5). Its KEYS are project
+         * files and its VALUES are destinations inside `outDir` — a directory the project does not
+         * contain and a rename can never move. So the key is visited and the value deliberately is
+         * not: offering the value to the shape fallback, which is what happened before, meant
+         * renaming a file at the project root could rewrite an unrelated copy DESTINATION that
+         * merely shared its name.
+         */
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          visitKeys(value as Record<string, unknown>, "copy", visit, true);
+        }
+        break;
+      }
+      case "source": {
+        /*
+         * A content collection's source (site-architecture.md §6), which may name a single file
+         * (`./content/listings.csv`) or a DIRECTORY (`./content/posts/`).
+         *
+         * Named rather than left to the shape fallback because a directory has no extension, and
+         * the extension test is exactly what keeps that fallback from admitting every route and
+         * bare word. Here the key is known and the value's shape is not diagnostic, so the value is
+         * offered unconditionally and precision stays where it always was — the caller's
+         * resolve-and-compare gate, which only matches a value resolving to the file or directory
+         * in question. A remote `https://…` source is filtered by `classifyRef` before that.
+         */
+        visitScalar(obj, key, "source", visit, false);
+        break;
+      }
       /*
        * Everything else, by SHAPE.
        *

package/src/refactor/scan.ts

@@ -14,10 +14,28 @@ import type { FormatRegistry } from "@jxsuite/schema/format-registry";
 /** Normalise a path to forward slashes (Windows `path` returns backslashes). */
 export const fwd = (p: string) => p.replaceAll("\\", "/");
 
-/** A parsed document plus the serializer that round-trips it back to disk (null when none). */
+/** 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;
+  /** Round-trips the whole document. Null when the format declares no `serialize`. */
   serialize: ((doc: unknown) => Promise<string>) | null;
+  /**
+   * Replaces authored values in the file's own bytes, changing nothing else. Null when the format
+   * declares no `rewrite`.
+   *
+   * The narrower of the two, and the only one a load-only format can offer: a CSV collection is a
+   * data source entries are read FROM, so there is no document to serialize — but one cell's text
+   * can be changed without inventing a quoting style. `applyRename` prefers `serialize` where it
+   * exists, because a full round trip can express a change (a tag rename) that a list of value
+   * edits cannot.
+   */
+  rewrite: ((edits: readonly ValueEdit[]) => Promise<string>) | null;
 }
 
 const isJsonPath = (p: string) => p.endsWith(".json");
@@ -58,8 +76,8 @@ export function documentGlob(registry: FormatRegistry): Bun.Glob {
 }
 
 /**
- * Read + parse a file, returning the doc and a matching serializer (null when the format can parse
- * but not serialize). Throws when no parser claims the extension.
+ * Read + parse a file, returning the doc and whichever write-back paths the format declares. Throws
+ * when no parser claims the extension.
  */
 export async function loadDoc(fp: string, registry: FormatRegistry): Promise<LoadedDoc> {
   const raw = await readFile(fp, "utf8");
@@ -67,6 +85,7 @@ export async function loadDoc(fp: string, registry: FormatRegistry): Promise<Loa
     const trailingNewline = raw.endsWith("\n");
     return {
       doc: JSON.parse(raw) as unknown,
+      rewrite: null,
       serialize: (doc) =>
         Promise.resolve(JSON.stringify(doc, null, 2) + (trailingNewline ? "\n" : "")),
     };
@@ -78,8 +97,15 @@ export async function loadDoc(fp: string, registry: FormatRegistry): Promise<Loa
   }
   const doc = await parseEntry.call("parse", raw);
   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);
+        }
+      : null,
     serialize: serializeEntry
       ? async (d) => {
           const out = await serializeEntry.call("serialize", d);

package/src/resolve.ts

@@ -1,5 +1,6 @@
 /** Resolve.js — Generic $src module proxy + timing: "server" function proxy */
 
+import { siteBasePath } from "@jxsuite/schema/asset-paths";
 import { dirname, relative, resolve } from "node:path";
 import { errorMessage, parseClassDef } from "@jxsuite/schema/parse";
 import { existsSync, readFileSync, statSync } from "node:fs";
@@ -99,6 +100,22 @@ async function loadProjectEntry(projectRoot: string) {
   }
 }
 
+/**
+ * The path a project says it is deployed under, or `""` for a site at an origin root.
+ *
+ * Read off `project.json`'s `url` (`@jxsuite/schema/asset-paths`), through the same mtime-keyed
+ * cache the asset mounts use — a second cache on the same file would be a second thing to
+ * invalidate, and this is asked on every request.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<string>} A path with a leading slash and no trailing one, or `""`
+ */
+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);
+}
+
 /**
  * Extension asset mounts for a project (specs/extensions.md §8.5) — the directories the dev server
  * serves at their site URLs, so content-relative images resolve exactly as they will once built.

package/src/server.ts

@@ -18,7 +18,12 @@ import { buildAll } from "./build.ts";
 import { createCollabRegistry } from "./collab.ts";
 import { createWatcher, injectSSE } from "./watch.ts";
 import { handleJxMounts } from "./jx-mounts.ts";
-import { handleResolve, handleServerFunction, projectAssetMounts } from "./resolve.ts";
+import {
+  handleResolve,
+  handleServerFunction,
+  projectAssetMounts,
+  projectSiteBase,
+} from "./resolve.ts";
 import {
   assertAccessible,
   assertCreatableParent,
@@ -301,6 +306,25 @@ export async function createDevServer(options: {
       }
       // Keep the un-collapsed decoded path: the static branch detects a POSIX-absolute "//abs" prefix.
       let { path } = decoded;
+
+      /*
+       * A subpath deployment's base, stripped once at the edge (site-architecture.md §5).
+       *
+       * A project whose `url` carries a path is SERVED from that path, and a build emits every URL
+       * under it — so a preview that only answered the bare path would exercise URLs the deployed
+       * site never uses, which is the class of bug that is only found in production. Stripping
+       * rather than moving the dev root means both spellings work: `localhost:3000/` is unchanged,
+       * and `localhost:3000/m/my-site/assets/x.js` resolves to the same file.
+       *
+       * `url` is mutated too, because everything downstream routes on it — the extension mounts
+       * match `url.pathname` against their own basePath, which is declared bare.
+       */
+      const siteBase = await projectSiteBase(activeProjectRoot ?? absRoot);
+      if (siteBase !== "" && (path === siteBase || path.startsWith(`${siteBase}/`))) {
+        path = path.slice(siteBase.length) || "/";
+        url.pathname = url.pathname.slice(siteBase.length) || "/";
+      }
+
       if (path.endsWith("/")) {
         path += "index.html";
       } else if (path === "") {

package/src/studio-api.ts

@@ -1497,6 +1497,26 @@ export async function handleStudioApi(
     }
   }
 
+  // What this backend can OFFER, enabled or not (specs/extensions.md §9.2) — the shipped
+  // First-party catalogue plus any dependency of THIS project exporting a jx-extension.json, each
+  // Marked with whether the project resolves it and whether this host does.
+  //
+  // Deliberately NOT a field on /__studio/formats. That route builds the project's registry and
+  // Fails when a declared extension does not resolve, which is exactly the state a reader is in
+  // When they need the catalogue to repair it; riding on formats would make the answer unavailable
+  // Precisely when it is the fix.
+  if (path === "/__studio/catalog" && req.method === "GET") {
+    const dir = url.searchParams.get("dir") || activeProjectRoot || root;
+    const projectRoot = isAbsolute(dir) ? dir : resolve(root, dir);
+    try {
+      assertAccessible(projectRoot, root, activeProjectRoot);
+      const { buildExtensionCatalog } = await import("./extension-catalog.ts");
+      return Response.json(await buildExtensionCatalog(projectRoot));
+    } catch (error) {
+      return problem("invalidRequest", errorMessage(error));
+    }
+  }
+
   // Pre-bundled per-project entry schemas (project.schema.json / document.schema.json) for the
   // Studio's editor — regenerated on demand when missing or older than project.json, then bundled
   // Into self-contained compound documents so no relative $ref resolution is needed client-side.
@@ -1846,7 +1866,13 @@ export async function handleStudioApi(
         if (fp.includes("..")) {
           return problem("invalidRequest", "Invalid path");
         }
-        const content = await runGit(["show", `${ref}:${fp}`]);
+        /* `./` IS LOAD-BEARING. `git show <rev>:<path>` resolves <path> from the REPOSITORY ROOT,
+           whatever the cwd is; only a `./` prefix makes it relative to the cwd. Every other verb
+           here — status, diff, checkout — is cwd-relative, and so is the `readFile` the studio
+           pairs this with, so without it a project nested inside its repo compared two DIFFERENT
+           FILES: the working copy of `examples/package.json` against the committed root
+           `package.json`, with no error anywhere and a plausible-looking diff. */
+        const content = await runGit(["show", `${ref}:./${fp}`]);
         return Response.json({ content });
       }