@open-press/core 1.1.1 → 1.1.3

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;

package/src/openpress/core/types.ts

@@ -1,5 +1,5 @@
 import type { HTMLAttributes, ReactNode } from "react";
-import type { EditableSourceRef, ObjectEntityKind } from "../document-model/documentTypes";
+import type { EditableSourceRef, ObjectEntityKind, PressType } from "../document-model/documentTypes";
 
 // ---------------------------------------------------------------------------
 // Frame / MdxArea / Press primitives
@@ -52,6 +52,9 @@ export interface PressProps {
   // Document title. Required in 1.0. Used for PDF metadata, HTML <title>,
   // OG tags, and the Workspace gallery / tab-bar label.
   title?: string;
+  // Creation mode. Pages are source-driven with MDX allocation; slides are
+  // explicit one-frame-per-page documents. Defaults to "pages".
+  type?: PressType;
   // Page geometry preset name or a custom geometry object. Optional;
   // workspace default applies if not set.
   page?: "a4" | "social-square" | "slide-16-9" | PageGeometry;
@@ -118,7 +121,7 @@ export type BaseCalloutProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
   children: ReactNode;
 };
 
-export type ObjectEntityElement = "span" | "div" | "section" | "article" | "figure" | "p";
+export type ObjectEntityElement = keyof HTMLElementTagNameMap;
 
 export type ObjectEntityProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
   as?: ObjectEntityElement;
@@ -135,9 +138,7 @@ export type ObjectEntityProps = Omit<HTMLAttributes<HTMLElement>, "children"> &
   children?: ReactNode;
 };
 
-export type TextProps = Omit<ObjectEntityProps, "kind"> & {
-  as?: "span" | "div" | "p";
-};
+export type TextProps = Omit<ObjectEntityProps, "kind">;
 
 // ---------------------------------------------------------------------------
 // Source descriptors and resolved sources
