@open-press/core 0.8.0 → 1.0.0

package/engine/runtime/config.mjs

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { normalizePageGeometry } from "./page-geometry.mjs";
 
 const DEFAULT_CONFIG = {
   title: "OpenPress Document",
@@ -30,33 +30,72 @@ const DEFAULT_CONFIG = {
     commitDirty: false,
     requiresConfirmation: true,
   },
+  page: null,
 };
 
+// 1.0 contract: the only user-writable config lives in package.json
+// under the "openpress" field. The engine reads it synchronously so
+// the deploy command can resolve its adapter before any React render.
+//
+// Everything else is convention (path layout) or declared on
+// <Press> / <Workspace> JSX props (document metadata).
 export async function loadConfig(root = ".") {
   const workspaceRoot = path.resolve(root);
-  const configPath = path.join(workspaceRoot, "openpress.config.mjs");
-  const rootConfig = await readUserConfig(configPath);
-  const { config, sourceConfigPath } = await resolveUserConfig(workspaceRoot, rootConfig, configPath);
-  return normalizeConfig(workspaceRoot, config, sourceConfigPath);
+  const packageOpenpress = await readPackageOpenpressField(workspaceRoot);
+  return normalizeConfig(workspaceRoot, packageOpenpress ?? {});
 }
 
