@open-press/core 1.2.1 → 1.3.1

package/engine/react/document-export.mjs

@@ -17,12 +17,13 @@ import { buildSectionScopedCss } from "./section-css.mjs";
 import { CORE_ENTRY, createReactSsrServer, loadReactDocumentEntry } from "./document-entry.mjs";
 import { buildReactMeasurementCss } from "./measurement-css.mjs";
 import { buildObjectEntities } from "./object-entities.mjs";
+import { resolvePageFoliosInHtml } from "./page-folio.mjs";
 import { allocateChains } from "./pipeline/allocate.mjs";
 import { measureFrames } from "./pipeline/frame-measurement.mjs";
 import { renderFinalPress } from "./pipeline/final-render.mjs";
 import { expandPressTree } from "./pipeline/press-tree.mjs";
 import { resolveAllSources } from "./sources/mdx-resolver.mjs";
-import { discoverSectionStyles } from "./style-discovery.mjs";
+import { discoverComponentsInRoots, discoverSectionStyles } from "./style-discovery.mjs";
 
 const MAX_ITERATIONS = 20;
 const PRESS_TYPES = new Set(["pages", "slides"]);
@@ -41,10 +42,10 @@ export async function exportReactDocument(root = ".", { syncAssets = true } = {}
     if (!entry) return null;
     if (!entry.Press) {
       throw new Error(
-        `OpenPress document entry ${entry.entryPath} must default-export a Press component (function) to export. ` +
-          `Legacy named exports (cover/toc/backCover) are not supported in v0.6 — see the Press Tree spec.`,
+        `OpenPress document entry ${entry.entryPath} must default-export a React component that renders one or more <Press> elements.`,
       );
     }
+    validateDiscoveredPressFolders(entry);
     // Resolve PressContext + Frame markers from the engine's loaded core module.
     // Use the absolute file path so the user's `import "@open-press/core"`
     // (resolved via vite alias) and our load hit the same module cache entry.
@@ -60,6 +61,9 @@ export async function exportReactDocument(root = ".", { syncAssets = true } = {}
     // workspace can host more than one chapter root.
     const sectionRoots = collectSectionRoots(entry.presses, entry.config.paths.documentRoot);
     const workspace = await discoverSectionStyles(workspaceRoot, entry.config, { sectionRoots });
+    const workspaceThemeRoots = collectWorkspaceThemeRoots(entry.presses, entry.config);
+    const workspaceComponentRoots = collectWorkspaceComponentRoots(entry.presses, entry.config);
+    const workspaceMediaRoots = collectWorkspaceMediaRoots(entry.presses, entry.config);
     const coreAuthorComponents = {};
     for (const name of ["MediaFigure", "ImageFigure"]) {
       if (typeof coreModule[name] === "function") coreAuthorComponents[name] = coreModule[name];
@@ -71,7 +75,10 @@ export async function exportReactDocument(root = ".", { syncAssets = true } = {}
 
     // Build measurement CSS once at the workspace level — shared by every
     // Press inside the Workspace.
-    const measurementCss = await buildReactMeasurementCss(workspaceRoot, entry.config, workspace);
+    const measurementCss = await buildReactMeasurementCss(workspaceRoot, entry.config, workspace, {
+      themeRoots: workspaceThemeRoots,
+      componentRoots: workspaceComponentRoots,
+    });
 
     // Write chapter-scoped CSS once (workspace shared). Every per-press
     // readerDocument references the same file via "/openpress/chapter-scoped.css".
@@ -148,7 +155,11 @@ export async function exportReactDocument(root = ".", { syncAssets = true } = {}
     await fs.writeFile(corpusPath, JSON.stringify(corpus), "utf8");
 
     if (syncAssets) {
-      await syncPublicAssets(workspaceRoot, entry.config.paths.publicDir, entry.config);
+      await syncPublicAssets(workspaceRoot, entry.config.paths.publicDir, entry.config, {
+        themeRoots: workspaceThemeRoots,
+        componentRoots: workspaceComponentRoots,
+        mediaRoots: workspaceMediaRoots,
+      });
     }
 
     const primary = pressResults[0];
@@ -188,24 +199,29 @@ async function exportSinglePress({
   // metadata overlaid. Press JSX page prop wins over the workspace page.
   const effectiveConfig = applyPressOverridesToConfig(entry.config, press.metadata);
   const documentRoot = effectiveConfig.paths.documentRoot;
+  const pressComponentRoots = componentRootsForPress(press, effectiveConfig);
+  const pressComponents = await loadComponentModules(
+    server,
+    await discoverComponentsInRoots(pressComponentRoots, documentRoot, "press"),
+  );
+  const resolvedComponents = {
+    ...globalComponents,
+    ...pressComponents,
+  };
+  const mediaRoots = mediaRootsForPress(press, effectiveConfig);
 
-  // Resolve sources for this press. The 1.0 contract reads them from
-  // <Press sources={[...]}>; the v0.x legacy path uses the synthesized
-  // record from `export const sources`.
+  // Resolve sources for this press. The contract reads them from
+  // <Press sources={[...]}>.
   const sourcesRecord = press.sources ?? {};
   const { resolved: sources, renderData: renderRegistry } = await resolveAllSources({
     sources: sourcesRecord,
     documentRoot,
-    globalComponents,
+    globalComponents: resolvedComponents,
   });
 
-  // Component the render pipeline drives. For Press elements captured
-  // by inspection (1.0 contract), wrap the captured element in a thin
-  // function component. For legacy projects without inspection data,
-  // fall back to the user's whole default export.
-  const PressComponent = press.element
-    ? () => press.element
-    : entry.Press;
+  // Component the render pipeline drives. Press elements are captured by
+  // inspection, then wrapped in a thin function component.
+  const PressComponent = () => press.element;
 
   // Iterative allocation loop (identical to v0.x — paginates until the
   // hints stabilise).
@@ -228,7 +244,7 @@ async function exportSinglePress({
       renderRegistry,
       css: measurementCss,
       baseHref: pathToFileURL(`${documentRoot}${path.sep}`).href,
-      mediaDir: path.join(documentRoot, "media"),
+      mediaDir: mediaRoots,
       captionNumbering: effectiveConfig.captionNumbering,
     });
     const alloc = allocateChains({
@@ -244,7 +260,7 @@ async function exportSinglePress({
       const blocks = measurement.blockHeights
         .slice(0, 8)
         .map((b) => `${b.id} h=${b.height.toFixed(0)}`);
-      process.stderr.write(`[allocator press=${slug || "(root)"} iter ${iteration}]\n`);
+      process.stderr.write(`[allocator press=${slug || "(missing-slug)"} iter ${iteration}]\n`);
       process.stderr.write(`  mdxAreas[0..4]: ${sample.join(" | ")}\n`);
       process.stderr.write(`  blocks[0..7]:   ${blocks.join(" | ")}\n`);
       process.stderr.write(`  hints:          ${JSON.stringify(alloc.hints.totalPagesPerChain)}\n`);
@@ -261,7 +277,7 @@ async function exportSinglePress({
   }
   if (allocation == null) {
     throw new Error(
-      `Allocation did not converge after ${MAX_ITERATIONS} iterations (press="${slug || "(root)"}"). ` +
+      `Allocation did not converge after ${MAX_ITERATIONS} iterations (press="${slug || "(missing-slug)"}"). ` +
         `This usually means a chain keeps growing without fitting; check MdxArea capacities and block heights.`,
     );
   }
@@ -282,15 +298,18 @@ async function exportSinglePress({
   // change is metadata.title comes from the per-press Press JSX prop.
   const blockMap = {};
   const captionState = createCaptionNumberingState();
+  const totalFrames = final.frames.length;
+  const pressSourcePath = sourcePathForPress({ entry, slug });
   const blocks = final.frames.map((frame, index) => {
     const source = {
-      file: "index.tsx",
-      path: slug ? `press/${slug}/index.tsx` : "press/index.tsx",
+      file: path.basename(pressSourcePath),
+      path: pressSourcePath,
       kind: frame.role ?? "manuscript.content",
       slug: frame.frameKey,
       sectionIndex: index + 1,
     };
-    const html = numberCaptionsInHtml(frame.html, effectiveConfig.captionNumbering, captionState);
+    const numberedHtml = numberCaptionsInHtml(frame.html, effectiveConfig.captionNumbering, captionState);
+    const html = resolvePageFoliosInHtml(numberedHtml, { pageIndex: index, totalPages: totalFrames });
     for (const id of collectFrameBlockIds(frame.blockIds, html)) {
       blockMap[id] = { id, pageIndex: index, pageNumber: index + 1, frameKey: frame.frameKey };
     }
@@ -364,11 +383,10 @@ async function exportSinglePress({
     blocks,
   };
 
-  // Output path: empty slug → root /openpress/document.json (legacy
-  // single-Press shape). Non-empty slug → /openpress/<slug>/document.json.
-  const pressOutputDir = slug
-    ? path.join(effectiveConfig.paths.publicDir, slug)
-    : effectiveConfig.paths.publicDir;
+  if (!slug) {
+    throw new Error("<Press slug> is required. Folder-convention workspaces write to /openpress/<slug>/document.json.");
+  }
+  const pressOutputDir = path.join(effectiveConfig.paths.publicDir, slug);
   await fs.mkdir(pressOutputDir, { recursive: true });
   const documentPath = path.join(pressOutputDir, "document.json");
   await fs.writeFile(documentPath, JSON.stringify(readerDocument, null, 2), "utf8");
@@ -377,7 +395,7 @@ async function exportSinglePress({
     slug,
     pressType,
     documentPath,
-    documentUrl: slug ? `/openpress/${slug}/document.json` : "/openpress/document.json",
+    documentUrl: `/openpress/${slug}/document.json`,
     readerDocument,
     pageCount: blocks.length,
   };
@@ -407,6 +425,114 @@ function applyPressOverridesToConfig(workspaceConfig, pressMetadata) {
   return out;
 }
 
+function collectWorkspaceComponentRoots(presses, config) {
+  return uniquePaths(presses.flatMap((press) => componentRootsForPress(press, config)));
+}
+
+function collectWorkspaceThemeRoots(presses, config) {
+  return uniquePaths(presses.flatMap((press) => themeRootsForPress(press, config)));
+}
+
+function collectWorkspaceMediaRoots(presses, config) {
+  return uniquePaths(presses.flatMap((press) => mediaRootsForPress(press, config)));
+}
+
+function themeRootsForPress(press, config) {
+  const documentRoot = config.paths.documentRoot;
+  const folder = pressFolderName(press);
+  const roots = [];
+  if (folder) roots.push(path.join(documentRoot, folder, "theme"));
+  roots.push(...declaredRoots(press.metadata?.theme, config, folder, "theme"));
+  return uniquePaths(roots);
+}
+
+function componentRootsForPress(press, config) {
+  const documentRoot = config.paths.documentRoot;
+  const folder = pressFolderName(press);
+  const roots = [
+    config.paths.componentsDir,
+  ];
+  if (folder) roots.push(path.join(documentRoot, folder, "components"));
+  roots.push(...declaredRoots(press.metadata?.componentsDir, config, folder, "componentsDir"));
+  return uniquePaths(roots);
+}
+
+function mediaRootsForPress(press, config) {
+  const documentRoot = config.paths.documentRoot;
+  const folder = pressFolderName(press);
+  const roots = [
+    config.paths.mediaDir,
+  ];
+  if (folder) roots.push(path.join(documentRoot, folder, "media"));
+  roots.push(...declaredRoots(press.metadata?.mediaDir, config, folder, "mediaDir"));
+  return uniquePaths(roots);
+}
+
+function declaredRoots(value, config, folder, propName) {
+  return pathList(value).map((entry) => resolvePressPath(entry, config, folder, propName));
+}
+
+function resolvePressPath(value, config, folder, propName) {
+  const raw = String(value).trim();
+  if (!raw) return null;
+  const documentRoot = config.paths.documentRoot;
+  const pressRoot = folder ? path.join(documentRoot, folder) : documentRoot;
+  const base = raw === "." || raw.startsWith("./") || raw.startsWith("../") ? pressRoot : documentRoot;
+  const absolutePath = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(base, raw);
+  const relative = path.relative(documentRoot, absolutePath);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`<Press ${propName}> path must stay inside press/: ${raw}`);
+  }
+  return absolutePath;
+}
+
+function pathList(value) {
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value)) return value.filter((item) => typeof item === "string");
+  return [];
+}
+
+function pressFolderName(press) {
+  const slug = typeof press.metadata?.slug === "string" ? press.metadata.slug.trim() : "";
+  if (!slug || slug.includes("/") || slug.includes("\\") || slug === "." || slug === "..") return "";
+  return slug;
+}
+
+function validateDiscoveredPressFolders(entry) {
+  const folders = Array.isArray(entry.pressFolders) ? entry.pressFolders : [];
+  if (folders.length === 0) return;
+  if (entry.presses.length !== folders.length) {
+    throw new Error(
+      `OpenPress found ${folders.length} press folder(s) but ${entry.presses.length} <Press> element(s). ` +
+        `Each press/<name>/press.tsx must render exactly one <Press>.`,
+    );
+  }
+  for (const [index, folder] of folders.entries()) {
+    const slug = typeof entry.presses[index]?.metadata?.slug === "string"
+      ? entry.presses[index].metadata.slug.trim()
+      : "";
+    if (!slug) {
+      throw new Error(`press/${folder}/press.tsx must declare <Press slug="${folder}">.`);
+    }
+    if (slug !== folder) {
+      throw new Error(`press/${folder}/press.tsx declares slug="${slug}", but folder-convention slugs must match the folder name.`);
+    }
+  }
+}
+
+function uniquePaths(paths) {
+  const out = [];
+  const seen = new Set();
+  for (const candidate of paths ?? []) {
+    if (!candidate) continue;
+    const normalized = path.resolve(candidate);
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    out.push(normalized);
+  }
+  return out;
+}
+
 async function loadComponentModules(server, components) {
   const out = {};
   for (const component of components) {
@@ -473,6 +599,10 @@ function collectFrameBlockIds(allocatedIds, html) {
   return ids;
 }
 
+function sourcePathForPress({ slug }) {
+  return `press/${slug}/press.tsx`;
+}
+
 function buildTocContext({ sources, frames, allocation }) {
   const toc = {};
   for (const source of Object.values(sources)) {

package/engine/react/mdx-compile.mjs

@@ -291,9 +291,9 @@ function normalizeTableCaptions(node) {
     const child = node.children[index];
     normalizeTableCaptions(child);
 
-    const legacyCaptionText = legacyTableCaptionText(child);
-    if (legacyCaptionText) {
-      throw new Error(`Legacy table caption markers are not supported. Use <TableCaption>${legacyCaptionText}</TableCaption> before the table.`);
+    const unsupportedCaptionText = unsupportedTableCaptionText(child);
+    if (unsupportedCaptionText) {
+      throw new Error(`Table caption marker syntax is not supported. Use <TableCaption>${unsupportedCaptionText}</TableCaption> before the table.`);
     }
 
     const captionText = tableCaptionText(child);
@@ -321,7 +321,7 @@ function normalizeTableCaptions(node) {
   }
 }
 
-function legacyTableCaptionText(node) {
+function unsupportedTableCaptionText(node) {
   if (node?.type !== "element" || node.tagName !== "p") return "";
   const match = textContent(node).match(LEGACY_TABLE_CAPTION_MARKER_RE);
   return match?.[1]?.trim() ?? "";

package/engine/react/measurement-css.mjs

@@ -8,15 +8,15 @@ import { buildSectionScopedCss } from "./section-css.mjs";
 
 const require = createRequire(import.meta.url);
 
-export async function buildReactMeasurementCss(root, config, workspace) {
+export async function buildReactMeasurementCss(root, config, workspace, options = {}) {
   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(await buildContentCss(root, config, { themeRoots: options.themeRoots }));
   parts.push("\n/* === public/openpress/components.css === */\n");
-  parts.push(await buildComponentsCss(root, config));
+  parts.push(await buildComponentsCss(root, config, { componentRoots: options.componentRoots }));
   const chapterCss = await buildSectionScopedCss(workspace);
   if (chapterCss.trim()) {
     parts.push("\n/* === public/openpress/chapter-scoped.css === */\n");

package/engine/react/page-folio.mjs

@@ -0,0 +1,37 @@
+const CURRENT_RE = /(<span\b[^>]*\bdata-openpress-page-folio-current="true"[^>]*>)([\s\S]*?)(<\/span>)/gi;
+const TOTAL_RE = /(<span\b[^>]*\bdata-openpress-page-folio-total="true"[^>]*>)([\s\S]*?)(<\/span>)/gi;
+
+export function resolvePageFoliosInHtml(html, { pageIndex, totalPages }) {
+  const current = Math.max(1, Math.trunc(pageIndex) + 1);
+  const total = Math.max(0, Math.trunc(totalPages));
+
+  return String(html ?? "")
+    .replace(CURRENT_RE, (match, open, _body, close) => {
+      const format = pickAttr(open, "data-openpress-page-folio-format") || "plain";
+      return `${open}${escapeHtml(formatPageNumber(current, format))}${close}`;
+    })
+    .replace(TOTAL_RE, (match, open, _body, close) => {
+      const format = pickAttr(open, "data-openpress-page-folio-format") || "plain";
+      return `${open}${escapeHtml(formatPageNumber(total, format))}${close}`;
+    });
+}
+
+export function formatPageNumber(value, format = "plain") {
+  const normalized = Math.max(0, Math.trunc(Number(value) || 0));
+  if (format === "3-digit") return String(normalized).padStart(3, "0");
+  if (format === "2-digit") return String(normalized).padStart(2, "0");
+  return String(normalized);
+}
+
+function pickAttr(attrs, name) {
+  const re = new RegExp(`${name}="([^"]*)"`);
+  const match = re.exec(attrs);
+  return match?.[1];
+}
+
+function escapeHtml(value) {
+  return String(value ?? "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}

package/engine/react/pagination/allocator.mjs

@@ -114,7 +114,7 @@ export function pagesFromRegions(filledRegions) {
   return pages;
 }
 
-// Public wrapper preserving the legacy (blocks, { pageSafeHeightPx }) signature.
+// Public wrapper preserving the existing (blocks, { pageSafeHeightPx }) signature.
 // New code can pass a `regions` stream directly to opt into multi-column or
 // heterogeneous layouts.
 export function paginateMeasuredBlocks(measuredBlocks, options = {}) {
@@ -146,7 +146,7 @@ function infiniteFixedCapacityRegionStream(capacity) {
   };
 }
 
-// Translate the new region-shaped warnings back to the legacy
+// Translate the new region-shaped warnings back to the existing
 // `block-overflows-page` schema that document-export.mjs and downstream
 // consumers expect. Once consumers migrate, this can drop.
 function mapWarning(warning, pageSafeHeightPx) {
@@ -161,7 +161,7 @@ function mapWarning(warning, pageSafeHeightPx) {
   return warning;
 }
 
-function positiveNumber(value, fallback) {
+function positiveNumber(value, defaultValue) {
   const number = Number(value);
-  return Number.isFinite(number) && number > 0 ? number : fallback;
+  return Number.isFinite(number) && number > 0 ? number : defaultValue;
 }

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

@@ -32,7 +32,7 @@ const CAPACITY_SAFETY_MAX_PX = 96;
  * @param {Map<string, object>} opts.renderRegistry Internal render data per sourceId.
  * @param {string} opts.css         Combined CSS for measurement context.
  * @param {string=} opts.baseHref   Base URL for relative media paths in MDX.
- * @param {string=} opts.mediaDir  Local media dir for inlining /openpress/media/* assets.
+ * @param {string|string[]=} opts.mediaDir  Local media roots for inlining /openpress/media/* assets.
  * @param {object=} opts.captionNumbering Caption label formatter options.
  * @param {{width:number,height:number}=} opts.viewport
  */
@@ -136,7 +136,7 @@ async function runChromiumMeasurement(html, viewport) {
     const page = await browser.newPage({ viewport });
     await page.setContent(html, { waitUntil: "load" });
     // Match the print-ready settle: fonts first (font metrics affect image
-    // alt-text fallback boxes), then await every image's `complete` AND
+    // alt-text placeholder boxes), then await every image's `complete` AND
     // `decode()` so intrinsic sizes are committed before layout, then two
     // animation frames so the chromium layout pass observes the final box
     // model. Without this, `getBoundingClientRect()` on figures that hold
@@ -200,11 +200,11 @@ async function runChromiumMeasurement(html, viewport) {
         ];
         for (const candidate of candidates) {
           if (!candidate) continue;
-          const fallback = candidate.getBoundingClientRect();
-          if (fallback.height > rect.height) {
+          const alternateRect = candidate.getBoundingClientRect();
+          if (alternateRect.height > rect.height) {
             return {
-              height: fallback.height,
-              width: rect.width > 0 ? rect.width : fallback.width,
+              height: alternateRect.height,
+              width: rect.width > 0 ? rect.width : alternateRect.width,
             };
           }
         }
@@ -250,7 +250,8 @@ function escapeAttr(value) {
 }
 
 async function inlineMeasurementMediaUrls(html, mediaDir) {
-  if (!mediaDir || !html) return html;
+  const mediaRoots = mediaRootList(mediaDir);
+  if (mediaRoots.length === 0 || !html) return html;
   let out = String(html);
   const matches = new Set();
   for (const match of out.matchAll(/\bsrc=(['"])([^\1]*?)\1/g)) {
@@ -269,7 +270,7 @@ async function inlineMeasurementMediaUrls(html, mediaDir) {
     }
   }
   for (const rawName of matches) {
-    const dataUrl = await mediaDataUrl(mediaDir, rawName);
+    const dataUrl = await mediaDataUrl(mediaRoots, rawName);
     if (!dataUrl) continue;
     out = out.replaceAll(`/openpress/media/${rawName}`, dataUrl);
     out = out.replaceAll(`media/${rawName}`, dataUrl);
@@ -278,7 +279,7 @@ async function inlineMeasurementMediaUrls(html, mediaDir) {
   return out;
 }
 
-async function mediaDataUrl(mediaDir, rawName) {
+async function mediaDataUrl(mediaRoots, rawName) {
   let fileName;
   try {
     fileName = decodeURIComponent(String(rawName));
@@ -286,14 +287,31 @@ async function mediaDataUrl(mediaDir, rawName) {
     fileName = String(rawName);
   }
   if (!fileName || fileName !== path.basename(fileName)) return null;
-  const filePath = path.join(mediaDir, fileName);
-  let bytes;
-  try {
-    bytes = await fs.readFile(filePath);
-  } catch {
-    return null;
+  for (const mediaDir of mediaRoots) {
+    const filePath = path.join(mediaDir, fileName);
+    let bytes;
+    try {
+      bytes = await fs.readFile(filePath);
+    } catch {
+      continue;
+    }
+    return `data:${mediaMimeType(fileName)};base64,${bytes.toString("base64")}`;
+  }
+  return null;
+}
+
+function mediaRootList(mediaDir) {
+  const raw = Array.isArray(mediaDir) ? mediaDir : [mediaDir];
+  const roots = [];
+  const seen = new Set();
+  for (const candidate of raw) {
+    if (!candidate) continue;
+    const normalized = path.resolve(candidate);
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    roots.push(normalized);
   }
-  return `data:${mediaMimeType(fileName)};base64,${bytes.toString("base64")}`;
+  return roots;
 }
 
 function mediaMimeType(fileName) {

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

@@ -2,8 +2,8 @@
 // <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
+// its props (title, page, sources, slug, theme, componentsDir, mediaDir).
+// This helper invokes the user's
 // component once at load time to inspect those props before the engine
 // runs its render pipeline.
 //
@@ -21,7 +21,7 @@ import React from "react";
  * for the single-Press case.
  *
  * @param {object} opts
- * @param {Function} opts.UserComponent  The default export of press/index.tsx.
+ * @param {Function} opts.UserComponent  The default export of press/<slug>/press.tsx.
  * @param {symbol} opts.PRESS_MARKER     Marker identifying Press components.
  * @param {symbol} opts.WORKSPACE_MARKER Marker identifying Workspace components.
  * @returns {{
@@ -35,7 +35,8 @@ import React from "react";
  *       page?: unknown,
  *       slug?: string,
  *       theme?: string,
- *       componentsDir?: string,
+ *       componentsDir?: string | string[],
+ *       mediaDir?: string | string[],
  *       captionNumbering?: unknown,
  *     },
  *     sources: Record<string, unknown> | null,  // mdxSource() descriptors keyed by id
@@ -118,14 +119,14 @@ function extractProps(element) {
 
 function collectPressElements(root, PRESS_MARKER) {
   const found = [];
-  walk(root);
+  walk(root, new Set());
   return found;
 
-  function walk(node) {
+  function walk(node, seen) {
     if (!isReactElement(node)) {
       // Could be array / fragment / string / number — flatten and recurse.
       if (Array.isArray(node)) {
-        for (const child of node) walk(child);
+        for (const child of node) walk(child, seen);
       }
       return;
     }
@@ -135,10 +136,32 @@ function collectPressElements(root, PRESS_MARKER) {
       // not more workspace structure.
       return;
     }
+    const rendered = renderCompositeElement(node, seen);
+    if (rendered !== null) {
+      walk(rendered, seen);
+      return;
+    }
     // Recurse into children + Fragment-like wrappers.
     const children = node.props?.children;
     if (children == null) return;
-    React.Children.forEach(children, walk);
+    React.Children.forEach(children, (child) => walk(child, seen));
+  }
+}
+
+function renderCompositeElement(element, seen) {
+  const type = element?.type;
+  if (typeof type !== "function") return null;
+  if (seen.has(type)) return null;
+  seen.add(type);
+  try {
+    return type(element.props ?? {});
+  } catch {
+    // Top-level Press wrapper components should be inert. If a user puts a
+    // hookful or effectful component at the Workspace boundary, leave it for
+    // the normal React render pipeline to report with full context.
+    return null;
+  } finally {
+    seen.delete(type);
   }
 }
 
@@ -149,15 +172,22 @@ function pickPressMetadata(pressProps) {
   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 (typeof pressProps.componentsDir === "string" || isStringArray(pressProps.componentsDir)) {
+    out.componentsDir = pressProps.componentsDir;
+  }
+  if (typeof pressProps.mediaDir === "string" || isStringArray(pressProps.mediaDir)) {
+    out.mediaDir = pressProps.mediaDir;
+  }
   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 isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+// Convert <Press sources={[ mdxSource({ id, ... }), ... ]}> into the
+// engine's expected sources record { [id]: descriptor }.
 function extractSources(pressProps) {
   if (!Array.isArray(pressProps.sources)) return null;
   const out = {};