@@ -233,4 +234,3 @@ export interface ResolvedSource {
 // Per-frame, per-chain, ordered list of React nodes assigned to each
 // MdxArea by area index.
 export type FrameAllocation = Record<string, Record<string, ReactNode[]>>;
-

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

@@ -18,6 +18,8 @@ export interface ReaderDocument {
   blocks: HtmlPageBlock[];
 }
 
+export type PressType = "pages" | "slides";
+
 export interface DocumentSource {
   type: string;
   contentDir?: string;
@@ -57,6 +59,7 @@ export interface SourceBlock {
 
 export interface DocumentMeta {
   title: string;
+  type?: PressType;
   subtitle?: string;
   organization?: string;
   version?: string;

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

@@ -5,6 +5,7 @@
 // Single-Press workspaces emit one entry with slug = "" and the
 // legacy /openpress/document.json path. Multi-Press emits one entry
 // per slug; each `documentUrl` resolves to /openpress/<slug>/document.json.
+import type { PressType } from "./documentTypes";
 
 export interface WorkspaceManifest {
   version: 1;
@@ -20,6 +21,9 @@ export interface WorkspaceManifestPress {
   slug: string;
   // <Press title="..."> prop. Required in v1.0 contract.
   title: string;
+  // Creation mode declared by <Press type>. Defaults to "pages" for older
+  // documents. The reader uses this for mode-specific navigation affordances.
+  type: PressType;
   // Page geometry summary. Same shape as the reader's
   // ReaderDocument.theme — readers can show a thumb in the gallery
   // without loading the full document.json.

package/src/openpress/reader/PageThumbnailsPanel.tsx

@@ -69,6 +69,7 @@ function ThumbnailCard({
   aspectRatio: string;
 }) {
   const surfaceRef = useRef<HTMLDivElement>(null);
+  const cardRef = useRef<HTMLDivElement>(null);
   const [scale, setScale] = useState<number | null>(null);
 
   useEffect(() => {
@@ -86,6 +87,11 @@ function ThumbnailCard({
     return () => ro.disconnect();
   }, [pageWidthPx, pageHeightPx]);
 
+  useEffect(() => {
+    if (!active) return;
+    cardRef.current?.scrollIntoView({ block: "nearest" });
+  }, [active]);
+
   const className = `openpress-thumb-card${active ? " is-active" : ""}`;
   // Wrap the page HTML using the same class structure as the main
   // reader (`.openpress-html-page > .openpress-html-page__html`) so
@@ -117,6 +123,7 @@ function ThumbnailCard({
 
   return (
     <div
+      ref={cardRef}
       role="button"
       tabIndex={0}
       className={className}

package/src/openpress/reader/SlidePresentationPage.tsx

@@ -0,0 +1,221 @@
+import { useCallback, useEffect, useMemo, useRef, useState, type CSSProperties, type MouseEvent as ReactMouseEvent } from "react";
+import { Maximize2, X } from "lucide-react";
+import { createPageObjectEntityId } from "../document-model";
+import type { HtmlPageBlock, ReaderDocument } from "../document-model";
+import { pageIndexFromHash, replacePageRoute } from "./readerPageRoute";
+import { clampReaderPageIndex, formatReaderPageNumber, normalizeReaderPageCount } from "./readerStateModel";
+import { usePageViewportScale } from "./usePageViewportScale";
+
+type PresentationUiMode = "chrome" | "immersive";
+
+export function SlidePresentationPage({
+  document,
+  pages,
+  style,
+  onExitPresentation,
+}: {
+  document: ReaderDocument;
+  pages: HtmlPageBlock[];
+  style: CSSProperties;
+  onExitPresentation?: (pageIndex: number) => void;
+}) {
+  const sourceContainerRef = useRef<HTMLDivElement | null>(null);
+  const stageRef = useRef<HTMLElement | null>(null);
+  const currentPageIndexRef = useRef(0);
+  const normalizedPageCount = normalizeReaderPageCount(pages.length);
+  const [currentPageIndex, setCurrentPageIndex] = useState(() => {
+    if (typeof window === "undefined") return 0;
+    return pageIndexFromHash(window.location.hash, normalizedPageCount) ?? 0;
+  });
+  const [uiMode, setUiMode] = useState<PresentationUiMode>(() => (
+    shouldStartImmersive() ? "immersive" : "chrome"
+  ));
+  const pageViewport = usePageViewportScale({
+    stageRef,
+    pageContainerRef: sourceContainerRef,
+    pageCount: pages.length,
+    layoutMode: "single",
+  });
+  const currentPage = pages[clampReaderPageIndex(currentPageIndex, normalizedPageCount)];
+  const currentPageLabel = formatReaderPageNumber(currentPageIndex + 1);
+  const totalPageLabel = formatReaderPageNumber(normalizedPageCount);
+  const setPage = useCallback((pageIndex: number) => {
+    const target = clampReaderPageIndex(pageIndex, normalizedPageCount);
+    setCurrentPageIndex(target);
+    replacePageRoute(target);
+  }, [normalizedPageCount]);
+
+  currentPageIndexRef.current = currentPageIndex;
+
+  useEffect(() => {
+    setCurrentPageIndex((idx) => clampReaderPageIndex(idx, normalizedPageCount));
+  }, [normalizedPageCount]);
+
+  useEffect(() => {
+    const syncPageFromHash = () => {
+      const fromHash = pageIndexFromHash(window.location.hash, normalizedPageCount);
+      if (fromHash !== null) setCurrentPageIndex(fromHash);
+    };
+
+    syncPageFromHash();
+    window.addEventListener("hashchange", syncPageFromHash);
+    return () => window.removeEventListener("hashchange", syncPageFromHash);
+  }, [normalizedPageCount]);
+
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (isEditableTarget(event.target)) return;
+      if (event.key === "Escape") {
+        event.preventDefault();
+        const activeDocument = globalThis.document;
+        if (activeDocument.fullscreenElement && activeDocument.exitFullscreen) {
+          void activeDocument.exitFullscreen();
+          return;
+        }
+        onExitPresentation?.(currentPageIndexRef.current);
+        return;
+      }
+      if (event.key === " " || event.code === "Space") {
+        event.preventDefault();
+        setPage(currentPageIndexRef.current + 1);
+      } else if (event.key === "ArrowRight" || event.key === "PageDown") {
+        event.preventDefault();
+        setPage(currentPageIndexRef.current + 1);
+      } else if (event.key === "ArrowLeft" || event.key === "PageUp") {
+        event.preventDefault();
+        setPage(currentPageIndexRef.current - 1);
+      } else if (event.key === "Home") {
+        event.preventDefault();
+        setPage(0);
+      } else if (event.key === "End") {
+        event.preventDefault();
+        setPage(normalizedPageCount - 1);
+      }
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [normalizedPageCount, onExitPresentation, setPage]);
+
+  useEffect(() => {
+    const handleFullscreenChange = () => {
+      setUiMode(globalThis.document.fullscreenElement ? "immersive" : "chrome");
+    };
+
+    globalThis.document.addEventListener("fullscreenchange", handleFullscreenChange);
+    return () => globalThis.document.removeEventListener("fullscreenchange", handleFullscreenChange);
+  }, []);
+
+  useEffect(() => {
+    if (!shouldStartImmersive()) return;
+    enterImmersive({ keepOnFailure: true });
+  }, []);
+
+  const handleStageClick = (event: ReactMouseEvent<HTMLElement>) => {
+    if (event.defaultPrevented) return;
+    if (!(event.target instanceof Element)) return;
+    if (event.target.closest("a, button, input, textarea, select, [contenteditable]")) return;
+    setPage(currentPageIndex + 1);
+  };
+
+  const handleFullscreen = () => {
+    enterImmersive({ keepOnFailure: false });
+  };
+
+  const enterImmersive = ({ keepOnFailure }: { keepOnFailure: boolean }) => {
+    const stage = stageRef.current;
+    if (!stage?.requestFullscreen) {
+      setUiMode("immersive");
+      return;
+    }
+    setUiMode("immersive");
+    void stage.requestFullscreen().catch(() => {
+      if (!keepOnFailure) setUiMode("chrome");
+    });
+  };
+
+  const pageHtml = useMemo(() => currentPage?.html ?? "", [currentPage?.html]);
+
+  return (
+    <main
+      className="openpress-workbench openpress-reader-app openpress-slide-presenter"
+      style={style}
+      data-openpress-react-runtime="true"
+      data-openpress-view-mode="paged"
+      data-openpress-press-type="slides"
+      data-openpress-presentation-mode="on"
+      data-openpress-present-ui={uiMode}
+      data-openpress-slide-presenter
+      aria-label={`${document.meta.title} 放映模式`}
+    >
+      <section
+        className="openpress-slide-presenter__stage"
+        data-openpress-present-stage
+        aria-label="投影片放映區"
+        onClick={handleStageClick}
+      >
+        <main className="reader-stage" tabIndex={-1} ref={stageRef}>
+          <div
+            className="reader-pages openpress-public-page openpress-slide-presenter__pages"
+            ref={sourceContainerRef}
+            data-openpress-public-page="true"
+            data-openpress-page-layout="single"
+          >
+            {currentPage ? (
+              <div
+                key={currentPage.id}
+                id={`page-${String(currentPage.pageNumber).padStart(2, "0")}`}
+                className="openpress-html-page"
+                data-openpress-object-id={currentPage.frameKey ? createPageObjectEntityId(currentPage.frameKey) : undefined}
+                data-openpress-page-index={currentPage.pageNumber - 1}
+                data-openpress-active="true"
+              >
+                <div className="openpress-html-page__html" dangerouslySetInnerHTML={{ __html: pageHtml }} />
+              </div>
+            ) : null}
+          </div>
+        </main>
+      </section>
+
+      <div className="openpress-slide-presenter__hud" aria-label="放映控制">
+        <span
+          className="openpress-slide-presenter__progress"
+          data-openpress-present-progress
+          data-openpress-present-scale={pageViewport.scaleMode}
+        >
+          {currentPageLabel} / {totalPageLabel}
+        </span>
+        <button
+          type="button"
+          className="openpress-slide-presenter__button"
+          data-openpress-present-fullscreen
+          onClick={handleFullscreen}
+          aria-label="進入全螢幕"
+          title="進入全螢幕"
+        >
+          <Maximize2 aria-hidden="true" />
+        </button>
+        <button
+          type="button"
+          className="openpress-slide-presenter__button"
+          data-openpress-present-exit
+          onClick={() => onExitPresentation?.(currentPageIndex)}
+          aria-label="回到工作台"
+          title="回到工作台"
+        >
+          <X aria-hidden="true" />
+        </button>
+      </div>
+    </main>
+  );
+}
+
+function isEditableTarget(target: EventTarget | null) {
+  if (!(target instanceof HTMLElement)) return false;
+  return Boolean(target.closest("input, textarea, select, button, [contenteditable]"));
+}
+
+function shouldStartImmersive() {
+  if (typeof window === "undefined") return false;
+  return new URLSearchParams(window.location.search).get("fullscreen") === "1";
+}

package/src/openpress/reader/index.ts

@@ -1,6 +1,7 @@
 export * from "./PageThumbnailsPanel";
 export * from "./PublicReaderPage";
 export * from "./ReaderNavigationPanel";
+export * from "./SlidePresentationPage";
 export * from "./pageViewportScaleModel";
 export * from "./readerPageRegistry";
 export * from "./readerPageRoute";

package/src/openpress/reader/usePanelState.ts

@@ -35,9 +35,12 @@ export function usePanelState({
     if (typeof window === "undefined") return undefined;
 
     const handleResize = () => {
-      setLeftPanelOpen((open) => (open && !shouldOpenLeftPanel() ? false : open));
-      setRightPanelOpen((open) => (open && !shouldOpenRightPanel() ? false : open));
-      onAfterResize?.();
+      const closeLeftPanel = leftPanelOpen && !shouldOpenLeftPanel();
+      const closeRightPanel = rightPanelOpen && !shouldOpenRightPanel();
+
+      if (closeLeftPanel) setLeftPanelOpen(false);
+      if (closeRightPanel) setRightPanelOpen(false);
+      if (closeLeftPanel || closeRightPanel) onAfterResize?.();
     };
 
     handleResize();
@@ -47,7 +50,7 @@ export function usePanelState({
       window.removeEventListener("resize", handleResize);
       window.visualViewport?.removeEventListener("resize", handleResize);
     };
-  }, [shouldOpenLeftPanel, shouldOpenRightPanel, onAfterResize]);
+  }, [leftPanelOpen, rightPanelOpen, shouldOpenLeftPanel, shouldOpenRightPanel, onAfterResize]);
 
   const toggleLeftPanel = useCallback(() => setLeftPanelOpen((open) => !open), []);
   const toggleRightPanel = useCallback(() => setRightPanelOpen((open) => !open), []);

package/src/openpress/shared/runtimeMode.ts

@@ -2,10 +2,25 @@ export function isLocalWorkspaceHost(hostname: string) {
   return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
 }
 
-export function isWorkspaceModeLocation(location: Pick<Location, "hostname" | "search">) {
-  return isLocalWorkspaceHost(location.hostname) && new URLSearchParams(location.search).has("dev");
+export function isWorkspaceModeLocation(location: Pick<Location, "hostname" | "pathname">) {
+  if (!isLocalWorkspaceHost(location.hostname)) return false;
+  const pathname = normalizePathname(location.pathname);
+  if (pathname === "workspace") return true;
+  const segments = pathname.split("/").filter(Boolean);
+  return segments.length === 2 && segments[1] === "preview";
+}
+
+export function isPresentationModeLocation(location: Pick<Location, "hostname" | "pathname">) {
+  if (!isLocalWorkspaceHost(location.hostname)) return false;
+  const pathname = normalizePathname(location.pathname);
+  const segments = pathname.split("/").filter(Boolean);
+  return segments.length === 2 && segments[1] === "present";
 }
 
 export function isPrintModeLocation(location: Pick<Location, "search">) {
   return new URLSearchParams(location.search).has("print");
 }
+
+function normalizePathname(pathname: string) {
+  return pathname.replace(/^\/+|\/+$/g, "");
+}

package/src/openpress/workbench/Workbench.tsx

@@ -4,7 +4,7 @@ import {
   useState,
   type CSSProperties,
 } from "react";
-import { ExternalLink, Home, MousePointer2, Ruler } from "lucide-react";
+import { ExternalLink, Home, MousePointer2, Play, Ruler } from "lucide-react";
 import {
   getProjectIdentity,
   resolveAnchorPageIndex,
@@ -55,6 +55,7 @@ export function HtmlWorkbench({
   deploymentInfo,
   onDocumentRefresh,
   onBackToWorkspace,
+  onOpenPresentation,
   extraControlPanels,
 }: {
   document: ReaderDocument;
@@ -64,6 +65,7 @@ export function HtmlWorkbench({
   deploymentInfo: DeploymentInfo;
   onDocumentRefresh?: () => void | Promise<void>;
   onBackToWorkspace?: () => void;
+  onOpenPresentation?: (pageIndex: number) => void;
   // Append extra panels into the right-side control panel. Built-in panels
   // (pending comments + project entry) render first; extra panels render
   // after them in the supplied order.
@@ -99,6 +101,8 @@ export function HtmlWorkbench({
   const [sourceEditorTarget, setSourceEditorTarget] = useState<InlineDocumentSourceTarget | null>(null);
 
   const projectIdentity = getProjectIdentity(document.meta);
+  const pressType = normalizePressType(document.meta.type);
+  const isSlidePress = pressType === "slides";
   const pageGeometry = formatPageGeometrySpec(document.theme);
   const inspectorSelectionLabel = formatInspectorSelection(
     inspector.selectedBlock,
@@ -284,6 +288,22 @@ export function HtmlWorkbench({
         />
       </div>
       <div className="openpress-workbench-toolbar__group openpress-workbench-toolbar__group--page" aria-label="頁面規格">
+        {isSlidePress && onOpenPresentation ? (
+          <button
+            type="button"
+            className="openpress-workbench-toolbar-action"
+            data-openpress-slide-present
+            data-openpress-toolbar-expanded="false"
+            data-openpress-toolbar-active="false"
+            aria-pressed="false"
+            title="進入放映模式"
+            aria-label="進入放映模式"
+            onClick={() => onOpenPresentation?.(reader.currentPageIndex)}
+          >
+            <Play aria-hidden="true" />
+            <span className="openpress-workbench-toolbar-action__label">放映</span>
+          </button>
+        ) : null}
         <button
           type="button"
           className="openpress-workbench-page-geometry"
@@ -386,8 +406,10 @@ export function HtmlWorkbench({
     pageViewport.scaleMode,
     pageViewport.setScaleMode,
     selectWorkspacePage,
+    isSlidePress,
     sourceBlocksByPath,
     onBackToWorkspace,
+    onOpenPresentation,
     reader.currentPageIndex,
     reader.currentPageLabel,
     projectIdentity.name,
@@ -398,6 +420,8 @@ export function HtmlWorkbench({
       style={style}
       devMode={devMode}
       viewMode={viewMode}
+      pressType={pressType}
+      presentationMode={false}
       inspectorMode={inspector.inspectorMode}
       editMode={inlineEditEnabled}
       leftPanelOpen={reader.leftPanelOpen}
@@ -418,7 +442,7 @@ export function HtmlWorkbench({
           {projectIdentity.label ? <span>{projectIdentity.label}</span> : null}
         </section>
 
-        {bookmarks.length > 0 ? (
+        {!isSlidePress && bookmarks.length > 0 ? (
           <section
             id="openpress-bookmarks"
             className="openpress-panel-section openpress-panel-section--bookmarks"
@@ -504,3 +528,7 @@ function formatInlineEditStatus(status: InlineDocumentEditStatus) {
   if (status.state === "failed") return "儲存失敗";
   return "";
 }
+
+function normalizePressType(value: ReaderDocument["meta"]["type"]) {
+  return value === "slides" ? "slides" : "pages";
+}