@backmatter/next 0.0.20 → 0.0.22

package/dist/config.cjs

@@ -87,7 +87,8 @@ var DEFAULT_DIRS = {
   richtext: "richtext",
   mdx: "mdx",
   layouts: "layouts",
-  objects: "objects"
+  objects: "objects",
+  sources: "sources"
 };
 
 // ../core/src/node/discover.ts
@@ -151,6 +152,9 @@ function listLayoutFiles(root, layoutsDir = "layouts") {
 function listObjectFiles(root, objectsDir = "objects") {
   return listModelFiles(root, objectsDir);
 }
+function listSourceDefFiles(root, sourcesDir = "sources") {
+  return listModelFiles(root, sourcesDir);
+}
 function listBlockFiles(root, blocksDir = "blocks") {
   const { files, skipped } = listPascalCaseFiles(root, blocksDir);
   return { blocks: files, skipped };
@@ -189,20 +193,32 @@ function renderCachedCmsClient() {
   return [
     "const raw = createBackmatter({ ...config, models, sync: false });",
     "",
-    "async function getDoc(locale: string, type: string, slug: string) {",
+    "async function cachedGetDoc(locale: string, type: string, slug: string) {",
     '  "use cache";',
     '  cacheLife("hours");',
     "  cacheTag(...contentCacheTags(locale, type, slug));",
     "  return raw.getDoc(locale, type, slug);",
     "}",
     "",
-    "async function listDocs(filter?: { type?: string; locale?: string }) {",
+    "async function cachedListDocs(filter?: { type?: string; locale?: string }) {",
     '  "use cache";',
     '  cacheLife("hours");',
     "  cacheTag(...listCacheTags(filter?.type));",
     "  return raw.listDocs(filter);",
     "}",
     "",
+    "async function getDoc(locale: string, type: string, slug: string) {",
+    "  const preview = currentPreviewContent();",
+    "  if (preview) return preview.getDoc(locale, type, slug);",
+    "  return cachedGetDoc(locale, type, slug);",
+    "}",
+    "",
+    "async function listDocs(filter?: { type?: string; locale?: string }) {",
+    "  const preview = currentPreviewContent();",
+    "  if (preview) return preview.listDocs(filter);",
+    "  return cachedListDocs(filter);",
+    "}",
+    "",
     "/** Typed content client: cms.query.{type}, cms.getDoc, cms.listDocs. */",
     "export const cms = {",
     "  ...raw,",
@@ -217,6 +233,7 @@ function renderModelsBarrel(input) {
   const lines = [GENERATED_HEADER, `import { createBackmatter } from "${input.sdk}";`];
   if (nextHost) {
     lines.push('import { contentCacheTags, createQuery, listCacheTags } from "@backmatter/core";');
+    lines.push('import { currentPreviewContent } from "@backmatter/next/preview-content";');
     lines.push('import { cacheLife, cacheTag } from "next/cache";');
   }
   if (input.configFile) {
@@ -325,6 +342,46 @@ function renderBlockFallbacksBarrel(input) {
 `)}
 `;
 }
+function renderPreviewAction(sdk) {
+  if (sdk !== "@backmatter/next") {
+    return `${GENERATED_HEADER}
+/** Instant preview needs @backmatter/next. This host has no server action. */
+export const renderPreview = null;
+`;
+  }
+  return `"use server";
+${GENERATED_HEADER}
+import { createRenderPreview } from "@backmatter/next/render-preview";
+import { cms } from "./index";
+import { blockLoaders } from "./blocks";
+import { layouts } from "./layouts";
+import { sources } from "./sources";
+import { components as mdxComponents } from "./mdx";
+import { richtextComponents } from "./richtext";
+
+const components = { ...richtextComponents, ...mdxComponents };
+
+export const renderPreview = createRenderPreview(cms, {
+  components,
+  blocks: blockLoaders,
+  layouts,
+  sources,
+});
+`;
+}
+function renderSourcesBarrel(input) {
+  const lines = [GENERATED_HEADER];
+  for (const source of input.sources) {
+    lines.push(`import ${source.importName} from "${importSpecifier(input.outDir, source.file)}";`);
+  }
+  lines.push("");
+  lines.push("/** External record loaders: sources/{type}.ts resolves that model's route data. */");
+  const entries = input.sources.map((s) => s.importName === s.stem ? s.stem : `${JSON.stringify(s.stem)}: ${s.importName}`);
+  lines.push(`export const sources = ${entries.length ? `{ ${entries.join(", ")} }` : "{}"};`);
+  return `${lines.join(`
+`)}
+`;
+}
 function renderLayoutsBarrel(input) {
   const lines = [GENERATED_HEADER];
   for (const layout of input.layouts) {
@@ -348,7 +405,9 @@ var REGISTRY_FILES = [
   "mdx.ts",
   "richtext.ts",
   "layouts.ts",
-  "sync.ts"
+  "sources.ts",
+  "sync.ts",
+  "preview-action.ts"
 ];
 function generate(options) {
   const root = import_node_path2.default.resolve(options.root);
@@ -360,6 +419,7 @@ function generate(options) {
   const { blocks: mdx, skipped: skippedMdx } = listMdxFiles(root, options.mdxDir ?? DEFAULT_DIRS.mdx);
   const layouts = listLayoutFiles(root, options.layoutsDir ?? DEFAULT_DIRS.layouts);
   const objects = listObjectFiles(root, options.objectsDir ?? DEFAULT_DIRS.objects);
+  const sources = listSourceDefFiles(root, options.sourcesDir ?? DEFAULT_DIRS.sources);
   const sdk = options.sdk ?? detectSdk(root);
   const configFile = findConfigFile(root);
   const write = options.write ?? true;
@@ -370,7 +430,9 @@ function generate(options) {
     "mdx.ts": renderMdxBarrel({ outDir, mdx }),
     "richtext.ts": renderRichtextBarrel({ outDir, richtext }),
     "layouts.ts": renderLayoutsBarrel({ outDir, layouts }),
-    "sync.ts": renderSyncBarrel({ outDir, models, blocks, richtext, objects, configFile, sdk })
+    "sources.ts": renderSourcesBarrel({ outDir, sources }),
+    "sync.ts": renderSyncBarrel({ outDir, models, blocks, richtext, objects, configFile, sdk }),
+    "preview-action.ts": renderPreviewAction(sdk)
   };
   const outputs = REGISTRY_FILES.map((name) => {
     const file = import_node_path2.default.join(outDir, name);
@@ -392,6 +454,7 @@ function generate(options) {
     mdx,
     layouts,
     objects,
+    sources,
     skippedBlocks: [...skippedBlocks, ...skippedRichtext],
     skippedMdx,
     configFile
@@ -710,6 +773,7 @@ function resolveLoaderOptions(options = {}) {
     mdxDir: options.mdxDir ?? DEFAULT_DIRS.mdx,
     layoutsDir: options.layoutsDir ?? DEFAULT_DIRS.layouts,
     objectsDir: options.objectsDir ?? DEFAULT_DIRS.objects,
+    sourcesDir: options.sourcesDir ?? DEFAULT_DIRS.sources,
     sdk: SDK
   };
 }
@@ -723,9 +787,10 @@ function generateRegistry(options = {}) {
 function registryMatchers(loaderOptions) {
   const rel = import_node_path4.default.relative(loaderOptions.root, import_node_path4.default.resolve(loaderOptions.root, loaderOptions.outDir)).split(import_node_path4.default.sep).join("/");
   const escaped = rel.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const names = REGISTRY_FILES.map((file) => file.replace(/\.ts$/, "")).join("|");
   return {
     glob: `**/${rel}/*.ts`,
-    test: new RegExp(`(^|[\\\\/])${escaped.replace(/\//g, "[\\\\/]")}[\\\\/](index|blocks|block-fallbacks|mdx|richtext|layouts|sync)\\.ts$`)
+    test: new RegExp(`(^|[\\\\/])${escaped.replace(/\//g, "[\\\\/]")}[\\\\/](${names})\\.ts$`)
   };
 }
 function withBackmatter(nextConfig = {}, options = {}) {

package/dist/loader.cjs

@@ -81,7 +81,8 @@ var DEFAULT_DIRS = {
   richtext: "richtext",
   mdx: "mdx",
   layouts: "layouts",
-  objects: "objects"
+  objects: "objects",
+  sources: "sources"
 };
 
 // ../core/src/node/discover.ts
@@ -145,6 +146,9 @@ function listLayoutFiles(root, layoutsDir = "layouts") {
 function listObjectFiles(root, objectsDir = "objects") {
   return listModelFiles(root, objectsDir);
 }
+function listSourceDefFiles(root, sourcesDir = "sources") {
+  return listModelFiles(root, sourcesDir);
+}
 function listBlockFiles(root, blocksDir = "blocks") {
   const { files, skipped } = listPascalCaseFiles(root, blocksDir);
   return { blocks: files, skipped };
@@ -183,20 +187,32 @@ function renderCachedCmsClient() {
   return [
     "const raw = createBackmatter({ ...config, models, sync: false });",
     "",
-    "async function getDoc(locale: string, type: string, slug: string) {",
+    "async function cachedGetDoc(locale: string, type: string, slug: string) {",
     '  "use cache";',
     '  cacheLife("hours");',
     "  cacheTag(...contentCacheTags(locale, type, slug));",
     "  return raw.getDoc(locale, type, slug);",
     "}",
     "",
-    "async function listDocs(filter?: { type?: string; locale?: string }) {",
+    "async function cachedListDocs(filter?: { type?: string; locale?: string }) {",
     '  "use cache";',
     '  cacheLife("hours");',
     "  cacheTag(...listCacheTags(filter?.type));",
     "  return raw.listDocs(filter);",
     "}",
     "",
+    "async function getDoc(locale: string, type: string, slug: string) {",
+    "  const preview = currentPreviewContent();",
+    "  if (preview) return preview.getDoc(locale, type, slug);",
+    "  return cachedGetDoc(locale, type, slug);",
+    "}",
+    "",
+    "async function listDocs(filter?: { type?: string; locale?: string }) {",
+    "  const preview = currentPreviewContent();",
+    "  if (preview) return preview.listDocs(filter);",
+    "  return cachedListDocs(filter);",
+    "}",
+    "",
     "/** Typed content client: cms.query.{type}, cms.getDoc, cms.listDocs. */",
     "export const cms = {",
     "  ...raw,",
@@ -211,6 +227,7 @@ function renderModelsBarrel(input) {
   const lines = [GENERATED_HEADER, `import { createBackmatter } from "${input.sdk}";`];
   if (nextHost) {
     lines.push('import { contentCacheTags, createQuery, listCacheTags } from "@backmatter/core";');
+    lines.push('import { currentPreviewContent } from "@backmatter/next/preview-content";');
     lines.push('import { cacheLife, cacheTag } from "next/cache";');
   }
   if (input.configFile) {
@@ -319,6 +336,46 @@ function renderBlockFallbacksBarrel(input) {
 `)}
 `;
 }
+function renderPreviewAction(sdk) {
+  if (sdk !== "@backmatter/next") {
+    return `${GENERATED_HEADER}
+/** Instant preview needs @backmatter/next. This host has no server action. */
+export const renderPreview = null;
+`;
+  }
+  return `"use server";
+${GENERATED_HEADER}
+import { createRenderPreview } from "@backmatter/next/render-preview";
+import { cms } from "./index";
+import { blockLoaders } from "./blocks";
+import { layouts } from "./layouts";
+import { sources } from "./sources";
+import { components as mdxComponents } from "./mdx";
+import { richtextComponents } from "./richtext";
+
+const components = { ...richtextComponents, ...mdxComponents };
+
+export const renderPreview = createRenderPreview(cms, {
+  components,
+  blocks: blockLoaders,
+  layouts,
+  sources,
+});
+`;
+}
+function renderSourcesBarrel(input) {
+  const lines = [GENERATED_HEADER];
+  for (const source of input.sources) {
+    lines.push(`import ${source.importName} from "${importSpecifier(input.outDir, source.file)}";`);
+  }
+  lines.push("");
+  lines.push("/** External record loaders: sources/{type}.ts resolves that model's route data. */");
+  const entries = input.sources.map((s) => s.importName === s.stem ? s.stem : `${JSON.stringify(s.stem)}: ${s.importName}`);
+  lines.push(`export const sources = ${entries.length ? `{ ${entries.join(", ")} }` : "{}"};`);
+  return `${lines.join(`
+`)}
+`;
+}
 function renderLayoutsBarrel(input) {
   const lines = [GENERATED_HEADER];
   for (const layout of input.layouts) {
@@ -342,7 +399,9 @@ var REGISTRY_FILES = [
   "mdx.ts",
   "richtext.ts",
   "layouts.ts",
-  "sync.ts"
+  "sources.ts",
+  "sync.ts",
+  "preview-action.ts"
 ];
 function generate(options) {
   const root = import_node_path2.default.resolve(options.root);
@@ -354,6 +413,7 @@ function generate(options) {
   const { blocks: mdx, skipped: skippedMdx } = listMdxFiles(root, options.mdxDir ?? DEFAULT_DIRS.mdx);
   const layouts = listLayoutFiles(root, options.layoutsDir ?? DEFAULT_DIRS.layouts);
   const objects = listObjectFiles(root, options.objectsDir ?? DEFAULT_DIRS.objects);
+  const sources = listSourceDefFiles(root, options.sourcesDir ?? DEFAULT_DIRS.sources);
   const sdk = options.sdk ?? detectSdk(root);
   const configFile = findConfigFile(root);
   const write = options.write ?? true;
@@ -364,7 +424,9 @@ function generate(options) {
     "mdx.ts": renderMdxBarrel({ outDir, mdx }),
     "richtext.ts": renderRichtextBarrel({ outDir, richtext }),
     "layouts.ts": renderLayoutsBarrel({ outDir, layouts }),
-    "sync.ts": renderSyncBarrel({ outDir, models, blocks, richtext, objects, configFile, sdk })
+    "sources.ts": renderSourcesBarrel({ outDir, sources }),
+    "sync.ts": renderSyncBarrel({ outDir, models, blocks, richtext, objects, configFile, sdk }),
+    "preview-action.ts": renderPreviewAction(sdk)
   };
   const outputs = REGISTRY_FILES.map((name) => {
     const file = import_node_path2.default.join(outDir, name);
@@ -386,6 +448,7 @@ function generate(options) {
     mdx,
     layouts,
     objects,
+    sources,
     skippedBlocks: [...skippedBlocks, ...skippedRichtext],
     skippedMdx,
     configFile
@@ -402,12 +465,14 @@ function backmatterLoader(source) {
   const mdxDir = import_node_path3.default.resolve(root, options.mdxDir);
   const layoutsDir = import_node_path3.default.resolve(root, options.layoutsDir);
   const objectsDir = import_node_path3.default.resolve(root, options.objectsDir);
+  const sourcesDir = import_node_path3.default.resolve(root, options.sourcesDir);
   this.addContextDependency(modelsDir);
   this.addContextDependency(blocksDir);
   this.addContextDependency(richtextDir);
   this.addContextDependency(mdxDir);
   this.addContextDependency(layoutsDir);
   this.addContextDependency(objectsDir);
+  this.addContextDependency(sourcesDir);
   this.cacheable?.(true);
   const result = generate({
     root,
@@ -418,6 +483,7 @@ function backmatterLoader(source) {
     mdxDir: options.mdxDir,
     layoutsDir: options.layoutsDir,
     objectsDir: options.objectsDir,
+    sourcesDir: options.sourcesDir,
     sdk: options.sdk
   });
   if (result.configFile)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/next",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "description": "Experimental Next.js adapter for Backmatter. APIs will break. Not ready for production.",
   "type": "module",
   "publishConfig": {
@@ -26,8 +26,11 @@
       "default": "./dist/loader.cjs"
     },
     "./routes": "./src/routes.ts",
+    "./render-preview": "./src/render-preview.ts",
+    "./preview-content": "./src/preview-content.ts",
     "./revalidate": "./src/revalidate.ts",
     "./preview-route": "./src/preview-route.ts",
+    "./cms-proxy": "./src/cms-proxy.ts",
     "./proxy": "./src/proxy.ts",
     "./middleware": "./src/middleware.ts",
     "./page": "./src/page-render.ts"
@@ -43,7 +46,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@backmatter/core": "^0.0.17",
+    "@backmatter/core": "^0.0.19",
     "@mdx-js/mdx": "^3.1.1",
     "remark-gfm": "^4.0.1"
   },

package/src/cms-proxy.ts

@@ -0,0 +1,108 @@
+// packages/next/src/cms-proxy.ts
+// Same-origin proxy. The browser calls this with the preview session cookie.
+// The host attaches that cookie as a bearer token and forwards an allow-list.
+import { PREVIEW_SESSION_COOKIE, readPreviewSession } from "@backmatter/core";
+import type { BackmatterClient } from "@backmatter/core/node/create-backmatter";
+
+const DOC = "/workspaces/[^/]+/docs/[^/]+/[^/]+/[^/]+";
+
+const ALLOWED: Array<{ method: string; pattern: RegExp }> = [
+  { method: "GET", pattern: /^\/workspaces\/[^/]+\/docs$/ },
+  { method: "GET", pattern: new RegExp(`^${DOC}$`) },
+  { method: "PUT", pattern: new RegExp(`^${DOC}$`) },
+  { method: "DELETE", pattern: new RegExp(`^${DOC}$`) },
+  { method: "DELETE", pattern: new RegExp(`^${DOC}/tree$`) },
+  { method: "POST", pattern: new RegExp(`^${DOC}/resolve$`) },
+  { method: "GET", pattern: /^\/workspaces\/[^/]+\/git$/ },
+  { method: "POST", pattern: /^\/workspaces\/[^/]+\/git\/commit$/ },
+  { method: "POST", pattern: /^\/workspaces\/[^/]+\/preview-ticket$/ },
+  { method: "GET", pattern: /^\/preview\/workspaces\/[^/]+\/docs\/[^/]+\/[^/]+\/[^/]+\/stream$/ },
+  { method: "GET", pattern: /^\/preview\/workspaces\/[^/]+\/tree\/stream$/ },
+  { method: "GET", pattern: /^\/workspaces\/[^/]+\/ai\/threads\/[^/]+$/ },
+  { method: "POST", pattern: /^\/workspaces\/[^/]+\/ai\/threads$/ },
+  { method: "POST", pattern: /^\/workspaces\/[^/]+\/ai\/threads\/[^/]+\/messages$/ },
+  { method: "GET", pattern: /^\/preview\/session$/ },
+  { method: "POST", pattern: /^\/preview\/session\/renew$/ },
+];
+
+export function cmsProxyAllowed(method: string, path: string): boolean {
+  return ALLOWED.some((rule) => rule.method === method && rule.pattern.test(path));
+}
+
+/** Workspace id in an allow-listed path, when the path names one. */
+export function workspaceIdFromProxyPath(path: string): string | null {
+  const match = path.match(/^\/(?:preview\/)?workspaces\/([^/]+)/);
+  return match?.[1] ?? null;
+}
+
+function cookieValue(header: string | null, name: string): string | undefined {
+  if (!header) return undefined;
+  for (const part of header.split(";")) {
+    const [key, ...rest] = part.trim().split("=");
+    if (key === name) return rest.join("=");
+  }
+  return undefined;
+}
+
+export type CmsProxyDeps = {
+  fetch?: typeof fetch;
+  readSessionToken?: (req: Request) => Promise<string | undefined> | string | undefined;
+};
+
+export function createCmsProxy(
+  cms: Pick<BackmatterClient, "config">,
+  deps: CmsProxyDeps = {},
+) {
+  const forward = deps.fetch ?? fetch;
+  const readSessionToken =
+    deps.readSessionToken ??
+    ((req: Request) => cookieValue(req.headers.get("cookie"), PREVIEW_SESSION_COOKIE));
+
+  const handle = async (req: Request): Promise<Response> => {
+    const secret = cms.config.previewToken;
+    const apiUrl = cms.config.apiUrl;
+    if (!secret || !apiUrl) return Response.json({ error: "preview_not_configured" }, { status: 503 });
+
+    const url = new URL(req.url);
+    const marker = "/api/backmatter/cms";
+    const at = url.pathname.indexOf(marker);
+    const path = at === -1 ? "" : url.pathname.slice(at + marker.length) || "/";
+    if (!cmsProxyAllowed(req.method, path)) {
+      return Response.json({ error: "not_found" }, { status: 404 });
+    }
+
+    const token = await readSessionToken(req);
+    const session = await readPreviewSession(secret, token);
+    if (!session) return Response.json({ error: "unauthorized" }, { status: 401 });
+    const pathWorkspace = workspaceIdFromProxyPath(path);
+    if (pathWorkspace && pathWorkspace !== session.workspaceId) {
+      return Response.json({ error: "forbidden" }, { status: 403 });
+    }
+    if (cms.config.workspaceId && session.workspaceId !== cms.config.workspaceId) {
+      return Response.json({ error: "forbidden" }, { status: 403 });
+    }
+
+    const upstream = new URL(`${apiUrl.replace(/\/$/, "")}${path}`);
+    upstream.search = url.search;
+    const headers = new Headers();
+    headers.set("Authorization", `Bearer ${token}`);
+    const contentType = req.headers.get("content-type");
+    if (contentType) headers.set("Content-Type", contentType);
+    const accept = req.headers.get("accept");
+    if (accept) headers.set("Accept", accept);
+
+    const hasBody = req.method !== "GET" && req.method !== "HEAD";
+    const res = await forward(upstream, {
+      method: req.method,
+      headers,
+      body: hasBody ? await req.arrayBuffer() : undefined,
+    });
+    const responseHeaders = new Headers();
+    const type = res.headers.get("content-type");
+    if (type) responseHeaders.set("Content-Type", type);
+    responseHeaders.set("Cache-Control", "no-store");
+    return new Response(res.body, { status: res.status, headers: responseHeaders });
+  };
+
+  return { GET: handle, POST: handle, PUT: handle, DELETE: handle };
+}

package/src/config.ts

@@ -14,6 +14,7 @@ import {
   DEFAULT_OUT_DIR,
   detectSdk,
   generate,
+  REGISTRY_FILES,
   type GenerateResult,
 } from "@backmatter/core/generate";
 import {
@@ -33,6 +34,7 @@ export type WithBackmatterOptions = {
   mdxDir?: string;
   layoutsDir?: string;
   objectsDir?: string;
+  sourcesDir?: string;
   /** Called after the boot-time generation. Default: log what changed. */
   onGenerate?: (result: GenerateResult) => void;
 };
@@ -92,6 +94,7 @@ export function resolveLoaderOptions(options: WithBackmatterOptions = {}): Backm
     mdxDir: options.mdxDir ?? DEFAULT_DIRS.mdx,
     layoutsDir: options.layoutsDir ?? DEFAULT_DIRS.layouts,
     objectsDir: options.objectsDir ?? DEFAULT_DIRS.objects,
+    sourcesDir: options.sourcesDir ?? DEFAULT_DIRS.sources,
     sdk: SDK,
   };
 }
@@ -112,9 +115,12 @@ export function registryMatchers(loaderOptions: BackmatterLoaderOptions): { glob
     .split(path.sep)
     .join("/");
   const escaped = rel.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const names = REGISTRY_FILES.map((file) => file.replace(/\.ts$/, "")).join("|");
   return {
     glob: `**/${rel}/*.ts`,
-    test: new RegExp(`(^|[\\\\/])${escaped.replace(/\//g, "[\\\\/]")}[\\\\/](index|blocks|block-fallbacks|mdx|richtext|layouts|sync)\\.ts$`),
+    test: new RegExp(
+      `(^|[\\\\/])${escaped.replace(/\//g, "[\\\\/]")}[\\\\/](${names})\\.ts$`,
+    ),
   };
 }
 

package/src/devbar-client.tsx

@@ -2,6 +2,7 @@
 "use client";
 
 import { useEffect, useState, type CSSProperties, type ReactNode } from "react";
+import { SiteChrome } from "./site-editor";
 import {
   clearHostPreviewSession,
   fetchCmsSession,
@@ -80,7 +81,7 @@ const barStyle: CSSProperties = {
   alignItems: "center",
   gap: 10,
   minHeight: 32,
-  maxWidth: "min(360px, calc(100vw - 24px))",
+  maxWidth: "min(520px, calc(100vw - 24px))",
   padding: "0 12px",
   paddingBottom: "env(safe-area-inset-bottom, 0px)",
   background: "#f4f4f5",
@@ -187,10 +188,12 @@ function Divider() {
 export function DevBarView({
   state,
   onExit,
+  onEdit,
   exiting,
 }: {
   state: DevModeState;
   onExit?: () => void;
+  onEdit?: () => void;
   exiting?: boolean;
 }) {
   if (state.status !== "ready") return null;
@@ -240,6 +243,20 @@ export function DevBarView({
           <Segment>draft</Segment>
         </>
       ) : null}
+      {!live && onEdit ? (
+        <>
+          <Divider />
+          <button
+            type="button"
+            className="backmatter-devbar-exit"
+            aria-label="Edit this page"
+            onClick={() => onEdit()}
+            style={exitButtonStyle}
+          >
+            Edit
+          </button>
+        </>
+      ) : null}
       {!live ? (
         <>
           <Divider />
@@ -262,19 +279,17 @@ export function DevBarView({
 export function DevBarClient({ apiUrl }: { apiUrl: string }) {
   const state = useDevMode({ apiUrl });
   const [exiting, setExiting] = useState(false);
-  return (
-    <DevBarView
-      state={state}
-      exiting={exiting}
-      onExit={() => {
-        if (exiting) return;
-        setExiting(true);
-        void exitHostPreview().then((ok) => {
-          if (!ok) setExiting(false);
-        });
-      }}
-    />
-  );
+  const exit = () => {
+    if (exiting) return;
+    setExiting(true);
+    void exitHostPreview().then((ok) => {
+      if (!ok) setExiting(false);
+    });
+  };
+  if (state.status === "ready" && state.mode === "preview") {
+    return <SiteChrome branch={state.branch} tree={state.tree} exiting={exiting} onExit={exit} />;
+  }
+  return <DevBarView state={state} exiting={exiting} onExit={exit} />;
 }
 
 export async function exitHostPreview(

package/src/layout-doc.ts

@@ -0,0 +1,38 @@
+// packages/next/src/layout-doc.ts
+// Shared body render for the catch-all and `renderPreview`. No preview chrome.
+// `data` is the external source record already resolved by the caller
+// (see source-data.ts); this module only threads it to blocks and the layout.
+import { createElement, type ReactNode } from "react";
+import { modelFormat, type BackmatterDoc, type ModelDef, type SourceDef } from "@backmatter/core";
+import { renderDoc, type MdxComponents } from "./mdx-compile";
+import { renderPage, type BlockComponents, type BlockFallbacks } from "./page-render";
+
+export type DocLayout = (doc: BackmatterDoc, body: ReactNode, data?: unknown) => ReactNode;
+
+export type LayoutDocOptions = {
+  models: readonly ModelDef[];
+  components?: MdxComponents;
+  blocks?: BlockComponents;
+  fallbacks?: BlockFallbacks;
+  layouts?: Record<string, DocLayout>;
+  /** `sources/{type}.ts` loaders, usually the generated `sources`. Resolved by the caller. */
+  sources?: Record<string, SourceDef>;
+  render?: (doc: BackmatterDoc, body: ReactNode) => ReactNode;
+};
+
+export async function renderLayoutDoc(
+  doc: BackmatterDoc,
+  options: LayoutDocOptions,
+  data?: unknown,
+): Promise<ReactNode> {
+  const model = options.models.find((item) => item.type === doc.type);
+  const isPage = Boolean(model && modelFormat(model) === "page");
+  const rendered = isPage
+    ? await renderPage(doc, options.blocks, options.fallbacks, data)
+    : await renderDoc(doc, { components: options.components });
+  const layout = options.layouts?.[doc.type];
+  const laidOut = layout ? layout(doc, rendered, data) : rendered;
+  if (options.render) return options.render(doc, laidOut);
+  if (layout || isPage) return laidOut;
+  return createElement("article", null, laidOut);
+}

package/src/loader.ts

@@ -1,10 +1,10 @@
 // packages/next/src/loader.ts
 // Bundler loader for `.backmatter/index.ts`, `.backmatter/blocks.ts`,
-// `.backmatter/mdx.ts`, `.backmatter/richtext.ts`, and `.backmatter/layouts.ts`.
+// `.backmatter/mdx.ts`, `.backmatter/richtext.ts`, `.backmatter/layouts.ts`, and `.backmatter/sources.ts`.
 //
 // This is the Tailwind-JIT mechanism: instead of running our own watcher we
 // tell the bundler that these modules depend on the `models/`, `blocks/`,
-// `richtext/`, `mdx/`, and `layouts/` directories. webpack and Turbopack already watch the filesystem;
+// `richtext/`, `mdx/`, `layouts/`, and `sources/` directories. webpack and Turbopack already watch the filesystem;
 // when a file is added, removed or renamed there they invalidate the module,
 // re-run this loader, and we regenerate the barrel from a fresh `readdir`.
 import path from "node:path";
@@ -19,6 +19,7 @@ export type BackmatterLoaderOptions = {
   mdxDir: string;
   layoutsDir: string;
   objectsDir: string;
+  sourcesDir: string;
   sdk: string;
 };
 
@@ -40,6 +41,7 @@ export default function backmatterLoader(this: BackmatterLoaderContext, source:
   const mdxDir = path.resolve(root, options.mdxDir);
   const layoutsDir = path.resolve(root, options.layoutsDir);
   const objectsDir = path.resolve(root, options.objectsDir);
+  const sourcesDir = path.resolve(root, options.sourcesDir);
 
   this.addContextDependency(modelsDir);
   this.addContextDependency(blocksDir);
@@ -47,6 +49,7 @@ export default function backmatterLoader(this: BackmatterLoaderContext, source:
   this.addContextDependency(mdxDir);
   this.addContextDependency(layoutsDir);
   this.addContextDependency(objectsDir);
+  this.addContextDependency(sourcesDir);
   this.cacheable?.(true);
 
   const result = generate({
@@ -58,6 +61,7 @@ export default function backmatterLoader(this: BackmatterLoaderContext, source:
     mdxDir: options.mdxDir,
     layoutsDir: options.layoutsDir,
     objectsDir: options.objectsDir,
+    sourcesDir: options.sourcesDir,
     sdk: options.sdk,
   });
   if (result.configFile) this.addDependency(result.configFile);