@open-press/core 0.6.0 → 0.7.1

package/engine/runtime/source-workspace.mjs

@@ -0,0 +1,186 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { loadReactDocumentEntry } from "../react/document-entry.mjs";
+
+export const REACT_MDX_CONTENT_EXTENSIONS = new Set([".mdx"]);
+
+export async function resolveActiveSourceWorkspace(config) {
+  const reactEntry = await loadReactDocumentEntry(config.root);
+  if (!reactEntry) {
+    throw new Error(
+      "React/MDX document entry not found. Expected document/index.tsx with a Press default export before using workspace source tools.",
+    );
+  }
+  const contentRoots = contentRootsFromSources(reactEntry.sources, reactEntry.config);
+  const sourceDir = firstDirectoryRoot(contentRoots) ?? reactEntry.config.paths.documentRoot;
+
+  return {
+    kind: "react-mdx",
+    checkedName: "react-source",
+    config: reactEntry.config,
+    entryPath: reactEntry.entryPath,
+    sourceDir,
+    contentRoots,
+    contentExtensions: REACT_MDX_CONTENT_EXTENSIONS,
+    contentLabel: "React MDX chapter source",
+    missingCode: "react-source.missing",
+    emptyCode: "react-source.empty",
+    missingMessage: "Registered React MDX sources do not exist yet; create the files or roots declared in document/index.tsx `sources` before running export.",
+    emptyMessage: "Registered React MDX sources contain no `*.mdx` files; the document will export with zero source blocks.",
+  };
+}
+
+export async function collectActiveContentFiles(sourceWorkspace, { skipUnderscoreFiles = false } = {}) {
+  const files = [];
+  const seen = new Set();
+  for (const root of sourceWorkspace.contentRoots ?? [{ kind: "dir", absolutePath: sourceWorkspace.sourceDir }]) {
+    const visit = async (absolutePath) => {
+      if (seen.has(absolutePath)) return;
+      if (!sourceWorkspace.contentExtensions.has(path.extname(absolutePath))) return;
+      const name = path.basename(absolutePath);
+      if (skipUnderscoreFiles && name.startsWith("_")) return;
+      seen.add(absolutePath);
+      files.push({
+        absolutePath,
+        name,
+        relativePath: rootRelativePath(sourceWorkspace.config, absolutePath),
+        sourceRelativePath: path.relative(root.basePath ?? path.dirname(absolutePath), absolutePath).replaceAll("\\", "/"),
+        text: await fs.readFile(absolutePath, "utf8"),
+      });
+    };
+    if (root.kind === "file") {
+      try {
+        const stat = await fs.stat(root.absolutePath);
+        if (stat.isFile()) await visit(root.absolutePath);
+      } catch (error) {
+        if (error?.code !== "ENOENT") throw error;
+      }
+      continue;
+    }
+    await walkFiles(root.absolutePath, visit);
+  }
+  files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  return files;
+}
+
+export async function sourceDirectoryExists(sourceWorkspace) {
+  const roots = sourceWorkspace.contentRoots ?? [{ kind: "dir", absolutePath: sourceWorkspace.sourceDir }];
+  for (const root of roots) {
+    try {
+      const stat = await fs.stat(root.absolutePath);
+      if (root.kind === "file" ? stat.isFile() : stat.isDirectory()) return true;
+    } catch (error) {
+      if (error?.code === "ENOENT") continue;
+      throw error;
+    }
+  }
+  return false;
+}
+
+export function rootRelativePath(config, absolutePath) {
+  return path.relative(config.root, absolutePath).replaceAll("\\", "/");
+}
+
+async function walkFiles(directory, visit) {
+  let entries;
+  try {
+    entries = await fs.readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return;
+    throw error;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    const absolutePath = path.join(directory, entry.name);
+    if (entry.isDirectory()) await walkFiles(absolutePath, visit);
+    else if (entry.isFile()) await visit(absolutePath);
+  }
+}
+
+function contentRootsFromSources(sources, config) {
+  const entries = Object.entries(sources ?? {});
+  if (entries.length === 0) {
+    return [{
+      kind: "dir",
+      absolutePath: config.paths.sourceDir,
+      basePath: config.paths.sourceDir,
+      sourceId: "default",
+      preset: "section-folders",
+    }];
+  }
+
+  const roots = [];
+  for (const [sourceId, descriptor] of entries) {
+    if (!descriptor || descriptor.type !== "mdx") continue;
+    if (descriptor.preset === "section-folders") {
+      roots.push(directoryRoot(config, descriptor.root ?? "chapters", sourceId, descriptor.preset));
+      continue;
+    }
+    if (descriptor.preset === "section-files") {
+      roots.push(directoryRoot(config, descriptor.root ?? "content", sourceId, descriptor.preset));
+      continue;
+    }
+    if (descriptor.preset === "file-list") {
+      for (const file of descriptor.files ?? []) {
+        roots.push(fileRoot(config, file, sourceId, descriptor.preset));
+      }
+      continue;
+    }
+  }
+  return dedupeRoots(roots);
+}
+
+function directoryRoot(config, rel, sourceId, preset) {
+  const absolutePath = resolveDocumentRelativePath(config.paths.documentRoot, rel, `Source "${sourceId}" ${preset} root`);
+  return {
+    kind: "dir",
+    absolutePath,
+    basePath: absolutePath,
+    sourceId,
+    preset,
+  };
+}
+
+function fileRoot(config, rel, sourceId, preset) {
+  if (typeof rel !== "string" || !rel.trim()) {
+    throw new Error(`Source "${sourceId}" file-list contains an empty or invalid entry.`);
+  }
+  if (!rel.endsWith(".mdx")) {
+    throw new Error(`Source "${sourceId}" file-list path "${rel}" must end with .mdx.`);
+  }
+  const absolutePath = resolveDocumentRelativePath(config.paths.documentRoot, rel, `Source "${sourceId}" file-list path "${rel}"`);
+  return {
+    kind: "file",
+    absolutePath,
+    basePath: path.dirname(absolutePath),
+    sourceId,
+    preset,
+  };
+}
+
+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;
+}
+
+function dedupeRoots(roots) {
+  const seen = new Set();
+  const out = [];
+  for (const root of roots) {
+    const key = `${root.kind}:${root.absolutePath}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(root);
+  }
+  return out;
+}
+
+function firstDirectoryRoot(roots) {
+  return roots.find((root) => root.kind === "dir")?.absolutePath ?? null;
+}

package/engine/{validation.mjs → runtime/validation.mjs}

@@ -109,27 +109,19 @@ export async function validateWorkspace(root) {
     }
   }
 
-  mark("react-pagination");
+  mark("react-source");
   const documentJsonPath = path.join(activeConfig.paths.publicDir, "document.json");
   const exportedDocument = await readJsonIfExists(documentJsonPath);
-  const paginationWarnings = exportedDocument?.source?.pagination?.warnings;
-  if (Array.isArray(paginationWarnings)) {
-    for (const warning of paginationWarnings) {
-      if (warning?.code !== "block-overflows-page") continue;
-      const warningPath = typeof warning.path === "string" && warning.path
-        ? path.resolve(activeConfig.root, warning.path)
-        : documentJsonPath;
+  const pressWarnings = exportedDocument?.source?.warnings;
+  if (Array.isArray(pressWarnings)) {
+    for (const warning of pressWarnings) {
+      const code = typeof warning?.code === "string" && warning.code ? warning.code : "warning";
       add(
         "warning",
-        "react-pagination.block-overflows-page",
-        `Block \`${warning.blockId ?? "(unknown)"}\` exceeds the configured page safe area during React pagination.`,
-        warningPath,
-        {
-          blockId: warning.blockId,
-          height: warning.height,
-          pageSafeHeightPx: warning.pageSafeHeightPx,
-          source: warning.source,
-        },
+        `react-source.${code}`,
+        pressWarningMessage(warning),
+        documentJsonPath,
+        warning,
       );
     }
   }
