@open-press/core 0.3.0

package/src/openpress/readerRuntime.ts

@@ -0,0 +1,230 @@
+import { useCallback, useEffect, useRef, useState, type RefCallback } from "react";
+import { pageIndexFromHash, replacePageRoute } from "./pageRoute";
+import { createReaderPageRegistry } from "./readerPageRegistry";
+import { clampReaderPageIndex, formatReaderPageNumber, normalizeReaderPageCount } from "./readerState";
+import { createPageVisibilityObserver, scrollToPage } from "./readerScroll";
+
+export interface SetPageOptions {
+  behavior?: ScrollBehavior;
+}
+
+interface UseReaderRuntimeOptions {
+  pageCount: number;
+  rightPanelBreakpoint?: number;
+}
+
+// Generous upper bound on a smooth scrollIntoView. If the target ref is gone or
+// the browser never settles on it, clear the guard so the IO observer regains
+// authority over currentPageIndex.
+const PROGRAMMATIC_SCROLL_FALLBACK_MS = 2500;
+
+export function useReaderRuntime({ pageCount, rightPanelBreakpoint = 1000 }: UseReaderRuntimeOptions) {
+  const normalizedPageCount = normalizeReaderPageCount(pageCount);
+  const stageRef = useRef<HTMLElement | null>(null);
+  const [pageRegistrationVersion, setPageRegistrationVersion] = useState(0);
+  const pageRegistry = useRef<ReturnType<typeof createReaderPageRegistry<HTMLElement>> | null>(null);
+  if (!pageRegistry.current) {
+    pageRegistry.current = createReaderPageRegistry<HTMLElement>(setPageRegistrationVersion);
+  }
+
+  const [currentPageIndex, setCurrentPageIndex] = useState(() => {
+    if (typeof window === "undefined") return 0;
+    const fromHash = pageIndexFromHash(window.location.hash, normalizedPageCount);
+    return fromHash ?? 0;
+  });
+  const [rightPanelOpen, setRightPanelOpen] = useState(() =>
+    typeof window === "undefined" ? true : window.innerWidth >= rightPanelBreakpoint,
+  );
+
+  const currentPageIndexRef = useRef(currentPageIndex);
+  currentPageIndexRef.current = currentPageIndex;
+
+  // While a programmatic scroll is in flight, the IntersectionObserver should
+  // only accept the destination page (not the intermediates we sweep past).
+  // The ref clears as soon as the destination becomes visible.
+  const pendingScrollTargetRef = useRef<number | null>(null);
+  const pendingScrollClearTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const armPendingScrollTarget = useCallback((target: number) => {
+    pendingScrollTargetRef.current = target;
+    if (pendingScrollClearTimerRef.current !== null) clearTimeout(pendingScrollClearTimerRef.current);
+    pendingScrollClearTimerRef.current = setTimeout(() => {
+      pendingScrollTargetRef.current = null;
+      pendingScrollClearTimerRef.current = null;
+    }, PROGRAMMATIC_SCROLL_FALLBACK_MS);
+  }, []);
+
+  const clearPendingScrollTarget = useCallback(() => {
+    pendingScrollTargetRef.current = null;
+    if (pendingScrollClearTimerRef.current !== null) {
+      clearTimeout(pendingScrollClearTimerRef.current);
+      pendingScrollClearTimerRef.current = null;
+    }
+  }, []);
+
+  useEffect(() => () => clearPendingScrollTarget(), [clearPendingScrollTarget]);
+
+  useEffect(() => {
+    pageRegistry.current?.trim(normalizedPageCount);
+    setCurrentPageIndex((idx) => clampReaderPageIndex(idx, normalizedPageCount));
+  }, [normalizedPageCount]);
+
+  useEffect(() => {
+    const stage = stageRef.current;
+    if (!stage) return undefined;
+    const observer = createPageVisibilityObserver(stage, (pageIndex) => {
+      // During a programmatic scroll, ignore intermediate pages the browser
+      // sweeps past; only the destination counts as the new current page.
+      if (pendingScrollTargetRef.current !== null) {
+        if (pageIndex !== pendingScrollTargetRef.current) return;
+        clearPendingScrollTarget();
+      }
+      setCurrentPageIndex((prev) => (prev === pageIndex ? prev : pageIndex));
+    });
+    if (!observer) return undefined;
+    pageRegistry.current?.refs.forEach((el) => el && observer.observe(el));
+    return () => observer.disconnect();
+  }, [clearPendingScrollTarget, normalizedPageCount, pageRegistrationVersion]);
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    replacePageRoute(currentPageIndex);
+  }, [currentPageIndex]);
+
+  // When refs change (initial mount, pagination kicks in), re-anchor the
+  // stage to the page we already believe we're on. Otherwise scroll-snap
+  // mandatory snaps to whichever page happens to sit closest to the current
+  // scroll position. Only fire when we have somewhere non-default to land,
+  // so the IO observer stays free to drive state during ordinary navigation.
+  useEffect(() => {
+    const refs = pageRegistry.current?.refs ?? [];
+    const idx = currentPageIndexRef.current;
+    if (idx === 0) return;
+    if (!refs[idx]) return;
+    armPendingScrollTarget(idx);
+    scrollToPage(refs, idx, "instant", stageRef.current);
+  }, [armPendingScrollTarget, pageRegistrationVersion]);
+
+  useEffect(() => {
+    if (typeof window === "undefined") return undefined;
+
+    const syncFromHash = (behavior: ScrollBehavior) => {
+      const refs = pageRegistry.current?.refs ?? [];
+      const hashPage = pageIndexFromHash(window.location.hash, normalizedPageCount);
+      if (hashPage === null) return;
+      // Our own replacePageRoute call writes the hash to mirror state; skip
+      // if the hash 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, normalizedPageCount]);
+
+  useEffect(() => {
+    if (typeof window === "undefined") return undefined;
+
+    let frame: number | null = null;
+    const reAnchorAfterPaint = () => {
+      if (frame !== null) window.cancelAnimationFrame(frame);
+      frame = window.requestAnimationFrame(() => {
+        frame = null;
+        const refs = pageRegistry.current?.refs ?? [];
+        // If a programmatic scroll is in flight, re-anchor to its destination
+        // so the snap doesn't pull us back to where we were before clicking.
+        const target = pendingScrollTargetRef.current ?? currentPageIndexRef.current;
+        scrollToPage(refs, target, "instant", stageRef.current);
+      });
+    };
+
+    const handleResize = () => {
+      setRightPanelOpen(window.innerWidth >= rightPanelBreakpoint);
+      // scroll-snap-type: y mandatory re-aligns to the closest snap point on
+      // viewport change, which can land one page off from where the reader was.
+      // Pin to the IO-confirmed current page (or active programmatic target).
+      reAnchorAfterPaint();
+    };
+
+    handleResize();
+    window.addEventListener("resize", handleResize);
+    window.visualViewport?.addEventListener("resize", handleResize);
+    return () => {
+      window.removeEventListener("resize", handleResize);
+      window.visualViewport?.removeEventListener("resize", handleResize);
+      if (frame !== null) window.cancelAnimationFrame(frame);
+    };
+  }, [rightPanelBreakpoint]);
+
+  const setPage = useCallback(
+    (pageIndex: number, options: SetPageOptions = {}) => {
+      const refs = pageRegistry.current?.refs ?? [];
+      const target = clampReaderPageIndex(pageIndex, normalizedPageCount);
+      armPendingScrollTarget(target);
+      setCurrentPageIndex(target);
+      scrollToPage(refs, target, options.behavior ?? "smooth", stageRef.current);
+    },
+    [armPendingScrollTarget, normalizedPageCount],
+  );
+
+  const nextPage = useCallback(() => {
+    setPage(currentPageIndexRef.current + 1);
+  }, [setPage]);
+
+  const prevPage = useCallback(() => {
+    setPage(currentPageIndexRef.current - 1);
+  }, [setPage]);
+
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (isEditableTarget(event.target)) return;
+      if (event.key === "ArrowRight" || event.key === "PageDown") {
+        event.preventDefault();
+        nextPage();
+      } else if (event.key === "ArrowLeft" || event.key === "PageUp") {
+        event.preventDefault();
+        prevPage();
+      } else if (event.key === "Home") {
+        event.preventDefault();
+        setPage(0);
+      } else if (event.key === "End") {
+        event.preventDefault();
+        setPage(Math.max(0, normalizedPageCount - 1));
+      }
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [nextPage, prevPage, setPage, normalizedPageCount]);
+
+  const registerPage = useCallback<(pageIndex: number) => RefCallback<HTMLElement>>(
+    (pageIndex) => pageRegistry.current?.registerPage(pageIndex) ?? (() => undefined),
+    [],
+  );
+
+  const progressPercent =
+    normalizedPageCount <= 1 ? 100 : ((currentPageIndex + 1) / normalizedPageCount) * 100;
+
+  return {
+    stageRef,
+    currentPageIndex,
+    currentPageLabel: formatReaderPageNumber(currentPageIndex + 1),
+    totalPageLabel: formatReaderPageNumber(normalizedPageCount),
+    progressPercent,
+    rightPanelOpen,
+    registerPage,
+    setPage,
+    toggleRightPanel: () => setRightPanelOpen((open) => !open),
+  };
+}
+
+function isEditableTarget(target: EventTarget | null) {
+  if (!(target instanceof HTMLElement)) return false;
+  return Boolean(target.closest("input, textarea, select, button, [contenteditable='true']"));
+}

package/src/openpress/readerScroll.ts

@@ -0,0 +1,92 @@
+// Single place that touches scrollIntoView and IntersectionObserver. Keeping
+// these together makes it obvious which DOM APIs the reader depends on and
+// keeps the React runtime free of imperative scroll bookkeeping.
+
+const DEBOUNCE_MS = 100;
+
+const OBSERVER_THRESHOLDS = [0, 0.25, 0.5, 0.75, 1];
+
+export function scrollToPage(
+  refs: Array<HTMLElement | null>,
+  pageIndex: number,
+  behavior: ScrollBehavior = "smooth",
+  root?: HTMLElement | null,
+) {
+  const target = refs[pageIndex];
+  if (!target) return false;
+
+  if (root && root.contains(target) && typeof root.scrollTo === "function") {
+    const rootRect = root.getBoundingClientRect();
+    const targetRect = target.getBoundingClientRect();
+    const scrollMarginTop = readScrollMarginTop(target);
+    root.scrollTo({
+      top: Math.max(0, root.scrollTop + targetRect.top - rootRect.top - scrollMarginTop),
+      behavior,
+    });
+    return true;
+  }
+
+  target.scrollIntoView({ behavior, block: "start" });
+  return true;
+}
+
+function readScrollMarginTop(target: HTMLElement) {
+  if (typeof window === "undefined") return 0;
+  const value = Number.parseFloat(window.getComputedStyle(target).scrollMarginTop);
+  return Number.isFinite(value) ? value : 0;
+}
+
+export interface PageVisibilityObserver {
+  observe: (element: Element) => void;
+  disconnect: () => void;
+}
+
+export function createPageVisibilityObserver(
+  root: Element,
+  onVisiblePageChange: (pageIndex: number) => void,
+): PageVisibilityObserver | null {
+  if (typeof IntersectionObserver === "undefined") return null;
+
+  const ratios = new Map<Element, number>();
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const flush = () => {
+    debounceTimer = null;
+    let bestEl: Element | null = null;
+    let bestRatio = -1;
+    for (const [el, ratio] of ratios) {
+      if (ratio > bestRatio) {
+        bestRatio = ratio;
+        bestEl = el;
+      }
+    }
+    if (!bestEl || bestRatio <= 0) return;
+    const raw = bestEl.getAttribute("data-openpress-page-index");
+    if (raw === null) return;
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isFinite(parsed)) onVisiblePageChange(parsed);
+  };
+
+  const observer = new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        ratios.set(entry.target, entry.isIntersecting ? entry.intersectionRatio : 0);
+      }
+      if (debounceTimer !== null) clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(flush, DEBOUNCE_MS);
+    },
+    { root, threshold: OBSERVER_THRESHOLDS },
+  );
+
+  return {
+    observe: (element) => observer.observe(element),
+    disconnect: () => {
+      observer.disconnect();
+      if (debounceTimer !== null) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+      }
+      ratios.clear();
+    },
+  };
+}

