@open-press/cli 0.5.0 → 0.7.0

package/dist/cli.js

@@ -19,6 +19,41 @@ import path from "path";
 import { Readable } from "stream";
 import { pipeline } from "stream/promises";
 import { x as extract } from "tar";
+async function degit({ owner, repo, ref = "main", dest, subdir }) {
+  const url = `https://codeload.github.com/${owner}/${repo}/tar.gz/refs/heads/${ref}`;
+  const tmpDir = await mkdir(path.join(tmpdir(), `open-press-degit-${Date.now()}`), { recursive: true });
+  const tarballPath = path.join(tmpDir, "repo.tar.gz");
+  try {
+    await fetchTo(url, tarballPath);
+    await mkdir(dest, { recursive: true });
+    const subdirSegments = subdir ? subdir.split("/").filter(Boolean).length : 0;
+    const totalStrip = 1 + subdirSegments;
+    const filterPrefix = subdir ? subdir.replace(/\/$/, "") + "/" : null;
+    await extract({
+      file: tarballPath,
+      cwd: dest,
+      strip: totalStrip,
+      filter: (filePath) => {
+        const segments = filePath.split("/");
+        const inside = segments.slice(1).join("/");
+        if (filterPrefix) {
+          return inside.startsWith(filterPrefix);
+        }
+        return true;
+      }
+    });
+  } finally {
+    await rm(tmpDir, { recursive: true, force: true }).catch(() => {
+    });
+  }
+}
+async function fetchTo(url, destFile) {
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok || !res.body) {
+    throw new Error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`);
+  }
+  await pipeline(Readable.fromWeb(res.body), createWriteStream(destFile));
+}
 async function pathIsEmpty(target) {
   try {
     const s = await stat(target);
@@ -80,14 +115,14 @@ async function patchPackageJsonName(packagePath, newName) {
 }
 
 // src/init.ts
-var KNOWN_PACKS = ["editorial-monograph", "claude-document"];
-var SKILLS_SOURCE = "quan0715/open-press";
+var BUNDLED_PACKS = ["editorial-monograph", "claude-document", "academic-paper"];
+var FRAMEWORK_SKILLS_SOURCE = "quan0715/open-press";
 var __dirname = path2.dirname(fileURLToPath(import.meta.url));
 var TEMPLATE_ROOT = path2.resolve(__dirname, "..", "template");
 var TEMPLATE_CORE = path2.join(TEMPLATE_ROOT, "core");
 var TEMPLATE_PACKS = path2.join(TEMPLATE_ROOT, "packs");
 async function init(options) {
-  validatePack(options.pack);
+  const packSpec = options.pack ? parsePackSpec(options.pack) : null;
   ensureTemplateBundled();
   const target = path2.resolve(process.cwd(), options.target);
   await ensureTarget(target, options.force);
@@ -95,17 +130,40 @@ async function init(options) {
   log("Copying framework (engine + runtime + config)\u2026");
   await cp(TEMPLATE_CORE, target, { recursive: true });
   const docDest = path2.join(target, "document");
-  if (options.pack) {
-    log(`Applying style pack: ${options.pack}`);
-    await rm2(docDest, { recursive: true, force: true });
-    await mkdir2(docDest, { recursive: true });
-    const packStarter = path2.join(TEMPLATE_PACKS, options.pack, "document");
+  await rm2(docDest, { recursive: true, force: true });
+  await mkdir2(docDest, { recursive: true });
+  if (packSpec?.kind === "bundled") {
+    log(`Applying bundled style pack: ${packSpec.name}`);
+    const packStarter = path2.join(TEMPLATE_PACKS, packSpec.name, "document");
     if (!existsSync(packStarter)) {
-      throw new Error(`Style pack starter not found in bundle: ${packStarter}`);
+      throw new Error(`Bundled style pack starter not found: ${packStarter}`);
     }
     await cp(packStarter, docDest, { recursive: true });
-  } else {
-    await mkdir2(docDest, { recursive: true });
+  } else if (packSpec?.kind === "github") {
+    log(`Fetching style pack from github:${packSpec.owner}/${packSpec.repo}${packSpec.ref ? `#${packSpec.ref}` : ""}\u2026`);
+    try {
+      await degit({
+        owner: packSpec.owner,
+        repo: packSpec.repo,
+        ref: packSpec.ref,
+        dest: docDest,
+        subdir: "starter/document"
+      });
+    } catch (err) {
+      throw new Error(
+        `Failed to fetch pack from github:${packSpec.owner}/${packSpec.repo}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    if (await pathIsEmpty(docDest)) {
+      throw new Error(
+        `github:${packSpec.owner}/${packSpec.repo} doesn't contain starter/document/ at the repo root.
+Third-party pack repos should follow this layout:
+  <repo>/
+  \u251C\u2500\u2500 starter/
+  \u2502   \u2514\u2500\u2500 document/   \u2190 cli copies this into your workspace's document/
+  \u2514\u2500\u2500 skills/<pack>/SKILL.md   \u2190 npx skills add picks this up`
+      );
+    }
   }
   const pkgPath = path2.join(target, "package.json");
   if (existsSync(pkgPath)) {
@@ -121,13 +179,23 @@ async function init(options) {
       author: options.author
     });
   }
