@open-press/core 0.5.0 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # @open-press/core
 
-Framework runtime, CLI engine, and page primitives for [open-press](https://github.com/quan0715/open-press) — an AI-first fixed-layout document workspace.
+Framework runtime, CLI engine, and Press Tree primitives for [open-press](https://github.com/quan0715/open-press) — an AI-first fixed-layout document workspace.
 
 Most users do **not** install this package directly. Instead, scaffold a workspace with the CLI:
 
@@ -20,15 +20,19 @@ npm install @open-press/core
 
 ```tsx
 import {
-  BasePage,
-  BaseCoverPage,
-  BaseTocPage,
-  BaseBackCoverPage,
+  Press,
+  Frame,
+  MdxArea,
   BaseFigure,
   BaseCallout,
 } from "@open-press/core";
+
+import { mdxSource } from "@open-press/core/mdx";
+import { Sections, Toc } from "@open-press/core/manuscript";
 ```
 
+`document/index.tsx` default-exports a `<Press>` tree. `Frame` marks fixed-layout pages, `MdxArea` receives measured MDX blocks, and `mdxSource()` declares which MDX files participate in the render pipeline.
+
 The CLI bin (`open-press`) supports dev / build / preview / validate / pdf / deploy / export commands. It requires a workspace with `openpress.config.mjs` and the surrounding framework files (which the scaffolder installs).
 
 ## License

package/engine/cli.mjs

@@ -6,7 +6,6 @@ import * as doctorCmd from "./commands/doctor.mjs";
 import * as exportCmd from "./commands/export.mjs";
 import * as initCmd from "./commands/init.mjs";
 import * as inspectCmd from "./commands/inspect.mjs";
-import * as migrateToReactCmd from "./commands/migrate-to-react.mjs";
 import * as pdfCmd from "./commands/pdf.mjs";
 import * as previewCmd from "./commands/preview.mjs";
 import * as replaceCmd from "./commands/replace.mjs";
@@ -16,13 +15,12 @@ import * as typecheckCmd from "./commands/typecheck.mjs";
 import * as upgradeCmd from "./commands/upgrade.mjs";
 import * as validateCmd from "./commands/validate.mjs";
 import { parseOptions } from "./commands/_shared.mjs";
-import { loadConfig } from "./config.mjs";
+import { loadConfig } from "./runtime/config.mjs";
 import { listStylePackSkills } from "./init.mjs";
-import { discoverWorkspace } from "./validation.mjs";
+import { discoverWorkspace } from "./runtime/validation.mjs";
 
 const COMMANDS = {
   init: initCmd,
-  "migrate-to-react": migrateToReactCmd,
   validate: validateCmd,
   inspect: inspectCmd,
   search: searchCmd,
@@ -79,7 +77,6 @@ async function printHelp() {
 
 Commands:
   init <target> [--skill <name>] [--force]
-  migrate-to-react [path] [--dry-run] [--force] [--json]
   validate
   inspect [--json] [--no-build] [--dry-run]
   search [path] <query> [--json] [--scope content|all]

package/engine/commands/_shared.mjs

@@ -2,14 +2,14 @@ import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { printUrlToPdf, stopChildProcess, waitForPrintReady } from "../chrome-pdf.mjs";
-import { loadConfig, publicPdfHref } from "../config.mjs";
+import { printUrlToPdf, stopChildProcess, waitForPrintReady } from "../output/chrome-pdf.mjs";
+import { loadConfig, publicPdfHref } from "../runtime/config.mjs";
 import { exportDocument } from "../document-export.mjs";
-import { optimizePdfMediaForStaticRoot } from "../pdf-media.mjs";
+import { optimizePdfMediaForStaticRoot } from "../output/pdf-media.mjs";
 
 export const ENGINE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 export const CLI_ENTRY = path.join(ENGINE_DIR, "cli.mjs");
-export const STATIC_SERVER = path.join(ENGINE_DIR, "static-server.mjs");
+export const STATIC_SERVER = path.join(ENGINE_DIR, "output", "static-server.mjs");
 
 export function parseOptions(argv) {
   const options = {};

package/engine/commands/deploy.mjs

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { deploySync } from "../deploy-sync.mjs";
+import { deploySync } from "../output/deploy-sync.mjs";
 import { CLI_ENTRY, buildReactPdf, formatNodeScriptCommand, runCommand, writePdfStageDeployConfig } from "./_shared.mjs";
 
 export async function run({ root, config, options, recurse }) {

package/engine/commands/inspect.mjs

@@ -1,5 +1,5 @@
-import { inspectWorkspace } from "../inspection.mjs";
-import { exitCodeForIssueReport } from "../issue-report.mjs";
+import { inspectWorkspace } from "../runtime/inspection.mjs";
+import { exitCodeForIssueReport } from "../runtime/issue-report.mjs";
 
 export async function run({ root, config, options, recurse }) {
   const host = options.host ?? "127.0.0.1";
@@ -10,7 +10,7 @@ export async function run({ root, config, options, recurse }) {
     if (!options.noBuild) {
       console.log("Command: node engine/cli.mjs render . --renderer react");
     }
-    console.log(`Command: node engine/static-server.mjs ${config.outputDir} --host ${host} --port ${port} --workspace .`);
+    console.log(`Command: node engine/output/static-server.mjs ${config.outputDir} --host ${host} --port ${port} --workspace .`);
     console.log(`Chrome inspection URL: ${url}`);
     return 0;
   }

package/engine/commands/replace.mjs

@@ -1,4 +1,4 @@
-import { replaceSourceText } from "../source-text-tools.mjs";
+import { replaceSourceText } from "../runtime/source-text-tools.mjs";
 
 export async function run({ config, options }) {
   const args = replaceArgsFromOptions(options);

package/engine/commands/search.mjs

@@ -1,4 +1,4 @@
-import { searchSourceText } from "../source-text-tools.mjs";
+import { searchSourceText } from "../runtime/source-text-tools.mjs";
 
 export async function run({ config, options }) {
   const query = searchQueryFromOptions(options);

package/engine/commands/validate.mjs

@@ -1,5 +1,5 @@
-import { validateWorkspace } from "../validation.mjs";
-import { exitCodeForIssueReport } from "../issue-report.mjs";
+import { validateWorkspace } from "../runtime/validation.mjs";
+import { exitCodeForIssueReport } from "../runtime/issue-report.mjs";
 
 export async function run({ root, options }) {
   const report = await validateWorkspace(root);

package/engine/document-export.mjs

@@ -10,6 +10,6 @@ export async function exportDocument(root = ROOT) {
   if (reactResult) return reactResult;
 
   throw new Error(
-    "React/MDX document entry not found. Expected document/index.tsx; run `node engine/cli.mjs migrate-to-react .` before exporting.",
+    "React/MDX document entry not found. Expected document/index.tsx with a Press default export before exporting.",
   );
 }

package/engine/{chrome-pdf.mjs → output/chrome-pdf.mjs}

@@ -203,8 +203,7 @@ export async function waitForPrintReady(client) {
       awaitPromise: true,
       expression: `Promise.resolve().then(async () => {
         const root = document.querySelector('[data-openpress-print-document="true"]');
-        const ready = root?.getAttribute('data-openpress-pagination') === 'ready';
-        if (!ready) return 0;
+        if (!root || root.querySelectorAll('.openpress-html-page').length === 0) return 0;
 
         await document.fonts?.ready;
         await Promise.all(Array.from(document.images).map(async (img) => {

package/engine/{deploy-sync.mjs → output/deploy-sync.mjs}

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { loadConfig } from "./config.mjs";
-import { copyDirectory } from "./file-utils.mjs";
+import { loadConfig } from "../runtime/config.mjs";
+import { copyDirectory } from "../runtime/file-utils.mjs";
 
 export async function deploySync(root, sourceDir, deployDir) {
   const config = await loadConfig(root);

package/engine/{fonts.mjs → output/fonts.mjs}

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { copyDirectory } from "./file-utils.mjs";
+import { copyDirectory } from "../runtime/file-utils.mjs";
 
 export async function copyThemeFonts(root, publicOutputDir, config) {
   const themeDir = config?.paths?.themeDir ?? path.join(path.resolve(root), "theme");

package/engine/{public-assets.mjs → output/public-assets.mjs}

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { loadConfig } from "./config.mjs";
-import { copyDirectory, writeComponentsCss, writeContentCss } from "./file-utils.mjs";
+import { loadConfig } from "../runtime/config.mjs";
+import { copyDirectory, writeComponentsCss, writeContentCss } from "../runtime/file-utils.mjs";
 import { copyThemeFonts } from "./fonts.mjs";
 import { copyKatexFonts } from "./katex-assets.mjs";
 

package/engine/{static-server.mjs → output/static-server.mjs}

@@ -2,8 +2,8 @@ import fs from "node:fs/promises";
 import http from "node:http";
 import path from "node:path";
 import { spawn } from "node:child_process";
-import { loadConfig, publicPdfHref } from "./config.mjs";
-import { handleProjectAssetRequest } from "./react/project-asset-endpoint.mjs";
+import { loadConfig, publicPdfHref } from "../runtime/config.mjs";
+import { handleProjectAssetRequest } from "../react/project-asset-endpoint.mjs";
 
 const [rootArg = "dist", ...rest] = process.argv.slice(2);
 const host = valueAfter(rest, "--host") ?? "127.0.0.1";

package/engine/react/caption-numbering.mjs

@@ -0,0 +1,73 @@
+const DEFAULT_CAPTION_NUMBERING = {
+  figure: "Figure",
+  table: "Table",
+  separator: " ",
+};
+
+export function normalizeCaptionNumbering(value = {}) {
+  const input = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  return {
+    figure: stringOption(input.figure, DEFAULT_CAPTION_NUMBERING.figure),
+    table: stringOption(input.table, DEFAULT_CAPTION_NUMBERING.table),
+    separator: typeof input.separator === "string" ? input.separator : DEFAULT_CAPTION_NUMBERING.separator,
+  };
+}
+
+export function createCaptionNumberingState() {
+  return {
+    figure: 0,
+    table: 0,
+    seenTables: new Set(),
+  };
+}
+
+export function numberCaptionsInHtml(html, numbering, state = createCaptionNumberingState()) {
+  if (!html) return html;
+  const options = normalizeCaptionNumbering(numbering);
+  let out = String(html);
+  out = numberTableCaptions(out, options, state);
+  out = numberFigureCaptions(out, options, state);
+  return out;
+}
+
+function numberTableCaptions(html, options, state) {
+  return html.replace(/<table\b([^>]*)>([\s\S]*?<caption\b([^>]*)>)([\s\S]*?)(<\/caption>[\s\S]*?<\/table>)/g, (match, tableAttrs, beforeCaptionText, captionAttrs, captionText, afterCaptionText) => {
+    if (captionText.includes("data-openpress-caption-label=")) return match;
+    const tableId = attrValue(tableAttrs, "data-openpress-table-id");
+    if (tableId && state.seenTables.has(tableId)) return match;
+    if (tableId) state.seenTables.add(tableId);
+    state.table += 1;
+    const label = captionLabel(options.table, state.table, options.separator);
+    return `<table${tableAttrs}>${beforeCaptionText}${captionLabelSpan("table", state.table, label)} ${captionText}${afterCaptionText}`;
+  });
+}
+
+function numberFigureCaptions(html, options, state) {
+  return html.replace(/<figure\b([^>]*)>([\s\S]*?<figcaption\b([^>]*)>)([\s\S]*?)(<\/figcaption>[\s\S]*?<\/figure>)/g, (match, figureAttrs, beforeCaptionText, captionAttrs, captionText, afterCaptionText) => {
+    if (captionText.includes("data-openpress-caption-label=")) return match;
+    state.figure += 1;
+    const label = captionLabel(options.figure, state.figure, options.separator);
+    return `<figure${figureAttrs}>${beforeCaptionText}${captionLabelSpan("figure", state.figure, label)} ${captionText}${afterCaptionText}`;
+  });
+}
+
+function captionLabel(noun, number, separator) {
+  return `${noun}${separator}${number}`;
+}
+
+function captionLabelSpan(kind, number, label) {
+  return `<span class="openpress-caption-label" data-openpress-caption-label="${kind}" data-openpress-caption-number="${number}">${escapeHtml(label)}</span>`;
+}
+
+function attrValue(attrs, name) {
+  const pattern = new RegExp(`${name}=(["'])(.*?)\\1`);
+  return attrs.match(pattern)?.[2] ?? "";
+}
+
+function stringOption(value, fallback) {
+  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+
+function escapeHtml(value) {
+  return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/engine/react/comment-marker.mjs

@@ -1,15 +1,18 @@
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { loadConfig } from "../config.mjs";
-import { collectSourceTextFiles } from "../source-text-tools.mjs";
-
+import { loadConfig } from "../runtime/config.mjs";
+import { collectSourceTextFiles } from "../runtime/source-text-tools.mjs";
+
+// Any `.mdx` or `.tsx` file under `document/` is a legal comment target.
+// The Press Tree allows arbitrary source layouts — `section-folders`,
+// `section-files`, `file-list`, custom `root` paths, etc. — so we no
+// longer hardcode `document/chapters/<slug>/content/*.mdx`. The boundary
+// is "inside the workspace's authored `document/` directory" and "looks
+// like an editable React/MDX source" by extension.
 const EDITABLE_COMMENT_SOURCE_PATTERNS = [
-  /^document\/index\.tsx$/,
-  /^document\/chapters\/[^/]+\/content\/[^/]+\.mdx$/,
-  /^document\/chapters\/[^/]+\/chapter\.tsx$/,
-  /^document\/chapters\/[^/]+\/components\/.+\.tsx$/,
-  /^document\/components\/.+\.tsx$/,
+  /^document\/.+\.mdx$/,
+  /^document\/.+\.tsx$/,
 ];
 const COMMENT_MARKER_RE = /\{\/\*\s*@openpress-comment\b(?<attrs>[^*]*)\*\/\}/g;
 const COMMENT_LINE_RE = /^\s*\{\/\*\s*@openpress-comment\b[^*]*\*\/\}\s*$/;
@@ -138,8 +141,14 @@ export function assertEditableCommentPath(relativePath) {
   }
 }
 
+// Strict check against workspace-relative paths. Callers walking the
+// workspace (`applyCommentMarker` via `collectSourceTextFiles`) already
+// receive paths with the `document/` prefix and must not have system
+// paths silently mapped into the editable set.
 export function isEditableCommentPath(relativePath) {
-  return EDITABLE_COMMENT_SOURCE_PATTERNS.some((pattern) => pattern.test(relativePath));
+  if (typeof relativePath !== "string" || !relativePath) return false;
+  const trimmed = relativePath.trim().replaceAll("\\", "/").replace(/^\.\//, "");
+  return EDITABLE_COMMENT_SOURCE_PATTERNS.some((pattern) => pattern.test(trimmed));
 }
 
 function normalizeEditableSourcePath(value) {
@@ -150,7 +159,42 @@ function normalizeEditableSourcePath(value) {
   if (path.posix.isAbsolute(normalized) || normalized.includes("\0") || normalized === "." || normalized.startsWith("../")) {
     throw new Error(`OpenPress comment target path is invalid: ${value}`);
   }
-  return path.posix.normalize(normalized);
+  const posix = path.posix.normalize(normalized);
+  // The Press Tree source resolver emits paths relative to `document/`
+  // (e.g. "chapters/01-start/content/01-start.mdx"). The comment marker
+  // works in workspace-relative paths (with the `document/` prefix). If
+  // the incoming path is documentRoot-relative, prepend `document/`.
+  if (!posix.startsWith("document/") && looksDocumentRelative(posix)) {
+    return `document/${posix}`;
+  }
+  return posix;
+}
+
+// Identify paths the Press Tree source resolver emits — those are relative
+// to `document/`. Match `.mdx` / `.tsx` files that don't already have the
+// `document/` prefix and don't look like system / engine paths. The check
+// is intentionally tight so we never silently rewrite engine internals
+// (e.g. `src/openpress/...`) into "editable" workspace paths.
+const SYSTEM_PATH_PREFIXES = [
+  "document/",
+  "src/",
+  "engine/",
+  "dist/",
+  "dist-react/",
+  "node_modules/",
+  "tests/",
+  "public/",
+  "packages/",
+  ".openpress/",
+  ".deploy/",
+  ".changeset/",
+  ".github/",
+];
+
+function looksDocumentRelative(posixPath) {
+  if (!/\.(mdx|tsx)$/.test(posixPath)) return false;
+  if (SYSTEM_PATH_PREFIXES.some((prefix) => posixPath.startsWith(prefix))) return false;
+  return true;
 }
 
 function normalizeLineNumber(value) {

package/engine/react/document-entry.mjs

@@ -1,3 +1,10 @@
+// Layer 1 — Document entry loader.
+//
+// Loads `document/index.tsx`, validates it exports a Press component as
+// default, reads optional `config` and `sources` named exports, and sets
+// up the vite SSR server with `@open-press/core` aliases (including the
+// subpaths `/mdx` and `/manuscript`).
+
 import fs from "node:fs/promises";
 import { createRequire } from "node:module";
 import path from "node:path";
@@ -5,16 +12,19 @@ import { fileURLToPath } from "node:url";
 import react from "@vitejs/plugin-react";
 import ts from "typescript";
 import { createServer as createViteServer } from "vite";
-import { normalizeConfig } from "../config.mjs";
+import { normalizeConfig } from "../runtime/config.mjs";
 
 const ENGINE_REACT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const FRAMEWORK_ROOT = path.resolve(ENGINE_REACT_DIR, "..", "..");
-const CORE_ENTRY = path.join(FRAMEWORK_ROOT, "src", "openpress", "core", "index.tsx");
+export const CORE_ENTRY = path.join(FRAMEWORK_ROOT, "src", "openpress", "core", "index.tsx");
+export const MDX_ENTRY = path.join(FRAMEWORK_ROOT, "src", "openpress", "mdx", "index.ts");
+export const MANUSCRIPT_ENTRY = path.join(FRAMEWORK_ROOT, "src", "openpress", "manuscript", "index.tsx");
+export const NUMBERING_ENTRY = path.join(FRAMEWORK_ROOT, "src", "openpress", "numbering", "index.ts");
 const REACT_PACKAGE_ROOT = path.join(FRAMEWORK_ROOT, "node_modules", "react");
 const require = createRequire(import.meta.url);
 const REACT_EXPORT_NAMES = Object.keys(require("react")).filter((name) => /^[A-Za-z_$][\w$]*$/.test(name));
 
-export async function loadReactDocumentEntry(root = ".") {
+export async function loadReactDocumentEntry(root = ".", { server: externalServer } = {}) {
   const workspaceRoot = path.resolve(root);
   const entryPath = path.join(workspaceRoot, "document", "index.tsx");
   if (!(await fileExists(entryPath))) return null;
@@ -22,22 +32,34 @@ export async function loadReactDocumentEntry(root = ".") {
   const source = await fs.readFile(entryPath, "utf8");
   assertNoObviousTopLevelSideEffects(source, entryPath);
 
-  const server = await createReactSsrServer(workspaceRoot);
-
+  // If caller provides a server, reuse it so module identity is shared
+  // across the pipeline (PressContext, React, etc.). Otherwise open a
+  // temporary server for one-shot config reads.
+  const ownServer = externalServer ?? (await createReactSsrServer(workspaceRoot));
   try {
-    const mod = await server.ssrLoadModule(entryPath);
+    const mod = await ownServer.ssrLoadModule(entryPath);
+
+    // Press default export is required for export/render but not for
+    // config-only commands (search, replace, validate). Validate if present;
+    // export pipeline throws separately if it's missing when actually needed.
+    const Press = typeof mod.default === "function" ? mod.default : null;
+
     const config = normalizeReactDocumentConfig(workspaceRoot, entryPath, mod.config);
+    const sources = mod.sources ?? {};
+    if (sources && (typeof sources !== "object" || Array.isArray(sources))) {
+      throw new Error(
+        `OpenPress document entry ${entryPath} \`sources\` export must be an object literal (or omitted).`,
+      );
+    }
+
     return {
       entryPath,
       config,
-      shell: {
-        cover: mod.cover ?? null,
-        toc: mod.toc ?? null,
-        backCover: mod.backCover ?? null,
-      },
+      Press,
+      sources,
     };
   } finally {
-    await server.close();
+    if (!externalServer) await ownServer.close();
   }
 }
 
@@ -51,7 +73,12 @@ export async function createReactSsrServer(workspaceRoot = ".") {
     plugins: [reactRuntimePlugin(), react()],
     resolve: {
       alias: [
-        { find: "@openpress/core", replacement: CORE_ENTRY },
+        // ORDER MATTERS: subpath aliases must precede the base alias so that
+        // `@open-press/core/mdx` doesn't resolve to `@open-press/core` + `/mdx`.
+        { find: "@open-press/core/mdx", replacement: MDX_ENTRY },
+        { find: "@open-press/core/manuscript", replacement: MANUSCRIPT_ENTRY },
+        { find: "@open-press/core/numbering", replacement: NUMBERING_ENTRY },
+        { find: "@open-press/core", replacement: CORE_ENTRY },
         { find: "@/components", replacement: path.join(resolvedWorkspaceRoot, "document", "components") },
       ],
     },
@@ -64,23 +91,6 @@ export async function createReactSsrServer(workspaceRoot = ".") {
   });
 }
 
-function normalizeReactDocumentConfig(workspaceRoot, entryPath, config) {
-  if (config != null && (typeof config !== "object" || Array.isArray(config))) {
-    throw new Error("OpenPress React document entry `config` export must be an object when provided.");
-  }
-  const rawConfig = config ?? {};
-  const paths = rawConfig.paths ?? {};
-  return normalizeConfig(workspaceRoot, {
-    ...rawConfig,
-    documentDir: rawConfig.documentDir ?? paths.documentDir ?? "document",
-    sourceDir: rawConfig.sourceDir ?? paths.chaptersDir ?? paths.sourceDir ?? "chapters",
-    componentsDir: rawConfig.componentsDir ?? paths.componentsDir ?? "components",
-    mediaDir: rawConfig.mediaDir ?? paths.mediaDir ?? "media",
-    themeDir: rawConfig.themeDir ?? paths.themeDir ?? "theme",
-    designDoc: rawConfig.designDoc ?? paths.designDoc ?? "design.md",
-  }, entryPath);
-}
-
 function assertNoObviousTopLevelSideEffects(source, entryPath) {
   const sourceFile = ts.createSourceFile(entryPath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
   for (const statement of sourceFile.statements) {
@@ -89,84 +99,117 @@ function assertNoObviousTopLevelSideEffects(source, entryPath) {
       continue;
     }
 
-    if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) {
-      continue;
-    }
-
-    if (ts.isExportDeclaration(statement) && statement.isTypeOnly) {
-      continue;
-    }
-
+    if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) continue;
+    if (ts.isExportDeclaration(statement) && statement.isTypeOnly) continue;
+    if (ts.isFunctionDeclaration(statement)) continue;
     if (ts.isVariableStatement(statement)) {
-      assertExportedConstStatement(statement, entryPath);
+      assertTopLevelVariableStatement(statement, entryPath);
       continue;
     }
-
-    if (ts.isExpressionStatement(statement)) {
-      assertPureTopLevelInitializer(statement.expression, entryPath);
+    if (ts.isExportAssignment(statement)) {
+      assertPureDefaultExport(statement.expression, entryPath);
+      continue;
     }
 
-    throw new Error(`OpenPress React document entry has unsupported top-level code in ${entryPath}: ${statementKindName(statement)}`);
+    throw new Error(`OpenPress document entry has unsupported top-level code in ${entryPath}: ${statementKindName(statement)}`);
   }
 }
 
 function assertPureImport(statement, entryPath) {
   if (!statement.importClause) {
-    throw new Error(`OpenPress React document entry has an unsupported side-effect import in ${entryPath}`);
+    throw new Error(`OpenPress document entry has an unsupported side-effect import in ${entryPath}`);
   }
   const moduleName = stringLiteralText(statement.moduleSpecifier);
   if (!statement.importClause.isTypeOnly && isFileSystemModule(moduleName)) {
-    throw new Error(`OpenPress React document entry imports filesystem APIs at top level in ${entryPath}`);
+    throw new Error(`OpenPress document entry imports filesystem APIs at top level in ${entryPath}`);
   }
 }
 
-function assertExportedConstStatement(statement, entryPath) {
-  if (!hasModifier(statement, ts.SyntaxKind.ExportKeyword)) {
-    throw new Error(`OpenPress React document entry only allows exported const declarations at top level in ${entryPath}`);
-  }
+function assertTopLevelVariableStatement(statement, entryPath) {
   if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) {
-    throw new Error(`OpenPress React document entry only allows exported const declarations at top level in ${entryPath}`);
+    throw new Error(`OpenPress document entry only allows top-level const declarations in ${entryPath}`);
   }
 
+  const exported = hasModifier(statement, ts.SyntaxKind.ExportKeyword);
   for (const declaration of statement.declarationList.declarations) {
-    if (declaration.initializer) assertPureTopLevelInitializer(declaration.initializer, entryPath);
+    if (!ts.isIdentifier(declaration.name)) {
+      throw new Error(`OpenPress document entry only allows identifier const declarations at top level in ${entryPath}`);
+    }
+    const name = declaration.name.text;
+    if (exported && name !== "config" && name !== "sources") {
+      throw new Error(`OpenPress document entry only allows exported const config and sources in ${entryPath}`);
+    }
+    if (!declaration.initializer) {
+      throw new Error(`OpenPress document entry const "${name}" must have an initializer in ${entryPath}`);
+    }
+    if (name === "config") {
+      assertPureExpression(declaration.initializer, entryPath, { allowMdxSourceCall: false });
+    } else if (name === "sources") {
+      assertPureSourcesInitializer(declaration.initializer, entryPath);
+    } else {
+      assertPureStaticInitializer(declaration.initializer, entryPath);
+    }
   }
 }
 
-function assertPureTopLevelInitializer(node, entryPath) {
-  visitNode(node, (child) => {
+function assertPureSourcesInitializer(node, entryPath) {
+  const expression = skipExpressionWrappers(node);
+  if (!ts.isObjectLiteralExpression(expression)) {
+    throw new Error(`OpenPress document entry exported sources must be an object literal in ${entryPath}`);
+  }
+  assertPureExpression(expression, entryPath, { allowMdxSourceCall: true });
+}
+
+function assertPureStaticInitializer(node, entryPath) {
+  const expression = skipExpressionWrappers(node);
+  if (ts.isFunctionExpression(expression) || ts.isArrowFunction(expression) || ts.isClassExpression(expression)) return;
+  assertPureExpression(expression, entryPath, { allowMdxSourceCall: false });
+}
+
+function assertPureDefaultExport(node, entryPath) {
+  const expression = skipExpressionWrappers(node);
+  if (ts.isFunctionExpression(expression) || ts.isArrowFunction(expression) || ts.isIdentifier(expression)) return;
+  throw new Error(`OpenPress document entry default export must be a function component in ${entryPath}`);
+}
+
+function assertPureExpression(node, entryPath, { allowMdxSourceCall }) {
+  visitExpression(node, (child) => {
     if (ts.isAwaitExpression(child)) {
-      throw new Error(`OpenPress React document entry has an unsupported top-level side effect: await in ${entryPath}`);
+      throw new Error(`OpenPress document entry has an unsupported top-level side effect: await in ${entryPath}`);
     }
-
     if (ts.isCallExpression(child)) {
       const callee = skipExpressionWrappers(child.expression);
+      if (allowMdxSourceCall && ts.isIdentifier(callee) && callee.text === "mdxSource") return;
       if (ts.isIdentifier(callee) && callee.text === "fetch") {
-        throw new Error(`OpenPress React document entry has an unsupported top-level side effect: fetch(...) in ${entryPath}`);
+        throw new Error(`OpenPress document entry has an unsupported top-level side effect: fetch(...) in ${entryPath}`);
       }
       if (ts.isPropertyAccessExpression(callee) && isIdentifierText(callee.expression, "console")) {
-        throw new Error(`OpenPress React document entry has an unsupported top-level side effect: console.${callee.name.text}(...) in ${entryPath}`);
+        throw new Error(`OpenPress document entry has an unsupported top-level side effect: console.${callee.name.text}(...) in ${entryPath}`);
       }
       if (ts.isPropertyAccessExpression(callee) && isIdentifierText(callee.expression, "fs")) {
-        throw new Error(`OpenPress React document entry has an unsupported top-level side effect: fs.${callee.name.text}(...) in ${entryPath}`);
+        throw new Error(`OpenPress document entry has an unsupported top-level side effect: fs.${callee.name.text}(...) in ${entryPath}`);
       }
-      throw new Error(`OpenPress React document entry cannot execute top-level function calls in exported config or shell JSX in ${entryPath}`);
+      throw new Error(`OpenPress document entry cannot execute top-level function calls outside sources.mdxSource(...) in ${entryPath}`);
     }
-
     if (ts.isPropertyAccessExpression(child) && isProcessEnvAccess(child)) {
-      throw new Error(`OpenPress React document entry cannot read process.env in exported config or shell JSX in ${entryPath}`);
+      throw new Error(`OpenPress document entry cannot read process.env at top level in ${entryPath}`);
     }
   });
 }
 
-function visitNode(node, visitor) {
+function visitExpression(node, visitor) {
   visitor(node);
-  ts.forEachChild(node, (child) => visitNode(child, visitor));
+  if (node !== undefined && node !== null && isFunctionLikeExpression(node)) return;
+  ts.forEachChild(node, (child) => visitExpression(child, visitor));
+}
+
+function isFunctionLikeExpression(node) {
+  return ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isClassExpression(node);
 }
 
 function skipExpressionWrappers(node) {
   let current = node;
-  while (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isTypeAssertionExpression(current)) {
+  while (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isTypeAssertionExpression(current) || ts.isNonNullExpression(current)) {
     current = current.expression;
   }
   return current;
@@ -196,6 +239,23 @@ function isFileSystemModule(moduleName) {
   return moduleName === "fs" || moduleName === "node:fs" || moduleName === "fs/promises" || moduleName === "node:fs/promises";
 }
 
+function normalizeReactDocumentConfig(workspaceRoot, entryPath, config) {
+  if (config != null && (typeof config !== "object" || Array.isArray(config))) {
+    throw new Error("OpenPress React document entry `config` export must be an object when provided.");
+  }
+  const rawConfig = config ?? {};
+  const paths = rawConfig.paths ?? {};
+  return normalizeConfig(workspaceRoot, {
+    ...rawConfig,
+    documentDir: rawConfig.documentDir ?? paths.documentDir ?? "document",
+    sourceDir: rawConfig.sourceDir ?? paths.chaptersDir ?? paths.sourceDir ?? "chapters",
+    componentsDir: rawConfig.componentsDir ?? paths.componentsDir ?? "components",
+    mediaDir: rawConfig.mediaDir ?? paths.mediaDir ?? "media",
+    themeDir: rawConfig.themeDir ?? paths.themeDir ?? "theme",
+    designDoc: rawConfig.designDoc ?? paths.designDoc ?? "design.md",
+  }, entryPath);
+}
+
 async function fileExists(filePath) {
   try {
     const stat = await fs.stat(filePath);