@open-press/core 0.7.1 → 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/file-walk.mjs

@@ -0,0 +1,22 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function walkFiles(directory, visit) {
+  let entries;
+  try {
+    entries = await fs.readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return;
+    throw error;
+  }
+
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    const absolutePath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      await walkFiles(absolutePath, visit);
+    } else if (entry.isFile()) {
+      await visit(absolutePath);
+    }
+  }
+}

package/engine/runtime/inspection.mjs

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { evaluateUrlWithChrome, stopChildProcess } from "../output/chrome-pdf.mjs";
 import { buildReactStatic, startStaticServer } from "../commands/_shared.mjs";
+import { walkFiles } from "./file-walk.mjs";
 import { createIssue, createIssueReport } from "./issue-report.mjs";
 import { collectActiveContentFiles, resolveActiveSourceWorkspace } from "./source-workspace.mjs";
 
@@ -217,26 +218,6 @@ async function readMediaFiles(directory) {
   return files;
 }
 
-async function walkFiles(directory, visit) {
-  let entries;
-  try {
-    entries = await fs.readdir(directory, { withFileTypes: true });
-  } catch (error) {
-    if (error?.code === "ENOENT") return;
-    throw error;
-  }
-
-  for (const entry of entries) {
-    if (entry.name.startsWith(".")) continue;
-    const absolutePath = path.join(directory, entry.name);
-    if (entry.isDirectory()) {
-      await walkFiles(absolutePath, visit);
-    } else if (entry.isFile()) {
-      await visit(absolutePath);
-    }
-  }
-}
-
 function summarizeComponentUsage(contentFiles) {
   const usages = new Map();
   for (const file of contentFiles) {

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/path-utils.mjs

@@ -0,0 +1,20 @@
+import path from "node:path";
+
+export function rootRelativePath(config, absolutePath) {
+  return path.relative(config.root, absolutePath).replaceAll("\\", "/");
+}
+
+export function documentRelativePath(absolutePath, documentRoot) {
+  return path.relative(documentRoot, absolutePath).split(path.sep).join("/");
+}
+
+export function resolveDocumentRelativePath(documentRoot, rel, label) {
+  if (typeof rel !== "string" || !rel.trim()) throw new Error(`${label} must be a non-empty document-relative path.`);
+  if (rel.includes("..")) throw new Error(`${label} contains "..", rejected.`);
+  const absolutePath = path.resolve(documentRoot, rel);
+  const relCheck = path.relative(documentRoot, absolutePath);
+  if (relCheck.startsWith("..") || path.isAbsolute(relCheck)) {
+    throw new Error(`${label} escapes the document root.`);
+  }
+  return absolutePath;
+}

package/engine/runtime/source-text-tools.d.mts

@@ -0,0 +1,102 @@
+import type { ResolvedConfig } from "./config.mjs";
+
+export type SourceTextScope = "content" | "all";
+
+export type SourceTextMatch = {
+  id: string;
+  scope: string;
+  file: string;
+  path: string;
+  line: number;
+  column: number;
+  index: number;
+  text: string;
+  preview: string;
+};
+
+export type SourceTextFileSummary = {
+  scope: string;
+  file: string;
+  path: string;
+  matchCount: number;
+};
+
+export type SourceSearchReport = {
+  kind: "search";
+  query: string;
+  scope: SourceTextScope;
+  caseSensitive: boolean;
+  matchCount: number;
+  files: Array<SourceTextFileSummary>;
+  matches: Array<SourceTextMatch>;
+};
+
+export type SourceBlockTextEditInput = {
+  config: ResolvedConfig;
+  path: string;
+  source: {
+    line: number;
+    column?: number;
+    endLine?: number;
+    endColumn?: number;
+  };
+  text: string;
+  kind?: string;
+  name?: string;
+  blockId?: string;
+  cellIndex?: number;
+  sourceMode?: boolean;
+};
+
+export type SourceBlockTextEdit = {
+  blockId?: string;
+  path: string;
+  requestedPath: string;
+  file: string;
+  line: number;
+  column: number;
+  endLine: number;
+  endColumn: number;
+  before: string;
+  after: string;
+  text: string;
+  cellIndex?: number;
+};
+
+export function searchSourceText(options: {
+  config: ResolvedConfig;
+  query: string;
+  scope?: SourceTextScope;
+  caseSensitive?: boolean;
+}): Promise<SourceSearchReport>;
+
+export function applySourceBlockTextEdit(options: SourceBlockTextEditInput): Promise<SourceBlockTextEdit>;
+
+export function applySourceBlockTextEditToText(documentText: string, options: Omit<SourceBlockTextEditInput, "config" | "path">): {
+  text: string;
+  edit: Omit<SourceBlockTextEdit, "path" | "requestedPath" | "file">;
+};
+
+export function readSourceBlockText(options: Pick<SourceBlockTextEditInput, "config" | "path" | "source">): Promise<{
+  path: string;
+  requestedPath: string;
+  file: string;
+  text: string;
+}>;
+
+export function readSourceBlockTextFromText(documentText: string, options: Pick<SourceBlockTextEditInput, "source">): string;
+
+export function applySourceBlockSourceEditToText(documentText: string, options: Pick<SourceBlockTextEditInput, "source" | "text" | "blockId">): {
+  text: string;
+  edit: Omit<SourceBlockTextEdit, "path" | "requestedPath" | "file">;
+};
+
+export function collectSourceTextFiles(config: ResolvedConfig, options?: {
+  scope?: SourceTextScope;
+}): Promise<Array<{
+  scope: string;
+  name: string;
+  absolutePath: string;
+  relativePath: string;
+  text: string;
+}>>;