@libraz/mejiro-react 0.5.0 → 0.6.0

package/README.md

@@ -31,6 +31,17 @@ export default function App() {
 html, body, #root { height: 100%; margin: 0; }
 ```
 
+To embed in normal page flow instead (a blog post, a docs page) with no height
+math, use `fit="width"` — the reader self-sizes its height from its width:
+
+```tsx
+<MejiroReader epubUrl="/book.epub" fit="width" />
+```
+
+> Embedding inside a framework with an unlayered global CSS reset (Next.js,
+> Tailwind preflight, normalize.css)? See the [cascade-layers note](https://github.com/libraz/mejiro/tree/main/docs/en/08-react-and-vue.md#css-cascade-layers-host-resets-can-clobber-the-reader-chrome)
+> so host resets don't clobber the reader chrome.
+
 ## Templates
 
 Copy-paste-ready starters live under [`examples/`](https://github.com/libraz/mejiro/tree/main/examples):

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode, CSSProperties, PointerEvent, TextareaHTMLAttributes, RefObject } from 'react';
 import { EpubBook, AssetResolver, EditableEpub, ManuscriptDialect, EpubChapter, EditableEpubBook, AnnotatedParagraph, AddImageInput, EditableEpubImage, EpubExportOptions, EpubProjectMetadata, EpubProject } from '@libraz/mejiro/epub';
-import { BookOptions, ChapterLayout, SpreadResult, PageResult, InChapterAnchor, ReadingAnchor, ManuscriptChapter, AnchorRect, AnchorRange, MejiroBook } from '@libraz/mejiro/book';
+import { BookOptions, ChapterLayout, SpreadResult, PageResult, ComputePageSizeOptions, InChapterAnchor, ReadingAnchor, ManuscriptChapter, AnchorRect, AnchorRange, MejiroBook } from '@libraz/mejiro/book';
 import { RenderPage } from '@libraz/mejiro/render';
 import { FontFamily, InlineAnnotation } from '@libraz/mejiro/browser';
 
@@ -567,6 +567,22 @@ type MejiroReaderMode = 'paginated' | 'scroll';
  * - `auto` — switch based on the surface aspect ratio (single when portrait).
  */
 type MejiroSpreadMode = 'double' | 'single' | 'auto';
+/**
+ * Which page of a spread prints its page number: `'both'` (right = odd,
+ * left = even), only `'right'`, only `'left'`, or `'none'`.
+ */
+type PageNumberDisplay = 'both' | 'right' | 'left' | 'none';
+/**
+ * How the reader sizes itself inside its container.
+ * - `fill` — fill the container's given height; the spread is fitted inside it,
+ *   letterboxing if the box aspect doesn't match the spread (the default; the
+ *   host must give the reader a height).
+ * - `width` — self-size from width: the reader derives its own height from its
+ *   measured width and the page aspect ratio, so the spread fills exactly with
+ *   no letterbox and the host needs no height/aspect magic numbers. The host
+ *   only constrains the width.
+ */
+type MejiroReaderFit = 'fill' | 'width';
 /** Built-in reader theme presets. */
 type MejiroThemeName = 'light' | 'dark' | 'sepia' | 'high-contrast' | 'auto';
 /**
@@ -656,6 +672,23 @@ interface MejiroReaderHandle {
      */
     subscribe<E extends keyof MejiroReaderEventMap>(event: E, listener: MejiroReaderEventMap[E]): () => void;
 }
+/**
+ * Context passed to a {@link MejiroReaderCommonProps.renderSettings} render prop.
+ *
+ * Lets a host replace the built-in settings controls with its own UI while
+ * keeping the panel chrome and its open/close accordion. All fields are wired
+ * to the live reader.
+ */
+interface MejiroReaderSettingsSlot {
+    /** Current effective settings (font, size, line spacing, kinsoku, hanging). */
+    settings: EditableSettings;
+    /** Applies a partial settings change and re-flows the chapter. */
+    update: (partial: Partial<BookOptions>) => void;
+    /** Whether the settings panel is currently open. */
+    open: boolean;
+    /** Toggles the settings panel open/closed (same as the header button). */
+    toggle: () => void;
+}
 /** Props shared across every {@link MejiroReader} source mode. */
 interface MejiroReaderCommonProps {
     /**
@@ -668,6 +701,15 @@ interface MejiroReaderCommonProps {
      * ```
      */
     options?: BookOptions;
+    /**
+     * Page-geometry overrides forwarded to `MejiroBook.computePageSize`. Use to
+     * tune how the spread is sized inside the surface — most usefully to shrink
+     * the reserved margins so the pages fill their frame, e.g.
+     * `pageGeometry={{ gutterOffset: 0, headerOffset: 0 }}`. Also accepts
+     * `aspect`, `minWidth`, `minHeight`, `maxHeight`, and inner `padding`; omitted
+     * fields fall back to the built-in defaults.
+     */
+    pageGeometry?: ComputePageSizeOptions;
     /** Font choices for the settings panel. */
     fonts?: FontChoice[];
     /**
@@ -699,6 +741,16 @@ interface MejiroReaderCommonProps {
      * only the right page; `auto` flips to `single` for portrait viewports.
      */
     spreadMode?: MejiroSpreadMode;
+    /**
+     * How the reader sizes itself in its container. `fill` (default) fills the
+     * container height and letterboxes the spread; `width` makes the reader
+     * self-size — it derives its height from its width and the page aspect, so an
+     * embedding host only has to constrain the width (no height/aspect magic
+     * numbers, no letterbox). In `width` mode the reserved `gutterOffset` /
+     * `headerOffset` default to 0 so the spread fills edge-to-edge; override via
+     * {@link MejiroReaderProps.pageGeometry} if you still want them. @defaultValue 'fill'
+     */
+    fit?: MejiroReaderFit;
     /**
      * Enable surface-tap chrome toggling. Tapping the center of the spread
      * (away from buttons) hides the header and chapter panel; tapping again
@@ -769,6 +821,15 @@ interface MejiroReaderCommonProps {
     chapterNavMode?: MejiroChapterNavMode;
     /** Show the settings panel toggle. @defaultValue `!bare` */
     enableSettings?: boolean;
+    /**
+     * Replaces the built-in settings controls with custom UI while keeping the
+     * panel chrome and its open/close accordion. Receives a
+     * {@link MejiroReaderSettingsSlot} wired to the live reader, so a host can
+     * build its own settings form without a parallel `options` shadow. The header
+     * "Settings" button still toggles the panel. `enableSettings` remains the
+     * on/off switch.
+     */
+    renderSettings?: (slot: MejiroReaderSettingsSlot) => ReactNode;
     /** Show the image-overlay editing/demo button. @defaultValue false */
     enableImageOverlay?: boolean;
     /** Show the stats line. @defaultValue `!bare` */
@@ -777,6 +838,14 @@ interface MejiroReaderCommonProps {
     enableKeyboard?: boolean;
     /** Show the "n / total" indicator. @defaultValue `!bare` */
     enablePageIndicator?: boolean;
+    /**
+     * Which page of a spread shows its page number in the running head.
+     * `'both'` numbers each page (right = odd, left = even), `'right'` /
+     * `'left'` number only that side, `'none'` hides them (the
+     * {@link MejiroReaderProps.enablePageIndicator} "n / total" badge is
+     * independent). @defaultValue 'both'
+     */
+    pageNumbers?: PageNumberDisplay;
     /**
      * Reader-side annotations to render as highlights. Each annotation whose
      * `chapter` matches the current chapter is converted to spread-local
@@ -1248,10 +1317,39 @@ declare function useAnnotations(options: UseAnnotationsOptions): UseAnnotationsR
 
 /** Options for {@link useChapterLayout}. */
 interface UseChapterLayoutOptions {
-    /** Listen for `window.resize` and re-flow on resize. @defaultValue true */
+    /** Observe the surface element for size changes and re-flow. @defaultValue true */
     enableResize?: boolean;
-    /** Debounce window (ms) for resize re-flows. @defaultValue 120 */
+    /** Debounce window (ms) applied to size-triggered re-flows. @defaultValue 120 */
     resizeDebounce?: number;
+    /**
+     * Resolver for page-geometry overrides forwarded to
+     * {@link MejiroBook.computePageSize} — e.g. to shrink the reserved
+     * `gutterOffset` / `headerOffset` so the pages fill their frame. Called on
+     * every (re)layout so it may return a value that changes over time.
+     */
+    pageGeometry?: () => ComputePageSizeOptions | undefined;
+    /**
+     * Capture the current reading position from the outgoing layout, just before
+     * a **reflow** (non-blank) re-layout replaces it. The returned anchor is
+     * exposed via {@link UseChapterLayoutReturn.pendingRestore} and should be
+     * applied once the new layout commits. Return `null` to skip preservation.
+     * Never called for blank (content-change) re-layouts.
+     *
+     * A reflow yields a brand-new {@link ChapterLayout} object, which resets any
+     * downstream spread index to 0; capturing here and restoring after keeps the
+     * reader on the same passage across resizes and font / option changes.
+     */
+    capturePosition?: (layout: ChapterLayout) => InChapterAnchor | null;
+}
+/** Options for {@link UseChapterLayoutReturn.recompute}. */
+interface RecomputeOptions {
+    /**
+     * Blank the current layout while the new one is computed. Use for content
+     * changes (chapter / book swaps); skip for size or option changes so the
+     * previous spread stays visible until the re-flow completes (no flicker).
+     * @defaultValue true
+     */
+    blank?: boolean;
 }
 /** Page dimensions returned by {@link MejiroBook.computePageSize}. */
 interface PageDimensions {
@@ -1272,14 +1370,37 @@ interface UseChapterLayoutReturn {
     /** Most recent layout time (ms). */
     elapsedMs: number;
     /** Force a fresh layout computation. */
-    recompute: () => Promise<void>;
+    recompute: (opts?: RecomputeOptions) => Promise<void>;
+    /**
+     * Anchor captured before the most recent reflow re-layout, awaiting
+     * restoration into the new {@link layout}. Consume it in a layout effect keyed
+     * on `layout` (after any index reset) and clear it back to `null`.
+     */
+    pendingRestore: RefObject<InChapterAnchor | null>;
 }
 /**
- * React hook that lays out the currently-selected chapter and re-flows on resize.
+ * React hook that lays out the currently-selected chapter and re-flows when the
+ * surface resizes.
  *
- * Re-layouts whenever `epub` or `chapterIndex` change. On `window.resize`,
- * page dimensions are recomputed and {@link ChapterLayout.resize} is called
- * instead of a full re-layout.
+ * Re-layouts whenever `book`, `epub`, or `chapterIndex` change, against the
+ * dimensions of `surface`. The `surface` element is observed with a
+ * {@link ResizeObserver}: the first observation runs immediately (so a reader
+ * mounted before its container had a final box is still sized correctly on
+ * first paint), and later size changes trigger a debounced **full re-layout**.
+ *
+ * A full re-layout — rather than a `ChapterLayout.resize()` fast-path — is used
+ * for size changes on purpose: the fast-path only stretches `pageWidth` and does
+ * not re-paginate, leaving sparse, half-empty pages after a non-trivial size
+ * delta. Because a full re-layout yields a new {@link ChapterLayout} object
+ * (resetting any downstream spread index to 0), the reading position is
+ * preserved across reflows via {@link UseChapterLayoutOptions.capturePosition}
+ * and {@link UseChapterLayoutReturn.pendingRestore}.
+ *
+ * @param book - The book instance to lay out with.
+ * @param epub - The current parsed EPUB.
+ * @param chapterIndex - Zero-based chapter index to lay out.
+ * @param surface - DOM ref for the reading surface used for page sizing.
+ * @param options - Behavior overrides.
  */
 declare function useChapterLayout(book: MejiroBook, epub: EpubBook | null, chapterIndex: number, surface: RefObject<HTMLElement | null>, options?: UseChapterLayoutOptions): UseChapterLayoutReturn;
 
@@ -1602,6 +1723,12 @@ interface UseSpreadReturn {
     prev: () => void;
     /** Jump to an arbitrary spread index (clamped). */
     goTo: (index: number) => void;
+    /**
+     * Set the spread index immediately, with no page-turn animation, clamped to
+     * `[0, totalSpreads − 1]`. Use to restore a reading position after a reflow
+     * re-layout (where an animated {@link goTo} would briefly flash spread 0).
+     */
+    setSpread: (index: number) => void;
     /** Manually refresh `spread` from `layout` at the current index. */
     refresh: () => void;
 }
@@ -1611,4 +1738,4 @@ interface UseSpreadReturn {
  */
 declare function useSpread(layout: ChapterLayout | null, options?: UseSpreadOptions): UseSpreadReturn;
 
-export { type Annotation, type AnnotationsStorage, type EditableEpubSelection, type EditableSettings, type EpubProjectChapterDraft, type FontChoice, type ImageRect, type ManuscriptEditorChapter, type ManuscriptPageDimensions, type ManuscriptPreviewProps, MejiroChapterNav, type MejiroChapterNavMode, type MejiroChapterNavProps, type MejiroChapterNavVariant, MejiroDropZone, type MejiroDropZoneProps, MejiroEditor, type MejiroEditorProps, type MejiroExportPolicy, MejiroI18nProvider, MejiroImageOverlay, type MejiroImageOverlayProps, type MejiroLocale, MejiroManuscriptEditor, type MejiroManuscriptEditorProps, type MejiroMessages, MejiroNotationHighlighter, type MejiroNotationHighlighterProps, MejiroPage, MejiroPageIndicator, type MejiroPageIndicatorProps, type MejiroPageProps, MejiroPageView, type MejiroPageViewProps, MejiroReader, type MejiroReaderControlledProps, type MejiroReaderEventMap, type MejiroReaderFileProps, type MejiroReaderHandle, type MejiroReaderMode, type MejiroReaderProps, type MejiroReaderUrlProps, MejiroScrollView, type MejiroScrollViewProps, MejiroSelectionLayer, type MejiroSelectionLayerProps, MejiroSettingsPanel, type MejiroSettingsPanelProps, MejiroShelf, type MejiroShelfProps, MejiroSpread, type MejiroSpreadMode, type MejiroSpreadProps, MejiroStats, type MejiroStatsProps, type MejiroTheme, type MejiroThemeName, MejiroToc, type MejiroTocProps, type MultiImageItem, type PageDimensions, type PageHeaderData, type ReadingPosition, type ReadingPositionStorage, type ReadingPositionValue, type UseAnnotationsOptions, type UseAnnotationsReturn, type UseChapterLayoutOptions, type UseChapterLayoutReturn, type UseEditableEpubOptions, type UseEditableEpubReturn, type UseEpubOptions, type UseEpubProjectOptions, type UseEpubProjectReturn, type UseEpubReturn, type UseI18nOptions, type UseImageOverlayOptions, type UseImageOverlayReturn, type UseLibraryOptions, type UseLibraryReturn, type UseManuscriptDraftOptions, type UseManuscriptDraftReturn, type UseManuscriptLayoutOptions, type UseManuscriptLayoutReturn, type UseMejiroBookReturn, type UseMultiImageOverlayOptions, type UseMultiImageOverlayReturn, type UseReadingPositionOptions, type UseReadingPositionReturn, type UseSpreadOptions, type UseSpreadReturn, type VolumeInfo, enMessages, format, jaMessages, resolveMessages, useAnnotations, useChapterLayout, useEditableEpub, useEpub, useEpubProject, useI18n, useImageOverlay, useLibrary, useManuscriptDraft, useManuscriptLayout, useMejiroBook, useMultiImageOverlay, useReadingPosition, useSpread };
+export { type Annotation, type AnnotationsStorage, type EditableEpubSelection, type EditableSettings, type EpubProjectChapterDraft, type FontChoice, type ImageRect, type ManuscriptEditorChapter, type ManuscriptPageDimensions, type ManuscriptPreviewProps, MejiroChapterNav, type MejiroChapterNavMode, type MejiroChapterNavProps, type MejiroChapterNavVariant, MejiroDropZone, type MejiroDropZoneProps, MejiroEditor, type MejiroEditorProps, type MejiroExportPolicy, MejiroI18nProvider, MejiroImageOverlay, type MejiroImageOverlayProps, type MejiroLocale, MejiroManuscriptEditor, type MejiroManuscriptEditorProps, type MejiroMessages, MejiroNotationHighlighter, type MejiroNotationHighlighterProps, MejiroPage, MejiroPageIndicator, type MejiroPageIndicatorProps, type MejiroPageProps, MejiroPageView, type MejiroPageViewProps, MejiroReader, type MejiroReaderControlledProps, type MejiroReaderEventMap, type MejiroReaderFileProps, type MejiroReaderFit, type MejiroReaderHandle, type MejiroReaderMode, type MejiroReaderProps, type MejiroReaderSettingsSlot, type MejiroReaderUrlProps, MejiroScrollView, type MejiroScrollViewProps, MejiroSelectionLayer, type MejiroSelectionLayerProps, MejiroSettingsPanel, type MejiroSettingsPanelProps, MejiroShelf, type MejiroShelfProps, MejiroSpread, type MejiroSpreadMode, type MejiroSpreadProps, MejiroStats, type MejiroStatsProps, type MejiroTheme, type MejiroThemeName, MejiroToc, type MejiroTocProps, type MultiImageItem, type PageDimensions, type PageHeaderData, type PageNumberDisplay, type ReadingPosition, type ReadingPositionStorage, type ReadingPositionValue, type UseAnnotationsOptions, type UseAnnotationsReturn, type UseChapterLayoutOptions, type UseChapterLayoutReturn, type UseEditableEpubOptions, type UseEditableEpubReturn, type UseEpubOptions, type UseEpubProjectOptions, type UseEpubProjectReturn, type UseEpubReturn, type UseI18nOptions, type UseImageOverlayOptions, type UseImageOverlayReturn, type UseLibraryOptions, type UseLibraryReturn, type UseManuscriptDraftOptions, type UseManuscriptDraftReturn, type UseManuscriptLayoutOptions, type UseManuscriptLayoutReturn, type UseMejiroBookReturn, type UseMultiImageOverlayOptions, type UseMultiImageOverlayReturn, type UseReadingPositionOptions, type UseReadingPositionReturn, type UseSpreadOptions, type UseSpreadReturn, type VolumeInfo, enMessages, format, jaMessages, resolveMessages, useAnnotations, useChapterLayout, useEditableEpub, useEpub, useEpubProject, useI18n, useImageOverlay, useLibrary, useManuscriptDraft, useManuscriptLayout, useMejiroBook, useMultiImageOverlay, useReadingPosition, useSpread };

package/dist/index.js

@@ -277,7 +277,7 @@ import { EditableEpub } from "@libraz/mejiro/epub";
 import { useCallback as useCallback7, useEffect as useEffect7, useRef as useRef10, useState as useState8 } from "react";
 
 // src/MejiroReader.tsx
-import { DEFAULT_BOOK_OPTIONS } from "@libraz/mejiro/book";
+import { DEFAULT_BOOK_OPTIONS, DEFAULT_PAGE_GEOMETRY } from "@libraz/mejiro/book";
 import { normalizeFontFamily as normalizeFontFamily5 } from "@libraz/mejiro/browser";
 import { manuscriptToEpubBook } from "@libraz/mejiro/epub";
 import {
@@ -285,6 +285,7 @@ import {
   useCallback as useCallback6,
   useEffect as useEffect6,
   useImperativeHandle,
+  useLayoutEffect as useLayoutEffect4,
   useMemo as useMemo4,
   useRef as useRef9,
   useState as useState7
@@ -538,6 +539,10 @@ var DEFAULT_FONTS = [
   { value: "serif", label: "System Serif" },
   { value: "sans-serif", label: "System Sans" }
 ];
+function fontLabelFromCss(css) {
+  const first = css.split(",")[0]?.trim() ?? css;
+  return first.replace(/^["']|["']$/g, "") || css;
+}
 function MejiroSettingsPanel({
   open,
   settings,
@@ -548,17 +553,12 @@ function MejiroSettingsPanel({
 }) {
   const messages = useI18n();
   const patch = (next) => onChange({ ...settings, ...next });
-  return /* @__PURE__ */ jsx7("div", { className: `mejiro-reader-settings-panel${open ? " is-open" : ""}`, children: /* @__PURE__ */ jsxs7("div", { className: "mejiro-reader-settings-inner", children: [
+  const currentFont = normalizeFontFamily3(settings.fontFamily);
+  const fontOptions = fonts.some((f) => f.value === currentFont) ? fonts : [{ value: currentFont, label: fontLabelFromCss(currentFont) }, ...fonts];
+  return /* @__PURE__ */ jsx7("div", { className: `mejiro-reader-settings-panel${open ? " is-open" : ""}`, children: /* @__PURE__ */ jsx7("div", { className: "mejiro-reader-settings-inner", children: /* @__PURE__ */ jsxs7("div", { className: "mejiro-reader-settings-content", children: [
     /* @__PURE__ */ jsxs7("div", { className: "mejiro-reader-settings-group", children: [
       /* @__PURE__ */ jsx7("span", { className: "mejiro-reader-settings-group-title", children: messages.settingsFont }),
-      /* @__PURE__ */ jsx7("div", { className: "mejiro-reader-control", children: /* @__PURE__ */ jsx7(
-        "select",
-        {
-          value: normalizeFontFamily3(settings.fontFamily),
-          onChange: (e) => patch({ fontFamily: e.target.value }),
-          children: fonts.map((f) => /* @__PURE__ */ jsx7("option", { value: f.value, children: f.label }, f.value))
-        }
-      ) }),
+      /* @__PURE__ */ jsx7("div", { className: "mejiro-reader-control", children: /* @__PURE__ */ jsx7("select", { value: currentFont, onChange: (e) => patch({ fontFamily: e.target.value }), children: fontOptions.map((f) => /* @__PURE__ */ jsx7("option", { value: f.value, children: f.label }, f.value)) }) }),
       /* @__PURE__ */ jsxs7("div", { className: "mejiro-reader-control", children: [
         /* @__PURE__ */ jsx7("label", { className: "mejiro-reader-control-label", htmlFor: "mejiro-reader-font-size", children: messages.settingsSize }),
         /* @__PURE__ */ jsx7(
@@ -643,7 +643,7 @@ function MejiroSettingsPanel({
         )
       ] })
     ] })
-  ] }) });
+  ] }) }) });
 }
 
 // src/MejiroSpread.tsx
@@ -685,11 +685,18 @@ function MejiroImageOverlay({
           {
             type: "button",
             "aria-label": messages.imageRemoveButton,
+            title: messages.imageRemoveButton,
             className: "mejiro-reader-image-overlay-close",
             onPointerDown: (e) => {
               e.stopPropagation();
               e.preventDefault();
               onClose?.();
+            },
+            onKeyDown: (e) => {
+              if (e.key !== "Enter" && e.key !== " ") return;
+              e.stopPropagation();
+              e.preventDefault();
+              onClose?.();
             }
           }
         )
@@ -978,7 +985,13 @@ function MejiroStats({
 }
 
 // src/useChapterLayout.ts
-import { useCallback, useEffect as useEffect2, useLayoutEffect as useLayoutEffect2, useRef as useRef4, useState as useState2 } from "react";
+import {
+  useCallback,
+  useEffect as useEffect2,
+  useLayoutEffect as useLayoutEffect2,
+  useRef as useRef4,
+  useState as useState2
+} from "react";
 function useChapterLayout(book, epub, chapterIndex, surface, options = {}) {
   const enableResize = options.enableResize ?? true;
   const resizeDebounce = options.resizeDebounce ?? 120;
@@ -989,31 +1002,43 @@ function useChapterLayout(book, epub, chapterIndex, surface, options = {}) {
   const [elapsedMs, setElapsedMs] = useState2(0);
   const layoutRef = useRef4(null);
   const requestIdRef = useRef4(0);
+  const pendingRestore = useRef4(null);
   layoutRef.current = layout;
-  const recompute = useCallback(async () => {
-    const requestId = ++requestIdRef.current;
-    const chapter = epub?.chapters[chapterIndex];
-    if (!(chapter && surface.current)) {
-      setLayout(null);
-      setPageWidth(0);
-      setPageHeight(0);
-      setContentHeight(0);
-      setElapsedMs(0);
-      return;
-    }
-    setLayout(null);
-    const dims = book.computePageSize(surface.current);
-    setPageWidth(dims.pageWidth);
-    setPageHeight(dims.pageHeight);
-    setContentHeight(dims.contentHeight);
-    const t0 = performance.now();
-    const l = await book.layoutChapter(chapter);
-    if (requestId !== requestIdRef.current) return;
-    setLayout(l);
-    setElapsedMs(performance.now() - t0);
-  }, [book, epub, chapterIndex, surface]);
+  const optionsRef = useRef4(options);
+  optionsRef.current = options;
+  const recompute = useCallback(
+    async (opts = {}) => {
+      const blank = opts.blank ?? true;
+      const o = optionsRef.current;
+      const requestId = ++requestIdRef.current;
+      const chapter = epub?.chapters[chapterIndex];
+      if (!(chapter && surface.current)) {
+        setLayout(null);
+        setPageWidth(0);
+        setPageHeight(0);
+        setContentHeight(0);
+        setElapsedMs(0);
+        return;
+      }
+      const captured = !blank && layoutRef.current ? o.capturePosition?.(layoutRef.current) ?? null : null;
+      pendingRestore.current = captured;
+      if (blank) setLayout(null);
+      const dims = book.computePageSize(surface.current, o.pageGeometry?.());
+      setPageWidth(dims.pageWidth);
+      setPageHeight(dims.pageHeight);
+      setContentHeight(dims.contentHeight);
+      const t0 = performance.now();
+      const l = await book.layoutChapter(chapter);
+      if (requestId !== requestIdRef.current) return;
+      layoutRef.current = l;
+      setLayout(l);
+      setElapsedMs(performance.now() - t0);
+    },
+    [book, epub, chapterIndex, surface]
+  );
   useLayoutEffect2(() => {
     requestIdRef.current++;
+    pendingRestore.current = null;
     setLayout(null);
     setPageWidth(0);
     setPageHeight(0);
@@ -1028,29 +1053,55 @@ function useChapterLayout(book, epub, chapterIndex, surface, options = {}) {
   }, [recompute]);
   useEffect2(() => {
     if (!enableResize) return;
+    const el = surface.current;
+    if (!el) return;
     let timer = null;
-    const onResize = () => {
-      if (!(surface.current && layoutRef.current)) return;
-      if (timer) clearTimeout(timer);
+    let observed = false;
+    const clear = () => {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    };
+    const scheduleReflow = (immediate) => {
+      clear();
+      if (immediate) {
+        void recompute({ blank: false });
+        return;
+      }
       timer = setTimeout(() => {
-        if (!(surface.current && layoutRef.current)) return;
-        const dims = book.computePageSize(surface.current);
-        setPageWidth(dims.pageWidth);
-        setPageHeight(dims.pageHeight);
-        setContentHeight(dims.contentHeight);
-        layoutRef.current.resize({
-          pageWidth: dims.pageWidth,
-          lineWidth: dims.contentHeight - book.getOptions().fontSize * 0.5
-        });
+        timer = null;
+        void recompute({ blank: false });
       }, resizeDebounce);
     };
-    window.addEventListener("resize", onResize);
+    if (typeof ResizeObserver !== "undefined") {
+      const observer = new ResizeObserver(() => {
+        const immediate = !observed;
+        observed = true;
+        scheduleReflow(immediate);
+      });
+      observer.observe(el);
+      return () => {
+        observer.disconnect();
+        clear();
+      };
+    }
+    const onWindowResize = () => scheduleReflow(false);
+    window.addEventListener("resize", onWindowResize);
     return () => {
-      window.removeEventListener("resize", onResize);
-      if (timer) clearTimeout(timer);
+      window.removeEventListener("resize", onWindowResize);
+      clear();
     };
-  }, [book, surface, enableResize, resizeDebounce]);
-  return { layout, pageWidth, pageHeight, contentHeight, elapsedMs, recompute };
+  }, [surface, enableResize, resizeDebounce, recompute]);
+  return {
+    layout,
+    pageWidth,
+    pageHeight,
+    contentHeight,
+    elapsedMs,
+    recompute,
+    pendingRestore
+  };
 }
 
 // src/useEpub.ts
@@ -1457,6 +1508,16 @@ function useSpread(layout, options = {}) {
     },
     [turnDuration]
   );
+  const setSpreadIndex = useCallback5((index) => {
+    if (!layoutRef.current) return;
+    if (turnTimerRef.current) {
+      clearTimeout(turnTimerRef.current);
+      turnTimerRef.current = null;
+    }
+    setTurning(false);
+    const max = Math.max(1, Math.ceil(layoutRef.current.totalPages / 2)) - 1;
+    setSpreadIdx(Math.max(0, Math.min(max, index)));
+  }, []);
   const next = useCallback5(() => goTo(spreadIdxRef.current + 1), [goTo]);
   const prev = useCallback5(() => goTo(spreadIdxRef.current - 1), [goTo]);
   useEffect5(() => {
@@ -1475,7 +1536,18 @@ function useSpread(layout, options = {}) {
     },
     []
   );
-  return { spreadIdx, spread, totalPages, totalSpreads, turning, next, prev, goTo, refresh };
+  return {
+    spreadIdx,
+    spread,
+    totalPages,
+    totalSpreads,
+    turning,
+    next,
+    prev,
+    goTo,
+    setSpread: setSpreadIndex,
+    refresh
+  };
 }
 
 // src/MejiroReader.tsx
@@ -1485,6 +1557,7 @@ function MejiroReaderInner(props, ref) {
   const dialectProp = "dialect" in props ? props.dialect : void 0;
   const {
     options = DEFAULT_BOOK_OPTIONS,
+    pageGeometry: pageGeometryProp,
     fonts,
     epub: epubProp,
     epubUrl,
@@ -1493,6 +1566,7 @@ function MejiroReaderInner(props, ref) {
     theme = "light",
     mode = "paginated",
     spreadMode = "double",
+    fit = "fill",
     enableSurfaceTap = true,
     fallback,
     fetchOptions,
@@ -1508,10 +1582,12 @@ function MejiroReaderInner(props, ref) {
     enableChapterNav = !bare,
     chapterNavMode = "select",
     enableSettings = !bare,
+    renderSettings,
     enableImageOverlay = false,
     enableStats = !bare,
     enableKeyboard = true,
     enablePageIndicator = !bare,
+    pageNumbers = "both",
     annotations,
     onLoad,
     onError,
@@ -1551,6 +1627,24 @@ function MejiroReaderInner(props, ref) {
     return () => observer.disconnect();
   }, [spreadMode]);
   const effectiveSingle = spreadMode === "single" || spreadMode === "auto" && autoSingle;
+  const resolvedGeometry = useMemo4(() => {
+    const columns = effectiveSingle ? 1 : 2;
+    if (fit !== "width") return { columns, ...pageGeometryProp };
+    return {
+      columns,
+      gutterOffset: 0,
+      headerOffset: 0,
+      maxHeight: Number.POSITIVE_INFINITY,
+      minWidth: 0,
+      minHeight: 0,
+      ...pageGeometryProp
+    };
+  }, [fit, pageGeometryProp, effectiveSingle]);
+  const surfaceAspect = useMemo4(() => {
+    const columns = effectiveSingle ? 1 : 2;
+    const aspect = resolvedGeometry?.aspect ?? DEFAULT_PAGE_GEOMETRY.aspect;
+    return `${columns} / ${aspect}`;
+  }, [effectiveSingle, resolvedGeometry]);
   const { book, options: bookOptions, setOptions } = useMejiroBook(options);
   const synthesizedEpub = useMemo4(() => {
     if (manuscriptProp === void 0) return null;
@@ -1575,7 +1669,18 @@ function MejiroReaderInner(props, ref) {
   useEffect6(() => {
     if (epubCtx.error) onErrorRef.current?.(epubCtx.error);
   }, [epubCtx.error]);
-  const layoutCtx = useChapterLayout(book, e, chapter, surfaceRef);
+  const pageGeometryRef = useRef9(resolvedGeometry);
+  pageGeometryRef.current = resolvedGeometry;
+  const curSpreadIdxRef = useRef9(0);
+  const spreadIdxPropRef = useRef9(spreadIdxProp);
+  spreadIdxPropRef.current = spreadIdxProp;
+  const layoutCtx = useChapterLayout(book, e, chapter, surfaceRef, {
+    pageGeometry: () => pageGeometryRef.current,
+    // Preserve the reading position across a reflow re-layout (size / option
+    // changes), but only in uncontrolled mode — when `spreadIdx` is controlled
+    // the host owns the position and the controlled-restore effect handles it.
+    capturePosition: (layout2) => spreadIdxPropRef.current != null ? null : layout2.anchorAt(curSpreadIdxRef.current, "right")
+  });
   const spreadChangedRef = useRef9(void 0);
   spreadChangedRef.current = (i) => {
     onSpreadChange?.(i);
@@ -1585,6 +1690,46 @@ function MejiroReaderInner(props, ref) {
     enableKeyboard,
     onChange: (i) => spreadChangedRef.current?.(i)
   });
+  curSpreadIdxRef.current = spreadCtx.spreadIdx;
+  const setSpreadRef = useRef9(spreadCtx.setSpread);
+  setSpreadRef.current = spreadCtx.setSpread;
+  useLayoutEffect4(() => {
+    const anchor = layoutCtx.pendingRestore.current;
+    if (!(anchor && layoutCtx.layout)) return;
+    layoutCtx.pendingRestore.current = null;
+    const loc = layoutCtx.layout.locateAnchor(anchor);
+    setSpreadRef.current(loc?.spreadIdx ?? 0);
+  }, [layoutCtx.layout]);
+  const optionsKey = [
+    bookOptions.fontFamily,
+    bookOptions.fontSize,
+    bookOptions.lineSpacing,
+    bookOptions.mode,
+    bookOptions.enableHanging
+  ].join("|");
+  const optionsKeyRef = useRef9(optionsKey);
+  const bookOptionsRef = useRef9(bookOptions);
+  bookOptionsRef.current = bookOptions;
+  const recomputeRef = useRef9(layoutCtx.recompute);
+  recomputeRef.current = layoutCtx.recompute;
+  useEffect6(() => {
+    if (optionsKeyRef.current === optionsKey) return;
+    optionsKeyRef.current = optionsKey;
+    const timer = setTimeout(() => {
+      void (async () => {
+        await setOptions({ ...bookOptionsRef.current });
+        await recomputeRef.current({ blank: false });
+      })();
+    }, 60);
+    return () => clearTimeout(timer);
+  }, [optionsKey, setOptions]);
+  const geometryKey = JSON.stringify(resolvedGeometry ?? null);
+  const geometryKeyRef = useRef9(geometryKey);
+  useEffect6(() => {
+    if (geometryKeyRef.current === geometryKey) return;
+    geometryKeyRef.current = geometryKey;
+    void recomputeRef.current({ blank: false });
+  }, [geometryKey]);
   const imageCtx = useMultiImageOverlay(layoutCtx.layout, spreadCtx.spreadIdx, {
     onUpdate: () => spreadCtx.refresh()
   });
@@ -1616,9 +1761,13 @@ function MejiroReaderInner(props, ref) {
   spreadGoToRef.current = spreadCtx.goTo;
   useEffect6(() => {
     if (spreadIdxProp == null) return;
-    if (spreadIdxProp === spreadCtx.spreadIdx) return;
     spreadGoToRef.current(spreadIdxProp);
-  }, [spreadIdxProp, spreadCtx.spreadIdx]);
+  }, [spreadIdxProp]);
+  useLayoutEffect4(() => {
+    const next = spreadIdxPropRef.current;
+    if (next == null || !layoutCtx.layout) return;
+    setSpreadRef.current(next);
+  }, [layoutCtx.layout]);
   const onChapter = useCallback6(
     (i) => {
       if (i === chapter) return;
@@ -1788,7 +1937,17 @@ function MejiroReaderInner(props, ref) {
   const layoutReady = e && spreadCtx.spread && layoutCtx.layout && layoutCtx.pageWidth > 0;
   const themeName = typeof theme === "string" ? theme : theme.name;
   const themeOverride = typeof theme === "string" ? void 0 : theme.override;
-  const themeStyle = themeOverride;
+  const themeStyle = useMemo4(() => {
+    const pad = pageGeometryProp?.padding;
+    const styleVars = {};
+    if (pad?.x != null) styleVars["--mejiro-page-pad-x"] = `${pad.x}px`;
+    if (pad?.y != null) styleVars["--mejiro-page-pad-y"] = `${pad.y}px`;
+    if (pad?.bottom != null) styleVars["--mejiro-page-pad-bottom"] = `${pad.bottom}px`;
+    if (fit === "width") styleVars["--mejiro-surface-aspect"] = surfaceAspect;
+    const hasVars = Object.keys(styleVars).length > 0;
+    if (!(themeOverride || hasVars)) return void 0;
+    return { ...themeOverride, ...styleVars };
+  }, [themeOverride, pageGeometryProp, fit, surfaceAspect]);
   const resolvedMessages = useI18n({ locale, messages });
   const effectiveSubtitle = subtitle ?? resolvedMessages.logoSubtitle;
   const defaultLogo = /* @__PURE__ */ jsxs10("div", { className: "mejiro-reader-logo", children: [
@@ -1846,15 +2005,22 @@ function MejiroReaderInner(props, ref) {
   const rightPage = currentSpread * 2 + 1;
   const leftPage = currentSpread * 2 + 2;
   const showLeft = spreadCtx.spread != null && leftPage <= spreadCtx.spread.totalPages;
+  const showRightNum = pageNumbers === "both" || pageNumbers === "right";
+  const showLeftNum = pageNumbers === "both" || pageNumbers === "left";
   return /* @__PURE__ */ jsx12(MejiroI18nProvider, { messages: resolvedMessages, children: /* @__PURE__ */ jsxs10(
     "div",
     {
-      className: `mejiro-reader${chromeHidden ? " mejiro-reader--chrome-hidden" : ""}`,
+      className: `mejiro-reader${chromeHidden ? " mejiro-reader--chrome-hidden" : ""}${fit === "width" ? " mejiro-reader--fit-width" : ""}`,
       "data-mejiro-theme": themeName,
       style: themeStyle,
       children: [
         header,
-        enableSettings && /* @__PURE__ */ jsx12(
+        enableSettings && (renderSettings ? /* @__PURE__ */ jsx12("div", { className: `mejiro-reader-settings-panel${settingsOpen ? " is-open" : ""}`, children: /* @__PURE__ */ jsx12("div", { className: "mejiro-reader-settings-inner", children: /* @__PURE__ */ jsx12("div", { className: "mejiro-reader-settings-content", children: renderSettings({
+          settings: editable,
+          update: setOptions,
+          open: settingsOpen,
+          toggle: () => setSettingsOpen((v) => !v)
+        }) }) }) }) : /* @__PURE__ */ jsx12(
           MejiroSettingsPanel,
           {
             open: settingsOpen,
@@ -1862,7 +2028,7 @@ function MejiroReaderInner(props, ref) {
             fonts,
             onChange: setOptions
           }
-        ),
+        )),
         /* @__PURE__ */ jsxs10("div", { className: `mejiro-reader-body${showChapterPanel ? " has-chapter-panel" : ""}`, children: [
           showChapterPanel && /* @__PURE__ */ jsx12(MejiroChapterNav, { epub: e, chapter, onChange: onChapter, variant: "panel" }),
           /* @__PURE__ */ jsxs10("div", { ref: surfaceRef, className: "mejiro-reader-surface", children: [
@@ -1900,10 +2066,13 @@ function MejiroReaderInner(props, ref) {
                 fontSize: bookOptions.fontSize,
                 lineSpacing: bookOptions.lineSpacing,
                 turning: spreadCtx.turning,
-                rightHeader: { title: runningTitleRight, pageNumber: rightPage },
+                rightHeader: {
+                  title: runningTitleRight,
+                  pageNumber: showRightNum ? rightPage : null
+                },
                 leftHeader: {
                   title: runningTitleLeft,
-                  pageNumber: showLeft ? leftPage : null
+                  pageNumber: showLeft && showLeftNum ? leftPage : null
                 },
                 images: imageCtx.currentImages,
                 indicator: enablePageIndicator ? /* @__PURE__ */ jsx12(
@@ -3618,7 +3787,7 @@ function useLibrary(options) {
 }
 
 // src/useManuscriptLayout.ts
-import { useCallback as useCallback15, useEffect as useEffect15, useLayoutEffect as useLayoutEffect4, useRef as useRef18, useState as useState17 } from "react";
+import { useCallback as useCallback15, useEffect as useEffect15, useLayoutEffect as useLayoutEffect5, useRef as useRef18, useState as useState17 } from "react";
 function useManuscriptLayout(book, chapter, surface, options = {}) {
   const dialect = options.dialect ?? "mejiro";
   const enableResize = options.enableResize ?? true;
@@ -3653,7 +3822,7 @@ function useManuscriptLayout(book, chapter, surface, options = {}) {
     setLayout(next);
     setElapsedMs(performance.now() - t0);
   }, [book, chapter, dialect, surface]);
-  useLayoutEffect4(() => {
+  useLayoutEffect5(() => {
     requestIdRef.current++;
     setLayout(null);
     setPageWidth(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libraz/mejiro-react",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "React components and hooks for mejiro — vertical text rendering, EPUB reader, and editor",
   "type": "module",
   "main": "./dist/index.js",
@@ -46,7 +46,7 @@
     "build": "tsup"
   },
   "dependencies": {
-    "@libraz/mejiro": "^0.5.0"
+    "@libraz/mejiro": "^0.6.0"
   },
   "peerDependencies": {
     "@types/react": ">=18",