@libraz/mejiro-react 0.10.0 → 0.11.0

package/dist/index.d.ts

@@ -1,20 +1,28 @@
-import { MejiroLocale, MejiroMessages, EditableSettings, FontChoice, ImageOverlayRect, PageHeaderData, MejiroStorage, Annotation, ReadingPositionValue } from '@libraz/mejiro';
-export { Annotation, EditableSettings, FontChoice, ImageOverlayRect, MejiroLocale, MejiroMessages, PageHeaderData, ReadingPositionValue, enMessages, jaMessages } from '@libraz/mejiro';
+import { MejiroLocale, MejiroMessages, EditableSettings, FontChoice, MejiroStorage, Annotation, MejiroError, ImageOverlayRect, PageHeaderData, BinaryInput, ManuscriptChapter as ManuscriptChapter$1, InlineAnnotation, ReadingAnchor as ReadingAnchor$1 } from '@libraz/mejiro';
+export { Annotation, EditableSettings, FontChoice, ImageOverlayRect, ManuscriptChapter, MejiroError, MejiroErrorCode, MejiroLocale, MejiroMessages, MejiroStorage, MejiroWarning, MejiroWarningCode, PageHeaderData, ReadingAnchor, enMessages, formatMessage, jaMessages, resolveMessages } from '@libraz/mejiro';
 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';
+import { ReactNode, ComponentPropsWithoutRef, CSSProperties, PointerEvent, TextareaHTMLAttributes, RefAttributes, RefObject, MutableRefObject } from 'react';
+import { EpubBook, EpubParseLimits, ManuscriptDialect, AssetResolver, EditableEpub, EpubChapter, EditableEpubBook, EditHistoryState, EditableEpubSelection, EditableParagraphBlock, ParagraphPatch, AddImageInput, EditableImageBlock, EditableEpubExportOptions, EpubProjectMetadata, CoverInput, EpubProjectAsset, EpubProject } from '@libraz/mejiro/epub';
 export { EditableEpubSelection } from '@libraz/mejiro/epub';
-import { ChapterLayout, SpreadResult, BookOptions, MejiroBookOptions, ComputePageSizeOptions, InChapterAnchor, ReadingAnchor, ManuscriptChapter, PageResult, AnchorRect, AnchorRange, MejiroBook } from '@libraz/mejiro/book';
+import { SpreadResult, ChapterLayout, InChapterAnchor, AnchorRect, SpreadPoint, AnchorRange, BookOptions, FitPageSizeOptions, ReadingAnchor, BookOptionsPatch, ManuscriptChapter, PageResult, MejiroBook } from '@libraz/mejiro/book';
 import { PageNumberDisplay, RenderPage } from '@libraz/mejiro/render';
 export { PageNumberDisplay } from '@libraz/mejiro/render';
-import { FontFamily, InlineAnnotation } from '@libraz/mejiro/browser';
+import { FontFamily } from '@libraz/mejiro/browser';
 
