@libraz/mejiro-react 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,6 +1,496 @@
+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, ComputePageSizeOptions, InChapterAnchor, ReadingAnchor, ManuscriptChapter, AnchorRect, AnchorRange, MejiroBook } from '@libraz/mejiro/book';
 import { RenderPage } from '@libraz/mejiro/render';
-import { CSSProperties, ReactNode, PointerEvent } from 'react';
-import { PageResult, ChapterLayout, SpreadResult } from '@libraz/mejiro/book';
+import { FontFamily, InlineAnnotation } from '@libraz/mejiro/browser';
+
+/** All UI strings rendered by the bundled React components. */
+interface MejiroMessages {
+    /** Logo subtitle. */
+    readonly logoSubtitle: string;
+    /** Header "Open" button label. */
+    readonly openButton: string;
+    /** Header "Settings" button label. */
+    readonly settingsButton: string;
+    /** Header "Image" overlay button label. */
+    readonly imageButton: string;
+    /** ARIA label for removing an image overlay. */
+    readonly imageRemoveButton: string;
+    /** Loading-state body text. */
+    readonly loading: string;
+    /** ARIA label for the previous-spread nav zone. */
+    readonly prevSpread: string;
+    /** ARIA label for the next-spread nav zone. */
+    readonly nextSpread: string;
+    /** Settings panel group title — Font. */
+    readonly settingsFont: string;
+    /** Settings panel font-size label. */
+    readonly settingsSize: string;
+    /** Settings panel "decrease font size" button. */
+    readonly settingsSizeDown: string;
+    /** Settings panel "increase font size" button. */
+    readonly settingsSizeUp: string;
+    /** Settings panel group title — Layout. */
+    readonly settingsLayout: string;
+    /** Settings panel kinsoku label. */
+    readonly settingsKinsoku: string;
+    /** Settings panel hanging-punctuation label. */
+    readonly settingsHanging: string;
+    /** Settings panel line-spacing label. */
+    readonly settingsLineSpacing: string;
+    /** Settings panel "strict" kinsoku option. */
+    readonly settingsStrict: string;
+    /** Settings panel "loose" kinsoku option. */
+    readonly settingsLoose: string;
+    /** Settings panel "on" toggle option. */
+    readonly toggleOn: string;
+    /** Settings panel "off" toggle option. */
+    readonly toggleOff: string;
+    /** Drop zone primary text. */
+    readonly dropZoneTitle: string;
+    /** Drop zone secondary hint. */
+    readonly dropZoneHint: string;
+    /** TOC heading. */
+    readonly tocTitle: string;
+    /** TOC search placeholder. */
+    readonly tocSearchPlaceholder: string;
+    /** TOC empty-results template. Placeholder `{query}` is replaced. */
+    readonly tocEmpty: string;
+    /** Shelf heading. */
+    readonly shelfTitle: string;
+    /** Generic chapter-N template. Placeholder `{n}` is replaced. */
+    readonly chapterN: string;
+    /** Aria-live announcement template. Placeholders: `{spread}`, `{total}`. */
+    readonly spreadAnnouncement: string;
+    /** Embedded EPUB editor preview subtitle. */
+    readonly editorPreviewSubtitle: string;
+    /** EPUB editor panel title. */
+    readonly editorTitle: string;
+    /** EPUB editor empty-state title. */
+    readonly editorNoBookLoaded: string;
+    /** EPUB editor paragraph list section label. */
+    readonly editorParagraphs: string;
+    /** EPUB editor proofread section label. */
+    readonly editorProofread: string;
+    /** EPUB editor apply-text button label. */
+    readonly editorApplyText: string;
+    /** EPUB editor ruby section label. */
+    readonly editorRuby: string;
+    /** EPUB editor ruby usage hint. */
+    readonly editorRubyHint: string;
+    /** EPUB editor ruby selected-range template. Placeholders: `{start}`, `{end}`, `{count}`. */
+    readonly editorRubyRange: string;
+    /** EPUB editor ruby input placeholder. */
+    readonly editorRubyPlaceholder: string;
+    /** EPUB editor apply-ruby button label. */
+    readonly editorApplyRuby: string;
+    /** EPUB editor image section label. */
+    readonly editorImages: string;
+    /** EPUB editor insert-image button label. */
+    readonly editorInsertImageAfterParagraph: string;
+    /** EPUB editor export button label. */
+    readonly editorExportEpub: string;
+    /** Manuscript editor preview subtitle. */
+    readonly manuscriptPreviewSubtitle: string;
+    /** Manuscript editor panel title. */
+    readonly manuscriptTitle: string;
+    /** Manuscript editor ruby notation hint. */
+    readonly manuscriptRubyHint: string;
+    /** Manuscript editor metadata section label. */
+    readonly manuscriptMetadata: string;
+    /** Manuscript editor chapters section label. */
+    readonly manuscriptChapters: string;
+    /** Manuscript editor draft section label. */
+    readonly manuscriptDraft: string;
+    /** Manuscript editor cover chooser label. */
+    readonly manuscriptChooseCoverImage: string;
+    /** Manuscript editor default book title. */
+    readonly manuscriptDefaultTitle: string;
+    /** Manuscript editor default chapter title template. Placeholder `{n}` is replaced. */
+    readonly manuscriptDefaultChapterTitle: string;
+    /** Manuscript editor default draft body. */
+    readonly manuscriptDefaultBody: string;
+    /** Generic untitled fallback. */
+    readonly untitled: string;
+    /** Manuscript editor add-chapter button label. */
+    readonly manuscriptAddChapter: string;
+    /** Manuscript editor remove-chapter button label. */
+    readonly manuscriptRemove: string;
+    /** Manuscript editor emphasis-dots button label. */
+    readonly manuscriptEmphasisDots: string;
+    /** Manuscript editor tate-chu-yoko button label. */
+    readonly manuscriptTcy: string;
+    /** Manuscript editor emphasis button label. */
+    readonly manuscriptEm: string;
+    /** Manuscript editor strong button label. */
+    readonly manuscriptStrong: string;
+    /** ARIA label for the chapter drag handle. Placeholders: `{title}`. */
+    readonly manuscriptReorderHandle: string;
+}
+/** Built-in English catalog (the default). */
+declare const enMessages: MejiroMessages;
+/** Built-in Japanese catalog. */
+declare const jaMessages: MejiroMessages;
+/** Built-in locale identifiers. */
+type MejiroLocale = 'en' | 'ja';
+/** Provider that scopes a message catalog to its descendants. */
+declare function MejiroI18nProvider({ locale, messages, children, }: {
+    locale?: MejiroLocale;
+    messages?: Partial<MejiroMessages>;
+    children: ReactNode;
+}): ReactNode;
+/** Options for {@link useI18n}. */
+interface UseI18nOptions {
+    /** Built-in locale to use as the base catalog. @defaultValue 'en' */
+    locale?: MejiroLocale;
+    /** Overrides merged on top of the built-in catalog. */
+    messages?: Partial<MejiroMessages>;
+}
+/**
+ * Returns the resolved `MejiroMessages` catalog. With no arguments the
+ * catalog provided by the nearest {@link MejiroI18nProvider} is returned;
+ * passing `locale` / `messages` resolves a catalog without context.
+ */
+declare function useI18n(options?: UseI18nOptions): MejiroMessages;
+/** Build a catalog without invoking React (useful in plain modules). */
+declare function resolveMessages(locale: MejiroLocale | undefined, overrides: Partial<MejiroMessages> | undefined): MejiroMessages;
+/** Replace `{name}` placeholders in a template. */
+declare function format(template: string, vars: Record<string, string | number>): string;
+
+type MejiroChapterNavVariant = 'select' | 'panel';
+/** Props for {@link MejiroChapterNav}. */
+interface MejiroChapterNavProps {
+    /** EPUB to list chapters from. */
+    epub: EpubBook;
+    /** Current chapter index. */
+    chapter: number;
+    /** Called when a new chapter is picked. */
+    onChange: (chapter: number) => void;
+    /** Visual treatment for the chapter list. @defaultValue 'select' */
+    variant?: MejiroChapterNavVariant;
+}
+/**
+ * Chapter selector for an {@link EpubBook}.
+ *
+ * @deprecated Prefer {@link MejiroToc} for new code. `MejiroToc` adds
+ * search and current-anchor highlighting and renders the same data with a
+ * more accessible markup. `MejiroChapterNav` remains supported for the
+ * `<select>` variant and existing `MejiroReader` integration.
+ */
+declare function MejiroChapterNav({ epub, chapter, onChange, variant, }: MejiroChapterNavProps): ReactNode;
+
+/** Props for {@link MejiroDropZone}. */
+interface MejiroDropZoneProps {
+    /** File `accept` filter for the picker. @defaultValue '.epub' */
+    accept?: string;
+    /** Validator. Defaults to `name.endsWith('.epub')`. */
+    validateFile?: (file: File) => boolean;
+    /** Called with the selected/dropped file. */
+    onFile: (file: File) => void;
+    /** Custom body content (replaces default icon/text). */
+    children?: ReactNode;
+    /** Additional class name for the root element. */
+    className?: string;
+    /** Additional inline styles. */
+    style?: CSSProperties;
+}
+/**
+ * Drop zone for EPUB files. Combines drag-and-drop with a click-to-open file picker.
+ */
+declare function MejiroDropZone({ accept, validateFile, onFile, children, className, style, }: MejiroDropZoneProps): ReactNode;
+
+/** A font choice shown in the settings panel. */
+interface FontChoice {
+    /** CSS `font-family` value applied to the book. */
+    value: string;
+    /** Human-readable label. */
+    label: string;
+}
+/** Subset of {@link BookOptions} editable from the panel. */
+type EditableSettings = Pick<BookOptions, 'fontFamily' | 'fontSize' | 'lineSpacing' | 'mode' | 'enableHanging'>;
+/** Props for {@link MejiroSettingsPanel}. */
+interface MejiroSettingsPanelProps {
+    /** Whether the panel is expanded. */
+    open: boolean;
+    /** Current editable settings. */
+    settings: EditableSettings;
+    /** Called when a setting changes. */
+    onChange: (next: EditableSettings) => void;
+    /** Font choices. */
+    fonts?: FontChoice[];
+    /** Min font size. @defaultValue 10 */
+    minFontSize?: number;
+    /** Max font size. @defaultValue 48 */
+    maxFontSize?: number;
+}
+/**
+ * Reader settings panel: font, size, kinsoku mode, hanging punctuation, line spacing.
+ */
+declare function MejiroSettingsPanel({ open, settings, onChange, fonts, minFontSize, maxFontSize, }: MejiroSettingsPanelProps): ReactNode;
+
+interface MejiroEditorProps {
+    /** URL fetched and loaded on mount. */
+    epubUrl?: string;
+    /** Font choices passed to the preview reader. */
+    fonts?: FontChoice[];
+    /**
+     * Allow editing paragraph text (the "Proofread" section).
+     * @defaultValue true
+     */
+    enableProofread?: boolean;
+    /**
+     * Allow editing ruby annotations (the "Ruby" section).
+     * @defaultValue true
+     */
+    enableRuby?: boolean;
+    /**
+     * Allow inserting images into the EPUB (the "Images" section).
+     * @defaultValue true
+     */
+    enableImages?: boolean;
+    /**
+     * Allow exporting the edited EPUB. SaaS publishers can disable this to
+     * restrict downloads (e.g. server-side export only).
+     * @defaultValue true
+     */
+    enableExport?: boolean;
+    /**
+     * Called before the export buffer is offered as a download. Return `false`
+     * (or a `Promise<false>`) to suppress the browser download — useful for
+     * uploading the buffer to a backend instead.
+     */
+    onBeforeExport?: (buffer: ArrayBuffer) => boolean | undefined | Promise<boolean | undefined>;
+    /**
+     * Declarative export policy. When set, supersedes `onBeforeExport` for
+     * download control and threads watermark / encrypt transforms through the
+     * export pipeline.
+     */
+    exportPolicy?: MejiroExportPolicy;
+    /**
+     * Resolves URL-only image assets ({@link EditableImageAsset.url} set, `data`
+     * unset) into bytes at export time. Forwarded to `editor.export()`. Use this
+     * to keep large image bytes off the client during editing and only fetch
+     * them once when the EPUB is assembled — e.g. signed S3 URLs that require
+     * custom auth headers.
+     */
+    assetResolver?: AssetResolver;
+    /** Called after an EPUB is loaded into the editor. */
+    onLoad?: (editor: EditableEpub) => void;
+    /** Called after export completes. */
+    onExport?: (buffer: ArrayBuffer) => void;
+    /** Called when loading or parsing an EPUB fails. */
+    onError?: (error: Error) => void;
+}
+/**
+ * Declarative restrictions on the export pipeline. Mejiro applies the
+ * transforms in this order: `watermark` (modifies the EPUB in-place) →
+ * `encrypt` (replaces the buffer with the result) → `allowDownload` (skips
+ * the browser download when `false`).
+ */
+interface MejiroExportPolicy {
+    /**
+     * If `false`, the EPUB buffer is still produced (and `onExport` still fires)
+     * but no browser download is triggered. Use when shipping the buffer
+     * elsewhere (e.g. uploading to a backend).
+     * @defaultValue true
+     */
+    allowDownload?: boolean;
+    /**
+     * Transforms the EPUB buffer before it is offered for download. Typically
+     * a server round-trip that returns a DRM-wrapped EPUB.
+     */
+    encrypt?: (buffer: ArrayBuffer) => ArrayBuffer | Promise<ArrayBuffer>;
+    /**
+     * Embeds a visible watermark string into the EPUB. Implemented by writing
+     * the text as XHTML metadata; renderers may surface it differently.
+     */
+    watermark?: {
+        text: string;
+        opacity?: number;
+    };
+}
+/** EPUB editor UI for proofreading, ruby edits, image insertion, and export. */
+declare function MejiroEditor({ epubUrl, fonts, enableProofread, enableRuby, enableImages, enableExport, onBeforeExport, exportPolicy, assetResolver, onLoad, onExport, onError, }: MejiroEditorProps): ReactNode;
+
+/** Rectangle describing an image overlay position and size. */
+interface ImageRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Options for {@link useImageOverlay}. */
+interface UseImageOverlayOptions {
+    /** Default image width in pixels. @defaultValue 120 */
+    defaultWidth?: number;
+    /** Default image height in pixels. @defaultValue 160 */
+    defaultHeight?: number;
+    /** Default x position. @defaultValue 80 */
+    defaultX?: number;
+    /** Default y position. @defaultValue 100 */
+    defaultY?: number;
+    /** Margin around the image in pixels. Defaults to the book's font size. */
+    margin?: number;
+}
+/** Return value of {@link useImageOverlay}. */
+interface UseImageOverlayReturn {
+    /** Current image rectangle, or `null` if no overlay is active. */
+    imageRect: ImageRect | null;
+    /** Whether an image overlay is currently active. */
+    hasImage: boolean;
+    /** Toggle the image overlay on/off. */
+    toggleImage: () => void;
+    /** Pointer-down handler for the overlay body (initiates drag). */
+    onOverlayPointerDown: (e: PointerEvent) => void;
+    /** Pointer-down handler for the resize handle. */
+    onResizePointerDown: (e: PointerEvent) => void;
+}
+/**
+ * React hook that manages a draggable/resizable image overlay
+ * with automatic text reflow via {@link ChapterLayout.syncImages}.
+ *
+ * @param layout - Current chapter layout (or `null` if not yet loaded).
+ * @param spreadIdx - Current spread index.
+ * @param onUpdate - Called with the updated {@link SpreadResult} after every reflow.
+ * @param options - Default dimensions and position for the overlay.
+ *
+ * @example
+ * ```tsx
+ * const { imageRect, hasImage, toggleImage, onOverlayPointerDown, onResizePointerDown } =
+ *   useImageOverlay(layout, spreadIdx, setSpread);
+ * ```
+ */
+declare function useImageOverlay(layout: ChapterLayout | null, spreadIdx: number, onUpdate: (spread: SpreadResult) => void, options?: UseImageOverlayOptions): UseImageOverlayReturn;
+
+/** Props for {@link MejiroImageOverlay}. */
+interface MejiroImageOverlayProps {
+    /** Position and size of the overlay (px). */
+    rect: ImageRect;
+    /** Label inside the overlay. @defaultValue `messages.imageButton` */
+    label?: string;
+    /** Pointer-down on the body (drag). */
+    onOverlayPointerDown?: (e: PointerEvent) => void;
+    /** Pointer-down on the resize handle. */
+    onResizePointerDown?: (e: PointerEvent) => void;
+    /** Triggered when the close button is pressed. */
+    onClose?: () => void;
+}
+/**
+ * Decorative image placeholder overlay with drag/resize affordances.
+ * Pair the pointer handlers with {@link useImageOverlay} or {@link useMultiImageOverlay}.
+ */
+declare function MejiroImageOverlay({ rect, label, onOverlayPointerDown, onResizePointerDown, onClose, }: MejiroImageOverlayProps): ReactNode;
+
+interface ManuscriptEditorChapter {
+    id: string;
+    title: string;
+    body: string;
+}
+/**
+ * Subset of {@link MejiroReader} props that the manuscript editor passes
+ * through to the live preview. Properties driven by the editor itself
+ * (`manuscript`, `fonts`, `chapter`, `onChapterChange`) are ignored if
+ * supplied here.
+ */
+interface ManuscriptPreviewProps {
+    subtitle?: string;
+    title?: string;
+    chapterNavMode?: 'select' | 'panel' | 'both' | 'none';
+    enableHeader?: boolean;
+    enableChapterNav?: boolean;
+    enableSettings?: boolean;
+    enableStats?: boolean;
+    enableKeyboard?: boolean;
+    enablePageIndicator?: boolean;
+    /**
+     * Toggle the surface-tap chrome-hide behavior of the embedded reader.
+     * Defaults to `false` here (the editor's preview is part of a side-by-side
+     * authoring workflow where tap-to-hide would surprise the author). Set
+     * to `true` to demo the fullscreen-reader behavior.
+     */
+    enableSurfaceTap?: boolean;
+    bare?: boolean;
+}
+interface MejiroManuscriptEditorProps {
+    /** Font choices passed to the preview reader. */
+    fonts?: FontChoice[];
+    /**
+     * Title. When `onTitleChange` is supplied, this is the controlled value
+     * (changes propagate from parent to the input). Otherwise it is the
+     * initial value and the editor manages its own title state.
+     */
+    title?: string;
+    /** Called whenever the title input changes. Enables controlled mode. */
+    onTitleChange?: (title: string) => void;
+    /**
+     * Author. Controlled when `onAuthorChange` is supplied; otherwise treated
+     * as the initial value.
+     */
+    author?: string;
+    /** Called whenever the author input changes. Enables controlled mode. */
+    onAuthorChange?: (author: string) => void;
+    /**
+     * Cover image. Controlled when `onCoverChange` is supplied; otherwise
+     * treated as the initial cover. Setting `null` clears the cover.
+     */
+    cover?: File | null;
+    /** Called whenever the cover changes. Enables controlled mode. */
+    onCoverChange?: (cover: File | null) => void;
+    /** Initial chapters. */
+    chapters?: ManuscriptEditorChapter[];
+    /**
+     * Called whenever the chapter draft settles (debounced by
+     * {@link MejiroManuscriptEditorProps.autosaveDelay}). Use to persist drafts
+     * to localStorage, IndexedDB, or upload to a server.
+     */
+    onAutosave?: (chapters: ManuscriptEditorChapter[]) => void | Promise<void>;
+    /** Autosave debounce in milliseconds. @defaultValue 800 */
+    autosaveDelay?: number;
+    /**
+     * Props forwarded to the embedded {@link MejiroReader} preview. Lets
+     * hosts customize subtitle / chapterNavMode / etc.; `manuscript`, `fonts`,
+     * `chapter`, and `onChapterChange` remain driven by the editor.
+     */
+    previewProps?: ManuscriptPreviewProps;
+    /**
+     * Resolves URL-only project assets (e.g. covers/illustrations registered as
+     * `{ url, ... }`) into bytes at export time. Forwarded to `project.export()`
+     * so authors can register signed-URL references without holding raw bytes
+     * client-side until publish.
+     */
+    assetResolver?: AssetResolver;
+    /** Called after export completes. */
+    onExport?: (buffer: ArrayBuffer) => void;
+}
+/** Manuscript-to-EPUB editor for author drafts from posting sites. */
+declare function MejiroManuscriptEditor({ fonts, title: titleProp, onTitleChange, author: authorProp, onAuthorChange, cover: coverProp, onCoverChange, chapters: initialChapters, onAutosave, autosaveDelay, previewProps, assetResolver, onExport, }: MejiroManuscriptEditorProps): ReactNode;
+
+/** Props for {@link MejiroNotationHighlighter}. */
+interface MejiroNotationHighlighterProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'onChange'> {
+    /** Source manuscript text. */
+    value: string;
+    /** Called whenever the textarea content changes. */
+    onChange: (next: string) => void;
+    /** Manuscript notation dialect. @defaultValue `'mejiro'` */
+    dialect?: ManuscriptDialect;
+    /** Class applied to the wrapper element. */
+    wrapperClassName?: string;
+    /** Inline style on the wrapper element. */
+    wrapperStyle?: CSSProperties;
+}
+/**
+ * Textarea with a notation-highlight overlay. The overlay sits *behind* the
+ * textarea and tints the background of manuscript notation tokens (ruby,
+ * emphasis dots, tate-chu-yoko, em / strong, links, footnotes) so authors can
+ * see at a glance which characters carry notation.
+ *
+ * The textarea is fully interactive; selection, undo / redo, and the
+ * browser-native caret are unaffected. Notation kinds are exposed via
+ * `data-token` attributes on the overlay spans so hosts can restyle them via
+ * CSS (`.mejiro-notation-token[data-token="ruby"]` etc.).
+ */
+declare const MejiroNotationHighlighter: react.ForwardRefExoticComponent<MejiroNotationHighlighterProps & react.RefAttributes<HTMLTextAreaElement>>;
 
 /** Props for the MejiroPage component. */
 interface MejiroPageProps {
@@ -19,12 +509,22 @@ interface MejiroPageProps {
  */
 declare function MejiroPage({ page, className, style }: MejiroPageProps): ReactNode;
 
+/** Props for {@link MejiroPageIndicator}. */
+interface MejiroPageIndicatorProps {
+    /** Current spread (1-based). */
+    current: number;
+    /** Total number of spreads. */
+    total: number;
+}
+/** Displays "current / total" spread position under the book. */
+declare function MejiroPageIndicator({ current, total }: MejiroPageIndicatorProps): ReactNode;
+
 /** Props for the MejiroPageView component. */
 interface MejiroPageViewProps {
     /** Page result from {@link ChapterLayout.getSpread} or {@link ChapterLayout.getPage}. */
     result: PageResult;
     /** CSS font family for slot-based rendering (used when images are present). */
-    fontFamily?: string;
+    fontFamily?: FontFamily;
     /** Line spacing multiplier for slot-based rendering (used when images are present). */
     lineSpacing?: number;
     /**
@@ -53,54 +553,1189 @@ interface MejiroPageViewProps {
  */
 declare function MejiroPageView({ result, fontFamily, lineSpacing, slotMode, className, style, }: MejiroPageViewProps): ReactNode;
 
-/** Rectangle describing an image overlay position and size. */
-interface ImageRect {
-    x: number;
-    y: number;
-    w: number;
-    h: number;
+type MejiroChapterNavMode = 'select' | 'panel' | 'both' | 'none';
+/**
+ * Reading-flow mode for {@link MejiroReader}.
+ * - `paginated` — two-page spread with page-turn animation (default).
+ * - `scroll` — every page in the chapter stacked in a vertical scroll view.
+ */
+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).
+ */
+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';
+/**
+ * Theme configuration for the reader. Either a preset name, or an object
+ * with a preset and an `override` map of CSS custom properties that take
+ * precedence over the preset values.
+ */
+type MejiroTheme = MejiroThemeName | {
+    name: MejiroThemeName;
+    override?: Record<string, string>;
+};
+/** Reading position exposed by {@link MejiroReaderHandle.getReadingPosition}. */
+interface ReadingPosition {
+    chapter: number;
+    spreadIdx: number;
+    totalPages: number;
+    totalSpreads: number;
 }
-/** Options for {@link useImageOverlay}. */
-interface UseImageOverlayOptions {
-    /** Default image width in pixels. @defaultValue 120 */
+/**
+ * Event payloads emitted by {@link MejiroReaderHandle.subscribe}.
+ *
+ * Each property maps an event name to its listener signature.
+ */
+interface MejiroReaderEventMap {
+    /** Fires after the current spread index changes. */
+    spreadChanged: (payload: {
+        chapter: number;
+        spreadIdx: number;
+    }) => void;
+    /** Fires when a turn animation begins (before the new spread is shown). */
+    turnStart: (payload: {
+        from: number;
+    }) => void;
+    /** Fires after a turn animation completes (the new spread is now shown). */
+    turnEnd: (payload: {
+        to: number;
+    }) => void;
+    /** Fires when the reader reaches the last spread of the current chapter. */
+    chapterFinished: (payload: {
+        chapter: number;
+    }) => void;
+}
+/** Imperative handle returned by `ref={...}` on {@link MejiroReader}. */
+interface MejiroReaderHandle {
+    /** Jump to a specific spread (0-based, clamped to [0, totalSpreads − 1]). */
+    goToSpread(index: number): void;
+    /** Advance one spread forward. */
+    next(): void;
+    /** Go back one spread. */
+    prev(): void;
+    /** Jump to a chapter (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.
+     *
+     * 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.
+     */
+    goToAnchor(anchor: ReadingAnchor): Promise<void>;
+    /**
+     * Returns the {@link ReadingAnchor} at the start of the current spread,
+     * or `null` if the layout is not ready.
+     */
+    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).
+     */
+    getVisibleRange(): {
+        start: ReadingAnchor;
+        end: ReadingAnchor;
+    } | null;
+    /**
+     * Updates book options at runtime. Same shape as {@link MejiroBook.setOptions}
+     * — font / size changes re-measure and re-layout asynchronously.
+     */
+    setOptions(partial: Partial<BookOptions>): Promise<void>;
+    /**
+     * Subscribes to a reader lifecycle event. Returns a function that
+     * detaches the listener.
+     */
+    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 {
+    /**
+     * Initial book options. Optional — defaults to {@link DEFAULT_BOOK_OPTIONS}
+     * (`serif` 16px, line spacing 1.8, strict kinsoku, hanging punctuation on).
+     * Spread the defaults to tweak only a few:
+     *
+     * ```ts
+     * { ...DEFAULT_BOOK_OPTIONS, fontFamily: '"Noto Serif JP"', fontSize: 18 }
+     * ```
+     */
+    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[];
+    /**
+     * Controlled chapter index. When omitted, the reader manages its own
+     * chapter state and resets to 0 on EPUB change.
+     */
+    chapter?: number;
+    /**
+     * 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.
+     */
+    spreadIdx?: number;
+    /**
+     * Visual theme preset, or `{ name, override }` to layer custom
+     * CSS variables on top of a preset. @defaultValue 'light'
+     *
+     * The selected name is reflected as `data-mejiro-theme` on the reader
+     * root, which the bundled CSS uses to swap palettes.
+     */
+    theme?: MejiroTheme;
+    /**
+     * Reading-flow mode. `paginated` (default) shows one spread at a time;
+     * `scroll` stacks every page in the chapter inside a vertical scroller.
+     */
+    mode?: MejiroReaderMode;
+    /**
+     * Spread layout. `double` (default) renders two pages; `single` renders
+     * 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
+     * shows them. @defaultValue true
+     */
+    enableSurfaceTap?: boolean;
+    /**
+     * Static fallback rendered while the layout is still hydrating. Pair with
+     * {@link renderEpubStatic} to ship server-rendered vertical text that
+     * search engines and slow connections can see before the client reader
+     * is ready.
+     */
+    fallback?: ReactNode;
+    /**
+     * Extra options merged into the EPUB `fetch` call (URL mode). Useful for
+     * sending bearer tokens or cookies.
+     */
+    fetchOptions?: RequestInit;
+    /**
+     * Custom EPUB fetcher used in place of the global `fetch`. Overrides
+     * {@link fetchOptions} when set.
+     */
+    fetchEpub?: (url: string) => Promise<ArrayBuffer>;
+    /**
+     * Built-in locale for UI strings (`'en'` / `'ja'`). Pair with `messages`
+     * to override individual strings. @defaultValue 'en'
+     */
+    locale?: MejiroLocale;
+    /**
+     * Partial override of the message catalog. Merged on top of the catalog
+     * selected by `locale`. Useful for projects that ship their own UI strings
+     * without re-implementing every label.
+     */
+    messages?: Partial<MejiroMessages>;
+    /** Header title text. @defaultValue 'mejiro' */
+    title?: string;
+    /** Header subtitle. @defaultValue `messages.logoSubtitle` */
+    subtitle?: string;
+    /**
+     * Replaces the default logo block (title + subtitle). Pass `null` to hide
+     * the logo while keeping the rest of the header. To remove the entire
+     * header, use `enableHeader={false}`.
+     */
+    logo?: ReactNode;
+    /**
+     * Shorthand for a chrome-less reader. When `true`, the defaults for
+     * `enableHeader`, `enableChapterNav`, `enableSettings`, `enableStats`, and
+     * `enablePageIndicator` flip from `true` to `false`. Explicitly-passed
+     * enable* props still win, so you can opt parts back in.
+     * @defaultValue false
+     */
+    bare?: boolean;
+    /** Show the built-in header. @defaultValue `!bare` */
+    enableHeader?: boolean;
+    /**
+     * Show the drop zone affordance. SaaS-style readers should keep this off
+     * (the host controls which EPUB is delivered); set true to accept
+     * user-supplied books.
+     * @defaultValue false
+     */
+    enableDropZone?: boolean;
+    /** Show the chapter selector in the header. @defaultValue `!bare` */
+    enableChapterNav?: boolean;
+    /**
+     * Where to render the built-in chapter navigation.
+     * @defaultValue 'select'
+     */
+    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` */
+    enableStats?: boolean;
+    /** Bind ArrowLeft/ArrowRight to navigation. @defaultValue true */
+    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
+     * rectangles via `ChapterLayout.selectionRects` and drawn on top of the
+     * page content. Pair with {@link useAnnotations} for persistence, or pass
+     * any shape that satisfies `{ chapter, start, end }`.
+     */
+    annotations?: ReadonlyArray<{
+        chapter: number;
+        start: InChapterAnchor;
+        end: InChapterAnchor;
+        color?: string;
+    }>;
+    /** Called after a successful EPUB load. */
+    onLoad?: (book: EpubBook) => void;
+    /** Called when loading or parsing an EPUB fails. */
+    onError?: (error: Error) => void;
+    /** Called when the chapter index changes. */
+    onChapterChange?: (chapter: number) => void;
+    /** Called when the spread index changes (alias: `onSpreadIdxChange`). */
+    onSpreadChange?: (spreadIdx: number) => void;
+    /** Called when the spread index changes — pair with the `spreadIdx` prop for controlled use. */
+    onSpreadIdxChange?: (spreadIdx: number) => void;
+    /**
+     * Called when the reader leaves a spread. Receives the anchor of the
+     * spread that was just left and the dwell time in milliseconds (computed
+     * via `performance.now()`). Useful for engagement analytics.
+     */
+    onPageRead?: (anchor: ReadingAnchor, dwellMs: number) => void;
+    /**
+     * Called when the reader reaches the last spread of a chapter. Same
+     * trigger as the `chapterFinished` event on {@link MejiroReaderHandle.subscribe}.
+     */
+    onChapterCompleted?: (chapter: number) => void;
+}
+/**
+ * Controlled-source variant: render a pre-parsed `EpubBook`. Pass `null`
+ * to render an empty reader (e.g. while the book is still loading on the host).
+ */
+interface MejiroReaderControlledProps extends MejiroReaderCommonProps {
+    /** Pre-parsed EPUB. Cannot be combined with `epubUrl` / `manuscript`. */
+    epub: EpubBook | null;
+    epubUrl?: never;
+    manuscript?: never;
+}
+/**
+ * URL-source variant: the reader fetches and parses the EPUB itself.
+ * Use this for "just open this book" scenarios.
+ */
+interface MejiroReaderUrlProps extends MejiroReaderCommonProps {
+    /** EPUB URL fetched on mount. Cannot be combined with `epub` / `manuscript`. */
+    epubUrl: string;
+    epub?: never;
+    manuscript?: never;
+}
+/**
+ * File-source variant: the reader exposes its drop zone / file picker.
+ * Neither `epub` nor `epubUrl` is supplied — useful for free-form viewers
+ * that accept user-supplied books.
+ */
+interface MejiroReaderFileProps extends MejiroReaderCommonProps {
+    epub?: never;
+    epubUrl?: never;
+    manuscript?: never;
+}
+/**
+ * Manuscript-source variant: render manuscript chapters directly without an
+ * EPUB ZIP round-trip. Designed for live preview in custom manuscript editors;
+ * each chapter body is split into paragraphs on blank lines and run through
+ * {@link parseManuscript} before layout.
+ */
+interface MejiroReaderManuscriptProps extends MejiroReaderCommonProps {
+    /** Manuscript chapters to render. Cannot be combined with `epub` / `epubUrl`. */
+    manuscript: readonly ManuscriptChapter[];
+    /** Manuscript notation dialect. @defaultValue `'mejiro'` */
+    dialect?: ManuscriptDialect;
+    epub?: never;
+    epubUrl?: never;
+}
+/**
+ * Props for {@link MejiroReader}. Discriminated union of the four source
+ * modes — TypeScript prevents passing more than one source at once.
+ */
+type MejiroReaderProps = MejiroReaderControlledProps | MejiroReaderUrlProps | MejiroReaderFileProps | MejiroReaderManuscriptProps;
+declare const MejiroReader: react.ForwardRefExoticComponent<MejiroReaderProps & react.RefAttributes<MejiroReaderHandle>>;
+
+/** Props for {@link MejiroScrollView}. */
+interface MejiroScrollViewProps {
+    /** Layout containing the pages to render. */
+    layout: ChapterLayout;
+    /** Page width in px. */
+    pageWidth: number;
+    /** Page height in px. */
+    pageHeight: number;
+    /** Content area height (px). */
+    contentHeight: number;
+    /** CSS font family applied to the content. */
+    fontFamily?: FontFamily;
+    /** Font size override (px). */
+    fontSize?: number;
+    /** Line spacing multiplier. */
+    lineSpacing?: number;
+    /** Force slot-based rendering on every page. */
+    slotMode?: boolean;
+    /**
+     * Visible page index reported to the parent as the user scrolls. The page
+     * with the largest intersection with the viewport is treated as visible.
+     */
+    onVisiblePageChange?: (pageIdx: number) => void;
+    /**
+     * Target page to scroll into view. When set, the view scrolls so that the
+     * matching page sits at the top of the scroll container.
+     */
+    scrollToPage?: number;
+    /** Vertical gap between pages (px). @defaultValue 24 */
+    pageGap?: number;
+}
+/**
+ * Continuous-scroll variant of {@link MejiroSpread}. Stacks every page in
+ * the chapter inside a vertically scrollable container. The visible page is
+ * detected via `IntersectionObserver` and reported through
+ * {@link MejiroScrollViewProps.onVisiblePageChange}.
+ */
+declare function MejiroScrollView({ layout, pageWidth, pageHeight, contentHeight, fontFamily, fontSize, lineSpacing, onVisiblePageChange, scrollToPage, pageGap, }: MejiroScrollViewProps): ReactNode;
+
+/** Props for {@link MejiroSelectionLayer}. */
+interface MejiroSelectionLayerProps {
+    /**
+     * Spread-local rectangles to highlight. Compute these via
+     * {@link ChapterLayout.selectionRects} and pass the full array; the layer
+     * picks the entries matching {@link MejiroSelectionLayerProps.side}.
+     */
+    rects: readonly AnchorRect[];
+    /** Which page-side this layer is rendered into. */
+    side: 'right' | 'left';
+    /** Optional class added to the outer wrapper. */
+    className?: string;
+    /** Optional inline style merged onto the outer wrapper. */
+    style?: CSSProperties;
+    /** Optional class for each rectangle (defaults to `mejiro-selection-rect`). */
+    rectClassName?: string;
+    /** Optional inline style for each rectangle. */
+    rectStyle?: CSSProperties;
+}
+/**
+ * Renders a selection-highlight overlay inside a page-content container.
+ *
+ * Use as a child of `.mejiro-reader-page-clip` (or any element that shares the
+ * page's content coordinate frame). The layer is pointer-transparent so it
+ * does not interfere with selection drag on the page below.
+ */
+declare function MejiroSelectionLayer({ rects, side, className, style, rectClassName, rectStyle, }: MejiroSelectionLayerProps): ReactNode;
+
+/** A single volume in a multi-book library. */
+interface VolumeInfo<T = unknown> {
+    /** Stable identifier (e.g. ISBN, slug, internal ID). */
+    id: string;
+    /** Human-readable title shown in pickers. */
+    label: string;
+    /** Optional author / byline. */
+    author?: string;
+    /** Optional cover image URL. */
+    cover?: string;
+    /** Free-form metadata attached by the host. */
+    meta?: T;
+}
+/** Options for {@link useLibrary}. */
+interface UseLibraryOptions<T = unknown> {
+    /** The volumes available to the reader. */
+    volumes: readonly VolumeInfo<T>[];
+    /** ID of the volume to start on. Defaults to the first entry. */
+    initialVolumeId?: string;
+    /** Called whenever the active volume changes. */
+    onChange?: (volume: VolumeInfo<T>) => void;
+}
+/** Return value of {@link useLibrary}. */
+interface UseLibraryReturn<T = unknown> {
+    /** The list of volumes (same reference as the options input). */
+    list: readonly VolumeInfo<T>[];
+    /** Currently active volume, or `null` for an empty library. */
+    current: VolumeInfo<T> | null;
+    /** Index of the current volume, or `-1` for an empty library. */
+    currentIndex: number;
+    /** Advance to the next volume in the list (no-op at the end). */
+    next(): void;
+    /** Go back to the previous volume in the list (no-op at the start). */
+    prev(): void;
+    /** Jump to a volume by ID. No-op when the ID is not in the list. */
+    goTo(id: string): void;
+}
+/**
+ * Headless hook for managing a multi-volume reading session. Pair it with
+ * {@link MejiroReader} (driving its `epub` / `epubUrl` prop) or
+ * {@link MejiroShelf} (visual picker).
+ */
+declare function useLibrary<T = unknown>(options: UseLibraryOptions<T>): UseLibraryReturn<T>;
+
+/** Props for {@link MejiroShelf}. */
+interface MejiroShelfProps<T = unknown> {
+    /** Volumes to display. */
+    volumes: readonly VolumeInfo<T>[];
+    /** ID of the currently active volume (highlighted in the grid). */
+    currentId?: string;
+    /** Called when the user picks a volume. */
+    onSelect?: (volume: VolumeInfo<T>) => void;
+    /** Heading shown above the grid. @defaultValue 'Library' */
+    title?: string;
+}
+/**
+ * Visual bookshelf picker. Renders each volume as a card with cover, label,
+ * and author. Pair with {@link useLibrary} to drive selection.
+ */
+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 in pixels. @defaultValue 160 */
+    /** Default image height. @defaultValue 160 */
     defaultHeight?: number;
-    /** Default x position. @defaultValue 80 */
+    /** Default x. @defaultValue 80 */
     defaultX?: number;
-    /** Default y position. @defaultValue 100 */
+    /** Default y. @defaultValue 100 */
     defaultY?: number;
-    /** Margin around the image in pixels. Defaults to the book's font size. */
+    /** 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 useImageOverlay}. */
-interface UseImageOverlayReturn {
-    /** Current image rectangle, or `null` if no overlay is active. */
-    imageRect: ImageRect | null;
-    /** Whether an image overlay is currently active. */
-    hasImage: boolean;
-    /** Toggle the image overlay on/off. */
-    toggleImage: () => void;
-    /** Pointer-down handler for the overlay body (initiates drag). */
-    onOverlayPointerDown: (e: PointerEvent) => 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: (e: PointerEvent) => void;
+    onResizePointerDown: (id: string, e: PointerEvent) => void;
 }
 /**
- * React hook that manages a draggable/resizable image overlay
- * with automatic text reflow via {@link ChapterLayout.syncImages}.
+ * 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;
+
+/** Per-page header data. */
+interface PageHeaderData {
+    /** Running title (left-aligned). */
+    title?: string;
+    /** Page number (right-aligned). `null` hides it. */
+    pageNumber?: number | null;
+}
+/** Props for {@link MejiroSpread}. */
+interface MejiroSpreadProps {
+    /** Spread data to render. */
+    spread: SpreadResult;
+    /** Page width (px). */
+    pageWidth: number;
+    /** Page height (px). */
+    pageHeight: number;
+    /** Content area height (px). */
+    contentHeight: number;
+    /** CSS font family applied to the content. */
+    fontFamily?: FontFamily;
+    /** Font size override (px). */
+    fontSize?: number;
+    /** Line spacing multiplier (slot mode). */
+    lineSpacing?: number;
+    /** Animate the page turn. */
+    turning?: boolean;
+    /** Header data for the right page. */
+    rightHeader?: PageHeaderData;
+    /** Header data for the left page. */
+    leftHeader?: PageHeaderData;
+    /** Image overlays on the current spread. */
+    images?: MultiImageItem[];
+    /** Force slot-mode rendering on both pages. */
+    slotMode?: boolean;
+    /** Custom renderer for per-page headers. */
+    renderPageHeader?: (side: 'right' | 'left', header: PageHeaderData) => ReactNode;
+    /** Custom indicator placed inside the spread (e.g. {@link MejiroPageIndicator}). */
+    indicator?: ReactNode;
+    /** Called when the previous-page zone is clicked. */
+    onPrev?: () => void;
+    /** Called when the next-page zone is clicked. */
+    onNext?: () => void;
+    /** 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;
+    /**
+     * Resolves a spread-local pixel coordinate to an in-chapter anchor.
+     * Typically `(x, y) => layout.anchorAtCoord(spreadIdx, x, y)`. When provided
+     * together with {@link MejiroSpreadProps.onSelectionChange}, the spread
+     * enables pointer-drag selection on the page content area.
+     */
+    anchorAtCoord?: (x: number, y: number) => InChapterAnchor | null;
+    /**
+     * Selection rectangles to render as a highlight overlay. Compute via
+     * {@link ChapterLayout.selectionRects}. Entries with `spreadIdx` other than
+     * the current spread are ignored.
+     */
+    selectionRects?: readonly AnchorRect[];
+    /**
+     * Called when the user drags-selects text on the spread.
+     * Called with `null` on a single-click (caret) where start equals end.
+     */
+    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.
+     */
+    singlePage?: boolean;
+    /**
+     * Called when the user makes a quick swipe gesture on the spread.
+     * `direction === 'next'` means the user swiped from right to left (the
+     * natural direction in vertical-rl for advancing).
+     */
+    onSwipe?: (direction: 'next' | 'prev') => void;
+    /** Called when the user taps the center area without swiping. */
+    onSurfaceTap?: () => void;
+}
+/**
+ * Renders a two-page spread 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, renderPageHeader, indicator, onPrev, onNext, onImagePointerDown, onImageResizePointerDown, onImageClose, anchorAtCoord, selectionRects, onSelectionChange, singlePage, onSwipe, onSurfaceTap, }: MejiroSpreadProps): ReactNode;
+
+/** Props for {@link MejiroStats}. */
+interface MejiroStatsProps {
+    /** Chapter currently displayed. */
+    chapter: EpubChapter | null;
+    /** Total page count for the current layout. */
+    totalPages: number;
+    /** Most recent layout time in ms. */
+    elapsedMs: number;
+    /** Optional label for the current font (e.g. "Noto Serif JP 16px"). */
+    fontLabel?: string;
+    /** Show estimated reading time in the stats line. @defaultValue false */
+    showReadingTime?: boolean;
+    /** Characters-per-minute used for the reading-time estimate. @defaultValue 600 */
+    cpm?: number;
+    /** Locale used to format the reading-time label. @defaultValue 'ja' */
+    readingTimeLocale?: 'ja' | 'en';
+}
+/** Compact reading stats line. */
+declare function MejiroStats({ chapter, totalPages, elapsedMs, fontLabel, showReadingTime, cpm, readingTimeLocale, }: MejiroStatsProps): ReactNode;
+
+/** Props for {@link MejiroToc}. */
+interface MejiroTocProps {
+    /** EPUB whose chapter list is rendered. */
+    epub: EpubBook;
+    /** Current reading anchor; the matching chapter is highlighted. */
+    currentAnchor?: ReadingAnchor | null;
+    /** Show a search input that filters chapter titles. @defaultValue false */
+    searchable?: boolean;
+    /** Heading displayed above the list. @defaultValue 'Contents' */
+    title?: string;
+    /** Placeholder shown in the search input. @defaultValue 'Search chapters…' */
+    searchPlaceholder?: string;
+    /** Called when the user picks a chapter. */
+    onSelect?: (chapter: number) => void;
+}
+/**
+ * Searchable, current-anchor-aware table of contents. Long-form replacement
+ * for {@link MejiroChapterNav}. Supersedes the older `MejiroChapterNav`
+ * for new code — the panel variant remains for backwards compatibility.
+ */
+declare function MejiroToc({ epub, currentAnchor, searchable, title, searchPlaceholder, onSelect, }: MejiroTocProps): ReactNode;
+
+/**
+ * A user-authored annotation on a book — a half-open range of in-chapter
+ * anchors plus optional metadata (color, note). Pair with the `annotations`
+ * prop on {@link MejiroReader} to render highlights, or with `goToAnchor` to
+ * implement bookmarks.
+ */
+interface Annotation {
+    /** Stable identifier. Auto-generated when omitted from {@link useAnnotations.add}. */
+    id: string;
+    /** Chapter the annotation lives in. */
+    chapter: number;
+    /** Range start (inclusive). */
+    start: InChapterAnchor;
+    /** Range end (exclusive). Equal to `start` for caret-style bookmarks. */
+    end: InChapterAnchor;
+    /** Free-form color identifier (e.g. `'yellow'`, `'#ffd166'`). */
+    color?: string;
+    /** Optional note text attached to the annotation. */
+    note?: string;
+    /** Unix epoch ms. Auto-set on {@link useAnnotations.add} when omitted. */
+    createdAt?: number;
+}
+/** Minimal storage interface required by {@link useAnnotations}. */
+interface AnnotationsStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** Options for {@link useAnnotations}. */
+interface UseAnnotationsOptions {
+    /** Storage key — usually scoped per-book (e.g. `mejiro:annotations:${bookId}`). */
+    key: string;
+    /**
+     * Storage backend. Defaults to `window.localStorage` when available.
+     * SSR consumers can omit this and the hook will fall back to in-memory.
+     */
+    storage?: AnnotationsStorage;
+    /** Throttle ms between writes. @defaultValue 250 */
+    throttleMs?: number;
+    /**
+     * Called immediately after each mutation (`add` / `remove` / `update` /
+     * `clear`) with the new annotation list. Use to mirror state to a server
+     * — `storage` only covers the local persistence side. Not invoked on
+     * initial hydration or when the `key` changes.
+     */
+    onChange?: (next: readonly Annotation[]) => void;
+}
+/** Return value of {@link useAnnotations}. */
+interface UseAnnotationsReturn {
+    /** Currently saved annotations, sorted by chapter / paragraph / charIndex. */
+    annotations: readonly Annotation[];
+    /** Add a new annotation. `id` and `createdAt` are auto-filled when omitted. */
+    add(input: Omit<Annotation, 'id' | 'createdAt'> & Partial<Pick<Annotation, 'id' | 'createdAt'>>): Annotation;
+    /** Remove an annotation by id. */
+    remove(id: string): void;
+    /** Patch an annotation by id. Pass `undefined` on a field to leave it untouched. */
+    update(id: string, patch: Partial<Omit<Annotation, 'id'>>): void;
+    /** Remove all annotations. */
+    clear(): void;
+}
+/**
+ * Persistence helper for reader annotations. Returns the saved annotation list
+ * plus add / update / remove helpers. Pair with the `annotations` prop on
+ * {@link MejiroReader} to render the corresponding highlight rectangles.
  *
- * @param layout - Current chapter layout (or `null` if not yet loaded).
- * @param spreadIdx - Current spread index.
- * @param onUpdate - Called with the updated {@link SpreadResult} after every reflow.
- * @param options - Default dimensions and position for the overlay.
+ * ```tsx
+ * const { annotations, add } = useAnnotations({ key: `mejiro:ann:${bookId}` });
+ * const handle = useRef<MejiroReaderHandle>(null);
+ *
+ * // Save a highlight at the current visible range:
+ * const range = handle.current?.getVisibleRange();
+ * if (range) add({ chapter: 0, start: range.start, end: range.end, color: 'yellow' });
+ *
+ * <MejiroReader epub={book} annotations={annotations} ref={handle} />
+ * ```
+ */
+declare function useAnnotations(options: UseAnnotationsOptions): UseAnnotationsReturn;
+
+/** Options for {@link useChapterLayout}. */
+interface UseChapterLayoutOptions {
+    /** Observe the surface element for size changes and re-flow. @defaultValue true */
+    enableResize?: boolean;
+    /** 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 {
+    pageWidth: number;
+    pageHeight: number;
+    contentHeight: number;
+}
+/** Return value of {@link useChapterLayout}. */
+interface UseChapterLayoutReturn {
+    /** Current layout, or `null` before the first computation. */
+    layout: ChapterLayout | null;
+    /** Page width in pixels. */
+    pageWidth: number;
+    /** Page height in pixels. */
+    pageHeight: number;
+    /** Content height in pixels. */
+    contentHeight: number;
+    /** Most recent layout time (ms). */
+    elapsedMs: number;
+    /** Force a fresh layout computation. */
+    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 when the
+ * surface resizes.
+ *
+ * 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;
+
+interface EditableEpubSelection {
+    chapter: number;
+    paragraph: number;
+}
+interface UseEditableEpubOptions {
+    /** URL fetched and loaded on mount. */
+    defaultUrl?: string;
+    /** Called after a successful load. */
+    onLoad?: (editor: EditableEpub) => void;
+    /** Called when a load fails. */
+    onError?: (error: Error) => void;
+    /** Called after export completes. */
+    onExport?: (buffer: ArrayBuffer) => void;
+}
+interface UseEditableEpubReturn {
+    editor: EditableEpub | null;
+    book: EditableEpubBook | null;
+    previewBook: EditableEpubBook | null;
+    loading: boolean;
+    exporting: boolean;
+    error: Error | null;
+    revision: number;
+    history: {
+        canUndo: boolean;
+        canRedo: boolean;
+        depth: number;
+        redoDepth: number;
+    } | null;
+    selection: EditableEpubSelection;
+    selectedParagraph: AnnotatedParagraph | null;
+    setSelection: (selection: EditableEpubSelection) => void;
+    loadBuffer: (buffer: ArrayBuffer) => Promise<EditableEpub | null>;
+    loadFile: (file: File) => Promise<EditableEpub | null>;
+    loadUrl: (url: string) => Promise<EditableEpub | null>;
+    updateParagraph: (text: string, inlineAnnotations?: readonly InlineAnnotation[]) => void;
+    setInlineAnnotations: (inlineAnnotations: readonly InlineAnnotation[]) => void;
+    addImage: (image: AddImageInput | EditableEpubImage) => void;
+    undo: () => boolean;
+    redo: () => boolean;
+    exportEpub: (options?: EpubExportOptions) => Promise<ArrayBuffer | null>;
+}
+/** Headless editable-EPUB state for custom proofreading/editor UIs. */
+declare function useEditableEpub(options?: UseEditableEpubOptions): UseEditableEpubReturn;
+
+/** Options for {@link useEpub}. */
+interface UseEpubOptions {
+    /** URL fetched on mount. A non-OK response is treated as "no default". */
+    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". */
+    onError?: (error: Error) => void;
+    /**
+     * Extra options merged into the `fetch` call when loading by URL. Useful
+     * for sending bearer tokens or cookies (`credentials: 'include'`).
+     */
+    fetchOptions?: RequestInit;
+    /**
+     * Custom EPUB fetcher used in place of the global `fetch`. Returns the
+     * raw `ArrayBuffer`. Overrides {@link fetchOptions} when set — common
+     * for hosts that already own an auth-aware HTTP client.
+     */
+    fetchEpub?: (url: string) => Promise<ArrayBuffer>;
+}
+/** Return value of {@link useEpub}. */
+interface UseEpubReturn {
+    /** Current parsed EPUB, or `null` before any load. */
+    epub: EpubBook | null;
+    /** Whether a load is in progress. */
+    loading: boolean;
+    /** Last load error, if any. */
+    error: Error | null;
+    /** Parse from an in-memory buffer. */
+    loadBuffer: (buffer: ArrayBuffer) => Promise<EpubBook | null>;
+    /** Parse from a {@link File}. */
+    loadFile: (file: File) => Promise<EpubBook | null>;
+    /** Fetch a URL and parse the response. */
+    loadUrl: (url: string) => Promise<EpubBook | null>;
+    /** Replace the current EPUB without going through the parser. */
+    setEpub: (book: EpubBook | null) => void;
+}
+/**
+ * React hook that parses EPUB files and exposes loading/error state plus
+ * convenience loaders for buffers, files, and URLs.
+ */
+declare function useEpub(options?: UseEpubOptions): UseEpubReturn;
+
+interface EpubProjectChapterDraft {
+    id: string;
+    title: string;
+    body: string;
+}
+interface UseEpubProjectOptions {
+    metadata?: Partial<EpubProjectMetadata>;
+    chapters?: EpubProjectChapterDraft[];
+    debounceMs?: number;
+    /**
+     * Resolves URL-only project assets into bytes when the preview or export
+     * pipeline materializes them. Forwarded to `project.export()`. Useful when
+     * cover / illustration assets are registered as remote URLs and you want
+     * the host (not the client) to provide auth headers.
+     */
+    assetResolver?: AssetResolver;
+    onPreview?: (book: EpubBook) => void;
+    onExport?: (buffer: ArrayBuffer) => void;
+}
+interface UseEpubProjectReturn {
+    metadata: EpubProjectMetadata;
+    chapters: EpubProjectChapterDraft[];
+    selectedChapter: number;
+    currentChapter: EpubProjectChapterDraft | null;
+    previewBook: EpubBook | null;
+    previewError: Error | null;
+    previewing: boolean;
+    setMetadata: (patch: Partial<EpubProjectMetadata>) => void;
+    setChapters: (chapters: EpubProjectChapterDraft[]) => void;
+    setSelectedChapter: (index: number) => void;
+    patchChapter: (index: number, patch: Partial<EpubProjectChapterDraft>) => void;
+    addChapter: (chapter?: Partial<EpubProjectChapterDraft>) => void;
+    removeChapter: (index?: number) => void;
+    reorderChapters: (from: number, to: number) => void;
+    buildProject: () => EpubProject;
+    exportEpub: () => Promise<ArrayBuffer>;
+}
+/** Headless manuscript-to-EPUB project state for custom authoring UIs. */
+declare function useEpubProject(options?: UseEpubProjectOptions): UseEpubProjectReturn;
+
+/** Options for {@link useManuscriptDraft}. */
+interface UseManuscriptDraftOptions {
+    /** Initial chapters. Defaults to a single empty chapter. */
+    initialChapters?: ManuscriptEditorChapter[];
+    /**
+     * Called when the draft changes (debounced). Use to persist to
+     * localStorage, IndexedDB, or upload to a server.
+     */
+    onAutosave?: (chapters: ManuscriptEditorChapter[]) => void | Promise<void>;
+    /** Debounce delay in milliseconds. @defaultValue 800 */
+    autosaveDelay?: number;
+}
+/** Return value of {@link useManuscriptDraft}. */
+interface UseManuscriptDraftReturn {
+    chapters: ManuscriptEditorChapter[];
+    /** Index of the chapter currently being edited. */
+    selected: number;
+    setSelected(index: number): void;
+    setChapters(chapters: ManuscriptEditorChapter[]): void;
+    patchChapter(index: number, patch: Partial<ManuscriptEditorChapter>): void;
+    addChapter(chapter?: Partial<ManuscriptEditorChapter>): void;
+    removeChapter(index: number): void;
+    reorderChapters(from: number, to: number): void;
+}
+/**
+ * Reactive store for manuscript drafts.
+ *
+ * Wraps the chapter array with helpers for adding, removing, reordering, and
+ * patching individual chapters, plus a debounced autosave hook that fires
+ * `onAutosave` whenever the chapter list settles.
+ */
+declare function useManuscriptDraft(options?: UseManuscriptDraftOptions): UseManuscriptDraftReturn;
+
+/** Options for {@link useManuscriptLayout}. */
+interface UseManuscriptLayoutOptions {
+    /** Manuscript notation dialect. @defaultValue `'mejiro'` */
+    dialect?: ManuscriptDialect;
+    /** Listen for `window.resize` and re-flow on resize. @defaultValue true */
+    enableResize?: boolean;
+    /** Debounce window (ms) for resize re-flows. @defaultValue 120 */
+    resizeDebounce?: number;
+}
+/** Page dimensions returned by {@link MejiroBook.computePageSize}. */
+interface ManuscriptPageDimensions {
+    pageWidth: number;
+    pageHeight: number;
+    contentHeight: number;
+}
+/** Return value of {@link useManuscriptLayout}. */
+interface UseManuscriptLayoutReturn {
+    /** Current layout, or `null` before the first computation. */
+    layout: ChapterLayout | null;
+    /** Page width in pixels. */
+    pageWidth: number;
+    /** Page height in pixels. */
+    pageHeight: number;
+    /** Content height in pixels. */
+    contentHeight: number;
+    /** Most recent layout time (ms). */
+    elapsedMs: number;
+    /** Force a fresh layout computation. */
+    recompute: () => Promise<void>;
+}
+/**
+ * React hook that lays out a single manuscript chapter directly, skipping the
+ * EPUB ZIP round-trip used by {@link useChapterLayout}.
+ *
+ * Intended for live preview in custom manuscript editors: pair with
+ * {@link useManuscriptDraft} for the chapter array and feed the resulting
+ * {@link ChapterLayout} into {@link MejiroSpread} or {@link MejiroScrollView}.
+ *
+ * Re-layouts whenever `chapter`, `dialect`, or `book` change. On `window.resize`,
+ * page dimensions are recomputed and {@link ChapterLayout.resize} is called
+ * instead of a full re-layout.
+ */
+declare function useManuscriptLayout(book: MejiroBook, chapter: ManuscriptChapter | null, surface: RefObject<HTMLElement | null>, options?: UseManuscriptLayoutOptions): UseManuscriptLayoutReturn;
+
+/** Return value of {@link useMejiroBook}. */
+interface UseMejiroBookReturn {
+    /** The managed {@link MejiroBook} instance. Stable across renders. */
+    book: MejiroBook;
+    /** Reactive snapshot of the current options. */
+    options: Readonly<BookOptions>;
+    /**
+     * Update options on the underlying book and the snapshot. The returned
+     * promise resolves once {@link MejiroBook.setOptions} has propagated
+     * font / size changes (re-measurement runs lazily inside that call).
+     */
+    setOptions: (next: Partial<BookOptions>) => Promise<void>;
+}
+/**
+ * React hook that owns a {@link MejiroBook} instance and exposes its
+ * options as React state. The book is created once on mount; subsequent
+ * option changes must go through {@link UseMejiroBookReturn.setOptions}
+ * (e.g. via the `MejiroReader` imperative handle).
+ */
+declare function useMejiroBook(initial: BookOptions): UseMejiroBookReturn;
+
+/**
+ * Persisted reading position. Anchor-shaped — pair with
+ * {@link MejiroReaderHandle.goToAnchor} to restore the user's exact location
+ * even after a reflow that invalidates spread indices.
+ */
+type ReadingPositionValue = ReadingAnchor;
+/** Minimal storage interface required by {@link useReadingPosition}. */
+interface ReadingPositionStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** Options for {@link useReadingPosition}. */
+interface UseReadingPositionOptions {
+    /** Storage key — usually scoped per-book (e.g. `mejiro:position:${bookId}`). */
+    key: string;
+    /**
+     * Storage backend. Defaults to `window.localStorage` when available.
+     * SSR consumers can omit this and the hook will fall back to in-memory.
+     */
+    storage?: ReadingPositionStorage;
+    /** Throttle ms between writes. @defaultValue 250 */
+    throttleMs?: number;
+    /**
+     * Called immediately after `save()` (with the new anchor) or `clear()`
+     * (with `null`). Use to mirror the position to a server alongside the
+     * local `storage`. Not invoked on initial hydration or `key` changes.
+     */
+    onChange?: (next: ReadingPositionValue | null) => void;
+}
+/** Return value of {@link useReadingPosition}. */
+interface UseReadingPositionReturn {
+    /** Most recently persisted position, or `null` if none. */
+    position: ReadingPositionValue | null;
+    /** Persist a new position (throttled). */
+    save(next: ReadingPositionValue): void;
+    /** Remove the persisted position. */
+    clear(): void;
+}
+/**
+ * Persistence helper for reader state. Returns the saved anchor and a
+ * throttled saver. Pair with {@link MejiroReaderHandle.goToAnchor} and
+ * {@link MejiroReaderHandle.subscribe} for exact reflow-safe restore.
  *
- * @example
  * ```tsx
- * const { imageRect, hasImage, toggleImage, onOverlayPointerDown, onResizePointerDown } =
- *   useImageOverlay(layout, spreadIdx, setSpread);
+ * const { position, save } = useReadingPosition({ key: `mejiro:${bookId}` });
+ * const reader = useRef<MejiroReaderHandle>(null);
+ *
+ * useEffect(() => {
+ *   if (position) reader.current?.goToAnchor(position);
+ * }, [position]);
+ *
+ * useEffect(() => {
+ *   const off = reader.current?.subscribe('spreadChanged', () => {
+ *     const anchor = reader.current?.getAnchor();
+ *     if (anchor) save(anchor);
+ *   });
+ *   return off;
+ * }, [save]);
  * ```
+ *
+ * Legacy `{ chapter, spreadIdx }` JSON from v0.4 is migrated automatically:
+ * the chapter is preserved, `spreadIdx` is dropped (it does not survive
+ * reflow), and the position is treated as the start of the chapter.
  */
-declare function useImageOverlay(layout: ChapterLayout | null, spreadIdx: number, onUpdate: (spread: SpreadResult) => void, options?: UseImageOverlayOptions): UseImageOverlayReturn;
+declare function useReadingPosition(options: UseReadingPositionOptions): UseReadingPositionReturn;
+
+/** Options for {@link useSpread}. */
+interface UseSpreadOptions {
+    /** Enable ArrowLeft/ArrowRight navigation. @defaultValue true */
+    enableKeyboard?: boolean;
+    /** Page-turn animation duration in ms. @defaultValue 180 */
+    turnDuration?: number;
+    /** 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. */
+    spreadIdx: number;
+    /** Current spread result, or `null` until the layout is ready. */
+    spread: SpreadResult | null;
+    /** Total number of pages. */
+    totalPages: number;
+    /** Total number of two-page spreads. */
+    totalSpreads: number;
+    /** Whether the turn animation is currently in flight. */
+    turning: boolean;
+    /** Advance one spread forward. */
+    next: () => void;
+    /** Go back one spread. */
+    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;
+}
+/**
+ * React hook that tracks the current spread index for a chapter layout
+ * and exposes navigation helpers with an optional page-turn animation.
+ */
+declare function useSpread(layout: ChapterLayout | null, options?: UseSpreadOptions): UseSpreadReturn;
 
-export { type ImageRect, MejiroPage, type MejiroPageProps, MejiroPageView, type MejiroPageViewProps, type UseImageOverlayOptions, type UseImageOverlayReturn, useImageOverlay };
+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 };