@open-press/core 1.2.1 → 1.3.2

package/README.md

@@ -5,7 +5,7 @@ Package-owned runtime, render engine, and Press Tree primitives for [open-press]
 Most users do **not** install this package directly. Instead, scaffold a workspace with the CLI:
 
 ```bash
-npx @open-press/cli init my-doc
+npx @open-press/cli init my-doc --type pages
 ```
 
 The scaffolded workspace depends on this package; it does not vendor a copy of the runtime. Starter files are supplied by skills or by project-specific `press/` source files.
@@ -31,7 +31,7 @@ import { mdxSource } from "@open-press/core/mdx";
 import { Sections, Toc } from "@open-press/core/manuscript";
 ```
 
-`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.
+Each `press/<slug>/press.tsx` default-exports a component that renders one `<Press>`. `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).

package/engine/commands/typecheck.mjs

@@ -8,7 +8,7 @@ import { loadConfig } from "../runtime/config.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
+// `.bin/` symlink farm and may fetch the wrong
 // `tsc@2.0.4` shim, which crashes.
 //
 // Resolution order:

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

package/engine/output/page-block.mjs

@@ -11,12 +11,21 @@ function rewriteAssetPaths(pageHtml, config) {
   const mediaDir = config.mediaDir.replace(/^\/+|\/+$/g, "");
   return pageHtml
     .replaceAll(`src="${mediaDir}/`, 'src="/openpress/media/')