package/src/openpress/readerState.ts

@@ -0,0 +1,15 @@
+export function clampReaderPageIndex(value: number, pageCount: number) {
+  const normalizedPageCount = normalizeReaderPageCount(pageCount);
+  if (normalizedPageCount <= 0) return 0;
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(Math.max(Math.trunc(value), 0), normalizedPageCount - 1);
+}
+
+export function formatReaderPageNumber(value: number) {
+  return String(Math.max(Math.trunc(value), 1)).padStart(2, "0");
+}
+
+export function normalizeReaderPageCount(value: number) {
+  if (!Number.isFinite(value)) return 0;
+  return Math.max(Math.trunc(value), 0);
+}

package/src/openpress/renderer.tsx

@@ -0,0 +1,91 @@
+import { useMemo, type CSSProperties } from "react";
+import { PrintDocument, PublicViewer } from "./publicPage";
+import { isPrintModeLocation, isWorkspaceModeLocation } from "./runtimeMode";
+import { HtmlWorkbench } from "./workbench";
+import type {
+  DeploymentInfo,
+  ReaderDocument,
+  HtmlPageBlock,
+  Theme,
+} from "./types";
+
+interface RendererProps {
+  document: ReaderDocument;
+  deploymentInfo?: DeploymentInfo;
+}
+
+export function Renderer({
+  document,
+  deploymentInfo = { online: false },
+}: RendererProps) {
+  const style = themeToCssVariables(document.theme);
+  const htmlPages = document.blocks.filter((block): block is HtmlPageBlock => block.kind === "htmlPage");
+  const workspaceMode = useMemo(() => {
+    if (typeof window === "undefined") return false;
+    return isWorkspaceModeLocation(window.location);
+  }, []);
+  const printMode = useMemo(() => {
+    if (typeof window === "undefined") return false;
+    return isPrintModeLocation(window.location);
+  }, []);
+
+  if (htmlPages.length > 0) {
+    if (printMode) {
+      return <PrintDocument document={document} pages={htmlPages} style={style} />;
+    }
+
+    if (!workspaceMode) {
+      return <PublicViewer document={document} pages={htmlPages} style={style} deploymentInfo={deploymentInfo} />;
+    }
+
+    return (
+      <HtmlWorkbench
+        document={document}
+        pages={htmlPages}
+        style={style}
+        devMode={workspaceMode}
+        deploymentInfo={deploymentInfo}
+      />
+    );
+  }
+
+  return <EmptyState style={style} workspaceMode={workspaceMode} />;
+}
+
+function EmptyState({ style, workspaceMode }: { style: CSSProperties; workspaceMode: boolean }) {
+  return (
+    <main className="openpress-shell openpress-empty-state" style={style}>
+      <section className="openpress-empty-state__panel">
+        <p className="openpress-empty-state__eyebrow">OpenPress</p>
+        <h1 className="openpress-empty-state__title">This document has no content yet.</h1>
+        <p className="openpress-empty-state__body">
+          Add React MDX chapter files under <code>document/chapters/**/content/</code>, then re-export.
+        </p>
+        {workspaceMode ? (
+          <ol className="openpress-empty-state__steps">
+            <li><code>npm run openpress:export</code> &nbsp;— refreshes <code>public/openpress/document.json</code></li>
+            <li>Reload this page</li>
+          </ol>
+        ) : (
+          <p className="openpress-empty-state__body">
+            (If you are the document author, run <code>npm run dev</code> locally to edit.)
+          </p>
+        )}
+      </section>
+    </main>
+  );
+}
+
+function themeToCssVariables(theme?: Theme) {
+  const style: CSSProperties & Record<`--${string}`, string> = {
+    "--openpress-font-family": theme?.fontFamily ?? "'Noto Sans TC', 'PingFang TC', sans-serif",
+    "--openpress-accent": theme?.accentColor ?? "#df4b21",
+    "--openpress-text": theme?.textColor ?? "#20242a",
+  };
+
+  if (theme?.pageWidth) style["--openpress-page-width"] = theme.pageWidth;
+  if (theme?.pageHeight) style["--openpress-page-height"] = theme.pageHeight;
+  if (theme?.pagePadding) style["--openpress-page-padding"] = theme.pagePadding;
+
+  return style;
+}

