@open-press/core 0.7.1 → 1.0.0

package/engine/output/static-server.mjs

@@ -3,7 +3,9 @@ import http from "node:http";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { loadConfig, publicPdfHref } from "../runtime/config.mjs";
+import { searchSourceText } from "../runtime/source-text-tools.mjs";
 import { handleProjectAssetRequest } from "../react/project-asset-endpoint.mjs";
+import { handleSourceEditRequest } from "../react/source-edit-endpoint.mjs";
 
 const [rootArg = "dist", ...rest] = process.argv.slice(2);
 const host = valueAfter(rest, "--host") ?? "127.0.0.1";
@@ -32,6 +34,14 @@ const server = http.createServer(async (req, res) => {
       await handleStatusRequest(req, res);
       return;
     }
+    if (url.pathname === "/__openpress/search") {
+      await handleSearchRequest(req, res, url);
+      return;
+    }
+    if (url.pathname === "/__openpress/source-edit") {
+      await handleSourceEditRequest(req, res, { root: workspace });
+      return;
+    }
     if (url.pathname === "/__openpress/local-pdf-export") {
       await handleLocalPdfExportRequest(req, res);
       return;
@@ -63,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}/`);
 });
@@ -103,6 +141,35 @@ async function handleStatusRequest(req, res) {
   });
 }
 
+async function handleSearchRequest(req, res, url) {
+  if (req.method !== "GET") {
+    writeJson(res, 405, { ok: false, message: "Search endpoint requires GET." });
+    return;
+  }
+
+  const query = (url.searchParams.get("q") ?? "").trim();
+  if (!query) {
+    writeJson(res, 400, { ok: false, message: "Search query is required." });
+    return;
+  }
+
+  try {
+    const report = await searchSourceText({
+      config,
+      query,
+      scope: searchScopeFrom(url),
+      caseSensitive: url.searchParams.get("caseSensitive") === "true",
+    });
+    writeJson(res, 200, { ok: true, ...report });
+  } catch (error) {
+    writeJson(res, 500, { ok: false, message: error instanceof Error ? error.message : String(error) });
+  }
+}
+
+function searchScopeFrom(url) {
+  return url.searchParams.get("scope") === "all" ? "all" : "content";
+}
+
 function valueAfter(args, flag) {
   const index = args.indexOf(flag);
   return index >= 0 ? args[index + 1] : undefined;
@@ -110,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));
@@ -118,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." });
@@ -328,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.`;
 }
@@ -394,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-endpoint.mjs

@@ -4,8 +4,7 @@ import {
   listCommentMarkers,
   updateCommentMarker,
 } from "./comment-marker.mjs";
