@open-press/cli 0.6.0 → 0.7.1

package/package.json

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

package/template/core/AGENTS.md

@@ -0,0 +1,126 @@
+# Working on this open-press workspace
+
+This directory is an **open-press workspace** scaffolded by
+`@open-press/cli`. You (the agent) own:
+
+- `document/` — chapters (MDX), components, theme, media. The actual content.
+- `package.json` / `openpress.config.mjs` — project metadata + build config.
+- `.agents/skills/` — agent skills installed by `npx skills` (auto-refreshed via `npx open-press upgrade`).
+
+The rest of the tree is the open-press framework copied at scaffold time
+(`engine/`, `src/`, `vite.config.ts`, etc). Treat it as vendored — don't
+hand-edit unless the user explicitly asks; the next `npx open-press upgrade`
+will rewrite it.
+
+## Quick reference
+
+```bash
+npm run dev                  # workbench at http://127.0.0.1:5173/?dev=1
+npm run openpress:validate   # structural checks
+npm run openpress:render     # full render through chromium
+npm run openpress:pdf        # write document.pdf
+npm run openpress:export     # write public/openpress/document.json
+npm run openpress:deploy     # deploy via the configured adapter
+npx open-press doctor        # current vs latest version + pending migrations
+npx open-press upgrade       # apply the upgrade flow (see below)
+```
+
+## When the user asks to upgrade
+
+Triggers: "升級 / 套件更新 / upgrade open-press / apply latest design /
+update to vX.Y.Z" etc.
+
+**Follow the upgrade SOP, do NOT manually diff template versions:**
+
+1. `npx open-press doctor` — confirm current vs latest, count pending
+   migrations.
+2. Ask the user "go ahead?" — briefly mention what will change (deps,
+   skills, migrations to read).
+3. `npx open-press upgrade` — refreshes `@open-press/core`, refreshes
+   installed skills, **fetches migration notes for each pending version
+   into `.openpress/migrations/<version>.md`** and lists the paths.
+4. For each migration file listed, read it fully. Each has a
+   `Document-level changes` section with `rg` find + rewrite rules.
+   Apply to `document/` with user confirmation.
+5. Verify:
+   ```bash
+   npm run openpress:validate
+   npm run openpress:render
+   ```
+   Fix anything broken using the migration notes.
+6. Report to the user: starting version → ending version, what was
+   applied, anything that needed manual judgement.
+
+**Anti-pattern**: running `npx @open-press/cli@latest init` somewhere
+and manually diffing against the workspace. The migration notes are the
+authoritative source for what changed; fresh templates ship default
+content that does not apply to a customised workspace.
+
+## When the user says "I changed X but the page didn't update"
+
+Common cause: **the reader renders from a static `public/openpress/document.json`,
+not from your live MDX / theme files.** Vite Hot Reload covers React UI
+chrome (workbench panels, inspector, navigation) but it does **not**
+regenerate `document.json`. So edits to:
+
+- `document/chapters/**/*.mdx` (prose)
+- `document/index.tsx` (Press tree, Cover/BackCover JSX)
+- `document/components/**/*.tsx` (Page, openers, custom components)
+- `document/theme/**` style files that affect pagination capacity
+- `openpress.config.mjs` metadata (title, captionNumbering, …)
+
+…all need a re-export before the workbench / public viewer reflect
+the change:
+
+```bash
+npm run openpress:export   # regenerate public/openpress/document.json
+# then refresh the browser
+```
+
+Quick rules of thumb:
+
+- Pure CSS edits under `document/theme/` that don't move blocks → HMR
+  is enough (CSS is hot-replaced).
+- Anything that affects content, pagination, or metadata → re-export.
+- `npm run openpress:render` is `export` + extra asset sync; either
+  works to refresh the JSON.
+
+**Agent SOP**: after applying any non-CSS edit to `document/`, run
+`npm run openpress:export` before telling the user "done". If they ask
+"why didn't my change show up?", check whether `document.json` was
+regenerated since the edit.
+
+## When the user reports a render / paginate issue
+
+Press Tree paginates at build time. Common things to check:
+
+1. `npm run openpress:export` then inspect
+   `public/openpress/document.json` for `source.warnings` (chain
+   overflow, missing chains, etc.).
+2. `npm run openpress:validate` for structural issues
+   (missing entries, broken anchors).
+3. `npm run dev` and use the workbench inspector to find which MDX
+   block / Frame element is misbehaving — comments and inline
+   annotations work directly from there.
+
+## Skills
+
+This workspace ships agent skills under `.agents/skills/`. If your
+platform supports skills (Claude Code, Cursor, Codex, Cline, Gemini
+CLI, …), prefer invoking them over re-reading this file:
+
+- `openpress` — operate the workspace (CLI, validate, export, render,
+  PDF, deploy, search/replace, comments, upgrades, routing).
+- `openpress-writing` — writing-time rules for MDX prose.
+- `openpress-design` — theme tokens, layout, page surfaces.
+- `openpress-deploy` — deployment workflows.
+- `openpress-init` — scaffolding new workspaces.
+- Plus any style-pack-specific skills installed by the user.
+
+Skills are kept in sync by `npx skills upgrade` (run automatically
+inside `npx open-press upgrade`).
+
+## Reporting issues
+
+- Issues / questions: https://github.com/quan0715/open-press/issues
+- Source: https://github.com/quan0715/open-press

package/template/core/CHANGELOG.md

@@ -1,5 +1,88 @@
 # @open-press/core
 
+## 0.7.1
+
+### Patch Changes
+
+- Measurement pipeline + pagination fixes:
+
+  - **Measurement**: wait on `document.fonts.ready`, image `load`/`error` + `decode()`,
+    and two `requestAnimationFrame` ticks before sampling block heights so figures
+    no longer under-measure on cold loads.
+  - **Measurement**: inline relative `media/`, `./media/`, and `/openpress/media/`
+    image sources during the SSR measurement pass (previously only the absolute
+    `/openpress/media/...` form was rewritten, leaving relative refs as broken).
+  - **MDX compile**: split bullet/numbered lists into per-item paginable blocks
+    so long lists can break across pages without losing ordered numbering.
+  - **Debug**: new `OPENPRESS_DEBUG_ALLOC` env var prints per-iteration allocator
+    state (mdxArea capacities, block heights, pagination hints, warnings).
+  - **Academic-paper starter**: `<MdxArea overflow="extend">` on the body and the
+    single-column `.reader-page--content .page-body` override removed so content
+    paginates naturally with the new allocator.
+
+## 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 +123,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 +133,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 +150,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 +167,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/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/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;");
+}