@open-press/core 1.2.1 → 1.3.1

package/engine/runtime/source-text-tools.mjs

@@ -451,10 +451,13 @@ function applySourceBlockTableCellEditToText(documentText, {
 export async function collectSourceTextFiles(config, { scope = "content" } = {}) {
   const roots = await sourceRoots(config, scope);
   const files = [];
+  const seen = new Set();
   for (const rootInfo of roots) {
     const visit = async (absolutePath) => {
+      if (seen.has(absolutePath)) return;
       const extension = path.extname(absolutePath);
       if (!rootInfo.extensions.has(extension)) return;
+      seen.add(absolutePath);
       const relativePath = path.relative(config.root, absolutePath).replaceAll("\\", "/");
       files.push({
         scope: rootInfo.scope,
@@ -557,18 +560,30 @@ async function sourceRoots(config, scope) {
     const roots = [
       ...contentRoots,
       { scope: "design-doc", kind: "file", absolutePath: sourceConfig.paths.designDoc, extensions: MARKDOWN_EXTENSIONS },
-      { scope: "components", kind: "dir", absolutePath: sourceConfig.paths.componentsDir, extensions: ALL_SOURCE_EXTENSIONS },
-      { scope: "document-entry", kind: "file", absolutePath: sourceWorkspace.entryPath, extensions: REACT_IMPLEMENTATION_EXTENSIONS },
-      ...implementationRoots(sourceWorkspace),
+      ...await implementationRoots(sourceWorkspace),
     ];
     return roots;
   }
   return contentRoots;
 }
 
-function implementationRoots(sourceWorkspace) {
+async function implementationRoots(sourceWorkspace) {
   const roots = [];
   const seen = new Set();
+  const documentRoot = sourceWorkspace.config.paths.documentRoot;
+  const entries = await readDirectoryEntries(documentRoot);
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+    const absolutePath = path.join(documentRoot, entry.name);
+    if (seen.has(absolutePath)) continue;
+    seen.add(absolutePath);
+    roots.push({
+      scope: entry.name === "shared" ? "shared-source" : "press-source",
+      kind: "dir",
+      absolutePath,
+      extensions: ALL_SOURCE_EXTENSIONS,
+    });
+  }
   for (const root of sourceWorkspace.contentRoots ?? [{ kind: "dir", absolutePath: sourceWorkspace.sourceDir }]) {
     const absolutePath = root.kind === "dir" ? root.absolutePath : path.dirname(root.absolutePath);
     if (seen.has(absolutePath)) continue;
@@ -583,6 +598,15 @@ function implementationRoots(sourceWorkspace) {
   return roots;
 }
 
+async function readDirectoryEntries(directory) {
+  try {
+    return await fs.readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+}
+
 function forEachLine(text, visit) {
   const lineRe = /([^\r\n]*)(\r\n|\n|\r|$)/g;
   let lineNumber = 1;

package/engine/runtime/source-workspace.mjs

@@ -12,7 +12,7 @@ export async function resolveActiveSourceWorkspace(config) {
   const reactEntry = await loadReactDocumentEntry(config.root);
   if (!reactEntry) {
     throw new Error(
-      "React/MDX document entry not found. Expected press/index.tsx with a Press default export before using workspace source tools.",
+      "React/MDX document entry not found. Expected one or more press/*/press.tsx files before using workspace source tools.",
     );
   }
   // Aggregate sources across every Press in the Workspace. Workspace
@@ -26,6 +26,7 @@ export async function resolveActiveSourceWorkspace(config) {
   }
   const contentRoots = contentRootsFromSources(aggregateSources, reactEntry.config);
   const sourceDir = firstDirectoryRoot(contentRoots) ?? reactEntry.config.paths.documentRoot;
+  const hasRegisteredSources = contentRoots.length > 0;
 
   return {
     kind: "react-mdx",
@@ -34,11 +35,12 @@ export async function resolveActiveSourceWorkspace(config) {
     entryPath: reactEntry.entryPath,
     sourceDir,
     contentRoots,
+    hasRegisteredSources,
     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 press/index.tsx `sources` before running export.",
+    missingMessage: "Registered React MDX sources do not exist yet; create the files or roots declared in press/*/press.tsx `sources` before running export.",
     emptyMessage: "Registered React MDX sources contain no `*.mdx` files; the document will export with zero source blocks.",
   };
 }
@@ -78,6 +80,7 @@ export async function collectActiveContentFiles(sourceWorkspace, { skipUnderscor
 
 export async function sourceDirectoryExists(sourceWorkspace) {
   const roots = sourceWorkspace.contentRoots ?? [{ kind: "dir", absolutePath: sourceWorkspace.sourceDir }];
+  if (roots.length === 0) return true;
   for (const root of roots) {
     try {
       const stat = await fs.stat(root.absolutePath);
@@ -93,13 +96,7 @@ export async function sourceDirectoryExists(sourceWorkspace) {
 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",
-    }];
+    return [];
   }
 
   const roots = [];

package/engine/runtime/validation.mjs

@@ -17,12 +17,20 @@ const PUBLIC_DEPLOY_ADAPTERS = new Set([
   "vercel",
 ]);
 
-// A directory is an OpenPress workspace if it contains a
-// press/index.tsx entry, or a package.json with an "openpress" field.
+// A directory is an OpenPress workspace if it contains folder-convention
+// Press entries, or a package.json with an "openpress" field.
 async function isWorkspaceRoot(dir) {
   try {
-    await fs.access(path.join(dir, "press", "index.tsx"));
-    return true;
+    const pressEntries = await fs.readdir(path.join(dir, "press"), { withFileTypes: true });
+    if (pressEntries.some((entry) => entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "shared")) {
+      for (const entry of pressEntries) {
+        if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "shared") continue;
+        try {
+          await fs.access(path.join(dir, "press", entry.name, "press.tsx"));
+          return true;
+        } catch {}
+      }
+    }
   } catch {}
   try {
     const pkg = JSON.parse(await fs.readFile(path.join(dir, "package.json"), "utf8"));
@@ -60,11 +68,7 @@ export async function validateWorkspace(root) {
 
   mark("config");
   for (const [key, target] of [
-    ["sourceDir", sourceWorkspace.sourceDir],
-    ["mediaDir", activeConfig.paths.mediaDir],
-    ["themeDir", activeConfig.paths.themeDir],
     ["designDoc", activeConfig.paths.designDoc],
-    ["componentsDir", activeConfig.paths.componentsDir],
   ]) {
     if (!(await exists(target))) add("error", `config.${key}`, `Configured OpenPress path \`${key}\` does not exist.`, target);
   }
@@ -87,11 +91,11 @@ export async function validateWorkspace(root) {
 
   mark(sourceWorkspace.checkedName);
   if (!(typeof activeConfig.title === "string" && activeConfig.title.trim())) {
-    add("warning", "press.title", "<Press title> is missing in press/index.tsx; the workbench will show the default placeholder.", activeConfig.configPath);
+    add("warning", "press.title", "<Press title> is missing in press/*/press.tsx; the workbench will show the default placeholder.", activeConfig.configPath);
   }
-  if (!(await sourceDirectoryExists(sourceWorkspace))) {
+  if (sourceWorkspace.hasRegisteredSources && !(await sourceDirectoryExists(sourceWorkspace))) {
     add("warning", sourceWorkspace.missingCode, sourceWorkspace.missingMessage, sourceWorkspace.sourceDir);
-  } else {
+  } else if (sourceWorkspace.hasRegisteredSources) {
     const contentFiles = await collectActiveContentFiles(sourceWorkspace, { skipUnderscoreFiles: true });
     if (contentFiles.length === 0) {
       add("warning", sourceWorkspace.emptyCode, sourceWorkspace.emptyMessage, sourceWorkspace.sourceDir);
@@ -119,19 +123,19 @@ export async function validateWorkspace(root) {
   }
 
   mark("react-source");
-  const documentJsonPath = path.join(activeConfig.paths.publicDir, "document.json");
-  const exportedDocument = await readJsonIfExists(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-source.${code}`,
-        pressWarningMessage(warning),
-        documentJsonPath,
-        warning,
-      );
+  for (const exported of await readExportedPressDocuments(activeConfig.paths.publicDir)) {
+    const pressWarnings = exported.document?.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-source.${code}`,
+          pressWarningMessage(warning),
+          exported.path,
+          warning,
+        );
+      }
     }
   }
 
@@ -173,6 +177,20 @@ async function readJsonIfExists(filePath) {
   }
 }
 
+async function readExportedPressDocuments(publicDir) {
+  const manifestPath = path.join(publicDir, "workspace.json");
+  const manifest = await readJsonIfExists(manifestPath);
+  if (!Array.isArray(manifest?.presses)) return [];
+  const out = [];
+  for (const press of manifest.presses) {
+    if (typeof press?.slug !== "string" || !press.slug.trim()) continue;
+    const documentJsonPath = path.join(publicDir, press.slug.trim(), "document.json");
+    const document = await readJsonIfExists(documentJsonPath);
+    if (document) out.push({ path: documentJsonPath, document });
+  }
+  return out;
+}
+
 async function exists(filePath) {
   try {
     await fs.access(filePath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-press/core",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "type": "module",
   "description": "open-press core — runtime primitives, CLI, and render pipeline for AI-first fixed-layout documents.",
   "license": "MIT",

package/src/openpress/app/OpenPressApp.tsx

@@ -24,9 +24,7 @@ type LoadState =
       document: ReaderDocument;
       deploymentInfo: DeploymentInfo;
       manifest: WorkspaceManifest | null;
-      // Empty string for single-Press workspaces (no slug routing needed)
-      // or for the root entry of a multi-Press workspace. Otherwise the
-      // active press's slug — used by refresh/back/forward to re-resolve.
+      // Active Press slug, used by refresh/back/forward to re-resolve.
       activeSlug: string;
       runtimeMode: OpenPressRuntimeMode;
     }
@@ -75,16 +73,10 @@ export function OpenPressApp() {
     route: WorkspaceRoute,
     deploymentInfo: DeploymentInfo,
   ) => {
-    // No manifest (legacy deploy): always load /openpress/document.json.
     if (!manifest || manifest.presses.length === 0) {
-      const document = await loadReaderDocument("/openpress/document.json");
       setState({
-        status: "ready",
-        document,
-        deploymentInfo,
-        manifest,
-        activeSlug: "",
-        runtimeMode: resolveRuntimeMode(document, route.mode),
+        status: "error",
+        message: "OpenPress workspace manifest is missing or empty. Run open-press render to generate /openpress/workspace.json.",
       });
       return;
     }
@@ -124,8 +116,8 @@ export function OpenPressApp() {
     const press = state.manifest
       ? findManifestPress(state.manifest, state.activeSlug)
       : null;
-    const url = press?.documentUrl ?? "/openpress/document.json";
-    const document = await loadReaderDocument(url);
+    if (!press) return;
+    const document = await loadReaderDocument(press.documentUrl);
     setState((latest) => {
       if (latest.status !== "ready") return latest;
       return { ...latest, document };
@@ -133,8 +125,7 @@ export function OpenPressApp() {
   }, [state]);
 
   // Gallery click → pushState + load. Bypasses resolveFromRoute's
-  // "empty slug + multi-Press → gallery" branch: an explicit click on
-  // the unslugged root Press must enter it, not bounce back to gallery.
+  // "empty slug + multi-Press → gallery" branch.
   const enterPress = useCallback(async (press: WorkspaceManifestPress) => {
     if (state.status !== "gallery") return;
     pushPressRoute(press.slug, "preview");

package/src/openpress/app/OpenPressRuntime.tsx

@@ -48,7 +48,7 @@ export function OpenPressRuntime({
   // (e.g. /<slug>/present -> /<slug>/preview after exiting the slide
   // presenter), so the SlidePresentationPage exits to the wrong
   // route-driven branch (PublicViewer instead of HtmlWorkbench) and the
-  // user sees the legacy public-viewer chrome until a hard reload.
+  // user sees stale public-viewer chrome until a hard reload.
   // Bump a version on every pathname/search change so the memos
   // re-evaluate exactly when the URL does.
   const routeVersion = useLocationVersion();
@@ -125,11 +125,11 @@ function EmptyState({ style, workspaceMode }: { style: CSSProperties; workspaceM
         <p className="openpress-empty-state__eyebrow">OpenPress</p>
         <h1 className="openpress-empty-state__title">This document has no content yet.</h1>
         <p className="openpress-empty-state__body">
-          Add React MDX chapter files under <code>press/chapters/**/content/</code>, then re-build.
+          Add React MDX chapter files under <code>press/&lt;slug&gt;/chapters/**/content/</code>, then re-build.
         </p>
         {workspaceMode ? (
           <ol className="openpress-empty-state__steps">
-            <li><code>npm run build</code> &nbsp;— validates and refreshes <code>public/openpress/document.json</code></li>
+            <li><code>npm run build</code> &nbsp;— validates and refreshes <code>public/openpress/workspace.json</code></li>
             <li>Reload this page</li>
           </ol>
         ) : (

package/src/openpress/app/WorkspaceGalleryPage.tsx

@@ -201,7 +201,7 @@ async function fetchFirstPage(url: string): Promise<HtmlPageBlock | null> {
 // Convert a CSS length string (px / mm / cm / in) into device pixels
 // at 96 dpi. A4 pages are stored as "210mm" / "297mm" so the gallery
 // and thumbnail scalers need this to compute their fit ratio — using
-// the bare string would always fall back to the default fallback.
+// the bare string would otherwise resolve to the default asset path.
 function parsePxLength(value: string | undefined): number | null {
   if (!value) return null;
   const match = value.trim().match(/^([\d.]+)\s*(px|mm|cm|in)$/i);

package/src/openpress/core/PageFolio.tsx

@@ -0,0 +1,115 @@
+import type { HTMLAttributes } from "react";
+import { cn } from "./cn";
+
+export type PageFolioVariant = "current" | "total" | "slash" | "of" | "prefix";
+export type PageFolioNumberFormat = "plain" | "2-digit" | "3-digit";
+
+export type PageFolioProps = Omit<HTMLAttributes<HTMLSpanElement>, "children"> & {
+  variant?: PageFolioVariant;
+  currentFormat?: PageFolioNumberFormat;
+  totalFormat?: PageFolioNumberFormat;
+  prefix?: string;
+  separator?: string;
+  ofLabel?: string;
+  ariaLabel?: string;
+};
+
+export function PageFolio({
+  variant = "current",
+  currentFormat = "plain",
+  totalFormat = "plain",
+  prefix = "",
+  separator = "/",
+  ofLabel = "of",
+  ariaLabel,
+  className,
+  ...rest
+}: PageFolioProps) {
+  const current = placeholderForFormat(currentFormat);
+  const total = placeholderForFormat(totalFormat);
+  const label = ariaLabel ?? defaultAriaLabel(variant);
+
+  return (
+    <span
+      {...rest}
+      className={cn("openpress-page-folio", `openpress-page-folio--${variant}`, className)}
+      data-openpress-page-folio="true"
+      data-openpress-page-folio-variant={variant}
+      data-openpress-page-folio-current-format={currentFormat}
+      data-openpress-page-folio-total-format={totalFormat}
+      data-openpress-page-folio-prefix={prefix}
+      data-openpress-page-folio-separator={separator}
+      data-openpress-page-folio-of-label={ofLabel}
+      aria-label={label}
+    >
+      {renderFolioParts({ variant, current, total, currentFormat, totalFormat, prefix, separator, ofLabel })}
+    </span>
+  );
+}
+
+function renderFolioParts({
+  variant,
+  current,
+  total,
+  currentFormat,
+  totalFormat,
+  prefix,
+  separator,
+  ofLabel,
+}: {
+  variant: PageFolioVariant;
+  current: string;
+  total: string;
+  currentFormat: PageFolioNumberFormat;
+  totalFormat: PageFolioNumberFormat;
+  prefix: string;
+  separator: string;
+  ofLabel: string;
+}) {
+  if (variant === "total") {
+    return <span className="openpress-page-folio__total" data-openpress-page-folio-total="true" data-openpress-page-folio-format={totalFormat}>{total}</span>;
+  }
+
+  if (variant === "slash") {
+    return (
+      <>
+        <span className="openpress-page-folio__current" data-openpress-page-folio-current="true" data-openpress-page-folio-format={currentFormat}>{current}</span>
+        <span className="openpress-page-folio__separator" data-openpress-page-folio-separator-text="true">{separator}</span>
+        <span className="openpress-page-folio__total" data-openpress-page-folio-total="true" data-openpress-page-folio-format={totalFormat}>{total}</span>
+      </>
+    );
+  }
+
+  if (variant === "of") {
+    return (
+      <>
+        <span className="openpress-page-folio__current" data-openpress-page-folio-current="true" data-openpress-page-folio-format={currentFormat}>{current}</span>
+        <span className="openpress-page-folio__separator" data-openpress-page-folio-of-text="true">{ofLabel}</span>
+        <span className="openpress-page-folio__total" data-openpress-page-folio-total="true" data-openpress-page-folio-format={totalFormat}>{total}</span>
+      </>
+    );
+  }
+
+  if (variant === "prefix") {
+    return (
+      <>
+        <span className="openpress-page-folio__prefix" data-openpress-page-folio-prefix-text="true">{prefix}</span>
+        <span className="openpress-page-folio__current" data-openpress-page-folio-current="true" data-openpress-page-folio-format={currentFormat}>{current}</span>
+      </>
+    );
+  }
+
+  return <span className="openpress-page-folio__current" data-openpress-page-folio-current="true" data-openpress-page-folio-format={currentFormat}>{current}</span>;
+}
+
+function placeholderForFormat(format: PageFolioNumberFormat) {
+  if (format === "3-digit") return "000";
+  if (format === "2-digit") return "00";
+  return "0";
+}
+
+function defaultAriaLabel(variant: PageFolioVariant) {
+  if (variant === "total") return "Total pages";
+  if (variant === "slash" || variant === "of") return "Page number and total pages";
+  return "Page number";
+}

package/src/openpress/core/Press.tsx

@@ -14,17 +14,16 @@ export interface AllocationHints {
   totalPagesPerChain: Record<string, number>;
 }
 
-// Metadata read from <Press> props by the engine pipeline. The 1.0 contract
-// declares these on the component; v0.x reads them from openpress.config.mjs
-// instead and leaves these as undefined. The engine merges both sources
-// (props override config) until v1.0 removes config support.
+// Metadata read from <Press> props by the engine pipeline. Each
+// press/<slug>/press.tsx entry declares its document metadata here.
 export interface PressMetadata {
   title?: string;
   type?: PressProps["type"];
   page?: PressProps["page"];
   slug?: string;
   theme?: string;
-  componentsDir?: string;
+  componentsDir?: PressProps["componentsDir"];
+  mediaDir?: PressProps["mediaDir"];
 }
 
 export interface PressContextValue {
@@ -36,9 +35,7 @@ export interface PressContextValue {
   // the first measurement pass.
   hints: AllocationHints | null;
   toc: Record<string, TocEntry[]> | null;
-  // Metadata declared on <Press> props in v1.0. Engine providers may
-  // omit this on v0.x; consumers should treat undefined as "no metadata
-  // declared on Press — fall back to openpress.config.mjs values".
+  // Metadata declared on <Press> props.
   metadata?: PressMetadata;
 }
 
@@ -48,8 +45,6 @@ export function Press(props: PressProps) {
   // Press is intentionally inert at render time — the engine reads its
   // props and children through React.Children inspection during the
   // export pipeline, then injects context above any nested helpers.
-  // For the v0.x shape (children-only usage), this still passes children
-  // through unchanged.
   return <Fragment>{props.children}</Fragment>;
 }
 

package/src/openpress/core/Slide.tsx

@@ -0,0 +1,11 @@
+import { Frame } from "./Frame";
+import type { SlideProps } from "./types";
+
+export function Slide({
+  id,
+  role = "canvas.slide",
+  chrome = false,
+  ...rest
+}: SlideProps) {
+  return <Frame {...rest} frameKey={id} role={role} chrome={chrome} />;
+}

package/src/openpress/core/index.tsx

@@ -8,13 +8,16 @@
 export { Press, PressContext, PRESS_MARKER } from "./Press";
 export { Workspace, WorkspaceContext, WORKSPACE_MARKER } from "./Workspace";
 export { Frame, FRAME_MARKER } from "./Frame";
+export { Slide } from "./Slide";
 export { FrameContext } from "./FrameContext";
+export { PageFolio } from "./PageFolio";
 export { MdxArea } from "./MdxArea";
 export { useSource } from "./useSource";
 export { ObjectEntity, Text, BaseFigure, BaseCallout, MediaFigure, ImageFigure } from "./primitives";
 
 export type {
   FrameProps,
+  SlideProps,
   FrameRole,
   MdxAreaProps,
   MdxAreaOverflow,
@@ -45,3 +48,4 @@ export type {
 export type { PressContextValue, AllocationHints, PressMetadata } from "./Press";
 export type { WorkspaceContextValue } from "./Workspace";
 export type { FrameContextValue } from "./FrameContext";
+export type { PageFolioNumberFormat, PageFolioProps, PageFolioVariant } from "./PageFolio";

package/src/openpress/core/types.ts

@@ -18,6 +18,12 @@ export type FrameProps = Omit<HTMLAttributes<HTMLElement>, "role" | "children">
   children?: ReactNode;
 };
 
+export type SlideProps = Omit<FrameProps, "frameKey" | "role" | "chrome" | "title"> & {
+  id: string;
+  role?: FrameRole;
+  chrome?: boolean;
+};
+
 export type MdxAreaOverflow = "extend" | "truncate" | "error";
 
 export type MdxAreaProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
@@ -47,9 +53,9 @@ export interface PressProps {
   // Document tree — Frames, manuscript helpers, etc.
   children: ReactNode;
   // -------------------------------------------------------------------------
-  // 1.0 metadata props — optional during v0.x deprecation, required in v1.0.
+  // Press metadata props.
   // -------------------------------------------------------------------------
-  // Document title. Required in 1.0. Used for PDF metadata, HTML <title>,
+  // Document title. Used for PDF metadata, HTML <title>,
   // OG tags, and the Workspace gallery / tab-bar label.
   title?: string;
   // Creation mode. Pages are source-driven with MDX allocation; slides are
@@ -61,15 +67,17 @@ export interface PressProps {
   // Array of source registrations from mdxSource(). Replaces the v0.x
   // `export const sources` named export.
   sources?: ReadonlyArray<PressSource>;
-  // URL / output slug for this Press inside a Workspace. Defaults to
-  // "/" when only one Press exists in the Workspace; required when the
-  // Workspace has multiple Press children.
+  // URL / output slug for this Press. Must match the Press folder name.
   slug?: string;
-  // Optional per-Press theme directory. Defaults to "./theme" relative
-  // to the document file; inherits from <Workspace theme> if not set.
+  // Optional per-Press theme directory. Defaults include the folder-local
+  // "./theme"; shared CSS lives in press/shared/theme.
   theme?: string;
-  // Optional per-Press components directory. Default "./components".
-  componentsDir?: string;
+  // Optional per-Press components directories. Defaults include the
+  // folder-local "./components" and workspace shared components.
+  componentsDir?: string | string[];
+  // Optional per-Press media directories. Defaults include the folder-local
+  // "./media" and workspace shared media.
+  mediaDir?: string | string[];
   // Optional caption numbering overrides. Engine defaults to
   // { figure: "Figure", table: "Table", separator: " " }.
   captionNumbering?: {
@@ -80,7 +88,8 @@ export interface PressProps {
 }
 
 // ---------------------------------------------------------------------------
-// Workspace — root component holding one or more Press children
+// Workspace — engine-owned grouping component holding one or more Press
+// children from discovered press/*/press.tsx entries.
 // ---------------------------------------------------------------------------
 
 export interface WorkspaceProps {
@@ -90,10 +99,9 @@ export interface WorkspaceProps {
   // Project label surfaced in the gallery header, tab bar, and PDF
   // metadata. Optional.
   name?: string;
-  // Workspace-level shared theme directory. Press children that don't
-  // set their own `theme` prop inherit from this. Default "./theme".
+  // Reserved for future workspace-level shared theme overrides.
   theme?: string;
-  // Workspace-level shared media directory. Default "./media".
+  // Reserved for future workspace-level shared media overrides.
   media?: string;
 }
 

package/src/openpress/core/useSource.ts

@@ -21,7 +21,7 @@ export function useSource<T extends ResolvedSource = ResolvedSource>(id: string)
     const knownText = known.length > 0 ? known.join(", ") : "(none)";
     throw new Error(
       `Unknown source "${id}". Available sources: ${knownText}. ` +
-        `Register it as a <Press sources={[mdxSource({ id: "${id}", ... })]}> entry in press/index.tsx.`,
+        `Register it as a <Press sources={[mdxSource({ id: "${id}", ... })]}> entry in press/<slug>/press.tsx.`,
     );
   }
   return source as T;

package/src/openpress/document-model/workspaceManifestModel.ts

@@ -1,10 +1,6 @@
 // Shape of /openpress/workspace.json — the reader fetches this on
 // boot to decide between gallery routing (multi-Press) and direct
-// load (single Press). One entry per <Press> child of <Workspace>.
-//
-// Single-Press workspaces emit one entry with slug = "" and the
-// legacy /openpress/document.json path. Multi-Press emits one entry
-// per slug; each `documentUrl` resolves to /openpress/<slug>/document.json.
+// load (single Press). One entry per discovered Press folder.
 import type { PressType } from "./documentTypes";
 
 export interface WorkspaceManifest {
@@ -16,13 +12,12 @@ export interface WorkspaceManifest {
 }
 
 export interface WorkspaceManifestPress {
-  // Slug for this Press. Empty string for single-Press workspaces
-  // (legacy root); slug-shaped string for multi-Press.
+  // Slug for this Press. Matches the folder-convention Press slug.
   slug: string;
   // <Press title="..."> prop. Required in v1.0 contract.
   title: string;
-  // Creation mode declared by <Press type>. Defaults to "pages" for older
-  // documents. The reader uses this for mode-specific navigation affordances.
+  // Creation mode declared by <Press type>. The reader uses this for
+  // mode-specific navigation affordances.
   type: PressType;
   // Page geometry summary. Same shape as the reader's
   // ReaderDocument.theme — readers can show a thumb in the gallery