@open-press/core 0.7.1 → 1.0.0

package/engine/react/pipeline/allocate.mjs

@@ -6,6 +6,8 @@
 //   - `hints`: { totalPagesPerChain: { [chainId]: number } } — fed back to <Sections>
 //   - `warnings`: chain-overflowed, etc.
 
+import { allocateBlocksToRegions, estimateRegionsNeeded } from "../pagination/allocator.mjs";
+
 const SANITY_LIMIT = 200;
 
 /**
@@ -58,7 +60,7 @@ export function allocateChains({ frames, mdxAreas, blockHeights, sources }) {
       continue;
     }
 
-    const { result, neededAreas } = greedyAllocate(blocks, regions);
+    const { result, neededAreas } = allocateBlocksToFiniteRegions(blocks, regions);
     const lastOverflow = regions[regions.length - 1].__overflow;
     const sourceFramesForChain = uniqueFramesForChain(frames, chainId);
 
@@ -110,76 +112,41 @@ export function allocateChains({ frames, mdxAreas, blockHeights, sources }) {
   };
 }
 
-function greedyAllocate(blocks, regions) {
-  const filled = [];
-  let regionIndex = 0;
-  let currentBlockIds = [];
-  let currentHeight = 0;
-  let consumed = 0;
-  const flush = () => {
-    if (currentBlockIds.length === 0) return;
-    filled.push({
-      region: regions[regionIndex],
-      blockIds: currentBlockIds,
-    });
-    currentBlockIds = [];
-    currentHeight = 0;
+function allocateBlocksToFiniteRegions(blocks, regions) {
+  const byRegionId = new Map(regions.map((region) => [region.id, region]));
+  const result = allocateBlocksToRegions(blocks, finiteRegionStream(regions), {
+    keepWithNext: shouldKeepWithNext,
+  });
+  const filled = result.regions.map((region) => ({
+    region: byRegionId.get(region.regionId),
+    blockIds: region.blockIds,
+  })).filter((fill) => fill.region);
+  const consumed = result.consumedCount;
+  const remaining = blocks.slice(consumed);
+  const extraNeeded = remaining.length > 0
+    ? estimateRegionsNeeded(remaining, regions[regions.length - 1].capacity, {
+      keepWithNext: shouldKeepWithNext,
+    })
+    : 0;
+  return {
+    result: { filled, consumed },
+    neededAreas: filled.length + extraNeeded,
   };
-  for (let blockIndex = 0; blockIndex < blocks.length; blockIndex += 1) {
-    const block = blocks[blockIndex];
-    while (regionIndex < regions.length) {
-      const region = regions[regionIndex];
-      const nextBlock = blocks[blockIndex + 1];
-      const keepWithNextHeight = shouldKeepWithNext(block, nextBlock) ? block.height + nextBlock.height : 0;
-      if (
-        currentBlockIds.length > 0 &&
-        keepWithNextHeight > 0 &&
-        currentHeight + keepWithNextHeight > region.capacity
-      ) {
-        flush();
-        regionIndex += 1;
-        continue;
-      }
-      if (currentBlockIds.length === 0 || currentHeight + block.height <= region.capacity) {
-        currentBlockIds.push(block.id);
-        currentHeight += block.height;
-        consumed += 1;
-        break;
-      }
-      // Doesn't fit — flush current region and advance
-      flush();
-      regionIndex += 1;
-    }
-    if (regionIndex >= regions.length) break;
-  }
-  flush();
-  // neededAreas = total regions consumed if we had unlimited supply
-  // For overflow detection we estimate: if consumed < blocks.length, we need more areas.
-  let neededAreas = filled.length;
-  if (consumed < blocks.length) {
-    // Estimate how many more areas needed
-    const lastCap = regions[regions.length - 1].capacity;
-    const remainingBlocks = blocks.slice(consumed);
-    let h = 0;
-    let extra = 0;
-    let inExtra = false;
-    for (const b of remainingBlocks) {
-      if (!inExtra || h + b.height > lastCap) {
-        extra += 1;
-        h = b.height;
-        inExtra = true;
-      } else {
-        h += b.height;
-      }
-    }
-    neededAreas += extra;
-  }
-  return { result: { filled, consumed }, neededAreas };
 }
 
 function shouldKeepWithNext(block, nextBlock) {
   if (!nextBlock) return false;
-  return /^h[1-6]$/.test(String(block?.name ?? ""));
+  const name = String(block?.name ?? "");
+  return /^h[1-6]$/.test(name) || name === "caption";
+}
+
+function finiteRegionStream(regions) {
+  let index = 0;
+  return {
+    next() {
+      return index < regions.length ? regions[index++] : null;
+    },
+  };
 }
 
 function recordAllocation(allocation, result, regions) {
@@ -223,12 +190,14 @@ function groupBlockHeights(blockHeights) {
 
 function buildBlockStream(chainSource, heightMap) {
   if (!chainSource || !heightMap) return [];
-  return chainSource.map((block) => ({
-    id: block.id,
-    kind: block.kind,
-    name: block.name,
-    height: heightMap.get(block.id) ?? 0,
-  }));
+  return chainSource
+    .filter((block) => block.layout !== "attached")
+    .map((block) => ({
+      id: block.id,
+      kind: block.kind,
+      name: block.name,
+      height: heightMap.get(block.id) ?? 0,
+    }));
 }
 
 function* iterateChains(sources) {

package/engine/react/pipeline/frame-measurement.mjs

@@ -221,6 +221,12 @@ async function runChromiumMeasurement(html, viewport) {
         const parentTop = chain.parentElement?.getBoundingClientRect().top ?? chain.getBoundingClientRect().top;
         let previousBottom = parentTop;
         for (const el of Array.from(chain.querySelectorAll("[data-openpress-block-id]"))) {
+          if (el.tagName.toLowerCase() === "caption") continue;
+          if (el.getAttribute("data-openpress-block-layout") === "attached") continue;
+          // Cells inherit their row's block-id so the inspector can resolve a
+          // SourceBlock when clicking inside a <td>. Skip them here so the
+          // row's measured height isn't overwritten by each cell.
+          if (el.getAttribute("data-openpress-inherited-block-id") === "true") continue;
           const rect = el.getBoundingClientRect();
           out.push({
             id: el.getAttribute("data-openpress-block-id"),

package/engine/react/press-tree-inspection.mjs

@@ -0,0 +1,172 @@
+// Walks the user's default-exported component tree to extract
+// <Workspace> and <Press> metadata declared as JSX props.
+//
+// The 1.0 contract says <Press> carries every per-document setting on
+// its props (title, page, sources, slug, theme, componentsDir) and is
+// always nested inside <Workspace>. This helper invokes the user's
+// component once at load time to inspect those props before the engine
+// runs its render pipeline.
+//
+// Safe to call because Workspace, Press, and (typically) the user's
+// default export are inert function components that just return JSX —
+// they don't use hooks at the entry boundary.
+
+import React from "react";
+
+/**
+ * Inspect the user's default export and extract every <Press> child
+ * of the (optional) <Workspace> wrapper. The export pipeline iterates
+ * the returned `presses` array — single-Press workspaces simply have
+ * length 1, multi-Press have length N. There is no separate code path
+ * for the single-Press case.
+ *
+ * @param {object} opts
+ * @param {Function} opts.UserComponent  The default export of press/index.tsx.
+ * @param {symbol} opts.PRESS_MARKER     Marker identifying Press components.
+ * @param {symbol} opts.WORKSPACE_MARKER Marker identifying Workspace components.
+ * @returns {{
+ *   workspaceProps: Record<string, unknown>,
+ *   presses: Array<{
+ *     element: object,                          // ReactElement
+ *     props: Record<string, unknown>,           // Press JSX props (no children)
+ *     metadata: {
+ *       title?: string,
+ *       page?: unknown,
+ *       slug?: string,
+ *       theme?: string,
+ *       componentsDir?: string,
+ *       captionNumbering?: unknown,
+ *     },
+ *     sources: Record<string, unknown> | null,  // mdxSource() descriptors keyed by id
+ *     children: unknown,                        // raw children for re-rendering
+ *     index: number,                            // position in the Workspace
+ *   }>,
+ *   wrappedInWorkspace: boolean,
+ * }}
+ */
+export function inspectPressTree({ UserComponent, PRESS_MARKER, WORKSPACE_MARKER }) {
+  if (typeof UserComponent !== "function") {
+    return emptyResult();
+  }
+
+  let root;
+  try {
+    root = UserComponent({});
+  } catch (err) {
+    // The user's default export threw before returning JSX. This is rare
+    // (function components at the entry boundary don't normally use hooks
+    // that could fail), but we treat it as "no Press metadata declared"
+    // and let the render pipeline surface the real error later with
+    // full React error context.
+    return emptyResult();
+  }
+
+  if (!isReactElement(root)) return emptyResult();
+
+  const workspaceProps = isMarked(root, WORKSPACE_MARKER) ? extractProps(root) : {};
+  const wrappedInWorkspace = isMarked(root, WORKSPACE_MARKER);
+
+  // Find every <Press> element in the tree (Workspace child, or root itself).
+  const pressElements = collectPressElements(root, PRESS_MARKER);
+
+  const presses = pressElements.map((element, index) => {
+    const props = extractProps(element);
+    return {
+      element,
+      props,
+      metadata: pickPressMetadata(props),
+      sources: extractSources(props),
+      children: element.props?.children ?? null,
+      index,
+    };
+  });
+
+  return {
+    workspaceProps,
+    presses,
+    wrappedInWorkspace,
+  };
+}
+
+function emptyResult() {
+  return {
+    workspaceProps: {},
+    presses: [],
+    wrappedInWorkspace: false,
+  };
+}
+
+function isReactElement(value) {
+  return value && typeof value === "object" && "type" in value && "props" in value;
+}
+
+function isMarked(element, marker) {
+  if (!isReactElement(element)) return false;
+  const type = element.type;
+  if (!type) return false;
+  // Components are tagged via `Component.openpressMarker = MARKER`.
+  return type.openpressMarker === marker;
+}
+
+function extractProps(element) {
+  if (!isReactElement(element) || !element.props) return {};
+  // Drop children — props are non-tree metadata only.
+  const { children, ...rest } = element.props;
+  return rest;
+}
+
+function collectPressElements(root, PRESS_MARKER) {
+  const found = [];
+  walk(root);
+  return found;
+
+  function walk(node) {
+    if (!isReactElement(node)) {
+      // Could be array / fragment / string / number — flatten and recurse.
+      if (Array.isArray(node)) {
+        for (const child of node) walk(child);
+      }
+      return;
+    }
+    if (isMarked(node, PRESS_MARKER)) {
+      found.push(node);
+      // Don't descend into Press — its children are the document tree,
+      // not more workspace structure.
+      return;
+    }
+    // Recurse into children + Fragment-like wrappers.
+    const children = node.props?.children;
+    if (children == null) return;
+    React.Children.forEach(children, walk);
+  }
+}
+
+function pickPressMetadata(pressProps) {
+  const out = {};
+  if (typeof pressProps.title === "string") out.title = pressProps.title;
+  if (pressProps.page !== undefined) out.page = pressProps.page;
+  if (typeof pressProps.slug === "string") out.slug = pressProps.slug;
+  if (typeof pressProps.theme === "string") out.theme = pressProps.theme;
+  if (typeof pressProps.componentsDir === "string") out.componentsDir = pressProps.componentsDir;
+  if (pressProps.captionNumbering !== undefined) out.captionNumbering = pressProps.captionNumbering;
+  return out;
+}
+
+// Convert the v1.0 <Press sources={[ mdxSource({ id, ... }), ... ]}> array
+// into the engine's expected sources record { [id]: descriptor }. Returns
+// null if no sources prop was declared (engine falls back to the named
+// `export const sources` from the entry module — the v0.x shape).
+function extractSources(pressProps) {
+  if (!Array.isArray(pressProps.sources)) return null;
+  const out = {};
+  for (const entry of pressProps.sources) {
+    if (!entry || typeof entry !== "object") continue;
+    const id = typeof entry.id === "string" ? entry.id : null;
+    if (!id) continue;
+    // Strip the id field — the engine's descriptor shape doesn't carry it
+    // (id was the record key in v0.x).
+    const { id: _omit, ...descriptor } = entry;
+    out[id] = descriptor;
+  }
+  return out;
+}

