@open-press/core 0.3.0

package/engine/commands/deploy.mjs

@@ -0,0 +1,31 @@
+import path from "node:path";
+import { deploySync } from "../deploy-sync.mjs";
+import { buildReactPdf, runCommand, writePdfStageDeployConfig } from "./_shared.mjs";
+
+export async function run({ root, config, options, recurse }) {
+  if (config.deploy.requiresConfirmation === true && !options.confirm) {
+    console.error("OpenPress deploy requires --confirm before updating a public Cloudflare Pages site.");
+    return 2;
+  }
+  const source = config.deploy.source;
+  const projectName = config.deploy.projectName;
+  const commitDirty = config.deploy.commitDirty;
+  if (options.dryRun) {
+    console.log("OpenPress deploy dry run");
+    console.log("Command: node engine/cli.mjs render . --renderer react");
+    console.log(`Step:    deploy-sync (copy ${config.outputDir} → ${source})`);
+    console.log(`Command: node engine/cli.mjs pdf . --output ${source}/${config.pdf.filename}`);
+    console.log(`Step:    write ${source}/openpress/deploy.json with deployment metadata`);
+    console.log(`Command: npx wrangler pages deploy ${source}${projectName ? ` --project-name=${projectName}` : ""}${commitDirty ? " --commit-dirty=true" : ""}`);
+    return 0;
+  }
+  const renderCode = await recurse("render", [root, "--renderer", "react"]);
+  if (renderCode !== 0) return renderCode;
+  await deploySync(root, config.outputDir, source);
+  await buildReactPdf({ root, config, outPath: path.resolve(root, source, config.pdf.filename), noBuild: true, recurse });
+  await writePdfStageDeployConfig(root, source, config);
+  const wranglerArgs = ["wrangler", "pages", "deploy", source];
+  if (projectName) wranglerArgs.push(`--project-name=${projectName}`);
+  if (commitDirty) wranglerArgs.push("--commit-dirty=true");
+  return runCommand("npx", wranglerArgs, root);
+}

package/engine/commands/dev.mjs

@@ -0,0 +1,26 @@
+import { exportDocument } from "../document-export.mjs";
+import { runCommand } from "./_shared.mjs";
+
+export async function run({ root, options }) {
+  const renderer = options.renderer ?? "react";
+  if (renderer !== "react") {
+    console.error(`Unknown renderer: ${renderer}`);
+    return 2;
+  }
+  const host = options.host ?? "127.0.0.1";
+  const port = options.port ?? "5173";
+  const url = `http://${host}:${port}/?dev=1`;
+  if (options.dryRun) {
+    console.log(`OpenPress dev URL: ${url}`);
+    if (!options.noBuild) {
+      console.log("Command: node engine/cli.mjs export .");
+    }
+    console.log(`Command: npx vite --config vite.config.ts --host ${host} --port ${port}`);
+    return 0;
+  }
+  if (!options.noBuild) {
+    await exportDocument(root);
+  }
+  console.log(`OpenPress dev: ${url}`);
+  return runCommand("npx", ["vite", "--config", "vite.config.ts", "--host", host, "--port", port], root);
+}

package/engine/commands/export.mjs

@@ -0,0 +1,8 @@
+import path from "node:path";
+import { exportDocument } from "../document-export.mjs";
+
+export async function run({ root }) {
+  const result = await exportDocument(root);
+  console.log(`OpenPress export: ${path.relative(root, result.documentPath)} (${result.pageCount} pages)`);
+  return 0;
+}

package/engine/commands/init.mjs

@@ -0,0 +1,24 @@
+import { initWorkspace, listStylePackSkills } from "../init.mjs";
+import { formatDisplayPath, parseInitOptions } from "./_shared.mjs";
+
+export const needsWorkspace = false;
+
+export async function run({ argv }) {
+  const options = parseInitOptions(argv);
+  if (!options.target) {
+    console.error("openpress init: target path is required");
+    console.error("Usage: openpress init <target> [--skill <name>] [--force]");
+    const available = await listStylePackSkills();
+    if (available.length) console.error(`Style packs available: ${available.join(", ")}`);
+    return 1;
+  }
+  const result = await initWorkspace(options);
+  const displayPath = formatDisplayPath(result.targetPath);
+  console.log(`OpenPress init: created ${displayPath} from style pack "${result.skill}".`);
+  console.log("Next steps:");
+  console.log(`  cd ${displayPath}`);
+  console.log("  # 填入 openpress.config.mjs 的 title / subtitle / organization");
+  console.log("  # 改 document/index.tsx 與 document/chapters/**/*.mdx 為實際內容");
+  console.log("  node engine/cli.mjs validate");
+  return 0;
+}

