@backmatter/core 0.0.15 → 0.0.17

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "@backmatter/core",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "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

@@ -8,6 +8,8 @@ export type BackmatterDirs = {
   models?: string;
   /** Folder with one `defineBlock` default export per file. Default: "blocks". */
   blocks?: string;
+  /** Folder with one in-content `defineBlock` per file. Default: "richtext". */
+  richtext?: string;
   /** Folder with one MDX tag component default export per file. Default: "mdx". */
   mdx?: string;
   /** Folder with one layout default export per model type. Default: "layouts". */
@@ -51,6 +53,7 @@ export type ResolvedConfig = Omit<BackmatterConfig, "dirs" | "defaultLocale"> &
 export const DEFAULT_DIRS: Required<BackmatterDirs> = {
   models: "models",
   blocks: "blocks",
+  richtext: "richtext",
   mdx: "mdx",
   layouts: "layouts",
   objects: "objects",
@@ -95,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;
 }
@@ -159,6 +186,7 @@ export function resolveConfig(
     dirs: {
       models: config.dirs?.models ?? DEFAULT_DIRS.models,
       blocks: config.dirs?.blocks ?? DEFAULT_DIRS.blocks,
+      richtext: config.dirs?.richtext ?? DEFAULT_DIRS.richtext,
       mdx: config.dirs?.mdx ?? DEFAULT_DIRS.mdx,
       layouts: config.dirs?.layouts ?? DEFAULT_DIRS.layouts,
       objects: config.dirs?.objects ?? DEFAULT_DIRS.objects,

package/src/model.ts

@@ -85,6 +85,8 @@ export type SchemaSnapshot = {
   version: number;
   models: ModelSnapshot[];
   blocks?: BlockSnapshot[];
+  /** In-content blocks from `richtext/`. Separate from page-builder `blocks`. */
+  richtext?: BlockSnapshot[];
   objects?: ObjectSnapshot[];
 };
 
@@ -178,6 +180,7 @@ export function serializeSchema(
   models: ModelDef[],
   blocks?: BlockDef[],
   objects?: ObjectDef[],
+  richtext?: BlockDef[],
 ): SchemaSnapshot {
   const snapshot: SchemaSnapshot = {
     version: 1,
@@ -186,6 +189,9 @@ export function serializeSchema(
   if (blocks && blocks.length > 0) {
     snapshot.blocks = blocks.map(serializeBlock);
   }
+  if (richtext && richtext.length > 0) {
+    snapshot.richtext = richtext.map(serializeBlock);
+  }
   if (objects && objects.length > 0) {
     snapshot.objects = objects.map(serializeObject);
   }
@@ -301,6 +307,28 @@ export function parseSchemaSnapshot(input: unknown): SchemaSnapshot {
     }
   }
 
+  let richtext: BlockSnapshot[] = [];
+  if (value.richtext !== undefined) {
+    if (!Array.isArray(value.richtext)) {
+      throw new Error("schema.richtext must be an array");
+    }
+    richtext = value.richtext.map((raw, i) => {
+      try {
+        return parseBlockSnapshot(raw);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "invalid block";
+        throw new Error(`schema.richtext[${i}]: ${msg}`);
+      }
+    });
+    const richtextNames = new Set<string>();
+    for (const block of richtext) {
+      if (richtextNames.has(block.name)) {
+        throw new Error(`duplicate richtext block name: ${block.name}`);
+      }
+      richtextNames.add(block.name);
+    }
+  }
+
   let objects: ObjectSnapshot[] = [];
   if (value.objects !== undefined) {
     if (!Array.isArray(value.objects)) {
@@ -323,5 +351,11 @@ export function parseSchemaSnapshot(input: unknown): SchemaSnapshot {
     }
   }
 
-  return { version, models, blocks, objects };
+  return {
+    version,
+    models,
+    blocks,
+    ...(richtext.length > 0 ? { richtext } : {}),
+    objects,
+  };
 }

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;
@@ -234,8 +235,10 @@ export async function runGenerate(args: CliArgs): Promise<GenerateResult> {
     root,
     modelsDir: config.dirs.models,
     blocksDir: config.dirs.blocks,
+    richtextDir: config.dirs.richtext,
     mdxDir: config.dirs.mdx,
     layoutsDir: config.dirs.layouts,
+    objectsDir: config.dirs.objects,
   });
 }
 
@@ -247,8 +250,9 @@ function renderConfigFile(sdk: string): string {
 import { defineConfig } from "${from}";
 
 // General settings only. Models live in models/*.ts, composer blocks in
-// blocks/*.tsx, MDX tags in mdx/*.tsx, and content in
-// content/{locale}/{type}/{slug}.{mdx,json} — all discovered automatically.
+// blocks/*.tsx, in-content blocks in richtext/*.tsx, MDX tags in mdx/*.tsx,
+// and content in content/{locale}/{type}/{slug}.{mdx,json} — all discovered
+// automatically.
 // Set workspaceId from General settings (not an env var).
 // API URL defaults to https://api.backmatter.app in production; tokens stay env.
 export default defineConfig({
@@ -258,16 +262,18 @@ 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 } from "${registryImport}/mdx";
-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 });
 
 export const generateStaticParams = route.generateStaticParams;
@@ -298,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");
   }
 }
 `;
@@ -315,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);
 `;
@@ -342,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);
 `;
@@ -381,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")}`);
@@ -404,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")}`);
@@ -443,15 +440,17 @@ 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");
   }
 
