@libraz/mejiro-react 0.9.0 → 0.9.2

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import * as react from 'react';
 import { ReactNode, CSSProperties, PointerEvent, TextareaHTMLAttributes, MutableRefObject, RefObject } from 'react';
 import { EpubBook, AssetResolver, EpubParseLimits, EditableEpub, ManuscriptDialect, EpubChapter, EditableEpubBook, EditableEpubSelection, AnnotatedParagraph, AddImageInput, EditableEpubImage, EpubExportOptions, EpubProjectMetadata, EpubProjectAsset, EpubProject } from '@libraz/mejiro/epub';
 export { EditableEpubSelection } from '@libraz/mejiro/epub';
-import { ChapterLayout, SpreadResult, BookOptions, ComputePageSizeOptions, InChapterAnchor, ReadingAnchor, ManuscriptChapter, PageResult, AnchorRect, AnchorRange, MejiroBook } from '@libraz/mejiro/book';
+import { ChapterLayout, SpreadResult, BookOptions, MejiroBookOptions, ComputePageSizeOptions, InChapterAnchor, ReadingAnchor, ManuscriptChapter, PageResult, AnchorRect, AnchorRange, MejiroBook } from '@libraz/mejiro/book';
 import { RenderPage } from '@libraz/mejiro/render';
 import { FontFamily, InlineAnnotation } from '@libraz/mejiro/browser';
 