-    .replaceAll(`src='${mediaDir}/`, "src='/openpress/media/");
+    .replaceAll(`src='${mediaDir}/`, "src='/openpress/media/")
+    .replaceAll('src="media/', 'src="/openpress/media/')
+    .replaceAll("src='media/", "src='/openpress/media/")
+    .replaceAll(`src="./${mediaDir}/`, 'src="/openpress/media/')
+    .replaceAll(`src='./${mediaDir}/`, "src='/openpress/media/")
+    .replaceAll('src="./media/', 'src="/openpress/media/')
+    .replaceAll("src='./media/", "src='/openpress/media/");
 }
 
 export function pageToBlock(index, pageHtml, source, config, { idPrefix = "openpress-page", anchorPrefix = "page", titleFallback = "Page" } = {}) {
   const paddedIndex = String(index + 1).padStart(2, "0");
-  const title = pageHtml.match(/data-page-title="([^"]*)"/)?.[1] ?? `${titleFallback} ${index + 1}`;
+  const title =
+    pageHtml.match(/data-page-title="([^"]*)"/)?.[1] ??
+    pageHtml.match(/data-openpress-frame-key="([^"]*)"/)?.[1] ??
+    `${titleFallback} ${index + 1}`;
   const anchor = pageHtml.match(/\bid="([^"]+)"/)?.[1] ?? `${anchorPrefix}-${paddedIndex}`;
   return {
     id: `${idPrefix}-${paddedIndex}`,

package/engine/output/public-assets.mjs

@@ -1,19 +1,54 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { loadConfig } from "../runtime/config.mjs";
-import { copyDirectory, writeComponentsCss, writeContentCss } from "../runtime/file-utils.mjs";
+import { writeComponentsCss, writeContentCss } from "../runtime/file-utils.mjs";
 import { copyThemeFonts } from "./fonts.mjs";
 import { copyKatexFonts } from "./katex-assets.mjs";
 
-export async function syncPublicAssets(root, publicOutputDir, config) {
+export async function syncPublicAssets(root, publicOutputDir, config, options = {}) {
   config ??= await loadConfig(root);
   await fs.rm(path.join(publicOutputDir, "report.css"), { force: true });
   for (const name of ["tokens.css"]) {
-    await fs.copyFile(path.join(config.paths.themeDir, name), path.join(publicOutputDir, name));
+    await copyOptionalFile(path.join(config.paths.themeDir, name), path.join(publicOutputDir, name));
   }
-  await writeContentCss(root, publicOutputDir, config);
+  await writeContentCss(root, publicOutputDir, config, { themeRoots: options.themeRoots });
   await copyThemeFonts(root, publicOutputDir, config);
   await copyKatexFonts(publicOutputDir);
-  await writeComponentsCss(root, publicOutputDir, config);
-  await copyDirectory(config.paths.mediaDir, path.join(publicOutputDir, "media"));
+  await writeComponentsCss(root, publicOutputDir, config, { componentRoots: options.componentRoots });
+  await copyMediaRoots(options.mediaRoots ?? [config.paths.mediaDir], path.join(publicOutputDir, "media"));
+}
+
+async function copyOptionalFile(src, dst) {
+  try {
+    await fs.copyFile(src, dst);
+  } catch (error) {
+    if (error?.code === "ENOENT") return;
+    throw error;
+  }
+}
+
+async function copyMediaRoots(mediaRoots, dst) {
+  await fs.rm(dst, { recursive: true, force: true });
+  await fs.mkdir(dst, { recursive: true });
+  for (const mediaRoot of uniquePaths(mediaRoots)) {
+    try {
+      await fs.cp(mediaRoot, dst, { recursive: true, force: true });
+    } catch (error) {
+      if (error?.code === "ENOENT") continue;
+      throw error;
+    }
+  }
+}
+
+function uniquePaths(paths) {
+  const out = [];
+  const seen = new Set();
+  for (const candidate of paths ?? []) {
+    if (!candidate) continue;
+    const normalized = path.resolve(candidate);
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    out.push(normalized);
+  }
+  return out;
 }

package/engine/output/static-server.mjs

@@ -84,7 +84,7 @@ const server = http.createServer(async (req, res) => {
       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
+      // SPA HTML response: 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.
@@ -181,9 +181,9 @@ function valueAfter(args, flag) {
 
 async function inferWorkspaceRoot(staticRoot) {
   for (const candidate of [staticRoot, path.dirname(staticRoot), path.dirname(path.dirname(staticRoot))]) {
-    // 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;
+    // Workspace markers: folder-convention Press entries or package.json
+    // with an "openpress" field. Either is sufficient.
+    if (await hasFolderPressEntries(candidate)) return candidate;
     if (await hasOpenpressPackageField(candidate)) return candidate;
   }
   if (path.basename(path.dirname(staticRoot)) === ".deploy") {
@@ -202,6 +202,20 @@ async function hasOpenpressPackageField(dir) {
   }
 }
 
+async function hasFolderPressEntries(dir) {
+  let entries;
+  try {
+    entries = await fs.readdir(path.join(dir, "press"), { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "shared") continue;
+    if (await fileExists(path.join(dir, "press", entry.name, "press.tsx"))) return true;
+  }
+  return false;
+}
+
 async function handleLocalPdfExportRequest(req, res) {
   if (req.method !== "POST") {
     writeJson(res, 405, { ok: false, message: "Local PDF export endpoint requires POST." });
@@ -377,14 +391,12 @@ async function handleMediaFileRequest(req, res, url) {
       writeJson(res, 404, { ok: false, message: "Media file not found." });
       return;
     }
-    const targetPath = path.join(config.paths.mediaDir, fileName);
-    const resolvedTarget = path.resolve(targetPath);
-    const mediaRoot = path.resolve(config.paths.mediaDir);
-    if (!resolvedTarget.startsWith(`${mediaRoot}${path.sep}`) && resolvedTarget !== mediaRoot) {
-      writeJson(res, 403, { ok: false, message: "Forbidden." });
+    const mediaPath = await findMediaFile(fileName);
+    if (!mediaPath) {
+      writeJson(res, 404, { ok: false, message: "Media file not found." });
       return;
     }
-    const body = await fs.readFile(resolvedTarget);
+    const body = await fs.readFile(mediaPath);
     res.writeHead(200, {
       "Content-Type": mediaMimeType(fileName),
       "Cache-Control": "no-store",
@@ -517,11 +529,7 @@ async function isDeploymentDirty(deployedAt) {
 
 function getDeploymentSourcePaths() {
   return [
-    config.paths.sourceDir,
-    config.paths.mediaDir,
-    config.paths.themeDir,
-    config.paths.designDoc,
-    config.paths.componentsDir,
+    config.paths.documentRoot,
     path.join(FRAMEWORK_ROOT, "src"),
     path.join(FRAMEWORK_ROOT, "index.html"),
     path.join(FRAMEWORK_ROOT, "vite.config.ts"),
@@ -597,6 +605,51 @@ async function uniqueMediaFileName(mediaDir, fileName) {
   return candidate;
 }
 
+async function findMediaFile(fileName) {
+  for (const mediaRoot of await collectMediaRoots()) {
+    const resolvedRoot = path.resolve(mediaRoot);
+    const candidate = path.resolve(mediaRoot, fileName);
+    if (!isInsideRoot(candidate, resolvedRoot)) continue;
+    if (await fileExists(candidate)) return candidate;
+  }
+  return null;
+}
+
+async function collectMediaRoots() {
+  const roots = [
+    config.paths.mediaDir,
+    path.join(config.paths.publicDir, "media"),
+    path.join(root, "openpress", "media"),
+  ];
+  try {
+    const entries = await fs.readdir(config.paths.documentRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "shared") continue;
+      roots.push(path.join(config.paths.documentRoot, entry.name, "media"));
+    }
+  } catch {
+    // Missing press/ is handled by render/validate.
+  }
+  return uniquePaths(roots);
+}
+
+function uniquePaths(paths) {
+  const out = [];
+  const seen = new Set();
+  for (const candidate of paths) {
+    const normalized = path.resolve(candidate);
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    out.push(normalized);
+  }
+  return out;
+}
+
+function isInsideRoot(candidate, rootDir) {
+  const relative = path.relative(rootDir, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
 function readRequestBuffer(req, maxBytes) {
   return new Promise((resolve, reject) => {
     const chunks = [];

package/engine/react/caption-numbering.mjs

@@ -64,8 +64,8 @@ function attrValue(attrs, name) {
   return attrs.match(pattern)?.[2] ?? "";
 }
 
-function stringOption(value, fallback) {
-  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+function stringOption(value, defaultValue) {
+  return typeof value === "string" && value.trim() ? value.trim() : defaultValue;
 }
 
 function escapeHtml(value) {

package/engine/react/comment-marker.mjs

@@ -6,8 +6,7 @@ import { collectSourceTextFiles } from "../runtime/source-text-tools.mjs";
 
 // 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 `press/chapters/<slug>/content/*.mdx`. The boundary
+// `section-files`, `file-list`, custom `root` paths, etc. 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 = [

package/engine/react/document-entry.mjs

@@ -1,9 +1,8 @@
 // Layer 1 — Document entry loader.
 //
-// Loads `press/index.tsx`, validates it exports a Press component as
-// default, reads optional `config` and `sources` named exports, and sets
-// up the vite SSR server with `@open-press/core` aliases (including the
-// subpaths `/mdx` and `/manuscript`).
+// Discovers `press/*/press.tsx`, generates an internal Workspace entry,
+// and sets up the vite SSR server with `@open-press/core` aliases
+// (including the subpaths `/mdx` and `/manuscript`).
 
 import fs from "node:fs/promises";
 import { createRequire } from "node:module";
@@ -26,11 +25,61 @@ const REACT_PACKAGE_ROOT = path.join(FRAMEWORK_ROOT, "node_modules", "react");
 const require = createRequire(import.meta.url);
 const REACT_EXPORT_NAMES = Object.keys(require("react")).filter((name) => /^[A-Za-z_$][\w$]*$/.test(name));
 
-// 1.0 contract: the document entry lives at press/index.tsx.
 async function resolveEntryPath(workspaceRoot) {
-  const candidate = path.join(workspaceRoot, "press", "index.tsx");
-  if (await fileExists(candidate)) return candidate;
-  return null;
+  return createDiscoveredPressEntry(workspaceRoot);
+}
+
+async function createDiscoveredPressEntry(workspaceRoot) {
+  const pressRoot = path.join(workspaceRoot, "press");
+  let entries = [];
+  try {
+    const children = await fs.readdir(pressRoot, { withFileTypes: true });
+    for (const child of children) {
+      if (!child.isDirectory()) continue;
+      if (child.name === "shared" || child.name.startsWith(".")) continue;
+      const entryPath = path.join(pressRoot, child.name, "press.tsx");
+      if (await fileExists(entryPath)) entries.push({ folder: child.name, entryPath });
+    }
+  } catch {
+    return null;
+  }
+
+  entries = entries.sort((a, b) => a.folder.localeCompare(b.folder));
+  if (entries.length === 0) return null;
+
+  for (const entry of entries) {
+    const source = await fs.readFile(entry.entryPath, "utf8");
+    assertNoObviousTopLevelSideEffects(source, entry.entryPath);
+  }
+
+  const generatedDir = path.join(workspaceRoot, ".openpress", "react");
+  await fs.mkdir(generatedDir, { recursive: true });
+  const generatedEntry = path.join(generatedDir, "discovered-press-entry.tsx");
+  const imports = entries
+    .map((entry, index) => `import Press${index} from "${relativeImportPath(generatedDir, entry.entryPath)}";`)
+    .join("\n");
+  const children = entries.map((_, index) => `      <Press${index} />`).join("\n");
+  const source = `import { Workspace } from "@open-press/core";
+${imports}
+
+export const __openpressPressFolders = ${JSON.stringify(entries.map((entry) => entry.folder))};
+
+export default function DiscoveredOpenPressWorkspace() {
+  return (
+    <Workspace>
+${children}
+    </Workspace>
+  );
+}
+`;
+  await fs.writeFile(generatedEntry, source, "utf8");
+  return generatedEntry;
+}
+
+function relativeImportPath(fromDir, toFile) {
+  let relative = path.relative(fromDir, toFile).replaceAll(path.sep, "/");
+  if (!relative.startsWith(".")) relative = `./${relative}`;
+  return relative;
 }
 
 export async function loadReactDocumentEntry(root = ".", { server: externalServer } = {}) {
@@ -82,6 +131,9 @@ export async function loadReactDocumentEntry(root = ".", { server: externalServe
       workspaceProps: inspection.workspaceProps,
       pressCount: inspection.presses.length,
       wrappedInWorkspace: inspection.wrappedInWorkspace,
+      pressFolders: Array.isArray(mod.__openpressPressFolders)
+        ? mod.__openpressPressFolders.filter((item) => typeof item === "string")
+        : [],
     };
   } finally {
     if (!externalServer) await ownServer.close();
@@ -112,7 +164,7 @@ export async function createReactSsrServer(workspaceRoot = ".") {
         { find: "@open-press/core/manuscript", replacement: MANUSCRIPT_ENTRY },
         { find: "@open-press/core/numbering", replacement: NUMBERING_ENTRY },
         { find: "@open-press/core", replacement: CORE_ENTRY },
-        { find: "@/components", replacement: path.join(resolvedWorkspaceRoot, "press", "components") },
+        { find: "@/components", replacement: path.join(resolvedWorkspaceRoot, "press", "shared", "components") },
       ],
     },
     optimizeDeps: {
@@ -159,10 +211,11 @@ function assertNoObviousTopLevelSideEffects(source, entryPath) {
 }
 
 function assertPureImport(statement, entryPath) {
+  const moduleName = stringLiteralText(statement.moduleSpecifier);
   if (!statement.importClause) {
+    if (typeof moduleName === "string" && moduleName.endsWith(".css")) return;
     throw new Error(`OpenPress document entry has an unsupported side-effect import in ${entryPath}`);
   }
-  const moduleName = stringLiteralText(statement.moduleSpecifier);
   if (!statement.importClause.isTypeOnly && isFileSystemModule(moduleName)) {
     throw new Error(`OpenPress document entry imports filesystem APIs at top level in ${entryPath}`);
   }
@@ -179,7 +232,7 @@ function assertTopLevelVariableStatement(statement, entryPath) {
       throw new Error(`OpenPress document entry only allows identifier const declarations at top level in ${entryPath}`);
     }
     const name = declaration.name.text;
-    if (exported && name !== "config" && name !== "sources") {
+    if (exported && name !== "config" && name !== "sources" && name !== "__openpressPressFolders") {
       throw new Error(`OpenPress document entry only allows exported const config and sources in ${entryPath}`);
     }
     if (!declaration.initializer) {

package/engine/react/document-export.d.mts

@@ -0,0 +1,6 @@
+export function exportReactDocument(
+  root?: string,
+  options?: {
+    syncAssets?: boolean;
+  },
+): Promise<unknown>;