@open-press/core 0.6.0 → 0.7.0

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

@@ -0,0 +1,135 @@
+// Layer 2 — Press Tree Expansion.
+//
+// SSR-renders the user's Press tree with a PressContext provider that
+// supplies resolved sources and (optionally) allocation hints. Output:
+//   - rendered HTML (used by Layer 3 for measurement and Layer 5 for final)
+//   - extracted frame metadata (frameKey, role, chrome, sequence position)
+//   - per-frame MdxArea slots (chainId, sequence index within frame)
+//
+// Frames are discovered by parsing the rendered HTML for elements with the
+// `data-openpress-frame-key` attribute. This works because <Frame> renders
+// to a deterministic `<section>` with that attribute set.
+
+import React from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+
+const FRAME_OPEN_RE = /<section\b([^>]*)\bdata-openpress-frame-key="([^"]+)"([^>]*)>/g;
+const ATTR_RE = (name) => new RegExp(`\\b${name}="([^"]*)"`);
+
+/**
+ * Render the Press tree and extract frame structure.
+ *
+ * @param {object} opts
+ * @param {React.ComponentType} opts.Press        The user's default-exported Press component.
+ * @param {object} opts.PressContext              The PressContext from @open-press/core.
+ * @param {Record<string, object>} opts.sources   Resolved sources keyed by sourceId.
+ * @param {object|null} opts.hints                Allocation hints (or null on first pass).
+ * @param {object|null} opts.allocation           FrameAllocation map (or null for measurement).
+ * @returns {{ html: string, frames: Array<FrameInstance> }}
+ */
+export function expandPressTree({ Press: UserPress, PressContext, sources, hints = null, allocation = null, toc = null }) {
+  const html = renderToStaticMarkup(
+    React.createElement(
+      PressContext.Provider,
+      { value: { sources, allocation, hints, toc } },
+      React.createElement(UserPress),
+    ),
+  );
+
+  const frames = extractFrames(html);
+  enforceUniqueFrameKeys(frames);
+  return { html, frames };
+}
+
+function extractFrames(html) {
+  const frames = [];
+  let match;
+  FRAME_OPEN_RE.lastIndex = 0;
+  while ((match = FRAME_OPEN_RE.exec(html)) !== null) {
+    const attrsBefore = match[1] ?? "";
+    const frameKey = match[2];
+    const attrsAfter = match[3] ?? "";
+    const allAttrs = `${attrsBefore} ${attrsAfter}`;
+    const role = pickAttr(allAttrs, "data-frame-role") || undefined;
+    const chromeRaw = pickAttr(allAttrs, "data-frame-chrome");
+    const chrome = chromeRaw === "false" ? false : true;
+    const openIndex = match.index;
+    const sectionHtml = sliceSection(html, openIndex);
+    const mdxAreas = extractMdxAreas(sectionHtml);
+    frames.push({
+      frameKey,
+      role,
+      chrome,
+      mdxAreas,
+      htmlStart: openIndex,
+      htmlEnd: openIndex + sectionHtml.length,
+      html: sectionHtml,
+    });
+  }
+  return frames;
+}
+
+const MDX_AREA_RE = /<([a-z][a-z0-9-]*)\b([^>]*)\bdata-openpress-mdx-area="true"([^>]*)>/gi;
+
+function extractMdxAreas(sectionHtml) {
+  const areas = [];
+  let match;
+  MDX_AREA_RE.lastIndex = 0;
+  while ((match = MDX_AREA_RE.exec(sectionHtml)) !== null) {
+    const attrs = `${match[2] ?? ""} ${match[3] ?? ""}`;
+    const chainId = pickAttr(attrs, "data-openpress-mdx-area-chain");
+    const overflow = pickAttr(attrs, "data-openpress-mdx-area-overflow") || "extend";
+    if (!chainId) continue;
+    const indexInFrame = areas.filter((a) => a.chainId === chainId).length;
+    areas.push({ chainId, overflow, indexInFrame, indexAcrossFrame: areas.length });
+  }
+  return areas;
+}
+
+function pickAttr(attrs, name) {
+  const match = ATTR_RE(name).exec(attrs);
+  return match ? match[1] : "";
+}
+
+// Find the end of a <section> opening at `start`, returning the full
+// `<section ...>...</section>` substring. Handles nested <section> elements
+// by depth-counting.
+function sliceSection(html, start) {
+  const sectionOpen = /<section\b[^>]*>/g;
+  const sectionClose = /<\/section\s*>/g;
+  sectionOpen.lastIndex = start + 1;
+  sectionClose.lastIndex = start + 1;
+  let depth = 1;
+  while (depth > 0) {
+    const nextOpen = sectionOpen.exec(html);
+    const nextClose = sectionClose.exec(html);
+    if (!nextClose) {
+      throw new Error(`Unterminated <section> in Press tree HTML near offset ${start}`);
+    }
+    if (nextOpen && nextOpen.index < nextClose.index) {
+      depth += 1;
+      sectionClose.lastIndex = nextOpen.index + 1;
+      continue;
+    }
+    depth -= 1;
+    if (depth === 0) {
+      return html.slice(start, nextClose.index + nextClose[0].length);
+    }
+    sectionOpen.lastIndex = nextClose.index + 1;
+  }
+  throw new Error(`Section depth balance bug at offset ${start}`);
+}
+
+function enforceUniqueFrameKeys(frames) {
+  const seen = new Map();
+  for (const frame of frames) {
+    if (seen.has(frame.frameKey)) {
+      const prior = seen.get(frame.frameKey);
+      throw new Error(
+        `Duplicate frameKey "${frame.frameKey}" found in Press tree. ` +
+          `First seen with role "${prior.role ?? "?"}", second with role "${frame.role ?? "?"}".`,
+      );
+    }
+    seen.set(frame.frameKey, frame);
+  }
+}

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

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { loadConfig } from "../config.mjs";
-import { collectSourceTextFiles } from "../source-text-tools.mjs";
+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;

