@open-press/core 0.3.0

package/engine/fonts.mjs

@@ -0,0 +1,62 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { copyDirectory } from "./file-utils.mjs";
+
+export async function copyThemeFonts(root, publicOutputDir, config) {
+  const themeDir = config?.paths?.themeDir ?? path.join(path.resolve(root), "theme");
+  const target = path.join(publicOutputDir, "fonts.css");
+  const themeFonts = path.join(themeDir, "fonts.css");
+  if (await isFile(themeFonts)) {
+    await fs.copyFile(themeFonts, target);
+  } else {
+    await fs.writeFile(target, defaultFontsCss(), "utf8");
+  }
+
+  const themeFontFiles = path.join(themeDir, "fonts");
+  if (await isDirectory(themeFontFiles)) {
+    await copyDirectory(themeFontFiles, path.join(publicOutputDir, "fonts"));
+  } else {
+    await fs.rm(path.join(publicOutputDir, "fonts"), { recursive: true, force: true });
+  }
+}
+
+async function isFile(filePath) {
+  try {
+    return (await fs.stat(filePath)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function isDirectory(filePath) {
+  try {
+    return (await fs.stat(filePath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function defaultFontsCss() {
+  return `@font-face {
+  font-family: "OpenPress Body";
+  src: local("PingFang TC"), local("Noto Sans TC"), local("Hiragino Sans"), local("Microsoft JhengHei");
+  font-weight: 300 700;
+  font-style: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: "OpenPress Serif";
+  src: local("Noto Serif TC"), local("Songti TC"), local("Source Han Serif TC"), local("PMingLiU");
+  font-weight: 300 700;
+  font-style: normal;
+  font-display: swap;
+}
+
+:root {
+  --openpress-font-body: "OpenPress Body", "PingFang TC", "Noto Sans TC", "Hiragino Sans", "Microsoft JhengHei", sans-serif;
+  --openpress-font-serif: "OpenPress Serif", "Noto Serif TC", "Songti TC", "Source Han Serif TC", "PMingLiU", serif;
+  --openpress-font-mono: "SFMono-Regular", "Menlo", "Consolas", monospace;
+}
+`;
+}

package/engine/init.mjs

@@ -0,0 +1,90 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SELF_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ENGINE_ROOT = path.resolve(SELF_DIR, "..");
+const SKILLS_DIR = path.join(ENGINE_ROOT, "skills");
+
+const DEFAULT_SKILL = "editorial-monograph";
+
+export async function initWorkspace({ target, skill = DEFAULT_SKILL, force = false }) {
+  if (!target) throw new Error("openpress init: target path is required");
+  const targetPath = path.resolve(target);
+
+  const starterPath = path.join(SKILLS_DIR, skill, "starter");
+  try {
+    const stat = await fs.stat(starterPath);
+    if (!stat.isDirectory()) {
+      throw new Error(`openpress init: skill "${skill}" has no starter/ directory at ${starterPath}`);
+    }
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      const available = await listStylePackSkills();
+      throw new Error(
+        `openpress init: skill "${skill}" not found or has no starter. ` +
+        `Available style packs: ${available.join(", ") || "(none)"}`,
+      );
+    }
+    throw error;
+  }
+
+  if (!force) {
+    try {
+      const stat = await fs.stat(targetPath);
+      if (stat.isDirectory()) {
+        const entries = await fs.readdir(targetPath);
+        if (entries.length > 0) {
+          throw new Error(`openpress init: target ${targetPath} exists and is not empty. Pass --force to overwrite.`);
+        }
+      } else {
+        throw new Error(`openpress init: target ${targetPath} exists and is not a directory.`);
+      }
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+  }
+
+  await fs.mkdir(targetPath, { recursive: true });
+  await copyDirectory(starterPath, targetPath);
+
+  return { targetPath, skill };
+}
+
+export async function listStylePackSkills() {
+  try {
+    const entries = await fs.readdir(SKILLS_DIR, { withFileTypes: true });
+    const names = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const starter = path.join(SKILLS_DIR, entry.name, "starter");
+      try {
+        const stat = await fs.stat(starter);
+        if (stat.isDirectory()) names.push(entry.name);
+      } catch {
+        // skill without starter/ is not a style pack — skip
+      }
+    }
+    return names.sort();
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+async function copyDirectory(source, destination) {
+  await fs.mkdir(destination, { recursive: true });
+  for (const entry of await fs.readdir(source, { withFileTypes: true })) {
+    if (entry.name === ".DS_Store") continue;
+    const sourcePath = path.join(source, entry.name);
+    const destPath = path.join(destination, entry.name);
+    if (entry.isDirectory()) {
+      await copyDirectory(sourcePath, destPath);
+    } else if (entry.isFile()) {
+      await fs.copyFile(sourcePath, destPath);
+    } else if (entry.isSymbolicLink()) {
+      const link = await fs.readlink(sourcePath);
+      await fs.symlink(link, destPath);
+    }
+  }
+}

package/engine/inspection.mjs

@@ -0,0 +1,348 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { evaluateUrlWithChrome, stopChildProcess } from "./chrome-pdf.mjs";
+import { buildReactStatic, startStaticServer } from "./commands/_shared.mjs";
+import { createIssue, createIssueReport } from "./issue-report.mjs";
+import { collectActiveContentFiles, resolveActiveSourceWorkspace } from "./source-workspace.mjs";
+
+const MEDIA_EXTENSIONS = new Set([".avif", ".gif", ".jpeg", ".jpg", ".png", ".svg", ".webp"]);
+const SOURCE_EXTENSIONS = new Set([".css", ".html", ".js", ".json", ".md", ".mjs", ".ts", ".tsx"]);
+
+export async function inspectWorkspace({ root, config, options = {}, recurse = null }) {
+  const checked = [];
+  const issues = [];
+
+  const sourceScan = await collectInspectionSources(config);
+  checked.push(sourceScan.checkedName);
+  sourceScan.contentFiles.forEach((file) => {
+    if (!file.text.trim()) {
+      issues.push(createIssue({
+        level: "warning",
+        code: "react-source.empty-file",
+        message: `${sourceScan.contentLabel} \`${file.relativePath}\` is empty.`,
+        path: file.absolutePath,
+      }));
+    }
+  });
+
+  checked.push("media");
+  const mediaFiles = await readMediaFiles(sourceScan.config.paths.mediaDir);
+  const sourceText = sourceScan.sourceFiles.map((file) => file.text).join("\n");
+  const unusedMedia = mediaFiles.filter((file) => !sourceText.includes(file.name) && !sourceText.includes(file.relativePath));
+  unusedMedia.forEach((file) => {
+    issues.push(createIssue({
+      level: "warning",
+      code: "media.unused",
+      message: `Media asset \`${file.relativePath}\` is not referenced by document sources.`,
+      path: file.absolutePath,
+      detail: {
+        file: file.name,
+        relativePath: file.relativePath,
+      },
+    }));
+  });
+
+  checked.push("components");
+  const componentUsage = sourceScan.componentUsage;
+
+  const summary = {
+    ...sourceScan.summary,
+    mediaFiles: mediaFiles.length,
+    unusedMedia: unusedMedia.length,
+    componentUsage,
+  };
+
+  checked.push("overflow");
+  const renderCode = await buildReactStatic({
+    root,
+    noBuild: options.noBuild,
+    recurse,
+    silent: options.json,
+  });
+  if (renderCode !== 0) {
+    issues.push(createIssue({
+      level: "error",
+      code: "inspect.render",
+      message: `React render failed before overflow inspection (exit code ${renderCode}).`,
+      path: config.configPath,
+    }));
+    return createIssueReport({
+      kind: "inspection",
+      checked,
+      issues,
+      summary,
+      okMessage: "OpenPress inspection OK",
+    });
+  }
+
+  const overflowMeasurements = await inspectRenderedOverflow({
+    root,
+    config,
+    host: options.host ?? "127.0.0.1",
+    port: options.port ?? "5186",
+  });
+  issues.push(...overflowIssuesFromMeasurements(overflowMeasurements));
+  summary.pages = overflowMeasurements.length;
+  summary.overflowPages = overflowMeasurements.filter((page) => (page.overflows ?? []).length > 0).length;
+
+  return createIssueReport({
+    kind: "inspection",
+    checked,
+    issues,
+    summary,
+    okMessage: "OpenPress inspection OK",
+  });
+}
+
+export async function collectInspectionSources(config) {
+  const sourceWorkspace = await resolveActiveSourceWorkspace(config);
+  const sourceConfig = sourceWorkspace.config;
+  const contentFiles = await collectActiveContentFiles(sourceWorkspace);
+  const sourceFiles = [
+    ...contentFiles,
+    ...await readSourceFiles(sourceConfig.paths.componentsDir),
+    ...await readSingleFile(sourceConfig.paths.designDoc),
+  ];
+  const componentUsage = summarizeComponentUsage(contentFiles);
+
+  return {
+    sourceKind: sourceWorkspace.kind,
+    checkedName: sourceWorkspace.checkedName,
+    contentLabel: sourceWorkspace.contentLabel,
+    config: sourceConfig,
+    contentFiles,
+    sourceFiles,
+    componentUsage,
+    summary: {
+      sourceKind: sourceWorkspace.kind,
+      sourceFiles: contentFiles.length,
+      mdxFiles: contentFiles.length,
+    },
+  };
+}
+
+export async function inspectRenderedOverflow({ root, config, host = "127.0.0.1", port = "5186" }) {
+  const server = await startStaticServer(root, config, host, port);
+  try {
+    return await evaluateUrlWithChrome({
+      root,
+      url: `http://${host}:${port}/?print=1`,
+      debuggingPortBase: 9900,
+      debuggingPortRange: 600,
+      profilePrefix: "chrome-inspect",
+      emulatedMedia: "print",
+      evaluate: waitForInspectionReady,
+    });
+  } finally {
+    await stopChildProcess(server);
+  }
+}
+
+export async function waitForInspectionReady(client) {
+  const deadline = Date.now() + 30000;
+  while (Date.now() < deadline) {
+    const result = await client.send("Runtime.evaluate", {
+      returnByValue: true,
+      awaitPromise: true,
+      expression: inspectionExpression(),
+    });
+    const value = result.result?.value;
+    if (Array.isArray(value)) return value;
+    await delay(100);
+  }
+  throw new Error("Timed out waiting for OpenPress pagination before inspection.");
+}
+
+export function overflowIssuesFromMeasurements(measurements) {
+  return measurements.flatMap((page) => {
+    const pageLabel = String(page.pageNumber).padStart(2, "0");
+    return (page.overflows ?? []).map((overflow) => createIssue({
+      level: "warning",
+      code: `overflow.${overflow.code}`,
+      message: `Page ${pageLabel} exceeds ${humanOverflowTarget(overflow.code)} by ${Math.ceil(overflow.overflowPx)}px.`,
+      path: page.source?.path,
+      detail: {
+        pageNumber: page.pageNumber,
+        title: page.title,
+        sourceFile: page.source?.file,
+        selector: overflow.selector,
+        tagName: overflow.tagName,
+        text: overflow.text,
+        overflowPx: Math.ceil(overflow.overflowPx),
+      },
+    }));
+  });
+}
+
+async function readSourceFiles(directory, extension = null) {
+  const files = [];
+  await walkFiles(directory, async (absolutePath) => {
+    if (extension && path.extname(absolutePath) !== extension) return;
+    if (!SOURCE_EXTENSIONS.has(path.extname(absolutePath))) return;
+    files.push({
+      absolutePath,
+      relativePath: path.relative(directory, absolutePath).replaceAll("\\", "/"),
+      text: await fs.readFile(absolutePath, "utf8"),
+    });
+  });
+  files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  return files;
+}
+
+async function readSingleFile(absolutePath) {
+  try {
+    const text = await fs.readFile(absolutePath, "utf8");
+    return [{
+      absolutePath,
+      relativePath: path.basename(absolutePath),
+      text,
+    }];
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+async function readMediaFiles(directory) {
+  const files = [];
+  await walkFiles(directory, async (absolutePath) => {
+    if (!MEDIA_EXTENSIONS.has(path.extname(absolutePath).toLowerCase())) return;
+    files.push({
+      absolutePath,
+      name: path.basename(absolutePath),
+      relativePath: path.relative(directory, absolutePath).replaceAll("\\", "/"),
+    });
+  });
+  files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  return files;
+}
+
+async function walkFiles(directory, visit) {
+  let entries;
+  try {
+    entries = await fs.readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return;
+    throw error;
+  }
+
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    const absolutePath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      await walkFiles(absolutePath, visit);
+    } else if (entry.isFile()) {
+      await visit(absolutePath);
+    }
+  }
+}
+
+function summarizeComponentUsage(contentFiles) {
+  const usages = new Map();
+  for (const file of contentFiles) {
+    for (const match of file.text.matchAll(/<([A-Z][A-Za-z0-9]*)\b/g)) {
+      const name = match[1];
+      const current = usages.get(name) ?? { name, count: 0, files: [] };
+      current.count += 1;
+      if (!current.files.includes(file.relativePath)) current.files.push(file.relativePath);
+      usages.set(name, current);
+    }
+  }
+  return Array.from(usages.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function humanOverflowTarget(code) {
+  if (code === "page-body") return "page body";
+  if (code === "page-frame") return "page frame";
+  return code.replaceAll("-", " ");
+}
+
+function inspectionExpression() {
+  return `Promise.resolve().then(async () => {
+    const root = document.querySelector('[data-openpress-print-document="true"]');
+    const ready = root?.getAttribute('data-openpress-pagination') === 'ready';
+    if (!ready) return null;
+
+    await document.fonts?.ready;
+    await Promise.all(Array.from(document.images).map(async (img) => {
+      if (!img.complete) {
+        await new Promise((resolve) => {
+          const settle = () => {
+            img.removeEventListener('load', settle);
+            img.removeEventListener('error', settle);
+            resolve();
+          };
+          img.addEventListener('load', settle, { once: true });
+          img.addEventListener('error', settle, { once: true });
+        });
+      }
+      await img.decode?.().catch(() => undefined);
+    }));
+    await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+
+    const textFor = (element) => (element?.textContent || '').replace(/\\s+/g, ' ').trim().slice(0, 120);
+    const overflowAmount = (outer, inner) => {
+      if (!outer || !inner) return 0;
+      const outerRect = outer.getBoundingClientRect();
+      const innerRect = inner.getBoundingClientRect();
+      return Math.max(0, innerRect.bottom - outerRect.bottom, innerRect.right - outerRect.right);
+    };
+    const contentBottomOverflow = (body) => {
+      if (!body) return 0;
+      const bodyRect = body.getBoundingClientRect();
+      const contentBottom = Array.from(body.children).reduce((bottom, child) => {
+        if (getComputedStyle(child).display === 'none') return bottom;
+        const marginBottom = Number.parseFloat(getComputedStyle(child).marginBottom) || 0;
+        return Math.max(bottom, child.getBoundingClientRect().bottom + marginBottom);
+      }, bodyRect.top);
+      return Math.max(0, contentBottom - bodyRect.bottom);
+    };
+    const addElementOverflow = (overflows, code, selector, container, element) => {
+      const px = overflowAmount(container, element);
+      if (px <= 1) return;
+      overflows.push({
+        code,
+        selector,
+        overflowPx: Math.ceil(px),
+        tagName: element.tagName,
+        text: textFor(element),
+      });
+    };
+
+    const wrappers = Array.from(document.querySelectorAll('.openpress-public-page > .openpress-html-page'));
+    if (wrappers.length === 0) return null;
+    return wrappers.map((wrapper, index) => {
+      const page = wrapper.querySelector('.reader-page') || wrapper;
+      const frame = page.querySelector('.page-frame') || page;
+      const body = page.querySelector('.page-body') || frame;
+      const sourcePath = wrapper.getAttribute('data-source-path') || undefined;
+      const sourceFile = wrapper.getAttribute('data-source-file') || sourcePath?.split('/').pop();
+      const overflows = [];
+      const bodyOverflow = contentBottomOverflow(body);
+      if (bodyOverflow > 1) {
+        overflows.push({
+          code: 'page-body',
+          selector: '.page-body',
+          overflowPx: Math.ceil(bodyOverflow),
+          tagName: body.tagName,
+          text: textFor(body),
+        });
+      }
+      addElementOverflow(overflows, 'page-frame', '.page-frame', page, frame);
+      body.querySelectorAll('table, img, pre, figure, [data-openpress-component]').forEach((element) => {
+        const tag = element.tagName.toLowerCase();
+        addElementOverflow(overflows, tag, tag, body, element);
+      });
+      return {
+        pageNumber: index + 1,
+        title: page.getAttribute('data-page-title') || wrapper.getAttribute('aria-label') || '',
+        source: sourcePath ? { file: sourceFile, path: sourcePath } : undefined,
+        overflows,
+      };
+    });
+  })`;
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/engine/issue-report.mjs

@@ -0,0 +1,44 @@
+export function createIssue({ level = "warning", code, message, path = null, detail = undefined }) {
+  return {
+    level,
+    code,
+    message,
+    ...(path ? { path } : {}),
+    ...(detail !== undefined ? { detail } : {}),
+  };
+}
+
+export function createIssueReport({ kind, checked = [], issues = [], summary = undefined, okMessage = undefined }) {
+  const report = {
+    kind,
+    ok: issues.every((issue) => issue.level !== "error"),
+    checked,
+    issues,
+    ...(summary !== undefined ? { summary } : {}),
+  };
+  return {
+    ...report,
+    format() {
+      return formatIssueReport(report, { okMessage });
+    },
+  };
+}
+
+export function exitCodeForIssueReport(report) {
+  return report.ok ? 0 : 1;
+}
+
+export function formatIssueReport(report, { okMessage } = {}) {
+  if (report.issues.length === 0) return okMessage ?? `${capitalize(report.kind)} OK`;
+  return report.issues.map(formatIssue).join("\n");
+}
+
+function formatIssue(issue) {
+  const suffix = issue.path ? ` (${issue.path})` : "";
+  return `[${issue.level}] ${issue.code}: ${issue.message}${suffix}`;
+}
+
+function capitalize(value) {
+  const text = String(value ?? "");
+  return text ? `${text.charAt(0).toUpperCase()}${text.slice(1)}` : "Report";
+}

package/engine/katex-assets.mjs

@@ -0,0 +1,45 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+const KATEX_OVERRIDES = `
+
+/* OpenPress math sizing keeps inline equations aligned with document typography. */
+.reader-page--content .katex {
+  font-size: 1em;
+}
+
+.reader-page--content .katex-display {
+  display: block;
+  width: fit-content;
+  max-width: 100%;
+  margin: var(--openpress-space-2) auto var(--openpress-space-3);
+  border-block: 1px solid color-mix(in srgb, var(--openpress-color-line) 76%, transparent);
+  padding: 0.55em 1.15em;
+  background: color-mix(in srgb, var(--openpress-color-panel) 78%, var(--openpress-color-document));
+  color: var(--openpress-color-ink);
+  overflow-x: auto;
+  overflow-y: hidden;
+  text-align: center;
+}
+
+.reader-page--content .katex-display > .katex {
+  font-size: 1.05em;
+}
+`;
+
+export async function readKatexCss() {
+  const cssPath = require.resolve("katex/dist/katex.min.css");
+  const css = await fs.readFile(cssPath, "utf8");
+  return `${css.replace(/url\(fonts\/([^)]+)\)/g, 'url("/openpress/katex-fonts/$1")')}${KATEX_OVERRIDES}`;
+}
+
+export async function copyKatexFonts(publicOutputDir) {
+  const sampleFont = require.resolve("katex/dist/fonts/KaTeX_Main-Regular.woff2");
+  const sourceDir = path.dirname(sampleFont);
+  const targetDir = path.join(publicOutputDir, "katex-fonts");
+  await fs.rm(targetDir, { recursive: true, force: true });
+  await fs.cp(sourceDir, targetDir, { recursive: true });
+}

package/engine/page-block.mjs

@@ -0,0 +1,30 @@
+import path from "node:path";
+
+export function documentRelativePath(config, ...parts) {
+  return path.posix.join(
+    ...(config.documentDir === "." ? [] : [config.documentDir]),
+    ...parts,
+  );
+}
+
+function rewriteAssetPaths(pageHtml, config) {
+  const mediaDir = config.mediaDir.replace(/^\/+|\/+$/g, "");
+  return pageHtml
+    .replaceAll(`src="${mediaDir}/`, 'src="/openpress/media/')
+    .replaceAll(`src='${mediaDir}/`, "src='/openpress/media/");
+}
+
+export function pageToBlock(index, pageHtml, source, config, { idPrefix = "openpress-page", anchorPrefix = "page", titleFallback = "Page" } = {}) {
+  const paddedIndex = String(index + 1).padStart(2, "0");
+  const title = pageHtml.match(/data-page-title="([^"]*)"/)?.[1] ?? `${titleFallback} ${index + 1}`;
+  const anchor = pageHtml.match(/\bid="([^"]+)"/)?.[1] ?? `${anchorPrefix}-${paddedIndex}`;
+  return {
+    id: `${idPrefix}-${paddedIndex}`,
+    kind: "htmlPage",
+    title,
+    pageNumber: index + 1,
+    source,
+    html: rewriteAssetPaths(pageHtml, config),
+    anchors: [anchor],
+  };
+}