package/engine/commands/inspect.mjs

@@ -0,0 +1,35 @@
+import { inspectWorkspace } from "../inspection.mjs";
+import { exitCodeForIssueReport } from "../issue-report.mjs";
+
+export async function run({ root, config, options, recurse }) {
+  const host = options.host ?? "127.0.0.1";
+  const port = options.port ?? "5186";
+  const url = `http://${host}:${port}/?print=1`;
+
+  if (options.dryRun) {
+    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(`Chrome inspection URL: ${url}`);
+    return 0;
+  }
+
+  const report = await inspectWorkspace({ root, config, options, recurse });
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return exitCodeForIssueReport(report);
+  }
+
+  if (report.ok) {
+    console.log(report.format());
+    console.log(`Checked: ${report.checked.join(", ")}`);
+    if (report.summary) {
+      console.log(`Summary: ${JSON.stringify(report.summary)}`);
+    }
+    return 0;
+  }
+
+  console.log(report.format());
+  return exitCodeForIssueReport(report);
+}

package/engine/commands/migrate-to-react.mjs

@@ -0,0 +1,27 @@
+import { migrateLegacyWorkspaceToReact } from "../react/migrate-to-react.mjs";
+import { validateWorkspace } from "../validation.mjs";
+
+export async function run({ root, config, options }) {
+  const result = await migrateLegacyWorkspaceToReact(root, config, {
+    dryRun: options.dryRun,
+    force: options.force,
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  const verb = options.dryRun ? "would create" : "created";
+  console.log(`OpenPress migrate-to-react ${verb} ${result.files.length} paths from ${result.sourceFiles} legacy files:`);
+  for (const file of result.files) {
+    console.log(`  ${file.action.padEnd(5)} ${file.path}`);
+  }
+
+  if (!options.dryRun) {
+    const report = await validateWorkspace(root);
+    console.log(report.ok ? `OpenPress validation OK\nChecked: ${report.checked.join(", ")}` : report.format());
+    return report.ok ? 0 : 1;
+  }
+  return 0;
+}

package/engine/commands/pdf.mjs

@@ -0,0 +1,26 @@
+import path from "node:path";
+import { buildReactPdf } from "./_shared.mjs";
+
+export async function run({ root, config, options, recurse }) {
+  const outputPath = options.output ? path.resolve(root, options.output) : undefined;
+  if (options.dryRun) {
+    const relOutput = path.relative(root, outputPath ?? config.paths.pdf);
+    const host = options.host ?? "127.0.0.1";
+    const port = options.port ?? "5185";
+    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: Chrome --print-to-pdf=${relOutput} http://${host}:${port}/?print=1`);
+    return 0;
+  }
+  const result = await buildReactPdf({
+    root,
+    config,
+    outPath: outputPath,
+    host: options.host,
+    port: options.port,
+    noBuild: options.noBuild,
+    recurse,
+  });
+  console.log(`OpenPress PDF: ${path.relative(root, result.pdfPath)}`);
+  return 0;
+}

package/engine/commands/preview.mjs

@@ -0,0 +1,26 @@
+import { runCommand } from "./_shared.mjs";
+
+export async function run({ root, config, options, recurse }) {
+  const renderer = options.renderer ?? "react";
+  if (renderer !== "react") {
+    console.error(`Unknown renderer: ${renderer}`);
+    return 2;
+  }
+  const host = options.host ?? "127.0.0.1";
+  const port = options.port ?? "5173";
+  const url = `http://${host}:${port}`;
+  if (options.dryRun) {
+    console.log(`OpenPress preview URL: ${url}`);
+    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 .`);
+    return 0;
+  }
+  if (!options.noBuild) {
+    const renderCode = await recurse("render", [root, "--renderer", renderer]);
+    if (renderCode !== 0) return renderCode;
+  }
+  console.log(`OpenPress preview: ${url}`);
+  return runCommand("node", ["engine/static-server.mjs", config.outputDir, "--host", host, "--port", port, "--workspace", "."], root);
+}

package/engine/commands/render.mjs

@@ -0,0 +1,17 @@
+import { exportDocument } from "../document-export.mjs";
+import { runCommand } from "./_shared.mjs";
+
+export async function run({ root, options }) {
+  const renderer = options.renderer ?? "react";
+  if (renderer !== "react") {
+    console.error(`Unknown renderer: ${renderer}`);
+    return 2;
+  }
+  if (options.dryRun) {
+    console.log("Command: node engine/cli.mjs export .");
+    console.log("Command: npx vite build --config vite.config.ts");
+    return 0;
+  }
+  await exportDocument(root);
+  return runCommand("npx", ["vite", "build", "--config", "vite.config.ts"], root);
+}

package/engine/commands/replace.mjs

@@ -0,0 +1,41 @@
+import { replaceSourceText } from "../source-text-tools.mjs";
+
+export async function run({ config, options }) {
+  const args = replaceArgsFromOptions(options);
+  if (!args) {
+    console.error("Usage: node engine/cli.mjs replace [path] <from> <to> [--json] [--apply] [--scope content|all] [--include-code] [--case-sensitive]");
+    return 2;
+  }
+
+  const report = await replaceSourceText({
+    config,
+    from: args.from,
+    to: args.to,
+    scope: options.scope ?? "content",
+    caseSensitive: options.caseSensitive === true,
+    includeCode: options.includeCode === true,
+    apply: options.apply === true,
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return 0;
+  }
+
+  console.log(`OpenPress replace ${report.applied ? "applied" : "preview"}: "${args.from}" -> "${args.to}" (${report.matchCount} matches in ${report.fileCount} files)`);
+  if (!report.applied) console.log("No files written. Re-run with --apply to update sources.");
+  for (const change of report.changes) {
+    console.log(`${change.path}: ${change.replacements.length} replacements`);
+  }
+  return 0;
+}
+
+function replaceArgsFromOptions(options) {
+  const positional = options.positional ?? [];
+  const args = positional.length >= 3 ? positional.slice(1) : positional;
+  if (args.length < 2) return null;
+  return {
+    from: args[0],
+    to: args[1],
+  };
+}

package/engine/commands/search.mjs

@@ -0,0 +1,33 @@
+import { searchSourceText } from "../source-text-tools.mjs";
+
+export async function run({ config, options }) {
+  const query = searchQueryFromOptions(options);
+  if (!query) {
+    console.error("Usage: node engine/cli.mjs search [path] <query> [--json] [--scope content|all] [--case-sensitive]");
+    return 2;
+  }
+
+  const report = await searchSourceText({
+    config,
+    query,
+    scope: options.scope ?? "content",
+    caseSensitive: options.caseSensitive === true,
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return 0;
+  }
+
+  console.log(`OpenPress search: "${query}" (${report.matchCount} matches)`);
+  for (const match of report.matches) {
+    console.log(`${match.id} ${match.path}:${match.line}:${match.column} ${match.preview}`);
+  }
+  return 0;
+}
+
+function searchQueryFromOptions(options) {
+  const positional = options.positional ?? [];
+  if (positional.length > 1) return positional.slice(1).join(" ");
+  return positional[0] ?? "";
+}

package/engine/commands/typecheck.mjs

@@ -0,0 +1,5 @@
+import { runCommand } from "./_shared.mjs";
+
+export async function run({ root }) {
+  return runCommand("npx", ["tsc", "--noEmit", "-p", "tsconfig.json"], root);
+}

package/engine/commands/validate.mjs

@@ -0,0 +1,17 @@
+import { validateWorkspace } from "../validation.mjs";
+import { exitCodeForIssueReport } from "../issue-report.mjs";
+
+export async function run({ root, options }) {
+  const report = await validateWorkspace(root);
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return exitCodeForIssueReport(report);
+  }
+  if (report.ok) {
+    console.log("OpenPress validation OK");
+    console.log(`Checked: ${report.checked.join(", ")}`);
+    return 0;
+  }
+  console.log(report.format());
+  return 1;
+}

package/engine/config.d.mts

@@ -0,0 +1,40 @@
+export interface ResolvedConfig {
+  root: string;
+  configPath: string;
+  title: string;
+  documentDir: string;
+  sourceDir: string;
+  mediaDir: string;
+  themeDir: string;
+  designDoc: string;
+  componentsDir: string;
+  publicDir: string;
+  outputDir: string;
+  pdf: {
+    filename: string;
+  };
+  deploy: {
+    adapter: string;
+    source: string;
+    projectName: string | null;
+    commitDirty: boolean;
+    requiresConfirmation: boolean;
+  };
+  paths: {
+    documentRoot: string;
+    sourceDir: string;
+    mediaDir: string;
+    themeDir: string;
+    designDoc: string;
+    componentsDir: string;
+    publicDir: string;
+    outputDir: string;
+    pdf: string;
+    deploySource: string;
+    deployMetadata: string;
+  };
+}
+
+export function loadConfig(root?: string): Promise<ResolvedConfig>;
+export function normalizeConfig(root: string, userConfig?: Record<string, unknown>, configPath?: string): ResolvedConfig;
+export function publicPdfHref(config: ResolvedConfig): string;

package/engine/config.mjs

@@ -0,0 +1,160 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const DEFAULT_CONFIG = {
+  title: "OpenPress Document",
+  subtitle: "",
+  organization: "",
+  workspaceLabel: "",
+  documentDir: ".",
+  sourceDir: "content",
+  mediaDir: "media",
+  themeDir: "theme",
+  designDoc: "design.md",
+  componentsDir: "components",
+  publicDir: "public/openpress",
+  outputDir: "dist",
+  pdf: {
+    filename: "document.pdf",
+  },
+  deploy: {
+    adapter: "cloudflare-pages",
+    source: ".deploy/openpress",
+    projectName: null,
+    commitDirty: false,
+    requiresConfirmation: true,
+  },
+};
+
+export async function loadConfig(root = ".") {
+  const workspaceRoot = path.resolve(root);
+  const configPath = path.join(workspaceRoot, "openpress.config.mjs");
+  const rootConfig = await readUserConfig(configPath);
+  const { config, sourceConfigPath } = await resolveUserConfig(workspaceRoot, rootConfig, configPath);
+  return normalizeConfig(workspaceRoot, config, sourceConfigPath);
+}
+
+export function normalizeConfig(root, userConfig = {}, configPath = path.join(root, "openpress.config.mjs")) {
+  const config = {
+    root: path.resolve(root),
+    configPath,
+    title: stringValue(userConfig.title, DEFAULT_CONFIG.title),
+    subtitle: optionalStringValue(userConfig.subtitle, DEFAULT_CONFIG.subtitle) ?? "",
+    organization: optionalStringValue(userConfig.organization, DEFAULT_CONFIG.organization) ?? "",
+    workspaceLabel: optionalStringValue(userConfig.workspaceLabel, DEFAULT_CONFIG.workspaceLabel) ?? "",
+    documentDir: documentPathValue(userConfig.documentDir, DEFAULT_CONFIG.documentDir),
+    sourceDir: relativePathValue(userConfig.sourceDir, DEFAULT_CONFIG.sourceDir),
+    mediaDir: relativePathValue(userConfig.mediaDir, DEFAULT_CONFIG.mediaDir),
+    themeDir: relativePathValue(userConfig.themeDir, DEFAULT_CONFIG.themeDir),
+    designDoc: relativePathValue(userConfig.designDoc, DEFAULT_CONFIG.designDoc),
+    componentsDir: relativePathValue(userConfig.componentsDir, DEFAULT_CONFIG.componentsDir),
+    publicDir: relativePathValue(userConfig.publicDir, DEFAULT_CONFIG.publicDir),
+    outputDir: relativePathValue(userConfig.outputDir, DEFAULT_CONFIG.outputDir),
+    pdf: {
+      filename: fileNameValue(userConfig.pdf?.filename, DEFAULT_CONFIG.pdf.filename),
+    },
+    deploy: {
+      adapter: stringValue(userConfig.deploy?.adapter, DEFAULT_CONFIG.deploy.adapter),
+      source: relativePathValue(userConfig.deploy?.source, DEFAULT_CONFIG.deploy.source),
+      projectName: optionalStringValue(userConfig.deploy?.projectName, DEFAULT_CONFIG.deploy.projectName),
+      commitDirty: booleanValue(userConfig.deploy?.commitDirty, DEFAULT_CONFIG.deploy.commitDirty),
+      requiresConfirmation: booleanValue(userConfig.deploy?.requiresConfirmation, DEFAULT_CONFIG.deploy.requiresConfirmation),
+    },
+  };
+
+  const documentRoot = config.documentDir === "." ? config.root : path.join(config.root, config.documentDir);
+  config.paths = {
+    documentRoot,
+    sourceDir: path.join(documentRoot, config.sourceDir),
+    mediaDir: path.join(documentRoot, config.mediaDir),
+    themeDir: path.join(documentRoot, config.themeDir),
+    designDoc: path.join(documentRoot, config.designDoc),
+    componentsDir: path.join(documentRoot, config.componentsDir),
+    publicDir: path.join(config.root, config.publicDir),
+    outputDir: path.join(config.root, config.outputDir),
+    pdf: path.join(config.root, config.outputDir, config.pdf.filename),
+    deploySource: path.join(config.root, config.deploy.source),
+    deployMetadata: path.join(config.root, config.deploy.source, "openpress", "deploy.json"),
+  };
+
+  return config;
+}
+
+export function publicPdfHref(config) {
+  return `/${config.pdf.filename}`;
+}
+
+async function readUserConfig(configPath) {
+  try {
+    const stat = await fs.stat(configPath);
+    const configUrl = `${pathToFileURL(configPath).href}?mtime=${stat.mtimeMs}`;
+    const mod = await import(configUrl);
+    return mod.default ?? {};
+  } catch (error) {
+    if (error?.code === "ENOENT") return {};
+    throw error;
+  }
+}
+
+async function resolveUserConfig(root, rootConfig, configPath) {
+  const documentConfigPath = configPathValue(rootConfig.config ?? rootConfig.documentConfig);
+  if (!documentConfigPath) {
+    return { config: rootConfig, sourceConfigPath: configPath };
+  }
+
+  const sourceConfigPath = path.resolve(root, documentConfigPath);
+  const documentConfig = await readUserConfig(sourceConfigPath);
+  return {
+    config: { ...documentConfig, ...rootConfig },
+    sourceConfigPath,
+  };
+}
+
+function stringValue(value, fallback) {
+  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+
+function optionalStringValue(value, fallback) {
+  if (value === null) return null;
+  if (typeof value === "string" && value.trim()) return value.trim();
+  return fallback;
+}
+
+function booleanValue(value, fallback) {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function fileNameValue(value, fallback) {
+  const fileName = stringValue(value, fallback);
+  if (fileName.includes("/") || fileName.includes("\\") || fileName === "." || fileName === "..") {
+    throw new Error(`OpenPress config pdf.filename must be a file name, got: ${fileName}`);
+  }
+  return fileName;
+}
+
+function configPathValue(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  return relativePathValue(value, null);
+}
+
+function documentPathValue(value, fallback) {
+  const raw = stringValue(value, fallback).replaceAll("\\", "/");
+  if (path.isAbsolute(raw)) throw new Error(`OpenPress config paths must be relative, got: ${raw}`);
+  const normalized = path.posix.normalize(raw).replace(/^\.\//, "");
+  if (normalized === ".") return ".";
+  if (!normalized || normalized === ".." || normalized.startsWith("../")) {
+    throw new Error(`OpenPress config path escapes workspace: ${raw}`);
+  }
+  return normalized;
+}
+
+function relativePathValue(value, fallback) {
+  const raw = stringValue(value, fallback).replaceAll("\\", "/");
+  if (path.isAbsolute(raw)) throw new Error(`OpenPress config paths must be relative, got: ${raw}`);
+  const normalized = path.posix.normalize(raw).replace(/^\.\//, "");
+  if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+    throw new Error(`OpenPress config path escapes workspace: ${raw}`);
+  }
+  return normalized;
+}

package/engine/deploy-sync.mjs

@@ -0,0 +1,15 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { loadConfig } from "./config.mjs";
+import { copyDirectory } from "./file-utils.mjs";
+
+export async function deploySync(root, sourceDir, deployDir) {
+  const config = await loadConfig(root);
+  sourceDir ??= config.outputDir;
+  deployDir ??= config.deploy.source;
+  const dist = path.join(root, sourceDir);
+  const deploy = path.join(root, deployDir);
+  await fs.rm(deploy, { recursive: true, force: true });
+  await fs.mkdir(deploy, { recursive: true });
+  await copyDirectory(dist, deploy);
+}

package/engine/document-export.mjs

@@ -0,0 +1,15 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { exportReactDocument } from "./react/document-export.mjs";
+
+const SELF_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(SELF_DIR, "..");
+
+export async function exportDocument(root = ROOT) {
+  const reactResult = await exportReactDocument(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.",
+  );
+}

package/engine/file-utils.mjs

@@ -0,0 +1,106 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { loadConfig } from "./config.mjs";
+import { readKatexCss } from "./katex-assets.mjs";
+
+const CONTENT_CSS_LAYERS = [
+  "base/page-contract.css",
+  "base/typography.css",
+  "page-surfaces/cover.css",
+  { path: "page-surfaces/chapter-opener.css", optional: true },
+  "page-surfaces/back-cover.css",
+  "page-surfaces/toc.css",
+  "shell/reader-controls.css",
+  "base/print.css",
+];
+
+export async function copyDirectory(src, dst) {
+  await fs.rm(dst, { recursive: true, force: true });
+  await fs.mkdir(path.dirname(dst), { recursive: true });
+  await fs.cp(src, dst, { recursive: true });
+}
+
+export async function writeContentCss(root, targetDir, config) {
+  config ??= await loadConfig(root);
+  const css = await buildContentCss(root, config);
+  await fs.mkdir(targetDir, { recursive: true });
+  await fs.writeFile(path.join(targetDir, "content.css"), css, "utf8");
+}
+
+export async function buildContentCss(root, config) {
+  config ??= await loadConfig(root);
+  const contentAssetsDir = config.paths.themeDir;
+  const parts = [];
+  for (const layer of CONTENT_CSS_LAYERS) {
+    const relativePath = typeof layer === "string" ? layer : layer.path;
+    const cssPath = path.join(contentAssetsDir, relativePath);
+    let css;
+    try {
+      css = await fs.readFile(cssPath, "utf8");
+    } catch (error) {
+      if (typeof layer !== "string" && layer.optional && error.code === "ENOENT") continue;
+      throw error;
+    }
+    parts.push(`/* === ${relativePath} === */\n`);
+    parts.push(css.trimEnd());
+    parts.push("\n\n");
+  }
+  parts.push("/* === engine/katex.css === */\n");
+  parts.push((await readKatexCss()).trimEnd());
+  parts.push("\n\n");
+  return parts.join("");
+}
+
+export async function writeComponentsCss(root, targetDir, config) {
+  config ??= await loadConfig(root);
+  const css = await buildComponentsCss(root, config);
+  await fs.mkdir(targetDir, { recursive: true });
+  await fs.writeFile(path.join(targetDir, "components.css"), css, "utf8");
+}
+
+export async function buildComponentsCss(root, config) {
+  config ??= await loadConfig(root);
+  const parts = [];
+  await appendCssDirectory(parts, path.join(config.paths.themeDir, "patterns"), "theme/patterns");
+  await appendComponentScopedCss(parts, config.paths.componentsDir);
+  return parts.join("");
+}
+
+async function appendCssDirectory(parts, directory, labelPrefix) {
+  let entries;
+  try {
+    entries = await fs.readdir(directory);
+  } catch {
+    return;
+  }
+  for (const name of entries.filter((entry) => entry.endsWith(".css")).sort()) {
+    parts.push(`/* === ${labelPrefix}/${name} === */\n`);
+    parts.push((await fs.readFile(path.join(directory, name), "utf8")).trimEnd());
+    parts.push("\n\n");
+  }
+}
+
+async function appendComponentScopedCss(parts, componentsDir) {
+  let entries;
+  try {
+    entries = await fs.readdir(componentsDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries.filter((item) => item.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
+    const cssPath = path.join(componentsDir, entry.name, "style.css");
+    let css;
+    try {
+      css = await fs.readFile(cssPath, "utf8");
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        continue;
+      }
+      throw error;
+    }
+    parts.push(`/* === components/${entry.name}/style.css === */\n`);
+    parts.push(css.trimEnd());
+    parts.push("\n\n");
+  }
+}