-/** Provider that scopes a message catalog to its descendants. */
-declare function MejiroI18nProvider({ locale, messages, children, }: {
+/** Props for {@link MejiroI18nProvider}. */
+interface MejiroI18nProviderProps {
+    /**
+     * Built-in locale to use as the base catalog. Without it the catalog of the
+     * enclosing provider is the base, or the English catalog at the top level.
+     */
     locale?: MejiroLocale;
+    /** Overrides merged on top of the base catalog. */
     messages?: Partial<MejiroMessages>;
+    /** Subtree the catalog applies to. */
     children: ReactNode;
-}): ReactNode;
+}
+/** Provider that scopes a message catalog to its descendants. */
+declare function MejiroI18nProvider({ locale, messages, children, }: MejiroI18nProviderProps): ReactNode;
 /** Options for {@link useI18n}. */
 interface UseI18nOptions {
     /**
@@ -31,45 +39,45 @@ interface UseI18nOptions {
  * 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;
 
 /**
  * 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 {
+/** Props for {@link MejiroChapterNav}; other `div` attributes go to the root element. */
+interface MejiroChapterNavProps extends ComponentPropsWithoutRef<'div'> {
     /** EPUB to list chapters from. */
     epub: EpubBook;
-    /** Current chapter index. */
-    chapter: number;
-    /** Called when a new chapter is picked. */
-    onChange: (chapter: number) => void;
+    /** Zero-based index of the chapter shown as current. */
+    chapterIndex: number;
+    /** Called with the zero-based index of the chapter the user picks. */
+    onChapterIndexChange: (chapterIndex: 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.
+ * Chapter picker for an {@link EpubBook}: a compact `<select>`, or a panel
+ * listing each chapter with its sub-headings and a text preview. For a
+ * searchable table of contents that follows the reading anchor, use
+ * {@link MejiroToc}.
  */
-declare function MejiroChapterNav({ epub, chapter, onChange, variant, }: MejiroChapterNavProps): ReactNode;
+declare const MejiroChapterNav: react.ForwardRefExoticComponent<MejiroChapterNavProps & react.RefAttributes<HTMLElement>>;
 
-/** Props for {@link MejiroDropZone}. */
-interface MejiroDropZoneProps {
+/** Props for {@link MejiroDropZone}; other `button` attributes go to the root element. */
+interface MejiroDropZoneProps extends ComponentPropsWithoutRef<'button'> {
     /** File `accept` filter for the picker. @defaultValue '.epub' */
     accept?: string;
     /** 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;
+    /**
+     * Called with a selected or dropped file that is not accepted: `'type'` when
+     * it fails the `accept` filter, `'validation'` when
+     * {@link MejiroDropZoneProps.validateFile} returns `false`.
+     */
+    onReject?: (file: File, reason: 'type' | 'validation') => void;
     /** Custom body content (replaces default icon/text). */
     children?: ReactNode;
     /** Additional class name for the root element. */
@@ -82,18 +90,21 @@ interface MejiroDropZoneProps {
  * picker. The root is a real button, so it is reachable with Tab, announced as
  * a control by screen readers, and opens the picker on Enter / Space.
  */
-declare function MejiroDropZone({ accept, validateFile, onFile, children, className, style, }: MejiroDropZoneProps): ReactNode;
+declare const MejiroDropZone: react.ForwardRefExoticComponent<MejiroDropZoneProps & react.RefAttributes<HTMLButtonElement>>;
 
-/** Props for {@link MejiroSettingsPanel}. */
-interface MejiroSettingsPanelProps {
+/** Props for {@link MejiroSettingsPanel}; other `div` attributes go to the root element. */
+interface MejiroSettingsPanelProps extends ComponentPropsWithoutRef<'div'> {
     /** Whether the panel is expanded. */
     open: boolean;
     /** Current editable settings. */
     settings: EditableSettings;
-    /** Called when a setting changes. */
-    onChange: (next: EditableSettings) => void;
+    /**
+     * Called when the user changes a setting, with the whole settings value:
+     * {@link MejiroSettingsPanelProps.settings} with that one field replaced.
+     */
+    onSettingsChange: (next: EditableSettings) => void;
     /** Font choices. */
-    fonts?: FontChoice[];
+    fonts?: readonly FontChoice[];
     /** Min font size. @defaultValue 10 */
     minFontSize?: number;
     /** Max font size. @defaultValue 48 */
@@ -102,181 +113,427 @@ interface MejiroSettingsPanelProps {
 /**
  * Reader settings panel: font, size, kinsoku mode, hanging punctuation, line spacing.
  */
-declare function MejiroSettingsPanel({ open, settings, onChange, fonts, minFontSize, maxFontSize, }: MejiroSettingsPanelProps): ReactNode;
+declare const MejiroSettingsPanel: react.ForwardRefExoticComponent<MejiroSettingsPanelProps & react.RefAttributes<HTMLDivElement>>;
 
-/** Props for {@link MejiroEditor}. */
-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). When `false` and
-     * `enableRuby` is on, the paragraph text stays visible read-only so a ruby
-     * base range can still be selected.
-     * @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>;
+/** Options for {@link useAnnotations}. */
+interface UseAnnotationsOptions {
+    /** Storage key — usually scoped per-book (e.g. `mejiro:annotations:${bookId}`). */
+    key: string;
     /**
-     * Declarative export policy. When set, supersedes `onBeforeExport` for
-     * download control and threads watermark / encrypt transforms through the
-     * export pipeline.
+     * Storage backend. Defaults to `window.localStorage` when available.
+     * SSR consumers can omit this and the hook will fall back to in-memory.
+     * The latest reference is always used, so an object literal recreated on
+     * every render is safe — only `key` triggers a re-hydration.
      */
-    exportPolicy?: MejiroExportPolicy;
+    storage?: MejiroStorage;
     /**
-     * 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.
+     * Debounce delay (ms): the latest value is written this long after the last
+     * change. A pending write is flushed on page hide, key change and unmount.
+     * @defaultValue 250
      */
-    assetResolver?: AssetResolver;
+    debounceMs?: number;
     /**
-     * Archive resource limits applied while opening an EPUB. Raise them for
-     * trusted, image-heavy books; tighten them for a public drop zone. Omitted
-     * fields keep their `DEFAULT_EPUB_PARSE_LIMITS` value.
+     * 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.
      */
-    limits?: Partial<EpubParseLimits>;
-    /** Called after an EPUB is loaded into the editor. */
-    onLoad?: (editor: EditableEpub) => void;
-    /** Called after export completes. */
-    onExport?: (buffer: ArrayBuffer) => void;
+    onAnnotationsChange?: (next: readonly Annotation[]) => void;
     /**
-     * Called when loading, image insertion, export or the preview reader fails.
-     * The error is also shown in the editor until a later load, image insertion
-     * or export succeeds.
+     * Receives a storage failure: `storage-read-failed` or `storage-corrupt` when
+     * hydrating (the list starts empty, and the stored value is left alone until
+     * the next mutation), `storage-write-failed` when a write or removal throws
+     * (the in-memory list is kept). Without it the error goes to `console.warn`.
      */
-    onError?: (error: Error) => void;
+    onError?: (error: MejiroError) => void;
 }
-/**
- * Declarative restrictions on the export pipeline. Mejiro applies the
- * transforms in this order: `watermark` (applied to an export-only copy of the
- * book, never to the edited document) → `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 exported EPUB. Implemented as a
-     * paragraph block prefixed with `[mejiro-watermark]` at the top of every
-     * chapter, so a downstream renderer can theme it by that prefix. The block
-     * only exists in the exported file — the edited document is unchanged.
-     */
-    watermark?: {
-        text: string;
-    };
+/** 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;
 }
-/** EPUB editor UI for proofreading, ruby edits, image insertion, and export. */
-declare function MejiroEditor({ epubUrl, fonts, enableProofread, enableRuby, enableImages, enableExport, onBeforeExport, exportPolicy, assetResolver, limits, onLoad, onExport, onError, }: MejiroEditorProps): ReactNode;
-
 /**
- * Rectangle describing an image overlay position and size.
+ * 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.
+ *
+ * ```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({ chapterIndex: 0, start: range.start, end: range.end, color: 'yellow' });
  *
- * @deprecated Alias of {@link ImageOverlayRect}, which is the single name for
- * this shape across the package family. The core package exports an unrelated
- * `ImageRect` (an exclusion rectangle, with margin fields), so the two names
- * collide when both packages are imported into one module.
+ * <MejiroReader epub={book} annotations={annotations} ref={handle} />
+ * ```
  */
-type ImageRect = ImageOverlayRect;
+declare function useAnnotations(options: UseAnnotationsOptions): UseAnnotationsReturn;
+
+/** 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: ImageOverlayRect;
+}
 /** Options for {@link useImageOverlay}. */
 interface UseImageOverlayOptions {
-    /** Default image width in pixels. @defaultValue 120 */
+    /** Layout spread that {@link UseImageOverlayReturn.addOverlay} places overlays on. */
+    spreadIndex: number;
+    /** Default overlay width in pixels. @defaultValue 120 */
     defaultWidth?: number;
-    /** Default image height in pixels. @defaultValue 160 */
+    /** Default overlay height in pixels. @defaultValue 160 */
     defaultHeight?: number;
-    /** Default x position. @defaultValue 80 */
+    /** Default x position, relative to the right page. @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 around each overlay, in pixels. Defaults to the book's font size. */
     margin?: number;
+    /**
+     * Called with each spread the layout re-flowed after an overlay change, and
+     * after the overlays are re-applied to a replacement layout or a new margin.
+     * Pair it with `useSpread().refresh()` so the spread on screen picks up the
+     * reflow. @defaultValue no-op
+     */
+    onReflow?: (spread: SpreadResult) => void;
 }
 /** Return value of {@link useImageOverlay}. */
 interface UseImageOverlayReturn {
-    /** Current image rectangle, or `null` if no overlay is active. */
-    imageRect: ImageOverlayRect | 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;
+    /**
+     * Overlays keyed by spread index. A new map whenever the overlays 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: ReadonlyMap<number, readonly MultiImageItem[]>;
+    /** Overlays on {@link UseImageOverlayOptions.spreadIndex}; a new array whenever `imagesBySpread` changes. */
+    currentImages: readonly MultiImageItem[];
+    /** Whether any spread holds at least one overlay. */
+    hasOverlays: boolean;
+    /** Adds an overlay on the current spread and returns it. */
+    addOverlay: (overrides?: Partial<ImageOverlayRect>) => MultiImageItem;
+    /** Removes the overlay with the given id; a no-op for an unknown id. */
+    removeOverlay: (id: string) => void;
+    /** Merges `rect` into the rectangle of the overlay with the given id; a no-op for an unknown id. */
+    updateOverlay: (id: string, rect: Partial<ImageOverlayRect>) => void;
+    /** Removes every overlay, or only those on `spreadIndex` when given. */
+    clearOverlays: (spreadIndex?: number) => void;
+    /** Pointer-down handler for an overlay body: starts a move drag. */
+    onOverlayPointerDown: (id: string, e: PointerEvent) => void;
+    /** Pointer-down handler for an overlay's resize handle: starts a resize drag. */
+    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 draggable, resizable image overlays per spread and
+ * re-flows the text around them via `ChapterLayout.setImages`.
  *
- * While an overlay is active the exclusion is re-issued whenever `layout` is
- * 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.
- * @param onUpdate - Called with the updated {@link SpreadResult} after every reflow.
- * @param options - Default dimensions and position for the overlay.
+ * @param layout - Chapter layout the overlays exclude text from, or `null` while none is ready.
+ * @param options - Current spread, overlay defaults, margin and reflow notification.
+ * @returns The overlay state, mutators and pointer handlers.
  *
  * @example
  * ```tsx
- * const { imageRect, hasImage, toggleImage, onOverlayPointerDown, onResizePointerDown } =
- *   useImageOverlay(layout, spreadIdx, setSpread);
+ * const nav = useSpread(layout);
+ * const overlays = useImageOverlay(layout, {
+ *   spreadIndex: nav.spreadIndex,
+ *   onReflow: () => nav.refresh(),
+ * });
  * ```
  */
-declare function useImageOverlay(layout: ChapterLayout | null, spreadIdx: number, onUpdate: (spread: SpreadResult) => void, options?: UseImageOverlayOptions): UseImageOverlayReturn;
+declare function useImageOverlay(layout: ChapterLayout | null, 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;
+/**
+ * Spread mode a view renders in once `'auto'` has been decided: one page at a
+ * time, or two-page spreads.
+ */
+type ResolvedSpreadMode = 'single' | 'double';
+/** Options for {@link UseSpreadReturn.goTo}. */
+interface GoToOptions {
+    /**
+     * Run the page-turn animation. With `false` the index changes immediately,
+     * cancelling any turn in flight — use it to restore a position after a
+     * re-layout, where an animated turn would briefly show the first spread.
+     * @defaultValue true
+     */
+    animate?: boolean;
+}
+/** Options for {@link useSpread}. */
+interface UseSpreadOptions {
+    /** Enable ArrowLeft/ArrowRight navigation. @defaultValue true */
+    enableKeyboard?: boolean;
+    /** Page-turn animation duration in milliseconds; `0` turns without animating. @defaultValue 180 */
+    turnDurationMs?: number;
+    /**
+     * Spread mode to navigate in. In `'single'` the navigation index counts
+     * pages; in `'double'` it counts two-page spreads. Changing it converts the
+     * index so the page on screen stays visible. @defaultValue 'double'
+     */
+    spreadMode?: ResolvedSpreadMode;
+    /**
+     * Keep the visible text on screen when `layout` is replaced: the new layout
+     * opens at the position holding the first text the old one showed, instead
+     * of at index 0. @defaultValue false
+     */
+    preservePosition?: boolean;
+    /**
+     * Called with the new navigation index after it changes: when an animated
+     * turn lands, at the end of {@link UseSpreadOptions.turnDurationMs}, or
+     * immediately for a turn without animation. Not called while a turn is in
+     * flight, and not called when a turn ends where it started.
+     */
+    onIndexChange?: (index: number) => void;
+}
+/** Return value of {@link useSpread}. */
+interface UseSpreadReturn {
+    /** Navigation index: a page index in single mode, a spread index otherwise. `0` without a layout. */
+    index: number;
+    /** Number of navigation positions: pages in single mode, spreads otherwise. `0` without a layout. */
+    count: number;
+    /** Index of the layout spread holding the visible page(s), as `ChapterLayout.getSpread` takes it. */
+    spreadIndex: number;
+    /** Number of spreads in the layout, whatever the spread mode. */
+    spreadCount: number;
+    /** Number of pages in the layout, as of {@link UseSpreadReturn.spread}. */
+    pageCount: number;
+    /** Layout spread holding the visible page(s), or `null` until the layout is ready. */
+    spread: SpreadResult | null;
+    /** Index of the first page shown, in reading order. */
+    firstPage: number;
+    /** Side of {@link UseSpreadReturn.spread} shown in single mode; `null` in double mode. */
+    singleSide: 'right' | 'left' | null;
+    /** Whether a page-turn animation is in flight. */
+    turning: boolean;
+    /** Move one position forward, counting from the target of a turn in flight. */
+    next: () => void;
+    /** Move one position back, counting from the target of a turn in flight. */
+    prev: () => void;
+    /**
+     * Go to a navigation index. Negative values go to `0` and values past the
+     * end to `count − 1`. A call during a turn replaces that turn's target, so
+     * the turn lands on the last index requested. A no-op without a layout or
+     * when `count` is `0`.
+     *
+     * @throws RangeError when `index` is not an integer (fractions, `NaN`, `±Infinity`).
+     */
+    goTo: (index: number, options?: GoToOptions) => void;
+    /** Navigation index that shows the given page. */
+    indexOfPage: (pageIndex: 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;
+    /** Re-read {@link UseSpreadReturn.spread} from `layout` at the current index. */
+    refresh: () => void;
 }
 /**
- * Decorative image placeholder overlay with drag/resize affordances.
- * Pair the pointer handlers with {@link useImageOverlay} or {@link useMultiImageOverlay}.
+ * React hook that tracks the navigation position in a chapter layout and
+ * exposes navigation helpers with an optional page-turn animation.
+ *
+ * @param layout - Chapter layout to navigate, or `null` while none is ready.
+ * @param options - Spread mode, animation, keyboard and change notification.
+ * @returns The navigation state and helpers.
  */
-declare function MejiroImageOverlay({ rect, label, onOverlayPointerDown, onResizePointerDown, onClose, }: MejiroImageOverlayProps): ReactNode;
+declare function useSpread(layout: ChapterLayout | null, options?: UseSpreadOptions): UseSpreadReturn;
+
+/**
+ * A selection rectangle from `ChapterLayout.selectionRects`, optionally
+ * carrying its own CSS fill colour.
+ */
+type SelectionRect = AnchorRect & {
+    /** CSS colour filling this rectangle; the stylesheet's selection fill when absent. */
+    color?: string;
+};
+/** The part of an {@link Annotation} a reader needs to draw it as a highlight. */
+type ReaderAnnotation = Pick<Annotation, 'chapterIndex' | 'start' | 'end' | 'color'>;
+/** Props for {@link MejiroSpread}; other `div` attributes go to the root element. */
+interface MejiroSpreadProps extends ComponentPropsWithoutRef<'div'> {
+    /** Spread data to render. */
+    spread: SpreadResult;
+    /**
+     * Layout the spread comes from. When given, its `geometry` and `typography`
+     * supply every page-size and font prop left unset.
+     */
+    layout?: ChapterLayout;
+    /** Page width (px). Defaults to `layout.geometry.pageWidth`. */
+    pageWidth?: number;
+    /** Page height (px). Defaults to `layout.geometry.pageHeight`. */
+    pageHeight?: number;
+    /** Content area height (px). Defaults to `layout.geometry.contentHeight`. */
+    contentHeight?: number;
+    /** CSS font family applied to the content. Defaults to `layout.typography.fontFamily`. */
+    fontFamily?: FontFamily;
+    /** Font size (px). Defaults to `layout.typography.fontSize`. */
+    fontSize?: number;
+    /** Line spacing multiplier. Defaults to `layout.typography.lineSpacing`. */
+    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, relative to the right page. In
+     * single spread mode, only those whose centre lies on the page shown are drawn.
+     */
+    images?: readonly MultiImageItem[];
+    /**
+     * Force slot-mode rendering on both pages. When omitted, each page falls
+     * through to {@link MejiroPageView}'s automatic choice: slot mode for pages
+     * with images, native `writing-mode: vertical-rl` otherwise.
+     */
+    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 point to an in-chapter anchor.
+     * Typically `(point) => layout.anchorAtCoord(spreadIndex, point)`. When provided
+     * together with {@link MejiroSpreadProps.onSelectionChange}, the spread
+     * enables pointer-drag selection on the page content area.
+     */
+    anchorAtCoord?: (point: SpreadPoint) => InChapterAnchor | null;
+    /**
+     * Zero-based index of the spread being rendered. Rectangles passed through
+     * {@link MejiroSpreadProps.selectionRects} carry spread-local coordinates,
+     * so this is what scopes them to this spread. When omitted, every supplied
+     * rectangle is painted.
+     */
+    spreadIndex?: number;
+    /**
+     * Selection rectangles to render as a highlight overlay. Compute via
+     * {@link ChapterLayout.selectionRects}. Entries whose `spreadIndex` differs
+     * from {@link MejiroSpreadProps.spreadIndex} are ignored. An entry may carry
+     * a `color` that becomes that rectangle's fill.
+     */
+    selectionRects?: readonly SelectionRect[];
+    /**
+     * 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;
+    /**
+     * `'single'` renders one page of the spread (centered), chosen by
+     * {@link MejiroSpreadProps.singleSide}; `'double'` renders both. Use
+     * `'single'` for portrait viewports or when a reader opts into single-page
+     * mode. @defaultValue 'double'
+     */
+    spreadMode?: ResolvedSpreadMode;
+    /**
+     * Page of the spread shown in single spread mode, as `useSpread` reports it
+     * in `singleSide`; `null` (what `useSpread` reports in double mode) shows the
+     * right page. @defaultValue 'right'
+     */
+    singleSide?: 'right' | 'left' | null;
+    /**
+     * 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 (or one page of it in single spread mode) with the
+ * book frame, page chrome, navigation zones, and image overlays. Used inside
+ * `mejiro-reader-surface`.
+ */
+declare const MejiroSpread: react.ForwardRefExoticComponent<MejiroSpreadProps & react.RefAttributes<HTMLDivElement>>;
+
+/** Second argument of a host `fetchEpub` callback. */
+interface FetchEpubOptions {
+    /**
+     * Aborted when the load is superseded — by a newer load, a `url` change,
+     * `setEpub` or unmount. Pass it on to the request so the download stops too.
+     */
+    signal: AbortSignal;
+}
+/** Options for {@link useEpub}. */
+interface UseEpubOptions {
+    /**
+     * URL to load. Fetched on mount and again whenever it changes; clearing it
+     * abandons a load still in flight and keeps the current EPUB.
+     */
+    url?: string;
+    /** Called after a successful load. */
+    onLoad?: (epub: EpubBook) => void;
+    /**
+     * Called when a load fails, including a non-2xx URL response
+     * (`MejiroError` `fetch-failed`). A `MejiroError` is passed as thrown.
+     */
+    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`. Resolves to the
+     * raw bytes. Overrides {@link UseEpubOptions.fetchOptions} when set — common
+     * for hosts that already own an auth-aware HTTP client.
+     */
+    fetchEpub?: (url: string, options: FetchEpubOptions) => Promise<BinaryInput>;
+    /**
+     * Archive resource limits applied while opening an EPUB. Raise them for
+     * trusted, image-heavy books; tighten them for a public drop zone. Omitted
+     * fields keep their `DEFAULT_EPUB_PARSE_LIMITS` value.
+     */
+    limits?: Partial<EpubParseLimits>;
+}
+/** 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 in-memory bytes. A `Uint8Array` is read through its own view
+     * and is neither retained nor modified.
+     */
+    loadBuffer: (bytes: BinaryInput) => 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, abandoning a load in flight. */
+    setEpub: (epub: EpubBook | null) => void;
+}
+/**
+ * React hook that parses EPUB files and exposes loading/error state plus
+ * convenience loaders for buffers, files, and URLs.
+ *
+ * One load runs at a time: starting another, changing `url`, calling
+ * `setEpub` or unmounting aborts the one in flight — its fetch and parse
+ * included — and its result is dropped. Each loader resolves to the parsed
+ * EPUB, or `null` when the load failed or was superseded.
+ */
+declare function useEpub(options?: UseEpubOptions): UseEpubReturn;
 
 /**
  * Where {@link MejiroReader} places its chapter navigation: the header
@@ -292,9 +549,9 @@ type MejiroReaderMode = 'paginated' | 'scroll';
 /**
  * Two-page vs single-page rendering of a spread.
  * - `double` — always render two pages (default).
- * - `single` — render one page at a time, centered; spread indices count pages.
+ * - `single` — render one page at a time, centered.
  * - `auto` — switch based on the surface aspect ratio (single when portrait),
- *   converting the index so the page on screen stays visible.
+ *   keeping the page on screen visible.
  */
 type MejiroSpreadMode = 'double' | 'single' | 'auto';
 
@@ -320,60 +577,90 @@ type MejiroTheme = MejiroThemeName | {
     name: MejiroThemeName;
     override?: Record<string, string>;
 };
-/** Reading position exposed by {@link MejiroReaderHandle.getReadingPosition}. */
-interface ReadingPosition {
+/**
+ * Spread-level position of a reader, as {@link MejiroReaderHandle.getSpreadPosition}
+ * reports it. A spread index does not survive a re-layout; persist a
+ * {@link ReadingAnchor} to keep a reading position.
+ */
+interface SpreadPosition {
     /** 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;
+    chapterIndex: number;
+    /** Zero-based index of the layout spread holding the visible page(s). */
+    spreadIndex: number;
     /** Number of spreads in the current chapter's layout. */
-    totalSpreads: number;
+    spreadCount: number;
+    /** Number of pages in the current chapter's layout. */
+    pageCount: number;
+}
+/** Payload of the `spreadIndexChange` reader event. */
+interface MejiroReaderSpreadIndexChangeEvent {
+    /** Chapter the spread belongs to. */
+    chapterIndex: number;
+    /** Layout spread now shown. */
+    spreadIndex: number;
+}
+/** Payload of the `chapterFinished` reader event. */
+interface MejiroReaderChapterFinishedEvent {
+    /** Chapter whose last position was reached. */
+    chapterIndex: number;
+}
+/** Payload of the `turnStart` reader event. */
+interface MejiroReaderTurnStartEvent {
+    /** Navigation position the turn leaves: a page in single mode, a spread otherwise. */
+    from: number;
+}
+/** Payload of the `turnEnd` reader event. */
+interface MejiroReaderTurnEndEvent {
+    /** Navigation position the turn landed on: a page in single mode, a spread otherwise. */
+    to: number;
+}
+/** Half-open range of reading anchors, as {@link MejiroReaderHandle.getVisibleRange} returns it. */
+interface ReadingAnchorRange {
+    /** First visible position (inclusive). */
+    start: ReadingAnchor;
+    /** Position where the text after the visible range begins (exclusive). */
+    end: ReadingAnchor;
 }
 /**
  * Event payloads emitted by {@link MejiroReaderHandle.subscribe}.
  *
- * Each property maps an event name to its listener signature.
+ * Each property maps an event name to its listener signature. An event that
+ * has a prop twin is named after it without the `on` prefix.
  */
 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;
+    /** Fires once the reader shows another layout spread or chapter. */
+    spreadIndexChange: (payload: MejiroReaderSpreadIndexChangeEvent) => void;
+    /** Fires when a turn animation begins (before the new position is shown). */
+    turnStart: (payload: MejiroReaderTurnStartEvent) => void;
+    /** Fires after a turn animation completes (the new position is now shown). */
+    turnEnd: (payload: MejiroReaderTurnEndEvent) => void;
+    /** Fires when the reader reaches the last position of the current chapter. */
+    chapterFinished: (payload: MejiroReaderChapterFinishedEvent) => 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. */
+    /**
+     * Turns to a layout spread (0-based, clamped to the chapter's spreads). In
+     * single-page mode the spread opens on its right page.
+     *
+     * @throws RangeError when `spreadIndex` is not an integer.
+     */
+    goToSpread(spreadIndex: number): void;
+    /** Advance one position: a page in single-page mode, a spread otherwise. */
     next(): void;
-    /** Go back one spread. */
+    /** Go back one position. */
     prev(): void;
-    /** 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;
+    /** Jump to a chapter (clamped to the book's chapters; opens at its first spread). */
+    goToChapter(chapterIndex: number): void;
+    /** Reads the current spread-level position. */
+    getSpreadPosition(): SpreadPosition;
     /**
      * 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. A call made
+     * the anchor is resolved and the matching position 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, or
+     * Returns a promise that resolves once the position 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.
@@ -381,31 +668,28 @@ interface MejiroReaderHandle {
     goToAnchor(anchor: ReadingAnchor): Promise<void>;
     /**
      * 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.
+     * position, or `null` if the layout is not ready. When an image blocks every
+     * page shown, 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 text on the next spread
-     * that has any (or the end of the chapter when none does).
+     * current position. `end` points at the start of the text on the next
+     * position that has any (or the end of the chapter when none does).
      */
-    getVisibleRange(): {
-        start: ReadingAnchor;
-        end: ReadingAnchor;
-    } | null;
+    getVisibleRange(): ReadingAnchorRange | null;
     /**
-     * Updates book options at runtime. Same shape as {@link MejiroBook.setOptions}
-     * — font / size changes re-measure and re-layout asynchronously.
+     * Merges `patch` into the book options at runtime; font / size changes
+     * re-measure and re-layout asynchronously.
      *
      * Successive calls are coalesced into a single application; the returned
      * promise resolves once that application has settled. A failed application
      * (such as a font that measures as a fallback under `strictFontCheck`) is
-     * reported through {@link MejiroReaderProps.onError} rather than rejecting
-     * the promise.
+     * reported through {@link MejiroReaderCommonProps.onError} rather than
+     * rejecting the promise.
      */
-    setOptions(partial: Partial<BookOptions>): Promise<void>;
+    updateOptions(patch: BookOptionsPatch): Promise<void>;
     /**
      * Subscribes to a reader lifecycle event. Returns a function that
      * detaches the listener.
@@ -422,51 +706,89 @@ interface MejiroReaderHandle {
 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;
+    /** Merges a settings change into the book options and re-flows the chapter. */
+    update: (patch: BookOptionsPatch) => 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. */
+/**
+ * Props shared across every {@link MejiroReader} source mode.
+ *
+ * The position props come in value / handler pairs (`chapterIndex` /
+ * `onChapterIndexChange`, `spreadIndex` / `onSpreadIndexChange`, `anchor` /
+ * `onAnchorChange`). A value without its handler is the initial position; with
+ * its handler the pair is controlled: the reader reports each navigation
+ * through the handler and shows the value it is given, returning to it when
+ * the host keeps it unchanged (an absent index reads as 0). When `anchor` is
+ * given it decides the chapter and spread, and `chapterIndex` / `spreadIndex`
+ * are not read.
+ */
 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 }
-     * ```
+     * Book options. Optional — defaults to {@link DEFAULT_BOOK_OPTIONS}
+     * (`serif` 16px, line spacing 1.8, strict kinsoku, hanging punctuation on);
+     * the keys given here override those defaults.
      *
-     * `strictFontCheck` is read once, when the reader mounts.
+     * The keys `MejiroBook.updateOptions` accepts follow this prop by content;
+     * the construction-only keys (`strictFontCheck`, `analyzer`, …) are read
+     * once, when the reader mounts.
      */
-    options?: Partial<MejiroBookOptions>;
+    options?: Partial<BookOptions>;
     /**
-     * Page-geometry overrides forwarded to `MejiroBook.computePageSize`. Use to
+     * Page-geometry overrides forwarded to `MejiroBook.fitPageSize`. 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.
+     * `aspect`, `minWidth`, `minHeight`, `maxHeight`, and the page padding;
+     * omitted fields fall back to the built-in defaults.
      */
-    pageGeometry?: ComputePageSizeOptions;
+    pageGeometry?: FitPageSizeOptions;
     /** Font choices for the settings panel. */
-    fonts?: FontChoice[];
+    fonts?: readonly FontChoice[];
+    /**
+     * Chapter to show. The initial chapter unless
+     * {@link MejiroReaderCommonProps.onChapterIndexChange} is given, which
+     * makes it controlled. An uncontrolled chapter resets to 0 when the book
+     * changes. @defaultValue 0
+     */
+    chapterIndex?: number;
+    /**
+     * Called with the chapter the reader moves to. Passing it makes
+     * {@link MejiroReaderCommonProps.chapterIndex} controlled.
+     */
+    onChapterIndexChange?: (chapterIndex: number) => void;
+    /**
+     * Layout spread to show — always a spread of the chapter layout, also in
+     * single-page mode, where the spread opens on its right page (the first in
+     * reading order). The initial spread unless
+     * {@link MejiroReaderCommonProps.onSpreadIndexChange} is given, which makes
+     * it controlled. A spread index does not survive a re-layout; use `anchor`
+     * to keep a reading position. @defaultValue 0
+     */
+    spreadIndex?: number;
     /**
-     * Controlled chapter index. When omitted, the reader manages its own
-     * chapter state and resets to 0 on EPUB change.
+     * Called with the layout spread the reader moves to. Turning from the right
+     * to the left page of one spread in single-page mode keeps the spread, so it
+     * does not fire; follow `onAnchorChange` for page-level changes. Passing it
+     * makes {@link MejiroReaderCommonProps.spreadIndex} controlled.
      */
-    chapter?: number;
+    onSpreadIndexChange?: (spreadIndex: number) => void;
     /**
-     * Controlled spread index. When supplied, the reader is driven by this
-     * value and emits {@link MejiroReaderProps.onSpreadIdxChange} on user
-     * navigation. A spread index does not survive reflow, so persist the
-     * reading position with `useReadingPosition` and the handle's
-     * `getAnchor` / `goToAnchor` instead.
+     * Reading position to show. When given, it decides the chapter and spread
+     * and `chapterIndex` / `spreadIndex` are not read. The initial position
+     * unless {@link MejiroReaderCommonProps.onAnchorChange} is given, which
+     * makes it controlled.
      */
-    spreadIdx?: number;
+    anchor?: ReadingAnchor | null;
+    /**
+     * Called with the anchor at the start of the text the reader moves to, on
+     * each move of the visible page(s) or chapter. Passing it makes
+     * {@link MejiroReaderCommonProps.anchor} controlled. Pair with
+     * `useReadingPosition` to persist the position.
+     */
+    onAnchorChange?: (anchor: ReadingAnchor) => void;
     /**
      * Visual theme preset, or `{ name, override }` to layer custom
      * CSS variables on top of a preset. @defaultValue 'light'
@@ -482,9 +804,8 @@ interface MejiroReaderCommonProps {
     mode?: MejiroReaderMode;
     /**
      * 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.
+     * page at a time; `auto` flips to `single` for portrait viewports, keeping
+     * the page on screen visible.
      */
     spreadMode?: MejiroSpreadMode;
     /**
@@ -494,7 +815,7 @@ interface MejiroReaderCommonProps {
      * 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'
+     * {@link MejiroReaderCommonProps.pageGeometry} if you still want them. @defaultValue 'fill'
      */
     fit?: MejiroReaderFit;
     /**
@@ -523,10 +844,12 @@ interface MejiroReaderCommonProps {
      */
     limits?: Partial<EpubParseLimits>;
     /**
-     * Custom EPUB fetcher used in place of the global `fetch`. Overrides
-     * {@link fetchOptions} when set.
+     * Custom EPUB fetcher used in place of the global `fetch`; resolves to the
+     * raw bytes. `options.signal` aborts when the load is superseded or the
+     * reader unmounts. Overrides {@link MejiroReaderCommonProps.fetchOptions}
+     * when set.
      */
-    fetchEpub?: (url: string) => Promise<ArrayBuffer>;
+    fetchEpub?: (url: string, options: FetchEpubOptions) => Promise<BinaryInput>;
     /**
      * Built-in locale for UI strings (`'en'` / `'ja'`). Pair with `messages`
      * to override individual strings. Defaults to the nearest `MejiroI18nProvider`
@@ -539,26 +862,19 @@ interface MejiroReaderCommonProps {
      * without re-implementing every label.
      */
     messages?: Partial<MejiroMessages>;
-    /** Header title text. @defaultValue 'mejiro' */
+    /**
+     * Header title text. The header — chapter select, stats, Open / Image /
+     * Settings buttons — is drawn only when a title or a
+     * {@link MejiroReaderCommonProps.logo} is given.
+     */
     title?: string;
-    /** Header subtitle. @defaultValue `messages.logoSubtitle` */
+    /** Header subtitle, shown under the title. @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}`.
+     * Header slot replacing the default logo block (title + subtitle). Giving
+     * it draws the header; pass `null` to draw the header without a logo.
      */
     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
@@ -566,90 +882,85 @@ interface MejiroReaderCommonProps {
      * @defaultValue false
      */
     enableDropZone?: boolean;
-    /** Show the chapter selector in the header. @defaultValue `!bare` */
-    enableChapterNav?: boolean;
     /**
-     * Where to render the built-in chapter navigation.
+     * Where to render the built-in chapter navigation; `'none'` renders
+     * neither. The `'select'` dropdown sits in the header.
      * @defaultValue 'select'
      */
     chapterNavMode?: MejiroChapterNavMode;
-    /** Show the settings panel toggle. @defaultValue `!bare` */
-    enableSettings?: boolean;
+    /**
+     * Show the settings panel and its header toggle. @defaultValue true
+     */
+    showSettings?: 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
+     * "Settings" button still toggles the panel. `showSettings` 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 */
+    /** Show the header button that places a sample image overlay. @defaultValue false */
+    showImageOverlayButton?: boolean;
+    /** Show the layout statistics in the header. @defaultValue false */
+    showStats?: boolean;
+    /**
+     * Bind ArrowLeft / ArrowRight to navigation while focus is inside the
+     * reader. The reader root takes focus for this. @defaultValue true
+     */
     enableKeyboard?: boolean;
-    /** Show the "n / total" indicator. @defaultValue `!bare` */
-    enablePageIndicator?: boolean;
+    /** Show the "n / total" indicator. @defaultValue true */
+    showPageIndicator?: 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
+     * {@link MejiroReaderCommonProps.showPageIndicator} "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
+     * `chapterIndex` matches the current chapter is converted to spread-local
      * rectangles via `ChapterLayout.selectionRects`; the rectangles landing on
      * the spread on screen are 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;
-    }>;
+     * {@link useAnnotations} for persistence.
+     */
+    annotations?: readonly ReaderAnnotation[];
     /** Called after a successful EPUB load. */
-    onLoad?: (book: EpubBook) => void;
+    onLoad?: (epub: EpubBook) => void;
     /**
      * Called when loading or parsing an EPUB fails, and when applying an option
      * 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. */
-    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 moves from one spread to another within the shown
-     * book (a change of chapter or spread index, like `spreadChanged`). Receives
-     * the anchor of the spread that was just left and the dwell time in
+    /**
+     * Called when the reader moves from one position to another within the
+     * shown book (a change of chapter or navigation position). Receives the
+     * anchor of the position that was just left and the dwell time in
      * milliseconds (computed via `performance.now()`). A book swap and unmount
-     * do not report the spread being left. Useful for engagement analytics.
+     * do not report the position being left. 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}.
+     * Called with the chapter index when the reader reaches the last position
+     * of a chapter. Same trigger as the `chapterFinished` event on
+     * {@link MejiroReaderHandle.subscribe}.
      */
-    onChapterCompleted?: (chapter: number) => void;
+    onChapterFinished?: (chapterIndex: 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).
+ * Parsed-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 {
+interface MejiroReaderParsedProps extends MejiroReaderCommonProps {
     /** Pre-parsed EPUB. Cannot be combined with `epubUrl` / `manuscript`. */
     epub: EpubBook | null;
+    /** Not accepted alongside `epub`. */
     epubUrl?: never;
+    /** Not accepted alongside `epub`. */
     manuscript?: never;
 }
 /**
@@ -657,19 +968,24 @@ interface MejiroReaderControlledProps extends MejiroReaderCommonProps {
  * Use this for "just open this book" scenarios.
  */
 interface MejiroReaderUrlProps extends MejiroReaderCommonProps {
-    /** EPUB URL fetched on mount. Cannot be combined with `epub` / `manuscript`. */
+    /** EPUB URL, fetched on mount and whenever it changes. Cannot be combined with `epub` / `manuscript`. */
     epubUrl: string;
+    /** Not accepted alongside `epubUrl`. */
     epub?: never;
+    /** Not accepted alongside `epubUrl`. */
     manuscript?: never;
 }
 /**
- * File-source variant: the reader exposes its drop zone / file picker.
+ * Picker-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 {
+interface MejiroReaderPickerProps extends MejiroReaderCommonProps {
+    /** Not accepted by the picker source. */
     epub?: never;
+    /** Not accepted by the picker source. */
     epubUrl?: never;
+    /** Not accepted by the picker source. */
     manuscript?: never;
 }
 /**
@@ -683,30 +999,30 @@ interface MejiroReaderManuscriptProps extends MejiroReaderCommonProps {
     manuscript: readonly ManuscriptChapter[];
     /** Manuscript notation dialect. @defaultValue `'mejiro'` */
     dialect?: ManuscriptDialect;
+    /** Not accepted alongside `manuscript`. */
     epub?: never;
+    /** Not accepted alongside `manuscript`. */
     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;
+type MejiroReaderProps = MejiroReaderParsedProps | MejiroReaderUrlProps | MejiroReaderPickerProps | 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.
+ * reader: the header (drawn when a `title` or `logo` is given), chapter
+ * navigation, settings, page indicator and keyboard navigation scoped to the
+ * reader root. The `ref` exposes {@link MejiroReaderHandle} for imperative
+ * navigation.
+ *
+ * ```tsx
+ * const reader = useRef<MejiroReaderHandle>(null);
+ * reader.current?.goToSpread(12);
+ * ```
  */
 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. */
@@ -716,53 +1032,18 @@ interface ManuscriptAutosaveDraft {
     /** Selected cover image, or `null` when none is set. */
     cover: File | null;
     /** Chapters in reading order, as plain (non-reactive) copies. */
-    chapters: ManuscriptEditorChapter[];
+    chapters: readonly ManuscriptChapter$1[];
 }
 /**
- * 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.
+ * The {@link MejiroReader} props an editor forwards to its live preview. The
+ * book, the chapter and its change handler, `fonts` and `onError` are driven
+ * by the editor itself.
  */
-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>;
-    /** Theme forwarded to the embedded reader preview. */
-    theme?: MejiroTheme;
-    /** Custom settings controls forwarded to the embedded reader preview. */
-    renderSettings?: (slot: MejiroReaderSettingsSlot) => ReactNode;
-    /**
-     * 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;
-    /** Render the preview without any reader chrome. */
-    bare?: boolean;
-}
+type ManuscriptPreviewProps = Pick<MejiroReaderCommonProps, 'title' | 'subtitle' | 'logo' | 'theme' | 'options' | 'pageGeometry' | 'mode' | 'spreadMode' | 'fit' | 'chapterNavMode' | 'pageNumbers' | 'showSettings' | 'renderSettings' | 'showStats' | 'showPageIndicator' | 'enableKeyboard' | 'enableSurfaceTap' | 'locale' | 'messages' | 'fallback'>;
 /** Props for {@link MejiroManuscriptEditor}. */
 interface MejiroManuscriptEditorProps {
     /** Font choices passed to the preview reader. */
-    fonts?: FontChoice[];
+    fonts?: readonly FontChoice[];
     /**
      * Title. When `onTitleChange` is supplied, this is the controlled value
      * (changes propagate from parent to the input). Otherwise it is the
@@ -785,8 +1066,17 @@ interface MejiroManuscriptEditorProps {
     cover?: File | null;
     /** Called whenever the cover changes. Enables controlled mode. */
     onCoverChange?: (cover: File | null) => void;
-    /** Initial chapters. */
-    chapters?: ManuscriptEditorChapter[];
+    /**
+     * Chapters. Controlled when `onChaptersChange` is supplied; otherwise the
+     * initial chapters. Without any, the editor starts with one chapter titled
+     * and filled from the active message catalog.
+     */
+    chapters?: readonly ManuscriptChapter$1[];
+    /**
+     * Called with the whole chapter list after each chapter edit, addition,
+     * removal or reorder. Enables controlled mode for `chapters`.
+     */
+    onChaptersChange?: (chapters: readonly ManuscriptChapter$1[]) => void;
     /**
      * Manuscript notation dialect. Drives the notation highlighter, the live
      * preview, and the exported EPUB alike, so the whole editor interprets one
@@ -794,17 +1084,16 @@ interface MejiroManuscriptEditorProps {
      */
     dialect?: ManuscriptDialect;
     /**
-     * Called whenever the chapter draft settles (debounced by
-     * {@link MejiroManuscriptEditorProps.autosaveDelay}). Use to persist drafts
-     * to localStorage, IndexedDB, or upload to a server.
+     * Called whenever the draft settles (debounced by
+     * {@link MejiroManuscriptEditorProps.autosaveDebounceMs}). Use to persist
+     * drafts to localStorage, IndexedDB, or upload to a server.
      */
     onAutosave?: (draft: ManuscriptAutosaveDraft) => void | Promise<void>;
     /** Autosave debounce in milliseconds. @defaultValue 800 */
-    autosaveDelay?: number;
+    autosaveDebounceMs?: 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.
+     * Props forwarded to the embedded {@link MejiroReader} preview. The preview
+     * header shows the work's title unless `title` is given here.
      */
     previewProps?: ManuscriptPreviewProps;
     /**
@@ -815,8 +1104,8 @@ interface MejiroManuscriptEditorProps {
      * references that must be fetched at export time.
      */
     assetResolver?: AssetResolver;
-    /** Called after export completes. */
-    onExport?: (buffer: ArrayBuffer) => void;
+    /** Called with the exported bytes, before the download. */
+    onExport?: (bytes: Uint8Array<ArrayBuffer>) => void;
     /**
      * Called when the EPUB export fails (asset resolution, cover reading, or
      * packaging) or the preview reader fails. The same error is shown in the editor panel, so hosts only
@@ -831,14 +1120,138 @@ interface MejiroManuscriptEditorProps {
     panelSide?: 'left' | 'right';
 }
 /** 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, dialect, onAutosave, autosaveDelay, previewProps, assetResolver, onExport, onError, panelSide, }: MejiroManuscriptEditorProps): ReactNode;
+declare function MejiroManuscriptEditor({ fonts, title: titleProp, onTitleChange, author: authorProp, onAuthorChange, cover: coverProp, onCoverChange, chapters: chaptersProp, onChaptersChange, dialect, onAutosave, autosaveDebounceMs, previewProps, assetResolver, onExport, onError, panelSide, }: MejiroManuscriptEditorProps): ReactNode;
+
+/** Props for {@link MejiroEditor}. */
+interface MejiroEditorProps {
+    /** EPUB URL, loaded on mount and whenever it changes. */
+    epubUrl?: string;
+    /**
+     * Extra options merged into the `fetch` call that loads `epubUrl`. Useful
+     * for sending bearer tokens or cookies (`credentials: 'include'`).
+     */
+    fetchOptions?: RequestInit;
+    /**
+     * Custom EPUB fetcher used in place of the global `fetch`; resolves to the
+     * raw bytes. `options.signal` aborts when the load is superseded or the
+     * editor unmounts. Overrides {@link MejiroEditorProps.fetchOptions} when set.
+     */
+    fetchEpub?: (url: string, options: FetchEpubOptions) => Promise<BinaryInput>;
+    /** Font choices passed to the preview reader. */
+    fonts?: readonly FontChoice[];
+    /**
+     * Allow editing paragraph text (the "Proofread" section). When `false` and
+     * `enableRuby` is on, the paragraph text stays visible read-only so a ruby
+     * base range can still be selected.
+     * @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;
+    /**
+     * Show the export button. SaaS publishers can hide it to restrict downloads
+     * (e.g. server-side export only).
+     * @defaultValue true
+     */
+    showExportButton?: boolean;
+    /** What the export button produces and whether it is offered as a download. */
+    exportPolicy?: ExportPolicy;
+    /**
+     * Resolves URL-only image assets (`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;
+    /**
+     * Archive resource limits applied while opening an EPUB. Raise them for
+     * trusted, image-heavy books; tighten them for a public drop zone. Omitted
+     * fields keep their `DEFAULT_EPUB_PARSE_LIMITS` value.
+     */
+    limits?: Partial<EpubParseLimits>;
+    /**
+     * Props forwarded to the embedded {@link MejiroReader} preview (theme,
+     * options, chrome). The book, the chapter and its change handler, `fonts`
+     * and `onError` remain driven by the editor.
+     */
+    previewProps?: ManuscriptPreviewProps;
+    /** Called after an EPUB is loaded into the editor. */
+    onLoad?: (editor: EditableEpub) => void;
+    /** Called with the exported bytes, after `exportPolicy.transform`, before any download. */
+    onExport?: (bytes: Uint8Array<ArrayBuffer>) => void;
+    /**
+     * Called when loading, image insertion, export or the preview reader fails.
+     * The error is also shown in the editor until a later load, image insertion
+     * or export succeeds.
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Restrictions on what {@link MejiroEditor}'s export produces. Applied in
+ * this order: `watermark` (written into the exported copy only, never into the
+ * edited document) → `transform` (replaces the bytes with its result) →
+ * `download`.
+ */
+interface ExportPolicy {
+    /**
+     * Offer the exported bytes as a browser download. With `false` the bytes are
+     * still produced and `onExport` still fires — use it to ship the bytes
+     * elsewhere (e.g. uploading to a backend).
+     * @defaultValue true
+     */
+    download?: boolean;
+    /**
+     * Transforms the exported bytes before `onExport` and the download.
+     * Typically a server round-trip that returns a DRM-wrapped EPUB.
+     */
+    transform?: (bytes: Uint8Array<ArrayBuffer>) => Uint8Array<ArrayBuffer> | Promise<Uint8Array<ArrayBuffer>>;
+    /**
+     * Visible watermark text. Each exported chapter starts with a paragraph
+     * holding it after a `[mejiro-watermark]` prefix, so a downstream renderer
+     * can theme it by that prefix. An empty string adds nothing.
+     */
+    watermark?: string;
+}
+/** EPUB editor UI for proofreading, ruby edits, image insertion, and export. */
+declare function MejiroEditor({ epubUrl, fetchOptions, fetchEpub, fonts, enableProofread, enableRuby, enableImages, showExportButton, exportPolicy, assetResolver, limits, previewProps, onLoad, onExport, onError, }: MejiroEditorProps): ReactNode;
+
+/** Props for {@link MejiroImagePlaceholder}; other `div` attributes go to the root element. */
+interface MejiroImagePlaceholderProps extends ComponentPropsWithoutRef<'div'> {
+    /** Position and size of the placeholder (px). */
+    rect: ImageOverlayRect;
+    /** Label inside the placeholder. @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 with drag and resize affordances, drawn where
+ * an image overlay excludes text. Pair the pointer handlers with
+ * {@link useImageOverlay}.
+ */
+declare const MejiroImagePlaceholder: react.ForwardRefExoticComponent<MejiroImagePlaceholderProps & react.RefAttributes<HTMLDivElement>>;
 
-/** Props for {@link MejiroNotationHighlighter}. */
-interface MejiroNotationHighlighterProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'onChange'> {
+/**
+ * Props for {@link MejiroNotationHighlighter}; other `textarea` attributes,
+ * the native `onChange` included, go to the textarea.
+ */
+interface MejiroNotationHighlighterProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value'> {
     /** Source manuscript text. */
     value: string;
-    /** Called whenever the textarea content changes. */
-    onChange: (next: string) => void;
+    /** Called with the new text whenever the textarea content changes, and when an IME composition ends. */
+    onValueChange: (next: string) => void;
     /** Manuscript notation dialect. @defaultValue `'mejiro'` */
     dialect?: ManuscriptDialect;
     /** Class applied to the wrapper element. */
@@ -859,8 +1272,8 @@ interface MejiroNotationHighlighterProps extends Omit<TextareaHTMLAttributes<HTM
  */
 declare const MejiroNotationHighlighter: react.ForwardRefExoticComponent<MejiroNotationHighlighterProps & react.RefAttributes<HTMLTextAreaElement>>;
 
-/** Props for the MejiroPage component. */
-interface MejiroPageProps {
+/** Props for the MejiroPage component; other `div` attributes go to the root element. */
+interface MejiroPageProps extends ComponentPropsWithoutRef<'div'> {
     /** Render page data from `buildRenderPage()`. */
     page: RenderPage;
     /** Additional CSS class name for the root element. */
@@ -874,25 +1287,36 @@ interface MejiroPageProps {
  * Converts a `RenderPage` data structure into DOM elements using
  * `mejiro-` prefixed CSS classes for layout.
  */
-declare function MejiroPage({ page, className, style }: MejiroPageProps): ReactNode;
+declare const MejiroPage: react.ForwardRefExoticComponent<MejiroPageProps & react.RefAttributes<HTMLDivElement>>;
 
-/** Props for {@link MejiroPageIndicator}. */
-interface MejiroPageIndicatorProps {
-    /** Current spread (1-based). */
-    current: number;
-    /** Total number of spreads. */
-    total: number;
+/** Props for {@link MejiroPageIndicator}; other `div` attributes go to the root element. */
+interface MejiroPageIndicatorProps extends ComponentPropsWithoutRef<'div'> {
+    /** Zero-based navigation index, as `useSpread` reports it in `index`. Shown one-based. */
+    index: number;
+    /** Number of navigation positions, as `useSpread` reports it in `count`. */
+    count: number;
 }
-/** Displays "current / total" spread position under the book. */
-declare function MejiroPageIndicator({ current, total }: MejiroPageIndicatorProps): ReactNode;
+/** Displays the one-based position out of the total, e.g. `3 / 12`, under the book. */
+declare const MejiroPageIndicator: react.ForwardRefExoticComponent<MejiroPageIndicatorProps & react.RefAttributes<HTMLDivElement>>;
 
-/** Props for the MejiroPageView component. */
-interface MejiroPageViewProps {
+/** Props for the MejiroPageView component; other `div` attributes go to the root element. */
+interface MejiroPageViewProps extends ComponentPropsWithoutRef<'div'> {
     /** Page result from {@link ChapterLayout.getSpread} or {@link ChapterLayout.getPage}. */
     result: PageResult;
-    /** CSS font family for slot-based rendering (used when images are present). */
+    /**
+     * Layout the page comes from. When given, its `typography` supplies
+     * `fontFamily` and `lineSpacing` when they are left unset.
+     */
+    layout?: ChapterLayout;
+    /**
+     * CSS font family for slot-based rendering (used when images are present).
+     * Defaults to `layout.typography.fontFamily`.
+     */
     fontFamily?: FontFamily;
-    /** Line spacing multiplier for slot-based rendering (used when images are present). */
+    /**
+     * Line spacing multiplier for slot-based rendering (used when images are
+     * present). Defaults to `layout.typography.lineSpacing`.
+     */
     lineSpacing?: number;
     /**
      * Force slot-based rendering even when `result.hasImages` is false.
@@ -918,77 +1342,26 @@ interface MejiroPageViewProps {
  * <MejiroPageView result={spread.right} fontFamily="serif" lineSpacing={1.8} />
  * ```
  */
-declare function MejiroPageView({ result, fontFamily, lineSpacing, slotMode, className, style, }: MejiroPageViewProps): ReactNode;
+declare const MejiroPageView: react.ForwardRefExoticComponent<MejiroPageViewProps & react.RefAttributes<HTMLDivElement>>;
 
-/** 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 {
+/** Props for {@link MejiroScrollView}; other `div` attributes go to the scroll container. */
+interface MejiroScrollViewProps extends ComponentPropsWithoutRef<'div'> {
     /**
-     * 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.
+     * Layout containing the pages to render. Its `geometry` and `typography`
+     * supply every page-size and font prop left unset.
      */
-    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. */
     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. */
+    /** Page width in px. Defaults to `layout.geometry.pageWidth`. */
+    pageWidth?: number;
+    /** Page height in px. Defaults to `layout.geometry.pageHeight`. */
+    pageHeight?: number;
+    /** Content area height (px). Defaults to `layout.geometry.contentHeight`. */
+    contentHeight?: number;
+    /** CSS font family applied to the content. Defaults to `layout.typography.fontFamily`. */
     fontFamily?: FontFamily;
-    /** Font size override (px). */
+    /** Font size (px). Defaults to `layout.typography.fontSize`. */
     fontSize?: number;
-    /** Line spacing multiplier. */
+    /** Line spacing multiplier. Defaults to `layout.typography.lineSpacing`. */
     lineSpacing?: number;
     /** Force slot-based rendering on every page. */
     slotMode?: boolean;
@@ -996,7 +1369,7 @@ interface MejiroScrollViewProps {
      * 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, source: 'user' | 'programmatic') => void;
+    onVisiblePageChange?: (pageIndex: number, source: 'user' | 'programmatic') => 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.
@@ -1007,22 +1380,20 @@ interface MejiroScrollViewProps {
     /**
      * 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.
+     * `pageIndex` addresses. An entry may carry a `color` fill.
      */
-    selectionRects?: readonly (AnchorRect & {
-        color?: string;
-    })[];
+    selectionRects?: readonly SelectionRect[];
     /** Zero-based spread whose pages carry {@link MejiroScrollViewProps.images}. */
-    spreadIdx?: number;
+    spreadIndex?: number;
     /**
-     * Image overlays on the spread at {@link MejiroScrollViewProps.spreadIdx}.
+     * Image overlays on the spread at {@link MejiroScrollViewProps.spreadIndex}.
      * 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`
+     * also what re-reads the pages; `useImageOverlay`'s `currentImages`
      * provides one on every change.
      */
-    images?: MultiImageItem[];
+    images?: readonly MultiImageItem[];
     /**
      * Which pages print their page number in the running head, by the same rule
      * as the paginated reader. @defaultValue 'both'
@@ -1041,10 +1412,10 @@ 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, selectionRects, spreadIdx, images, pageNumbers, onImagePointerDown, onImageResizePointerDown, onImageClose, }: MejiroScrollViewProps): ReactNode;
+declare const MejiroScrollView: react.ForwardRefExoticComponent<MejiroScrollViewProps & react.RefAttributes<HTMLDivElement>>;
 
-/** Props for {@link MejiroSelectionLayer}. */
-interface MejiroSelectionLayerProps {
+/** Props for {@link MejiroSelectionLayer}; other `div` attributes go to the root element. */
+interface MejiroSelectionLayerProps extends ComponentPropsWithoutRef<'div'> {
     /**
      * Spread-local rectangles to highlight. Compute these via
      * {@link ChapterLayout.selectionRects} and pass the full array; the layer
@@ -1054,9 +1425,7 @@ interface MejiroSelectionLayerProps {
      * fill. Entries without one take the fill from the shipped stylesheet
      * (`.mejiro-selection-rect`, themeable via `--mejiro-selection-bg`).
      */
-    rects: readonly (AnchorRect & {
-        color?: string;
-    })[];
+    rects: readonly SelectionRect[];
     /** Which page-side this layer is rendered into. */
     side: 'right' | 'left';
     /** Optional class added to the outer wrapper. */
@@ -1069,289 +1438,144 @@ interface MejiroSelectionLayerProps {
     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. Defaults to the active message catalog's `shelfTitle`. */
-    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;
-
-/** 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, 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
-     * through to {@link MejiroPageView}'s automatic choice: slot mode for pages
-     * with images, native `writing-mode: vertical-rl` otherwise.
-     */
-    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;
-    /**
-     * Zero-based index of the spread being rendered. Rectangles passed through
-     * {@link MejiroSpreadProps.selectionRects} carry spread-local coordinates,
-     * so this is what scopes them to this spread. When omitted, every supplied
-     * rectangle is painted.
-     */
-    spreadIdx?: number;
-    /**
-     * Selection rectangles to render as a highlight overlay. Compute via
-     * {@link ChapterLayout.selectionRects}. Entries whose `spreadIdx` differs
-     * from {@link MejiroSpreadProps.spreadIdx} are ignored. An entry may carry
-     * a `color` that becomes that rectangle's fill.
-     */
-    selectionRects?: readonly (AnchorRect & {
-        color?: string;
-    })[];
-    /**
-     * 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;
-    /**
-     * 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
-     * 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 (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`.
+ * 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 const MejiroSelectionLayer: react.ForwardRefExoticComponent<MejiroSelectionLayerProps & react.RefAttributes<HTMLDivElement>>;
+
+/** 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 with the new active volume whenever it changes. */
+    onVolumeChange?: (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. */
+    volume: VolumeInfo<T> | null;
+    /** Index of the active volume in the list, or `-1` for an empty library. */
+    volumeIndex: 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;
+    /** Make the volume with the given ID active. No-op when the ID is not in the list. */
+    selectVolume(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}; other `section` attributes go to the root
+ * element, except `title`, which here is the heading text.
+ */
+interface MejiroShelfProps<T = unknown> extends ComponentPropsWithoutRef<'section'> {
+    /** Volumes to display. */
+    volumes: readonly VolumeInfo<T>[];
+    /** ID of the currently active volume (highlighted in the grid). */
+    currentId?: string;
+    /** Called with the volume the user picks. */
+    onVolumeSelect?: (volume: VolumeInfo<T>) => void;
+    /** Heading shown above the grid. Defaults to the active message catalog's `shelfTitle`. */
+    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 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;
+declare const MejiroShelf: <T = unknown>(props: MejiroShelfProps<T> & RefAttributes<HTMLElement>) => ReactNode;
 
-/** Props for {@link MejiroStats}. */
-interface MejiroStatsProps {
+/** Props for {@link MejiroStats}; other `span` attributes go to the root element. */
+interface MejiroStatsProps extends ComponentPropsWithoutRef<'span'> {
     /** Chapter currently displayed. */
     chapter: EpubChapter | null;
-    /** Total page count for the current layout. */
-    totalPages: number;
+    /** Number of pages in the current layout. */
+    pageCount: 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';
+    /** Characters per minute used for the reading-time estimate. @defaultValue 600 */
+    charsPerMinute?: number;
+    /**
+     * Locale whose catalog spells the reading-time units. Defaults to the
+     * catalog of the nearest `MejiroI18nProvider`.
+     */
+    locale?: MejiroLocale;
 }
 /** Compact reading stats line. */
-declare function MejiroStats({ chapter, totalPages, elapsedMs, fontLabel, showReadingTime, cpm, readingTimeLocale, }: MejiroStatsProps): ReactNode;
+declare const MejiroStats: react.ForwardRefExoticComponent<MejiroStatsProps & react.RefAttributes<HTMLSpanElement>>;
 
-/** Props for {@link MejiroToc}. */
-interface MejiroTocProps {
+/**
+ * Props for {@link MejiroToc}; other `nav` attributes go to the root element,
+ * except `title`, which here is the heading text.
+ */
+interface MejiroTocProps extends ComponentPropsWithoutRef<'nav'> {
     /** 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;
+    showSearch?: boolean;
     /** Heading displayed above the list. Defaults to the active message catalog's `tocTitle`. */
     title?: string;
     /** 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;
-}
-/**
- * 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;
-
-/** Minimal storage interface required by {@link useAnnotations}. */
-type AnnotationsStorage = MejiroStorage;
-/** 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.
-     * The latest reference is always used, so an object literal recreated on
-     * every render is safe — only `key` triggers a re-hydration.
-     */
-    storage?: AnnotationsStorage;
-    /**
-     * Debounce delay (ms): the latest value is written this long after the last change. A pending write is flushed on page hide, key change and unmount. @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;
+    /** Called with the zero-based index of the chapter the user picks. */
+    onChapterSelect?: (chapterIndex: number) => 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.
- *
- * ```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} />
- * ```
+ * Searchable table of contents that highlights the chapter of the current
+ * reading anchor. For a compact chapter picker, use {@link MejiroChapterNav}.
  */
-declare function useAnnotations(options: UseAnnotationsOptions): UseAnnotationsReturn;
+declare const MejiroToc: react.ForwardRefExoticComponent<MejiroTocProps & react.RefAttributes<HTMLElement>>;
 
 /** Options for {@link useChapterLayout}. */
 interface UseChapterLayoutOptions {
+    /** The parsed EPUB whose chapter is laid out; `null` lays nothing out. */
+    epub: EpubBook | null;
+    /** Zero-based index of the chapter to lay out. */
+    chapterIndex: number;
+    /** The reading surface the pages are sized against. */
+    surface: RefObject<HTMLElement | null>;
     /** 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;
+    resizeDebounceMs?: number;
     /**
      * Resolver for page-geometry overrides forwarded to
-     * {@link MejiroBook.computePageSize} — e.g. to shrink the reserved
+     * {@link MejiroBook.fitPageSize} — 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;
+    pageGeometry?: () => FitPageSizeOptions | undefined;
     /**
      * Capture the reading position from the outgoing layout, just before a
      * **reflow** (non-blank) re-layout replaces it. The anchor is held in
@@ -1374,8 +1598,11 @@ interface UseChapterLayoutOptions {
      */
     onError?: (error: Error) => void;
 }
-/** Options for {@link UseChapterLayoutReturn.recompute}. */
-interface RecomputeOptions {
+/**
+ * Options for the `recompute` of {@link useChapterLayout} and
+ * {@link useManuscriptLayout}.
+ */
+interface ChapterLayoutRecomputeOptions {
     /**
      * 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
@@ -1384,20 +1611,11 @@ interface RecomputeOptions {
      */
     blank?: boolean;
 }
-/** 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}. */
 interface UseChapterLayoutReturn {
     /** Current layout, or `null` before the first computation. */
     layout: ChapterLayout | null;
-    /** Page width in pixels. */
+    /** Page width in pixels, as {@link MejiroBook.fitPageSize} measured it. */
     pageWidth: number;
     /** Page height in pixels. */
     pageHeight: number;
@@ -1405,11 +1623,16 @@ interface UseChapterLayoutReturn {
     contentHeight: number;
     /** Most recent layout time (ms). */
     elapsedMs: number;
+    /**
+     * Failure of the most recent layout of the current source, whichever path
+     * started it; `null` once a layout succeeds or the source changes.
+     */
+    error: Error | null;
     /**
      * Force a fresh layout computation. A failure goes to `onError` when one is
      * supplied; otherwise the returned promise rejects.
      */
-    recompute: (opts?: RecomputeOptions) => Promise<void>;
+    recompute: (opts?: ChapterLayoutRecomputeOptions) => Promise<void>;
     /**
      * Anchor captured by `capturePosition` before the most recent reflow,
      * awaiting restoration into the new layout. `restorePosition`, when given,
@@ -1429,9 +1652,11 @@ interface UseChapterLayoutReturn {
  *
  * 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**.
+ * {@link ResizeObserver}: the first observation of a positive box 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**. While the surface measures zero wide or high,
+ * nothing is measured or laid out.
  *
  * Size and option changes lay the chapter out again rather than calling
  * `ChapterLayout.resize()`, so page geometry is re-derived from the surface and
@@ -1445,23 +1670,36 @@ interface UseChapterLayoutReturn {
  * composable.
  *
  * @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.
+ * @param options - The EPUB, chapter and surface to lay out, plus behavior overrides.
  */
-declare function useChapterLayout(book: MejiroBook, epub: EpubBook | null, chapterIndex: number, surface: RefObject<HTMLElement | null>, options?: UseChapterLayoutOptions): UseChapterLayoutReturn;
+declare function useChapterLayout(book: MejiroBook, options: UseChapterLayoutOptions): UseChapterLayoutReturn;
 
 /** Options for {@link useEditableEpub}. */
 interface UseEditableEpubOptions {
-    /** URL fetched and loaded on mount. */
-    defaultUrl?: string;
+    /**
+     * URL to load. Fetched on mount and again whenever it changes; clearing it
+     * abandons a load still in flight and keeps the current editor.
+     */
+    url?: string;
     /** Called after a successful load. */
     onLoad?: (editor: EditableEpub) => void;
-    /** Called when a load fails. */
+    /**
+     * Called when a load or an export fails. A `MejiroError` is passed as
+     * thrown; a failed export also rejects the promise `exportEpub` returned.
+     */
     onError?: (error: Error) => void;
-    /** Called after export completes. */
-    onExport?: (buffer: ArrayBuffer) => void;
+    /** Called with the EPUB bytes after an export completes. */
+    onExport?: (bytes: Uint8Array<ArrayBuffer>) => 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`. Resolves to the
+     * raw bytes. Overrides {@link UseEditableEpubOptions.fetchOptions} when set.
+     */
+    fetchEpub?: (url: string, options: FetchEpubOptions) => Promise<BinaryInput>;
     /**
      * Archive resource limits applied while opening an EPUB. Raise them for
      * trusted, image-heavy books; tighten them for a public drop zone. Omitted
@@ -1476,131 +1714,101 @@ interface UseEditableEpubOptions {
 }
 /** Return value of {@link useEditableEpub}. */
 interface UseEditableEpubReturn {
-    /** Loaded editor, or `null` before any load. */
+    /**
+     * Loaded editing session, or `null` before any load. Edits made on it
+     * directly are picked up like the hook's own: the hook subscribes to it and
+     * advances `revision` on every change.
+     */
     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;
+    epub: EditableEpubBook | null;
+    /**
+     * The document projected onto the reader's {@link EpubBook} shape, rebuilt
+     * on every change, for feeding a preview reader.
+     */
+    previewEpub: EpubBook | null;
     /** Whether a load is in progress. */
     loading: boolean;
     /** Whether an export is in progress. */
     exporting: boolean;
-    /** Last load error, if any. */
+    /** Last load or export error, if any. */
     error: Error | null;
-    /** Counter bumped on every load, edit, undo and redo. */
+    /** Counter advanced on every load and every change to the document. */
     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. */
+    history: EditHistoryState | null;
+    /** Block 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. */
+    /** The paragraph block at `selection`, or `null` when no paragraph is selected. */
+    selectedParagraph: EditableParagraphBlock | null;
+    /** Moves the selection, clamped to the loaded document. */
     setSelection: (selection: EditableEpubSelection) => void;
-    /** Loads an EPUB from an in-memory buffer. */
-    loadBuffer: (buffer: ArrayBuffer) => Promise<EditableEpub | null>;
+    /**
+     * Loads an EPUB from in-memory bytes. A `Uint8Array` is read through its own
+     * view and is neither retained nor modified.
+     */
+    loadBuffer: (bytes: BinaryInput) => 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. */
+    /** Fetches and loads an EPUB; a non-2xx response is reported as `fetch-failed`. */
     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. */
+    /**
+     * Applies `patch` to the selected paragraph, as
+     * {@link EditableEpub.updateParagraph} does. Does nothing when no block is
+     * selected.
+     */
+    updateParagraph: (patch: ParagraphPatch) => void;
+    /** Replaces the selected paragraph's inline annotations. Does nothing when no block is selected. */
     setInlineAnnotations: (inlineAnnotations: readonly InlineAnnotation[]) => void;
-    /** Inserts an image into the selected chapter. */
-    addImage: (image: AddImageInput | EditableEpubImage) => void;
+    /**
+     * Inserts an image into the selected chapter, as {@link EditableEpub.addImage}
+     * does, and returns the stored block; `null` before any load.
+     */
+    addImage: (image: AddImageInput) => EditableImageBlock | null;
     /** 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. */
-declare function useEditableEpub(options?: UseEditableEpubOptions): UseEditableEpubReturn;
-
-/** Options for {@link useEpub}. */
-interface UseEpubOptions {
-    /** URL fetched on mount. */
-    defaultUrl?: string;
-    /** Called after a successful load. */
-    onLoad?: (book: EpubBook) => void;
-    /** 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
-     * 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>;
-    /**
-     * Archive resource limits applied while opening an EPUB. Raise them for
-     * trusted, image-heavy books; tighten them for a public drop zone. Omitted
-     * fields keep their `DEFAULT_EPUB_PARSE_LIMITS` value.
+     * Packages the edited document as EPUB bytes; `null` before any load. A
+     * failure is stored in `error`, passed to `onError` and rejects.
      */
-    limits?: Partial<EpubParseLimits>;
-}
-/** 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;
+    exportEpub: (options?: EditableEpubExportOptions) => Promise<Uint8Array<ArrayBuffer> | null>;
 }
 /**
- * React hook that parses EPUB files and exposes loading/error state plus
- * convenience loaders for buffers, files, and URLs.
+ * Headless editable-EPUB state for custom proofreading/editor UIs.
+ *
+ * One load runs at a time: starting another, changing `url` or unmounting
+ * aborts the one in flight — its fetch and parse included — and its result is
+ * dropped.
  */
-declare function useEpub(options?: UseEpubOptions): UseEpubReturn;
+declare function useEditableEpub(options?: UseEditableEpubOptions): UseEditableEpubReturn;
 
-/** 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}. */
 interface UseEpubProjectOptions {
-    /** Initial package metadata, merged over the hook's Japanese defaults. */
-    metadata?: Partial<EpubProjectMetadata>;
-    /** Initial chapter drafts. A single generated chapter is used when empty. */
-    chapters?: EpubProjectChapterDraft[];
+    /**
+     * Package metadata on mount. The title defaults to `''` and the language to
+     * `'ja'`; a missing or blank identifier is generated.
+     */
+    initialMetadata?: Partial<EpubProjectMetadata>;
+    /**
+     * Chapters on mount. When absent or empty, one chapter is generated from
+     * {@link UseEpubProjectOptions.defaultChapterTitle} /
+     * {@link UseEpubProjectOptions.defaultChapterBody}.
+     */
+    initialChapters?: readonly ManuscriptChapter$1[];
     /** Preview rebuild debounce in milliseconds. @defaultValue 250 */
     debounceMs?: number;
     /**
-     * Initial cover asset. Pass `{ href, url }` to keep the bytes remote until
-     * export, or `{ href, data }` to embed them straight away.
+     * Cover on mount. Pass `{ url, mediaType }` to keep the bytes remote until
+     * export, or `{ data, mediaType }` to embed them straight away.
      */
-    cover?: EpubProjectAsset;
+    initialCover?: CoverInput;
     /**
-     * Initial non-cover assets (illustrations, extra stylesheets). Same
-     * `data` / `url` choice as {@link UseEpubProjectOptions.cover}.
+     * Non-cover assets on mount (illustrations, extra stylesheets). Same
+     * `data` / `url` choice as {@link UseEpubProjectOptions.initialCover}.
      */
-    assets?: EpubProjectAsset[];
+    initialAssets?: readonly EpubProjectAsset[];
     /**
      * Resolves URL-only project assets into bytes when the preview or export
      * pipeline materializes them. Forwarded to `project.export()`. Register the
@@ -1609,63 +1817,76 @@ interface UseEpubProjectOptions {
      * provide auth headers here.
      */
     assetResolver?: AssetResolver;
-    /** Called with each successfully rebuilt preview book. */
-    onPreview?: (book: EpubBook) => void;
+    /** Called with each successfully rebuilt preview EPUB. */
+    onPreview?: (epub: EpubBook) => void;
     /** Called with the EPUB bytes produced by {@link UseEpubProjectReturn.exportEpub}. */
-    onExport?: (buffer: ArrayBuffer) => void;
-    /** Creates the default title for a generated chapter. */
+    onExport?: (bytes: Uint8Array<ArrayBuffer>) => void;
+    /**
+     * Called when an export fails; the promise `exportEpub` returned rejects
+     * too. A `MejiroError` is passed as thrown. Preview failures go to
+     * {@link UseEpubProjectReturn.previewError} instead.
+     */
+    onError?: (error: Error) => void;
+    /** Creates the title of a generated chapter. @defaultValue `() => ''` */
     defaultChapterTitle?: (index: number) => string;
-    /** Creates the default body for a generated chapter. */
+    /** Creates the body of a generated chapter. @defaultValue `() => ''` */
     defaultChapterBody?: (index: number) => string;
 }
 /** State and actions returned by {@link useEpubProject}. */
 interface UseEpubProjectReturn {
     /** Current book metadata. */
     metadata: EpubProjectMetadata;
-    /** Current chapter drafts, in reading order. */
-    chapters: EpubProjectChapterDraft[];
+    /** Current chapters, in reading order. */
+    chapters: readonly ManuscriptChapter$1[];
     /** 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;
+    selectedChapterIndex: number;
+    /** The chapter at `selectedChapterIndex`, or `null` when there is none. */
+    currentChapter: ManuscriptChapter$1 | null;
+    /** Current cover, or `null` when the project has no cover. */
+    cover: CoverInput | null;
     /** Current non-cover assets, in registration order. */
-    assets: EpubProjectAsset[];
+    assets: readonly EpubProjectAsset[];
     /** Parsed EPUB built from the current project, refreshed after each debounced change. */
-    previewBook: EpubBook | null;
+    previewEpub: EpubBook | null;
     /** Last preview build failure, if any. */
     previewError: Error | null;
     /** Whether a preview build is pending or running. */
     previewing: boolean;
+    /** Whether an export is in progress. */
+    exporting: boolean;
+    /** Last export failure, if any; cleared when an export starts. */
+    error: Error | null;
     /**
      * Merges `patch` into the metadata. A missing or blank `identifier` keeps the
      * current one.
      */
-    setMetadata: (patch: Partial<EpubProjectMetadata>) => void;
+    updateMetadata: (patch: Partial<EpubProjectMetadata>) => void;
     /** Replaces every chapter; an empty list becomes one generated chapter. */
-    setChapters: (chapters: EpubProjectChapterDraft[]) => void;
+    setChapters: (chapters: readonly ManuscriptChapter$1[]) => void;
     /** Selects a chapter, clamped to the chapter range. */
-    setSelectedChapter: (index: number) => void;
+    setSelectedChapterIndex: (index: number) => void;
     /**
-     * Replaces the cover asset, or drops it when passed `null`. The new cover is
+     * Replaces the cover, or drops it when passed `null`. The new cover is
      * reflected by both the debounced preview and {@link UseEpubProjectReturn.exportEpub}.
      */
-    setCover: (asset: EpubProjectAsset | null) => void;
+    setCover: (cover: CoverInput | null) => void;
     /**
      * Replaces the non-cover asset list. Assets are registered on every rebuilt
      * project, so URL-only entries reach `assetResolver` at export time.
      */
-    setAssets: (assets: EpubProjectAsset[]) => void;
+    setAssets: (assets: readonly 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;
+    updateChapter: (index: number, patch: Partial<ManuscriptChapter$1>) => void;
+    /**
+     * Appends a chapter and selects it. Omitted fields are generated: a unique
+     * id, and the title and body of `defaultChapterTitle` / `defaultChapterBody`.
+     */
+    addChapter: (chapter?: Partial<ManuscriptChapter$1>) => void;
     /**
-     * Removes the chapter at `index` (the selected one by default); the last chapter is never
-     * removed.
+     * Removes the chapter at `index`; the last remaining chapter is never
+     * removed. Pass `selectedChapterIndex` to remove the selected one.
      */
-    removeChapter: (index?: number) => void;
+    removeChapter: (index: number) => void;
     /**
      * Moves a chapter from `from` to `to`. An out-of-range `from` selects no
      * chapter and leaves the list untouched; `to` is clamped to the list bounds —
@@ -1674,49 +1895,64 @@ interface UseEpubProjectReturn {
     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>;
+    /**
+     * Packages the current project as EPUB bytes. A failure is stored in
+     * `error`, passed to `onError` and rejects.
+     */
+    exportEpub: () => Promise<Uint8Array<ArrayBuffer>>;
 }
 /** Headless manuscript-to-EPUB project state for custom authoring UIs. */
 declare function useEpubProject(options?: UseEpubProjectOptions): UseEpubProjectReturn;
 
 /** Options for {@link useManuscriptDraft}. */
-interface UseManuscriptDraftOptions<TAutosave = ManuscriptEditorChapter[]> {
-    /** Initial chapters. Defaults to a single empty chapter. */
-    initialChapters?: ManuscriptEditorChapter[];
+interface UseManuscriptDraftOptions<TAutosave = ManuscriptChapter$1[]> {
+    /**
+     * Initial chapters, read on mount. Defaults to a single chapter with an
+     * empty title and body.
+     */
+    initialChapters?: readonly ManuscriptChapter$1[];
     /**
-     * Called when the draft changes (debounced). Use to persist to
-     * localStorage, IndexedDB, or upload to a server.
+     * Called when the draft changes (debounced). This is the persistence
+     * channel of the hook, and it may be async: return a promise to have the
+     * next save wait for it and to have a rejection land in `autosaveError`.
+     * Use it to write to localStorage or IndexedDB, or to upload to a server.
      */
     onAutosave?: (draft: TAutosave) => void | Promise<void>;
     /** Maps chapters to the autosave payload. Defaults to the chapter array. */
-    autosavePayload?: (chapters: ManuscriptEditorChapter[]) => TAutosave;
-    /** Extra key that triggers autosave when non-chapter metadata changes. */
-    autosaveKey?: string;
+    autosavePayload?: (chapters: readonly ManuscriptChapter$1[]) => TAutosave;
+    /**
+     * Values outside the chapters that the autosave payload depends on (a
+     * title, an author). A change to any of them, compared with `Object.is`,
+     * schedules an autosave like a chapter edit does.
+     */
+    autosaveDeps?: readonly unknown[];
     /** Debounce delay in milliseconds. @defaultValue 800 */
-    autosaveDelay?: number;
-    /** Creates the default title for a generated chapter. */
+    autosaveDebounceMs?: number;
+    /** Creates the title of a generated chapter. @defaultValue `() => ''` */
     defaultChapterTitle?: (index: number) => string;
-    /** Creates the default body for a generated chapter. */
+    /** Creates the body of a generated chapter. @defaultValue `() => ''` */
     defaultChapterBody?: (index: number) => string;
 }
 /** Return value of {@link useManuscriptDraft}. */
 interface UseManuscriptDraftReturn {
     /** Current chapters, in reading order. */
-    chapters: ManuscriptEditorChapter[];
+    chapters: readonly ManuscriptChapter$1[];
     /** Index of the chapter currently being edited. */
-    selected: number;
+    selectedChapterIndex: number;
     /** Selects a chapter, clamped to the chapter range. */
-    setSelected(index: number): void;
+    setSelectedChapterIndex(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;
+    setChapters(chapters: readonly ManuscriptChapter$1[]): 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;
+    updateChapter(index: number, patch: Partial<ManuscriptChapter$1>): void;
+    /**
+     * Appends a chapter and selects it. Omitted fields are generated: a unique
+     * id, and the title and body of `defaultChapterTitle` / `defaultChapterBody`.
+     */
+    addChapter(chapter?: Partial<ManuscriptChapter$1>): 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. */
@@ -1733,16 +1969,20 @@ interface UseManuscriptDraftReturn {
  * patching individual chapters, plus a debounced autosave hook that fires
  * `onAutosave` whenever the chapter list settles.
  */
-declare function useManuscriptDraft<TAutosave = ManuscriptEditorChapter[]>(options?: UseManuscriptDraftOptions<TAutosave>): UseManuscriptDraftReturn;
+declare function useManuscriptDraft<TAutosave = ManuscriptChapter$1[]>(options?: UseManuscriptDraftOptions<TAutosave>): UseManuscriptDraftReturn;
 
 /** Options for {@link useManuscriptLayout}. */
 interface UseManuscriptLayoutOptions {
+    /** The chapter to lay out; `null` lays nothing out. */
+    chapter: ManuscriptChapter | null;
+    /** The reading surface the pages are sized against. */
+    surface: RefObject<HTMLElement | null>;
     /** Manuscript notation dialect. @defaultValue `'mejiro'` */
     dialect?: ManuscriptDialect;
     /** 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;
+    resizeDebounceMs?: number;
     /**
      * Capture the reading position from the outgoing layout, just before a
      * **reflow** (non-blank) re-layout replaces it. The anchor is held in
@@ -1765,30 +2005,11 @@ interface UseManuscriptLayoutOptions {
      */
     onError?: (error: Error) => void;
 }
-/** Options for {@link UseManuscriptLayoutReturn.recompute}. */
-interface ManuscriptRecomputeOptions {
-    /**
-     * Blank the current layout while the new one is computed. Use for content
-     * changes (chapter swaps); skip for size 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 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}. */
 interface UseManuscriptLayoutReturn {
     /** Current layout, or `null` before the first computation. */
     layout: ChapterLayout | null;
-    /** Page width in pixels. */
+    /** Page width in pixels, as {@link MejiroBook.fitPageSize} measured it. */
     pageWidth: number;
     /** Page height in pixels. */
     pageHeight: number;
@@ -1796,11 +2017,16 @@ interface UseManuscriptLayoutReturn {
     contentHeight: number;
     /** Most recent layout time (ms). */
     elapsedMs: number;
+    /**
+     * Failure of the most recent layout of the current source, whichever path
+     * started it; `null` once a layout succeeds or the source changes.
+     */
+    error: Error | null;
     /**
      * Force a fresh layout computation. A failure goes to `onError` when one is
      * supplied; otherwise the returned promise rejects.
      */
-    recompute: (opts?: ManuscriptRecomputeOptions) => Promise<void>;
+    recompute: (opts?: ChapterLayoutRecomputeOptions) => Promise<void>;
     /**
      * Anchor captured by `capturePosition` before the most recent reflow,
      * awaiting restoration into the new layout. `restorePosition`, when given,
@@ -1820,7 +2046,8 @@ interface UseManuscriptLayoutReturn {
  * Re-layouts whenever the chapter's id, title or body, `dialect`, or `book`
  * change; a new chapter object with the same content does not. The surface is
  * observed with {@link ResizeObserver}; size changes trigger a full re-layout
- * so pagination stays correct after non-trivial container changes.
+ * so pagination stays correct after non-trivial container changes. While the
+ * surface measures zero wide or high, nothing is measured or laid out.
  *
  * A size-driven re-layout keeps the previous layout on screen while the new one
  * is computed (no blank flash) and yields a new {@link ChapterLayout} object,
@@ -1830,8 +2057,11 @@ interface UseManuscriptLayoutReturn {
  * {@link UseManuscriptLayoutOptions.restorePosition} and
  * {@link UseManuscriptLayoutReturn.pendingRestore}, identically in the Vue
  * composable.
+ *
+ * @param book - The book instance to lay out with.
+ * @param options - The chapter and surface to lay out, plus behavior overrides.
  */
-declare function useManuscriptLayout(book: MejiroBook, chapter: ManuscriptChapter | null, surface: RefObject<HTMLElement | null>, options?: UseManuscriptLayoutOptions): UseManuscriptLayoutReturn;
+declare function useManuscriptLayout(book: MejiroBook, options: UseManuscriptLayoutOptions): UseManuscriptLayoutReturn;
 
 /** Options for {@link useMejiroBook}. */
 interface UseMejiroBookOptions {
@@ -1847,7 +2077,7 @@ interface UseMejiroBookOptions {
     /**
      * 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
+     * {@link UseMejiroBookReturn.updateOptions} resolves instead of rejecting, so
      * fire-and-forget callers cannot leave an unhandled rejection behind.
      */
     onError?: (error: Error) => void;
@@ -1862,26 +2092,31 @@ interface UseMejiroBookReturn {
      */
     options: Readonly<BookOptions>;
     /**
-     * Update options on the underlying book and the snapshot. The snapshot is
-     * updated synchronously; the returned promise resolves once
-     * {@link MejiroBook.setOptions} has propagated font / size changes (which
+     * Merges `patch` into the options of the underlying book and the snapshot.
+     * The snapshot is updated synchronously; the returned promise resolves once
+     * {@link MejiroBook.updateOptions} has propagated font / size changes (which
      * complete only after the font has loaded).
      */
-    setOptions: (next: Partial<BookOptions>) => Promise<void>;
+    updateOptions: (patch: BookOptionsPatch) => 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).
+ * options as React state.
  *
- * @param initial - Initial book options (passed to the {@link MejiroBook} constructor).
- * @param options - Behavior overrides (debouncing, error reporting).
+ * The book is created once on mount from `options`. Afterwards, a change to
+ * the content of a key {@link MejiroBook.updateOptions} accepts — compared by
+ * value, so an object literal recreated every render is fine — is applied like
+ * an {@link UseMejiroBookReturn.updateOptions} call; without `onError`, a
+ * failure of such an application goes to `console.warn`. A change to a
+ * construction-time key (`strictFontCheck`, `analyzer`, `pageSize`, …) is
+ * ignored and the book is not recreated; give the component a new React `key`
+ * to start over with a new book.
+ *
+ * @param options - Book options; read in full on mount, and for their runtime keys on every render.
+ * @param hookOptions - Behavior overrides (debouncing, error reporting).
  */
-declare function useMejiroBook(initial: MejiroBookOptions, options?: UseMejiroBookOptions): UseMejiroBookReturn;
+declare function useMejiroBook(options: BookOptions, hookOptions?: UseMejiroBookOptions): UseMejiroBookReturn;
 
-/** Minimal storage interface required by {@link useReadingPosition}. */
-type ReadingPositionStorage = MejiroStorage;
 /** Options for {@link useReadingPosition}. */
 interface UseReadingPositionOptions {
     /** Storage key — usually scoped per-book (e.g. `mejiro:position:${bookId}`). */
@@ -1890,24 +2125,34 @@ interface UseReadingPositionOptions {
      * Storage backend. Defaults to `window.localStorage` when available.
      * SSR consumers can omit this and the hook will fall back to in-memory.
      */
-    storage?: ReadingPositionStorage;
+    storage?: MejiroStorage;
     /**
-     * Debounce delay (ms): the latest value is written this long after the last change. A pending write is flushed on page hide, key change and unmount. @defaultValue 250
+     * Debounce delay (ms): the latest value is written this long after the last
+     * change. A pending write is flushed on page hide, key change and unmount.
+     * @defaultValue 250
      */
-    throttleMs?: number;
+    debounceMs?: 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;
+    onPositionChange?: (next: ReadingAnchor$1 | null) => void;
+    /**
+     * Receives a storage failure: `storage-read-failed` or `storage-corrupt` when
+     * hydrating (the position starts as `null`, and the stored value is left
+     * alone until the next `save()`), `storage-write-failed` when a write or
+     * removal throws (the in-memory position is kept). Without it the error goes
+     * to `console.warn`.
+     */
+    onError?: (error: MejiroError) => void;
 }
 /** Return value of {@link useReadingPosition}. */
 interface UseReadingPositionReturn {
     /** Most recently persisted position, or `null` if none. */
-    position: ReadingPositionValue | null;
-    /** Persist a new position (debounced by `throttleMs`). */
-    save(next: ReadingPositionValue): void;
+    position: ReadingAnchor$1 | null;
+    /** Persist a new position (debounced by `debounceMs`). */
+    save(next: ReadingAnchor$1): void;
     /** Remove the persisted position. */
     clear(): void;
 }
@@ -1934,73 +2179,11 @@ interface UseReadingPositionReturn {
  * }, [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.
+ * Every stored layout {@link parseReadingPosition} reads is accepted; one
+ * that names only a chapter and a spread resumes at the start of the chapter,
+ * because a spread index does not survive reflow.
  */
 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;
-    /**
-     * 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 navigation index: a page index in single mode, a spread index otherwise. */
-    spreadIdx: number;
-    /** Layout spread holding the visible page(s), or `null` until the layout is ready. */
-    spread: SpreadResult | null;
-    /** 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;
-    /** 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 position (page or spread) forward. */
-    next: () => void;
-    /** Go back one position. */
-    prev: () => void;
-    /** Jump to an arbitrary navigation index (clamped). */
-    goTo: (index: number) => void;
-    /**
-     * 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;
-}
-/**
- * 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 { MejiroChapterNav, MejiroDropZone, MejiroEditor, MejiroI18nProvider, MejiroImageOverlay, MejiroManuscriptEditor, MejiroNotationHighlighter, MejiroPage, MejiroPageIndicator, MejiroPageView, MejiroReader, MejiroScrollView, MejiroSelectionLayer, MejiroSettingsPanel, MejiroShelf, MejiroSpread, MejiroStats, MejiroToc, format, resolveMessages, useAnnotations, useChapterLayout, useEditableEpub, useEpub, useEpubProject, useI18n, useImageOverlay, useLibrary, useManuscriptDraft, useManuscriptLayout, useMejiroBook, useMultiImageOverlay, useReadingPosition, useSpread };
-export type { AnnotationsStorage, EpubProjectChapterDraft, ImageRect, ManuscriptAutosaveDraft, ManuscriptEditorChapter, ManuscriptPageDimensions, ManuscriptPreviewProps, ManuscriptRecomputeOptions, MejiroChapterNavMode, MejiroChapterNavProps, MejiroChapterNavVariant, MejiroDropZoneProps, MejiroEditorProps, MejiroExportPolicy, MejiroImageOverlayProps, MejiroManuscriptEditorProps, MejiroNotationHighlighterProps, MejiroPageIndicatorProps, MejiroPageProps, MejiroPageViewProps, MejiroReaderCommonProps, MejiroReaderControlledProps, MejiroReaderEventMap, MejiroReaderFileProps, MejiroReaderFit, MejiroReaderHandle, MejiroReaderManuscriptProps, MejiroReaderMode, MejiroReaderProps, MejiroReaderSettingsSlot, MejiroReaderUrlProps, MejiroScrollViewProps, MejiroSelectionLayerProps, MejiroSettingsPanelProps, MejiroShelfProps, MejiroSpreadMode, MejiroSpreadProps, MejiroStatsProps, MejiroTheme, MejiroThemeName, MejiroTocProps, MultiImageItem, PageDimensions, ReadingPosition, ReadingPositionStorage, RecomputeOptions, UseAnnotationsOptions, UseAnnotationsReturn, UseChapterLayoutOptions, UseChapterLayoutReturn, UseEditableEpubOptions, UseEditableEpubReturn, UseEpubOptions, UseEpubProjectOptions, UseEpubProjectReturn, UseEpubReturn, UseI18nOptions, UseImageOverlayOptions, UseImageOverlayReturn, UseLibraryOptions, UseLibraryReturn, UseManuscriptDraftOptions, UseManuscriptDraftReturn, UseManuscriptLayoutOptions, UseManuscriptLayoutReturn, UseMejiroBookOptions, UseMejiroBookReturn, UseMultiImageOverlayOptions, UseMultiImageOverlayReturn, UseReadingPositionOptions, UseReadingPositionReturn, UseSpreadOptions, UseSpreadReturn, VolumeInfo };
+export { MejiroChapterNav, MejiroDropZone, MejiroEditor, MejiroI18nProvider, MejiroImagePlaceholder, MejiroManuscriptEditor, MejiroNotationHighlighter, MejiroPage, MejiroPageIndicator, MejiroPageView, MejiroReader, MejiroScrollView, MejiroSelectionLayer, MejiroSettingsPanel, MejiroShelf, MejiroSpread, MejiroStats, MejiroToc, useAnnotations, useChapterLayout, useEditableEpub, useEpub, useEpubProject, useI18n, useImageOverlay, useLibrary, useManuscriptDraft, useManuscriptLayout, useMejiroBook, useReadingPosition, useSpread };
+export type { ChapterLayoutRecomputeOptions, ExportPolicy, FetchEpubOptions, GoToOptions, ManuscriptAutosaveDraft, ManuscriptPreviewProps, MejiroChapterNavMode, MejiroChapterNavProps, MejiroChapterNavVariant, MejiroDropZoneProps, MejiroEditorProps, MejiroI18nProviderProps, MejiroImagePlaceholderProps, MejiroManuscriptEditorProps, MejiroNotationHighlighterProps, MejiroPageIndicatorProps, MejiroPageProps, MejiroPageViewProps, MejiroReaderChapterFinishedEvent, MejiroReaderCommonProps, MejiroReaderEventMap, MejiroReaderFit, MejiroReaderHandle, MejiroReaderManuscriptProps, MejiroReaderMode, MejiroReaderParsedProps, MejiroReaderPickerProps, MejiroReaderProps, MejiroReaderSettingsSlot, MejiroReaderSpreadIndexChangeEvent, MejiroReaderTurnEndEvent, MejiroReaderTurnStartEvent, MejiroReaderUrlProps, MejiroScrollViewProps, MejiroSelectionLayerProps, MejiroSettingsPanelProps, MejiroShelfProps, MejiroSpreadMode, MejiroSpreadProps, MejiroStatsProps, MejiroTheme, MejiroThemeName, MejiroTocProps, MultiImageItem, ReaderAnnotation, ReadingAnchorRange, ResolvedSpreadMode, SelectionRect, SpreadPosition, UseAnnotationsOptions, UseAnnotationsReturn, UseChapterLayoutOptions, UseChapterLayoutReturn, UseEditableEpubOptions, UseEditableEpubReturn, UseEpubOptions, UseEpubProjectOptions, UseEpubProjectReturn, UseEpubReturn, UseI18nOptions, UseImageOverlayOptions, UseImageOverlayReturn, UseLibraryOptions, UseLibraryReturn, UseManuscriptDraftOptions, UseManuscriptDraftReturn, UseManuscriptLayoutOptions, UseManuscriptLayoutReturn, UseMejiroBookOptions, UseMejiroBookReturn, UseReadingPositionOptions, UseReadingPositionReturn, UseSpreadOptions, UseSpreadReturn, VolumeInfo };