@open-press/cli 0.7.1 → 1.0.0

package/template/core/src/openpress/reader/PageThumbnailsPanel.tsx

@@ -0,0 +1,168 @@
+import { useEffect, useRef, useState, type CSSProperties } from "react";
+import type { HtmlPageBlock, Theme } from "../document-model";
+import { Panel } from "../shared";
+
+// Used by canvas-style Press (slides, social posts) that don't have an
+// MDX-derived TOC. Renders each page as a clickable miniature so the user
+// can navigate without bookmarks. The miniature embeds the same HTML
+// that the main reader renders, scaled to fit the panel width.
+
+const FALLBACK_PAGE_WIDTH_PX = 794; // A4 portrait at 96dpi — matches reader default.
+
+export function PageThumbnails({
+  pages,
+  currentPageIndex,
+  onSelectPage,
+  theme,
+}: {
+  pages: HtmlPageBlock[];
+  currentPageIndex: number;
+  onSelectPage: (pageIndex: number, options?: { behavior?: ScrollBehavior }) => void;
+  theme?: Theme;
+}) {
+  const pageWidthPx = parsePxLength(theme?.pageWidth) ?? FALLBACK_PAGE_WIDTH_PX;
+  const pageHeightPx = parsePxLength(theme?.pageHeight) ?? pageWidthPx;
+  // Compute aspect from the parsed dimensions so it always matches the
+  // page render. theme.pageAspectRatio may be missing on per-Press
+  // documents in multi-Press workspaces, which is why we don't read it
+  // here.
+  const aspectRatio = `${pageWidthPx} / ${pageHeightPx}`;
+
+  if (pages.length === 0) {
+    return <Panel.Empty className="openpress-asset-empty" role="status">尚無頁面</Panel.Empty>;
+  }
+
+  return (
+    <ul className="openpress-thumb-list" aria-label="頁面縮圖">
+      {pages.map((page, index) => (
+        <li key={page.id}>
+          <ThumbnailCard
+            page={page}
+            index={index}
+            active={index === currentPageIndex}
+            onClick={() => onSelectPage(index, { behavior: "smooth" })}
+            pageWidthPx={pageWidthPx}
+            pageHeightPx={pageHeightPx}
+            aspectRatio={aspectRatio}
+          />
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+function ThumbnailCard({
+  page,
+  index,
+  active,
+  onClick,
+  pageWidthPx,
+  pageHeightPx,
+  aspectRatio,
+}: {
+  page: HtmlPageBlock;
+  index: number;
+  active: boolean;
+  onClick: () => void;
+  pageWidthPx: number;
+  pageHeightPx: number;
+  aspectRatio: string;
+}) {
+  const surfaceRef = useRef<HTMLDivElement>(null);
+  const [scale, setScale] = useState<number | null>(null);
+
+  useEffect(() => {
+    const el = surfaceRef.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 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
+  // section-scoped CSS that targets those classes still applies in
+  // the miniature.
+  const pageClass = page.className
+    ? `openpress-html-page ${page.className}`
+    : "openpress-html-page";
+  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",
+  };
+  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 pageTitle = page.title || `Page ${index + 1}`;
+
+  return (
+    <div
+      role="button"
+      tabIndex={0}
+      className={className}
+      data-openpress-thumb-index={index}
+      aria-label={`前往第 ${index + 1} 頁：${pageTitle}`}
+      aria-current={active ? "page" : undefined}
+      onClick={onClick}
+      onKeyDown={(event) => {
+        if (event.key === "Enter" || event.key === " ") {
+          event.preventDefault();
+          onClick();
+        }
+      }}
+    >
+      <div className="openpress-thumb-card__surface" ref={surfaceRef} style={{ aspectRatio }}>
+        <div className="openpress-thumb-card__frame" style={frameStyle}>
+          <div className={pageClass} style={pageStyle} data-openpress-thumb-page="true">
+            <div
+              className="openpress-html-page__html"
+              // Page HTML comes from the trusted build pipeline (same source
+              // as the main reader).
+              dangerouslySetInnerHTML={{ __html: page.html }}
+            />
+          </div>
+        </div>
+      </div>
+      <div className="openpress-thumb-card__meta">
+        <span className="openpress-thumb-card__index">{String(index + 1).padStart(2, "0")}</span>
+        <span className="openpress-thumb-card__title">{pageTitle}</span>
+      </div>
+    </div>
+  );
+}
+
+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/template/core/src/openpress/{publicPage.tsx → reader/PublicReaderPage.tsx}

@@ -1,30 +1,33 @@
 import {
-  useLayoutEffect,
   useMemo,
   useRef,
-  useState,
   type CSSProperties,
   type MouseEvent as ReactMouseEvent,
   type RefCallback,
   type RefObject,
 } from "react";
 import { BookOpen, ExternalLink, X } from "lucide-react";
-import { createAnchorPageMap, resolveAnchorPageIndex } from "./anchorMap";
-import { collectBookmarkIndex } from "./indexes";
-import type { InspectorState } from "./inspector";
-import { getProjectIdentity } from "./projectIdentity";
-import { useReaderRuntime } from "./readerRuntime";
-import { scheduleBrowserFrame } from "./frameScheduler";
-import type { DeploymentInfo, ReaderDocument, HtmlPageBlock } from "./types";
-import { Bookmarks, CurrentPagePanel } from "./workbenchPanels";
-import type { DisplayPage } from "./workbenchTypes";
+import {
+  collectBookmarkIndex,
+  createAnchorPageMap,
+  createPageObjectEntityId,
+  getProjectIdentity,
+  resolveAnchorPageIndex,
+  type DeploymentInfo,
+  type HtmlPageBlock,
+  type ReaderDocument,
+} from "../document-model";
+import type { InspectorState } from "../workbench/inspector";
+import { useReaderRuntime } from "./useReaderRuntime";
+import { Bookmarks, CurrentPagePanel } from "./ReaderNavigationPanel";
+import type { DisplayPage } from "./readerTypes";
+import { usePageViewportScale } from "./usePageViewportScale";
+import type { PageLayoutMode } from "./pageViewportScaleModel";
 
 export const PUBLIC_DRAWER_BREAKPOINT = 1185;
-export type ViewMode = "reading" | "paged";
+export type ViewMode = "paged";
 export type PageInspector = Pick<InspectorState, "enabled" | "handleClick">;
 
-const PAGED_VIEW_MIN_WIDTH = 360;
-
 export function PublicViewer({
   document,
   pages,
@@ -46,6 +49,12 @@ export function PublicViewer({
     pageCount: displayPages.length,
     rightPanelBreakpoint: PUBLIC_DRAWER_BREAKPOINT,
   });
+  usePageViewportScale({
+    stageRef: reader.stageRef,
+    pageContainerRef: sourceContainerRef,
+    pageCount: displayPages.length,
+    layoutMode: "single",
+  });
   const currentPage = displayPages[reader.currentPageIndex];
   const staticPdfHref = deploymentInfo.pdf;
   const projectIdentity = getProjectIdentity(document.meta);
@@ -135,7 +144,7 @@ export function PublicViewer({
             totalPageLabel={reader.totalPageLabel}
             progressPercent={reader.progressPercent}
             title={currentPage?.title || document.meta.title}
-            pageLabelPrefix={viewMode === "reading" ? "節" : "頁"}
+            pageLabelPrefix="頁"
             showHeading={false}
             showTitle={false}
           />
@@ -145,37 +154,8 @@ export function PublicViewer({
   );
 }
 
-export function useViewMode() {
-  const [pagedAllowed, setPagedAllowed] = useState(() => {
-    if (typeof window === "undefined") return true;
-    return viewportAllowsPagedMode();
-  });
-
-  useLayoutEffect(() => {
-    if (typeof window === "undefined") return undefined;
-
-    let cancelFrame: (() => void) | null = null;
-    const sync = () => {
-      cancelFrame?.();
-      cancelFrame = scheduleBrowserFrame(() => {
-        cancelFrame = null;
-        setPagedAllowed(viewportAllowsPagedMode());
-      });
-    };
-
-    sync();
-    window.addEventListener("resize", sync);
-    window.visualViewport?.addEventListener("resize", sync);
-    return () => {
-      window.removeEventListener("resize", sync);
-      window.visualViewport?.removeEventListener("resize", sync);
-      cancelFrame?.();
-    };
-  }, []);
-
-  const viewMode: ViewMode = pagedAllowed ? "paged" : "reading";
-
-  return { viewMode };
+export function useViewMode(): { viewMode: ViewMode } {
+  return { viewMode: "paged" };
 }
 
 export function PrintDocument({
@@ -210,11 +190,6 @@ export function PrintDocument({
   );
 }
 
-function viewportAllowsPagedMode() {
-  if (typeof window === "undefined") return true;
-  return window.innerWidth >= PAGED_VIEW_MIN_WIDTH;
-}
-
 export function PublicPage({
   pages,
   currentPageIndex,
@@ -224,6 +199,7 @@ export function PublicPage({
   exposeSourceData = false,
   inspector,
   onInternalAnchorNavigate,
+  pageLayoutMode = "single",
 }: {
   pages: DisplayPage[];
   currentPageIndex: number;
@@ -233,6 +209,7 @@ export function PublicPage({
   exposeSourceData?: boolean;
   inspector?: PageInspector;
   onInternalAnchorNavigate?: (anchorId: string, pageIndex?: number) => boolean;
+  pageLayoutMode?: PageLayoutMode;
 }) {
   const handlePageClick = (event: ReactMouseEvent<HTMLDivElement>) => {
     if (inspector?.enabled && inspector.handleClick(event)) return;
@@ -257,6 +234,7 @@ export function PublicPage({
       className="reader-pages openpress-public-page"
       ref={sourceContainerRef}
       data-openpress-public-page="true"
+      data-openpress-page-layout={pageLayoutMode}
       onClick={handlePageClick}
     >
       {pages.map((page) => (
@@ -265,7 +243,9 @@ export function PublicPage({
           ref={registerPage(page.pageNumber - 1)}
           id={`page-${String(page.pageNumber).padStart(2, "0")}`}
           className="openpress-html-page"
+          data-openpress-object-id={page.frameKey ? createPageObjectEntityId(page.frameKey) : undefined}
           data-openpress-page-index={page.pageNumber - 1}
+          data-openpress-page-spread-side={pageLayoutMode === "spread" ? ((page.pageNumber - 1) % 2 === 0 ? "left" : "right") : undefined}
           data-openpress-active={currentPageIndex === page.pageNumber - 1 ? "true" : "false"}
           data-source-path={exposeSourceData ? page.source?.path : undefined}
           data-source-file={exposeSourceData ? page.source?.file : undefined}

package/template/core/src/openpress/{workbenchPanels.tsx → reader/ReaderNavigationPanel.tsx}

@@ -1,5 +1,6 @@
 import { type CSSProperties, type MouseEvent as ReactMouseEvent } from "react";
-import type { BookmarkItem } from "./indexes";
+import type { BookmarkItem } from "../document-model";
+import { Panel } from "../shared";
 
 type BookmarkSelectOptions = {
   behavior?: ScrollBehavior;
@@ -20,7 +21,7 @@ export function Bookmarks({
   };
 
   if (items.length === 0) {
-    return <p className="openpress-asset-empty">尚無書籤</p>;
+    return <Panel.Empty className="openpress-asset-empty" role="status">尚無書籤</Panel.Empty>;
   }
 
   return (
@@ -103,8 +104,8 @@ export function CurrentPagePanel({
   showTitle?: boolean;
 }) {
   return (
-    <section className="openpress-panel-section openpress-panel-section--current" aria-label="目前頁面">
-      {showHeading ? <div className="openpress-panel-heading">目前頁面</div> : null}
+    <Panel.Section className="openpress-panel-section--current" aria-label="目前頁面">
+      {showHeading ? <Panel.SectionTitle className="openpress-panel-heading">目前頁面</Panel.SectionTitle> : null}
       <div className="openpress-current-page-card">
         <div className="openpress-current-page-card__number" aria-label="目前頁數">
           {pageLabelPrefix ? <span className="openpress-current-page-card__prefix">{pageLabelPrefix}</span> : null}
@@ -117,6 +118,6 @@ export function CurrentPagePanel({
           <span style={{ "--progress": `${progressPercent}%` } as CSSProperties} />
         </div>
       </div>
-    </section>
+    </Panel.Section>
   );
 }

package/template/core/src/openpress/reader/index.ts

@@ -0,0 +1,11 @@
+export * from "./PageThumbnailsPanel";
+export * from "./PublicReaderPage";
+export * from "./ReaderNavigationPanel";
+export * from "./pageViewportScaleModel";
+export * from "./readerPageRegistry";
+export * from "./readerPageRoute";
+export * from "./readerScroll";
+export * from "./readerStateModel";
+export * from "./readerTypes";
+export * from "./usePageViewportScale";
+export * from "./useReaderRuntime";

package/template/core/src/openpress/reader/pageViewportScaleModel.ts

@@ -0,0 +1,73 @@
+export type PageLayoutMode = "single" | "spread";
+
+export type PageViewportScaleMode =
+  | "fit-width"
+  | "fit-page"
+  | "scale-25"
+  | "scale-50"
+  | "scale-75"
+  | "scale-100"
+  | "scale-125"
+  | "scale-150"
+  | "scale-200";
+
+export const PAGE_VIEWPORT_SCALE_OPTIONS: Array<{
+  value: PageViewportScaleMode;
+  label: string;
+}> = [
+  { value: "scale-25", label: "25%" },
+  { value: "scale-50", label: "50%" },
+  { value: "scale-75", label: "75%" },
+  { value: "scale-100", label: "100%" },
+  { value: "scale-125", label: "125%" },
+  { value: "scale-150", label: "150%" },
+  { value: "scale-200", label: "200%" },
+  { value: "fit-width", label: "符合頁面寬度" },
+  { value: "fit-page", label: "符合全開頁面" },
+];
+
+const MIN_PAGE_VIEWPORT_SCALE = 0.12;
+const MAX_FIT_PAGE_VIEWPORT_SCALE = 1;
+const MAX_FIXED_PAGE_VIEWPORT_SCALE = 2;
+
+export function resolvePageViewportScale({
+  mode,
+  fitWidthScale,
+  fitPageScale,
+}: {
+  mode: PageViewportScaleMode;
+  fitWidthScale: number;
+  fitPageScale: number;
+}) {
+  if (mode === "fit-width") return clampPageViewportScale(fitWidthScale, MAX_FIT_PAGE_VIEWPORT_SCALE);
+  if (mode === "fit-page") return clampPageViewportScale(fitPageScale, MAX_FIT_PAGE_VIEWPORT_SCALE);
+  return scaleModeToFixedValue(mode);
+}
+
+export function formatPageViewportScaleLabel(mode: PageViewportScaleMode, scale: number) {
+  void mode;
+  return formatPageViewportScalePercent(scale);
+}
+
+export function formatPageViewportScalePercent(scale: number) {
+  return `${Math.round(clampPageViewportScale(scale, MAX_FIXED_PAGE_VIEWPORT_SCALE) * 100)}%`;
+}
+
+export function formatPageViewportScaleValue(scale: number) {
+  return clampPageViewportScale(scale, MAX_FIXED_PAGE_VIEWPORT_SCALE)
+    .toFixed(4)
+    .replace(/0+$/, "")
+    .replace(/\.$/, "");
+}
+
+function scaleModeToFixedValue(mode: PageViewportScaleMode) {
+  const match = /^scale-(\d+)$/.exec(mode);
+  if (!match) return 1;
+  return clampPageViewportScale(Number.parseInt(match[1] ?? "100", 10) / 100, MAX_FIXED_PAGE_VIEWPORT_SCALE);
+}
+
+function clampPageViewportScale(value: number, maxScale: number) {
+  if (!Number.isFinite(value)) return 1;
+  const safeMaxScale = Number.isFinite(maxScale) && maxScale > 0 ? maxScale : MAX_FIXED_PAGE_VIEWPORT_SCALE;
+  return Math.min(Math.max(value, MIN_PAGE_VIEWPORT_SCALE), safeMaxScale);
+}

package/template/core/src/openpress/reader/readerTypes.ts

@@ -0,0 +1,4 @@
+import type { IndexedHtmlPage } from "../document-model";
+import type { HtmlPageBlock } from "../document-model";
+
+export type DisplayPage = IndexedHtmlPage & Pick<HtmlPageBlock, "source" | "frameKey">;

package/template/core/src/openpress/reader/usePageViewportScale.ts

@@ -0,0 +1,119 @@
+import { useLayoutEffect, useMemo, useState, type RefObject } from "react";
+import { scheduleBrowserFrame } from "../shared";
+import {
+  formatPageViewportScaleLabel,
+  formatPageViewportScaleValue,
+  resolvePageViewportScale,
+  type PageLayoutMode,
+  type PageViewportScaleMode,
+} from "./pageViewportScaleModel";
+
+export function usePageViewportScale({
+  stageRef,
+  pageContainerRef,
+  pageCount,
+  layoutMode = "single",
+}: {
+  stageRef: RefObject<HTMLElement | null>;
+  pageContainerRef: RefObject<HTMLElement | null>;
+  pageCount: number;
+  layoutMode?: PageLayoutMode;
+}) {
+  const [scaleMode, setScaleMode] = useState<PageViewportScaleMode>("fit-width");
+  const [scale, setScale] = useState(1);
+
+  useLayoutEffect(() => {
+    if (typeof window === "undefined") return undefined;
+
+    let cancelFrame: (() => void) | null = null;
+
+    const syncScale = () => {
+      cancelFrame?.();
+      cancelFrame = scheduleBrowserFrame(() => {
+        cancelFrame = null;
+        const container = pageContainerRef.current;
+        if (!container) return;
+
+        const pageSurface = container.querySelector<HTMLElement>(".openpress-html-page__html");
+        if (!pageSurface) {
+          container.style.setProperty("--openpress-page-viewport-scale", "1");
+          container.dataset.openpressPageScaleMode = scaleMode;
+          container.dataset.openpressPageScale = "1";
+          setScale(1);
+          return;
+        }
+
+        const stage = stageRef.current ?? container.parentElement;
+        const containerStyle = window.getComputedStyle(container);
+        const paddingLeft = parseCssPixelValue(containerStyle.paddingLeft);
+        const paddingRight = parseCssPixelValue(containerStyle.paddingRight);
+        const paddingTop = parseCssPixelValue(containerStyle.paddingTop);
+        const paddingBottom = parseCssPixelValue(containerStyle.paddingBottom);
+        const columnGap = parseCssPixelValue(containerStyle.columnGap || containerStyle.gap);
+        const availableWidth = Math.max(
+          1,
+          (stage?.clientWidth || container.clientWidth || window.innerWidth) - paddingLeft - paddingRight,
+        );
+        const availableHeight = Math.max(
+          1,
+          (stage?.clientHeight || container.clientHeight || window.innerHeight) - paddingTop - paddingBottom,
+        );
+        const pageWidth = pageSurface.offsetWidth;
+        const pageHeight = pageSurface.offsetHeight;
+        const canonicalWidth = layoutMode === "spread" ? (pageWidth * 2) + columnGap : pageWidth;
+        const canonicalHeight = pageHeight;
+        const fitWidthScale = canonicalWidth > 0 ? availableWidth / canonicalWidth : 1;
+        const fitPageScale = canonicalWidth > 0 && canonicalHeight > 0
+          ? Math.min(availableWidth / canonicalWidth, availableHeight / canonicalHeight)
+          : 1;
+        const nextScale = resolvePageViewportScale({ mode: scaleMode, fitWidthScale, fitPageScale });
+        const nextScaleValue = formatPageViewportScaleValue(nextScale);
+
+        container.style.setProperty("--openpress-page-viewport-scale", nextScaleValue);
+        container.dataset.openpressPageScaleMode = scaleMode;
+        container.dataset.openpressPageScale = nextScaleValue;
+        setScale((current) => (current === nextScale ? current : nextScale));
+      });
+    };
+
+    syncScale();
+
+    const ResizeObserverCtor = window.ResizeObserver;
+    const observer = ResizeObserverCtor ? new ResizeObserverCtor(syncScale) : null;
+    const stage = stageRef.current;
+    const container = pageContainerRef.current;
+    if (stage) observer?.observe(stage);
+    if (container) observer?.observe(container);
+
+    window.addEventListener("resize", syncScale);
+    window.visualViewport?.addEventListener("resize", syncScale);
+    return () => {
+      cancelFrame?.();
+      observer?.disconnect();
+      window.removeEventListener("resize", syncScale);
+      window.visualViewport?.removeEventListener("resize", syncScale);
+    };
+  }, [layoutMode, pageContainerRef, pageCount, scaleMode, stageRef]);
+
+  const scaleLabel = useMemo(
+    () => {
+      const labelScale = scaleMode.startsWith("scale-")
+        ? resolvePageViewportScale({ mode: scaleMode, fitWidthScale: scale, fitPageScale: scale })
+        : scale;
+      return formatPageViewportScaleLabel(scaleMode, labelScale);
+    },
+    [scale, scaleMode],
+  );
+
+  return {
+    scale,
+    scaleMode,
+    scaleLabel,
+    setScaleMode,
+  };
+}
+
+function parseCssPixelValue(value: string) {
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) ? parsed : 0;
+}

package/template/core/src/openpress/reader/usePanelState.ts

@@ -0,0 +1,56 @@
+import { useCallback, useEffect, useState } from "react";
+
+export interface UsePanelStateOptions {
+  leftPanelBreakpoint?: number;
+  rightPanelBreakpoint?: number;
+  onAfterResize?: () => void;
+}
+
+export interface PanelState {
+  leftPanelOpen: boolean;
+  rightPanelOpen: boolean;
+  toggleLeftPanel: () => void;
+  toggleRightPanel: () => void;
+}
+
+export function usePanelState({
+  leftPanelBreakpoint,
+  rightPanelBreakpoint = 1000,
+  onAfterResize,
+}: UsePanelStateOptions = {}): PanelState {
+  const shouldOpenLeftPanel = useCallback(
+    () =>
+      leftPanelBreakpoint === undefined || typeof window === "undefined" || window.innerWidth >= leftPanelBreakpoint,
+    [leftPanelBreakpoint],
+  );
+  const shouldOpenRightPanel = useCallback(
+    () => typeof window === "undefined" || window.innerWidth >= rightPanelBreakpoint,
+    [rightPanelBreakpoint],
+  );
+
+  const [rightPanelOpen, setRightPanelOpen] = useState(false);
+  const [leftPanelOpen, setLeftPanelOpen] = useState(false);
+
+  useEffect(() => {
+    if (typeof window === "undefined") return undefined;
+
+    const handleResize = () => {
+      setLeftPanelOpen((open) => (open && !shouldOpenLeftPanel() ? false : open));
+      setRightPanelOpen((open) => (open && !shouldOpenRightPanel() ? false : open));
+      onAfterResize?.();
+    };
+
+    handleResize();
+    window.addEventListener("resize", handleResize);
+    window.visualViewport?.addEventListener("resize", handleResize);
+    return () => {
+      window.removeEventListener("resize", handleResize);
+      window.visualViewport?.removeEventListener("resize", handleResize);
+    };
+  }, [shouldOpenLeftPanel, shouldOpenRightPanel, onAfterResize]);
+
+  const toggleLeftPanel = useCallback(() => setLeftPanelOpen((open) => !open), []);
+  const toggleRightPanel = useCallback(() => setRightPanelOpen((open) => !open), []);
+
+  return { leftPanelOpen, rightPanelOpen, toggleLeftPanel, toggleRightPanel };
+}

package/template/core/src/openpress/reader/useReaderHashSync.ts

@@ -0,0 +1,61 @@
+import { useEffect, type MutableRefObject } from "react";
+import { pageIndexFromHash, replacePageRoute } from "./readerPageRoute";
+import { scrollToPage } from "./readerScroll";
+
+export interface UseReaderHashSyncOptions {
+  stageRef: MutableRefObject<HTMLElement | null>;
+  pageRefs: MutableRefObject<Array<HTMLElement | null>>;
+  currentPageIndex: number;
+  currentPageIndexRef: MutableRefObject<number>;
+  normalizedPageCount: number;
+  setCurrentPageIndex: (index: number) => void;
+  armPendingScrollTarget: (target: number) => void;
+}
+
+export function useReaderHashSync({
+  stageRef,
+  pageRefs,
+  currentPageIndex,
+  currentPageIndexRef,
+  normalizedPageCount,
+  setCurrentPageIndex,
+  armPendingScrollTarget,
+}: UseReaderHashSyncOptions) {
+  // Mirror currentPageIndex into the URL hash so deep links + history work.
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    replacePageRoute(currentPageIndex);
+  }, [currentPageIndex]);
+
+  // Listen for hash/back/forward navigation and drive scroll to match.
+  useEffect(() => {
+    if (typeof window === "undefined") return undefined;
+
+    const syncFromHash = (behavior: ScrollBehavior) => {
+      const refs = pageRefs.current;
+      const hashPage = pageIndexFromHash(window.location.hash, normalizedPageCount);
+      if (hashPage === null) return;
+      // replacePageRoute writes the hash to mirror state; skip if it already
+      // matches so we don't fight ourselves.
+      if (hashPage === currentPageIndexRef.current) return;
+      armPendingScrollTarget(hashPage);
+      setCurrentPageIndex(hashPage);
+      scrollToPage(refs, hashPage, behavior, stageRef.current);
+    };
+
+    const onHashChange = () => syncFromHash("smooth");
+    window.addEventListener("hashchange", onHashChange);
+    window.addEventListener("popstate", onHashChange);
+    return () => {
+      window.removeEventListener("hashchange", onHashChange);
+      window.removeEventListener("popstate", onHashChange);
+    };
+  }, [
+    armPendingScrollTarget,
+    currentPageIndexRef,
+    normalizedPageCount,
+    pageRefs,
+    setCurrentPageIndex,
+    stageRef,
+  ]);
+}