@open-press/core 0.6.0 → 0.7.1

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/upgrade.mjs

@@ -1,9 +1,15 @@
 import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { diagnose } from "./doctor.mjs";
 import { runCommand } from "./_shared.mjs";
 
+// Migration notes live in the framework repo, not in scaffolded workspaces.
+// `npx open-press upgrade` fetches the notes for each pending version and
+// caches them under `.openpress/migrations/` so agents can read locally.
+const MIGRATION_REMOTE_BASE = "https://raw.githubusercontent.com/quan0715/open-press/main/docs/migrations";
+const MIGRATION_CACHE_DIR = path.join(".openpress", "migrations");
+
 export async function run({ root, options }) {
   const dryRun = Boolean(options?.dryRun);
   const skipSkills = Boolean(options?.noSkills);
@@ -85,7 +91,11 @@ export async function run({ root, options }) {
     process.stdout.write("  (no migration docs in this version range)\n\n");
   } else {
     for (const m of migrationContents) {
-      process.stdout.write(`  ─ ${m.path}\n`);
+      if (m.path) {
+        process.stdout.write(`  ─ ${m.path}${m.fetched ? "  (fetched from github)" : ""}\n`);
+      } else {
+        process.stdout.write(`  ─ ${m.version}.md  (not found locally or on github — check the repo manually)\n`);
+      }
     }
     process.stdout.write(
       "\nAgent: open each file, identify document-level changes, grep document/ for affected patterns, propose edits before applying.\n",
@@ -107,11 +117,43 @@ async function hasCoreDep(root) {
 
 async function loadMigrations(root, versions) {
   const results = [];
+  const cacheDir = path.join(root, MIGRATION_CACHE_DIR);
+  await mkdir(cacheDir, { recursive: true });
+
   for (const v of versions) {
-    const p = path.join(root, "docs", "migrations", `${v}.md`);
-    if (existsSync(p)) {
-      results.push({ version: v, path: path.relative(root, p) });
+    // Framework repo has docs/migrations/ at root — prefer local if present
+    // (covers the open-press framework repo itself acting as a workspace).
+    const localDocsPath = path.join(root, "docs", "migrations", `${v}.md`);
+    if (existsSync(localDocsPath)) {
+      results.push({ version: v, path: path.relative(root, localDocsPath), fetched: false });
+      continue;
+    }
+
+    // Otherwise fetch from GitHub raw and cache to .openpress/migrations/.
+    const cachedPath = path.join(cacheDir, `${v}.md`);
+    if (existsSync(cachedPath)) {
+      results.push({ version: v, path: path.relative(root, cachedPath), fetched: false });
+      continue;
+    }
+
+    const body = await fetchMigration(v);
+    if (body) {
+      await writeFile(cachedPath, body, "utf8");
+      results.push({ version: v, path: path.relative(root, cachedPath), fetched: true });
+    } else {
+      results.push({ version: v, path: null, fetched: false });
     }
   }
   return results;
 }
+
+async function fetchMigration(version) {
+  const url = `${MIGRATION_REMOTE_BASE}/${version}.md`;
+  try {
+    const res = await fetch(url, { headers: { Accept: "text/plain" } });
+    if (!res.ok) return null;
+    return await res.text();
+  } catch {
+    return null;
+  }
+}

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) {