@@ -153,6 +145,16 @@ function findCommentMarkers(text) {
   return markers;
 }
 
+function pressWarningMessage(warning) {
+  if (warning?.code === "chain-overflowed") {
+    return `Content chain \`${warning.chainId ?? "(unknown)"}\` overflowed during Press Tree allocation.`;
+  }
+  if (warning?.code === "chain-has-no-area") {
+    return `Content chain \`${warning.chainId ?? "(unknown)"}\` has blocks but no matching MdxArea.`;
+  }
+  return `Press Tree export warning: ${warning?.code ?? "warning"}.`;
+}
+
 async function readJsonIfExists(filePath) {
   try {
     return JSON.parse(await fs.readFile(filePath, "utf8"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-press/core",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "type": "module",
   "description": "open-press core — runtime primitives, CLI, and render pipeline for AI-first fixed-layout documents.",
   "license": "MIT",
@@ -26,7 +26,10 @@
   "main": "./src/openpress/core/index.tsx",
   "types": "./src/openpress/core/index.tsx",
   "exports": {
-    ".": "./src/openpress/core/index.tsx"
+    ".": "./src/openpress/core/index.tsx",
+    "./mdx": "./src/openpress/mdx/index.ts",
+    "./manuscript": "./src/openpress/manuscript/index.tsx",
+    "./numbering": "./src/openpress/numbering/index.ts"
   },
   "bin": {
     "open-press": "engine/cli.mjs"

package/src/openpress/anchorMap.ts

@@ -0,0 +1,27 @@
+// Anchor → page-index resolution shared between the public viewer and
+// the workbench. Lives in its own module so React Fast Refresh can keep
+// `PublicPage` / `HtmlWorkbench` HMR-clean (Fast Refresh expects component
+// files to export only components).
+
+import type { DisplayPage } from "./workbenchTypes";
+
+export function createAnchorPageMap(pages: DisplayPage[]) {
+  const map = new Map<string, number>();
+  pages.forEach((page, index) => {
+    page.anchors?.forEach((anchor) => {
+      if (anchor && !map.has(anchor)) map.set(anchor, index);
+    });
+  });
+  return map;
+}
+
+export function resolveAnchorPageIndex(
+  anchorPageMap: Map<string, number>,
+  pageCount: number,
+  anchorId: string,
+  pageIndex?: number,
+): number | null {
+  if (typeof pageIndex === "number" && Number.isInteger(pageIndex) && pageIndex >= 0 && pageIndex < pageCount) return pageIndex;
+  const mapped = anchorPageMap.get(anchorId);
+  return mapped === undefined ? null : mapped;
+}

package/src/openpress/core/Frame.tsx

@@ -0,0 +1,80 @@
+import { useContext, type ReactNode } from "react";
+import { FrameContext, type FrameContextValue } from "./FrameContext";
+import { PressContext } from "./Press";
+import type { FrameProps } from "./types";
+
+// Substring reserved for the overflow extension pipeline.
+const RESERVED_EXTENDED = ":extended:";
+
+export const FRAME_MARKER: unique symbol = Symbol.for("@open-press/core:Frame");
+
+function classNames(...values: Array<string | undefined>) {
+  const joined = values.filter(Boolean).join(" ");
+  return joined.length > 0 ? joined : undefined;
+}
+
+export function Frame({
+  frameKey,
+  role,
+  chrome = true,
+  className,
+  children,
+  ...rest
+}: FrameProps) {
+  if (!frameKey || !String(frameKey).trim()) {
+    throw new Error("Frame requires a non-empty frameKey.");
+  }
+  if (frameKey && frameKey.includes(RESERVED_EXTENDED)) {
+    throw new Error(
+      `Frame frameKey="${frameKey}" contains reserved substring ":extended:". ` +
+        `This pattern is reserved for the overflow-extension pipeline.`,
+    );
+  }
+
+  const press = useContext(PressContext);
+  const allocation = press?.allocation ?? null;
+  const frameAllocation = frameKey && allocation ? allocation[frameKey] : undefined;
+
+  // Mutable per-render counter. SSR renders a Frame exactly once, so a plain
+  // object is fine — no useRef needed.
+  const areaCounts: Record<string, number> = {};
+  const frameContextValue: FrameContextValue = {
+    frameKey: frameKey ?? "",
+    consumeArea(chainId: string): ReactNode | null {
+      const index = areaCounts[chainId] ?? 0;
+      areaCounts[chainId] = index + 1;
+      if (!frameAllocation) return null;
+      const chainSlots = frameAllocation[chainId];
+      if (!chainSlots) return null;
+      return chainSlots[index] ?? null;
+    },
+  };
+
+  const pageKind = derivePageKind(role);
+
+  return (
+    <FrameContext.Provider value={frameContextValue}>
+      <section
+        {...(rest as Record<string, unknown>)}
+        className={classNames("reader-page", className)}
+        data-openpress-frame-key={frameKey}
+        data-frame-role={role}
+        data-page-kind={pageKind}
+        data-frame-chrome={chrome ? "true" : "false"}
+        data-page-footer={chrome ? "true" : "false"}
+      >
+        {children}
+      </section>
+    </FrameContext.Provider>
+  );
+}
+
+(Frame as unknown as { openpressMarker: typeof FRAME_MARKER }).openpressMarker = FRAME_MARKER;
+
+function derivePageKind(role: string | undefined): string | undefined {
+  if (!role) return undefined;
+  const trimmed = role.trim();
+  if (!trimmed) return undefined;
+  const lastDot = trimmed.lastIndexOf(".");
+  return lastDot === -1 ? trimmed : trimmed.slice(lastDot + 1);
+}

package/src/openpress/core/FrameContext.tsx

@@ -0,0 +1,19 @@
+import { createContext, type ReactNode } from "react";
+
+// FrameContext is the runtime channel between Frame and its descendant
+// MdxArea instances. Frame creates one of these on each render; MdxArea
+// reads it to claim its slot of allocated content.
+//
+// "Claiming" is order-sensitive: the first <MdxArea chainId="X"> rendered
+// inside a Frame takes areaIndex 0 for chain X, the next takes index 1,
+// and so on. Empty Frames (no allocation) return null, which renders the
+// MdxArea as a measurement placeholder.
+
+export interface FrameContextValue {
+  frameKey: string;
+  // Consume the next allocation slot for this chainId. Returns null if the
+  // frame has no allocation (measurement pass) or no blocks for this chain.
+  consumeArea(chainId: string): ReactNode | null;
+}
+
+export const FrameContext = createContext<FrameContextValue | null>(null);

package/src/openpress/core/MdxArea.tsx

@@ -0,0 +1,35 @@
+import { useContext, type ReactNode } from "react";
+import { FrameContext } from "./FrameContext";
+import type { MdxAreaProps } from "./types";
+
+function classNames(...values: Array<string | undefined>) {
+  const joined = values.filter(Boolean).join(" ");
+  return joined.length > 0 ? joined : undefined;
+}
+
+export function MdxArea({
+  chainId,
+  overflow = "extend",
+  className,
+  ...rest
+}: MdxAreaProps) {
+  const frame = useContext(FrameContext);
+
+  let blocks: ReactNode | null = null;
+  if (frame) {
+    blocks = frame.consumeArea(chainId);
+  }
+
+  return (
+    <div
+      {...(rest as Record<string, unknown>)}
+      className={classNames("openpress-mdx-area", className)}
+      data-openpress-mdx-area="true"
+      data-openpress-mdx-area-chain={chainId}
+      data-openpress-mdx-area-overflow={overflow}
+      data-openpress-mdx-area-empty={blocks == null ? "true" : undefined}
+    >
+      {blocks}
+    </div>
+  );
+}

package/src/openpress/core/Press.tsx

@@ -0,0 +1,34 @@
+import { createContext, Fragment, type ReactNode } from "react";
+import type { FrameAllocation, ResolvedSource, TocEntry } from "./types";
+
+// Marker the engine uses to distinguish a Press default export from any other
+// React component. Workspaces register a default export whose `type` is this
+// `Press` component; the engine identity-checks against it.
+export const PRESS_MARKER: unique symbol = Symbol.for("@open-press/core:Press");
+
+// Allocation hints feed Layer 4 results back to Layer 2 so helpers like
+// <Sections> can emit the correct number of pages per chain. Null during
+// the first pass; populated after the allocator has decided how many
+// frames each chain needs.
+export interface AllocationHints {
+  totalPagesPerChain: Record<string, number>;
+}
+
+export interface PressContextValue {
+  sources: Record<string, ResolvedSource>;
+  // Allocation map keyed by frameKey -> chainId -> areaIndex -> blocks.
+  // null during measurement passes; populated during final render.
+  allocation: FrameAllocation | null;
+  // Allocation hints fed back from Layer 4 to Layer 2 helpers. null on
+  // the first measurement pass.
+  hints: AllocationHints | null;
+  toc: Record<string, TocEntry[]> | null;
+}
+
+export const PressContext = createContext<PressContextValue | null>(null);
+
+export function Press({ children }: { children: ReactNode }) {
+  return <Fragment>{children}</Fragment>;
+}
+
+(Press as unknown as { openpressMarker: typeof PRESS_MARKER }).openpressMarker = PRESS_MARKER;

package/src/openpress/core/index.tsx

@@ -1,20 +1,39 @@
-export {
-  BaseBackCoverPage,
-  BaseCallout,
-  BaseCoverPage,
-  BaseFigure,
-  BasePage,
-  BaseContentPage,
-  BaseTocPage,
-} from "./basePages";
+// @open-press/core — Press tree primitives.
+//
+// Layout: this entry exports only the kernel. Source descriptors live in
+// `@open-press/core/mdx`; manuscript helpers live in
+// `@open-press/core/manuscript`. Keeping the surface small is intentional —
+// the engine is not allowed to know about higher-level conventions.
+
+export { Press, PressContext, PRESS_MARKER } from "./Press";
+export { Frame, FRAME_MARKER } from "./Frame";
+export { FrameContext } from "./FrameContext";
+export { MdxArea } from "./MdxArea";
+export { useSource } from "./useSource";
+export { BaseFigure, BaseCallout } from "./primitives";
+
 export type {
+  FrameProps,
+  FrameRole,
+  MdxAreaProps,
+  MdxAreaOverflow,
+  PressProps,
+  BaseFigureProps,
   BaseCalloutKind,
   BaseCalloutProps,
-  BaseFigureProps,
-  BasePageProps,
-  BaseContentPageProps,
-  BaseShellPageProps,
-  PageKind,
-  PageProps,
   Manifest,
+  // Source-side types are re-exported here for convenience so authors can
+  // import `ResolvedSource` from the same place they import primitives.
+  ResolvedSource,
+  SourceNode,
+  OutlineItem,
+  SourceFileRecord,
+  SourceBlock,
+  TocEntry,
+  MdxSourceDescriptor,
+  SourceDescriptor,
+  FrameAllocation,
 } from "./types";
+
+export type { PressContextValue, AllocationHints } from "./Press";
+export type { FrameContextValue } from "./FrameContext";

package/src/openpress/core/primitives.tsx

@@ -0,0 +1,23 @@
+import type { BaseCalloutProps, BaseFigureProps } from "./types";
+
+function classNames(...values: Array<string | undefined>) {
+  const joined = values.filter(Boolean).join(" ");
+  return joined.length > 0 ? joined : undefined;
+}
+
+export function BaseFigure({ caption, className, children, ...figureProps }: BaseFigureProps) {
+  return (
+    <figure {...figureProps} className={classNames("openpress-figure", className)}>
+      <div data-figure-body>{children}</div>
+      {caption === undefined ? null : <figcaption>{caption}</figcaption>}
+    </figure>
+  );
+}
+
+export function BaseCallout({ kind = "info", className, children, ...calloutProps }: BaseCalloutProps) {
+  return (
+    <aside {...calloutProps} className={classNames("openpress-callout", className)} data-callout-kind={kind}>
+      {children}
+    </aside>
+  );
+}