@open-press/cli 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-press/cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "Scaffolder for open-press — AI-first fixed-layout document workspaces.",
   "license": "MIT",

package/template/core/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @open-press/core
 
+## 0.7.0
+
+### Minor Changes
+
+- 718d2d1: **Press Tree render architecture** — full refresh of the React export pipeline (clean break, no v0.5 compatibility).
+
+  The render kernel no longer knows about `cover`, `toc`, `chapter`, or `back-cover` as built-in concepts. Workspaces describe their document as a React tree using three primitives:
+
+  - `Press` — root composition boundary.
+  - `Frame` — a single fixed-layout surface (replaces `BasePage` and friends).
+  - `MdxArea` — a measurable slot consuming a content chain, with `overflow="extend|truncate|error"` control.
+
+  Sources are now declarative descriptors:
+
+  ```tsx
+  export const sources = {
+    story: mdxSource({ preset: "section-folders", root: "chapters" }),
+  };
+
+  export default function MyPress() {
+    return (
+      <Press>
+        <Cover />
+        <Toc source="story" />
+        <Sections source="story" page={Page} />
+        <BackCover />
+      </Press>
+    );
+  }
+  ```
+
+  Three `mdxSource()` presets: `section-folders` (existing convention), `section-files` (flat file-per-section), `file-list` (explicit ordering).
+
+  Manuscript helpers (`Toc`, `Sections`, `Chapters` alias) ship in `@open-press/core/manuscript`. `mdxSource()` lives in `@open-press/core/mdx`. Subpath exports keep the public surface tight without committing to separate npm packages.
+
+  `Toc` is implemented as a manuscript helper, not a core kernel special case. Registered sources generate a synthetic `toc:<sourceId>` chain; `TocArea` consumes it with the same allocation path as `MdxArea`.
+
+  Reader-side pagination is removed. The export pipeline writes final frame HTML into `document.json`; the reader displays that HTML and no longer mutates headings/captions, injects footers, or reflows pages at runtime. Page shell belongs to workspace components.
+
+  MDX source resolution now derives manuscript TOC entries from actual `##` / `###` headings, not folder slugs. Heading numbering is written during export as `data-chapter="01"` / `data-section="1.1"` attributes so themes can render numbering with CSS without reader-side mutation.
+
+  **Removed (no compatibility layer):**
+
+  - `BasePage`, `BaseCoverPage`, `BaseTocPage`, `BaseContentPage`, `BaseBackCoverPage`.
+  - Legacy named exports (`cover`, `toc`, `backCover`) from `document/index.tsx`.
+  - The `migrate-to-react` CLI command.
+  - Implicit chapter discovery as the only source mechanism.
+  - Legacy `chapter.tsx` meta/opener auto-discovery. Section openers are explicit workspace components in the Press tree.
+
+  The top-level purity gate remains: `config` must be data, `sources` must be pure `mdxSource()` descriptors, and filesystem/network/process side effects are rejected before module execution. Default-exported function bodies can contain normal React component logic, including hooks and `.map()`.
+
+  All `<Frame>` instances require a stable `frameKey`; source roots and file-list entries must stay inside `document/`.
+
+  **Workspace data attributes:**
+
+  - `data-frame-role` (new, opaque role like `"manuscript.content"`).
+  - `data-page-kind` (derived from role's last segment — reader CSS keeps using this).
+  - `data-section-id` replaces `data-chapter-slug` for section-scoped CSS.
+
+  **Migration:** Workspaces written for v0.5.x must rewrite `document/index.tsx` to default-export a Press component. Pre-1.0 minor bump is acceptable per repo policy; no production deployments exist to break.
+
+  See `docs/superpowers/specs/2026-05-23-press-tree-render-architecture-design.md` for full design rationale.
+
 ## 0.6.0
 
 ### Minor Changes
@@ -40,6 +103,7 @@
 - 0169cba: Agent-driven upgrade flow.
 
   **New commands:**
+
   - `npx open-press doctor` — diagnose workspace against latest framework state. Reports `@open-press/core` version vs npm latest, installed skill count, and any pending `docs/migrations/<version>.md` notes between current and latest. `--json` for machine-readable output, `--no-cache` to bypass the 24h cache. Always exits 0 (informational only).
 
   - `npx open-press upgrade` — orchestrate the upgrade. Runs `npm update @open-press/core` (when the workspace declares the dep) and `npx skills upgrade`, then surfaces the list of migration notes for the agent to read. **Does not auto-edit `document/` content** — the agent reads the surfaced `docs/migrations/<version>.md` notes and proposes edits to the user with confirmation. Use `--dry-run` to preview, `--no-deps` / `--no-skills` to target one layer.
@@ -49,6 +113,7 @@
   `open-press dev` now runs `doctor` before starting Vite. When the workspace is behind, a single line prints: `○ open-press: @open-press/core 0.4.0 → 0.5.0 · 1 migration note(s) — run npx open-press doctor for details.` Cached for 24h, network failure is silent, never blocks dev.
 
   **Migration docs:**
+
   - New `docs/migrations/_template.md` — each release with breaking changes ships a `docs/migrations/<version>.md` file with sections the agent reads.
   - New `docs/migrations/0.4.0.md` — backfilled. Documents the SKILL fold (no document or CLI changes).
 
@@ -65,6 +130,7 @@
 ### Minor Changes
 
 - 3cb4939: Consolidate internal skills (13 → 11).
+
   - `openpress-update` folded into `openpress` as an "Updating An Existing Workspace" section. The release-upgrade flow, pre-flight checks, breaking-change reference, and do-not list are now part of the system-operation skill where they naturally belong.
   - `openpress-document-hierarchy` folded into `openpress-writing` as a "Hierarchy" section. Hierarchy decisions (H2/H3/H4 model, TOC depth, appendix placement, H4 granularity) and prose decisions happen in the same workflow; one skill, one routing decision.
   - `references/data-structures-outline.md` moved from the hierarchy skill into `openpress-writing/references/`.
@@ -81,4 +147,4 @@
 
   **@open-press/cli** (new): scaffolder for open-press workspaces. Run `npx @open-press/cli init <target> --pack <pack>` to create a fixed-layout document workspace from a bundled template. Supports `editorial-monograph` and `claude-document` style packs, metadata flags, and AI-agent skill installation under `.claude/skills/` and `.agents/skills/`.
 
-  **@open-press/core** (new): framework runtime, CLI engine, render pipeline, and base page primitives (BasePage, BaseCoverPage, BaseTocPage, BaseBackCoverPage, BaseFigure, BaseCallout). Consumed transitively by workspaces scaffolded via `@open-press/cli`. Exposes the `open-press` bin (dev / build / preview / validate / pdf / deploy / export).
+  **@open-press/core** (new): framework runtime, CLI engine, render pipeline, and document primitives. Consumed transitively by workspaces scaffolded via `@open-press/cli`. Exposes the `open-press` bin (dev / build / preview / validate / pdf / deploy / export).

package/template/core/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/template/core/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/template/core/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/template/core/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/template/core/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/template/core/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/template/core/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/template/core/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/template/core/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/template/core/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/template/core/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/template/core/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/template/core/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/template/core/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/template/core/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/template/core/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) {