-export function normalizeConfig(root, userConfig = {}, configPath = path.join(root, "openpress.config.mjs")) {
+async function readPackageOpenpressField(workspaceRoot) {
+  const pkgPath = path.join(workspaceRoot, "package.json");
+  try {
+    const raw = await fs.readFile(pkgPath, "utf8");
+    const parsed = JSON.parse(raw);
+    const field = parsed?.openpress;
+    return (field && typeof field === "object" && !Array.isArray(field)) ? field : null;
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    if (error instanceof SyntaxError) {
+      throw new Error(`Malformed package.json at ${pkgPath}: ${error.message}`);
+    }
+    throw error;
+  }
+}
+
+// Convention-only fields. The user can't override these — they're part
+// of OpenPress's product surface. If you don't like the layout, your
+// project isn't an OpenPress workspace.
+const CONVENTION = {
+  documentDir: "press",
+  sourceDir: "chapters",
+  mediaDir: "media",
+  themeDir: "theme",
+  componentsDir: "components",
+  designDoc: "design.md",
+  publicDir: "public/openpress",
+  outputDir: "dist-react",
+};
+
+export function normalizeConfig(root, userConfig = {}, configPath = path.join(root, "package.json")) {
   const config = {
     root: path.resolve(root),
     configPath,
-    title: stringValue(userConfig.title, DEFAULT_CONFIG.title),
-    subtitle: optionalStringValue(userConfig.subtitle, DEFAULT_CONFIG.subtitle) ?? "",
-    organization: optionalStringValue(userConfig.organization, DEFAULT_CONFIG.organization) ?? "",
-    workspaceLabel: optionalStringValue(userConfig.workspaceLabel, DEFAULT_CONFIG.workspaceLabel) ?? "",
-    documentDir: documentPathValue(userConfig.documentDir, DEFAULT_CONFIG.documentDir),
-    sourceDir: relativePathValue(userConfig.sourceDir, DEFAULT_CONFIG.sourceDir),
-    mediaDir: relativePathValue(userConfig.mediaDir, DEFAULT_CONFIG.mediaDir),
-    themeDir: relativePathValue(userConfig.themeDir, DEFAULT_CONFIG.themeDir),
-    designDoc: relativePathValue(userConfig.designDoc, DEFAULT_CONFIG.designDoc),
-    componentsDir: relativePathValue(userConfig.componentsDir, DEFAULT_CONFIG.componentsDir),
-    publicDir: relativePathValue(userConfig.publicDir, DEFAULT_CONFIG.publicDir),
-    outputDir: relativePathValue(userConfig.outputDir, DEFAULT_CONFIG.outputDir),
+    // Document metadata defaults — actual values are merged in by
+    // loadReactDocumentEntry from <Press> / <Workspace> JSX props.
+    title: DEFAULT_CONFIG.title,
+    subtitle: "",
+    organization: "",
+    workspaceLabel: "",
+    // Paths — fixed conventions, not user-configurable.
+    documentDir: CONVENTION.documentDir,
+    sourceDir: CONVENTION.sourceDir,
+    mediaDir: CONVENTION.mediaDir,
+    themeDir: CONVENTION.themeDir,
+    designDoc: CONVENTION.designDoc,
+    componentsDir: CONVENTION.componentsDir,
+    publicDir: CONVENTION.publicDir,
+    outputDir: CONVENTION.outputDir,
     captionNumbering: captionNumberingValue(userConfig.captionNumbering, DEFAULT_CONFIG.captionNumbering),
+    page: normalizePageGeometry(userConfig.page ?? DEFAULT_CONFIG.page),
     pdf: {
       filename: fileNameValue(userConfig.pdf?.filename, DEFAULT_CONFIG.pdf.filename),
     },
@@ -91,32 +130,6 @@ export function publicPdfHref(config) {
   return `/${config.pdf.filename}`;
 }
 
-async function readUserConfig(configPath) {
-  try {
-    const stat = await fs.stat(configPath);
-    const configUrl = `${pathToFileURL(configPath).href}?mtime=${stat.mtimeMs}`;
-    const mod = await import(configUrl);
-    return mod.default ?? {};
-  } catch (error) {
-    if (error?.code === "ENOENT") return {};
-    throw error;
-  }
-}
-
-async function resolveUserConfig(root, rootConfig, configPath) {
-  const documentConfigPath = configPathValue(rootConfig.config ?? rootConfig.documentConfig);
-  if (!documentConfigPath) {
-    return { config: rootConfig, sourceConfigPath: configPath };
-  }
-
-  const sourceConfigPath = path.resolve(root, documentConfigPath);
-  const documentConfig = await readUserConfig(sourceConfigPath);
-  return {
-    config: { ...documentConfig, ...rootConfig },
-    sourceConfigPath,
-  };
-}
-
 function stringValue(value, fallback) {
   return typeof value === "string" && value.trim() ? value.trim() : fallback;
 }
@@ -148,22 +161,6 @@ function fileNameValue(value, fallback) {
   return fileName;
 }
 
-function configPathValue(value) {
-  if (typeof value !== "string" || !value.trim()) return null;
-  return relativePathValue(value, null);
-}
-
-function documentPathValue(value, fallback) {
-  const raw = stringValue(value, fallback).replaceAll("\\", "/");
-  if (path.isAbsolute(raw)) throw new Error(`OpenPress config paths must be relative, got: ${raw}`);
-  const normalized = path.posix.normalize(raw).replace(/^\.\//, "");
-  if (normalized === ".") return ".";
-  if (!normalized || normalized === ".." || normalized.startsWith("../")) {
-    throw new Error(`OpenPress config path escapes workspace: ${raw}`);
-  }
-  return normalized;
-}
-
 function relativePathValue(value, fallback) {
   const raw = stringValue(value, fallback).replaceAll("\\", "/");
   if (path.isAbsolute(raw)) throw new Error(`OpenPress config paths must be relative, got: ${raw}`);

package/engine/runtime/file-utils.mjs

@@ -10,6 +10,7 @@ const CONTENT_CSS_LAYERS = [
   { path: "page-surfaces/chapter-opener.css", optional: true },
   "page-surfaces/back-cover.css",
   "page-surfaces/toc.css",
+  { path: "page-surfaces", type: "directory", exclude: ["cover.css", "chapter-opener.css", "back-cover.css", "toc.css"] },
   "shell/reader-controls.css",
   "base/print.css",
 ];
@@ -32,6 +33,12 @@ export async function buildContentCss(root, config) {
   const contentAssetsDir = config.paths.themeDir;
   const parts = [];
   for (const layer of CONTENT_CSS_LAYERS) {
+    if (typeof layer !== "string" && layer.type === "directory") {
+      await appendCssDirectory(parts, path.join(contentAssetsDir, layer.path), layer.path, {
+        exclude: new Set(layer.exclude ?? []),
+      });
+      continue;
+    }
     const relativePath = typeof layer === "string" ? layer : layer.path;
     const cssPath = path.join(contentAssetsDir, relativePath);
     let css;
@@ -66,7 +73,7 @@ export async function buildComponentsCss(root, config) {
   return parts.join("");
 }
 
-async function appendCssDirectory(parts, directory, labelPrefix) {
+async function appendCssDirectory(parts, directory, labelPrefix, options = {}) {
   let entries;
   try {
     entries = await fs.readdir(directory);
@@ -74,6 +81,7 @@ async function appendCssDirectory(parts, directory, labelPrefix) {
     return;
   }
   for (const name of entries.filter((entry) => entry.endsWith(".css")).sort()) {
+    if (options.exclude?.has(name)) continue;
     parts.push(`/* === ${labelPrefix}/${name} === */\n`);
     parts.push((await fs.readFile(path.join(directory, name), "utf8")).trimEnd());
     parts.push("\n\n");

package/engine/runtime/page-geometry.mjs

@@ -0,0 +1,131 @@
+const CSS_LENGTH_RE = /^(\d+(?:\.\d+)?)(px|mm|cm|in|pt|pc)$/i;
+
+export const PAGE_GEOMETRY_PRESETS = {
+  a4: {
+    id: "a4",
+    label: "A4 Page",
+    width: "210mm",
+    height: "297mm",
+  },
+  "social-square": {
+    id: "social-square",
+    label: "Social Square",
+    width: "1080px",
+    height: "1080px",
+  },
+  "slide-16-9": {
+    id: "slide-16-9",
+    label: "Slide 16:9",
+    width: "1920px",
+    height: "1080px",
+  },
+};
+
+export function normalizePageGeometry(value) {
+  if (value == null || value === false) return null;
+
+  if (typeof value === "string") {
+    return presetPageGeometry(value);
+  }
+
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("OpenPress config page must be a preset name or an object.");
+  }
+
+  const preset = typeof value.preset === "string" ? presetPageGeometry(value.preset) : null;
+  const width = cssLengthValue(value.width, preset?.width);
+  const height = cssLengthValue(value.height, preset?.height);
+  if (!width || !height) {
+    throw new Error("OpenPress config page requires width and height when no preset is provided.");
+  }
+
+  const id = optionalId(value.id, preset?.id ?? "custom");
+  const label = optionalLabel(value.label, preset?.label ?? "Custom Page");
+
+  return pageGeometry({
+    id,
+    label,
+    width,
+    height,
+  });
+}
+
+export function pageGeometryToTheme(page) {
+  if (!page) return undefined;
+  return {
+    pagePreset: page.id,
+    pageLabel: page.label,
+    pageWidth: page.width,
+    pageHeight: page.height,
+    pageAspectRatio: page.aspectRatio,
+    pageHeightRatio: page.heightRatio,
+  };
+}
+
+function presetPageGeometry(id) {
+  const preset = PAGE_GEOMETRY_PRESETS[id];
+  if (!preset) {
+    throw new Error(
+      `Unknown OpenPress page preset: "${id}". ` +
+        `Available presets: ${Object.keys(PAGE_GEOMETRY_PRESETS).join(", ")}.`,
+    );
+  }
+  return pageGeometry(preset);
+}
+
+function pageGeometry({ id, label, width, height }) {
+  const ratio = sameUnitRatio(width, height);
+  return {
+    id,
+    label,
+    width,
+    height,
+    aspectRatio: ratio ? `${trimNumber(ratio.width)} / ${trimNumber(ratio.height)}` : undefined,
+    heightRatio: ratio ? trimNumber(ratio.height / ratio.width) : undefined,
+  };
+}
+
+function cssLengthValue(value, fallback) {
+  if (value == null) return fallback ?? null;
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error("OpenPress page width/height must be CSS length strings.");
+  }
+  const trimmed = value.trim();
+  if (!CSS_LENGTH_RE.test(trimmed)) {
+    throw new Error(`OpenPress page size must be an absolute CSS length, got: ${trimmed}`);
+  }
+  return trimmed;
+}
+
+function optionalId(value, fallback) {
+  if (value == null) return fallback;
+  if (typeof value !== "string" || !/^[a-z0-9][a-z0-9-]*$/i.test(value)) {
+    throw new Error("OpenPress page id must be a simple slug.");
+  }
+  return value;
+}
+
+function optionalLabel(value, fallback) {
+  if (value == null) return fallback;
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error("OpenPress page label must be a non-empty string.");
+  }
+  return value.trim();
+}
+
+function sameUnitRatio(width, height) {
+  const w = parseCssLength(width);
+  const h = parseCssLength(height);
+  if (!w || !h || w.unit.toLowerCase() !== h.unit.toLowerCase()) return null;
+  return { width: w.value, height: h.value };
+}
+
+function parseCssLength(value) {
+  const match = CSS_LENGTH_RE.exec(value);
+  if (!match) return null;
+  return { value: Number(match[1]), unit: match[2] };
+}
+
+function trimNumber(value) {
+  return Number(value.toFixed(6)).toString();
+}

package/engine/runtime/source-text-tools.mjs

@@ -824,7 +824,7 @@ function normalizeSourceTextPath(value) {
   return String(value ?? "")
     .replaceAll("\\", "/")
     .replace(/^\.\//, "")
-    .replace(/^document\//, "");
+    .replace(/^press\//, "");
 }
 
 function stringValue(value) {

package/engine/runtime/source-workspace.mjs

@@ -12,10 +12,19 @@ export async function resolveActiveSourceWorkspace(config) {
   const reactEntry = await loadReactDocumentEntry(config.root);
   if (!reactEntry) {
     throw new Error(
-      "React/MDX document entry not found. Expected document/index.tsx with a Press default export before using workspace source tools.",
+      "React/MDX document entry not found. Expected press/index.tsx with a Press default export before using workspace source tools.",
     );
   }
-  const contentRoots = contentRootsFromSources(reactEntry.sources, reactEntry.config);
+  // Aggregate sources across every Press in the Workspace. Workspace
+  // tooling (validate, search, replace, inspect) walks the union — a
+  // multi-Press project's sources all live under the same press/ tree.
+  const aggregateSources = {};
+  for (const press of reactEntry.presses ?? []) {
+    if (press.sources && typeof press.sources === "object") {
+      Object.assign(aggregateSources, press.sources);
+    }
+  }
+  const contentRoots = contentRootsFromSources(aggregateSources, reactEntry.config);
   const sourceDir = firstDirectoryRoot(contentRoots) ?? reactEntry.config.paths.documentRoot;
 
   return {
@@ -29,7 +38,7 @@ export async function resolveActiveSourceWorkspace(config) {
     contentLabel: "React MDX chapter source",
     missingCode: "react-source.missing",
     emptyCode: "react-source.empty",
-    missingMessage: "Registered React MDX sources do not exist yet; create the files or roots declared in document/index.tsx `sources` before running export.",
+    missingMessage: "Registered React MDX sources do not exist yet; create the files or roots declared in press/index.tsx `sources` before running export.",
     emptyMessage: "Registered React MDX sources contain no `*.mdx` files; the document will export with zero source blocks.",
   };
 }

package/engine/runtime/validation.mjs

@@ -17,6 +17,20 @@ const PUBLIC_DEPLOY_ADAPTERS = new Set([
   "vercel",
 ]);
 
+// A directory is an OpenPress workspace if it contains a
+// press/index.tsx entry, or a package.json with an "openpress" field.
+async function isWorkspaceRoot(dir) {
+  try {
+    await fs.access(path.join(dir, "press", "index.tsx"));
+    return true;
+  } catch {}
+  try {
+    const pkg = JSON.parse(await fs.readFile(path.join(dir, "package.json"), "utf8"));
+    if (pkg?.openpress && typeof pkg.openpress === "object") return true;
+  } catch {}
+  return false;
+}
+
 export async function discoverWorkspace(startPath = ".") {
   let current = path.resolve(startPath);
   try {
@@ -26,15 +40,10 @@ export async function discoverWorkspace(startPath = ".") {
     current = path.dirname(current);
   }
   while (true) {
-    const configPath = path.join(current, "openpress.config.mjs");
-    try {
-      await fs.access(configPath);
-      return current;
-    } catch {
-      const parent = path.dirname(current);
-      if (parent === current) throw new Error(`No OpenPress workspace found from ${startPath}`);
-      current = parent;
-    }
+    if (await isWorkspaceRoot(current)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) throw new Error(`No OpenPress workspace found from ${startPath}`);
+    current = parent;
   }
 }
 
@@ -78,7 +87,7 @@ export async function validateWorkspace(root) {
 
   mark(sourceWorkspace.checkedName);
   if (!(typeof activeConfig.title === "string" && activeConfig.title.trim())) {
-    add("warning", "config.title", "openpress.config.mjs `title` is empty; the workbench will show the default placeholder.", activeConfig.configPath);
+    add("warning", "press.title", "<Press title> is missing in press/index.tsx; the workbench will show the default placeholder.", activeConfig.configPath);
   }
   if (!(await sourceDirectoryExists(sourceWorkspace))) {
     add("warning", sourceWorkspace.missingCode, sourceWorkspace.missingMessage, sourceWorkspace.sourceDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-press/core",
-  "version": "0.8.0",
+  "version": "1.0.0",
   "type": "module",
   "description": "open-press core — runtime primitives, CLI, and render pipeline for AI-first fixed-layout documents.",
   "license": "MIT",
@@ -48,6 +48,7 @@
   "dependencies": {
     "@mdx-js/mdx": "^3.1.1",
     "@mdx-js/react": "^3.1.1",
+    "html-to-image": "^1.11.13",
     "js-yaml": "^4.1.1",
     "katex": "^0.16.47",
     "lucide-react": "^1.16.0",
@@ -80,11 +81,8 @@
     "test:e2e:reader": "playwright test --config playwright.reader.config.ts",
     "test:node": "node --test tests/*.test.mjs",
     "test:react": "vitest run",
-    "openpress:validate": "node engine/cli.mjs validate .",
-    "openpress:export": "node engine/cli.mjs export .",
+    "openpress:image": "node engine/cli.mjs image .",
     "openpress:pdf": "node engine/cli.mjs pdf .",
-    "openpress:render": "node engine/cli.mjs render . --renderer react",
-    "openpress:preview": "node engine/cli.mjs preview . --renderer react",
     "openpress:deploy": "node engine/cli.mjs deploy .",
     "openpress:deploy:dry-run": "node engine/cli.mjs deploy . --confirm --dry-run"
   }