-  for (const dir of ["models", "content", "blocks", "mdx", "layouts"]) {
+  for (const dir of ["models", "content", "blocks", "richtext", "mdx", "layouts"]) {
     await mkdir(path.join(root, dir), { recursive: true });
   }
 

package/src/node/create-backmatter.ts

@@ -18,6 +18,8 @@ export type CreateBackmatterOptions<Models extends readonly ModelDef[] = readonl
   BackmatterConfig & {
     models: Models;
     blocks?: readonly BlockDef[];
+    /** In-content blocks (`richtext/*.tsx`). Synced separately from page blocks. */
+    richtext?: readonly BlockDef[];
     objects?: readonly ObjectDef[];
     /**
      * When true, API fetches use Next cache tags instead of `cache: "no-store"`.
@@ -67,7 +69,7 @@ function toSnapshots(models: readonly ModelDef[]): ModelSnapshot[] {
 export function createBackmatter<const Models extends readonly ModelDef[]>(
   options: CreateBackmatterOptions<Models>,
 ): BackmatterClient<Models> {
-  const { models: modelDefs, blocks: blockDefs, objects: objectDefs, taggedApiFetch, sync = true, ...rest } = options;
+  const { models: modelDefs, blocks: blockDefs, richtext: richtextDefs, objects: objectDefs, taggedApiFetch, sync = true, ...rest } = options;
   const config = resolveConfig(rest);
   const models = toSnapshots(modelDefs);
   const siteRoot = config.siteRoot ?? process.cwd();
@@ -91,6 +93,7 @@ export function createBackmatter<const Models extends readonly ModelDef[]>(
         hostToken,
         models: [...modelDefs],
         blocks: blockDefs ? [...blockDefs] : undefined,
+        richtext: richtextDefs ? [...richtextDefs] : undefined,
         objects: objectDefs ? [...objectDefs] : undefined,
         branch: config.branch,
         siteUrl,

package/src/node/generate.ts

@@ -31,6 +31,7 @@ export type GenerateOptions = {
   outDir?: string;
   modelsDir?: string;
   blocksDir?: string;
+  richtextDir?: string;
   mdxDir?: string;
   layoutsDir?: string;
   objectsDir?: string;
@@ -59,6 +60,7 @@ export type GenerateResult = {
   changed: string[];
   models: ModelFile[];
   blocks: BlockFile[];
+  richtext: BlockFile[];
   mdx: BlockFile[];
   layouts: ModelFile[];
   objects: ModelFile[];
@@ -161,11 +163,13 @@ export function renderSyncBarrel(input: {
   outDir: string;
   models: ModelFile[];
   blocks: BlockFile[];
+  richtext?: BlockFile[];
   objects?: ModelFile[];
   configFile: string | null;
   sdk: string;
 }): string {
   const objects = input.objects ?? [];
+  const richtext = input.richtext ?? [];
   const lines = [GENERATED_HEADER, `import { createBackmatter } from "${input.sdk}";`];
   if (input.configFile) {
     lines.push(`import config from "${importSpecifier(input.outDir, input.configFile)}";`);
@@ -178,6 +182,9 @@ export function renderSyncBarrel(input: {
   for (const b of input.blocks) {
     lines.push(`import ${b.name} from "${importSpecifier(input.outDir, b.file)}";`);
   }
+  for (const b of richtext) {
+    lines.push(`import richtext${b.name} from "${importSpecifier(input.outDir, b.file)}";`);
+  }
   for (const object of objects) {
     lines.push(`import ${object.importName} from "${importSpecifier(input.outDir, object.file)}";`);
   }
@@ -187,10 +194,16 @@ export function renderSyncBarrel(input: {
   lines.push("");
   lines.push(`export const blocks = [${input.blocks.map((b) => b.name).join(", ")}] as const;`);
   lines.push("");
+  lines.push(
+    `export const richtext = [${richtext.map((b) => `richtext${b.name}`).join(", ")}] as const;`,
+  );
+  lines.push("");
   lines.push(`export const objects = [${objects.map((o) => o.importName).join(", ")}] as const;`);
   lines.push("");
   lines.push("/** Typed content client: cms.query.{type}, cms.getDoc, cms.listDocs. */");
-  lines.push("export const cms = createBackmatter({ ...config, models, blocks, objects, sync: true });");
+  lines.push(
+    "export const cms = createBackmatter({ ...config, models, blocks, richtext, objects, sync: true });",
+  );
   return `${lines.join("\n")}\n`;
 }
 
@@ -206,6 +219,18 @@ export function renderMdxBarrel(input: { outDir: string; mdx: BlockFile[] }): st
   return `${lines.join("\n")}\n`;
 }
 