@@ -32,6 +32,10 @@ declare function resolveMessages(locale: MejiroLocale | undefined, overrides: Pa
 /** Replace `{name}` placeholders in a template. */
 declare function format(template: string, vars: Record<string, string | number>): string;
 
+/**
+ * Layout of {@link MejiroChapterNav}: `'select'` is a compact dropdown,
+ * `'panel'` a chapter list with titles, headings and a text preview.
+ */
 type MejiroChapterNavVariant = 'select' | 'panel';
 /** Props for {@link MejiroChapterNav}. */
 interface MejiroChapterNavProps {
@@ -58,7 +62,7 @@ declare function MejiroChapterNav({ epub, chapter, onChange, variant, }: MejiroC
 interface MejiroDropZoneProps {
     /** File `accept` filter for the picker. @defaultValue '.epub' */
     accept?: string;
-    /** Validator. Defaults to `name.endsWith('.epub')`. */
+    /** Validator. Defaults to the `accept` filter, with extensions matched case-insensitively. */
     validateFile?: (file: File) => boolean;
     /** Called with the selected/dropped file. */
     onFile: (file: File) => void;
@@ -96,6 +100,7 @@ interface MejiroSettingsPanelProps {
  */
 declare function MejiroSettingsPanel({ open, settings, onChange, fonts, minFontSize, maxFontSize, }: MejiroSettingsPanelProps): ReactNode;
 
+/** Props for {@link MejiroEditor}. */
 interface MejiroEditorProps {
     /** URL fetched and loaded on mount. */
     epubUrl?: string;
@@ -152,7 +157,10 @@ interface MejiroEditorProps {
     onLoad?: (editor: EditableEpub) => void;
     /** Called after export completes. */
     onExport?: (buffer: ArrayBuffer) => void;
-    /** Called when loading or parsing an EPUB fails. */
+    /**
+     * Called when loading, image insertion or export fails. The error is also
+     * shown in the editor.
+     */
     onError?: (error: Error) => void;
 }
 /**
@@ -227,8 +235,9 @@ interface UseImageOverlayReturn {
  * with automatic text reflow via {@link ChapterLayout.syncImages}.
  *
  * While an overlay is active the exclusion is re-issued whenever `layout` is
- * replaced or `spreadIdx` changes, so a re-layout or a page turn never leaves
- * the overlay drawn without its matching text reflow.
+ * replaced, `spreadIdx` changes or `options.margin` changes, so a re-layout, a
+ * page turn or a new margin never leaves the overlay drawn without its matching
+ * text reflow.
  *
  * @param layout - Current chapter layout (or `null` if not yet loaded).
  * @param spreadIdx - Current spread index.
@@ -262,6 +271,10 @@ interface MejiroImageOverlayProps {
  */
 declare function MejiroImageOverlay({ rect, label, onOverlayPointerDown, onResizePointerDown, onClose, }: MejiroImageOverlayProps): ReactNode;
 
+/**
+ * Where {@link MejiroReader} places its chapter navigation: the header
+ * dropdown (`'select'`), the side chapter list (`'panel'`), both, or neither.
+ */
 type MejiroChapterNavMode = 'select' | 'panel' | 'both' | 'none';
 /**
  * Reading-flow mode for {@link MejiroReader}.
@@ -272,8 +285,9 @@ type MejiroReaderMode = 'paginated' | 'scroll';
 /**
  * Two-page vs single-page rendering of a spread.
  * - `double` — always render two pages (default).
- * - `single` — render only the right page, centered.
- * - `auto` — switch based on the surface aspect ratio (single when portrait).
+ * - `single` — render one page at a time, centered; spread indices count pages.
+ * - `auto` — switch based on the surface aspect ratio (single when portrait),
+ *   converting the index so the page on screen stays visible.
  */
 type MejiroSpreadMode = 'double' | 'single' | 'auto';
 /**
@@ -305,9 +319,13 @@ type MejiroTheme = MejiroThemeName | {
 };
 /** Reading position exposed by {@link MejiroReaderHandle.getReadingPosition}. */
 interface ReadingPosition {
+    /** Zero-based index of the current chapter. */
     chapter: number;
+    /** Zero-based index of the current spread within the chapter. */
     spreadIdx: number;
+    /** Number of pages in the current chapter's layout. */
     totalPages: number;
+    /** Number of spreads in the current chapter's layout. */
     totalSpreads: number;
 }
 /**
@@ -342,29 +360,33 @@ interface MejiroReaderHandle {
     next(): void;
     /** Go back one spread. */
     prev(): void;
-    /** Jump to a chapter (resets spread index to 0). */
+    /** Jump to a chapter (clamped to the book's chapters; resets spread index to 0). */
     goToChapter(index: number): void;
     /** Read the current reading position. */
     getReadingPosition(): ReadingPosition;
     /**
      * Navigate to a {@link ReadingAnchor}. If the chapter differs from the
      * current one, the chapter is switched first; once the new layout is ready
-     * the anchor is resolved and the matching spread is opened.
+     * the anchor is resolved and the matching spread is opened. A call made
+     * before the book has loaded is applied once it has.
      *
-     * Returns a promise that resolves once the spread has been applied. If
-     * another `goToAnchor` is invoked before the previous one settles, the
-     * earlier promise resolves immediately (superseded). Resolves on unmount.
+     * Returns a promise that resolves once the spread has been applied, or
+     * without moving when the anchor's chapter or position does not exist in the
+     * book. If another `goToAnchor` is invoked before the previous one settles,
+     * the earlier promise resolves immediately (superseded). Resolves on unmount.
      */
     goToAnchor(anchor: ReadingAnchor): Promise<void>;
     /**
-     * Returns the {@link ReadingAnchor} at the start of the current spread,
-     * or `null` if the layout is not ready.
+     * Returns the {@link ReadingAnchor} at the start of the text on the current
+     * spread, or `null` if the layout is not ready. When an image blocks every
+     * page of the spread, the anchor is where the text resumes after it; `null`
+     * again if none follows.
      */
     getAnchor(): ReadingAnchor | null;
     /**
      * Returns the half-open range of {@link ReadingAnchor}s visible on the
-     * current spread. `end` points at the start of the next spread (or the end
-     * of the chapter for the last spread).
+     * current spread. `end` points at the start of the text on the next spread
+     * that has any (or the end of the chapter when none does).
      */
     getVisibleRange(): {
         start: ReadingAnchor;
@@ -376,8 +398,9 @@ interface MejiroReaderHandle {
      *
      * Successive calls are coalesced into a single application; the returned
      * promise resolves once that application has settled. A failed application
-     * (typically a font that could not be loaded) is reported through
-     * {@link MejiroReaderProps.onError} rather than rejecting the promise.
+     * (such as a font that measures as a fallback under `strictFontCheck`) is
+     * reported through {@link MejiroReaderProps.onError} rather than rejecting
+     * the promise.
      */
     setOptions(partial: Partial<BookOptions>): Promise<void>;
     /**
@@ -413,8 +436,10 @@ interface MejiroReaderCommonProps {
      * ```ts
      * { ...DEFAULT_BOOK_OPTIONS, fontFamily: '"Noto Serif JP"', fontSize: 18 }
      * ```
+     *
+     * `strictFontCheck` is read once, when the reader mounts.
      */
-    options?: Partial<BookOptions>;
+    options?: Partial<MejiroBookOptions>;
     /**
      * Page-geometry overrides forwarded to `MejiroBook.computePageSize`. Use to
      * tune how the spread is sized inside the surface — most usefully to shrink
@@ -434,7 +459,9 @@ interface MejiroReaderCommonProps {
     /**
      * Controlled spread index. When supplied, the reader is driven by this
      * value and emits {@link MejiroReaderProps.onSpreadIdxChange} on user
-     * navigation. Combine with `useReadingPosition` for save/restore.
+     * navigation. A spread index does not survive reflow, so persist the
+     * reading position with `useReadingPosition` and the handle's
+     * `getAnchor` / `goToAnchor` instead.
      */
     spreadIdx?: number;
     /**
@@ -451,8 +478,10 @@ interface MejiroReaderCommonProps {
      */
     mode?: MejiroReaderMode;
     /**
-     * Spread layout. `double` (default) renders two pages; `single` renders
-     * only the right page; `auto` flips to `single` for portrait viewports.
+     * Spread layout. `double` (default) renders two pages; `single` renders one
+     * page at a time, and `spreadIdx`, `goToSpread`, `onSpreadIdxChange` and
+     * `spreadChanged` then count pages; `auto` flips to `single` for portrait
+     * viewports, keeping the page on screen visible.
      */
     spreadMode?: MejiroSpreadMode;
     /**
@@ -489,7 +518,7 @@ interface MejiroReaderCommonProps {
      * component directly, so hosts that accept them should tighten the
      * defaults here.
      */
-    limits?: EpubParseLimits;
+    limits?: Partial<EpubParseLimits>;
     /**
      * Custom EPUB fetcher used in place of the global `fetch`. Overrides
      * {@link fetchOptions} when set.
@@ -585,7 +614,8 @@ interface MejiroReaderCommonProps {
     onLoad?: (book: EpubBook) => void;
     /**
      * Called when loading or parsing an EPUB fails, and when applying an option
-     * change fails (typically a font that could not be loaded).
+     * change fails (such as a font that measures as a fallback under
+     * `strictFontCheck`; without it, a font that fails to load is not an error).
      */
     onError?: (error: Error) => void;
     /** Called when the chapter index changes. */
@@ -655,18 +685,31 @@ interface MejiroReaderManuscriptProps extends MejiroReaderCommonProps {
  * modes — TypeScript prevents passing more than one source at once.
  */
 type MejiroReaderProps = MejiroReaderControlledProps | MejiroReaderUrlProps | MejiroReaderFileProps | MejiroReaderManuscriptProps;
+/**
+ * Full-page EPUB reader. Composes the package's primitives into a working
+ * reader; features opt out via the `enableX` props or all chrome via `bare`.
+ * The `ref` exposes {@link MejiroReaderHandle} for imperative navigation.
+ */
 declare const MejiroReader: react.ForwardRefExoticComponent<MejiroReaderProps & react.RefAttributes<MejiroReaderHandle>>;
 
+/** One chapter of the manuscript being edited. */
 interface ManuscriptEditorChapter {
+    /** Stable identifier; survives reordering and title edits. */
     id: string;
+    /** Chapter title; an empty title falls back to the localized "untitled" label. */
     title: string;
+    /** Chapter body in the editor's manuscript notation. */
     body: string;
 }
 /** Autosave payload emitted by {@link MejiroManuscriptEditor}. */
 interface ManuscriptAutosaveDraft {
+    /** Book title as currently entered. */
     title: string;
+    /** Author name as currently entered. */
     author: string;
+    /** Selected cover image, or `null` when none is set. */
     cover: File | null;
+    /** Chapters in reading order, as plain (non-reactive) copies. */
     chapters: ManuscriptEditorChapter[];
 }
 /**
@@ -676,14 +719,23 @@ interface ManuscriptAutosaveDraft {
  * supplied here.
  */
 interface ManuscriptPreviewProps {
+    /** Header subtitle of the preview reader. */
     subtitle?: string;
+    /** Header title of the preview reader. */
     title?: string;
+    /** Where the preview places its chapter navigation. @defaultValue 'panel' */
     chapterNavMode?: 'select' | 'panel' | 'both' | 'none';
+    /** Show the preview header. */
     enableHeader?: boolean;
+    /** Show the preview chapter navigation. */
     enableChapterNav?: boolean;
+    /** Show the preview settings panel toggle. */
     enableSettings?: boolean;
+    /** Show the preview layout statistics. */
     enableStats?: boolean;
+    /** Enable arrow-key page turns in the preview. */
     enableKeyboard?: boolean;
+    /** Show the preview page indicator. */
     enablePageIndicator?: boolean;
     /** Book options forwarded to the embedded reader preview. */
     options?: Partial<BookOptions>;
@@ -698,6 +750,7 @@ interface ManuscriptPreviewProps {
      * to `true` to demo the fullscreen-reader behavior.
      */
     enableSurfaceTap?: boolean;
+    /** Render the preview without any reader chrome. */
     bare?: boolean;
 }
 /** Props for {@link MejiroManuscriptEditor}. */
@@ -861,6 +914,60 @@ interface MejiroPageViewProps {
  */
 declare function MejiroPageView({ result, fontFamily, lineSpacing, slotMode, className, style, }: MejiroPageViewProps): ReactNode;
 
+/** A single image overlay placed on a specific spread. */
+interface MultiImageItem {
+    /** Stable ID for the overlay (auto-assigned on add). */
+    id: string;
+    /** Position and size in pixels, relative to the right page. */
+    rect: ImageRect;
+}
+/** Options for {@link useMultiImageOverlay}. */
+interface UseMultiImageOverlayOptions {
+    /** Default image width. @defaultValue 120 */
+    defaultWidth?: number;
+    /** Default image height. @defaultValue 160 */
+    defaultHeight?: number;
+    /** Default x. @defaultValue 80 */
+    defaultX?: number;
+    /** Default y. @defaultValue 100 */
+    defaultY?: number;
+    /** Margin around each image, in pixels. Defaults to the book's font size. */
+    margin?: number;
+    /** Called after every reflow caused by adding/removing/moving an image. */
+    onUpdate?: (spread: SpreadResult) => void;
+}
+/** Return value of {@link useMultiImageOverlay}. */
+interface UseMultiImageOverlayReturn {
+    /**
+     * Map of all images keyed by spread index. A new map whenever the images or
+     * the margin they are applied with change, and a replacement layout has them
+     * before any view renders from it, so this map and the layout together key
+     * anything derived from the layout.
+     */
+    imagesBySpread: Map<number, MultiImageItem[]>;
+    /** Images on the current spread; a new array whenever `imagesBySpread` changes. */
+    currentImages: MultiImageItem[];
+    /** Whether any spread has at least one image. */
+    hasImages: boolean;
+    /** Add a new image on the current spread. */
+    addImage: (overrides?: Partial<ImageRect>) => MultiImageItem;
+    /** Remove the image with the given id. */
+    removeImage: (id: string) => void;
+    /** Replace an image's rectangle. */
+    updateImage: (id: string, rect: Partial<ImageRect>) => void;
+    /** Remove every image (or only those on `spreadIdx` if given). */
+    clearImages: (spreadIdx?: number) => void;
+    /** Pointer-down handler for the overlay body (drag). */
+    onOverlayPointerDown: (id: string, e: PointerEvent) => void;
+    /** Pointer-down handler for the resize handle. */
+    onResizePointerDown: (id: string, e: PointerEvent) => void;
+}
+/**
+ * React hook that manages multiple draggable/resizable image overlays
+ * per spread with automatic reflow via {@link ChapterLayout.setImages}.
+ */
+declare function useMultiImageOverlay(layout: ChapterLayout | null, spreadIdx: number, options?: UseMultiImageOverlayOptions): UseMultiImageOverlayReturn;
+
 /** Props for {@link MejiroScrollView}. */
 interface MejiroScrollViewProps {
     /** Layout containing the pages to render. */
@@ -891,6 +998,31 @@ interface MejiroScrollViewProps {
     scrollToPage?: number;
     /** Vertical gap between pages (px). @defaultValue 24 */
     pageGap?: number;
+    /**
+     * Selection rectangles to highlight. Compute via
+     * {@link ChapterLayout.selectionRects}; each entry is painted on the page its
+     * `pageIdx` addresses. An entry may carry a `color` fill.
+     */
+    selectionRects?: readonly (AnchorRect & {
+        color?: string;
+    })[];
+    /** Zero-based spread whose pages carry {@link MejiroScrollViewProps.images}. */
+    spreadIdx?: number;
+    /**
+     * Image overlays on the spread at {@link MejiroScrollViewProps.spreadIdx}.
+     * Each renders on the page whose area contains its centre (see
+     * `overlayPageSide`), matching {@link MejiroSpread}'s single-page routing.
+     * The layout reflows in place when its images change, so a new array here is
+     * also what re-reads the pages; `useMultiImageOverlay`'s `currentImages`
+     * provides one on every change.
+     */
+    images?: MultiImageItem[];
+    /** Pointer-down on an image overlay. */
+    onImagePointerDown?: (id: string, e: PointerEvent) => void;
+    /** Pointer-down on an image resize handle. */
+    onImageResizePointerDown?: (id: string, e: PointerEvent) => void;
+    /** Image overlay close button. */
+    onImageClose?: (id: string) => void;
 }
 /**
  * Continuous-scroll variant of {@link MejiroSpread}. Stacks every page in
@@ -898,7 +1030,7 @@ interface MejiroScrollViewProps {
  * detected via `IntersectionObserver` and reported through
  * {@link MejiroScrollViewProps.onVisiblePageChange}.
  */
-declare function MejiroScrollView({ layout, pageWidth, pageHeight, contentHeight, fontFamily, fontSize, lineSpacing, slotMode, onVisiblePageChange, scrollToPage, pageGap, }: MejiroScrollViewProps): ReactNode;
+declare function MejiroScrollView({ layout, pageWidth, pageHeight, contentHeight, fontFamily, fontSize, lineSpacing, slotMode, onVisiblePageChange, scrollToPage, pageGap, selectionRects, spreadIdx, images, onImagePointerDown, onImageResizePointerDown, onImageClose, }: MejiroScrollViewProps): ReactNode;
 
 /** Props for {@link MejiroSelectionLayer}. */
 interface MejiroSelectionLayerProps {
@@ -986,7 +1118,7 @@ interface MejiroShelfProps<T = unknown> {
     currentId?: string;
     /** Called when the user picks a volume. */
     onSelect?: (volume: VolumeInfo<T>) => void;
-    /** Heading shown above the grid. @defaultValue 'Library' */
+    /** Heading shown above the grid. Defaults to the active message catalog's `shelfTitle`. */
     title?: string;
 }
 /**
@@ -995,55 +1127,6 @@ interface MejiroShelfProps<T = unknown> {
  */
 declare function MejiroShelf<T = unknown>({ volumes, currentId, onSelect, title, }: MejiroShelfProps<T>): ReactNode;
 
-/** A single image overlay placed on a specific spread. */
-interface MultiImageItem {
-    /** Stable ID for the overlay (auto-assigned on add). */
-    id: string;
-    /** Position and size in pixels, relative to the right page. */
-    rect: ImageRect;
-}
-/** Options for {@link useMultiImageOverlay}. */
-interface UseMultiImageOverlayOptions {
-    /** Default image width. @defaultValue 120 */
-    defaultWidth?: number;
-    /** Default image height. @defaultValue 160 */
-    defaultHeight?: number;
-    /** Default x. @defaultValue 80 */
-    defaultX?: number;
-    /** Default y. @defaultValue 100 */
-    defaultY?: number;
-    /** Margin around each image, in pixels. Defaults to the book's font size. */
-    margin?: number;
-    /** Called after every reflow caused by adding/removing/moving an image. */
-    onUpdate?: (spread: SpreadResult) => void;
-}
-/** Return value of {@link useMultiImageOverlay}. */
-interface UseMultiImageOverlayReturn {
-    /** Map of all images keyed by spread index. */
-    imagesBySpread: Map<number, MultiImageItem[]>;
-    /** Images on the current spread. */
-    currentImages: MultiImageItem[];
-    /** Whether any spread has at least one image. */
-    hasImages: boolean;
-    /** Add a new image on the current spread. */
-    addImage: (overrides?: Partial<ImageRect>) => MultiImageItem;
-    /** Remove the image with the given id. */
-    removeImage: (id: string) => void;
-    /** Replace an image's rectangle. */
-    updateImage: (id: string, rect: Partial<ImageRect>) => void;
-    /** Remove every image (or only those on `spreadIdx` if given). */
-    clearImages: (spreadIdx?: number) => void;
-    /** Pointer-down handler for the overlay body (drag). */
-    onOverlayPointerDown: (id: string, e: PointerEvent) => void;
-    /** Pointer-down handler for the resize handle. */
-    onResizePointerDown: (id: string, e: PointerEvent) => void;
-}
-/**
- * React hook that manages multiple draggable/resizable image overlays
- * per spread with automatic reflow via {@link ChapterLayout.setImages}.
- */
-declare function useMultiImageOverlay(layout: ChapterLayout | null, spreadIdx: number, options?: UseMultiImageOverlayOptions): UseMultiImageOverlayReturn;
-
 /** Props for {@link MejiroSpread}. */
 interface MejiroSpreadProps {
     /** Spread data to render. */
@@ -1066,7 +1149,11 @@ interface MejiroSpreadProps {
     rightHeader?: PageHeaderData;
     /** Header data for the left page. */
     leftHeader?: PageHeaderData;
-    /** Image overlays on the current spread. */
+    /**
+     * Image overlays on the current spread, relative to the right page. With
+     * {@link MejiroSpreadProps.singlePage}, only those whose centre lies on the
+     * page shown are drawn.
+     */
     images?: MultiImageItem[];
     /**
      * Force slot-mode rendering on both pages. When omitted, each page falls
@@ -1117,11 +1204,16 @@ interface MejiroSpreadProps {
      */
     onSelectionChange?: (range: AnchorRange | null) => void;
     /**
-     * Hide the left page and render only the right page (centered). Use this
-     * for portrait viewports or when a reader explicitly opts into single-page
-     * mode.
+     * Render only one page of the spread (centered), chosen by
+     * {@link MejiroSpreadProps.singleSide}. Use this for portrait viewports or
+     * when a reader explicitly opts into single-page mode.
      */
     singlePage?: boolean;
+    /**
+     * Page of the spread shown when {@link MejiroSpreadProps.singlePage} is set
+     * (`useSpread` reports it as `singleSide`). @defaultValue 'right'
+     */
+    singleSide?: 'right' | 'left';
     /**
      * Called when the user makes a quick swipe gesture on the spread.
      * `direction === 'next'` means the user swiped from right to left (the
@@ -1132,10 +1224,11 @@ interface MejiroSpreadProps {
     onSurfaceTap?: () => void;
 }
 /**
- * Renders a two-page spread with the book frame, page chrome, navigation
- * zones, and image overlays. Used inside `mejiro-reader-surface`.
+ * Renders a two-page spread (or one page of it in single-page mode) with the
+ * book frame, page chrome, navigation zones, and image overlays. Used inside
+ * `mejiro-reader-surface`.
  */
-declare function MejiroSpread({ spread, pageWidth, pageHeight, contentHeight, fontFamily, fontSize, lineSpacing, turning, rightHeader, leftHeader, images, slotMode, renderPageHeader, indicator, onPrev, onNext, onImagePointerDown, onImageResizePointerDown, onImageClose, anchorAtCoord, spreadIdx, selectionRects, onSelectionChange, singlePage, onSwipe, onSurfaceTap, }: MejiroSpreadProps): ReactNode;
+declare function MejiroSpread({ spread, pageWidth, pageHeight, contentHeight, fontFamily, fontSize, lineSpacing, turning, rightHeader, leftHeader, images, slotMode, renderPageHeader, indicator, onPrev, onNext, onImagePointerDown, onImageResizePointerDown, onImageClose, anchorAtCoord, spreadIdx, selectionRects, onSelectionChange, singlePage, singleSide, onSwipe, onSurfaceTap, }: MejiroSpreadProps): ReactNode;
 
 /** Props for {@link MejiroStats}. */
 interface MejiroStatsProps {
@@ -1165,9 +1258,9 @@ interface MejiroTocProps {
     currentAnchor?: ReadingAnchor | null;
     /** Show a search input that filters chapter titles. @defaultValue false */
     searchable?: boolean;
-    /** Heading displayed above the list. @defaultValue 'Contents' */
+    /** Heading displayed above the list. Defaults to the active message catalog's `tocTitle`. */
     title?: string;
-    /** Placeholder shown in the search input. @defaultValue 'Search chapters…' */
+    /** Placeholder shown in the search input. Defaults to the active message catalog's `tocSearchPlaceholder`. */
     searchPlaceholder?: string;
     /** Called when the user picks a chapter. */
     onSelect?: (chapter: number) => void;
@@ -1247,17 +1340,26 @@ interface UseChapterLayoutOptions {
      */
     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.
+     * Capture the reading position from the outgoing layout, just before a
+     * **reflow** (non-blank) re-layout replaces it. The anchor is held in
+     * `pendingRestore` until the new layout is in place, then handed to
+     * `restorePosition` when one is given. Return `null` to skip preservation.
+     * Never called for blank (content-change) re-layouts, which start at spread 0.
      */
     capturePosition?: (layout: ChapterLayout) => InChapterAnchor | null;
+    /**
+     * Apply an anchor captured by `capturePosition` to the new layout, e.g. by
+     * locating it and jumping to its spread. Called once the new layout is in
+     * place — after it commits, before paint — and `pendingRestore` is cleared
+     * first. Without it, consume `pendingRestore` yourself.
+     */
+    restorePosition?: (layout: ChapterLayout, position: InChapterAnchor) => void;
+    /**
+     * Called once when a layout of the current source fails, whichever path
+     * started it (source change, resize or `recompute`); a superseded layout
+     * reports nothing. When supplied, `recompute` resolves instead of rejecting.
+     */
+    onError?: (error: Error) => void;
 }
 /** Options for {@link UseChapterLayoutReturn.recompute}. */
 interface RecomputeOptions {
@@ -1271,8 +1373,11 @@ interface RecomputeOptions {
 }
 /** Page dimensions returned by {@link MejiroBook.computePageSize}. */
 interface PageDimensions {
+    /** Width of one page, in CSS pixels. */
     pageWidth: number;
+    /** Height of one page, in CSS pixels. */
     pageHeight: number;
+    /** Height of the text area inside a page, in CSS pixels. */
     contentHeight: number;
 }
 /** Return value of {@link useChapterLayout}. */
@@ -1287,12 +1392,16 @@ interface UseChapterLayoutReturn {
     contentHeight: number;
     /** Most recent layout time (ms). */
     elapsedMs: number;
-    /** Force a fresh layout computation. */
+    /**
+     * Force a fresh layout computation. A failure goes to `onError` when one is
+     * supplied; otherwise the returned promise rejects.
+     */
     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`.
+     * Anchor captured by `capturePosition` before the most recent reflow,
+     * awaiting restoration into the new layout. `restorePosition`, when given,
+     * consumes it; otherwise read it once the new layout is in place and set it
+     * back to `null`.
      *
      * Declared as a `MutableRefObject` because consumers are expected to write to
      * it — `@types/react@18` models `RefObject.current` as read-only, so a
@@ -1311,13 +1420,16 @@ interface UseChapterLayoutReturn {
  * 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}.
+ * Size and option changes lay the chapter out again rather than calling
+ * `ChapterLayout.resize()`, so page geometry is re-derived from the surface and
+ * the book's current options. The book replays the line-breaking hints it
+ * already derived for the chapter, so a reflow never re-runs the analyzer.
+ * Because each re-layout yields a new {@link ChapterLayout} object (resetting
+ * any downstream spread index to 0), the reading position is carried across
+ * reflows by {@link UseChapterLayoutOptions.capturePosition},
+ * {@link UseChapterLayoutOptions.restorePosition} and
+ * {@link UseChapterLayoutReturn.pendingRestore}, identically in the Vue
+ * composable.
  *
  * @param book - The book instance to lay out with.
  * @param epub - The current parsed EPUB.
@@ -1327,6 +1439,7 @@ interface UseChapterLayoutReturn {
  */
 declare function useChapterLayout(book: MejiroBook, epub: EpubBook | null, chapterIndex: number, surface: RefObject<HTMLElement | null>, options?: UseChapterLayoutOptions): UseChapterLayoutReturn;
 
+/** Options for {@link useEditableEpub}. */
 interface UseEditableEpubOptions {
     /** URL fetched and loaded on mount. */
     defaultUrl?: string;
@@ -1342,32 +1455,58 @@ interface UseEditableEpubOptions {
      * fields keep their `DEFAULT_EPUB_PARSE_LIMITS` value.
      */
     limits?: Partial<EpubParseLimits>;
+    /**
+     * Resolves URL-only images into bytes when {@link UseEditableEpubReturn.exportEpub}
+     * packages the book. An `assetResolver` passed to `exportEpub` itself wins.
+     */
+    assetResolver?: AssetResolver;
 }
+/** Return value of {@link useEditableEpub}. */
 interface UseEditableEpubReturn {
+    /** Loaded editor, or `null` before any load. */
     editor: EditableEpub | null;
+    /** The editor's live document, or `null` before any load. */
     book: EditableEpubBook | null;
+    /** Snapshot of `book` re-cloned on every edit, for feeding a preview reader. */
     previewBook: EditableEpubBook | null;
+    /** Whether a load is in progress. */
     loading: boolean;
+    /** Whether an export is in progress. */
     exporting: boolean;
+    /** Last load error, if any. */
     error: Error | null;
+    /** Counter bumped on every load, edit, undo and redo. */
     revision: number;
+    /** Undo / redo availability, or `null` before any load. */
     history: {
         canUndo: boolean;
         canRedo: boolean;
         depth: number;
         redoDepth: number;
     } | null;
+    /** Paragraph targeted by the editing commands. */
     selection: EditableEpubSelection;
+    /** The paragraph at `selection`, or `null` when there is none. */
     selectedParagraph: AnnotatedParagraph | null;
+    /** Moves the selection, clamped to the loaded book. */
     setSelection: (selection: EditableEpubSelection) => void;
+    /** Loads an EPUB from an in-memory buffer. */
     loadBuffer: (buffer: ArrayBuffer) => Promise<EditableEpub | null>;
+    /** Loads an EPUB from a {@link File}. */
     loadFile: (file: File) => Promise<EditableEpub | null>;
+    /** Fetches and loads an EPUB; a non-2xx response is reported as an error. */
     loadUrl: (url: string) => Promise<EditableEpub | null>;
+    /** Replaces the selected paragraph's text and, optionally, its inline annotations. */
     updateParagraph: (text: string, inlineAnnotations?: readonly InlineAnnotation[]) => void;
+    /** Replaces the selected paragraph's inline annotations. */
     setInlineAnnotations: (inlineAnnotations: readonly InlineAnnotation[]) => void;
+    /** Inserts an image into the selected chapter. */
     addImage: (image: AddImageInput | EditableEpubImage) => void;
+    /** Reverts the last edit. Returns `false` when there is nothing to undo. */
     undo: () => boolean;
+    /** Re-applies the last undone edit. Returns `false` when there is nothing to redo. */
     redo: () => boolean;
+    /** Packages the edited document as an EPUB buffer. */
     exportEpub: (options?: EpubExportOptions) => Promise<ArrayBuffer | null>;
 }
 /** Headless editable-EPUB state for custom proofreading/editor UIs. */
@@ -1375,11 +1514,11 @@ declare function useEditableEpub(options?: UseEditableEpubOptions): UseEditableE
 
 /** Options for {@link useEpub}. */
 interface UseEpubOptions {
-    /** URL fetched on mount. A non-OK response is treated as "no default". */
+    /** URL fetched on mount. */
     defaultUrl?: string;
     /** Called after a successful load. */
     onLoad?: (book: EpubBook) => void;
-    /** Called when a load fails. Non-OK URL responses are still treated as "no default". */
+    /** Called when a load fails, including a non-2xx URL response. */
     onError?: (error: Error) => void;
     /**
      * Extra options merged into the `fetch` call when loading by URL. Useful
@@ -1424,8 +1563,11 @@ declare function useEpub(options?: UseEpubOptions): UseEpubReturn;
 
 /** One chapter of the manuscript draft the hook keeps in React state. */
 interface EpubProjectChapterDraft {
+    /** Stable chapter identifier. */
     id: string;
+    /** Chapter title. */
     title: string;
+    /** Chapter body in the manuscript notation. */
     body: string;
 }
 /** Options for {@link useEpubProject}. */
@@ -1465,19 +1607,32 @@ interface UseEpubProjectOptions {
 }
 /** State and actions returned by {@link useEpubProject}. */
 interface UseEpubProjectReturn {
+    /** Current book metadata. */
     metadata: EpubProjectMetadata;
+    /** Current chapter drafts, in reading order. */
     chapters: EpubProjectChapterDraft[];
+    /** Index of the chapter being edited. */
     selectedChapter: number;
+    /** The chapter at `selectedChapter`, or `null` when there is none. */
     currentChapter: EpubProjectChapterDraft | null;
     /** Current cover asset, or `null` when the project has no cover. */
     cover: EpubProjectAsset | null;
     /** Current non-cover assets, in registration order. */
     assets: EpubProjectAsset[];
+    /** Parsed EPUB built from the current project, refreshed after each debounced change. */
     previewBook: EpubBook | null;
+    /** Last preview build failure, if any. */
     previewError: Error | null;
+    /** Whether a preview build is pending or running. */
     previewing: boolean;
+    /**
+     * Merges `patch` into the metadata. A missing or blank `identifier` keeps the
+     * current one.
+     */
     setMetadata: (patch: Partial<EpubProjectMetadata>) => void;
+    /** Replaces every chapter; an empty list becomes one generated chapter. */
     setChapters: (chapters: EpubProjectChapterDraft[]) => void;
+    /** Selects a chapter, clamped to the chapter range. */
     setSelectedChapter: (index: number) => void;
     /**
      * Replaces the cover asset, or drops it when passed `null`. The new cover is
@@ -1489,8 +1644,14 @@ interface UseEpubProjectReturn {
      * project, so URL-only entries reach `assetResolver` at export time.
      */
     setAssets: (assets: EpubProjectAsset[]) => void;
+    /** Merges `patch` into the chapter at `index`. */
     patchChapter: (index: number, patch: Partial<EpubProjectChapterDraft>) => void;
+    /** Appends a chapter (generated defaults fill omitted fields) and selects it. */
     addChapter: (chapter?: Partial<EpubProjectChapterDraft>) => void;
+    /**
+     * Removes the chapter at `index` (the selected one by default); the last chapter is never
+     * removed.
+     */
     removeChapter: (index?: number) => void;
     /**
      * Moves a chapter from `from` to `to`. An out-of-range `from` selects no
@@ -1498,7 +1659,9 @@ interface UseEpubProjectReturn {
      * the same contract as `EpubProject.reorderChapters()`.
      */
     reorderChapters: (from: number, to: number) => void;
+    /** Builds an `EpubProject` from the current state. */
     buildProject: () => EpubProject;
+    /** Packages the current project as an EPUB buffer. */
     exportEpub: () => Promise<ArrayBuffer>;
 }
 /** Headless manuscript-to-EPUB project state for custom authoring UIs. */
@@ -1526,14 +1689,24 @@ interface UseManuscriptDraftOptions<TAutosave = ManuscriptEditorChapter[]> {
 }
 /** Return value of {@link useManuscriptDraft}. */
 interface UseManuscriptDraftReturn {
+    /** Current chapters, in reading order. */
     chapters: ManuscriptEditorChapter[];
     /** Index of the chapter currently being edited. */
     selected: number;
+    /** Selects a chapter, clamped to the chapter range. */
     setSelected(index: number): void;
+    /**
+     * Replaces every chapter; an empty list becomes one generated chapter. The
+     * selected chapter is kept by id when it survives.
+     */
     setChapters(chapters: ManuscriptEditorChapter[]): void;
+    /** Merges `patch` into the chapter at `index`. */
     patchChapter(index: number, patch: Partial<ManuscriptEditorChapter>): void;
+    /** Appends a chapter (generated defaults fill omitted fields) and selects it. */
     addChapter(chapter?: Partial<ManuscriptEditorChapter>): void;
+    /** Removes the chapter at `index`; the last remaining chapter is never removed. */
     removeChapter(index: number): void;
+    /** Moves the chapter at `from` to `to`, keeping the same chapter selected. */
     reorderChapters(from: number, to: number): void;
     /** Last autosave failure, if any. */
     autosaveError: Error | null;
@@ -1558,13 +1731,26 @@ interface UseManuscriptLayoutOptions {
     /** Debounce window (ms) applied to size-triggered re-flows. @defaultValue 120 */
     resizeDebounce?: number;
     /**
-     * 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 UseManuscriptLayoutReturn.pendingRestore} and should be
-     * applied once the new layout commits. Return `null` to skip preservation.
-     * Never called for blank (content-change) re-layouts.
+     * Capture the reading position from the outgoing layout, just before a
+     * **reflow** (non-blank) re-layout replaces it. The anchor is held in
+     * `pendingRestore` until the new layout is in place, then handed to
+     * `restorePosition` when one is given. Return `null` to skip preservation.
+     * Never called for blank (content-change) re-layouts, which start at spread 0.
      */
     capturePosition?: (layout: ChapterLayout) => InChapterAnchor | null;
+    /**
+     * Apply an anchor captured by `capturePosition` to the new layout, e.g. by
+     * locating it and jumping to its spread. Called once the new layout is in
+     * place — after it commits, before paint — and `pendingRestore` is cleared
+     * first. Without it, consume `pendingRestore` yourself.
+     */
+    restorePosition?: (layout: ChapterLayout, position: InChapterAnchor) => void;
+    /**
+     * Called once when a layout of the current source fails, whichever path
+     * started it (source change, resize or `recompute`); a superseded layout
+     * reports nothing. When supplied, `recompute` resolves instead of rejecting.
+     */
+    onError?: (error: Error) => void;
 }
 /** Options for {@link UseManuscriptLayoutReturn.recompute}. */
 interface ManuscriptRecomputeOptions {
@@ -1578,8 +1764,11 @@ interface ManuscriptRecomputeOptions {
 }
 /** Page dimensions returned by {@link MejiroBook.computePageSize}. */
 interface ManuscriptPageDimensions {
+    /** Width of one page, in CSS pixels. */
     pageWidth: number;
+    /** Height of one page, in CSS pixels. */
     pageHeight: number;
+    /** Height of the text area inside a page, in CSS pixels. */
     contentHeight: number;
 }
 /** Return value of {@link useManuscriptLayout}. */
@@ -1594,12 +1783,16 @@ interface UseManuscriptLayoutReturn {
     contentHeight: number;
     /** Most recent layout time (ms). */
     elapsedMs: number;
-    /** Force a fresh layout computation. */
+    /**
+     * Force a fresh layout computation. A failure goes to `onError` when one is
+     * supplied; otherwise the returned promise rejects.
+     */
     recompute: (opts?: ManuscriptRecomputeOptions) => 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`.
+     * Anchor captured by `capturePosition` before the most recent reflow,
+     * awaiting restoration into the new layout. `restorePosition`, when given,
+     * consumes it; otherwise read it once the new layout is in place and set it
+     * back to `null`.
      */
     pendingRestore: MutableRefObject<InChapterAnchor | null>;
 }
@@ -1619,8 +1812,10 @@ interface UseManuscriptLayoutReturn {
  * is computed (no blank flash) and yields a new {@link ChapterLayout} object,
  * which resets any downstream spread index to 0; the reading position is
  * preserved across such reflows via
- * {@link UseManuscriptLayoutOptions.capturePosition} and
- * {@link UseManuscriptLayoutReturn.pendingRestore}.
+ * {@link UseManuscriptLayoutOptions.capturePosition},
+ * {@link UseManuscriptLayoutOptions.restorePosition} and
+ * {@link UseManuscriptLayoutReturn.pendingRestore}, identically in the Vue
+ * composable.
  */
 declare function useManuscriptLayout(book: MejiroBook, chapter: ManuscriptChapter | null, surface: RefObject<HTMLElement | null>, options?: UseManuscriptLayoutOptions): UseManuscriptLayoutReturn;
 
@@ -1636,11 +1831,10 @@ interface UseMejiroBookOptions {
      */
     debounceMs?: number;
     /**
-     * Called when applying options to the book fails — typically a font that
-     * could not be loaded. When supplied, failures are reported here and the
-     * promise returned by {@link UseMejiroBookReturn.setOptions} resolves instead
-     * of rejecting, so fire-and-forget callers cannot leave an unhandled
-     * rejection behind.
+     * Called when applying options to the book fails. When supplied, failures are
+     * reported here and the promise returned by
+     * {@link UseMejiroBookReturn.setOptions} resolves instead of rejecting, so
+     * fire-and-forget callers cannot leave an unhandled rejection behind.
      */
     onError?: (error: Error) => void;
 }
@@ -1648,7 +1842,10 @@ interface UseMejiroBookOptions {
 interface UseMejiroBookReturn {
     /** The managed {@link MejiroBook} instance. Stable across renders. */
     book: MejiroBook;
-    /** Reactive snapshot of the current options. */
+    /**
+     * Reactive snapshot of the current options. Once the latest application
+     * settles it holds what the book applied, so a rejected change rolls back.
+     */
     options: Readonly<BookOptions>;
     /**
      * Update options on the underlying book and the snapshot. The snapshot is
@@ -1667,7 +1864,7 @@ interface UseMejiroBookReturn {
  * @param initial - Initial book options (passed to the {@link MejiroBook} constructor).
  * @param options - Behavior overrides (debouncing, error reporting).
  */
-declare function useMejiroBook(initial: BookOptions, options?: UseMejiroBookOptions): UseMejiroBookReturn;
+declare function useMejiroBook(initial: MejiroBookOptions, options?: UseMejiroBookOptions): UseMejiroBookReturn;
 
 /** Minimal storage interface required by {@link useReadingPosition}. */
 type ReadingPositionStorage = MejiroStorage;
@@ -1707,9 +1904,10 @@ interface UseReadingPositionReturn {
  * const { position, save } = useReadingPosition({ key: `mejiro:${bookId}` });
  * const reader = useRef<MejiroReaderHandle>(null);
  *
+ * // Restore once per mount: depending on `position` would re-run after every save().
  * useEffect(() => {
  *   if (position) reader.current?.goToAnchor(position);
- * }, [position]);
+ * }, []);
  *
  * useEffect(() => {
  *   const off = reader.current?.subscribe('spreadChanged', () => {
@@ -1732,33 +1930,53 @@ interface UseSpreadOptions {
     enableKeyboard?: boolean;
     /** Page-turn animation duration in ms. @defaultValue 180 */
     turnDuration?: number;
+    /**
+     * Show one page at a time: the navigation index then counts pages instead
+     * of two-page spreads. Toggling it converts the index so the page on
+     * screen stays visible. @defaultValue false
+     */
+    single?: boolean;
     /** Called when the spread index changes (after the turn animation midpoint). */
     onChange?: (spreadIdx: number) => void;
 }
 /** Return value of {@link useSpread}. */
 interface UseSpreadReturn {
-    /** Current spread index. */
+    /** Current navigation index: a page index in single mode, a spread index otherwise. */
     spreadIdx: number;
-    /** Current spread result, or `null` until the layout is ready. */
+    /** Layout spread holding the visible page(s), or `null` until the layout is ready. */
     spread: SpreadResult | null;
-    /** Total number of pages. */
+    /** First page shown, in reading order. */
+    firstPage: number;
+    /** Index of {@link UseSpreadReturn.spread} in the layout (`ChapterLayout.getSpread`). */
+    layoutSpreadIdx: number;
+    /** Side of {@link UseSpreadReturn.spread} shown in single mode; `null` in double mode. */
+    singleSide: 'right' | 'left' | null;
+    /** Total number of pages, as of {@link UseSpreadReturn.spread}. */
     totalPages: number;
-    /** Total number of two-page spreads. */
+    /** Number of navigation positions: pages in single mode, two-page spreads otherwise. */
     totalSpreads: number;
     /** Whether the turn animation is currently in flight. */
     turning: boolean;
-    /** Advance one spread forward. */
+    /** Advance one position (page or spread) forward. */
     next: () => void;
-    /** Go back one spread. */
+    /** Go back one position. */
     prev: () => void;
-    /** Jump to an arbitrary spread index (clamped). */
+    /** Jump to an arbitrary navigation 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
+     * Set the navigation 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;
+    /** Navigation index that shows the given page index. */
+    indexOfPage: (pageIdx: number) => number;
+    /**
+     * Anchor at the start of the text shown at navigation index `index`. A page an
+     * image blocks entirely holds no text, so the anchor then comes from the next
+     * page that does, even past `index`; `null` when no page from there on holds text.
+     */
+    anchorAt: (index: number) => InChapterAnchor | null;
     /** Manually refresh `spread` from `layout` at the current index. */
     refresh: () => void;
 }