@open-press/core 1.1.1 → 1.1.3

package/engine/commands/dev.mjs

@@ -17,7 +17,7 @@ export async function run({ root, options }) {
   }
   const host = options.host ?? "127.0.0.1";
   const port = options.port ?? "5173";
-  const url = `http://${host}:${port}/?dev=1`;
+  const url = `http://${host}:${port}/workspace`;
   if (options.dryRun) {
     console.log(`OpenPress dev URL: ${url}`);
     if (!options.noBuild) {

package/engine/react/document-entry.mjs

@@ -14,6 +14,7 @@ import ts from "typescript";
 import { createServer as createViteServer } from "vite";
 import { loadConfig } from "../runtime/config.mjs";
 import { inspectPressTree } from "./press-tree-inspection.mjs";
+import { textSourceTransformPlugin } from "./text-source-transform.mjs";
 
 const ENGINE_REACT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const FRAMEWORK_ROOT = path.resolve(ENGINE_REACT_DIR, "..", "..");
@@ -95,7 +96,14 @@ export async function createReactSsrServer(workspaceRoot = ".") {
     cacheDir: path.join(resolvedWorkspaceRoot, ".openpress", "vite-ssr"),
     appType: "custom",
     logLevel: "silent",
-    plugins: [reactRuntimePlugin(), react()],
+    plugins: [
+      textSourceTransformPlugin({
+        workspaceRoot: resolvedWorkspaceRoot,
+        documentRoot: path.join(resolvedWorkspaceRoot, "press"),
+      }),
+      reactRuntimePlugin(),
+      react(),
+    ],
     resolve: {
       alias: [
         // ORDER MATTERS: subpath aliases must precede the base alias so that

package/engine/react/document-export.mjs

@@ -24,6 +24,7 @@ import { resolveAllSources } from "./sources/mdx-resolver.mjs";
 import { discoverSectionStyles } from "./style-discovery.mjs";
 
 const MAX_ITERATIONS = 20;
+const PRESS_TYPES = new Set(["pages", "slides"]);
 
 export async function exportReactDocument(root = ".", { syncAssets = true } = {}) {
   const workspaceRoot = path.resolve(root);
@@ -115,6 +116,7 @@ export async function exportReactDocument(root = ".", { syncAssets = true } = {}
       presses: pressResults.map((r) => ({
         slug: r.slug,
         title: r.readerDocument.meta.title,
+        type: r.pressType,
         page: r.readerDocument.theme ?? null,
         pageCount: r.pageCount,
         documentUrl: r.documentUrl,
@@ -158,6 +160,7 @@ async function exportSinglePress({
   const slug = typeof press.metadata?.slug === "string" && press.metadata.slug.trim()
     ? press.metadata.slug.trim()
     : "";
+  const pressType = normalizePressType(press.metadata?.type);
 
   // Effective config for this press: workspace config with per-press
   // metadata overlaid. Press JSX page prop wins over the workspace page.
@@ -308,6 +311,7 @@ async function exportSinglePress({
   const readerDocument = {
     meta: {
       title: trimmedString(effectiveConfig.title) ?? "Untitled Document",
+      type: pressType,
       subtitle: trimmedString(effectiveConfig.subtitle) ?? "",
       organization: trimmedString(effectiveConfig.organization) ?? "",
       workspaceLabel: trimmedString(effectiveConfig.workspaceLabel) ?? "",
@@ -349,6 +353,7 @@ async function exportSinglePress({
 
   return {
     slug,
+    pressType,
     documentPath,
     documentUrl: slug ? `/openpress/${slug}/document.json` : "/openpress/document.json",
     readerDocument,
@@ -356,6 +361,14 @@ async function exportSinglePress({
   };
 }
 
+function normalizePressType(value) {
+  if (value === undefined || value === null || value === "") return "pages";
+  if (PRESS_TYPES.has(value)) return value;
+  throw new Error(
+    `Unsupported Press type "${value}". Supported types: ${[...PRESS_TYPES].join(", ")}.`,
+  );
+}
+
 // Apply per-Press JSX prop overrides onto the workspace-level config.
 // Returns a new config object — the original is untouched so other
 // presses in the same workspace get a clean base.
@@ -509,4 +522,3 @@ function collectSectionRoots(presses, documentRoot) {
   }
   return [...roots];
 }
-

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

@@ -31,6 +31,7 @@ import React from "react";
  *     props: Record<string, unknown>,           // Press JSX props (no children)
  *     metadata: {
  *       title?: string,
+ *       type?: "pages" | "slides",
  *       page?: unknown,
  *       slug?: string,
  *       theme?: string,
@@ -144,6 +145,7 @@ function collectPressElements(root, PRESS_MARKER) {
 function pickPressMetadata(pressProps) {
   const out = {};
   if (typeof pressProps.title === "string") out.title = pressProps.title;
+  if (typeof pressProps.type === "string") out.type = pressProps.type;
   if (pressProps.page !== undefined) out.page = pressProps.page;
   if (typeof pressProps.slug === "string") out.slug = pressProps.slug;
   if (typeof pressProps.theme === "string") out.theme = pressProps.theme;

package/engine/react/text-source-transform.mjs

@@ -0,0 +1,175 @@
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+
+const TEXT_SOURCE_FILE_RE = /\.[jt]sx$/;
+
+export function textSourceTransformPlugin({ workspaceRoot, documentRoot }) {
+  const resolvedWorkspaceRoot = realpathIfExists(path.resolve(workspaceRoot));
+  const resolvedDocumentRoot = realpathIfExists(path.resolve(documentRoot));
+
+  return {
+    name: "openpress-text-source-transform",
+    enforce: "pre",
+    transform(code, id) {
+      const filePath = cleanViteId(id);
+      if (!TEXT_SOURCE_FILE_RE.test(filePath)) return null;
+      if (!isInsidePath(filePath, resolvedDocumentRoot)) return null;
+
+      const relativePath = path.relative(resolvedWorkspaceRoot, filePath).replaceAll(path.sep, "/");
+      if (!relativePath || relativePath.startsWith("..")) return null;
+
+      const nextCode = addLiteralTextSourceProps(code, {
+        filePath,
+        sourcePath: relativePath,
+      });
+      if (nextCode === code) return null;
+      return { code: nextCode, map: null };
+    },
+  };
+}
+
+export function addLiteralTextSourceProps(code, { filePath = "index.tsx", sourcePath = "press/index.tsx" } = {}) {
+  const sourceFile = ts.createSourceFile(filePath, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const textRefs = collectOpenPressTextRefs(sourceFile);
+  if (textRefs.identifiers.size === 0 && textRefs.namespaces.size === 0) return code;
+
+  const insertions = [];
+
+  const visit = (node) => {
+    if (ts.isJsxElement(node) && isTextElementName(node.openingElement.tagName, textRefs)) {
+      const opening = node.openingElement;
+      if (!hasJsxAttribute(opening, "source")) {
+        const literal = literalTextChildRange(node, sourceFile, code);
+        if (literal) {
+          insertions.push({
+            offset: opening.end - 1,
+            text: ` source={${sourcePropExpression({
+              sourcePath,
+              objectId: stringLiteralAttribute(opening, "objectId"),
+              range: literal.range,
+            })}}`,
+          });
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+
+  if (insertions.length === 0) return code;
+  let out = code;
+  for (const insertion of insertions.sort((a, b) => b.offset - a.offset)) {
+    out = `${out.slice(0, insertion.offset)}${insertion.text}${out.slice(insertion.offset)}`;
+  }
+  return out;
+}
+
+function collectOpenPressTextRefs(sourceFile) {
+  const identifiers = new Set();
+  const namespaces = new Set();
+
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+    if (!statement.importClause) continue;
+    if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
+    if (statement.moduleSpecifier.text !== "@open-press/core") continue;
+
+    const bindings = statement.importClause.namedBindings;
+    if (!bindings) continue;
+    if (ts.isNamespaceImport(bindings)) {
+      namespaces.add(bindings.name.text);
+      continue;
+    }
+    if (!ts.isNamedImports(bindings)) continue;
+
+    for (const element of bindings.elements) {
+      const importedName = element.propertyName?.text ?? element.name.text;
+      if (importedName === "Text") identifiers.add(element.name.text);
+    }
+  }
+
+  return { identifiers, namespaces };
+}
+
+function literalTextChildRange(node, sourceFile, code) {
+  const textChildren = [];
+  for (const child of node.children) {
+    if (ts.isJsxText(child)) {
+      const raw = code.slice(child.pos, child.end);
+      if (raw.trim()) textChildren.push({ child, raw });
+      continue;
+    }
+    if (ts.isJsxExpression(child) && !child.expression && code.slice(child.pos, child.end).trim() === "{}") continue;
+    if (code.slice(child.pos, child.end).trim()) return null;
+  }
+  if (textChildren.length !== 1) return null;
+
+  const { child, raw } = textChildren[0];
+  const text = raw.trim();
+  const startInRaw = raw.indexOf(text);
+  const startOffset = child.pos + startInRaw;
+  const endOffset = startOffset + text.length;
+  const start = sourceFile.getLineAndCharacterOfPosition(startOffset);
+  const end = sourceFile.getLineAndCharacterOfPosition(endOffset);
+  return {
+    text,
+    range: {
+      line: start.line + 1,
+      column: start.character + 1,
+      endLine: end.line + 1,
+      endColumn: end.character + 1,
+    },
+  };
+}
+
+function sourcePropExpression({ sourcePath, objectId, range }) {
+  const props = [
+    `path: ${JSON.stringify(sourcePath)}`,
+    `kind: "tsx-text"`,
+    `source: { line: ${range.line}, column: ${range.column}, endLine: ${range.endLine}, endColumn: ${range.endColumn} }`,
+  ];
+  if (objectId) props.splice(2, 0, `objectId: ${JSON.stringify(objectId)}`);
+  return `{ ${props.join(", ")} }`;
+}
+
+function isTextElementName(name, refs) {
+  if (ts.isIdentifier(name)) return refs.identifiers.has(name.text);
+  if (!ts.isJsxMemberExpression(name)) return false;
+  if (name.name.text !== "Text") return false;
+  return ts.isIdentifier(name.expression) && refs.namespaces.has(name.expression.text);
+}
+
+function hasJsxAttribute(opening, name) {
+  return opening.attributes.properties.some((prop) =>
+    ts.isJsxAttribute(prop) && prop.name.text === name
+  );
+}
+
+function stringLiteralAttribute(opening, name) {
+  const attr = opening.attributes.properties.find((prop) =>
+    ts.isJsxAttribute(prop) && prop.name.text === name
+  );
+  if (!attr || !ts.isJsxAttribute(attr) || !attr.initializer) return undefined;
+  if (ts.isStringLiteral(attr.initializer)) return attr.initializer.text;
+  return undefined;
+}
+
+function cleanViteId(id) {
+  const withoutQuery = String(id ?? "").split("?")[0];
+  const fsPath = withoutQuery.startsWith("/@fs/") ? withoutQuery.slice("/@fs".length) : withoutQuery;
+  return realpathIfExists(path.resolve(fsPath));
+}
+
+function realpathIfExists(filePath) {
+  try {
+    return fs.realpathSync.native(filePath);
+  } catch {
+    return filePath;
+  }
+}
+
+function isInsidePath(filePath, parentPath) {
+  const relative = path.relative(parentPath, filePath);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}

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.1",
+  "version": "1.1.3",
   "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,36 +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 normalizeSlug(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 pushSlug(slug: string) {
+function routeFromWorkspacePathname(pathname: string): WorkspaceRoute {
+  const normalized = normalizeSlug(pathname);
+  if (!normalized || normalized === "workspace") return { slug: "", mode: "preview" };
+
+  const segments = normalized.split("/").filter(Boolean);
+  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 { slug: normalized, mode: "preview" };
+}
+
+function pushPressRoute(slug: string, mode: OpenPressRuntimeMode, pageIndex?: number) {
   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;
+  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