-
-const MAX_COMMENT_BODY_BYTES = 64 * 1024;
+import { readJsonBody, writeJson } from "./http-json.mjs";
 
 export async function handleCommentRequest(req, res, {
   root = ".",
@@ -16,17 +15,14 @@ export async function handleCommentRequest(req, res, {
     try {
       writeJson(res, 200, { ok: true, comments: await listCommentMarkers({ root }) });
     } catch (error) {
-      writeJson(res, 400, {
-        ok: false,
-        message: error instanceof Error ? error.message : String(error),
-      });
+      writeErrorJson(res, error);
     }
     return;
   }
 
   if (req.method === "DELETE") {
     try {
-      const body = await readJsonBody(req);
+      const body = await readJsonBody(req, { bodyLabel: "OpenPress comment request" });
       const result = await clearCommentMarkers({
         root,
         id: body?.id,
@@ -34,17 +30,14 @@ export async function handleCommentRequest(req, res, {
       });
       writeJson(res, 200, { ok: true, ...result });
     } catch (error) {
-      writeJson(res, 400, {
-        ok: false,
-        message: error instanceof Error ? error.message : String(error),
-      });
+      writeErrorJson(res, error);
     }
     return;
   }
 
   if (req.method === "PATCH") {
     try {
-      const body = await readJsonBody(req);
+      const body = await readJsonBody(req, { bodyLabel: "OpenPress comment request" });
       const result = await updateCommentMarker({
         root,
         id: body?.id,
@@ -64,10 +57,7 @@ export async function handleCommentRequest(req, res, {
         },
       });
     } catch (error) {
-      writeJson(res, 400, {
-        ok: false,
-        message: error instanceof Error ? error.message : String(error),
-      });
+      writeErrorJson(res, error);
     }
     return;
   }
@@ -78,7 +68,7 @@ export async function handleCommentRequest(req, res, {
   }
 
   try {
-    const body = await readJsonBody(req);
+    const body = await readJsonBody(req, { bodyLabel: "OpenPress comment request" });
     const target = body?.target ?? {};
     const result = await insertCommentMarker({
       root,
@@ -100,29 +90,13 @@ export async function handleCommentRequest(req, res, {
       },
     });
   } catch (error) {
-    writeJson(res, 400, {
-      ok: false,
-      message: error instanceof Error ? error.message : String(error),
-    });
-  }
-}
-
-async function readJsonBody(req) {
-  let body = "";
-  for await (const chunk of req) {
-    body += String(chunk);
-    if (Buffer.byteLength(body, "utf8") > MAX_COMMENT_BODY_BYTES) {
-      throw new Error("OpenPress comment request body is too large.");
-    }
-  }
-  try {
-    return JSON.parse(body || "{}");
-  } catch {
-    throw new Error("OpenPress comment request body must be valid JSON.");
+    writeErrorJson(res, error);
   }
 }
 
-function writeJson(res, status, body) {
-  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
-  res.end(`${JSON.stringify(body, null, 2)}\n`);
+function writeErrorJson(res, error) {
+  writeJson(res, 400, {
+    ok: false,
+    message: error instanceof Error ? error.message : String(error),
+  });
 }

package/engine/react/comment-marker.mjs

@@ -4,18 +4,18 @@ 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*$/;
+const COMMENT_MARKER_RE = /(?:\{\/\*|\/\*)\s*@openpress-comment\b(?<attrs>[^*]*)\*\/\}?/g;
+const COMMENT_LINE_RE = /^\s*(?:\{\/\*|\/\*)\s*@openpress-comment\b[^*]*\*\/\}?\s*$/;
 
 export async function insertCommentMarker({
   root = ".",
@@ -35,9 +35,15 @@ export async function insertCommentMarker({
   }
 
   const noteText = normalizedNote(note);
-  const marker = createCommentMarker({ id, timestamp, note: noteText, hint });
   const line = normalizeLineNumber(source?.line);
   const text = await fs.readFile(absolutePath, "utf8");
+  const marker = createCommentMarker({
+    id,
+    timestamp,
+    note: noteText,
+    hint,
+    syntax: commentMarkerSyntaxForInsert(text, line, relativePath),
+  });
   const nextText = insertLineBefore(text, line, marker);
   await fs.writeFile(absolutePath, nextText, "utf8");
 
@@ -51,9 +57,10 @@ export async function insertCommentMarker({
   };
 }
 
-export function createCommentMarker({ id = createCommentId(), timestamp = new Date().toISOString(), note, hint } = {}) {
+export function createCommentMarker({ id = createCommentId(), timestamp = new Date().toISOString(), note, hint, syntax = "jsx" } = {}) {
   const payload = { note: normalizedNote(note), ...(typeof hint === "string" && hint.trim() ? { hint: hint.trim() } : {}) };
-  return `{/* @openpress-comment id="${escapeMarkerAttribute(id)}" ts="${escapeMarkerAttribute(timestamp)}" text="${encodeCommentPayload(payload)}" */}`;
+  const body = `@openpress-comment id="${escapeMarkerAttribute(id)}" ts="${escapeMarkerAttribute(timestamp)}" text="${encodeCommentPayload(payload)}"`;
+  return syntax === "block" ? `/* ${body} */` : `{/* ${body} */}`;
 }
 
 export function decodeCommentMarkerText(marker) {
@@ -160,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/",
@@ -285,7 +292,7 @@ function replaceCommentMarkerLine(text, { id, note, hint, timestamp }) {
     if (!COMMENT_LINE_RE.test(line)) continue;
     const attrs = parseMarkerAttributes(line);
     if (attrs.id !== id) continue;
-    const marker = createCommentMarker({ id, timestamp, note, hint });
+    const marker = createCommentMarker({ id, timestamp, note, hint, syntax: commentMarkerSyntaxForLine(line) });
     lines[index] = `${line.match(/^\s*/)?.[0] ?? ""}${marker}`;
     return {
       text: `${lines.join(newline)}${hasTrailingNewline ? newline : ""}`,
@@ -311,6 +318,23 @@ function parseMarkerAttributes(value) {
   return attrs;
 }
 
+function commentMarkerSyntaxForInsert(text, line, relativePath) {
+  if (!String(relativePath).endsWith(".tsx")) return "jsx";
+  const lines = String(text ?? "").split(/\r?\n/);
+  const index = Math.min(Math.max(line - 1, 0), lines.length);
+  const priorContent = lines.slice(0, index).some((entry) => entry.trim().length > 0);
+  if (!priorContent) return "block";
+  const targetLine = lines[index] ?? "";
+  if (/^\s*(import\b|export\b|function\b|const\b|let\b|var\b|type\b|interface\b|return\b)/.test(targetLine)) {
+    return "block";
+  }
+  return "jsx";
+}
+
+function commentMarkerSyntaxForLine(line) {
+  return /^\s*\/\*/.test(line) ? "block" : "jsx";
+}
+
 function lineStartOffsets(text) {
   const starts = [0];
   for (let index = 0; index < text.length; index += 1) {

package/engine/react/document-entry.mjs

@@ -1,6 +1,6 @@
 // Layer 1 — Document entry loader.
 //
-// Loads `document/index.tsx`, validates it exports a Press component as
+// 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`).
@@ -12,7 +12,8 @@ import { fileURLToPath } from "node:url";
 import react from "@vitejs/plugin-react";
 import ts from "typescript";
 import { createServer as createViteServer } from "vite";
-import { normalizeConfig } from "../runtime/config.mjs";
+import { loadConfig } from "../runtime/config.mjs";
+import { inspectPressTree } from "./press-tree-inspection.mjs";
 
 const ENGINE_REACT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const FRAMEWORK_ROOT = path.resolve(ENGINE_REACT_DIR, "..", "..");
@@ -24,10 +25,17 @@ 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;
+}
+
 export async function loadReactDocumentEntry(root = ".", { server: externalServer } = {}) {
   const workspaceRoot = path.resolve(root);
-  const entryPath = path.join(workspaceRoot, "document", "index.tsx");
-  if (!(await fileExists(entryPath))) return null;
+  const entryPath = await resolveEntryPath(workspaceRoot);
+  if (!entryPath) return null;
 
   const source = await fs.readFile(entryPath, "utf8");
   assertNoObviousTopLevelSideEffects(source, entryPath);
@@ -44,19 +52,35 @@ export async function loadReactDocumentEntry(root = ".", { server: externalServe
     // export pipeline throws separately if it's missing when actually needed.
     const Press = typeof mod.default === "function" ? mod.default : null;
 
-    const config = normalizeReactDocumentConfig(workspaceRoot, entryPath, mod.config);
-    const sources = mod.sources ?? {};
-    if (sources && (typeof sources !== "object" || Array.isArray(sources))) {
-      throw new Error(
-        `OpenPress document entry ${entryPath} \`sources\` export must be an object literal (or omitted).`,
+    // Inspect the JSX tree returned by the user's default export to
+    // pull <Workspace> / <Press> props declared inline. The 1.0 contract
+    // treats workspaces uniformly as "array of Press children" — the
+    // single-doc case is just length 1.
+    let inspection = { workspaceProps: {}, presses: [], wrappedInWorkspace: false };
+    if (Press) {
+      const coreModule = await ownServer.ssrLoadModule(
+        path.join(FRAMEWORK_ROOT, "src", "openpress", "core", "index.tsx"),
       );
+      inspection = inspectPressTree({
+        UserComponent: Press,
+        PRESS_MARKER: coreModule.PRESS_MARKER,
+        WORKSPACE_MARKER: coreModule.WORKSPACE_MARKER,
+      });
     }
 
+    // Workspace-level config (deploy, pdf, captionNumbering defaults)
+    // comes from package.json "openpress" via loadConfig. Each Press
+    // overlays its own metadata via JSX props at export time.
+    const config = await loadConfig(workspaceRoot);
+
     return {
       entryPath,
       config,
       Press,
-      sources,
+      presses: inspection.presses,
+      workspaceProps: inspection.workspaceProps,
+      pressCount: inspection.presses.length,
+      wrappedInWorkspace: inspection.wrappedInWorkspace,
     };
   } finally {
     if (!externalServer) await ownServer.close();
@@ -68,6 +92,7 @@ export async function createReactSsrServer(workspaceRoot = ".") {
   return createViteServer({
     configFile: false,
     root: FRAMEWORK_ROOT,
+    cacheDir: path.join(resolvedWorkspaceRoot, ".openpress", "vite-ssr"),
     appType: "custom",
     logLevel: "silent",
     plugins: [reactRuntimePlugin(), react()],
@@ -79,7 +104,17 @@ 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, "document", "components") },
+        { find: "@/components", replacement: path.join(resolvedWorkspaceRoot, "press", "components") },
+      ],
+    },
+    optimizeDeps: {
+      include: [
+        "@mdx-js/react",
+        "react",
+        "react-dom",
+        "react-dom/server",
+        "react/jsx-dev-runtime",
+        "react/jsx-runtime",
       ],
     },
     server: {
@@ -239,23 +274,6 @@ function isFileSystemModule(moduleName) {
   return moduleName === "fs" || moduleName === "node:fs" || moduleName === "fs/promises" || moduleName === "node:fs/promises";
 }
 
-function normalizeReactDocumentConfig(workspaceRoot, entryPath, config) {
-  if (config != null && (typeof config !== "object" || Array.isArray(config))) {
-    throw new Error("OpenPress React document entry `config` export must be an object when provided.");
-  }
-  const rawConfig = config ?? {};
-  const paths = rawConfig.paths ?? {};
-  return normalizeConfig(workspaceRoot, {
-    ...rawConfig,
-    documentDir: rawConfig.documentDir ?? paths.documentDir ?? "document",
-    sourceDir: rawConfig.sourceDir ?? paths.chaptersDir ?? paths.sourceDir ?? "chapters",
-    componentsDir: rawConfig.componentsDir ?? paths.componentsDir ?? "components",
-    mediaDir: rawConfig.mediaDir ?? paths.mediaDir ?? "media",
-    themeDir: rawConfig.themeDir ?? paths.themeDir ?? "theme",
-    designDoc: rawConfig.designDoc ?? paths.designDoc ?? "design.md",
-  }, entryPath);
-}
-
 async function fileExists(filePath) {
   try {
     const stat = await fs.stat(filePath);