@open-press/core 0.8.0 → 1.0.0

package/README.md

@@ -5,10 +5,10 @@ Framework runtime, CLI engine, and Press Tree primitives for [open-press](https:
 Most users do **not** install this package directly. Instead, scaffold a workspace with the CLI:
 
 ```bash
-npx @open-press/cli init my-doc --pack editorial-monograph
+npx @open-press/cli init my-doc
 ```
 
-The scaffolded workspace contains a snapshot of this package.
+The scaffolded workspace contains a snapshot of this package. Starter files are supplied by skills, not by `@open-press/core`.
 
 ## Direct use
 
@@ -31,7 +31,10 @@ 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.
+`press/index.tsx` or transitional `document/index.tsx` default-exports a `<Workspace>/<Press>` tree. `Frame` marks fixed-layout pages, `MdxArea` receives measured MDX blocks, and `mdxSource()` declares which MDX files participate in the render pipeline.
+
+For the maintenance contract around Press Tree, page geometry presets, and the
+allocation pipeline, see [`docs/press-tree.md`](https://github.com/quan0715/open-press/blob/main/docs/press-tree.md).
 
 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).
 

package/engine/cli.mjs

@@ -4,25 +4,25 @@ import * as deployCmd from "./commands/deploy.mjs";
 import * as devCmd from "./commands/dev.mjs";
 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 imageCmd from "./commands/image.mjs";
 import * as pdfCmd from "./commands/pdf.mjs";
 import * as previewCmd from "./commands/preview.mjs";
 import * as replaceCmd from "./commands/replace.mjs";
 import * as renderCmd from "./commands/render.mjs";
 import * as searchCmd from "./commands/search.mjs";
+import * as skillsSyncCmd from "./commands/skills-sync.mjs";
 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 "./runtime/config.mjs";
-import { listStylePackSkills } from "./init.mjs";
 import { discoverWorkspace } from "./runtime/validation.mjs";
 
 const COMMANDS = {
-  init: initCmd,
   validate: validateCmd,
   inspect: inspectCmd,
+  image: imageCmd,
   search: searchCmd,
   replace: replaceCmd,
   export: exportCmd,
@@ -34,6 +34,8 @@ const COMMANDS = {
   deploy: deployCmd,
   doctor: doctorCmd,
   upgrade: upgradeCmd,
+  migrate: upgradeCmd,
+  "skills:sync": skillsSyncCmd,
 };
 
 const args = process.argv.slice(2);
@@ -71,12 +73,9 @@ async function main(commandName, argv) {
 }
 
 async function printHelp() {
-  const packs = await listStylePackSkills();
-  const skillList = packs.length ? packs.join(" | ") : "(none installed)";
   console.log(`Usage: node engine/cli.mjs <command> [path] [options]
 
 Commands:
-  init <target> [--skill <name>] [--force]
   validate
   inspect [--json] [--no-build] [--dry-run]
   search [path] <query> [--json] [--scope content|all]
@@ -86,11 +85,12 @@ Commands:
   preview --renderer react [--host 127.0.0.1] [--port 5173] [--no-build] [--dry-run]
   dev --renderer react [--host 127.0.0.1] [--port 5173] [--no-build] [--dry-run]
   typecheck
+  image [--output <outputDir>] [--no-build] [--dry-run]
   pdf [--output <outputDir>/<pdf.filename>] [--no-build] [--dry-run]
   deploy --confirm [--dry-run]
   doctor [--json] [--no-cache]                          # version + skill staleness check
   upgrade [--dry-run] [--no-deps] [--no-skills] [--json] # apply updates; agent-driven
-
-Style packs available for \`init --skill\`: ${skillList}
+  migrate [--dry-run] [--no-deps] [--no-skills] [--json] # alias for upgrade; reads migration notes
+  skills:sync [--source <owner/repo>] [--dry-run]        # refresh installed agent skills
 `);
 }

package/engine/commands/_shared.mjs

@@ -2,7 +2,7 @@ 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 "../output/chrome-pdf.mjs";
+import { captureUrlPagesToPng, printUrlToPdf, stopChildProcess, waitForPrintReady } from "../output/chrome-pdf.mjs";
 import { loadConfig, publicPdfHref } from "../runtime/config.mjs";
 import { exportDocument } from "../document-export.mjs";
 import { optimizePdfMediaForStaticRoot } from "../output/pdf-media.mjs";
@@ -23,6 +23,9 @@ export function parseOptions(argv) {
     else if (value === "--force") options.force = true;
     else if (value === "--confirm") options.confirm = true;
     else if (value === "--json") options.json = true;
+    else if (value === "--no-cache") options.noCache = true;
+    else if (value === "--no-deps") options.noDeps = true;
+    else if (value === "--no-skills") options.noSkills = true;
     else if (value === "--no-build") options.noBuild = true;
     else if (value === "--apply") options.apply = true;
     else if (value === "--include-code") options.includeCode = true;
@@ -38,20 +41,6 @@ export function parseOptions(argv) {
   return options;
 }
 
-export function parseInitOptions(argv) {
-  const options = { force: false };
-  const positional = [];
-  for (let i = 0; i < argv.length; i += 1) {
-    const value = argv[i];
-    if (value === "--skill") options.skill = argv[++i];
-    else if (value === "--force") options.force = true;
-    else if (value.startsWith("--")) throw new Error(`Unknown option: ${value}`);
-    else positional.push(value);
-  }
-  options.target = positional[0];
-  return options;
-}
-
 export function formatDisplayPath(absolutePath) {
   const relative = path.relative(process.cwd(), absolutePath);
   if (!relative || relative.startsWith("..")) return absolutePath;
@@ -118,6 +107,39 @@ export async function buildReactPdf({
   return { pdfPath: outPath };
 }
 
+export async function buildReactImages({
+  root,
+  config,
+  outDir,
+  host = "127.0.0.1",
+  port = "5186",
+  noBuild = false,
+  recurse,
+}) {
+  config ??= await loadConfig(root);
+  outDir ??= path.join(config.paths.outputDir, "images");
+  const renderCode = await buildReactStatic({ root, noBuild, recurse });
+  if (renderCode !== 0) throw new Error(`React render failed with exit code ${renderCode}`);
+  await fs.mkdir(outDir, { recursive: true });
+
+  const server = await startStaticServer(root, config, host, port);
+  try {
+    const result = await captureUrlPagesToPng({
+      root,
+      url: `http://${host}:${port}/?print=1`,
+      outDir,
+      waitForReady: waitForPrintReady,
+      debuggingPortBase: 9700,
+      debuggingPortRange: 600,
+      profilePrefix: "chrome-image",
+    });
+    console.log(`${result.files.length} OpenPress pages exported to PNG`);
+    return { outDir, files: result.files, pageCount: result.pageCount };
+  } finally {
+    await stopChildProcess(server);
+  }
+}
+
 export function startStaticServer(root, config, host, port) {
   return new Promise((resolve, reject) => {
     const child = spawn("node", [STATIC_SERVER, config.outputDir, "--host", host, "--port", port, "--workspace", "."], {

package/engine/commands/image.mjs

@@ -0,0 +1,29 @@
+import path from "node:path";
+import { CLI_ENTRY, STATIC_SERVER, buildReactImages, formatNodeScriptCommand } from "./_shared.mjs";
+
+export async function run({ root, config, options, recurse }) {
+  const outputDir = options.output ? path.resolve(root, options.output) : path.join(config.paths.outputDir, "images");
+  const host = options.host ?? "127.0.0.1";
+  const port = options.port ?? "5186";
+
+  if (options.dryRun) {
+    console.log(`Command: ${formatNodeScriptCommand(root, CLI_ENTRY)} render . --renderer react`);
+    console.log(`Command: ${formatNodeScriptCommand(root, STATIC_SERVER)} ${config.outputDir} --host ${host} --port ${port} --workspace .`);
+    console.log(`Chrome image export URL: http://${host}:${port}/?print=1`);
+    console.log(`Output: ${path.relative(root, path.join(outputDir, "page-001.png"))}`);
+    return 0;
+  }
+
+  const result = await buildReactImages({
+    root,
+    config,
+    outDir: outputDir,
+    host,
+    port,
+    noBuild: options.noBuild,
+    recurse,
+  });
+
+  console.log(`OpenPress images: ${path.relative(root, result.outDir)} (${result.files.length} pages)`);
+  return 0;
+}

package/engine/commands/skills-sync.mjs

@@ -0,0 +1,71 @@
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { runCommand } from "./_shared.mjs";
+
+const DEFAULT_SOURCE = "quan0715/open-press";
+
+// Refresh installed agent skills against the workspace's lock file.
+// Behavior:
+//   - If skills-lock.json exists, run `npx skills upgrade` (refreshes all
+//     currently-installed sources to their latest published versions).
+//   - If skills-lock.json is missing, install the OpenPress framework
+//     skill bundle (and any user-supplied --source) as a first-time setup.
+//   - If a --source flag is passed, also add that source on top of any
+//     existing installations.
+//
+// Always exits 0 unless the underlying `skills` tool fails.
+export async function run({ root, options }) {
+  const lockPath = path.join(root, "skills-lock.json");
+  const lockExists = existsSync(lockPath);
+  const extraSource = options?.source;
+
+  if (options?.dryRun) {
+    if (lockExists) {
+      console.log("Command: npx -y skills@latest upgrade");
+    } else {
+      console.log(`Command: npx -y skills@latest add ${DEFAULT_SOURCE}`);
+    }
+    if (extraSource) {
+      console.log(`Command: npx -y skills@latest add ${extraSource}`);
+    }
+    return 0;
+  }
+
+  if (lockExists) {
+    const sources = await readLockSources(lockPath);
+    if (sources.length === 0) {
+      console.log("skills-lock.json has no sources; installing framework default…");
+      const code = await runCommand("npx", ["-y", "skills@latest", "add", DEFAULT_SOURCE], root);
+      if (code !== 0) return code;
+    } else {
+      console.log(`Refreshing ${sources.length} installed source(s)…`);
+      for (const src of sources) console.log(`  ${src}`);
+      const code = await runCommand("npx", ["-y", "skills@latest", "upgrade"], root);
+      if (code !== 0) return code;
+    }
+  } else {
+    console.log(`No skills-lock.json; installing framework default: ${DEFAULT_SOURCE}`);
+    const code = await runCommand("npx", ["-y", "skills@latest", "add", DEFAULT_SOURCE], root);
+    if (code !== 0) return code;
+  }
+
+  if (extraSource) {
+    console.log(`Adding extra source: ${extraSource}`);
+    const code = await runCommand("npx", ["-y", "skills@latest", "add", extraSource], root);
+    if (code !== 0) return code;
+  }
+
+  console.log("✓ Skills synced");
+  return 0;
+}
+
+async function readLockSources(lockPath) {
+  try {
+    const lock = JSON.parse(await readFile(lockPath, "utf8"));
+    const sources = Array.isArray(lock?.sources) ? lock.sources : [];
+    return sources.map((s) => s?.source).filter((s) => typeof s === "string");
+  } catch {
+    return [];
+  }
+}

package/engine/commands/typecheck.mjs

@@ -1,5 +1,67 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
 import { runCommand } from "./_shared.mjs";
 
+// Run typecheck via the locally installed typescript. The previous
+// implementation used `npx tsc`; npm 11 + Node 24 (our CI / release
+// pin) changed npx's bin lookup so it no longer walks pnpm's nested
+// `.bin/` symlink farm and falls back to fetching the legacy
+// `tsc@2.0.4` shim, which crashes.
+//
+// Resolution order:
+//   1. `node <resolved tsc>` via require.resolve(typescript/package.json)
+//      — works with npm-hoisted layouts and most pnpm installs.
+//   2. Walk up node_modules/.bin/tsc — covers downstream npm/yarn.
+//   3. Fall back to `pnpm exec tsc` — pnpm knows its own symlink farm
+//      even when bare require.resolve doesn't, which is what CI hits.
 export async function run({ root }) {
-  return runCommand("npx", ["tsc", "--noEmit", "-p", "tsconfig.json"], root);
+  const absoluteRoot = path.resolve(root);
+
+  const tscBin = resolveTscBin(absoluteRoot);
+  if (tscBin) {
+    return runCommand("node", [tscBin, "--noEmit", "-p", "tsconfig.json"], absoluteRoot);
+  }
+
+  if (hasCommand("pnpm")) {
+    return runCommand("pnpm", ["exec", "tsc", "--noEmit", "-p", "tsconfig.json"], absoluteRoot);
+  }
+
+  console.error("[openpress] typescript is not installed in this workspace.");
+  console.error("Add it with: npm install --save-dev typescript");
+  return 1;
+}
+
+function resolveTscBin(absoluteRoot) {
+  try {
+    const require = createRequire(path.join(absoluteRoot, "package.json"));
+    const pkgPath = require.resolve("typescript/package.json");
+    return path.join(path.dirname(pkgPath), "bin", "tsc");
+  } catch {
+    // fall through to .bin probe
+  }
+
+  let dir = absoluteRoot;
+  while (true) {
+    const candidate = path.join(dir, "node_modules", ".bin", "tsc");
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function hasCommand(name) {
+  const PATH = process.env.PATH ?? "";
+  const sep = process.platform === "win32" ? ";" : ":";
+  const exts = process.platform === "win32"
+    ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")
+    : [""];
+  for (const dir of PATH.split(sep)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      if (fs.existsSync(path.join(dir, name + ext))) return true;
+    }
+  }
+  return false;
 }

package/engine/commands/upgrade.mjs

@@ -46,7 +46,7 @@ export async function run({ root, options }) {
     if (!json) {
       process.stdout.write("dry run — nothing changed. The agent should:\n");
       process.stdout.write("  1. read each docs/migrations/<version>.md for document-level changes\n");
-      process.stdout.write("  2. apply edits to document/ where needed\n");
+      process.stdout.write("  2. apply edits to press/ where needed\n");
       process.stdout.write("  3. re-run: npx open-press upgrade   (without --dry-run)\n");
     } else {
       process.stdout.write(JSON.stringify({ status: "dry-run", before }, null, 2) + "\n");
@@ -98,11 +98,11 @@ export async function run({ root, options }) {
       }
     }
     process.stdout.write(
-      "\nAgent: open each file, identify document-level changes, grep document/ for affected patterns, propose edits before applying.\n",
+      "\nAgent: open each file, identify document-level changes, grep press/ for affected patterns, propose edits before applying.\n",
     );
   }
 
-  process.stdout.write("\nVerify with:\n  npm run openpress:validate\n  npm run openpress:render\n\n");
+  process.stdout.write("\nVerify with:\n  npm run build\n\n");
   return 0;
 }
 

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 with a Press default export before exporting.",
+    "React/MDX document entry not found. Expected press/index.tsx with a Press default export before exporting.",
   );
 }

package/engine/output/chrome-pdf.mjs

@@ -152,6 +152,78 @@ export async function printUrlToPdf({
   }
 }
 
+export async function captureUrlPagesToPng({
+  root,
+  url,
+  outDir,
+  chrome,
+  waitForReady = waitForPrintReady,
+  viewport = DEFAULT_PRINT_VIEWPORT,
+  debuggingPortBase = 9700,
+  debuggingPortRange = 300,
+  profilePrefix = "chrome-image",
+}) {
+  chrome ??= resolveChromePath();
+  await fs.mkdir(outDir, { recursive: true });
+
+  const debuggingPort = String(debuggingPortBase + Math.floor(Math.random() * debuggingPortRange));
+  const profileDir = path.join(root, ".openpress", "tmp", `${profilePrefix}-${process.pid}-${Date.now()}`);
+  await fs.mkdir(profileDir, { recursive: true });
+
+  const child = spawn(
+    chrome,
+    [
+      "--headless=new",
+      "--disable-gpu",
+      "--no-sandbox",
+      `--remote-debugging-port=${debuggingPort}`,
+      `--user-data-dir=${profileDir}`,
+      "about:blank",
+    ],
+    { cwd: root, stdio: ["ignore", "pipe", "pipe"] },
+  );
+
+  try {
+    const tab = await waitForChromeTab(debuggingPort);
+    const client = await connectChromeDevTools(tab.webSocketDebuggerUrl);
+    try {
+      await preparePdfPage(client, { viewport });
+      await client.send("Page.navigate", { url });
+      const pageCount = await waitForReady(client);
+      const rects = await getPrintPageRects(client);
+      if (rects.length === 0) throw new Error("No OpenPress pages found for image export.");
+
+      const padWidth = Math.max(3, String(rects.length).length);
+      const files = [];
+      for (const [index, rect] of rects.entries()) {
+        const filename = `page-${String(index + 1).padStart(padWidth, "0")}.png`;
+        const filePath = path.join(outDir, filename);
+        const result = await client.send("Page.captureScreenshot", {
+          format: "png",
+          fromSurface: true,
+          captureBeyondViewport: true,
+          clip: {
+            x: Math.max(0, rect.x),
+            y: Math.max(0, rect.y),
+            width: rect.width,
+            height: rect.height,
+            scale: 1,
+          },
+        });
+        await fs.writeFile(filePath, Buffer.from(String(result.data ?? ""), "base64"));
+        files.push(filePath);
+      }
+
+      return { pageCount, files };
+    } finally {
+      client.close();
+    }
+  } finally {
+    await stopChildProcess(child);
+    await cleanupChromeProfile(profileDir);
+  }
+}
+
 export async function preparePdfPage(client, { viewport = DEFAULT_PRINT_VIEWPORT } = {}) {
   await client.send("Page.enable");
   await client.send("Runtime.enable");
@@ -265,6 +337,26 @@ export async function waitForPrintReady(client) {
   throw new Error("Timed out waiting for OpenPress pagination before PDF export.");
 }
 
+async function getPrintPageRects(client) {
+  const result = await client.send("Runtime.evaluate", {
+    returnByValue: true,
+    expression: `(() => {
+      return Array.from(document.querySelectorAll('.openpress-public-page > .openpress-html-page')).map((page, index) => {
+        const target = page.querySelector('.openpress-html-page__html') || page;
+        const rect = target.getBoundingClientRect();
+        return {
+          index,
+          x: rect.left + window.scrollX,
+          y: rect.top + window.scrollY,
+          width: rect.width,
+          height: rect.height,
+        };
+      }).filter((rect) => rect.width > 0 && rect.height > 0);
+    })()`,
+  });
+  return Array.isArray(result.result?.value) ? result.result.value : [];
+}
+
 export async function stopChildProcess(child) {
   if (child.exitCode !== null || child.signalCode !== null) return;
   child.kill();

package/engine/output/static-server.mjs

@@ -73,17 +73,45 @@ const server = http.createServer(async (req, res) => {
       res.end("Forbidden");
       return;
     }
-    const stat = await fs.stat(target);
-    const filePath = stat.isDirectory() ? path.join(target, "index.html") : target;
-    const body = await fs.readFile(filePath);
-    res.writeHead(200, { "Content-Type": mimeTypes[path.extname(filePath)] ?? "application/octet-stream" });
-    res.end(body);
+    try {
+      const stat = await fs.stat(target);
+      const filePath = stat.isDirectory() ? path.join(target, "index.html") : target;
+      const body = await fs.readFile(filePath);
+      res.writeHead(200, { "Content-Type": mimeTypes[path.extname(filePath)] ?? "application/octet-stream" });
+      res.end(body);
+    } catch (err) {
+      // SPA fallback: when a path doesn't map to a real file AND it
+      // looks like a client-side route (no extension, not under a
+      // reserved namespace), serve index.html so the reader's URL-based
+      // routing can take over. This lets /cheatsheet / /proposal etc.
+      // reload correctly without needing host-level rewrite rules.
+      if (err?.code === "ENOENT" && shouldFallbackToIndex(url.pathname)) {
+        const indexBody = await fs.readFile(path.join(root, "index.html"));
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(indexBody);
+        return;
+      }
+      throw err;
+    }
   } catch {
     res.writeHead(404);
     res.end("Not found");
   }
 });
 
+function shouldFallbackToIndex(pathname) {
+  // Reserved namespaces — real resources whose 404s should stay 404.
+  if (pathname.startsWith("/openpress/")) return false;
+  if (pathname.startsWith("/__openpress/")) return false;
+  if (pathname.startsWith("/assets/")) return false;
+  // Anything with a file extension is an asset miss; fall through.
+  const lastSlash = pathname.lastIndexOf("/");
+  const tail = pathname.slice(lastSlash + 1);
+  if (tail.includes(".")) return false;
+  // Otherwise: looks like a client-side route — serve the SPA shell.
+  return true;
+}
+
 server.listen(port, host, () => {
   console.log(`OpenPress static preview: http://${host}:${port}/`);
 });
@@ -149,7 +177,10 @@ function valueAfter(args, flag) {
 
 async function inferWorkspaceRoot(staticRoot) {
   for (const candidate of [staticRoot, path.dirname(staticRoot), path.dirname(path.dirname(staticRoot))]) {
-    if (await fileExists(path.join(candidate, "openpress.config.mjs"))) return candidate;
+    // 1.0 workspace markers: press/index.tsx (the document entry) or
+    // package.json with an "openpress" field. Either is sufficient.
+    if (await fileExists(path.join(candidate, "press", "index.tsx"))) return candidate;
+    if (await hasOpenpressPackageField(candidate)) return candidate;
   }
   if (path.basename(path.dirname(staticRoot)) === ".deploy") {
     return path.dirname(path.dirname(staticRoot));
@@ -157,6 +188,16 @@ async function inferWorkspaceRoot(staticRoot) {
   return process.cwd();
 }
 
+async function hasOpenpressPackageField(dir) {
+  try {
+    const text = await fs.readFile(path.join(dir, "package.json"), "utf8");
+    const parsed = JSON.parse(text);
+    return parsed?.openpress && typeof parsed.openpress === "object";
+  } catch {
+    return false;
+  }
+}
+
 async function handleLocalPdfExportRequest(req, res) {
   if (req.method !== "POST") {
     writeJson(res, 405, { ok: false, message: "Local PDF export endpoint requires POST." });
@@ -367,7 +408,7 @@ function isDeployConfigured() {
 function deploySetupMessage() {
   if (isDeployConfigured()) return undefined;
   if (config.deploy.adapter === "cloudflare-pages") {
-    return "Cloudflare Pages deployment requires `deploy.projectName` in openpress.config.mjs.";
+    return 'Cloudflare Pages deployment requires `openpress.deploy.projectName` in package.json.';
   }
   return `Deployment adapter \`${config.deploy.adapter}\` is not configured.`;
 }
@@ -433,8 +474,6 @@ function getDeploymentSourcePaths() {
     path.join(workspace, "src"),
     path.join(workspace, "index.html"),
     path.join(workspace, "package.json"),
-    path.join(workspace, "openpress.config.mjs"),
-    config.configPath,
     path.join(workspace, "vite.config.ts"),
   ];
 }

package/engine/react/comment-marker.mjs

@@ -4,15 +4,15 @@ import path from "node:path";
 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.
+// Any `.mdx` or `.tsx` file under `press/` 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
+// longer hardcode `press/chapters/<slug>/content/*.mdx`. The boundary
+// is "inside the workspace's authored `press/` directory" and "looks
 // like an editable React/MDX source" by extension.
 const EDITABLE_COMMENT_SOURCE_PATTERNS = [
-  /^document\/.+\.mdx$/,
-  /^document\/.+\.tsx$/,
+  /^press\/.+\.mdx$/,
+  /^press\/.+\.tsx$/,
 ];
 const COMMENT_MARKER_RE = /(?:\{\/\*|\/\*)\s*@openpress-comment\b(?<attrs>[^*]*)\*\/\}?/g;
 const COMMENT_LINE_RE = /^\s*(?:\{\/\*|\/\*)\s*@openpress-comment\b[^*]*\*\/\}?\s*$/;
@@ -167,23 +167,23 @@ function normalizeEditableSourcePath(value) {
     throw new Error(`OpenPress comment target path is invalid: ${value}`);
   }
   const posix = path.posix.normalize(normalized);
-  // The Press Tree source resolver emits paths relative to `document/`
+  // The Press Tree source resolver emits paths relative to `press/`
   // (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}`;
+  // works in workspace-relative paths (with the `press/` prefix). If
+  // the incoming path is documentRoot-relative, prepend `press/`.
+  if (!posix.startsWith("press/") && looksDocumentRelative(posix)) {
+    return `press/${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
+// to `press/`. Match `.mdx` / `.tsx` files that don't already have the
+// `press/` 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/",
+  "press/",
   "src/",
   "engine/",
   "dist/",