@open-press/core 0.8.0 → 1.0.0

package/src/openpress/app/OpenPressApp.tsx

@@ -1,14 +1,33 @@
 import { useCallback, useEffect, useState } from "react";
 import { OpenPressRuntime } from "./OpenPressRuntime";
+import { WorkspaceGalleryPage } from "./WorkspaceGalleryPage";
 import { isLocalWorkspaceHost } from "../shared";
-import type { DeploymentInfo, ReaderDocument } from "../document-model";
+import type {
+  DeploymentInfo,
+  ReaderDocument,
+  WorkspaceManifest,
+  WorkspaceManifestPress,
+} from "../document-model";
+import { findManifestPress, manifestHasMultiplePresses } from "../document-model";
 
 type LoadState =
   | { status: "loading" }
+  | {
+      // Gallery state — shown for multi-Press workspaces at the root URL.
+      // Single-Press workspaces never reach this state.
+      status: "gallery";
+      manifest: WorkspaceManifest;
+      deploymentInfo: DeploymentInfo;
+    }
   | {
       status: "ready";
       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.
+      activeSlug: string;
     }
   | { status: "error"; message: string };
 
@@ -42,26 +61,93 @@ function LoadingScreen() {
 export function OpenPressApp() {
   const [state, setState] = useState<LoadState>({ status: "loading" });
 
+  // Single resolution function — same code path for "boot from URL",
+  // "click gallery card", and "browser back button". Given a manifest
+  // + slug, decides whether to render gallery or load a press.
+  const resolveFromSlug = useCallback(async (
+    manifest: WorkspaceManifest | null,
+    slug: string,
+    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: "" });
+      return;
+    }
+
+    // Empty slug + multi-Press: show gallery. Empty slug + single-Press:
+    // load the only press. Same expression handles both — array length
+    // is the only thing that matters.
+    const normalizedSlug = normalizeSlug(slug);
+    if (!normalizedSlug && manifestHasMultiplePresses(manifest)) {
+      setState({ status: "gallery", manifest, deploymentInfo });
+      return;
+    }
+
+    const press = normalizedSlug
+      ? findManifestPress(manifest, normalizedSlug)
+      : manifest.presses[0];
+    if (!press) {
+      setState({
+        status: "error",
+        message: `Unknown document slug "/${normalizedSlug}". Known: ${manifest.presses.map((p) => `/${p.slug}`).join(", ")}.`,
+      });
+      return;
+    }
+    const document = await loadReaderDocument(press.documentUrl);
+    setState({ status: "ready", document, deploymentInfo, manifest, activeSlug: press.slug });
+  }, []);
+
   const refreshDocument = useCallback(async () => {
-    const document = await loadReaderDocument();
-    setState((current) => {
-      if (current.status !== "ready") return current;
-      return { ...current, document };
+    if (state.status !== "ready") return;
+    const press = state.manifest
+      ? findManifestPress(state.manifest, state.activeSlug)
+      : null;
+    const url = press?.documentUrl ?? "/openpress/document.json";
+    const document = await loadReaderDocument(url);
+    setState((latest) => {
+      if (latest.status !== "ready") return latest;
+      return { ...latest, document };
     });
-  }, []);
+  }, [state]);
 
