@open-press/core 0.6.0 → 0.7.1

package/engine/react/mdx-compile.mjs

@@ -31,6 +31,7 @@ export async function compileMdx({
   components = {},
   chapterSlug = "document",
   includeBlockIds = null,
+  blockAttributes = null,
 } = {}) {
   if (typeof source !== "string") throw new Error("compileMdx requires a string `source`.");
   if (typeof filePath !== "string" || !filePath.trim()) throw new Error("compileMdx requires `filePath`.");
@@ -39,7 +40,7 @@ export async function compileMdx({
 
   const blocks = [];
   const remarkPlugins = [[remarkMath, { singleDollarTextMath: true }], remarkGfm, [remarkBlockOnlyMdx, { filePath }]];
-  const rehypePlugins = [rehypeKatex, rehypeTableCaptions, [rehypeBlockIds, { blocks, filePath, chapterSlug, includeBlockIds }]];
+  const rehypePlugins = [rehypeKatex, rehypeTableCaptions, [rehypeBlockIds, { blocks, filePath, chapterSlug, includeBlockIds, blockAttributes }]];
   const mod = await evaluate(mdxSource, {
     ...jsxRuntime,
     baseUrl: pathToFileURL(filePath).href,
@@ -78,6 +79,7 @@ export function rehypeBlockIds(options = {}) {
   const chapterSlug = slugPart(options.chapterSlug ?? "document");
   const sourceSlug = slugPart(path.basename(filePath, path.extname(filePath)));
   const includeBlockIds = Array.isArray(options.includeBlockIds) ? new Set(options.includeBlockIds) : null;
+  const blockAttributes = normalizeBlockAttributes(options.blockAttributes);
   let counter = 0;
 
   return (tree) => {
@@ -87,22 +89,106 @@ export function rehypeBlockIds(options = {}) {
 
       const id = `b-${chapterSlug}-${sourceSlug}-${counter}`;
       counter += 1;
+      if (block.name === "table") {
+        return applyTableRowBlocks({
+          node,
+          id,
+          blocks,
+          filePath,
+          chapterSlug,
+          includeBlockIds,
+        });
+      }
+      if (block.name === "ul" || block.name === "ol") {
+        return applyListItemBlocks({
+          node,
+          id,
+          blocks,
+          filePath,
+          chapterSlug,
+          includeBlockIds,
+        });
+      }
       if (includeBlockIds && !includeBlockIds.has(id)) return false;
 
       setDataAttribute(node, "data-openpress-block-id", id);
+      const extraAttributes = blockAttributes.get(id);
+      if (extraAttributes) {
+        for (const [name, value] of Object.entries(extraAttributes)) {
+          if (value == null || value === "") continue;
+          setDataAttribute(node, name, String(value));
+        }
+      }
       blocks.push({
         id,
         kind: block.kind,
         name: block.name,
+        text: block.text,
         filePath,
         chapterSlug,
         source: sourcePosition(node.position),
       });
-      return true;
+      return "skip";
     });
   };
 }
 
+function applyTableRowBlocks({
+  node,
+  id,
+  blocks,
+  filePath,
+  chapterSlug,
+  includeBlockIds,
+}) {
+  const rows = tableBodyRows(node);
+  if (rows.length === 0) {
+    if (includeBlockIds && !includeBlockIds.has(id)) return false;
+    setDataAttribute(node, "data-openpress-block-id", id);
+    blocks.push({
+      id,
+      kind: "element",
+      name: "table",
+      text: textContent(node).trim() || undefined,
+      filePath,
+      chapterSlug,
+      source: sourcePosition(node.position),
+    });
+    return "skip";
+  }
+
+  const rowRecords = rows.map((row, index) => ({
+    id: `${id}-r${index}`,
+    node: row,
+    index,
+  }));
+  const selected = includeBlockIds
+    ? rowRecords.filter((row) => includeBlockIds.has(row.id))
+    : rowRecords;
+  if (selected.length === 0) return false;
+
+  setDataAttribute(node, "data-openpress-table-id", id);
+  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);
+
+  for (const row of selected) {
+    setDataAttribute(row.node, "data-openpress-block-id", row.id);
+    blocks.push({
+      id: row.id,
+      kind: "table-row",
+      name: "table-row",
+      text: textContent(row.node).trim() || undefined,
+      filePath,
+      chapterSlug,
+      tableId: id,
+      rowIndex: row.index,
+      source: sourcePosition(row.node.position ?? node.position),
+    });
+  }
+  return "skip";
+}
+
 export function remarkBlockOnlyMdx(options = {}) {
   const filePath = String(options.filePath ?? "document.mdx");
 
@@ -227,7 +313,7 @@ function normalizeSingleLineDisplayMath(source) {
 
 function blockInfo(node) {
   if (node?.type === "element" && PAGINABLE_TAGS.has(node.tagName)) {
-    return { kind: "element", name: node.tagName };
+    return { kind: "element", name: node.tagName, text: headingText(node) };
   }
   if (node?.type === "element" && node.tagName === "span" && hasClassName(node, "katex-display")) {
     return { kind: "element", name: "math" };
@@ -238,6 +324,130 @@ function blockInfo(node) {
   return null;
 }
 
+function applyListItemBlocks({
+  node,
+  id,
+  blocks,
+  filePath,
+  chapterSlug,
+  includeBlockIds,
+}) {
+  const items = listItems(node);
+  if (items.length === 0) {
+    if (includeBlockIds && !includeBlockIds.has(id)) return false;
+    setDataAttribute(node, "data-openpress-block-id", id);
+    blocks.push({
+      id,
+      kind: "element",
+      name: node.tagName,
+      text: textContent(node).trim() || undefined,
+      filePath,
+      chapterSlug,
+      source: sourcePosition(node.position),
+    });
+    return "skip";
+  }
+
+  const itemRecords = items.map((item, index) => ({
+    id: `${id}-i${index}`,
+    node: item,
+    index,
+  }));
+  const selected = includeBlockIds
+    ? itemRecords.filter((item) => includeBlockIds.has(item.id))
+    : itemRecords;
+  if (selected.length === 0) return false;
+
+  setDataAttribute(node, "data-openpress-list-id", id);
+
+  // For ordered lists, continuation pages must keep numbering picking up
+  // from the first surviving item. `start` is the 1-based number of the
+  // first `<li>` rendered, so if the original list had `start="5"` and we
+  // dropped the first three items, continuation starts at 5 + 3 = 8.
+  if (node.tagName === "ol" && selected[0]?.index > 0) {
+    const baseStart = Number(node.properties?.start ?? 1);
+    const continuationStart = baseStart + selected[0].index;
+    node.properties = { ...node.properties, start: continuationStart };
+  }
+
+  const selectedNodes = new Set(selected.map((item) => item.node));
+  pruneUnselectedListItems(node, new Set(itemRecords.map((item) => item.node)), selectedNodes);
+
+  for (const item of selected) {
+    setDataAttribute(item.node, "data-openpress-block-id", item.id);
+    blocks.push({
+      id: item.id,
+      kind: "list-item",
+      name: "list-item",
+      text: textContent(item.node).trim() || undefined,
+      filePath,
+      chapterSlug,
+      listId: id,
+      listTag: node.tagName,
+      itemIndex: item.index,
+      source: sourcePosition(item.node.position ?? node.position),
+    });
+  }
+  return "skip";
+}
+
+function listItems(list) {
+  if (list?.type !== "element") return [];
+  if (list.tagName !== "ul" && list.tagName !== "ol") return [];
+  return (list.children ?? []).filter((child) => child?.type === "element" && child.tagName === "li");
+}
+
+function pruneUnselectedListItems(node, itemNodes, selectedNodes) {
+  if (!Array.isArray(node?.children)) return;
+  node.children = node.children.filter((child) => {
+    if (!itemNodes.has(child)) return true;
+    return selectedNodes.has(child);
+  });
+}
+
+function tableBodyRows(table) {
+  if (table?.type !== "element" || table.tagName !== "table") return [];
+  const rows = [];
+  for (const child of table.children ?? []) {
+    if (child?.type === "element" && child.tagName === "tbody") {
+      for (const row of child.children ?? []) {
+        if (row?.type === "element" && row.tagName === "tr") rows.push(row);
+      }
+    }
+  }
+  if (rows.length > 0) return rows;
+  return (table.children ?? []).filter((child) => child?.type === "element" && child.tagName === "tr");
+}
+
+function pruneUnselectedTableRows(node, rowNodes, selectedNodes) {
+  if (!Array.isArray(node?.children)) return;
+  node.children = node.children.filter((child) => {
+    if (!rowNodes.has(child)) return true;
+    return selectedNodes.has(child);
+  });
+  for (const child of node.children) pruneUnselectedTableRows(child, rowNodes, selectedNodes);
+}
+
+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";
+  });
+}
+
+function headingText(node) {
+  if (!/^h[1-6]$/.test(String(node?.tagName ?? ""))) return undefined;
+  return textContent(node).trim() || undefined;
+}
+
+function normalizeBlockAttributes(value) {
+  if (!value) return new Map();
+  if (value instanceof Map) return value;
+  if (typeof value === "object") return new Map(Object.entries(value));
+  return new Map();
+}
+
 function hasClassName(node, className) {
   const raw = node?.properties?.className;
   if (Array.isArray(raw)) return raw.includes(className);
@@ -269,6 +479,7 @@ function visit(node, visitor) {
 function filterTree(node, visitor) {
   const keep = visitor(node);
   if (!keep) return false;
+  if (keep === "skip") return true;
   if (!Array.isArray(node?.children)) return true;
   node.children = node.children.filter((child) => filterTree(child, visitor));
   return true;

package/engine/react/measurement-css.mjs

@@ -2,8 +2,8 @@ import fs from "node:fs/promises";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { buildComponentsCss, buildContentCss } from "../file-utils.mjs";
-import { buildChapterScopedCss } from "./chapter-css.mjs";
+import { buildComponentsCss, buildContentCss } from "../runtime/file-utils.mjs";
+import { buildSectionScopedCss } from "./section-css.mjs";
 
 const require = createRequire(import.meta.url);
 
@@ -15,7 +15,7 @@ export async function buildReactMeasurementCss(root, config, workspace) {
   parts.push(await buildContentCss(root, config));
   parts.push("\n/* === public/openpress/components.css === */\n");
   parts.push(await buildComponentsCss(root, config));
-  const chapterCss = await buildChapterScopedCss(workspace);
+  const chapterCss = await buildSectionScopedCss(workspace);
   if (chapterCss.trim()) {
     parts.push("\n/* === public/openpress/chapter-scoped.css === */\n");
     parts.push(chapterCss);

package/engine/react/pagination/allocator.mjs

@@ -0,0 +1,122 @@
+import { DEFAULT_PAGE_SAFE_HEIGHT_PX } from "../pagination-constants.mjs";
+import { singleColumnRegionStream } from "./regions.mjs";
+
+// Pure region-based block allocator.
+//
+// Greedy bin-packing: walk measured blocks in order, append to the current
+// 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) {
+  const filled = [];
+  const warnings = [];
+  let current = regionStream.next();
+  if (!current) {
+    return { regions: filled, warnings: [{ code: "out-of-regions" }] };
+  }
+  let currentBlockIds = [];
+  let currentHeight = 0;
+
+  const flush = () => {
+    if (currentBlockIds.length === 0) return;
+    filled.push({
+      regionId: current.id,
+      pageIndex: current.pageIndex,
+      columnIndex: current.columnIndex,
+      blockIds: currentBlockIds,
+    });
+    currentBlockIds = [];
+    currentHeight = 0;
+  };
+
+  for (const block of measuredBlocks ?? []) {
+    const id = String(block?.id ?? "");
+    if (!id) continue;
+    const height = Math.max(0, Number(block.height) || 0);
+
+    if (height > current.capacity) {
+      warnings.push({
+        code: "block-overflows-region",
+        blockId: id,
+        height,
+        regionCapacity: current.capacity,
+        regionId: current.id,
+        pageIndex: current.pageIndex,
+      });
+    }
+
+    if (currentBlockIds.length > 0 && currentHeight + height > current.capacity) {
+      flush();
+      const next = regionStream.next();
+      if (!next) {
+        warnings.push({ code: "out-of-regions", blockId: id });
+        break;
+      }
+      current = next;
+    }
+
+    currentBlockIds.push(id);
+    currentHeight += height;
+  }
+
+  flush();
+  return { regions: filled, warnings };
+}
+
+// Derive a flat pages[] view from filled regions. Blocks within a page are
+// emitted in column order (col 0, col 1, ...) — matching how readers consume
+// a multi-column page (left-to-right, top-to-bottom).
+export function pagesFromRegions(filledRegions) {
+  const byPage = new Map();
+  for (const region of filledRegions) {
+    if (!byPage.has(region.pageIndex)) byPage.set(region.pageIndex, []);
+    byPage.get(region.pageIndex).push(region);
+  }
+  const pages = [];
+  for (const [pageIndex, regionsOnPage] of [...byPage.entries()].sort((a, b) => a[0] - b[0])) {
+    const sorted = regionsOnPage.slice().sort((a, b) => a.columnIndex - b.columnIndex);
+    const blockIds = sorted.flatMap((r) => r.blockIds);
+    pages.push({
+      pageIndex,
+      blockIds,
+      breakAfter: blockIds.at(-1),
+    });
+  }
+  return pages;
+}
+
+// Public wrapper preserving the legacy (blocks, { pageSafeHeightPx }) signature.
+// New code can pass a `regions` stream directly to opt into multi-column or
+// heterogeneous layouts.
+export function paginateMeasuredBlocks(measuredBlocks, options = {}) {
+  const { pageSafeHeightPx = DEFAULT_PAGE_SAFE_HEIGHT_PX, regions } = options;
+  const safeHeight = positiveNumber(pageSafeHeightPx, DEFAULT_PAGE_SAFE_HEIGHT_PX);
+  const stream = regions ?? singleColumnRegionStream({ pageSafeHeightPx: safeHeight });
+  const { regions: filledRegions, warnings } = allocateBlocksToRegions(measuredBlocks, stream);
+  const pages = pagesFromRegions(filledRegions);
+  return {
+    pages,
+    regions: filledRegions,
+    warnings: warnings.map((w) => mapWarning(w, safeHeight)),
+  };
+}
+
+// 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.
+function mapWarning(warning, pageSafeHeightPx) {
+  if (warning.code === "block-overflows-region") {
+    return {
+      code: "block-overflows-page",
+      blockId: warning.blockId,
+      height: warning.height,
+      pageSafeHeightPx,
+    };
+  }
+  return warning;
+}
+
+function positiveNumber(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : fallback;
+}

package/engine/react/pagination/regions.mjs

@@ -0,0 +1,81 @@
+// A Region is a fillable area on a page — the engine treats pagination as a
+// stream of regions consumed in order. One single-column page is "one region";
+// a two-column page is two regions on the same pageIndex; a newspaper page
+// could be three (main-left, main-right, sidebar).
+//
+// A RegionStream is a lazy iterator that yields regions on demand. The
+// allocator pulls the next region when the current one is full. This makes
+// "multi-column" and "newspaper-style mixed layout" the same code path as
+// single-column — only the stream differs.
+//
+// Shape:
+//   Region = { id: string, capacity: number, pageIndex: number, columnIndex: number }
+//   RegionStream = { next(): Region } | Iterable<Region>
+
+/**
+ * Default region stream: an infinite sequence of single-column pages.
+ * Equivalent to today's "one safe-height page after another" behavior.
+ */
+export function singleColumnRegionStream({ pageSafeHeightPx }) {
+  return iteratorFromGenerator(function* () {
+    let pageIndex = 0;
+    while (true) {
+      yield {
+        id: `page-${pageIndex}-col-0`,
+        capacity: pageSafeHeightPx,
+        pageIndex,
+        columnIndex: 0,
+      };
+      pageIndex++;
+    }
+  });
+}
+
+/**
+ * Multi-column region stream: each page yields `columnCount` regions in order,
+ * all sharing the same pageIndex but with increasing columnIndex.
+ *
+ * Blocks fill column 0 first, then column 1, then advance to the next page's
+ * column 0 — same greedy semantics as single-column, just more regions per page.
+ */
+export function multiColumnRegionStream({ pageSafeHeightPx, columnCount }) {
+  const cols = Math.max(1, Math.floor(columnCount) || 1);
+  return iteratorFromGenerator(function* () {
+    let pageIndex = 0;
+    while (true) {
+      for (let col = 0; col < cols; col++) {
+        yield {
+          id: `page-${pageIndex}-col-${col}`,
+          capacity: pageSafeHeightPx,
+          pageIndex,
+          columnIndex: col,
+        };
+      }
+      pageIndex++;
+    }
+  });
+}
+
+/**
+ * Build a region stream from an explicit list of regions. Useful for
+ * heterogeneous layouts (e.g. a research-article first page with a wide
+ * abstract region on top + two narrow columns below). Stream ends when
+ * the list is exhausted — the caller is responsible for providing enough
+ * regions; the allocator emits an `out-of-regions` warning otherwise.
+ */
+export function fixedRegionStream(regions) {
+  const list = Array.isArray(regions) ? regions : [];
+  return iteratorFromGenerator(function* () {
+    for (const region of list) yield region;
+  });
+}
+
+function iteratorFromGenerator(genFn) {
+  const iter = genFn();
+  return {
+    next() {
+      const { value, done } = iter.next();
+      return done ? null : value;
+    },
+  };
+}

package/engine/react/pagination.mjs

@@ -1,121 +1,9 @@
-import { chromium } from "playwright";
-import {
-  DEFAULT_PAGE_SAFE_HEIGHT_PX,
-  PAGE_BODY_FIT_SAFETY_MAX_PX,
-  PAGE_BODY_FIT_SAFETY_RATIO,
-} from "./pagination-constants.mjs";
-
-const DEFAULT_VIEWPORT = { width: 794, height: 1123 };
-
-export function paginateMeasuredBlocks(measuredBlocks, { pageSafeHeightPx = DEFAULT_PAGE_SAFE_HEIGHT_PX } = {}) {
-  const safeHeight = positiveNumber(pageSafeHeightPx, DEFAULT_PAGE_SAFE_HEIGHT_PX);
-  const pages = [];
-  const warnings = [];
-  let currentBlockIds = [];
-  let currentHeight = 0;
-
-  for (const block of measuredBlocks ?? []) {
-    const id = String(block?.id ?? "");
-    if (!id) continue;
-    const height = Math.max(0, Number(block.height) || 0);
-
-    if (height > safeHeight) {
-      warnings.push({
-        code: "block-overflows-page",
-        blockId: id,
-        height,
-        pageSafeHeightPx: safeHeight,
-      });
-    }
-
-    if (currentBlockIds.length > 0 && currentHeight + height > safeHeight) {
-      pages.push(pageRecord(pages.length, currentBlockIds));
-      currentBlockIds = [];
-      currentHeight = 0;
-    }
-
-    currentBlockIds.push(id);
-    currentHeight += height;
-  }
-
-  if (currentBlockIds.length > 0) {
-    pages.push(pageRecord(pages.length, currentBlockIds));
-  }
-
-  return { pages, warnings };
-}
-
-export async function measureBlocksInChromium({
-  html,
-  css = "",
-  pageSafeHeightPx,
-  viewport = DEFAULT_VIEWPORT,
-} = {}) {
-  const browser = await chromium.launch();
-  try {
-    const page = await browser.newPage({ viewport });
-    await page.setContent(measurementDocument(html, css), { waitUntil: "load" });
-    await page.evaluate(async () => {
-      if (document.fonts?.ready) await document.fonts.ready;
-    });
-    const measurements = await page.evaluate(() => (
-      Array.from(document.querySelectorAll("[data-openpress-block-id]")).map((element) => ({
-        id: element.getAttribute("data-openpress-block-id"),
-        height: element.getBoundingClientRect().height,
-      }))
-    ));
-    const safeHeight = positiveNumber(pageSafeHeightPx, null)
-      ?? await measurePageSafeHeight(page)
-      ?? DEFAULT_PAGE_SAFE_HEIGHT_PX;
-    return {
-      measurements,
-      pageSafeHeightPx: safeHeight,
-      ...paginateMeasuredBlocks(measurements, { pageSafeHeightPx: safeHeight }),
-    };
-  } finally {
-    await browser.close();
-  }
-}
-
-async function measurePageSafeHeight(page) {
-  return page.evaluate(({ ratio, maxPx }) => {
-    const body = document.querySelector(".reader-page[data-page-kind='content'] .page-body")
-      ?? document.querySelector(".reader-page--content .page-body")
-      ?? document.querySelector(".page-body");
-    if (!body) return null;
-    const height = body.getBoundingClientRect().height;
-    if (!Number.isFinite(height) || height <= 0) return null;
-    const safetyInset = Math.min(maxPx, Math.max(0, height * ratio));
-    return Math.max(1, height - safetyInset);
-  }, {
-    ratio: PAGE_BODY_FIT_SAFETY_RATIO,
-    maxPx: PAGE_BODY_FIT_SAFETY_MAX_PX,
-  });
-}
-
-function pageRecord(pageIndex, blockIds) {
-  return {
-    pageIndex,
-    blockIds,
-    breakAfter: blockIds.at(-1),
-  };
-}
-
-function positiveNumber(value, fallback) {
-  const number = Number(value);
-  return Number.isFinite(number) && number > 0 ? number : fallback;
-}
-
-function measurementDocument(html = "", css = "") {
-  return `<!doctype html>
-<html>
-  <head>
-    <meta charset="utf-8">
-    <style>
-      body { margin: 0; }
-      ${css}
-    </style>
-  </head>
-  <body>${html}</body>
-</html>`;
-}
+// Public surface for the build-time region allocator.
+//
+// The Press Tree pipeline measures MdxArea capacities and block heights in
+// `engine/react/pipeline/frame-measurement.mjs` and runs allocation through
+// 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 { singleColumnRegionStream, multiColumnRegionStream, fixedRegionStream } from "./pagination/regions.mjs";