@backmatter/core 0.0.16 → 0.0.18

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "@backmatter/core",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "Experimental Backmatter SDK. APIs will break. Not ready for production.",
   "type": "module",
   "publishConfig": {
     "access": "public"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MRued/backmatter.git",
+    "directory": "packages/core"
+  },
   "exports": {
     ".": "./src/index.ts",
     "./node": "./src/node/index.ts",
     "./node/create-backmatter": "./src/node/create-backmatter.ts",
+    "./node/registry-import": "./src/node/registry-import.ts",
     "./preview": "./src/preview.ts",
     "./generate": "./src/node/generate.ts"
   },
@@ -21,7 +27,7 @@
     "!**/test-fixtures"
   ],
   "bin": {
-    "backmatter": "./bin/backmatter.js"
+    "backmatter": "bin/backmatter.js"
   },
   "scripts": {
     "test": "bun test"

package/src/config.ts

@@ -98,14 +98,38 @@ export function resolveDevBarApiUrl(
   return "";
 }
 
+function isLoopbackApiUrl(url: string): boolean {
+  try {
+    const { hostname } = new URL(url);
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+  } catch {
+    return false;
+  }
+}
+
+/** Vercel, Netlify, Cloudflare Pages, or Railway — not a laptop `next build`. */
+function onPlatformDeploy(env: Record<string, string | undefined>): boolean {
+  return Boolean(env.VERCEL || env.NETLIFY || env.CF_PAGES || env.RAILWAY_ENVIRONMENT);
+}
+
 function detectApiUrl(
   config: BackmatterConfig,
   env: Record<string, string | undefined>,
   workspaceId: string | undefined,
 ): string | undefined {
-  const explicit = config.apiUrl !== undefined ? config.apiUrl : env.BACKMATTER_API_URL;
+  const fromConfig = config.apiUrl !== undefined;
+  const explicit = fromConfig ? config.apiUrl : env.BACKMATTER_API_URL;
   const trimmed = explicit?.trim();
-  if (trimmed) return stripTrailingSlash(trimmed);
+  // Next loads `.env` for every environment, so a dev loopback URL is present
+  // during `next build` and fails page-data collection when that API is down.
+  // A local production build falls through to the cloud API. An explicit
+  // config.apiUrl, `next dev`, and a real platform deploy keep the loopback URL.
+  const ignoreDevLoopback =
+    !fromConfig &&
+    Boolean(trimmed && isLoopbackApiUrl(trimmed)) &&
+    env.NEXT_PHASE === "phase-production-build" &&
+    !onPlatformDeploy(env);
+  if (trimmed && !ignoreDevLoopback) return stripTrailingSlash(trimmed);
   if (workspaceId && isDeployedHost(env)) return CLOUD_API_URL;
   return undefined;
 }

package/src/node/cli.ts

@@ -17,6 +17,7 @@ import { resolveConfig, type BackmatterConfig, type ResolvedConfig } from "../co
 import { discoverModels, discoverBlocks } from "./discover";
 import { walkContentFiles } from "./fs-loader";
 import { detectSdk, findConfigFile, generate, type GenerateResult } from "./generate";
+import { ensureRegistryTsconfig, REGISTRY_SPECIFIER } from "./registry-import";
 
 export type CliArgs = {
   command?: string;
@@ -261,16 +262,16 @@ export default defineConfig({
 `;
 }
 
-function renderCatchAllPage(registryImport: string): string {
+function renderCatchAllPage(): string {
   return `// ${CATCH_ALL_DIR}/page.tsx — mounts every model at its route, including / via indexSlug.
 import { cacheLife } from "next/cache";
 import { createCatchAll } from "@backmatter/next/routes";
-import { cms } from "${registryImport}";
-import { components as mdxComponents } from "${registryImport}/mdx";
-import { richtextComponents } from "${registryImport}/richtext";
-import { blockLoaders } from "${registryImport}/blocks";
-import { blockFallbacks } from "${registryImport}/block-fallbacks";
-import { layouts } from "${registryImport}/layouts";
+import { cms } from "${REGISTRY_SPECIFIER}";
+import { components as mdxComponents } from "${REGISTRY_SPECIFIER}/mdx";
+import { richtextComponents } from "${REGISTRY_SPECIFIER}/richtext";
+import { blockLoaders } from "${REGISTRY_SPECIFIER}/blocks";
+import { blockFallbacks } from "${REGISTRY_SPECIFIER}/block-fallbacks";
+import { layouts } from "${REGISTRY_SPECIFIER}/layouts";
 
 const components = { ...richtextComponents, ...mdxComponents };
 const route = createCatchAll(cms, { components, blocks: blockLoaders, fallbacks: blockFallbacks, layouts });
@@ -303,12 +304,12 @@ export default async function Page(props: {
 `;
 }
 
-function renderInstrumentation(syncImport: string): string {
+function renderInstrumentation(): string {
   return `// instrumentation.ts — schema sync on Node. Next also runs register() on Edge;
-// do not import .backmatter/sync there (it pulls Node APIs).
+// do not import ${REGISTRY_SPECIFIER}/sync there (it pulls Node APIs).
 export async function register() {
   if (process.env.NEXT_RUNTIME === "nodejs") {
-    await import("${syncImport}");
+    await import("${REGISTRY_SPECIFIER}/sync");
   }
 }
 `;
@@ -320,15 +321,15 @@ export function warnMissingInstrumentation(root: string): void {
   const hasSrc = existsSync(path.join(root, "src", "instrumentation.ts"));
   if (!hasRoot && !hasSrc) {
     console.warn(
-      "backmatter: add instrumentation.ts that imports .backmatter/sync — block schema sync will not run without it",
+      `backmatter: add instrumentation.ts that imports ${REGISTRY_SPECIFIER}/sync — block schema sync will not run without it`,
     );
   }
 }
 
-function renderPreviewRoute(registryImport: string): string {
+function renderPreviewRoute(): string {
   return `// api/backmatter/preview/route.ts — preview session enable / disable / stream / session.
 import { createPreviewRoute } from "@backmatter/next/preview-route";
-import { cms } from "${registryImport}";
+import { cms } from "${REGISTRY_SPECIFIER}";
 
 export const { GET, POST } = createPreviewRoute(cms);
 `;
@@ -347,10 +348,10 @@ export const config = {
 `;
 }
 
-function renderRevalidateRoute(registryImport: string): string {
+function renderRevalidateRoute(): string {
   return `// api/backmatter/revalidate/route.ts — content.committed from the BACKMATTER server.
 import { createRevalidateRoute } from "@backmatter/next/revalidate";
-import { cms } from "${registryImport}";
+import { cms } from "${REGISTRY_SPECIFIER}";
 
 export const POST = createRevalidateRoute(cms);
 `;
@@ -386,21 +387,16 @@ export async function runInit(args: CliArgs): Promise<string[]> {
     } else if (existsSync(requiredCatchAll)) {
       notes.push(`kept existing ${path.join(appDir, "[...backmatter]", "page.tsx")}`);
     } else {
-      const registry = path.relative(pageDir, path.join(root, ".backmatter")).split(path.sep).join("/");
       await mkdir(pageDir, { recursive: true });
-      await writeFile(page, renderCatchAllPage(registry.startsWith(".") ? registry : `./${registry}`));
+      await writeFile(page, renderCatchAllPage());
       notes.push(`wrote ${path.join(appDir, CATCH_ALL_DIR, "page.tsx")}`);
     }
 
     const revalidateDir = path.join(root, appDir, "api", "backmatter", "revalidate");
     const revalidateFile = path.join(revalidateDir, "route.ts");
     if (!existsSync(revalidateFile)) {
-      const registry = path.relative(revalidateDir, path.join(root, ".backmatter")).split(path.sep).join("/");
       await mkdir(revalidateDir, { recursive: true });
-      await writeFile(
-        revalidateFile,
-        renderRevalidateRoute(registry.startsWith(".") ? registry : `./${registry}`),
-      );
+      await writeFile(revalidateFile, renderRevalidateRoute());
       notes.push(`wrote ${path.join(appDir, "api/backmatter/revalidate/route.ts")}`);
     } else {
       notes.push(`kept existing ${path.join(appDir, "api/backmatter/revalidate/route.ts")}`);
@@ -409,12 +405,8 @@ export async function runInit(args: CliArgs): Promise<string[]> {
     const previewDir = path.join(root, appDir, "api", "backmatter", "preview");
     const previewFile = path.join(previewDir, "route.ts");
     if (!existsSync(previewFile)) {
-      const registry = path.relative(previewDir, path.join(root, ".backmatter")).split(path.sep).join("/");
       await mkdir(previewDir, { recursive: true });
-      await writeFile(
-        previewFile,
-        renderPreviewRoute(registry.startsWith(".") ? registry : `./${registry}`),
-      );
+      await writeFile(previewFile, renderPreviewRoute());
       notes.push(`wrote ${path.join(appDir, "api/backmatter/preview/route.ts")}`);
     } else {
       notes.push(`kept existing ${path.join(appDir, "api/backmatter/preview/route.ts")}`);
@@ -448,10 +440,12 @@ export async function runInit(args: CliArgs): Promise<string[]> {
       notes.push("kept existing instrumentation.ts");
     } else {
       const dest = usesSrcApp ? srcInstrumentation : rootInstrumentation;
-      const syncImport = usesSrcApp ? "../.backmatter/sync" : "./.backmatter/sync";
-      await writeFile(dest, renderInstrumentation(syncImport));
+      await writeFile(dest, renderInstrumentation());
       notes.push(`wrote ${path.relative(root, dest)}`);
     }
+
+    const tsconfigNote = ensureRegistryTsconfig(root);
+    if (tsconfigNote) notes.push(tsconfigNote);
   } else {
     notes.push("no @backmatter/next dependency: skipped the catch-all route");
   }

package/src/node/eval-model.ts

@@ -1,15 +1,18 @@
 // packages/core/src/node/eval-model.ts
-// Sandbox-eval a convention `models/{type}.ts` blob (GitHub import). Only
-// `defineModel` / `field` from @backmatter/core or @backmatter/next are in scope —
-// never import() the customer checkout.
+// Sandbox-eval convention model and object files (GitHub import). The allowed
+// surface is the same one `discoverModels` / `discoverObjects` run: `defineModel`,
+// `defineObject`, and `field` from @backmatter/core or @backmatter/next, plus
+// `import name from "../objects/<name>"`. Never import() the customer checkout.
 import { runInNewContext } from "node:vm";
 import { defineModel, type ModelDef } from "../model";
+import { defineObject, type ObjectDef } from "../object";
 import { field } from "../fields";
 
 const SOURCE_EXT = /\.(ts|tsx|js|jsx|mjs)$/;
 const IGNORED = /(\.test\.|\.spec\.|\.d\.ts$|\.stories\.)/;
 const ALLOWED_IMPORT = /^\s*import\s+\{([^}]+)\}\s+from\s+["'](@backmatter\/core|@backmatter\/next)["']\s*;?\s*$/gm;
 const ALLOWED_NAMES = new Set(["defineModel", "field"]);
+const OBJECT_NAMES = new Set(["defineObject", "field"]);
 const FORBIDDEN = [
   { re: /\brequire\s*\(/, name: "require" },
   { re: /\bimport\s*\(/, name: "import" },
@@ -44,38 +47,61 @@ function stemOf(repoPath: string): string {
   return name.replace(SOURCE_EXT, "");
 }
 
-function stripAllowedImports(source: string): string {
+function stripAllowedImports(
+  source: string,
+  allowed: Set<string> = ALLOWED_NAMES,
+  label = "defineModel and field",
+): string {
+  ALLOWED_IMPORT.lastIndex = 0;
   const names = new Set<string>();
   const stripped = source.replace(ALLOWED_IMPORT, (_full, specifiers: string) => {
     for (const part of specifiers.split(",")) {
       const name = part.trim();
       if (!name) continue;
-      if (/\bas\b/.test(name) || !ALLOWED_NAMES.has(name)) {
-        throw new Error(`import "${name}" is not allowed; only defineModel and field`);
+      if (/\bas\b/.test(name) || !allowed.has(name)) {
+        throw new Error(`import "${name}" is not allowed; only ${label}`);
       }
       names.add(name);
     }
     return "";
   });
   if (/^\s*import\b/m.test(stripped)) {
-    throw new Error("import is not allowed except defineModel/field from @backmatter/core or @backmatter/next");
+    throw new Error(
+      `import is not allowed except ${label} from @backmatter/core or @backmatter/next`,
+    );
   }
   return stripped;
 }
 
-function assertNoForbidden(source: string): void {
+/** `import name from "../objects/<file>"` — the only local import a model may use. */
+function takeObjectImports(source: string): {
+  source: string;
+  bindings: Array<{ local: string; stem: string }>;
+} {
+  const bindings: Array<{ local: string; stem: string }> = [];
+  const re =
+    /^\s*import\s+([A-Za-z_$][\w$]*)\s+from\s+["']\.\.\/objects\/([A-Za-z][A-Za-z0-9]*)(?:\.(?:ts|tsx|js|jsx|mjs))?["']\s*;?\s*$/gm;
+  const next = source.replace(re, (_full, local: string, stem: string) => {
+    bindings.push({ local, stem });
+    return "";
+  });
+  return { source: next, bindings };
+}
+
+function assertNoForbidden(source: string, kind = "model"): void {
   for (const { re, name } of FORBIDDEN) {
-    if (re.test(source)) throw new Error(`${name} is not allowed in model files`);
+    re.lastIndex = 0;
+    if (re.test(source)) throw new Error(`${name} is not allowed in ${kind} files`);
   }
 }
 
-function rewriteDefaultExport(source: string): string {
+function rewriteDefaultExport(source: string, what = "defineModel({ ... })"): string {
   if (!/\bexport\s+default\b/.test(source)) {
-    throw new Error("must export default defineModel({ ... })");
+    throw new Error(`must export default ${what}`);
   }
   const rewritten = source.replace(/\bexport\s+default\s+/, "return ");
   if (/\bexport\b/.test(rewritten)) {
-    throw new Error("must export default defineModel({ ... })");
+    throw new Error(`must export default ${what}`);
   }
   return rewritten;
 }
@@ -85,18 +111,75 @@ function transpile(source: string): string {
   return transpiler.transformSync(source);
 }
 
+function isObjectDef(value: unknown): value is ObjectDef {
+  if (!value || typeof value !== "object") return false;
+  const object = value as Record<string, unknown>;
+  return typeof object.name === "string" && typeof object.fields === "object" && !("type" in object);
+}
+
+/**
+ * Evaluate one `objects/{name}.ts` blob. Same rule as `discoverObjects`:
+ * the file stem must equal `object.name`.
+ */
+export function evalObjectSource(source: string, stem: string): ObjectDef {
+  const body = rewriteDefaultExport(
+    stripAllowedImports(source, OBJECT_NAMES, "defineObject and field"),
+    "defineObject({ ... })",
+  );
+  assertNoForbidden(body, "object");
+  const wrapped = `(function () {\n${body}\n})()`;
+  const js = transpile(wrapped);
+  const sandbox = Object.create(null) as {
+    defineObject: typeof defineObject;
+    field: typeof field;
+  };
+  sandbox.defineObject = defineObject;
+  sandbox.field = field;
+  Object.freeze(sandbox);
+
+  let result: unknown;
+  try {
+    result = runInNewContext(js, sandbox, {
+      timeout: EVAL_TIMEOUT_MS,
+      filename: `${stem}.js`,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`object "${stem}" failed to evaluate: ${message}`);
+  }
+  if (!isObjectDef(result)) {
+    throw new Error("must export default defineObject({ ... })");
+  }
+  if (result.name !== stem) {
+    throw new Error(
+      `defines name "${result.name}" but the file is named "${stem}"; rename one so they match`,
+    );
+  }
+  return result;
+}
+
 /**
  * Evaluate one convention model file. `stem` is the file name without extension
- * and must equal `model.type`.
+ * and must equal `model.type`. `objects` supplies `import x from "../objects/<file>"`.
  */
-export function evalModelSource(source: string, stem: string): ModelDef {
-  const body = rewriteDefaultExport(stripAllowedImports(source));
+export function evalModelSource(
+  source: string,
+  stem: string,
+  objects: Readonly<Record<string, ObjectDef>> = {},
+): ModelDef {
+  const taken = takeObjectImports(source);
+  const body = rewriteDefaultExport(stripAllowedImports(taken.source));
   assertNoForbidden(body);
   const wrapped = `(function () {\n${body}\n})()`;
   const js = transpile(wrapped);
-  const sandbox = Object.create(null) as { defineModel: typeof defineModel; field: typeof field };
+  const sandbox = Object.create(null) as Record<string, unknown>;
   sandbox.defineModel = defineModel;
   sandbox.field = field;
+  for (const binding of taken.bindings) {
+    const object = objects[binding.stem];
+    if (!object) throw new Error(`import "../objects/${binding.stem}" was not found`);
+    sandbox[binding.local] = object;
+  }
   Object.freeze(sandbox);
 
   let result: unknown;
@@ -125,6 +208,11 @@ export function evalModelsFromTree(
   files: Array<{ path: string; source: string }>,
   modelsDir = "models",
 ): ModelDef[] {
+  const objects: Record<string, ObjectDef> = {};
+  for (const file of files.filter((f) => isModelSourcePath(f.path, "objects"))) {
+    const stem = stemOf(file.path);
+    objects[stem] = evalObjectSource(file.source, stem);
+  }
   const models: ModelDef[] = [];
   const types = new Set<string>();
   const sorted = files
@@ -132,7 +220,7 @@ export function evalModelsFromTree(
     .sort((a, b) => a.path.localeCompare(b.path));
   for (const file of sorted) {
     const stem = stemOf(file.path);
-    const model = evalModelSource(file.source, stem);
+    const model = evalModelSource(file.source, stem, objects);
     if (types.has(model.type)) {
       throw new Error(`duplicate model type "${model.type}" (${file.path})`);
     }

package/src/node/index.ts

@@ -18,7 +18,7 @@ export {
   toIdentifier,
 } from "./discover";
 export type { BlockFile, ModelFile } from "./discover";
-export { evalModelSource, evalModelsFromTree, isModelSourcePath } from "./eval-model";
+export { evalModelSource, evalModelsFromTree, evalObjectSource, isModelSourcePath } from "./eval-model";
 export {
   evalBlockSource,
   evalBlocksFromTree,
@@ -39,6 +39,15 @@ export {
   REGISTRY_FILES,
 } from "./generate";
 export type { GenerateOptions, GenerateResult, GeneratedFile } from "./generate";
+export {
+  REGISTRY_SPECIFIER,
+  addRegistryPaths,
+  ensureRegistryTsconfig,
+  registryImportPaths,
+  inferTurbopackRoot,
+  registryTurbopackAlias,
+  registryWebpackAlias,
+} from "./registry-import";
 export {
   contentRoots,
   formatResults,

package/src/node/registry-import.ts

@@ -0,0 +1,335 @@
+// packages/core/src/node/registry-import.ts
+// The generated client lives in `.backmatter/`. Apps import it as `backmatter`
+// from any file. These helpers are the alias (`withBackmatter`) and the
+// matching `tsconfig.json` `paths` (`init` and `withBackmatter`).
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { DEFAULT_OUT_DIR, REGISTRY_FILES } from "./generate";
+
+export const REGISTRY_SPECIFIER = "backmatter";
+
+export type RegistryAlias = {
+  /** Bare import, e.g. `backmatter` or `backmatter/mdx`. */
+  specifier: string;
+  /** File name inside the out dir, e.g. `index.ts`. */
+  file: string;
+};
+
+export function registryAliases(): RegistryAlias[] {
+  return REGISTRY_FILES.map((file) => {
+    const stem = file.slice(0, -".ts".length);
+    return {
+      specifier: stem === "index" ? REGISTRY_SPECIFIER : `${REGISTRY_SPECIFIER}/${stem}`,
+      file,
+    };
+  });
+}
+
+const LOCK_FILES = ["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lock", "bun.lockb"];
+
+/**
+ * Highest workspace or lockfile at or above `appRoot`, inside the git repo.
+ * Next uses the same files to choose `turbopack.root`. In a single-package app
+ * that is the app root; in this monorepo it is the repository root.
+ */
+export function inferTurbopackRoot(appRoot: string): string {
+  const start = path.resolve(appRoot);
+  const gitRoot = findGitRoot(start);
+  let dir = start;
+  let root = start;
+  while (true) {
+    if (hasWorkspace(dir) || LOCK_FILES.some((name) => existsSync(path.join(dir, name)))) root = dir;
+    if (gitRoot && dir === gitRoot) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return root;
+}
+
+/**
+ * Turbopack `resolveAlias` values, relative to the Next app, with a `./` prefix.
+ * Next resolves these from the app directory even when `turbopack.root` is a
+ * parent workspace. A monorepo prefix (`./packages/docs/.backmatter/...`) makes
+ * the lookup `packages/docs/packages/docs/.backmatter`.
+ */
+export function registryTurbopackAlias(
+  appRoot: string,
+  outDir = DEFAULT_OUT_DIR,
+): Record<string, string> {
+  const alias: Record<string, string> = {};
+  const base = path.resolve(appRoot);
+  for (const { specifier, file } of registryAliases()) {
+    const abs = path.resolve(appRoot, outDir, file);
+    alias[specifier] = asRelative(path.relative(base, abs).split(path.sep).join("/"));
+  }
+  return alias;
+}
+
+/**
+ * Webpack `resolve.alias`. Keys end in `$` so `backmatter` matches only that
+ * specifier, and `backmatter/mdx` stays its own entry. Values are absolute.
+ */
+export function registryWebpackAlias(root: string, outDir = DEFAULT_OUT_DIR): Record<string, string> {
+  const alias: Record<string, string> = {};
+  for (const { specifier, file } of registryAliases()) {
+    alias[`${specifier}$`] = path.resolve(root, outDir, file);
+  }
+  return alias;
+}
+
+/**
+ * `tsconfig` `paths` for the registry. Values are relative to `baseUrl` when
+ * set, otherwise to the tsconfig directory (the project root).
+ */
+export function registryImportPaths(outDir = DEFAULT_OUT_DIR, baseUrl?: string): Record<string, string[]> {
+  const base = !baseUrl || baseUrl === "." ? "." : baseUrl;
+  const from = path.resolve("/registry-root", base);
+  const to = path.resolve("/registry-root", outDir);
+  const folder = asRelative(path.relative(from, to).split(path.sep).join("/"));
+  const paths: Record<string, string[]> = {};
+  for (const { specifier, file } of registryAliases()) {
+    paths[specifier] = [`${folder}/${file}`];
+  }
+  return paths;
+}
+
+/** Insert missing `backmatter` paths. Returns the source unchanged when they are already present. */
+export function addRegistryPaths(source: string, outDir = DEFAULT_OUT_DIR): string {
+  let parsed: unknown;
+  try {
+    parsed = looseParse(source);
+  } catch {
+    return source;
+  }
+  if (!isRecord(parsed)) return source;
+  const options = parsed.compilerOptions;
+  if (!isRecord(options)) return source;
+  const baseUrl = typeof options.baseUrl === "string" ? options.baseUrl : undefined;
+  const mappings = registryImportPaths(outDir, baseUrl);
+  const existing = isRecord(options.paths) ? options.paths : undefined;
+  if (options.paths !== undefined && !existing) return source;
+  const missing = Object.fromEntries(
+    Object.entries(mappings).filter(([key]) => !existing || existing[key] === undefined),
+  );
+  if (Object.keys(missing).length === 0) return source;
+
+  const compiler = findKeyBrace(source, "compilerOptions", 0, source.length);
+  if (!compiler) return source;
+  const compilerEnd = matchBrace(source, compiler.brace);
+  if (compilerEnd < 0) return source;
+
+  const nl = source.includes("\r\n") ? "\r\n" : "\n";
+  if (existing) {
+    const pathsBrace = findKeyBrace(source, "paths", compiler.brace + 1, compilerEnd);
+    if (!pathsBrace || pathsBrace.brace > compilerEnd) return source;
+    const indent = innerIndent(source, pathsBrace.brace);
+    const entries = formatEntries(missing, indent, nl);
+    return insertEntries(source, pathsBrace.brace, entries, indent, nl);
+  }
+
+  const indent = innerIndent(source, compiler.brace);
+  const child = `${indent}  `;
+  const entries = formatEntries(missing, child, nl);
+  const block = `${indent}"paths": {${nl}${entries},${nl}${indent}}`;
+  return `${source.slice(0, compiler.brace + 1)}${nl}${block},${source.slice(compiler.brace + 1)}`;
+}
+
+/** Write `paths` into tsconfig.json or jsconfig.json when the registry keys are missing. */
+export function ensureRegistryTsconfig(root: string, outDir = DEFAULT_OUT_DIR): string | null {
+  const tsconfig = path.join(root, "tsconfig.json");
+  const jsconfig = path.join(root, "jsconfig.json");
+  const file = existsSync(tsconfig) ? tsconfig : existsSync(jsconfig) ? jsconfig : null;
+  if (!file) return null;
+  const before = readFileSync(file, "utf-8");
+  const after = addRegistryPaths(before, outDir);
+  if (after === before) return null;
+  writeFileSync(file, after);
+  return `updated ${path.basename(file)}`;
+}
+
+function hasWorkspace(dir: string): boolean {
+  const pkgPath = path.join(dir, "package.json");
+  if (!existsSync(pkgPath)) return false;
+  try {
+    return JSON.parse(readFileSync(pkgPath, "utf-8")).workspaces != null;
+  } catch {
+    return false;
+  }
+}
+
+function findGitRoot(start: string): string | null {
+  let dir = start;
+  while (true) {
+    if (existsSync(path.join(dir, ".git"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** `.backmatter/...` is relative, and still needs a `./` so bundlers do not treat it as a package. */
+function asRelative(rel: string): string {
+  if (rel.startsWith("./") || rel.startsWith("../")) return rel;
+  return `./${rel}`;
+}
+
+function insertEntries(source: string, open: number, entries: string, indent: string, nl: string): string {
+  let rest = source.slice(open + 1);
+  if (!/^\r?\n/.test(rest)) rest = `${nl}${indent}${rest.trimStart()}`;
+  return `${source.slice(0, open + 1)}${nl}${entries},${rest}`;
+}
+
+function formatEntries(mappings: Record<string, string[]>, indent: string, nl: string): string {
+  return Object.entries(mappings)
+    .map(([key, value]) => `${indent}"${key}": [${value.map((entry) => JSON.stringify(entry)).join(", ")}]`)
+    .join(`,${nl}`);
+}
+
+function innerIndent(source: string, open: number): string {
+  const rest = source.slice(open + 1);
+  const nl = rest.search(/\r?\n/);
+  if (nl !== -1) {
+    const after = rest.slice(nl).replace(/^\r?\n/, "");
+    const indent = after.match(/^[ \t]*/)?.[0] ?? "";
+    const next = after[indent.length];
+    if (indent.length > 0 && next && next !== "}") return indent;
+  }
+  const lineStart = source.lastIndexOf("\n", open) + 1;
+  const base = source.slice(lineStart, open).match(/^[ \t]*/)?.[0] ?? "";
+  return `${base}  `;
+}
+
+function looseParse(source: string): unknown {
+  const stripped = stripJsonComments(source).replace(/,\s*([}\]])/g, "$1");
+  return JSON.parse(stripped);
+}
+
+function stripJsonComments(input: string): string {
+  let out = "";
+  let i = 0;
+  let inString = false;
+  let escaped = false;
+  while (i < input.length) {
+    const c = input[i]!;
+    const next = input[i + 1];
+    if (inString) {
+      out += c;
+      if (escaped) escaped = false;
+      else if (c === "\\") escaped = true;
+      else if (c === '"') inString = false;
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      inString = true;
+      out += c;
+      i++;
+      continue;
+    }
+    if (c === "/" && next === "/") {
+      i += 2;
+      while (i < input.length && input[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && next === "*") {
+      i += 2;
+      while (i < input.length && !(input[i] === "*" && input[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function findKeyBrace(source: string, key: string, start: number, end: number): { brace: number } | null {
+  const needle = `"${key}"`;
+  let i = start;
+  let inString = false;
+  let escaped = false;
+  while (i < end) {
+    const c = source[i]!;
+    const next = source[i + 1];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (c === "\\") escaped = true;
+      else if (c === '"') inString = false;
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      if (source.startsWith(needle, i)) {
+        let j = i + needle.length;
+        while (j < end && /\s/.test(source[j]!)) j++;
+        if (source[j] === ":") {
+          j++;
+          while (j < end && /\s/.test(source[j]!)) j++;
+          if (source[j] === "{") return { brace: j };
+        }
+      }
+      inString = true;
+      i++;
+      continue;
+    }
+    if (c === "/" && next === "/") {
+      i += 2;
+      while (i < end && source[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && next === "*") {
+      i += 2;
+      while (i < end && !(source[i] === "*" && source[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    i++;
+  }
+  return null;
+}
+
+function matchBrace(source: string, open: number): number {
+  let depth = 0;
+  let i = open;
+  let inString = false;
+  let escaped = false;
+  while (i < source.length) {
+    const c = source[i]!;
+    const next = source[i + 1];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (c === "\\") escaped = true;
+      else if (c === '"') inString = false;
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      inString = true;
+      i++;
+      continue;
+    }
+    if (c === "/" && next === "/") {
+      i += 2;
+      while (i < source.length && source[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && next === "*") {
+      i += 2;
+      while (i < source.length && !(source[i] === "*" && source[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    if (c === "{") depth++;
+    else if (c === "}") {
+      depth--;
+      if (depth === 0) return i;
+    }
+    i++;
+  }
+  return -1;
+}