-  log(`Installing agent skills via \`npx skills add ${SKILLS_SOURCE}\`\u2026`);
+  log(`Installing framework skills via \`npx skills add ${FRAMEWORK_SKILLS_SOURCE}\`\u2026`);
   try {
-    await runInTarget(target, "npx", ["-y", "skills@latest", "add", SKILLS_SOURCE]);
+    await runInTarget(target, "npx", ["-y", "skills@latest", "add", FRAMEWORK_SKILLS_SOURCE]);
   } catch (err) {
-    log(`(skills install failed; you can retry manually with \`npx skills add ${SKILLS_SOURCE}\`)`);
+    log(`(framework skills install failed; retry: npx skills add ${FRAMEWORK_SKILLS_SOURCE})`);
     log(`  reason: ${err instanceof Error ? err.message : String(err)}`);
   }
+  if (packSpec?.kind === "github") {
+    const packSource = `${packSpec.owner}/${packSpec.repo}`;
+    log(`Installing pack skills via \`npx skills add ${packSource}\`\u2026`);
+    try {
+      await runInTarget(target, "npx", ["-y", "skills@latest", "add", packSource]);
+    } catch (err) {
+      log(`(pack skills install failed; retry: npx skills add ${packSource})`);
+      log(`  reason: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
   if (options.install) {
     log("Installing dependencies (npm install)\u2026");
     await runInTarget(target, "npm", ["install"]);
@@ -148,6 +216,26 @@ async function init(options) {
   }
   printNextSteps(target, options);
 }
+function parsePackSpec(spec) {
+  if (spec.startsWith("github:")) {
+    const rest = spec.slice("github:".length);
+    const [pathPart, ref] = rest.split("#");
+    const segments = pathPart.split("/").filter(Boolean);
+    if (segments.length !== 2) {
+      throw new Error(
+        `Invalid --pack spec: "${spec}". Use github:owner/repo or github:owner/repo#ref.`
+      );
+    }
+    const [owner, repo] = segments;
+    return { kind: "github", owner, repo, ref: ref?.trim() || void 0 };
+  }
+  if (!BUNDLED_PACKS.includes(spec)) {
+    throw new Error(
+      `Unknown style pack: "${spec}". Bundled packs: ${BUNDLED_PACKS.join(", ")}. For third-party packs use github:owner/repo (e.g. github:quan0715/openpress-pack-nycu-thesis).`
+    );
+  }
+  return { kind: "bundled", name: spec };
+}
 function ensureTemplateBundled() {
   if (!existsSync(TEMPLATE_CORE) || !existsSync(TEMPLATE_PACKS)) {
     throw new Error(
@@ -155,12 +243,6 @@ function ensureTemplateBundled() {
     );
   }
 }
-function validatePack(pack) {
-  if (pack === void 0) return;
-  if (!KNOWN_PACKS.includes(pack)) {
-    throw new Error(`Unknown style pack: ${pack}. Known packs: ${KNOWN_PACKS.join(", ")}`);
-  }
-}
 async function ensureTarget(target, force) {
   if (existsSync(target)) {
     if (force) return;
@@ -228,19 +310,28 @@ Usage:
   npx @open-press/cli init <target> [flags]
 
 Flags:
-  --pack <name>            Style pack starter: editorial-monograph | claude-document
+  --pack <spec>            Style pack source. Either:
+                             \u2022 a bundled name \u2014 editorial-monograph | claude-document | academic-paper
+                             \u2022 github:owner/repo (third-party pack)
+                             \u2022 github:owner/repo#branch-or-tag
   --title <s>              Document title (written to openpress.config.mjs)
   --subtitle <s>           Document subtitle
   --organization <s>       Organization name
-  --author <s>             Author name (defaults to git user.name)
+  --author <s>             Author name
   --no-git                 Skip git init
   --no-install             Skip npm install
   --force                  Allow non-empty target
   --help                   Show this help
 
 Examples:
+  # Bundled
   npx @open-press/cli init my-doc --pack editorial-monograph
-  npx @open-press/cli init my-doc --pack claude-document --title "Q2 Brief" --author Quan
+  npx @open-press/cli init my-brief --pack claude-document --title "Q2 Brief" --author Quan
+  npx @open-press/cli init my-paper --pack academic-paper --title "Paper Title" --author "First Author"
+
+  # Third-party (any GitHub repo with starter/document/ at the root)
+  npx @open-press/cli init my-thesis --pack github:quan0715/openpress-pack-nycu-thesis
+  npx @open-press/cli init my-paper --pack github:foo/their-pack#v1.2
 `;
 async function main(argv) {
   if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-press/cli",
-  "version": "0.5.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,101 @@
 # @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
+
+- f8fdecd: Third bundled pack: `academic-paper`.
+
+  A single-column A4 academic / research paper starter — serif title block, abstract band, index terms, numbered sections (I, II, III), italic sub-sections (A, B, C), `[N]` numeric references, sample chapters derived from the IEEE conference template structure (Introduction, Methods, Results & Discussion, Acknowledgment, References).
+
+  ```bash
+  npx @open-press/cli init my-paper --pack academic-paper
+  ```
+
+  Suitable for: draft / preprint / iteration. Not suitable for camera-ready IEEE / ACM submission — those still need LaTeX with the publisher's class file.
+
+  Two-column body and other paged-document features (footnotes, cross-references with page numbers, running headers) are intentionally **out of scope for this release**. They'll be designed as a self-maintained engine evolution + multi-mode architecture in a separate spec round, rather than depending on a third-party pagination polyfill.
+
+- c490653: `@open-press/cli init` accepts third-party style packs via `--pack github:owner/repo`.
+
+  ```bash
+  # bundled (unchanged)
+  npx @open-press/cli init my-doc --pack editorial-monograph
+
+  # third-party (new)
+  npx @open-press/cli init my-thesis --pack github:quan0715/openpress-pack-nycu-thesis
+  npx @open-press/cli init my-paper --pack github:foo/their-pack#v1.2
+  ```
+
+  The cli fetches `starter/document/` from the named repo (default branch, or `#ref` for a specific branch/tag) and copies it into the new workspace. If the pack repo also publishes SKILL files at `skills/<name>/`, they're installed via `npx skills add <owner>/<repo>` after the framework skills, so the agent picks them up automatically.
+
+  Repo layout convention for third-party packs is documented in `docs/style-pack-authoring.md`. Empty-result extraction (the named repo exists but has no `starter/document/` at root) fails with a clear error pointing at the expected layout.
+
+  The two bundled packs (`editorial-monograph`, `claude-document`) keep their current short-name behaviour; only the cli's validator widened to accept the `github:` prefix.
+
 ## 0.5.0
 
 ### Minor Changes
@@ -51,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;");
+}