package/src/openpress/runtimeMode.ts

@@ -0,0 +1,22 @@
+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 isPrintModeLocation(location: Pick<Location, "search">) {
+  return new URLSearchParams(location.search).has("print");
+}
+
+export function buildPublicPreviewHref(currentHref: string, pageIndex?: number) {
+  const url = new URL(currentHref);
+  url.searchParams.delete("dev");
+  url.searchParams.delete("workspace");
+  url.searchParams.delete("fontPreview");
+  if (typeof pageIndex === "number") {
+    url.hash = `page-${String(pageIndex + 1).padStart(2, "0")}`;
+  }
+  return url.toString();
+}

package/src/openpress/types.ts

@@ -0,0 +1,112 @@
+export interface DeploymentInfo {
+  online: boolean;
+  deployedAt?: string;
+  pdf?: string;
+  publicUrl?: string;
+  dirty?: boolean;
+  configured?: boolean;
+  adapter?: string;
+  source?: string;
+  projectName?: string;
+  setupMessage?: string;
+}
+
+export interface ReaderDocument {
+  meta: DocumentMeta;
+  source?: DocumentSource;
+  theme?: Theme;
+  blocks: HtmlPageBlock[];
+}
+
+export interface DocumentSource {
+  type: string;
+  contentDir?: string;
+  editable?: boolean;
+  editMode?: string;
+  styles?: DocumentStyle[];
+  blockMap?: Record<string, SourceBlock>;
+  pagination?: BuildPagination;
+}
+
+export interface DocumentStyle {
+  kind: string;
+  href?: string;
+  path?: string;
+}
+
+export interface SourceLocation {
+  line: number;
+  column: number;
+  endLine?: number;
+  endColumn?: number;
+}
+
+export interface SourceBlock {
+  id: string;
+  kind?: string;
+  name?: string;
+  chapterSlug?: string;
+  path: string;
+  pageIndex?: number;
+  pageNumber?: number;
+  source?: SourceLocation;
+}
+
+export interface BuildPagination {
+  mode: string;
+  pageSafeHeightPx?: number;
+  warnings?: PaginationWarning[];
+}
+
+export interface PaginationWarning {
+  code: string;
+  blockId?: string;
+  height?: number;
+  pageSafeHeightPx?: number;
+  path?: string;
+  source?: SourceLocation;
+}
+
+export interface DocumentMeta {
+  title: string;
+  subtitle?: string;
+  organization?: string;
+  version?: string;
+  footer?: string;
+  workspaceLabel?: string;
+}
+
+export interface Theme {
+  pageWidth?: string;
+  pageHeight?: string;
+  pagePadding?: string;
+  fontFamily?: string;
+  accentColor?: string;
+  textColor?: string;
+}
+
+export interface BlockSource {
+  file: string;
+  path: string;
+  kind?: string;
+  chapter?: number;
+  slug?: string;
+  sectionIndex?: number;
+}
+
+// The engine currently emits one block kind only: a fully-rendered HTML page.
+// All historical structured-block variants (cover / section / paragraph /
+// list / figure / table / callout) were aspirational and never instantiated;
+// they were removed along with the unused client-side block model. If the
+// engine ever emits structured blocks again, reintroduce a discriminated
+// union here.
+export interface HtmlPageBlock {
+  id: string;
+  kind: "htmlPage";
+  title: string;
+  pageNumber: number;
+  html: string;
+  anchors?: string[];
+  className?: string;
+  source?: BlockSource;
+}