@open-press/core 1.1.2 → 1.1.4

package/engine/runtime/inspection.mjs

@@ -139,9 +139,51 @@ export async function inspectRenderedOverflow({ root, config, host = "127.0.0.1"
   }
 }
 
-export async function waitForInspectionReady(client) {
-  const deadline = Date.now() + 30000;
-  while (Date.now() < deadline) {
+export const INSPECTION_READY_DEFAULTS = Object.freeze({
+  totalTimeoutMs: 300_000,
+  idleTimeoutMs: 30_000,
+  pollIntervalMs: 100,
+});
+
+export function resolveInspectionReadyTiming(env = process.env) {
+  const total = Number(env.OPENPRESS_INSPECTION_TIMEOUT_MS);
+  const idle = Number(env.OPENPRESS_INSPECTION_IDLE_MS);
+  return {
+    totalTimeoutMs: Number.isFinite(total) && total > 0 ? total : INSPECTION_READY_DEFAULTS.totalTimeoutMs,
+    idleTimeoutMs: Number.isFinite(idle) && idle > 0 ? idle : INSPECTION_READY_DEFAULTS.idleTimeoutMs,
+    pollIntervalMs: INSPECTION_READY_DEFAULTS.pollIntervalMs,
+  };
+}
+
+function formatInspectionTimeoutMessage(reason, snapshot, timing, elapsedMs) {
+  const seconds = Math.round(elapsedMs / 1000);
+  const observed = `(observed ${snapshot.pageCount} page(s))`;
+  if (reason === "idle") {
+    return (
+      `Timed out waiting for OpenPress pagination before inspection. ` +
+      `No progress for ${seconds}s ${observed}. ` +
+      `Raise OPENPRESS_INSPECTION_IDLE_MS (currently ${timing.idleTimeoutMs}ms) to extend the idle window.`
+    );
+  }
+  return (
+    `Timed out waiting for OpenPress pagination before inspection. ` +
+    `Total ${seconds}s exceeded ${observed}. ` +
+    `Raise OPENPRESS_INSPECTION_TIMEOUT_MS (currently ${timing.totalTimeoutMs}ms) to extend the hard cap.`
+  );
+}
+
+export async function waitForInspectionReady(client, timing = resolveInspectionReadyTiming()) {
+  const startedAt = Date.now();
+  let lastSignature = "";
+  let lastProgressAt = startedAt;
+  let lastSnapshot = { pageCount: 0 };
+
+  while (true) {
+    const totalElapsed = Date.now() - startedAt;
+    if (totalElapsed > timing.totalTimeoutMs) {
+      throw new Error(formatInspectionTimeoutMessage("total", lastSnapshot, timing, totalElapsed));
+    }
+
     const result = await client.send("Runtime.evaluate", {
       returnByValue: true,
       awaitPromise: true,
@@ -149,9 +191,23 @@ export async function waitForInspectionReady(client) {
     });
     const value = result.result?.value;
     if (Array.isArray(value)) return value;
-    await delay(100);
+
+    const pageCount = Number.isFinite(Number(value?.pageCount)) ? Number(value.pageCount) : lastSnapshot.pageCount;
+    lastSnapshot = { pageCount };
+
+    const signature = String(pageCount);
+    if (signature !== lastSignature) {
+      lastSignature = signature;
+      lastProgressAt = Date.now();
+    }
+
+    const idleElapsed = Date.now() - lastProgressAt;
+    if (idleElapsed > timing.idleTimeoutMs) {
+      throw new Error(formatInspectionTimeoutMessage("idle", lastSnapshot, timing, idleElapsed));
+    }
+
+    await delay(timing.pollIntervalMs);
   }
-  throw new Error("Timed out waiting for OpenPress pagination before inspection.");
 }
 
 export function overflowIssuesFromMeasurements(measurements) {
@@ -241,7 +297,9 @@ function humanOverflowTarget(code) {
 function inspectionExpression() {
   return `Promise.resolve().then(async () => {
     const root = document.querySelector('[data-openpress-print-document="true"]');
-    if (!root || root.querySelectorAll('.openpress-html-page').length === 0) return null;
+    if (!root) return { pending: true, pageCount: 0 };
+    const candidates = root.querySelectorAll('.openpress-html-page');
+    if (candidates.length === 0) return { pending: true, pageCount: 0 };
 
     await document.fonts?.ready;
     await Promise.all(Array.from(document.images).map(async (img) => {
@@ -290,7 +348,7 @@ function inspectionExpression() {
     };
 
     const wrappers = Array.from(document.querySelectorAll('.openpress-public-page > .openpress-html-page'));
-    if (wrappers.length === 0) return null;
+    if (wrappers.length === 0) return { pending: true, pageCount: candidates.length };
     return wrappers.map((wrapper, index) => {
       const page = wrapper.querySelector('.reader-page') || wrapper;
       const frame = page.querySelector('.page-frame') || page;

package/engine/runtime/page-selector.mjs

@@ -0,0 +1,87 @@
+const TOKEN_PATTERN = /^\s*(-?\d*)\s*(?:-\s*(\d*))?\s*$/;
+
+export function parsePageSelector(input) {
+  if (typeof input !== "string") {
+    throw new TypeError("Page selector must be a string");
+  }
+  const trimmed = input.trim();
+  if (trimmed === "") {
+    throw new Error("Page selector is empty; expected something like '3', '3,5-7', or '12-'.");
+  }
+
+  const segments = trimmed.split(",").map((part) => part.trim()).filter(Boolean);
+  if (segments.length === 0) {
+    throw new Error(`Page selector "${input}" has no usable segments.`);
+  }
+
+  return segments.map((segment) => parseSegment(segment, input));
+}
+
+function parseSegment(segment, original) {
+  if (!segment.includes("-")) {
+    const value = toPositiveInteger(segment, original);
+    return { kind: "single", value };
+  }
+
+  if (segment === "-") {
+    throw new Error(`Page selector "${original}" contains a bare "-"; ranges need at least one bound.`);
+  }
+
+  const dashIndex = segment.indexOf("-");
+  if (segment.indexOf("-", dashIndex + 1) !== -1) {
+    throw new Error(`Page selector segment "${segment}" has too many dashes.`);
+  }
+
+  const leftRaw = segment.slice(0, dashIndex);
+  const rightRaw = segment.slice(dashIndex + 1);
+  const from = leftRaw.trim() === "" ? null : toPositiveInteger(leftRaw, original);
+  const to = rightRaw.trim() === "" ? null : toPositiveInteger(rightRaw, original);
+
+  if (from != null && to != null && from > to) {
+    throw new Error(`Page selector range "${segment}" goes backwards (${from} > ${to}).`);
+  }
+
+  return { kind: "range", from, to };
+}
+
+function toPositiveInteger(raw, original) {
+  const trimmed = raw.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    throw new Error(`Page selector "${original}" contains non-integer token "${raw}".`);
+  }
+  const value = Number(trimmed);
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`Page selector "${original}" contains out-of-range page number "${raw}"; pages start at 1.`);
+  }
+  return value;
+}
+
+export function resolvePageSelector(spec, totalPages) {
+  if (!Array.isArray(spec)) {
+    throw new TypeError("resolvePageSelector expects a parsed selector array");
+  }
+  if (!Number.isInteger(totalPages) || totalPages < 0) {
+    throw new TypeError("resolvePageSelector expects a non-negative integer totalPages");
+  }
+  if (totalPages === 0) return [];
+
+  const selected = new Set();
+  for (const segment of spec) {
+    if (segment.kind === "single") {
+      if (segment.value > totalPages) {
+        throw new Error(`Page ${segment.value} is out of range; document has ${totalPages} page(s).`);
+      }
+      selected.add(segment.value);
+      continue;
+    }
+    const from = segment.from ?? 1;
+    const to = segment.to ?? totalPages;
+    if (from > totalPages) {
+      throw new Error(`Range start ${from} is out of range; document has ${totalPages} page(s).`);
+    }
+    const upper = Math.min(to, totalPages);
+    for (let i = from; i <= upper; i += 1) selected.add(i);
+  }
+
+  return Array.from(selected).sort((a, b) => a - b);
+}

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

@@ -93,8 +93,7 @@ export async function applySourceBlockTextEdit({
 }) {
   const requestedPath = stringValue(sourcePath);
   if (!requestedPath) throw new Error("Source edit requires a source path.");
-  const files = await collectSourceTextFiles(config, { scope: "content" });
-  const file = files.find((candidate) => sourceTextPathMatches(candidate.relativePath, requestedPath));
+  const file = await findEditableSourceTextFile(config, requestedPath);
   if (!file) throw new Error(`Editable source file not found: ${requestedPath}`);
 
   const result = sourceMode
@@ -120,8 +119,7 @@ export async function applySourceBlockTextEdit({
 export async function readSourceBlockText({ config, path: sourcePath, source }) {
   const requestedPath = stringValue(sourcePath);
   if (!requestedPath) throw new Error("Source read requires a source path.");
-  const files = await collectSourceTextFiles(config, { scope: "content" });
-  const file = files.find((candidate) => sourceTextPathMatches(candidate.relativePath, requestedPath));
+  const file = await findEditableSourceTextFile(config, requestedPath);
   if (!file) throw new Error(`Editable source file not found: ${requestedPath}`);
   return {
     path: file.relativePath,
@@ -205,6 +203,13 @@ export function applySourceBlockTextEditToText(documentText, {
       name,
     });
   }
+  if (kind === "object-text") {
+    return applySourceBlockObjectTextEditToText(documentText, {
+      source,
+      text,
+      blockId,
+    });
+  }
   if (kind === "element" && name === "pre") {
     return applySourceBlockCodeEditToText(documentText, {
       source,
@@ -265,6 +270,48 @@ export function applySourceBlockTextEditToText(documentText, {
   };
 }
 
+function applySourceBlockObjectTextEditToText(documentText, {
+  source,
+  text,
+  blockId,
+} = {}) {
+  const sourceRange = normalizeSourceRange(source);
+  const replacementText = normalizeEditedText(text);
+  const lines = splitTextLines(documentText);
+  const startIndex = sourceRange.line - 1;
+  const endIndex = sourceRange.endLine - 1;
+  if (!lines[startIndex]) throw new Error(`Source edit line ${sourceRange.line} is outside the source file.`);
+  if (!lines[endIndex]) throw new Error(`Source edit end line ${sourceRange.endLine} is outside the source file.`);
+
+  const selectedLines = lines.slice(startIndex, endIndex + 1);
+  const before = selectedLines.map((line) => line.line).join("\n");
+  const after = replaceSourceRangeText(before, sourceRange, replacementText);
+  const replacementLines = after.split("\n");
+  const ending = selectedLines[selectedLines.length - 1].ending;
+  const nextLines = [
+    ...lines.slice(0, startIndex),
+    ...replacementLines.map((line, index) => ({
+      line,
+      ending: index === replacementLines.length - 1 ? ending : "\n",
+    })),
+    ...lines.slice(endIndex + 1),
+  ];
+
+  return {
+    text: joinTextLines(nextLines),
+    edit: {
+      blockId,
+      line: sourceRange.line,
+      column: sourceRange.column,
+      endLine: sourceRange.endLine,
+      endColumn: sourceRange.endColumn,
+      before,
+      after,
+      text: replacementText,
+    },
+  };
+}
+
 function applySourceBlockCodeEditToText(documentText, {
   source,
   text,
@@ -722,6 +769,15 @@ function replaceTableCellContent(cell, replacementText) {
   return `${leading}${replacementText}${trailing}`;
 }
 
+function replaceSourceRangeText(sourceText, sourceRange, replacementText) {
+  const lines = sourceText.split("\n");
+  const firstLine = lines[0] ?? "";
+  const lastLine = lines[lines.length - 1] ?? "";
+  const prefix = firstLine.slice(0, Math.max(0, sourceRange.column - 1));
+  const suffix = lastLine.slice(Math.max(0, sourceRange.endColumn - 1));
+  return `${prefix}${replacementText}${suffix}`;
+}
+
 function markdownTextPrefix(line, { kind, name }) {
   if (kind === "list-item") return line.match(/^(\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?)/)?.[1] ?? "- ";
   if (name && /^h[1-6]$/.test(name)) return line.match(/^(\s{0,3}#{1,6}\s+)/)?.[1] ?? `${"#".repeat(Number(name.slice(1)))} `;
@@ -791,8 +847,8 @@ function applySourceBlockComponentCaptionEditToText(documentText, {
 }
 
 function assertEditableComponentCaption({ name, blockId }) {
-  if (name === "MediaFigure" || name === "ImageFigure") return;
-  throw new Error(`Only MediaFigure and ImageFigure caption props can be edited inline${blockId ? `: ${blockId}` : ""}.`);
+  if (typeof name === "string" && /^[A-Z][A-Za-z0-9_$]*$/.test(name)) return;
+  throw new Error(`Component caption edits require a named React component${blockId ? `: ${blockId}` : ""}.`);
 }
 
 function replaceComponentCaptionProp(sourceText, replacementText) {
@@ -820,6 +876,15 @@ function sourceTextPathMatches(candidatePath, requestedPath) {
   return normalizeSourceTextPath(candidatePath) === normalizeSourceTextPath(requestedPath);
 }
 
+async function findEditableSourceTextFile(config, requestedPath) {
+  const contentFiles = await collectSourceTextFiles(config, { scope: "content" });
+  const contentMatch = contentFiles.find((candidate) => sourceTextPathMatches(candidate.relativePath, requestedPath));
+  if (contentMatch) return contentMatch;
+
+  const allFiles = await collectSourceTextFiles(config, { scope: "all" });
+  return allFiles.find((candidate) => sourceTextPathMatches(candidate.relativePath, requestedPath));
+}
+
 function normalizeSourceTextPath(value) {
   return String(value ?? "")
     .replaceAll("\\", "/")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-press/core",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "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

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useState } from "react";
-import { OpenPressRuntime } from "./OpenPressRuntime";
+import { OpenPressRuntime, type OpenPressRuntimeMode } from "./OpenPressRuntime";
 import { WorkspaceGalleryPage } from "./WorkspaceGalleryPage";
 import { isLocalWorkspaceHost } from "../shared";
 import type {
@@ -28,9 +28,15 @@ type LoadState =
       // 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;
+      runtimeMode: OpenPressRuntimeMode;
     }
   | { status: "error"; message: string };
 
+interface WorkspaceRoute {
+  slug: string;
+  mode: OpenPressRuntimeMode;
+}
+
 interface DeployConfig {
   pdf?: string;
   deployed_at?: string;
@@ -63,23 +69,30 @@ export function OpenPressApp() {
 
   // 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 (
+  // + route, decides whether to render gallery or load a press.
+  const resolveFromRoute = useCallback(async (
     manifest: WorkspaceManifest | null,
-    slug: string,
+    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: "" });
+      setState({
+        status: "ready",
+        document,
+        deploymentInfo,
+        manifest,
+        activeSlug: "",
+        runtimeMode: resolveRuntimeMode(document, route.mode),
+      });
       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);
+    const normalizedSlug = normalizeSlug(route.slug);
     if (!normalizedSlug && manifestHasMultiplePresses(manifest)) {
       setState({ status: "gallery", manifest, deploymentInfo });
       return;
@@ -96,7 +109,14 @@ export function OpenPressApp() {
       return;
     }
     const document = await loadReaderDocument(press.documentUrl);
-    setState({ status: "ready", document, deploymentInfo, manifest, activeSlug: press.slug });
+    setState({
+      status: "ready",
+      document,
+      deploymentInfo,
+      manifest,
+      activeSlug: press.slug,
+      runtimeMode: resolveRuntimeMode(document, route.mode),
+    });
   }, []);
 
   const refreshDocument = useCallback(async () => {
@@ -112,12 +132,12 @@ export function OpenPressApp() {
     });
   }, [state]);
 
-  // Gallery click → pushState + load. Bypasses resolveFromSlug's
+  // 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.
   const enterPress = useCallback(async (press: WorkspaceManifestPress) => {
     if (state.status !== "gallery") return;
-    pushSlug(press.slug);
+    pushPressRoute(press.slug, "preview");
     setState({ status: "loading" });
     try {
       const document = await loadReaderDocument(press.documentUrl);
@@ -127,6 +147,7 @@ export function OpenPressApp() {
         deploymentInfo: state.deploymentInfo,
         manifest: state.manifest,
         activeSlug: press.slug,
+        runtimeMode: "preview",
       });
     } catch (error) {
       setState({
@@ -147,7 +168,7 @@ export function OpenPressApp() {
           loadDeploymentInfo(),
         ]);
         if (cancelled) return;
-        await resolveFromSlug(manifest, currentSlugFromLocation(), deploymentInfo);
+        await resolveFromRoute(manifest, currentRouteFromLocation(), deploymentInfo);
       } catch (error) {
         if (!cancelled) {
           setState({
@@ -162,7 +183,7 @@ export function OpenPressApp() {
     return () => {
       cancelled = true;
     };
-  }, [resolveFromSlug]);
+  }, [resolveFromRoute]);
 
   // Back / forward button — re-resolve from the new URL.
   useEffect(() => {
@@ -176,11 +197,11 @@ export function OpenPressApp() {
       const deploymentInfo = state.status === "gallery" || state.status === "ready"
         ? state.deploymentInfo
         : offlineDeploymentInfo;
-      void resolveFromSlug(manifest, currentSlugFromLocation(), deploymentInfo);
+      void resolveFromRoute(manifest, currentRouteFromLocation(), deploymentInfo);
     }
     window.addEventListener("popstate", onPopState);
     return () => window.removeEventListener("popstate", onPopState);
-  }, [state, resolveFromSlug]);
+  }, [state, resolveFromRoute]);
 
   if (state.status === "loading") return <LoadingScreen />;
 
@@ -197,7 +218,7 @@ export function OpenPressApp() {
   const backToWorkspace = state.manifest && manifestHasMultiplePresses(state.manifest)
     ? () => {
         if (state.status !== "ready" || !state.manifest) return;
-        pushSlug("");
+        pushPressRoute("", "preview");
         setState({
           status: "gallery",
           manifest: state.manifest,
@@ -206,49 +227,97 @@ export function OpenPressApp() {
       }
     : undefined;
 
+  const presentationSlug = state.activeSlug || currentRouteFromLocation().slug;
+  const openPresentation = state.document.meta.type === "slides" && presentationSlug
+    ? (pageIndex: number) => {
+        openPressRoute(presentationSlug, "present", pageIndex, { fullscreen: true });
+      }
+    : undefined;
+
+  const exitPresentation = state.document.meta.type === "slides"
+    ? (pageIndex: number) => {
+        if (state.status !== "ready") return;
+        const slug = state.activeSlug || currentRouteFromLocation().slug;
+        if (slug) pushPressRoute(slug, "preview", pageIndex);
+        setState((latest) => latest.status === "ready"
+          ? { ...latest, runtimeMode: "preview" }
+          : latest);
+      }
+    : undefined;
+
   return (
     <OpenPressRuntime
       document={state.document}
+      runtimeMode={state.runtimeMode}
       deploymentInfo={state.deploymentInfo}
       onDocumentRefresh={refreshDocument}
+      onOpenPresentation={openPresentation}
+      onExitPresentation={exitPresentation}
       onBackToWorkspace={backToWorkspace}
     />
   );
 }
 
-function currentSlugFromLocation(): string {
-  if (typeof window === "undefined") return "";
-  return slugFromWorkspacePathname(window.location.pathname);
+function currentRouteFromLocation(): WorkspaceRoute {
+  if (typeof window === "undefined") return { slug: "", mode: "preview" };
+  return routeFromWorkspacePathname(window.location.pathname);
 }
 
 function normalizeSlug(raw: string): string {
   return raw.replace(/^\/+|\/+$/g, "");
 }
 
-function slugFromWorkspacePathname(pathname: string): string {
+function routeFromWorkspacePathname(pathname: string): WorkspaceRoute {
   const normalized = normalizeSlug(pathname);
-  if (!normalized || normalized === "workspace") return "";
+  if (!normalized || normalized === "workspace") return { slug: "", mode: "preview" };
 
   const segments = normalized.split("/").filter(Boolean);
-  if (segments.length === 2 && segments[1] === "preview") {
-    return segments[0] ?? "";
+  if (segments.length === 2 && (segments[1] === "preview" || segments[1] === "present")) {
+    return { slug: segments[0] ?? "", mode: segments[1] };
   }
 
   // Legacy static/public route compatibility. New workspace navigation
   // writes /workspace and /<press-slug>/preview.
-  return normalized;
+  return { slug: normalized, mode: "preview" };
 }
 
-function pushSlug(slug: string) {
+function pushPressRoute(slug: string, mode: OpenPressRuntimeMode, pageIndex?: number) {
   if (typeof window === "undefined") return;
-  // Drop query + hash: workbench routing is path-based, and page anchors
-  // do not transfer across documents.
-  const pathname = slug ? `/${normalizeSlug(slug)}/preview` : "/workspace";
-  const target = pathname;
-  if (window.location.pathname === pathname) return;
+  const target = buildPressRoute(slug, mode, pageIndex);
+  if (`${window.location.pathname}${window.location.search}${window.location.hash}` === target) return;
   window.history.pushState({}, "", target);
 }
 
+function openPressRoute(
+  slug: string,
+  mode: OpenPressRuntimeMode,
+  pageIndex?: number,
+  options: { fullscreen?: boolean } = {},
+) {
+  if (typeof window === "undefined") return;
+  window.open(buildPressRoute(slug, mode, pageIndex, options), "_blank", "noopener,noreferrer");
+}
+
+function buildPressRoute(
+  slug: string,
+  mode: OpenPressRuntimeMode,
+  pageIndex?: number,
+  options: { fullscreen?: boolean } = {},
+) {
+  const normalizedSlug = normalizeSlug(slug);
+  const pathname = normalizedSlug ? `/${normalizedSlug}/${mode}` : "/workspace";
+  const search = mode === "present" && options.fullscreen ? "?fullscreen=1" : "";
+  const pageHash = typeof pageIndex === "number"
+    ? `#page-${String(pageIndex + 1).padStart(2, "0")}`
+    : "";
+  return `${pathname}${search}${pageHash}`;
+}
+
+function resolveRuntimeMode(document: ReaderDocument, requestedMode: OpenPressRuntimeMode): OpenPressRuntimeMode {
+  if (requestedMode === "present" && document.meta.type === "slides") return "present";
+  return "preview";
+}
+
 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

package/src/openpress/app/OpenPressRuntime.tsx

@@ -1,6 +1,6 @@
 import { useMemo, type CSSProperties } from "react";
-import { PrintDocument, PublicViewer } from "../reader";
-import { isPrintModeLocation, isWorkspaceModeLocation } from "../shared";
+import { PrintDocument, PublicViewer, SlidePresentationPage } from "../reader";
+import { isPresentationModeLocation, isPrintModeLocation, isWorkspaceModeLocation } from "../shared";
 import { HtmlWorkbench } from "../workbench";
 import type {
   DeploymentInfo,
@@ -9,10 +9,15 @@ import type {
   Theme,
 } from "../document-model";
 
+export type OpenPressRuntimeMode = "preview" | "present";
+
 interface OpenPressRuntimeProps {
   document: ReaderDocument;
+  runtimeMode?: OpenPressRuntimeMode;
   deploymentInfo?: DeploymentInfo;
   onDocumentRefresh?: () => void | Promise<void>;
+  onOpenPresentation?: (pageIndex: number) => void;
+  onExitPresentation?: (pageIndex: number) => 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.
@@ -21,12 +26,20 @@ interface OpenPressRuntimeProps {
 
 export function OpenPressRuntime({
   document,
+  runtimeMode,
   deploymentInfo = { online: false },
   onDocumentRefresh,
+  onOpenPresentation,
+  onExitPresentation,
   onBackToWorkspace,
 }: OpenPressRuntimeProps) {
   const style = themeToCssVariables(document.theme);
   const htmlPages = document.blocks.filter((block): block is HtmlPageBlock => block.kind === "htmlPage");
+  const activeRuntimeMode = useMemo<OpenPressRuntimeMode>(() => {
+    if (runtimeMode) return runtimeMode;
+    if (typeof window === "undefined") return "preview";
+    return isPresentationModeLocation(window.location) ? "present" : "preview";
+  }, [runtimeMode]);
   const workspaceMode = useMemo(() => {
     if (typeof window === "undefined") return false;
     return isWorkspaceModeLocation(window.location);
@@ -41,6 +54,17 @@ export function OpenPressRuntime({
       return <PrintDocument document={document} pages={htmlPages} style={style} />;
     }
 
+    if (activeRuntimeMode === "present" && document.meta.type === "slides") {
+      return (
+        <SlidePresentationPage
+          document={document}
+          pages={htmlPages}
+          style={style}
+          onExitPresentation={onExitPresentation}
+        />
+      );
+    }
+
     if (!workspaceMode) {
       return <PublicViewer document={document} pages={htmlPages} style={style} deploymentInfo={deploymentInfo} />;
     }
@@ -53,6 +77,7 @@ export function OpenPressRuntime({
         devMode={workspaceMode}
         deploymentInfo={deploymentInfo}
         onDocumentRefresh={onDocumentRefresh}
+        onOpenPresentation={onOpenPresentation}
         onBackToWorkspace={onBackToWorkspace}
       />
     );

package/src/openpress/core/Press.tsx

@@ -20,6 +20,7 @@ export interface AllocationHints {
 // (props override config) until v1.0 removes config support.
 export interface PressMetadata {
   title?: string;
+  type?: PressProps["type"];
   page?: PressProps["page"];
   slug?: string;
   theme?: string;