@open-press/core 0.7.1 → 1.0.0

package/engine/react/mdx-compile.mjs

@@ -112,6 +112,7 @@ export function rehypeBlockIds(options = {}) {
       if (includeBlockIds && !includeBlockIds.has(id)) return false;
 
       setDataAttribute(node, "data-openpress-block-id", id);
+      setDataAttribute(node, "data-openpress-object-id", createBlockObjectEntityId(id));
       const extraAttributes = blockAttributes.get(id);
       if (extraAttributes) {
         for (const [name, value] of Object.entries(extraAttributes)) {
@@ -142,9 +143,19 @@ function applyTableRowBlocks({
   includeBlockIds,
 }) {
   const rows = tableBodyRows(node);
+  const header = tableHeaderRow(node);
+  const caption = tableCaption(node);
+  const captionRecord = caption ? { id: `${id}-caption`, node: caption } : null;
+  const headerRecord = header ? { id: `${id}-h0`, node: header } : null;
+  const selectedCaption = captionRecord && (!includeBlockIds || includeBlockIds.has(captionRecord.id));
+  const selectedHeader = headerRecord && (!includeBlockIds || includeBlockIds.has(headerRecord.id));
+  const firstSelectedRowIndex = selectedFirstTableRowIndex(rows, includeBlockIds, id);
+  const renderCaption = selectedCaption || (captionRecord && includeBlockIds && firstSelectedRowIndex === 0);
+  const renderHeader = Boolean(headerRecord && (!includeBlockIds || firstSelectedRowIndex === 0 || selectedHeader));
   if (rows.length === 0) {
     if (includeBlockIds && !includeBlockIds.has(id)) return false;
     setDataAttribute(node, "data-openpress-block-id", id);
+    setDataAttribute(node, "data-openpress-object-id", createBlockObjectEntityId(id));
     blocks.push({
       id,
       kind: "element",
@@ -165,15 +176,64 @@ function applyTableRowBlocks({
   const selected = includeBlockIds
     ? rowRecords.filter((row) => includeBlockIds.has(row.id))
     : rowRecords;
-  if (selected.length === 0) return false;
+  if (selected.length === 0 && !selectedCaption && !selectedHeader) return false;
 
   setDataAttribute(node, "data-openpress-table-id", id);
+  if (headerRecord && renderHeader) {
+    setDataAttribute(headerRecord.node, "data-openpress-block-id", headerRecord.id);
+    setDataAttribute(headerRecord.node, "data-openpress-object-id", createBlockObjectEntityId(headerRecord.id));
+    setDataAttribute(headerRecord.node, "data-openpress-block-layout", "attached");
+    annotateTableCells(headerRecord.node, headerRecord.id);
+  }
+  if (captionRecord) {
+    if (renderCaption) {
+      setDataAttribute(captionRecord.node, "data-openpress-block-id", captionRecord.id);
+      setDataAttribute(captionRecord.node, "data-openpress-object-id", createBlockObjectEntityId(captionRecord.id));
+      if (selectedCaption) {
+        blocks.push({
+          id: captionRecord.id,
+          kind: "element",
+          name: "caption",
+          text: textContent(captionRecord.node).trim() || undefined,
+          filePath,
+          chapterSlug,
+          tableId: id,
+          layout: "attached",
+          source: sourcePosition(captionRecord.node.position ?? node.position),
+        });
+      }
+    } else {
+      removeTableCaption(node);
+    }
+  }
+  if (headerRecord && selectedHeader) {
+    blocks.push({
+      id: headerRecord.id,
+      kind: "table-row",
+      name: "table-header-row",
+      text: textContent(headerRecord.node).trim() || undefined,
+      filePath,
+      chapterSlug,
+      tableId: id,
+      rowIndex: -1,
+      layout: "attached",
+      source: sourcePosition(headerRecord.node.position ?? node.position),
+    });
+  }
   const selectedNodes = new Set(selected.map((row) => row.node));
   pruneUnselectedTableRows(node, new Set(rowRecords.map((row) => row.node)), selectedNodes);
-  if (selected[0]?.index > 0) stripTableHeader(node);
+  if (!renderHeader) stripTableHeader(node);
 
   for (const row of selected) {
     setDataAttribute(row.node, "data-openpress-block-id", row.id);
+    setDataAttribute(row.node, "data-openpress-object-id", createBlockObjectEntityId(row.id));
+    // Bake cell-level object ids into every <td>/<th>. The inspector resolves
+    // a clicked target via `closest("[data-openpress-object-id]")` — without
+    // this, a click inside a cell would walk up to the row and a comment
+    // would target the entire row. With the cell-precision id present in the
+    // static HTML the inspector targets the individual cell, matching the
+    // engine's per-cell source-edit pipeline (`cellIndex`).
+    annotateTableCells(row.node, row.id);
     blocks.push({
       id: row.id,
       kind: "table-row",
@@ -189,6 +249,28 @@ function applyTableRowBlocks({
   return "skip";
 }
 
+function annotateTableCells(rowNode, rowBlockId) {
+  const children = Array.isArray(rowNode?.children) ? rowNode.children : [];
+  let cellIndex = 0;
+  for (const child of children) {
+    if (child?.type !== "element") continue;
+    if (child.tagName !== "td" && child.tagName !== "th") continue;
+    // Inherit the row's block id so `findObjectSelection` can resolve the
+    // cell's underlying SourceBlock (which lives on the row). The
+    // cell-precision `data-openpress-object-id` + cellIndex still let the
+    // inspector / source-edit pipeline target a single cell within that row.
+    // `data-openpress-inherited-block-id="true"` keeps the same convention
+    // the inline editor uses for caption / cell descendants, so block
+    // measurement (which queries `[data-openpress-block-id]`) can skip
+    // these and not double-count the row's height across N cells.
+    setDataAttribute(child, "data-openpress-block-id", rowBlockId);
+    setDataAttribute(child, "data-openpress-inherited-block-id", "true");
+    setDataAttribute(child, "data-openpress-object-id", `${createBlockObjectEntityId(rowBlockId)}:cell:${cellIndex}`);
+    setDataAttribute(child, "data-openpress-table-cell-index", String(cellIndex));
+    cellIndex += 1;
+  }
+}
+
 export function remarkBlockOnlyMdx(options = {}) {
   const filePath = String(options.filePath ?? "document.mdx");
 
@@ -229,6 +311,7 @@ function normalizeTableCaptions(node) {
         type: "element",
         tagName: "caption",
         properties: {},
+        position: child.position,
         children: [{ type: "text", value: captionText }],
       });
     }
@@ -272,8 +355,10 @@ function wrapMdxComponents(components) {
     if (typeof Component !== "function") continue;
     wrapped[name] = function ComponentBlock(props = {}) {
       const blockId = props["data-openpress-block-id"];
+      const objectId = props["data-openpress-object-id"] || (blockId ? createBlockObjectEntityId(blockId) : undefined);
       const rest = { ...props };
       delete rest["data-openpress-block-id"];
+      delete rest["data-openpress-object-id"];
 
       if (!blockId) return React.createElement(Component, rest);
 
@@ -281,6 +366,7 @@ function wrapMdxComponents(components) {
         "div",
         {
           "data-openpress-block-id": blockId,
+          "data-openpress-object-id": objectId,
           "data-openpress-component-block": name,
         },
         React.createElement(Component, rest),
@@ -336,6 +422,7 @@ function applyListItemBlocks({
   if (items.length === 0) {
     if (includeBlockIds && !includeBlockIds.has(id)) return false;
     setDataAttribute(node, "data-openpress-block-id", id);
+    setDataAttribute(node, "data-openpress-object-id", createBlockObjectEntityId(id));
     blocks.push({
       id,
       kind: "element",
@@ -375,6 +462,7 @@ function applyListItemBlocks({
 
   for (const item of selected) {
     setDataAttribute(item.node, "data-openpress-block-id", item.id);
+    setDataAttribute(item.node, "data-openpress-object-id", createBlockObjectEntityId(item.id));
     blocks.push({
       id: item.id,
       kind: "list-item",
@@ -419,6 +507,28 @@ function tableBodyRows(table) {
   return (table.children ?? []).filter((child) => child?.type === "element" && child.tagName === "tr");
 }
 
+function tableHeaderRow(table) {
+  if (table?.type !== "element" || table.tagName !== "table") return null;
+  for (const child of table.children ?? []) {
+    if (child?.type !== "element" || child.tagName !== "thead") continue;
+    return (child.children ?? []).find((row) => row?.type === "element" && row.tagName === "tr") ?? null;
+  }
+  return null;
+}
+
+function selectedFirstTableRowIndex(rows, includeBlockIds, tableId) {
+  if (!includeBlockIds) return 0;
+  for (let index = 0; index < rows.length; index += 1) {
+    if (includeBlockIds.has(`${tableId}-r${index}`)) return index;
+  }
+  return -1;
+}
+
+function tableCaption(table) {
+  if (table?.type !== "element" || table.tagName !== "table") return null;
+  return (table.children ?? []).find((child) => child?.type === "element" && child.tagName === "caption") ?? null;
+}
+
 function pruneUnselectedTableRows(node, rowNodes, selectedNodes) {
   if (!Array.isArray(node?.children)) return;
   node.children = node.children.filter((child) => {
@@ -432,10 +542,15 @@ function stripTableHeader(table) {
   if (!Array.isArray(table?.children)) return;
   table.children = table.children.filter((child) => {
     if (child?.type !== "element") return true;
-    return child.tagName !== "caption" && child.tagName !== "thead";
+    return child.tagName !== "thead";
   });
 }
 
+function removeTableCaption(table) {
+  if (!Array.isArray(table?.children)) return;
+  table.children = table.children.filter((child) => child?.type !== "element" || child.tagName !== "caption");
+}
+
 function headingText(node) {
   if (!/^h[1-6]$/.test(String(node?.tagName ?? ""))) return undefined;
   return textContent(node).trim() || undefined;
@@ -470,6 +585,14 @@ function setDataAttribute(node, name, value) {
   node.properties[name] = value;
 }
 
+function createObjectEntityId(kind, ...parts) {
+  return [kind, ...parts.map((part) => encodeURIComponent(String(part)))].join(":");
+}
+
+function createBlockObjectEntityId(blockId) {
+  return createObjectEntityId("mdx-block", blockId);
+}
+
 function visit(node, visitor) {
   visitor(node);
   if (!Array.isArray(node?.children)) return;

package/engine/react/measurement-css.mjs

@@ -3,6 +3,7 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { buildComponentsCss, buildContentCss } from "../runtime/file-utils.mjs";
+import { pageGeometryToTheme } from "../runtime/page-geometry.mjs";
 import { buildSectionScopedCss } from "./section-css.mjs";
 
 const require = createRequire(import.meta.url);
@@ -11,6 +12,7 @@ export async function buildReactMeasurementCss(root, config, workspace) {
   const parts = [];
   await appendOptionalFile(parts, path.join(config.paths.themeDir, "fonts.css"), "theme/fonts.css");
   await appendOptionalFile(parts, path.join(config.paths.themeDir, "tokens.css"), "theme/tokens.css");
+  appendPageGeometryCss(parts, config.page);
   parts.push("/* === public/openpress/content.css === */\n");
   parts.push(await buildContentCss(root, config));
   parts.push("\n/* === public/openpress/components.css === */\n");
@@ -20,7 +22,26 @@ export async function buildReactMeasurementCss(root, config, workspace) {
     parts.push("\n/* === public/openpress/chapter-scoped.css === */\n");
     parts.push(chapterCss);
   }
-  return rewriteAssetUrls(parts.join("\n"), config);
+  return rewriteAssetUrls(stripViewportMediaQueries(parts.join("\n")), config);
+}
+
+function appendPageGeometryCss(parts, page) {
+  const theme = pageGeometryToTheme(page);
+  if (!theme) return;
+
+  const declarations = [
+    ["--openpress-page-width", theme.pageWidth],
+    ["--openpress-page-height", theme.pageHeight],
+    ["--openpress-page-aspect-ratio", theme.pageAspectRatio],
+    ["--openpress-page-height-ratio", theme.pageHeightRatio],
+  ].filter(([, value]) => value);
+
+  parts.push("/* === openpress page geometry === */\n");
+  parts.push(":root {\n");
+  for (const [name, value] of declarations) {
+    parts.push(`  ${name}: ${value};\n`);
+  }
+  parts.push("}\n\n");
 }
 
 async function appendOptionalFile(parts, filePath, label) {
@@ -42,3 +63,95 @@ function rewriteAssetUrls(css, config) {
     .replace(/url\((["'])?\/openpress\/fonts\//g, `url($1${themeFontsDir}`)
     .replace(/url\((["'])?\/openpress\/katex-fonts\//g, `url($1${katexFontsDir}`);
 }
+
+function stripViewportMediaQueries(css) {
+  let output = "";
+  let cursor = 0;
+
+  while (cursor < css.length) {
+    const mediaIndex = css.indexOf("@media", cursor);
+    if (mediaIndex < 0) {
+      output += css.slice(cursor);
+      break;
+    }
+
+    output += css.slice(cursor, mediaIndex);
+    const blockStart = css.indexOf("{", mediaIndex);
+    if (blockStart < 0) {
+      output += css.slice(mediaIndex);
+      break;
+    }
+
+    const prelude = css.slice(mediaIndex + "@media".length, blockStart);
+    const blockEnd = findCssBlockEnd(css, blockStart);
+    if (blockEnd < 0) {
+      output += css.slice(mediaIndex);
+      break;
+    }
+
+    if (!isViewportMediaPrelude(prelude)) {
+      output += css.slice(mediaIndex, blockEnd + 1);
+    }
+    cursor = blockEnd + 1;
+  }
+
+  return output;
+}
+
+function isViewportMediaPrelude(prelude) {
+  if (/\bprint\b/i.test(prelude)) return false;
+  return /\(\s*(?:min-|max-)?(?:device-)?(?:width|height)\s*:/i.test(prelude)
+    || /\(\s*orientation\s*:/i.test(prelude)
+    || /\(\s*(?:min-|max-)?aspect-ratio\s*:/i.test(prelude);
+}
+
+function findCssBlockEnd(css, blockStart) {
+  let depth = 0;
+  let quote = "";
+  let inComment = false;
+
+  for (let index = blockStart; index < css.length; index += 1) {
+    const current = css[index];
+    const next = css[index + 1];
+
+    if (inComment) {
+      if (current === "*" && next === "/") {
+        inComment = false;
+        index += 1;
+      }
+      continue;
+    }
+
+    if (quote) {
+      if (current === "\\") {
+        index += 1;
+        continue;
+      }
+      if (current === quote) quote = "";
+      continue;
+    }
+
+    if (current === "/" && next === "*") {
+      inComment = true;
+      index += 1;
+      continue;
+    }
+
+    if (current === "\"" || current === "'") {
+      quote = current;
+      continue;
+    }
+
+    if (current === "{") {
+      depth += 1;
+      continue;
+    }
+
+    if (current === "}") {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+  }
+
+  return -1;
+}

package/engine/react/object-entities.mjs

@@ -0,0 +1,204 @@
+export function createObjectEntityId(kind, ...parts) {
+  return [kind, ...parts.map((part) => encodeURIComponent(String(part)))].join(":");
+}
+
+export function createBlockObjectEntityId(blockId) {
+  return createObjectEntityId("mdx-block", blockId);
+}
+
+export function createPageObjectEntityId(frameKey) {
+  return createObjectEntityId("page", frameKey);
+}
+
+export function createFrameObjectEntityId(frameKey) {
+  return createObjectEntityId("frame", frameKey);
+}
+
+export function createScopedObjectEntityId(kind, parentId, objectId) {
+  return parentId ? createObjectEntityId(kind, parentId, objectId) : createObjectEntityId(kind, objectId);
+}
+
+export function createMdxAreaObjectEntityId(frameKey, chainId, indexInFrame) {
+  return createObjectEntityId("mdx-area", frameKey, chainId, indexInFrame);
+}
+
+export function buildObjectEntities({ frames, blocks, blockMap }) {
+  const entities = {};
+  const blockParentIdByBlockId = new Map();
+
+  for (const block of blocks) {
+    const frameKey = block.frameKey ?? block.id;
+    const sourcePath = block.source?.path;
+    const pageId = createPageObjectEntityId(frameKey);
+    const base = {
+      frameKey,
+      pageId,
+      source: sourcePath
+        ? {
+            path: sourcePath,
+            file: block.source?.file,
+            line: 1,
+            column: 1,
+          }
+        : undefined,
+    };
+
+    entities[pageId] = {
+      id: pageId,
+      kind: "page",
+      label: block.title || `Page ${block.pageNumber}`,
+      ...base,
+    };
+
+    const frameId = createFrameObjectEntityId(frameKey);
+    entities[frameId] = {
+      id: frameId,
+      kind: "frame",
+      label: block.role || block.title || frameKey,
+      ...base,
+      parentId: pageId,
+      metadata: { role: block.role ?? null, chrome: block.chrome ?? null },
+    };
+  }
+
+  for (const frame of frames) {
+    const pageId = createPageObjectEntityId(frame.frameKey);
+    const frameId = createFrameObjectEntityId(frame.frameKey);
+    for (const area of frame.mdxAreas ?? []) {
+      const id = createMdxAreaObjectEntityId(frame.frameKey, area.chainId, area.indexInFrame);
+      const firstEditableBlock = (area.blockIds ?? [])
+        .map((blockId) => blockMap[blockId])
+        .find((block) => block?.path);
+      for (const blockId of area.blockIds ?? []) blockParentIdByBlockId.set(blockId, id);
+      entities[id] = {
+        id,
+        kind: "mdx-area",
+        label: `${area.chainId} area ${area.indexInFrame + 1}`,
+        parentId: frameId,
+        pageId,
+        frameKey: frame.frameKey,
+        chainId: area.chainId,
+        source: firstEditableBlock
+          ? {
+              path: firstEditableBlock.path,
+              source: firstEditableBlock.source,
+              line: firstEditableBlock.source?.line,
+              column: firstEditableBlock.source?.column,
+            }
+          : undefined,
+        metadata: { blockCount: area.blockIds?.length ?? 0 },
+      };
+    }
+  }
+
+  for (const block of Object.values(blockMap)) {
+    if (!block?.id) continue;
+    const id = createBlockObjectEntityId(block.id);
+    const pageId = block.frameKey ? createPageObjectEntityId(block.frameKey) : undefined;
+    entities[id] = {
+      id,
+      kind: "mdx-block",
+      label: block.name ? `${block.name} ${block.id}` : block.id,
+      parentId: blockParentIdByBlockId.get(block.id),
+      pageId,
+      blockId: block.id,
+      frameKey: block.frameKey,
+      chainId: block.chainId,
+      source: block.path
+        ? {
+            path: block.path,
+            source: block.source,
+            line: block.source?.line,
+            column: block.source?.column,
+          }
+        : undefined,
+      metadata: {
+        blockKind: block.kind ?? null,
+        componentName: block.kind === "component" ? block.name ?? null : null,
+      },
+    };
+  }
+
+  for (const entity of collectRenderedObjectEntities(frames)) {
+    if (!entity.id || entities[entity.id]) continue;
+    const pageId = entity.pageId || createPageObjectEntityId(entity.frameKey);
+    const frameId = createFrameObjectEntityId(entity.frameKey);
+    entities[entity.id] = {
+      id: entity.id,
+      kind: entity.kind,
+      label: entity.label || entity.id,
+      parentId: entity.parentId || (entity.id === frameId ? pageId : frameId),
+      pageId,
+      blockId: entity.blockId,
+      frameKey: entity.frameKey,
+      chainId: entity.chainId,
+      source: entity.source,
+      metadata: entity.metadata,
+    };
+  }
+
+  return entities;
+}
+
+const OBJECT_OPEN_RE = /<([a-z][a-z0-9-]*)\b([^>]*)\bdata-openpress-object-id="([^"]+)"([^>]*)>/gi;
+const ATTR_RE = (name) => new RegExp(`\\b${name}="([^"]*)"`);
+
+function collectRenderedObjectEntities(frames) {
+  const entities = [];
+  for (const frame of frames) {
+    const pageId = createPageObjectEntityId(frame.frameKey);
+    const frameId = createFrameObjectEntityId(frame.frameKey);
+    const html = String(frame.html ?? "");
+    let match;
+    OBJECT_OPEN_RE.lastIndex = 0;
+    while ((match = OBJECT_OPEN_RE.exec(html)) !== null) {
+      const attrs = `${match[2] ?? ""} data-openpress-object-id="${match[3] ?? ""}" ${match[4] ?? ""}`;
+      const id = htmlDecode(match[3] ?? "");
+      const kind = htmlDecode(pickAttr(attrs, "data-openpress-object-kind")) || objectKindFromId(id);
+      if (!id || !kind) continue;
+      entities.push({
+        id,
+        kind,
+        label: htmlDecode(pickAttr(attrs, "data-openpress-object-label")) || id,
+        parentId: htmlDecode(pickAttr(attrs, "data-openpress-object-parent-id")) || (id === frameId ? pageId : frameId),
+        pageId: htmlDecode(pickAttr(attrs, "data-openpress-object-page-id")) || pageId,
+        blockId: htmlDecode(pickAttr(attrs, "data-openpress-block-id")) || undefined,
+        frameKey: htmlDecode(pickAttr(attrs, "data-openpress-object-frame-key")) || frame.frameKey,
+        chainId: htmlDecode(pickAttr(attrs, "data-openpress-object-chain-id")) || undefined,
+        source: parseJsonAttribute(pickAttr(attrs, "data-openpress-object-source")),
+        metadata: parseJsonAttribute(pickAttr(attrs, "data-openpress-object-metadata")),
+      });
+    }
+  }
+  return entities;
+}
+
+function pickAttr(attrs, name) {
+  const match = ATTR_RE(name).exec(attrs);
+  return match ? match[1] : "";
+}
+
+function objectKindFromId(id) {
+  const separator = id.indexOf(":");
+  return separator === -1 ? "" : id.slice(0, separator);
+}
+
+function parseJsonAttribute(value) {
+  const decoded = htmlDecode(value);
+  if (!decoded) return undefined;
+  try {
+    return JSON.parse(decoded);
+  } catch {
+    return undefined;
+  }
+}
+
+function htmlDecode(value) {
+  return String(value ?? "")
+    .replaceAll("&quot;", '"')
+    .replaceAll("&#x27;", "'")
+    .replaceAll("&#39;", "'")
+    .replaceAll("&lt;", "<")
+    .replaceAll("&gt;", ">")
+    .replaceAll("&amp;", "&");
+}

package/engine/react/pagination/allocator.mjs

@@ -7,7 +7,8 @@ import { singleColumnRegionStream } from "./regions.mjs";
 // region until adding the next block would exceed capacity, then advance to
 // the next region. Pages are a derived view (grouping by pageIndex), so the
 // same code paginates single-column, multi-column, and heterogeneous layouts.
-export function allocateBlocksToRegions(measuredBlocks, regionStream) {
+export function allocateBlocksToRegions(measuredBlocks, regionStream, options = {}) {
+  const keepWithNext = typeof options.keepWithNext === "function" ? options.keepWithNext : null;
   const filled = [];
   const warnings = [];
   let current = regionStream.next();
@@ -16,6 +17,7 @@ export function allocateBlocksToRegions(measuredBlocks, regionStream) {
   }
   let currentBlockIds = [];
   let currentHeight = 0;
+  let consumedCount = 0;
 
   const flush = () => {
     if (currentBlockIds.length === 0) return;
@@ -29,7 +31,9 @@ export function allocateBlocksToRegions(measuredBlocks, regionStream) {
     currentHeight = 0;
   };
 
-  for (const block of measuredBlocks ?? []) {
+  const blocks = measuredBlocks ?? [];
+  for (let blockIndex = 0; blockIndex < blocks.length; blockIndex += 1) {
+    const block = blocks[blockIndex];
     const id = String(block?.id ?? "");
     if (!id) continue;
     const height = Math.max(0, Number(block.height) || 0);
@@ -45,6 +49,24 @@ export function allocateBlocksToRegions(measuredBlocks, regionStream) {
       });
     }
 
+    const nextBlock = blocks[blockIndex + 1];
+    const nextHeight = Math.max(0, Number(nextBlock?.height) || 0);
+    const keepWithNextHeight = keepWithNext?.(block, nextBlock) ? height + nextHeight : 0;
+
+    if (
+      currentBlockIds.length > 0 &&
+      keepWithNextHeight > 0 &&
+      currentHeight + keepWithNextHeight > current.capacity
+    ) {
+      flush();
+      const next = regionStream.next();
+      if (!next) {
+        warnings.push({ code: "out-of-regions", blockId: id });
+        break;
+      }
+      current = next;
+    }
+
     if (currentBlockIds.length > 0 && currentHeight + height > current.capacity) {
       flush();
       const next = regionStream.next();
@@ -57,10 +79,17 @@ export function allocateBlocksToRegions(measuredBlocks, regionStream) {
 
     currentBlockIds.push(id);
     currentHeight += height;
+    consumedCount += 1;
   }
 
   flush();
-  return { regions: filled, warnings };
+  return { regions: filled, warnings, consumedCount };
+}
+
+export function estimateRegionsNeeded(measuredBlocks, regionCapacity, options = {}) {
+  const capacity = positiveNumber(regionCapacity, DEFAULT_PAGE_SAFE_HEIGHT_PX);
+  const result = allocateBlocksToRegions(measuredBlocks, infiniteFixedCapacityRegionStream(capacity), options);
+  return result.regions.length;
 }
 
 // Derive a flat pages[] view from filled regions. Blocks within a page are
@@ -101,6 +130,22 @@ export function paginateMeasuredBlocks(measuredBlocks, options = {}) {
   };
 }
 
+function infiniteFixedCapacityRegionStream(capacity) {
+  let index = 0;
+  return {
+    next() {
+      const region = {
+        id: `estimate-region-${index}`,
+        capacity,
+        pageIndex: index,
+        columnIndex: 0,
+      };
+      index += 1;
+      return region;
+    },
+  };
+}
+
 // Translate the new region-shaped warnings back to the legacy
 // `block-overflows-page` schema that document-export.mjs and downstream
 // consumers expect. Once consumers migrate, this can drop.

package/engine/react/pagination.mjs

@@ -5,5 +5,5 @@
 // these helpers. The region kernel is also usable on its own for custom
 // pipelines or unit tests.
 
-export { paginateMeasuredBlocks, allocateBlocksToRegions, pagesFromRegions } from "./pagination/allocator.mjs";
+export { paginateMeasuredBlocks, allocateBlocksToRegions, estimateRegionsNeeded, pagesFromRegions } from "./pagination/allocator.mjs";
 export { singleColumnRegionStream, multiColumnRegionStream, fixedRegionStream } from "./pagination/regions.mjs";