package/engine/react/project-asset-endpoint.mjs

@@ -3,8 +3,7 @@ import path from "node:path";
 import { loadConfig } from "../runtime/config.mjs";
 import { collectSourceTextFiles } from "../runtime/source-text-tools.mjs";
 import { insertCommentMarker } from "./comment-marker.mjs";
-
-const MAX_PROJECT_ASSET_BODY_BYTES = 64 * 1024;
+import { readJsonBody, writeJson } from "./http-json.mjs";
 
 export async function handleProjectAssetRequest(req, res, {
   root = ".",
@@ -16,7 +15,7 @@ export async function handleProjectAssetRequest(req, res, {
   }
 
   try {
-    const body = await readJsonBody(req);
+    const body = await readJsonBody(req, { bodyLabel: "Project asset request" });
     const config = await loadConfig(root);
     const action = stringValue(body?.action);
     const kind = stringValue(body?.kind);
@@ -53,6 +52,7 @@ export async function handleProjectAssetRequest(req, res, {
         note: body?.note,
         commentTarget: body?.commentTarget,
         currentSource: body?.currentSource,
+        objectEntity: body?.objectEntity,
         timestamp,
       });
       writeJson(res, 200, { ok: true, ...result });
@@ -133,6 +133,7 @@ async function createProjectAssetComment({
   note,
   commentTarget,
   currentSource,
+  objectEntity,
   timestamp,
 }) {
   const normalizedName = normalizeAssetName(kind, name);
@@ -146,13 +147,14 @@ async function createProjectAssetComment({
     commentTarget: stringValue(commentTarget),
     currentSource,
   });
+  const objectHint = stringValue(objectEntity?.id) ? ` object=${stringValue(objectEntity.id)}` : "";
 
   const result = await insertCommentMarker({
     root: config.root,
     path: target.path,
     source: { line: target.line, column: 1 },
     note: `${assetLabel(kind, normalizedName)}：${noteText}`,
-    hint: `openpress-project-asset kind=${kind} action=comment target=${target.reason} asset=${normalizedName}`,
+    hint: `openpress-project-asset kind=${kind} action=comment target=${target.reason} asset=${normalizedName}${objectHint}`,
     timestamp,
   });
 
@@ -357,23 +359,3 @@ async function fileExists(filePath) {
     return false;
   }
 }
-
-async function readJsonBody(req) {
-  let body = "";
-  for await (const chunk of req) {
-    body += String(chunk);
-    if (Buffer.byteLength(body, "utf8") > MAX_PROJECT_ASSET_BODY_BYTES) {
-      throw new Error("Project asset request body is too large.");
-    }
-  }
-  try {
-    return JSON.parse(body || "{}");
-  } catch {
-    throw new Error("Project asset request body must be valid JSON.");
-  }
-}
-
-function writeJson(res, status, body) {
-  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
-  res.end(`${JSON.stringify(body, null, 2)}\n`);
-}

package/engine/react/source-edit-endpoint.d.mts

@@ -0,0 +1,10 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+export function handleSourceEditRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  options?: {
+    root?: string;
+    refreshDocument?: boolean;
+  },
+): Promise<void>;

package/engine/react/source-edit-endpoint.mjs

@@ -0,0 +1,75 @@
+import { loadConfig } from "../runtime/config.mjs";
+import { applySourceBlockTextEdit, readSourceBlockText } from "../runtime/source-text-tools.mjs";
+import { exportReactDocument } from "./document-export.mjs";
+import { readJsonBody, writeJson } from "./http-json.mjs";
+
+export async function handleSourceEditRequest(req, res, {
+  root = ".",
+  refreshDocument = true,
+} = {}) {
+  if (req.method === "GET") {
+    try {
+      const requestUrl = new URL(req.url ?? "/", "http://localhost");
+      const config = await loadConfig(root);
+      const sourceText = await readSourceBlockText({
+        config,
+        path: requestUrl.searchParams.get("path"),
+        source: {
+          line: Number(requestUrl.searchParams.get("line")),
+          column: Number(requestUrl.searchParams.get("column") || 1),
+          endLine: Number(requestUrl.searchParams.get("endLine") || requestUrl.searchParams.get("line")),
+          endColumn: Number(requestUrl.searchParams.get("endColumn") || requestUrl.searchParams.get("column") || 1),
+        },
+      });
+      writeJson(res, 200, { ok: true, source: sourceText });
+    } catch (error) {
+      writeJson(res, 400, {
+        ok: false,
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+    return;
+  }
+
+  if (req.method !== "POST") {
+    writeJson(res, 405, { ok: false, message: "OpenPress source edit endpoint requires GET or POST." });
+    return;
+  }
+
+  try {
+    const body = await readJsonBody(req, {
+      bodyLabel: "OpenPress source edit request",
+      maxBytes: 256 * 1024,
+    });
+    const config = await loadConfig(root);
+    const edit = await applySourceBlockTextEdit({
+      config,
+      path: body?.path,
+      source: body?.source,
+      text: body?.text,
+      kind: body?.kind,
+      name: body?.name,
+      blockId: body?.blockId,
+      sourceMode: body?.sourceMode === true,
+    });
+    const exported = refreshDocument && body?.refreshDocument !== false
+      ? await exportReactDocument(root, { syncAssets: false })
+      : null;
+
+    writeJson(res, 200, {
+      ok: true,
+      edit,
+      document: exported
+        ? {
+          path: exported.documentPath,
+          pageCount: exported.pageCount,
+        }
+        : undefined,
+    });
+  } catch (error) {
+    writeJson(res, 400, {
+      ok: false,
+      message: error instanceof Error ? error.message : String(error),
+    });
+  }
+}

package/engine/react/sources/mdx-resolver.mjs

@@ -10,13 +10,14 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import React from "react";
+import { documentRelativePath, resolveDocumentRelativePath } from "../../runtime/path-utils.mjs";
 import { compileMdx } from "../mdx-compile.mjs";
 import { createHeadingState, fallbackOutlineItems, headingAttributesForBlock } from "./heading-numbering.mjs";
 
 const MDX_EXT = ".mdx";
 
 /**
- * Resolve all sources registered in `document/index.tsx`.
+ * Resolve all sources registered in `press/index.tsx`.
  *
  * @param {object} opts
  * @param {Record<string, object>} opts.sources         The raw `sources` export.
@@ -103,6 +104,7 @@ async function resolveSource({ sourceId, descriptor, documentRoot, globalCompone
           kind: block.kind,
           name: block.name,
           text: block.text,
+          layout: block.layout,
           chainId,
           sectionSlug: section.slug,
           path: documentRelative(file.absolutePath, documentRoot),
@@ -323,6 +325,7 @@ function compileTocBlocks({ tocBlocks, chainId, blockIds, toc }) {
         {
           className,
           "data-openpress-block-id": block.id,
+          "data-openpress-object-id": createBlockObjectEntityId(block.id),
           "data-openpress-toc-entry": block.sectionSlug,
         },
         React.createElement(
@@ -352,6 +355,14 @@ function locateSection(renderData, chainId) {
   throw new Error(`No section found for chainId "${chainId}" in source "${renderData.sourceId}".`);
 }
 
+function createObjectEntityId(kind, ...parts) {
+  return [kind, ...parts.map((part) => encodeURIComponent(String(part)))].join(":");
+}
+
+function createBlockObjectEntityId(blockId) {
+  return createObjectEntityId("mdx-block", blockId);
+}
+
 // ---------------------------------------------------------------------------
 // Validation
 // ---------------------------------------------------------------------------
@@ -425,17 +436,4 @@ function deriveTitleFromDirName(name) {
     .join(" ");
 }
 
-function documentRelative(absolutePath, documentRoot) {
-  return path.relative(documentRoot, absolutePath).split(path.sep).join("/");
-}
-
-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;
-}
+const documentRelative = documentRelativePath;

package/engine/react/style-discovery.mjs

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { documentRelativePath } from "../runtime/path-utils.mjs";
 
 // Style discovery — only used to find per-section CSS files for the
 // section-folders preset. MDX content discovery lives in `sources/mdx-resolver`.
@@ -8,13 +9,31 @@ import path from "node:path";
 
 const COMPONENT_EXT = ".tsx";
 
-export async function discoverSectionStyles(root = ".", config = {}) {
+export async function discoverSectionStyles(root = ".", config = {}, { sectionRoots } = {}) {
   const workspaceRoot = path.resolve(root);
-  const documentRoot = config.paths?.documentRoot ?? path.join(workspaceRoot, "document");
+  const documentRoot = config.paths?.documentRoot ?? path.join(workspaceRoot, "press");
   const componentsRoot = config.paths?.componentsDir ?? path.join(documentRoot, "components");
-  const sectionsRoot = config.paths?.chaptersDir ?? config.paths?.sourceDir ?? path.join(documentRoot, "chapters");
   const globalComponents = await discoverComponents(componentsRoot, documentRoot, "global");
-  const sections = await discoverSections(documentRoot, sectionsRoot);
+
+  // Multi-Press workspaces can place their chapters under per-Press
+  // subfolders (e.g. press/userstory/chapters/, press/slidepack/chapters/).
+  // The caller passes each Press's resolved section-folders root; we
+  // discover sections in every root and merge. Duplicate paths are
+  // de-duplicated by absolutePath. Falls back to the workspace-default
+  // root (press/chapters/) when no roots are passed in.
+  const effectiveRoots = sectionRoots && sectionRoots.length > 0
+    ? sectionRoots
+    : [config.paths?.chaptersDir ?? config.paths?.sourceDir ?? path.join(documentRoot, "chapters")];
+  const seen = new Set();
+  const sections = [];
+  for (const sectionsRoot of effectiveRoots) {
+    const found = await discoverSections(documentRoot, sectionsRoot);
+    for (const section of found) {
+      if (seen.has(section.absolutePath)) continue;
+      seen.add(section.absolutePath);
+      sections.push(section);
+    }
+  }
 
   return {
     root: workspaceRoot,
@@ -102,10 +121,6 @@ function pathRecord(absolutePath, documentRoot) {
   };
 }
 
-function documentRelativePath(absolutePath, documentRoot) {
-  return path.relative(documentRoot, absolutePath).split(path.sep).join("/");
-}
-
 function compareSectionDirectories(a, b) {
   const left = sectionSortKey(a.name);
   const right = sectionSortKey(b.name);

package/engine/runtime/config.d.mts

@@ -10,6 +10,14 @@ export interface ResolvedConfig {
   componentsDir: string;
   publicDir: string;
   outputDir: string;
+  page: null | {
+    id: string;
+    label: string;
+    width: string;
+    height: string;
+    aspectRatio?: string;
+    heightRatio?: string;
+  };
   pdf: {
     filename: string;
   };