package/engine/react/{chapter-css.mjs → section-css.mjs}

@@ -3,13 +3,16 @@ import postcss from "postcss";
 
 const UNSCOPED_RULE_PARENTS = new Set(["keyframes", "-webkit-keyframes", "page"]);
 
-export async function buildChapterScopedCss(workspace) {
+// Section-scoped CSS. Style files under `chapters/<slug>/styles/*.css` (in
+// the section-folders preset) are scoped to `[data-section-id="<slug>"]`.
+// Workspaces using other source presets do not get section-scoped CSS in v1.
+export async function buildSectionScopedCss(workspace) {
   const parts = [];
-  for (const chapter of workspace.chapters ?? []) {
-    for (const styleFile of chapter.styleFiles ?? []) {
+  for (const section of workspace.sections ?? workspace.chapters ?? []) {
+    for (const styleFile of section.styleFiles ?? []) {
       const source = await fs.readFile(styleFile.absolutePath, "utf8");
-      const scoped = await scopeChapterCss(source, {
-        chapterSlug: chapter.slug,
+      const scoped = await scopeSectionCss(source, {
+        sectionSlug: section.slug,
         from: styleFile.absolutePath,
       });
       if (!scoped.trim()) continue;
@@ -21,10 +24,10 @@ export async function buildChapterScopedCss(workspace) {
   return parts.join("\n");
 }
 
-export async function scopeChapterCss(source, { chapterSlug, from = undefined } = {}) {
-  if (typeof source !== "string") throw new Error("scopeChapterCss requires a CSS source string.");
-  const slug = cssAttributeValue(chapterSlug);
-  const scope = `[data-chapter-slug="${slug}"]`;
+export async function scopeSectionCss(source, { sectionSlug, from = undefined } = {}) {
+  if (typeof source !== "string") throw new Error("scopeSectionCss requires a CSS source string.");
+  const slug = cssAttributeValue(sectionSlug);
+  const scope = `[data-section-id="${slug}"]`;
   const root = postcss.parse(source, { from });
 
   root.walkRules((rule) => {

package/engine/react/sources/heading-numbering.mjs

@@ -0,0 +1,132 @@
+// Heading numbering and outline emission for MDX sources.
+//
+// Pure functions called from `mdx-resolver.mjs` while walking each section's
+// compiled blocks. Produces:
+//   - `data-chapter` / `data-section` / `data-topic` attributes on heading
+//     blocks (h2/h3/h4)
+//   - stable IDs on the same blocks
+//   - outline entries (for TOC + reader navigation)
+//
+// Numbering state is per-source, advances forward through blocks in source
+// order. The caller threads `headingState` between calls.
+
+/**
+ * Build a fresh per-source heading state. One state object per call to
+ * `resolveSource` — counts subsection / topic indices and tracks whether
+ * this section has already seen its chapter heading.
+ */
+export function createHeadingState() {
+  return {
+    hasChapterHeading: false,
+    subsectionCounter: 0,
+    topicCounter: 0,
+  };
+}
+
+/**
+ * For one block emitted by the MDX compiler, decide whether it is a heading,
+ * what id/data-* attributes it should carry, and whether it adds an entry to
+ * the outline. Returns `null` for non-heading blocks.
+ *
+ * @param {object} opts
+ * @param {object} opts.block        The compiled block record.
+ * @param {string} opts.sourceId     Source registry key.
+ * @param {object} opts.section      Section descriptor (slug, title, …).
+ * @param {Array}  opts.outlineItems Mutable outline array — entries are pushed onto it.
+ * @param {number} opts.chapterNumber  1-based chapter index for this section.
+ * @param {string} opts.chapterLabel   Display label, e.g. `"#3"` or `"03"`.
+ * @param {object} opts.headingState   Per-source counter state from `createHeadingState`.
+ */
+export function headingAttributesForBlock({
+  block,
+  sourceId,
+  section,
+  outlineItems,
+  chapterNumber,
+  chapterLabel,
+  headingState,
+}) {
+  const title = String(block.text ?? "").trim();
+
+  if (block.name === "h2") {
+    const firstChapterHeading = !headingState.hasChapterHeading;
+    const id = firstChapterHeading ? `section-${section.slug}` : block.id;
+    const headingTitle = title || section.title || section.slug;
+    outlineItems.push({
+      id: `${sourceId}:${section.slug}:${block.id}`,
+      tocId: firstChapterHeading
+        ? `toc-${sourceId}-${section.slug}`
+        : `toc-${sourceId}-${section.slug}-${block.id}`,
+      depth: 0,
+      title: headingTitle,
+      label: chapterLabel,
+      sectionSlug: section.slug,
+      blockId: block.id,
+      href: `#${id}`,
+    });
+    headingState.hasChapterHeading = true;
+    headingState.subsectionCounter = 0;
+    headingState.topicCounter = 0;
+    return {
+      attributes: {
+        id,
+        "data-chapter": chapterLabel,
+      },
+      sectionTitle: firstChapterHeading ? headingTitle : undefined,
+    };
+  }
+
+  if (block.name === "h3") {
+    headingState.subsectionCounter += 1;
+    headingState.topicCounter = 0;
+    const label = `${chapterNumber}.${headingState.subsectionCounter}`;
+    outlineItems.push({
+      id: `${sourceId}:${section.slug}:${block.id}`,
+      tocId: `toc-${sourceId}-${section.slug}-${block.id}`,
+      depth: 1,
+      title: title || `Section ${label}`,
+      label,
+      sectionSlug: section.slug,
+      blockId: block.id,
+      href: `#${block.id}`,
+    });
+    return {
+      attributes: {
+        id: block.id,
+        "data-section": label,
+      },
+    };
+  }
+
+  if (block.name === "h4") {
+    headingState.topicCounter += 1;
+    const label = `${chapterNumber}.${Math.max(1, headingState.subsectionCounter)}.${headingState.topicCounter}`;
+    return {
+      attributes: {
+        id: block.id,
+        "data-topic": label,
+      },
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Build a fallback single-entry outline when a section has no h2/h3 headings
+ * the resolver could pick up. The outline still needs one row so the TOC
+ * doesn't lose the section.
+ */
+export function fallbackOutlineItems({ sourceId, section, chapterLabel, title, blocks }) {
+  const targetBlock = blocks[0];
+  return [{
+    id: `${sourceId}:${section.slug}`,
+    tocId: `toc-${sourceId}-${section.slug}`,
+    depth: 0,
+    title,
+    label: chapterLabel,
+    sectionSlug: section.slug,
+    blockId: targetBlock?.id,
+    href: `#section-${section.slug}`,
+  }];
+}