+  // Gallery click → pushState + load. Bypasses resolveFromSlug's
+  // "empty slug + multi-Press → gallery" branch: an explicit click on
+  // the unslugged root Press must enter it, not bounce back to gallery.
+  const enterPress = useCallback(async (press: WorkspaceManifestPress) => {
+    if (state.status !== "gallery") return;
+    pushSlug(press.slug);
+    setState({ status: "loading" });
+    try {
+      const document = await loadReaderDocument(press.documentUrl);
+      setState({
+        status: "ready",
+        document,
+        deploymentInfo: state.deploymentInfo,
+        manifest: state.manifest,
+        activeSlug: press.slug,
+      });
+    } catch (error) {
+      setState({
+        status: "error",
+        message: error instanceof Error ? error.message : "Unable to load OpenPress document.",
+      });
+    }
+  }, [state]);
+
+  // Bootstrap: read URL → load manifest + deploy info → resolve.
   useEffect(() => {
     let cancelled = false;
 
-    async function loadDocument() {
+    async function bootstrap() {
       try {
-        const [document, deploymentInfo] = await Promise.all([
-          loadReaderDocument(),
+        const [manifest, deploymentInfo] = await Promise.all([
+          loadWorkspaceManifest(),
           loadDeploymentInfo(),
         ]);
-        if (!cancelled) {
-          setState({ status: "ready", document, deploymentInfo });
-        }
+        if (cancelled) return;
+        await resolveFromSlug(manifest, currentSlugFromLocation(), deploymentInfo);
       } catch (error) {
         if (!cancelled) {
           setState({
@@ -72,11 +158,29 @@ export function OpenPressApp() {
       }
     }
 
-    void loadDocument();
+    void bootstrap();
     return () => {
       cancelled = true;
     };
-  }, []);
+  }, [resolveFromSlug]);
+
+  // Back / forward button — re-resolve from the new URL.
+  useEffect(() => {
+    function onPopState() {
+      if (state.status === "loading") return;
+      const manifest = state.status === "gallery"
+        ? state.manifest
+        : state.status === "ready"
+        ? state.manifest
+        : null;
+      const deploymentInfo = state.status === "gallery" || state.status === "ready"
+        ? state.deploymentInfo
+        : offlineDeploymentInfo;
+      void resolveFromSlug(manifest, currentSlugFromLocation(), deploymentInfo);
+    }
+    window.addEventListener("popstate", onPopState);
+    return () => window.removeEventListener("popstate", onPopState);
+  }, [state, resolveFromSlug]);
 
   if (state.status === "loading") return <LoadingScreen />;
 
@@ -84,19 +188,71 @@ export function OpenPressApp() {
     return <div className="openpress-load-state openpress-load-state--error">{state.message}</div>;
   }
 
+  if (state.status === "gallery") {
+    return <WorkspaceGalleryPage manifest={state.manifest} onSelectPress={enterPress} />;
+  }
+
+  // Only multi-Press workspaces have a gallery to go back to. Single-Press
+  // workspaces don't render the button (no destination exists).
+  const backToWorkspace = state.manifest && manifestHasMultiplePresses(state.manifest)
+    ? () => {
+        if (state.status !== "ready" || !state.manifest) return;
+        pushSlug("");
+        setState({
+          status: "gallery",
+          manifest: state.manifest,
+          deploymentInfo: state.deploymentInfo,
+        });
+      }
+    : undefined;
+
   return (
     <OpenPressRuntime
       document={state.document}
       deploymentInfo={state.deploymentInfo}
       onDocumentRefresh={refreshDocument}
+      onBackToWorkspace={backToWorkspace}
     />
   );
 }
 
-async function loadReaderDocument(): Promise<ReaderDocument> {
-  const response = await fetch("/openpress/document.json", { cache: "no-store" });
+function currentSlugFromLocation(): string {
+  if (typeof window === "undefined") return "";
+  return normalizeSlug(window.location.pathname);
+}
+
+function normalizeSlug(raw: string): string {
+  return raw.replace(/^\/+|\/+$/g, "");
+}
+
+function pushSlug(slug: string) {
+  if (typeof window === "undefined") return;
+  // Preserve the current query string (e.g. ?dev=1 keeps the workbench
+  // chrome alive across gallery navigation). Drop the hash — it's a
+  // page anchor that means nothing in a different document.
+  const pathname = slug ? `/${normalizeSlug(slug)}` : "/";
+  const target = `${pathname}${window.location.search}`;
+  if (window.location.pathname === pathname) return;
+  window.history.pushState({}, "", target);
+}
+
+async function loadWorkspaceManifest(): Promise<WorkspaceManifest | null> {
+  // Optional — older deployments don't ship workspace.json. The reader
+  // falls back to /openpress/document.json directly when missing, which
+  // matches pre-v1.0 behavior.
+  try {
+    const response = await fetch("/openpress/workspace.json", { cache: "no-store" });
+    if (!response.ok) return null;
+    return (await response.json()) as WorkspaceManifest;
+  } catch {
+    return null;
+  }
+}
+
+async function loadReaderDocument(url: string): Promise<ReaderDocument> {
+  const response = await fetch(url, { cache: "no-store" });
   if (!response.ok) {
-    throw new Error(`Unable to load /openpress/document.json (${response.status})`);
+    throw new Error(`Unable to load ${url} (${response.status})`);
   }
   return (await response.json()) as ReaderDocument;
 }

package/src/openpress/app/OpenPressRuntime.tsx

@@ -13,12 +13,17 @@ interface OpenPressRuntimeProps {
   document: ReaderDocument;
   deploymentInfo?: DeploymentInfo;
   onDocumentRefresh?: () => void | Promise<void>;
+  // Optional — supplied by OpenPressApp when this Press was entered from
+  // a multi-Press gallery. Renders a "工作台" home button in the toolbar
+  // that returns to the gallery without a full page reload.
+  onBackToWorkspace?: () => void;
 }
 
 export function OpenPressRuntime({
   document,
   deploymentInfo = { online: false },
   onDocumentRefresh,
+  onBackToWorkspace,
 }: OpenPressRuntimeProps) {
   const style = themeToCssVariables(document.theme);
   const htmlPages = document.blocks.filter((block): block is HtmlPageBlock => block.kind === "htmlPage");
@@ -48,6 +53,7 @@ export function OpenPressRuntime({
         devMode={workspaceMode}
         deploymentInfo={deploymentInfo}
         onDocumentRefresh={onDocumentRefresh}
+        onBackToWorkspace={onBackToWorkspace}
       />
     );
   }
@@ -62,11 +68,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>document/chapters/**/content/</code>, then re-export.
+          Add React MDX chapter files under <code>press/chapters/**/content/</code>, then re-build.
         </p>
         {workspaceMode ? (
           <ol className="openpress-empty-state__steps">
-            <li><code>npm run openpress:export</code> &nbsp;— refreshes <code>public/openpress/document.json</code></li>
+            <li><code>npm run build</code> &nbsp;— validates and refreshes <code>public/openpress/document.json</code></li>
             <li>Reload this page</li>
           </ol>
         ) : (
@@ -88,6 +94,8 @@ function themeToCssVariables(theme?: Theme) {
 
   if (theme?.pageWidth) style["--openpress-page-width"] = theme.pageWidth;
   if (theme?.pageHeight) style["--openpress-page-height"] = theme.pageHeight;
+  if (theme?.pageAspectRatio) style["--openpress-page-aspect-ratio"] = theme.pageAspectRatio;
+  if (theme?.pageHeightRatio) style["--openpress-page-height-ratio"] = theme.pageHeightRatio;
   if (theme?.pagePadding) style["--openpress-page-padding"] = theme.pagePadding;
 
   return style;

package/src/openpress/app/WorkspaceGalleryPage.tsx

@@ -0,0 +1,219 @@
+import { useEffect, useRef, useState, type CSSProperties, type KeyboardEvent } from "react";
+import type { HtmlPageBlock, ReaderDocument, WorkspaceManifest, WorkspaceManifestPress } from "../document-model";
+
+interface Props {
+  manifest: WorkspaceManifest;
+  // Called when the reader navigates into a specific Press. The host
+  // is responsible for routing (history.pushState, hash, etc.); the
+  // gallery just emits the chosen slug.
+  onSelectPress: (press: WorkspaceManifestPress) => void;
+}
+
+// Reader landing page for multi-Press workspaces. Shows a Figma-style
+// uniform-grid card per Press; each card lazily loads that Press's
+// document.json and renders the first page as a thumbnail preview.
+// Single-Press workspaces skip the gallery entirely.
+export function WorkspaceGalleryPage({ manifest, onSelectPress }: Props) {
+  const heading = manifest.name ?? "Workspace";
+  const pressCount = String(manifest.presses.length).padStart(2, "0");
+
+  return (
+    <main className="openpress-workspace-gallery" aria-labelledby="workspace-gallery-heading">
+      <header className="openpress-workspace-gallery__header">
+        <div className="openpress-workspace-gallery__headline">
+          <p className="openpress-workspace-gallery__eyebrow">Workspace</p>
+          <h1 id="workspace-gallery-heading">{heading}</h1>
+        </div>
+        <p className="openpress-workspace-gallery__count">
+          <span>{pressCount}</span>
+          <small>{manifest.presses.length === 1 ? "document" : "documents"}</small>
+        </p>
+      </header>
+
+      <ul className="openpress-workspace-gallery__grid" role="list">
+        {manifest.presses.map((press) => (
+          <li key={press.slug || "root"} className="openpress-workspace-gallery__item">
+            <PressCard press={press} onSelect={() => onSelectPress(press)} />
+          </li>
+        ))}
+      </ul>
+    </main>
+  );
+}
+
+// Card is a div+role=button (not <button>) so it can contain the
+// rendered page HTML — buttons may only hold phrasing content, and
+// page HTML is block-level.
+function PressCard({ press, onSelect }: { press: WorkspaceManifestPress; onSelect: () => void }) {
+  const handleKey = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      onSelect();
+    }
+  };
+
+  return (
+    <div
+      role="button"
+      tabIndex={0}
+      className="openpress-workspace-gallery__card"
+      onClick={onSelect}
+      onKeyDown={handleKey}
+      aria-label={`Open ${press.title}`}
+    >
+      <PressThumbnail press={press} />
+      <div className="openpress-workspace-gallery__body">
+        <div className="openpress-workspace-gallery__title">{press.title}</div>
+        <div className="openpress-workspace-gallery__meta">
+          {press.slug ? <span className="openpress-workspace-gallery__slug">{press.slug}</span> : null}
+          {press.page?.pageLabel ? (
+            <span className="openpress-workspace-gallery__geom">{press.page.pageLabel}</span>
+          ) : null}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function PressThumbnail({ press }: { press: WorkspaceManifestPress }) {
+  const [state, setState] = useState<ThumbnailState>({ status: "loading" });
+
+  // Lazy-load each Press's document.json so the gallery doesn't block
+  // on a network waterfall when there are many Press. Errors degrade
+  // to the geometry-only placeholder used by the loading state.
+  useEffect(() => {
+    let cancelled = false;
+    fetchFirstPage(press.documentUrl).then((page) => {
+      if (cancelled) return;
+      setState(page ? { status: "ready", page } : { status: "error" });
+    }).catch(() => {
+      if (!cancelled) setState({ status: "error" });
+    });
+    return () => { cancelled = true; };
+  }, [press.documentUrl]);
+
+  // Outer card is uniform 4:3 (set in CSS). The page itself letterboxes
+  // inside via centered scale, so A4 portrait renders tall-and-narrow,
+  // social square renders centered, 16:9 slide stretches edge-to-edge.
+  return (
+    <div className="openpress-workspace-gallery__thumb" aria-hidden="true">
+      {state.status === "ready" ? (
+        <PageMiniature page={state.page} press={press} />
+      ) : (
+        <div className="openpress-workspace-gallery__thumb-placeholder" data-state={state.status}>
+          <div className="openpress-workspace-gallery__thumb-skel" style={skelAspectStyle(press)} />
+        </div>
+      )}
+    </div>
+  );
+}
+
+function skelAspectStyle(press: WorkspaceManifestPress): CSSProperties {
+  const w = parsePxLength(press.page?.pageWidth);
+  const h = parsePxLength(press.page?.pageHeight);
+  if (w && h) return { aspectRatio: `${w} / ${h}`, height: "75%" };
+  return { aspectRatio: "1 / 1.414", height: "75%" };
+}
+
+function PageMiniature({ page, press }: { page: HtmlPageBlock; press: WorkspaceManifestPress }) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [scale, setScale] = useState<number | null>(null);
+  const pageWidthPx = parsePxLength(press.page?.pageWidth) ?? 1080;
+  const pageHeightPx = parsePxLength(press.page?.pageHeight) ?? pageWidthPx;
+
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const update = () => {
+      const w = el.clientWidth;
+      const h = el.clientHeight;
+      if (w > 0 && h > 0) {
+        setScale(Math.min(w / pageWidthPx, h / pageHeightPx));
+      }
+    };
+    update();
+    if (typeof ResizeObserver === "undefined") return;
+    const ro = new ResizeObserver(update);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [pageWidthPx, pageHeightPx]);
+
+  const scaledWidth = scale ? pageWidthPx * scale : 0;
+  const scaledHeight = scale ? pageHeightPx * scale : 0;
+  const frameStyle: CSSProperties = {
+    width: `${scaledWidth}px`,
+    height: `${scaledHeight}px`,
+    position: "relative",
+    visibility: scale ? "visible" : "hidden",
+  };
+
+  // Match the wrapping used by PublicReaderPage so scoped CSS targeting
+  // `.openpress-html-page__html` selectors lights up identically. The
+  // outer frame owns centering; the page only scales from its top-left
+  // origin, which avoids mixed translate/scale centering drift.
+  const pageStyle: CSSProperties = {
+    "--openpress-page-width": `${pageWidthPx}px`,
+    "--openpress-page-height": `${pageHeightPx}px`,
+    width: `${pageWidthPx}px`,
+    height: `${pageHeightPx}px`,
+    transform: scale ? `scale(${scale})` : undefined,
+    transformOrigin: "top left",
+    position: "absolute",
+    top: 0,
+    left: 0,
+  } as CSSProperties;
+  const pageClass = page.className
+    ? `openpress-html-page ${page.className}`
+    : "openpress-html-page";
+
+  return (
+    <div className="openpress-workspace-gallery__thumb-stage" ref={containerRef}>
+      <div className="openpress-workspace-gallery__thumb-frame" style={frameStyle}>
+        <div className={pageClass} style={pageStyle} data-openpress-thumb-page="true">
+          <div
+            className="openpress-html-page__html"
+            // Trusted HTML — same source as the reader's main render path.
+            dangerouslySetInnerHTML={{ __html: page.html }}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}
+
+type ThumbnailState =
+  | { status: "loading" }
+  | { status: "error" }
+  | { status: "ready"; page: HtmlPageBlock };
+
+async function fetchFirstPage(url: string): Promise<HtmlPageBlock | null> {
+  try {
+    const response = await fetch(url, { cache: "no-store" });
+    if (!response.ok) return null;
+    const doc = (await response.json()) as ReaderDocument;
+    const firstPage = doc.blocks.find((b): b is HtmlPageBlock => b.kind === "htmlPage");
+    return firstPage ?? null;
+  } catch {
+    return 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.
+function parsePxLength(value: string | undefined): number | null {
+  if (!value) return null;
+  const match = value.trim().match(/^([\d.]+)\s*(px|mm|cm|in)$/i);
+  if (!match) return null;
+  const n = Number(match[1]);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  const unit = match[2].toLowerCase();
+  switch (unit) {
+    case "px": return n;
+    case "mm": return n * (96 / 25.4);
+    case "cm": return n * (96 / 2.54);
+    case "in": return n * 96;
+    default: return null;
+  }
+}

package/src/openpress/core/Frame.tsx

@@ -3,7 +3,7 @@ import { cn } from "./cn";
 import { FrameContext, type FrameContextValue } from "./FrameContext";
 import { PressContext } from "./Press";
 import type { FrameProps } from "./types";
-import { createFrameObjectEntityId } from "../document-model/objectEntityModel";
+import { createFrameObjectEntityId, createPageObjectEntityId, createScopedObjectEntityId } from "../document-model/objectEntityModel";
 
 // Substring reserved for the overflow extension pipeline.
 const RESERVED_EXTENDED = ":extended:";
@@ -28,15 +28,22 @@ export function Frame({
     );
   }
 
+  const parentFrame = useContext(FrameContext);
   const press = useContext(PressContext);
   const allocation = press?.allocation ?? null;
   const frameAllocation = frameKey && allocation ? allocation[frameKey] : undefined;
+  const pageId = parentFrame?.pageId ?? createPageObjectEntityId(frameKey);
+  const objectId = parentFrame
+    ? createScopedObjectEntityId("frame", parentFrame.objectId, frameKey)
+    : createFrameObjectEntityId(frameKey);
 
   // 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 ?? "",
+    objectId,
+    pageId,
     consumeArea(chainId: string) {
       const index = areaCounts[chainId] ?? 0;
       areaCounts[chainId] = index + 1;
@@ -48,18 +55,24 @@ export function Frame({
   };
 
   const pageKind = derivePageKind(role);
+  const isNestedFrame = Boolean(parentFrame);
 
   return (
     <FrameContext.Provider value={frameContextValue}>
       <section
         {...(rest as Record<string, unknown>)}
-        className={cn("reader-page", className)}
-        data-openpress-frame-key={frameKey}
-        data-openpress-object-id={createFrameObjectEntityId(frameKey)}
+        className={cn(isNestedFrame ? undefined : "reader-page", className)}
+        data-openpress-frame-key={isNestedFrame ? undefined : frameKey}
+        data-openpress-region-frame-key={isNestedFrame ? frameKey : undefined}
+        data-openpress-object-id={objectId}
+        data-openpress-object-kind="frame"
+        data-openpress-object-label={role ?? frameKey}
+        data-openpress-object-parent-id={parentFrame?.objectId ?? (isNestedFrame ? undefined : pageId)}
+        data-openpress-object-page-id={pageId}
         data-frame-role={role}
-        data-page-kind={pageKind}
-        data-frame-chrome={chrome ? "true" : "false"}
-        data-page-footer={chrome ? "true" : "false"}
+        data-page-kind={isNestedFrame ? undefined : pageKind}
+        data-frame-chrome={isNestedFrame ? undefined : chrome ? "true" : "false"}
+        data-page-footer={isNestedFrame ? undefined : chrome ? "true" : "false"}
       >
         {children}
       </section>

package/src/openpress/core/FrameContext.tsx

@@ -18,6 +18,8 @@ export interface ConsumedMdxArea {
 
 export interface FrameContextValue {
   frameKey: string;
+  objectId: string;
+  pageId: string;
   consumeArea(chainId: string): ConsumedMdxArea;
 }
 

package/src/openpress/core/Press.tsx

@@ -1,5 +1,5 @@
-import { createContext, Fragment, type ReactNode } from "react";
-import type { FrameAllocation, ResolvedSource, TocEntry } from "./types";
+import { createContext, Fragment } from "react";
+import type { FrameAllocation, PressProps, 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
@@ -14,6 +14,18 @@ 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.
+export interface PressMetadata {
+  title?: string;
+  page?: PressProps["page"];
+  slug?: string;
+  theme?: string;
+  componentsDir?: string;
+}
+
 export interface PressContextValue {
   sources: Record<string, ResolvedSource>;
   // Allocation map keyed by frameKey -> chainId -> areaIndex -> blocks.
@@ -23,12 +35,21 @@ 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?: PressMetadata;
 }
 
 export const PressContext = createContext<PressContextValue | null>(null);
 
-export function Press({ children }: { children: ReactNode }) {
-  return <Fragment>{children}</Fragment>;
+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>;
 }
 
 (Press as unknown as { openpressMarker: typeof PRESS_MARKER }).openpressMarker = PRESS_MARKER;

package/src/openpress/core/Workspace.tsx

@@ -0,0 +1,36 @@
+import { createContext, Fragment } from "react";
+import type { WorkspaceProps } from "./types";
+
+// Marker the engine uses to identify a Workspace default export, in the
+// same way PRESS_MARKER identifies Press. Multi-doc projects nest one
+// or more <Press> children inside <Workspace>; single-doc projects use
+// a Workspace with one Press child (uniform shape — no exceptions).
+export const WORKSPACE_MARKER: unique symbol = Symbol.for("@open-press/core:Workspace");
+
+export interface WorkspaceContextValue {
+  // Project-level label surfaced in the gallery header / tab bar / PDF
+  // metadata. Undefined if the Workspace did not declare a name.
+  name?: string;
+  // Workspace-level shared theme directory. Press children that don't
+  // set their own `theme` prop inherit from this.
+  theme?: string;
+  // Workspace-level shared media directory.
+  media?: string;
+  // Number of Press children registered in this Workspace. Set by the
+  // engine during expansion; useful to detect "gallery vs single-doc"
+  // routing without re-walking the tree.
+  pressCount: number;
+}
+
+export const WorkspaceContext = createContext<WorkspaceContextValue | null>(null);
+
+// Workspace is intentionally inert at render time. The engine inspects
+// its props (name / theme / media) and iterates Press children during
+// the export pipeline; rendering just passes children through so the
+// Press → Frame → MdxArea tree underneath behaves identically to v0.x
+// when there's only one Press child.
+export function Workspace(props: WorkspaceProps) {
+  return <Fragment>{props.children}</Fragment>;
+}
+
+(Workspace as unknown as { openpressMarker: typeof WORKSPACE_MARKER }).openpressMarker = WORKSPACE_MARKER;