+export function renderRichtextBarrel(input: { outDir: string; richtext: BlockFile[] }): string {
+  const lines = [GENERATED_HEADER];
+  for (const b of input.richtext) {
+    lines.push(`import ${b.name} from "${importSpecifier(input.outDir, b.file)}";`);
+  }
+  lines.push("");
+  lines.push("/** In-content blocks: <Image /> in MDX resolves to richtext/Image.tsx. */");
+  const entries = input.richtext.map((b) => `${b.name}: ${b.name}.component`);
+  lines.push(`export const richtextComponents = ${entries.length ? `{ ${entries.join(", ")} }` : "{}"};`);
+  return `${lines.join("\n")}\n`;
+}
+
 export function renderBlocksBarrel(input: { outDir: string; blocks: BlockFile[] }): string {
   const lines = [GENERATED_HEADER, ""];
   lines.push('/** Composer loaders: JSON `{ type: "Hero" }` → dynamic import of blocks/Hero.tsx. */');
@@ -257,6 +282,7 @@ export const REGISTRY_FILES = [
   "blocks.ts",
   "block-fallbacks.ts",
   "mdx.ts",
+  "richtext.ts",
   "layouts.ts",
   "sync.ts",
 ] as const;
@@ -269,6 +295,10 @@ export function generate(options: GenerateOptions): GenerateResult {
     root,
     options.blocksDir ?? DEFAULT_DIRS.blocks,
   );
+  const { blocks: richtext, skipped: skippedRichtext } = listBlockFiles(
+    root,
+    options.richtextDir ?? DEFAULT_DIRS.richtext,
+  );
   const fallbacks = listBlockFallbackFiles(root, options.blocksDir ?? DEFAULT_DIRS.blocks);
   const { blocks: mdx, skipped: skippedMdx } = listMdxFiles(
     root,
@@ -285,8 +315,9 @@ export function generate(options: GenerateOptions): GenerateResult {
     "blocks.ts": renderBlocksBarrel({ outDir, blocks }),
     "block-fallbacks.ts": renderBlockFallbacksBarrel({ outDir, fallbacks }),
     "mdx.ts": renderMdxBarrel({ outDir, mdx }),
+    "richtext.ts": renderRichtextBarrel({ outDir, richtext }),
     "layouts.ts": renderLayoutsBarrel({ outDir, layouts }),
-    "sync.ts": renderSyncBarrel({ outDir, models, blocks, objects, configFile, sdk }),
+    "sync.ts": renderSyncBarrel({ outDir, models, blocks, richtext, objects, configFile, sdk }),
   };
   const outputs: GeneratedFile[] = REGISTRY_FILES.map((name) => {
     const file = path.join(outDir, name);
@@ -304,10 +335,11 @@ export function generate(options: GenerateOptions): GenerateResult {
     changed: outputs.filter((o) => o.changed).map((o) => o.rel),
     models,
     blocks,
+    richtext,
     mdx,
     layouts,
     objects,
-    skippedBlocks,
+    skippedBlocks: [...skippedBlocks, ...skippedRichtext],
     skippedMdx,
     configFile,
   };

package/src/node/index.ts

@@ -32,12 +32,22 @@ export {
   renderBlocksBarrel,
   renderLayoutsBarrel,
   renderMdxBarrel,
+  renderRichtextBarrel,
   renderModelsBarrel,
   renderSyncBarrel,
   DEFAULT_OUT_DIR,
   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;
+}

package/src/sync-schema.ts

@@ -23,6 +23,8 @@ export type SyncSchemaOptions = {
   hostToken: string;
   models: Array<ModelDef | ModelSnapshot>;
   blocks?: BlockDef[];
+  /** In-content blocks from the client `richtext/` directory. */
+  richtext?: BlockDef[];
   objects?: ObjectDef[];
   branch?: string;
   siteUrl?: string;
@@ -34,6 +36,7 @@ export async function syncSchema(options: SyncSchemaOptions): Promise<void> {
     options.models as ModelDef[],
     options.blocks,
     options.objects,
+    options.richtext,
   );
   const body: { payload: ReturnType<typeof serializeSchema>; branch: string; siteUrl?: string } = {
     payload,