@open-press/core 0.7.1 → 1.0.0

package/engine/runtime/validation.mjs

@@ -17,6 +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.
+async function isWorkspaceRoot(dir) {
+  try {
+    await fs.access(path.join(dir, "press", "index.tsx"));
+    return true;
+  } catch {}
+  try {
+    const pkg = JSON.parse(await fs.readFile(path.join(dir, "package.json"), "utf8"));
+    if (pkg?.openpress && typeof pkg.openpress === "object") return true;
+  } catch {}
+  return false;
+}
+
 export async function discoverWorkspace(startPath = ".") {
   let current = path.resolve(startPath);
   try {
@@ -26,15 +40,10 @@ export async function discoverWorkspace(startPath = ".") {
     current = path.dirname(current);
   }
   while (true) {
-    const configPath = path.join(current, "openpress.config.mjs");
-    try {
-      await fs.access(configPath);
-      return current;
-    } catch {
-      const parent = path.dirname(current);
-      if (parent === current) throw new Error(`No OpenPress workspace found from ${startPath}`);
-      current = parent;
-    }
+    if (await isWorkspaceRoot(current)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) throw new Error(`No OpenPress workspace found from ${startPath}`);
+    current = parent;
   }
 }
 
@@ -78,7 +87,7 @@ export async function validateWorkspace(root) {
 
   mark(sourceWorkspace.checkedName);
   if (!(typeof activeConfig.title === "string" && activeConfig.title.trim())) {
-    add("warning", "config.title", "openpress.config.mjs `title` is empty; the workbench will show the default placeholder.", activeConfig.configPath);
+    add("warning", "press.title", "<Press title> is missing in press/index.tsx; the workbench will show the default placeholder.", activeConfig.configPath);
   }
   if (!(await sourceDirectoryExists(sourceWorkspace))) {
     add("warning", sourceWorkspace.missingCode, sourceWorkspace.missingMessage, sourceWorkspace.sourceDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-press/core",
-  "version": "0.7.1",
+  "version": "1.0.0",
   "type": "module",
   "description": "open-press core — runtime primitives, CLI, and render pipeline for AI-first fixed-layout documents.",
   "license": "MIT",
@@ -48,6 +48,7 @@
   "dependencies": {
     "@mdx-js/mdx": "^3.1.1",
     "@mdx-js/react": "^3.1.1",
+    "html-to-image": "^1.11.13",
     "js-yaml": "^4.1.1",
     "katex": "^0.16.47",
     "lucide-react": "^1.16.0",
@@ -80,11 +81,8 @@
     "test:e2e:reader": "playwright test --config playwright.reader.config.ts",
     "test:node": "node --test tests/*.test.mjs",
     "test:react": "vitest run",
-    "openpress:validate": "node engine/cli.mjs validate .",
-    "openpress:export": "node engine/cli.mjs export .",
+    "openpress:image": "node engine/cli.mjs image .",
     "openpress:pdf": "node engine/cli.mjs pdf .",
-    "openpress:render": "node engine/cli.mjs render . --renderer react",
-    "openpress:preview": "node engine/cli.mjs preview . --renderer react",
     "openpress:deploy": "node engine/cli.mjs deploy .",
     "openpress:deploy:dry-run": "node engine/cli.mjs deploy . --confirm --dry-run"
   }

package/src/openpress/app/OpenPressApp.tsx

@@ -0,0 +1,296 @@
+import { useCallback, useEffect, useState } from "react";
+import { OpenPressRuntime } from "./OpenPressRuntime";
+import { WorkspaceGalleryPage } from "./WorkspaceGalleryPage";
+import { isLocalWorkspaceHost } from "../shared";
+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 };
+
+interface DeployConfig {
+  pdf?: string;
+  deployed_at?: string;
+  public_url?: string;
+  dirty?: boolean;
+  deploy_configured?: boolean;
+  deploy_adapter?: string;
+  deploy_source?: string;
+  deploy_project_name?: string | null;
+  deploy_setup_message?: string;
+}
+
+const offlineDeploymentInfo: DeploymentInfo = { online: false };
+
+function LoadingScreen() {
+  return (
+    <div className="openpress-loading-screen" aria-label="載入中" role="status">
+      <div className="openpress-loading-screen__inner">
+        <div className="openpress-loading-dots" aria-hidden="true">
+          <span /><span /><span />
+        </div>
+        <span className="openpress-loading-screen__label">載入文件</span>
+      </div>
+    </div>
+  );
+}
+
+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 () => {
+    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 bootstrap() {
+      try {
+        const [manifest, deploymentInfo] = await Promise.all([
+          loadWorkspaceManifest(),
+          loadDeploymentInfo(),
+        ]);
+        if (cancelled) return;
+        await resolveFromSlug(manifest, currentSlugFromLocation(), deploymentInfo);
+      } catch (error) {
+        if (!cancelled) {
+          setState({
+            status: "error",
+            message: error instanceof Error ? error.message : "Unable to load OpenPress document.",
+          });
+        }
+      }
+    }
+
+    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 />;
+
+  if (state.status === "error") {
+    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}
+    />
+  );
+}
+
+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 ${url} (${response.status})`);
+  }
+  return (await response.json()) as ReaderDocument;
+}
+
+async function loadDeploymentInfo(): Promise<DeploymentInfo> {
+  if (typeof window !== "undefined" && isLocalWorkspaceHost(window.location.hostname)) {
+    const localInfo = await loadDeploymentInfoFrom("/__openpress/status");
+    if (localInfo) return localInfo;
+  }
+
+  return (await loadDeploymentInfoFrom("/openpress/deploy.json")) ?? offlineDeploymentInfo;
+}
+
+async function loadDeploymentInfoFrom(path: string): Promise<DeploymentInfo | null> {
+  try {
+    const response = await fetch(path, { cache: "no-store" });
+    if (!response.ok) {
+      return null;
+    }
+    const config = (await response.json()) as DeployConfig;
+    return deploymentConfigToInfo(config);
+  } catch {
+    return null;
+  }
+}
+
+function deploymentConfigToInfo(config: DeployConfig): DeploymentInfo {
+  const configured = config.deploy_configured !== false;
+  return {
+    online: configured && Boolean(config.deployed_at || config.public_url),
+    deployedAt: config.deployed_at,
+    pdf: typeof config.pdf === "string" ? config.pdf : undefined,
+    publicUrl: typeof config.public_url === "string" ? config.public_url : undefined,
+    dirty: config.dirty === true,
+    configured,
+    adapter: typeof config.deploy_adapter === "string" ? config.deploy_adapter : undefined,
+    source: typeof config.deploy_source === "string" ? config.deploy_source : undefined,
+    projectName: typeof config.deploy_project_name === "string" ? config.deploy_project_name : undefined,
+    setupMessage: typeof config.deploy_setup_message === "string" ? config.deploy_setup_message : undefined,
+  };
+}

package/src/openpress/{renderer.tsx → app/OpenPressRuntime.tsx}

@@ -1,23 +1,30 @@
 import { useMemo, type CSSProperties } from "react";
-import { PrintDocument, PublicViewer } from "./publicPage";
-import { isPrintModeLocation, isWorkspaceModeLocation } from "./runtimeMode";
-import { HtmlWorkbench } from "./workbench";
+import { PrintDocument, PublicViewer } from "../reader";
+import { isPrintModeLocation, isWorkspaceModeLocation } from "../shared";
+import { HtmlWorkbench } from "../workbench";
 import type {
   DeploymentInfo,
   ReaderDocument,
   HtmlPageBlock,
   Theme,
-} from "./types";
+} from "../document-model";
 
-interface RendererProps {
+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 Renderer({
+export function OpenPressRuntime({
   document,
   deploymentInfo = { online: false },
-}: RendererProps) {
+  onDocumentRefresh,
+  onBackToWorkspace,
+}: OpenPressRuntimeProps) {
   const style = themeToCssVariables(document.theme);
   const htmlPages = document.blocks.filter((block): block is HtmlPageBlock => block.kind === "htmlPage");
   const workspaceMode = useMemo(() => {
@@ -45,6 +52,8 @@ export function Renderer({
         style={style}
         devMode={workspaceMode}
         deploymentInfo={deploymentInfo}
+        onDocumentRefresh={onDocumentRefresh}
+        onBackToWorkspace={onBackToWorkspace}
       />
     );
   }
@@ -59,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>
         ) : (
@@ -85,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/app/index.ts

@@ -0,0 +1,2 @@
+export { OpenPressApp } from "./OpenPressApp";
+export { OpenPressRuntime } from "./OpenPressRuntime";