@libraz/mejiro-react 0.8.0 → 0.9.1

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-import { MejiroLocale, MejiroMessages, EditableSettings, FontChoice, PageHeaderData, MejiroStorage, Annotation, ReadingPositionValue } from '@libraz/mejiro';
-export { Annotation, EditableSettings, FontChoice, MejiroLocale, MejiroMessages, PageHeaderData, ReadingPositionValue, enMessages, jaMessages } from '@libraz/mejiro';
+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 * as react from 'react';
-import { ReactNode, CSSProperties, PointerEvent, TextareaHTMLAttributes, RefObject } from 'react';
-import { EpubBook, AssetResolver, EditableEpub, ManuscriptDialect, EpubChapter, EditableEpubBook, AnnotatedParagraph, AddImageInput, EditableEpubImage, EpubExportOptions, EpubProjectMetadata, EpubProject } from '@libraz/mejiro/epub';
+import { ReactNode, CSSProperties, PointerEvent, TextareaHTMLAttributes, MutableRefObject, RefObject } from 'react';
+import { EpubBook, AssetResolver, EpubParseLimits, EditableEpub, ManuscriptDialect, EpubChapter, EditableEpubBook, EditableEpubSelection, AnnotatedParagraph, AddImageInput, EditableEpubImage, EpubExportOptions, EpubProjectMetadata, EpubProjectAsset, EpubProject } from '@libraz/mejiro/epub';
+export { EditableEpubSelection } from '@libraz/mejiro/epub';
 import { ChapterLayout, SpreadResult, BookOptions, ComputePageSizeOptions, InChapterAnchor, ReadingAnchor, ManuscriptChapter, PageResult, AnchorRect, AnchorRange, MejiroBook } from '@libraz/mejiro/book';
 import { RenderPage } from '@libraz/mejiro/render';
 import { FontFamily, InlineAnnotation } from '@libraz/mejiro/browser';
@@ -31,6 +32,10 @@ declare function resolveMessages(locale: MejiroLocale | undefined, overrides: Pa
 /** Replace `{name}` placeholders in a template. */
 declare function format(template: string, vars: Record<string, string | number>): string;
 
+/**
+ * Layout of {@link MejiroChapterNav}: `'select'` is a compact dropdown,
+ * `'panel'` a chapter list with titles, headings and a text preview.
+ */
 type MejiroChapterNavVariant = 'select' | 'panel';
 /** Props for {@link MejiroChapterNav}. */
 interface MejiroChapterNavProps {
@@ -57,7 +62,7 @@ declare function MejiroChapterNav({ epub, chapter, onChange, variant, }: MejiroC
 interface MejiroDropZoneProps {
     /** File `accept` filter for the picker. @defaultValue '.epub' */
     accept?: string;
-    /** Validator. Defaults to `name.endsWith('.epub')`. */
+    /** Validator. Defaults to the `accept` filter, with extensions matched case-insensitively. */
     validateFile?: (file: File) => boolean;
     /** Called with the selected/dropped file. */
     onFile: (file: File) => void;
@@ -69,7 +74,9 @@ interface MejiroDropZoneProps {
     style?: CSSProperties;
 }
 /**
- * Drop zone for EPUB files. Combines drag-and-drop with a click-to-open file picker.
+ * Drop zone for EPUB files. Combines drag-and-drop with a click-to-open file
+ * 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;
 
@@ -93,6 +100,7 @@ interface MejiroSettingsPanelProps {
  */
 declare function MejiroSettingsPanel({ open, settings, onChange, fonts, minFontSize, maxFontSize, }: MejiroSettingsPanelProps): ReactNode;
 
+/** Props for {@link MejiroEditor}. */
 interface MejiroEditorProps {
     /** URL fetched and loaded on mount. */
     epubUrl?: string;
@@ -139,18 +147,27 @@ interface MejiroEditorProps {
      * 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>;
     /** Called after an EPUB is loaded into the editor. */
     onLoad?: (editor: EditableEpub) => void;
     /** Called after export completes. */
     onExport?: (buffer: ArrayBuffer) => void;
-    /** Called when loading or parsing an EPUB fails. */
+    /**
+     * Called when loading, image insertion or export fails. The error is also
+     * shown in the editor.
+     */
     onError?: (error: Error) => void;
 }
 /**
  * Declarative restrictions on the export pipeline. Mejiro applies the
- * transforms in this order: `watermark` (modifies the EPUB in-place) →
- * `encrypt` (replaces the buffer with the result) → `allowDownload` (skips
- * the browser download when `false`).
+ * 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 {
     /**
@@ -166,24 +183,27 @@ interface MejiroExportPolicy {
      */
     encrypt?: (buffer: ArrayBuffer) => ArrayBuffer | Promise<ArrayBuffer>;
     /**
-     * Embeds a visible watermark string into the EPUB. Implemented by writing
-     * the text as XHTML metadata; renderers may surface it differently.
+     * 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;
-        opacity?: number;
     };
 }
 /** EPUB editor UI for proofreading, ruby edits, image insertion, and export. */
-declare function MejiroEditor({ epubUrl, fonts, enableProofread, enableRuby, enableImages, enableExport, onBeforeExport, exportPolicy, assetResolver, onLoad, onExport, onError, }: MejiroEditorProps): ReactNode;
+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. */
-interface ImageRect {
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-}
+/**
+ * Rectangle describing an image overlay position and size.
+ *
+ * @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.
+ */
+type ImageRect = ImageOverlayRect;
 /** Options for {@link useImageOverlay}. */
 interface UseImageOverlayOptions {
     /** Default image width in pixels. @defaultValue 120 */
@@ -200,7 +220,7 @@ interface UseImageOverlayOptions {
 /** Return value of {@link useImageOverlay}. */
 interface UseImageOverlayReturn {
     /** Current image rectangle, or `null` if no overlay is active. */
-    imageRect: ImageRect | null;
+    imageRect: ImageOverlayRect | null;
     /** Whether an image overlay is currently active. */
     hasImage: boolean;
     /** Toggle the image overlay on/off. */
@@ -214,6 +234,11 @@ interface UseImageOverlayReturn {
  * React hook that manages a draggable/resizable image overlay
  * with automatic text reflow via {@link ChapterLayout.syncImages}.
  *
+ * 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.
@@ -246,6 +271,10 @@ interface MejiroImageOverlayProps {
  */
 declare function MejiroImageOverlay({ rect, label, onOverlayPointerDown, onResizePointerDown, onClose, }: MejiroImageOverlayProps): ReactNode;
 
+/**
+ * Where {@link MejiroReader} places its chapter navigation: the header
+ * dropdown (`'select'`), the side chapter list (`'panel'`), both, or neither.
+ */
 type MejiroChapterNavMode = 'select' | 'panel' | 'both' | 'none';
 /**
  * Reading-flow mode for {@link MejiroReader}.
@@ -256,8 +285,9 @@ type MejiroReaderMode = 'paginated' | 'scroll';
 /**
  * Two-page vs single-page rendering of a spread.
  * - `double` — always render two pages (default).
- * - `single` — render only the right page, centered.
- * - `auto` — switch based on the surface aspect ratio (single when portrait).
+ * - `single` — render one page at a time, centered; spread indices count pages.
+ * - `auto` — switch based on the surface aspect ratio (single when portrait),
+ *   converting the index so the page on screen stays visible.
  */
 type MejiroSpreadMode = 'double' | 'single' | 'auto';
 /**
@@ -289,9 +319,13 @@ type MejiroTheme = MejiroThemeName | {
 };
 /** Reading position exposed by {@link MejiroReaderHandle.getReadingPosition}. */
 interface ReadingPosition {
+    /** Zero-based index of the current chapter. */
     chapter: number;
+    /** Zero-based index of the current spread within the chapter. */
     spreadIdx: number;
+    /** Number of pages in the current chapter's layout. */
     totalPages: number;
+    /** Number of spreads in the current chapter's layout. */
     totalSpreads: number;
 }
 /**
@@ -341,14 +375,16 @@ interface MejiroReaderHandle {
      */
     goToAnchor(anchor: ReadingAnchor): Promise<void>;
     /**
-     * Returns the {@link ReadingAnchor} at the start of the current spread,
-     * or `null` if the layout is not ready.
+     * Returns the {@link ReadingAnchor} at the start of the text on the current
+     * spread, or `null` if the layout is not ready. When an image blocks every
+     * page of the spread, the anchor is where the text resumes after it; `null`
+     * again if none follows.
      */
     getAnchor(): ReadingAnchor | null;
     /**
      * Returns the half-open range of {@link ReadingAnchor}s visible on the
-     * current spread. `end` points at the start of the next spread (or the end
-     * of the chapter for the last spread).
+     * current spread. `end` points at the start of the text on the next spread
+     * that has any (or the end of the chapter when none does).
      */
     getVisibleRange(): {
         start: ReadingAnchor;
@@ -357,6 +393,12 @@ interface MejiroReaderHandle {
     /**
      * Updates book options at runtime. Same shape as {@link MejiroBook.setOptions}
      * — 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.
      */
     setOptions(partial: Partial<BookOptions>): Promise<void>;
     /**
@@ -413,7 +455,9 @@ interface MejiroReaderCommonProps {
     /**
      * Controlled spread index. When supplied, the reader is driven by this
      * value and emits {@link MejiroReaderProps.onSpreadIdxChange} on user
-     * navigation. Combine with `useReadingPosition` for save/restore.
+     * navigation. A spread index does not survive reflow, so persist the
+     * reading position with `useReadingPosition` and the handle's
+     * `getAnchor` / `goToAnchor` instead.
      */
     spreadIdx?: number;
     /**
@@ -430,8 +474,10 @@ interface MejiroReaderCommonProps {
      */
     mode?: MejiroReaderMode;
     /**
-     * Spread layout. `double` (default) renders two pages; `single` renders
-     * only the right page; `auto` flips to `single` for portrait viewports.
+     * Spread layout. `double` (default) renders two pages; `single` renders one
+     * page at a time, and `spreadIdx`, `goToSpread`, `onSpreadIdxChange` and
+     * `spreadChanged` then count pages; `auto` flips to `single` for portrait
+     * viewports, keeping the page on screen visible.
      */
     spreadMode?: MejiroSpreadMode;
     /**
@@ -462,6 +508,13 @@ interface MejiroReaderCommonProps {
      * sending bearer tokens or cookies.
      */
     fetchOptions?: RequestInit;
+    /**
+     * Resource limits applied while parsing an EPUB the reader loads itself
+     * (URL mode and the drop zone / file picker). Untrusted files reach this
+     * component directly, so hosts that accept them should tighten the
+     * defaults here.
+     */
+    limits?: Partial<EpubParseLimits>;
     /**
      * Custom EPUB fetcher used in place of the global `fetch`. Overrides
      * {@link fetchOptions} when set.
@@ -542,9 +595,10 @@ interface MejiroReaderCommonProps {
     /**
      * Reader-side annotations to render as highlights. Each annotation whose
      * `chapter` matches the current chapter is converted to spread-local
-     * rectangles via `ChapterLayout.selectionRects` and drawn on top of the
-     * page content. Pair with {@link useAnnotations} for persistence, or pass
-     * any shape that satisfies `{ chapter, start, end }`.
+     * 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;
@@ -554,7 +608,11 @@ interface MejiroReaderCommonProps {
     }>;
     /** Called after a successful EPUB load. */
     onLoad?: (book: EpubBook) => void;
-    /** Called when loading or parsing an EPUB fails. */
+    /**
+     * 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;
@@ -623,18 +681,31 @@ interface MejiroReaderManuscriptProps extends MejiroReaderCommonProps {
  * modes — TypeScript prevents passing more than one source at once.
  */
 type MejiroReaderProps = MejiroReaderControlledProps | MejiroReaderUrlProps | MejiroReaderFileProps | MejiroReaderManuscriptProps;
+/**
+ * Full-page EPUB reader. Composes the package's primitives into a working
+ * reader; features opt out via the `enableX` props or all chrome via `bare`.
+ * The `ref` exposes {@link MejiroReaderHandle} for imperative navigation.
+ */
 declare const MejiroReader: react.ForwardRefExoticComponent<MejiroReaderProps & react.RefAttributes<MejiroReaderHandle>>;
 
+/** One chapter of the manuscript being edited. */
 interface ManuscriptEditorChapter {
+    /** Stable identifier; survives reordering and title edits. */
     id: string;
+    /** Chapter title; an empty title falls back to the localized "untitled" label. */
     title: string;
+    /** Chapter body in the editor's manuscript notation. */
     body: string;
 }
 /** Autosave payload emitted by {@link MejiroManuscriptEditor}. */
 interface ManuscriptAutosaveDraft {
+    /** Book title as currently entered. */
     title: string;
+    /** Author name as currently entered. */
     author: string;
+    /** Selected cover image, or `null` when none is set. */
     cover: File | null;
+    /** Chapters in reading order, as plain (non-reactive) copies. */
     chapters: ManuscriptEditorChapter[];
 }
 /**
@@ -644,14 +715,23 @@ interface ManuscriptAutosaveDraft {
  * supplied here.
  */
 interface ManuscriptPreviewProps {
+    /** Header subtitle of the preview reader. */
     subtitle?: string;
+    /** Header title of the preview reader. */
     title?: string;
+    /** Where the preview places its chapter navigation. @defaultValue 'panel' */
     chapterNavMode?: 'select' | 'panel' | 'both' | 'none';
+    /** Show the preview header. */
     enableHeader?: boolean;
+    /** Show the preview chapter navigation. */
     enableChapterNav?: boolean;
+    /** Show the preview settings panel toggle. */
     enableSettings?: boolean;
+    /** Show the preview layout statistics. */
     enableStats?: boolean;
+    /** Enable arrow-key page turns in the preview. */
     enableKeyboard?: boolean;
+    /** Show the preview page indicator. */
     enablePageIndicator?: boolean;
     /** Book options forwarded to the embedded reader preview. */
     options?: Partial<BookOptions>;
@@ -666,8 +746,10 @@ interface ManuscriptPreviewProps {
      * to `true` to demo the fullscreen-reader behavior.
      */
     enableSurfaceTap?: boolean;
+    /** Render the preview without any reader chrome. */
     bare?: boolean;
 }
+/** Props for {@link MejiroManuscriptEditor}. */
 interface MejiroManuscriptEditorProps {
     /** Font choices passed to the preview reader. */
     fonts?: FontChoice[];
@@ -695,6 +777,12 @@ interface MejiroManuscriptEditorProps {
     onCoverChange?: (cover: File | null) => void;
     /** Initial chapters. */
     chapters?: ManuscriptEditorChapter[];
+    /**
+     * Manuscript notation dialect. Drives the notation highlighter, the live
+     * preview, and the exported EPUB alike, so the whole editor interprets one
+     * dialect. @defaultValue `'mejiro'`
+     */
+    dialect?: ManuscriptDialect;
     /**
      * Called whenever the chapter draft settles (debounced by
      * {@link MejiroManuscriptEditorProps.autosaveDelay}). Use to persist drafts
@@ -710,17 +798,30 @@ interface MejiroManuscriptEditorProps {
      */
     previewProps?: ManuscriptPreviewProps;
     /**
-     * Resolves URL-only project assets (e.g. covers/illustrations registered as
-     * `{ url, ... }`) into bytes at export time. Forwarded to `project.export()`
-     * so authors can register signed-URL references without holding raw bytes
-     * client-side until publish.
+     * Resolver for URL-only assets, forwarded to `project.export()`. This editor
+     * owns a `File` cover and manuscript text only, and embeds the cover bytes
+     * itself, so nothing it registers is URL-only — build the project through
+     * `useEpubProject` (`setCover` / `setAssets`) to author `{ url }` asset
+     * references that must be fetched at export time.
      */
     assetResolver?: AssetResolver;
     /** Called after export completes. */
     onExport?: (buffer: ArrayBuffer) => void;
+    /**
+     * Called when the EPUB export fails (asset resolution, cover reading, or
+     * packaging). The same error is shown in the editor panel, so hosts only
+     * need this to log or report it.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Which side of the editor the manuscript panel sits on. `'right'` (the
+     * default) puts the preview on the left; `'left'` mirrors the layout.
+     * @defaultValue 'right'
+     */
+    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, onAutosave, autosaveDelay, previewProps, assetResolver, onExport, }: MejiroManuscriptEditorProps): ReactNode;
+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;
 
 /** Props for {@link MejiroNotationHighlighter}. */
 interface MejiroNotationHighlighterProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'onChange'> {
@@ -809,6 +910,60 @@ interface MejiroPageViewProps {
  */
 declare function MejiroPageView({ result, fontFamily, lineSpacing, slotMode, className, style, }: MejiroPageViewProps): ReactNode;
 
+/** A single image overlay placed on a specific spread. */
+interface MultiImageItem {
+    /** Stable ID for the overlay (auto-assigned on add). */
+    id: string;
+    /** Position and size in pixels, relative to the right page. */
+    rect: ImageRect;
+}
+/** Options for {@link useMultiImageOverlay}. */
+interface UseMultiImageOverlayOptions {
+    /** Default image width. @defaultValue 120 */
+    defaultWidth?: number;
+    /** Default image height. @defaultValue 160 */
+    defaultHeight?: number;
+    /** Default x. @defaultValue 80 */
+    defaultX?: number;
+    /** Default y. @defaultValue 100 */
+    defaultY?: number;
+    /** Margin around each image, in pixels. Defaults to the book's font size. */
+    margin?: number;
+    /** Called after every reflow caused by adding/removing/moving an image. */
+    onUpdate?: (spread: SpreadResult) => void;
+}
+/** Return value of {@link useMultiImageOverlay}. */
+interface UseMultiImageOverlayReturn {
+    /**
+     * Map of all images keyed by spread index. A new map whenever the images or
+     * the margin they are applied with change, and a replacement layout has them
+     * before any view renders from it, so this map and the layout together key
+     * anything derived from the layout.
+     */
+    imagesBySpread: Map<number, MultiImageItem[]>;
+    /** Images on the current spread; a new array whenever `imagesBySpread` changes. */
+    currentImages: MultiImageItem[];
+    /** Whether any spread has at least one image. */
+    hasImages: boolean;
+    /** Add a new image on the current spread. */
+    addImage: (overrides?: Partial<ImageRect>) => MultiImageItem;
+    /** Remove the image with the given id. */
+    removeImage: (id: string) => void;
+    /** Replace an image's rectangle. */
+    updateImage: (id: string, rect: Partial<ImageRect>) => void;
+    /** Remove every image (or only those on `spreadIdx` if given). */
+    clearImages: (spreadIdx?: number) => void;
+    /** Pointer-down handler for the overlay body (drag). */
+    onOverlayPointerDown: (id: string, e: PointerEvent) => void;
+    /** Pointer-down handler for the resize handle. */
+    onResizePointerDown: (id: string, e: PointerEvent) => void;
+}
+/**
+ * React hook that manages multiple draggable/resizable image overlays
+ * per spread with automatic reflow via {@link ChapterLayout.setImages}.
+ */
+declare function useMultiImageOverlay(layout: ChapterLayout | null, spreadIdx: number, options?: UseMultiImageOverlayOptions): UseMultiImageOverlayReturn;
+
 /** Props for {@link MejiroScrollView}. */
 interface MejiroScrollViewProps {
     /** Layout containing the pages to render. */
@@ -839,6 +994,31 @@ interface MejiroScrollViewProps {
     scrollToPage?: number;
     /** Vertical gap between pages (px). @defaultValue 24 */
     pageGap?: number;
+    /**
+     * Selection rectangles to highlight. Compute via
+     * {@link ChapterLayout.selectionRects}; each entry is painted on the page its
+     * `pageIdx` addresses. An entry may carry a `color` fill.
+     */
+    selectionRects?: readonly (AnchorRect & {
+        color?: string;
+    })[];
+    /** Zero-based spread whose pages carry {@link MejiroScrollViewProps.images}. */
+    spreadIdx?: number;
+    /**
+     * Image overlays on the spread at {@link MejiroScrollViewProps.spreadIdx}.
+     * Each renders on the page whose area contains its centre (see
+     * `overlayPageSide`), matching {@link MejiroSpread}'s single-page routing.
+     * The layout reflows in place when its images change, so a new array here is
+     * also what re-reads the pages; `useMultiImageOverlay`'s `currentImages`
+     * provides one on every change.
+     */
+    images?: MultiImageItem[];
+    /** Pointer-down on an image overlay. */
+    onImagePointerDown?: (id: string, e: PointerEvent) => void;
+    /** Pointer-down on an image resize handle. */
+    onImageResizePointerDown?: (id: string, e: PointerEvent) => void;
+    /** Image overlay close button. */
+    onImageClose?: (id: string) => void;
 }
 /**
  * Continuous-scroll variant of {@link MejiroSpread}. Stacks every page in
@@ -846,7 +1026,7 @@ interface MejiroScrollViewProps {
  * detected via `IntersectionObserver` and reported through
  * {@link MejiroScrollViewProps.onVisiblePageChange}.
  */
-declare function MejiroScrollView({ layout, pageWidth, pageHeight, contentHeight, fontFamily, fontSize, lineSpacing, onVisiblePageChange, scrollToPage, pageGap, }: MejiroScrollViewProps): ReactNode;
+declare function MejiroScrollView({ layout, pageWidth, pageHeight, contentHeight, fontFamily, fontSize, lineSpacing, slotMode, onVisiblePageChange, scrollToPage, pageGap, selectionRects, spreadIdx, images, onImagePointerDown, onImageResizePointerDown, onImageClose, }: MejiroScrollViewProps): ReactNode;
 
 /** Props for {@link MejiroSelectionLayer}. */
 interface MejiroSelectionLayerProps {
@@ -854,8 +1034,14 @@ interface MejiroSelectionLayerProps {
      * Spread-local rectangles to highlight. Compute these via
      * {@link ChapterLayout.selectionRects} and pass the full array; the layer
      * picks the entries matching {@link MejiroSelectionLayerProps.side}.
+     *
+     * A rectangle may carry its own `color`, which becomes that rectangle's
+     * fill. Entries without one take the fill from the shipped stylesheet
+     * (`.mejiro-selection-rect`, themeable via `--mejiro-selection-bg`).
      */
-    rects: readonly AnchorRect[];
+    rects: readonly (AnchorRect & {
+        color?: string;
+    })[];
     /** Which page-side this layer is rendered into. */
     side: 'right' | 'left';
     /** Optional class added to the outer wrapper. */
@@ -864,7 +1050,7 @@ interface MejiroSelectionLayerProps {
     style?: CSSProperties;
     /** Optional class for each rectangle (defaults to `mejiro-selection-rect`). */
     rectClassName?: string;
-    /** Optional inline style for each rectangle. */
+    /** Optional inline style for each rectangle. Takes precedence over `color`. */
     rectStyle?: CSSProperties;
 }
 /**
@@ -928,7 +1114,7 @@ interface MejiroShelfProps<T = unknown> {
     currentId?: string;
     /** Called when the user picks a volume. */
     onSelect?: (volume: VolumeInfo<T>) => void;
-    /** Heading shown above the grid. @defaultValue 'Library' */
+    /** Heading shown above the grid. Defaults to the active message catalog's `shelfTitle`. */
     title?: string;
 }
 /**
@@ -937,55 +1123,6 @@ interface MejiroShelfProps<T = unknown> {
  */
 declare function MejiroShelf<T = unknown>({ volumes, currentId, onSelect, title, }: MejiroShelfProps<T>): ReactNode;
 
-/** A single image overlay placed on a specific spread. */
-interface MultiImageItem {
-    /** Stable ID for the overlay (auto-assigned on add). */
-    id: string;
-    /** Position and size in pixels, relative to the right page. */
-    rect: ImageRect;
-}
-/** Options for {@link useMultiImageOverlay}. */
-interface UseMultiImageOverlayOptions {
-    /** Default image width. @defaultValue 120 */
-    defaultWidth?: number;
-    /** Default image height. @defaultValue 160 */
-    defaultHeight?: number;
-    /** Default x. @defaultValue 80 */
-    defaultX?: number;
-    /** Default y. @defaultValue 100 */
-    defaultY?: number;
-    /** Margin around each image, in pixels. Defaults to the book's font size. */
-    margin?: number;
-    /** Called after every reflow caused by adding/removing/moving an image. */
-    onUpdate?: (spread: SpreadResult) => void;
-}
-/** Return value of {@link useMultiImageOverlay}. */
-interface UseMultiImageOverlayReturn {
-    /** Map of all images keyed by spread index. */
-    imagesBySpread: Map<number, MultiImageItem[]>;
-    /** Images on the current spread. */
-    currentImages: MultiImageItem[];
-    /** Whether any spread has at least one image. */
-    hasImages: boolean;
-    /** Add a new image on the current spread. */
-    addImage: (overrides?: Partial<ImageRect>) => MultiImageItem;
-    /** Remove the image with the given id. */
-    removeImage: (id: string) => void;
-    /** Replace an image's rectangle. */
-    updateImage: (id: string, rect: Partial<ImageRect>) => void;
-    /** Remove every image (or only those on `spreadIdx` if given). */
-    clearImages: (spreadIdx?: number) => void;
-    /** Pointer-down handler for the overlay body (drag). */
-    onOverlayPointerDown: (id: string, e: PointerEvent) => void;
-    /** Pointer-down handler for the resize handle. */
-    onResizePointerDown: (id: string, e: PointerEvent) => void;
-}
-/**
- * React hook that manages multiple draggable/resizable image overlays
- * per spread with automatic reflow via {@link ChapterLayout.setImages}.
- */
-declare function useMultiImageOverlay(layout: ChapterLayout | null, spreadIdx: number, options?: UseMultiImageOverlayOptions): UseMultiImageOverlayReturn;
-
 /** Props for {@link MejiroSpread}. */
 interface MejiroSpreadProps {
     /** Spread data to render. */
@@ -1008,9 +1145,17 @@ interface MejiroSpreadProps {
     rightHeader?: PageHeaderData;
     /** Header data for the left page. */
     leftHeader?: PageHeaderData;
-    /** Image overlays on the current spread. */
+    /**
+     * Image overlays on the current spread, relative to the right page. With
+     * {@link MejiroSpreadProps.singlePage}, only those whose centre lies on the
+     * page shown are drawn.
+     */
     images?: MultiImageItem[];
-    /** Force slot-mode rendering on both pages. */
+    /**
+     * 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;
@@ -1033,23 +1178,38 @@ interface MejiroSpreadProps {
      * 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 with `spreadIdx` other than
-     * the current spread are ignored.
+     * {@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[];
+    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;
     /**
-     * Hide the left page and render only the right page (centered). Use this
-     * for portrait viewports or when a reader explicitly opts into single-page
-     * mode.
+     * Render only one page of the spread (centered), chosen by
+     * {@link MejiroSpreadProps.singleSide}. Use this for portrait viewports or
+     * when a reader explicitly opts into single-page mode.
      */
     singlePage?: boolean;
+    /**
+     * Page of the spread shown when {@link MejiroSpreadProps.singlePage} is set
+     * (`useSpread` reports it as `singleSide`). @defaultValue 'right'
+     */
+    singleSide?: 'right' | 'left';
     /**
      * Called when the user makes a quick swipe gesture on the spread.
      * `direction === 'next'` means the user swiped from right to left (the
@@ -1060,10 +1220,11 @@ interface MejiroSpreadProps {
     onSurfaceTap?: () => void;
 }
 /**
- * Renders a two-page spread with the book frame, page chrome, navigation
- * zones, and image overlays. Used inside `mejiro-reader-surface`.
+ * Renders a two-page spread (or one page of it in single-page mode) with the
+ * book frame, page chrome, navigation zones, and image overlays. Used inside
+ * `mejiro-reader-surface`.
  */
-declare function MejiroSpread({ spread, pageWidth, pageHeight, contentHeight, fontFamily, fontSize, lineSpacing, turning, rightHeader, leftHeader, images, renderPageHeader, indicator, onPrev, onNext, onImagePointerDown, onImageResizePointerDown, onImageClose, anchorAtCoord, selectionRects, onSelectionChange, singlePage, onSwipe, onSurfaceTap, }: MejiroSpreadProps): ReactNode;
+declare function MejiroSpread({ spread, pageWidth, pageHeight, contentHeight, fontFamily, fontSize, lineSpacing, turning, rightHeader, leftHeader, images, slotMode, renderPageHeader, indicator, onPrev, onNext, onImagePointerDown, onImageResizePointerDown, onImageClose, anchorAtCoord, spreadIdx, selectionRects, onSelectionChange, singlePage, singleSide, onSwipe, onSurfaceTap, }: MejiroSpreadProps): ReactNode;
 
 /** Props for {@link MejiroStats}. */
 interface MejiroStatsProps {
@@ -1093,9 +1254,9 @@ interface MejiroTocProps {
     currentAnchor?: ReadingAnchor | null;
     /** Show a search input that filters chapter titles. @defaultValue false */
     searchable?: boolean;
-    /** Heading displayed above the list. @defaultValue 'Contents' */
+    /** Heading displayed above the list. Defaults to the active message catalog's `tocTitle`. */
     title?: string;
-    /** Placeholder shown in the search input. @defaultValue 'Search chapters…' */
+    /** Placeholder shown in the search input. Defaults to the active message catalog's `tocSearchPlaceholder`. */
     searchPlaceholder?: string;
     /** Called when the user picks a chapter. */
     onSelect?: (chapter: number) => void;
@@ -1116,6 +1277,8 @@ interface UseAnnotationsOptions {
     /**
      * 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;
     /** Throttle ms between writes. @defaultValue 250 */
@@ -1173,17 +1336,20 @@ interface UseChapterLayoutOptions {
      */
     pageGeometry?: () => ComputePageSizeOptions | undefined;
     /**
-     * Capture the current reading position from the outgoing layout, just before
-     * a **reflow** (non-blank) re-layout replaces it. The returned anchor is
-     * exposed via {@link UseChapterLayoutReturn.pendingRestore} and should be
-     * applied once the new layout commits. Return `null` to skip preservation.
-     * Never called for blank (content-change) re-layouts.
-     *
-     * A reflow yields a brand-new {@link ChapterLayout} object, which resets any
-     * downstream spread index to 0; capturing here and restoring after keeps the
-     * reader on the same passage across resizes and font / option changes.
+     * Capture the reading position from the outgoing layout, just before a
+     * **reflow** (non-blank) re-layout replaces it. The anchor is held in
+     * `pendingRestore` until the new layout is in place, then handed to
+     * `restorePosition` when one is given. Return `null` to skip preservation.
+     * Never called for blank (content-change) re-layouts, which start at spread 0.
      */
     capturePosition?: (layout: ChapterLayout) => InChapterAnchor | null;
+    /**
+     * Apply an anchor captured by `capturePosition` to the new layout, e.g. by
+     * locating it and jumping to its spread. Called once the new layout is in
+     * place — after it commits, before paint — and `pendingRestore` is cleared
+     * first. Without it, consume `pendingRestore` yourself.
+     */
+    restorePosition?: (layout: ChapterLayout, position: InChapterAnchor) => void;
 }
 /** Options for {@link UseChapterLayoutReturn.recompute}. */
 interface RecomputeOptions {
@@ -1197,8 +1363,11 @@ interface RecomputeOptions {
 }
 /** Page dimensions returned by {@link MejiroBook.computePageSize}. */
 interface PageDimensions {
+    /** Width of one page, in CSS pixels. */
     pageWidth: number;
+    /** Height of one page, in CSS pixels. */
     pageHeight: number;
+    /** Height of the text area inside a page, in CSS pixels. */
     contentHeight: number;
 }
 /** Return value of {@link useChapterLayout}. */
@@ -1216,11 +1385,17 @@ interface UseChapterLayoutReturn {
     /** Force a fresh layout computation. */
     recompute: (opts?: RecomputeOptions) => Promise<void>;
     /**
-     * Anchor captured before the most recent reflow re-layout, awaiting
-     * restoration into the new {@link layout}. Consume it in a layout effect keyed
-     * on `layout` (after any index reset) and clear it back to `null`.
+     * Anchor captured by `capturePosition` before the most recent reflow,
+     * awaiting restoration into the new layout. `restorePosition`, when given,
+     * consumes it; otherwise read it once the new layout is in place and set it
+     * back to `null`.
+     *
+     * Declared as a `MutableRefObject` because consumers are expected to write to
+     * it — `@types/react@18` models `RefObject.current` as read-only, so a
+     * `RefObject` here would make the documented recipe fail to compile on the
+     * lower end of the supported peer range.
      */
-    pendingRestore: RefObject<InChapterAnchor | null>;
+    pendingRestore: MutableRefObject<InChapterAnchor | null>;
 }
 /**
  * React hook that lays out the currently-selected chapter and re-flows when the
@@ -1232,13 +1407,16 @@ interface UseChapterLayoutReturn {
  * mounted before its container had a final box is still sized correctly on
  * first paint), and later size changes trigger a debounced **full re-layout**.
  *
- * A full re-layout — rather than a `ChapterLayout.resize()` fast-path — is used
- * for size changes on purpose: the fast-path only stretches `pageWidth` and does
- * not re-paginate, leaving sparse, half-empty pages after a non-trivial size
- * delta. Because a full re-layout yields a new {@link ChapterLayout} object
- * (resetting any downstream spread index to 0), the reading position is
- * preserved across reflows via {@link UseChapterLayoutOptions.capturePosition}
- * and {@link UseChapterLayoutReturn.pendingRestore}.
+ * Size and option changes lay the chapter out again rather than calling
+ * `ChapterLayout.resize()`, so page geometry is re-derived from the surface and
+ * the book's current options. The book replays the line-breaking hints it
+ * already derived for the chapter, so a reflow never re-runs the analyzer.
+ * Because each re-layout yields a new {@link ChapterLayout} object (resetting
+ * any downstream spread index to 0), the reading position is carried across
+ * reflows by {@link UseChapterLayoutOptions.capturePosition},
+ * {@link UseChapterLayoutOptions.restorePosition} and
+ * {@link UseChapterLayoutReturn.pendingRestore}, identically in the Vue
+ * composable.
  *
  * @param book - The book instance to lay out with.
  * @param epub - The current parsed EPUB.
@@ -1248,10 +1426,7 @@ interface UseChapterLayoutReturn {
  */
 declare function useChapterLayout(book: MejiroBook, epub: EpubBook | null, chapterIndex: number, surface: RefObject<HTMLElement | null>, options?: UseChapterLayoutOptions): UseChapterLayoutReturn;
 
-interface EditableEpubSelection {
-    chapter: number;
-    paragraph: number;
-}
+/** Options for {@link useEditableEpub}. */
 interface UseEditableEpubOptions {
     /** URL fetched and loaded on mount. */
     defaultUrl?: string;
@@ -1261,32 +1436,64 @@ interface UseEditableEpubOptions {
     onError?: (error: Error) => void;
     /** Called after export completes. */
     onExport?: (buffer: ArrayBuffer) => void;
+    /**
+     * 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>;
+    /**
+     * Resolves URL-only images into bytes when {@link UseEditableEpubReturn.exportEpub}
+     * packages the book. An `assetResolver` passed to `exportEpub` itself wins.
+     */
+    assetResolver?: AssetResolver;
 }
+/** Return value of {@link useEditableEpub}. */
 interface UseEditableEpubReturn {
+    /** Loaded editor, or `null` before any load. */
     editor: EditableEpub | null;
+    /** The editor's live document, or `null` before any load. */
     book: EditableEpubBook | null;
+    /** Snapshot of `book` re-cloned on every edit, for feeding a preview reader. */
     previewBook: EditableEpubBook | null;
+    /** Whether a load is in progress. */
     loading: boolean;
+    /** Whether an export is in progress. */
     exporting: boolean;
+    /** Last load error, if any. */
     error: Error | null;
+    /** Counter bumped on every load, edit, undo and redo. */
     revision: number;
+    /** Undo / redo availability, or `null` before any load. */
     history: {
         canUndo: boolean;
         canRedo: boolean;
         depth: number;
         redoDepth: number;
     } | null;
+    /** Paragraph targeted by the editing commands. */
     selection: EditableEpubSelection;
+    /** The paragraph at `selection`, or `null` when there is none. */
     selectedParagraph: AnnotatedParagraph | null;
+    /** Moves the selection, clamped to the loaded book. */
     setSelection: (selection: EditableEpubSelection) => void;
+    /** Loads an EPUB from an in-memory buffer. */
     loadBuffer: (buffer: ArrayBuffer) => Promise<EditableEpub | null>;
+    /** Loads an EPUB from a {@link File}. */
     loadFile: (file: File) => Promise<EditableEpub | null>;
+    /** Fetches and loads an EPUB; a non-2xx response is reported as an error. */
     loadUrl: (url: string) => Promise<EditableEpub | null>;
+    /** Replaces the selected paragraph's text and, optionally, its inline annotations. */
     updateParagraph: (text: string, inlineAnnotations?: readonly InlineAnnotation[]) => void;
+    /** Replaces the selected paragraph's inline annotations. */
     setInlineAnnotations: (inlineAnnotations: readonly InlineAnnotation[]) => void;
+    /** Inserts an image into the selected chapter. */
     addImage: (image: AddImageInput | EditableEpubImage) => void;
+    /** Reverts the last edit. Returns `false` when there is nothing to undo. */
     undo: () => boolean;
+    /** Re-applies the last undone edit. Returns `false` when there is nothing to redo. */
     redo: () => boolean;
+    /** Packages the edited document as an EPUB buffer. */
     exportEpub: (options?: EpubExportOptions) => Promise<ArrayBuffer | null>;
 }
 /** Headless editable-EPUB state for custom proofreading/editor UIs. */
@@ -1294,11 +1501,11 @@ declare function useEditableEpub(options?: UseEditableEpubOptions): UseEditableE
 
 /** Options for {@link useEpub}. */
 interface UseEpubOptions {
-    /** URL fetched on mount. A non-OK response is treated as "no default". */
+    /** URL fetched on mount. */
     defaultUrl?: string;
     /** Called after a successful load. */
     onLoad?: (book: EpubBook) => void;
-    /** Called when a load fails. Non-OK URL responses are still treated as "no default". */
+    /** Called when a load fails, including a non-2xx URL response. */
     onError?: (error: Error) => void;
     /**
      * Extra options merged into the `fetch` call when loading by URL. Useful
@@ -1311,6 +1518,12 @@ interface UseEpubOptions {
      * 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.
+     */
+    limits?: Partial<EpubParseLimits>;
 }
 /** Return value of {@link useEpub}. */
 interface UseEpubReturn {
@@ -1335,45 +1548,104 @@ interface UseEpubReturn {
  */
 declare function useEpub(options?: UseEpubOptions): UseEpubReturn;
 
+/** One chapter of the manuscript draft the hook keeps in React state. */
 interface EpubProjectChapterDraft {
+    /** Stable chapter identifier. */
     id: string;
+    /** Chapter title. */
     title: string;
+    /** Chapter body in the manuscript notation. */
     body: string;
 }
+/** Options for {@link useEpubProject}. */
 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[];
+    /** 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?: EpubProjectAsset;
+    /**
+     * Initial non-cover assets (illustrations, extra stylesheets). Same
+     * `data` / `url` choice as {@link UseEpubProjectOptions.cover}.
+     */
+    assets?: EpubProjectAsset[];
     /**
      * Resolves URL-only project assets into bytes when the preview or export
-     * pipeline materializes them. Forwarded to `project.export()`. Useful when
-     * cover / illustration assets are registered as remote URLs and you want
-     * the host (not the client) to provide auth headers.
+     * pipeline materializes them. Forwarded to `project.export()`. Register the
+     * URLs through {@link UseEpubProjectReturn.setCover} /
+     * {@link UseEpubProjectReturn.setAssets} and let the host (not the client)
+     * provide auth headers here.
      */
     assetResolver?: AssetResolver;
+    /** Called with each successfully rebuilt preview book. */
     onPreview?: (book: EpubBook) => void;
+    /** Called with the EPUB bytes produced by {@link UseEpubProjectReturn.exportEpub}. */
     onExport?: (buffer: ArrayBuffer) => void;
     /** Creates the default title for a generated chapter. */
     defaultChapterTitle?: (index: number) => string;
     /** Creates the default body for a generated chapter. */
     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[];
+    /** Index of the chapter being edited. */
     selectedChapter: number;
+    /** The chapter at `selectedChapter`, or `null` when there is none. */
     currentChapter: EpubProjectChapterDraft | null;
+    /** Current cover asset, or `null` when the project has no cover. */
+    cover: EpubProjectAsset | null;
+    /** Current non-cover assets, in registration order. */
+    assets: EpubProjectAsset[];
+    /** Parsed EPUB built from the current project, refreshed after each debounced change. */
     previewBook: EpubBook | null;
+    /** Last preview build failure, if any. */
     previewError: Error | null;
+    /** Whether a preview build is pending or running. */
     previewing: boolean;
+    /** Merges `patch` into the metadata. */
     setMetadata: (patch: Partial<EpubProjectMetadata>) => void;
+    /** Replaces every chapter; an empty list becomes one generated chapter. */
     setChapters: (chapters: EpubProjectChapterDraft[]) => void;
+    /** Selects a chapter, clamped to the chapter range. */
     setSelectedChapter: (index: number) => void;
+    /**
+     * Replaces the cover asset, or drops it when passed `null`. The new cover is
+     * reflected by both the debounced preview and {@link UseEpubProjectReturn.exportEpub}.
+     */
+    setCover: (asset: EpubProjectAsset | 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;
+    /** Merges `patch` into the chapter at `index`. */
     patchChapter: (index: number, patch: Partial<EpubProjectChapterDraft>) => void;
+    /** Appends a chapter (generated defaults fill omitted fields) and selects it. */
     addChapter: (chapter?: Partial<EpubProjectChapterDraft>) => void;
+    /**
+     * Removes the chapter at `index` (the selected one by default); the last chapter is never
+     * removed.
+     */
     removeChapter: (index?: number) => void;
+    /**
+     * Moves a chapter from `from` to `to`. An out-of-range `from` selects no
+     * chapter and leaves the list untouched; `to` is clamped to the list bounds —
+     * the same contract as `EpubProject.reorderChapters()`.
+     */
     reorderChapters: (from: number, to: number) => void;
+    /** Builds an `EpubProject` from the current state. */
     buildProject: () => EpubProject;
+    /** Packages the current project as an EPUB buffer. */
     exportEpub: () => Promise<ArrayBuffer>;
 }
 /** Headless manuscript-to-EPUB project state for custom authoring UIs. */
@@ -1401,14 +1673,24 @@ interface UseManuscriptDraftOptions<TAutosave = ManuscriptEditorChapter[]> {
 }
 /** Return value of {@link useManuscriptDraft}. */
 interface UseManuscriptDraftReturn {
+    /** Current chapters, in reading order. */
     chapters: ManuscriptEditorChapter[];
     /** Index of the chapter currently being edited. */
     selected: number;
+    /** Selects a chapter, clamped to the chapter range. */
     setSelected(index: number): void;
+    /**
+     * Replaces every chapter; an empty list becomes one generated chapter. The
+     * selected chapter is kept by id when it survives.
+     */
     setChapters(chapters: ManuscriptEditorChapter[]): void;
+    /** Merges `patch` into the chapter at `index`. */
     patchChapter(index: number, patch: Partial<ManuscriptEditorChapter>): void;
+    /** Appends a chapter (generated defaults fill omitted fields) and selects it. */
     addChapter(chapter?: Partial<ManuscriptEditorChapter>): void;
+    /** Removes the chapter at `index`; the last remaining chapter is never removed. */
     removeChapter(index: number): void;
+    /** Moves the chapter at `from` to `to`, keeping the same chapter selected. */
     reorderChapters(from: number, to: number): void;
     /** Last autosave failure, if any. */
     autosaveError: Error | null;
@@ -1432,11 +1714,39 @@ interface UseManuscriptLayoutOptions {
     enableResize?: boolean;
     /** Debounce window (ms) applied to size-triggered re-flows. @defaultValue 120 */
     resizeDebounce?: number;
+    /**
+     * Capture the reading position from the outgoing layout, just before a
+     * **reflow** (non-blank) re-layout replaces it. The anchor is held in
+     * `pendingRestore` until the new layout is in place, then handed to
+     * `restorePosition` when one is given. Return `null` to skip preservation.
+     * Never called for blank (content-change) re-layouts, which start at spread 0.
+     */
+    capturePosition?: (layout: ChapterLayout) => InChapterAnchor | null;
+    /**
+     * Apply an anchor captured by `capturePosition` to the new layout, e.g. by
+     * locating it and jumping to its spread. Called once the new layout is in
+     * place — after it commits, before paint — and `pendingRestore` is cleared
+     * first. Without it, consume `pendingRestore` yourself.
+     */
+    restorePosition?: (layout: ChapterLayout, position: InChapterAnchor) => void;
+}
+/** 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}. */
@@ -1452,7 +1762,14 @@ interface UseManuscriptLayoutReturn {
     /** Most recent layout time (ms). */
     elapsedMs: number;
     /** Force a fresh layout computation. */
-    recompute: () => Promise<void>;
+    recompute: (opts?: ManuscriptRecomputeOptions) => Promise<void>;
+    /**
+     * Anchor captured by `capturePosition` before the most recent reflow,
+     * awaiting restoration into the new layout. `restorePosition`, when given,
+     * consumes it; otherwise read it once the new layout is in place and set it
+     * back to `null`.
+     */
+    pendingRestore: MutableRefObject<InChapterAnchor | null>;
 }
 /**
  * React hook that lays out a single manuscript chapter directly, skipping the
@@ -1465,9 +1782,37 @@ interface UseManuscriptLayoutReturn {
  * Re-layouts whenever `chapter`, `dialect`, or `book` change. The surface is
  * observed with {@link ResizeObserver}; size changes trigger a full re-layout
  * so pagination stays correct after non-trivial container changes.
+ *
+ * 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,
+ * which resets any downstream spread index to 0; the reading position is
+ * preserved across such reflows via
+ * {@link UseManuscriptLayoutOptions.capturePosition},
+ * {@link UseManuscriptLayoutOptions.restorePosition} and
+ * {@link UseManuscriptLayoutReturn.pendingRestore}, identically in the Vue
+ * composable.
  */
 declare function useManuscriptLayout(book: MejiroBook, chapter: ManuscriptChapter | null, surface: RefObject<HTMLElement | null>, options?: UseManuscriptLayoutOptions): UseManuscriptLayoutReturn;
 
+/** Options for {@link useMejiroBook}. */
+interface UseMejiroBookOptions {
+    /**
+     * Coalescing window (ms) applied before a change reaches the underlying
+     * {@link MejiroBook}. The exposed snapshot is always updated synchronously so
+     * controlled settings UI stays responsive; only the book application — and the
+     * font load it may trigger — is debounced, so dragging a continuous control
+     * results in a single re-measurement. `0` applies immediately.
+     * @defaultValue 0
+     */
+    debounceMs?: number;
+    /**
+     * Called when applying options to the book fails. When supplied, failures are
+     * reported here and the promise returned by
+     * {@link UseMejiroBookReturn.setOptions} resolves instead of rejecting, so
+     * fire-and-forget callers cannot leave an unhandled rejection behind.
+     */
+    onError?: (error: Error) => void;
+}
 /** Return value of {@link useMejiroBook}. */
 interface UseMejiroBookReturn {
     /** The managed {@link MejiroBook} instance. Stable across renders. */
@@ -1475,9 +1820,10 @@ interface UseMejiroBookReturn {
     /** Reactive snapshot of the current options. */
     options: Readonly<BookOptions>;
     /**
-     * Update options on the underlying book and the snapshot. The returned
-     * promise resolves once {@link MejiroBook.setOptions} has propagated
-     * font / size changes (re-measurement runs lazily inside that call).
+     * 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
+     * complete only after the font has loaded).
      */
     setOptions: (next: Partial<BookOptions>) => Promise<void>;
 }
@@ -1486,8 +1832,11 @@ interface UseMejiroBookReturn {
  * 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).
+ *
+ * @param initial - Initial book options (passed to the {@link MejiroBook} constructor).
+ * @param options - Behavior overrides (debouncing, error reporting).
  */
-declare function useMejiroBook(initial: BookOptions): UseMejiroBookReturn;
+declare function useMejiroBook(initial: BookOptions, options?: UseMejiroBookOptions): UseMejiroBookReturn;
 
 /** Minimal storage interface required by {@link useReadingPosition}. */
 type ReadingPositionStorage = MejiroStorage;
@@ -1527,9 +1876,10 @@ interface UseReadingPositionReturn {
  * const { position, save } = useReadingPosition({ key: `mejiro:${bookId}` });
  * const reader = useRef<MejiroReaderHandle>(null);
  *
+ * // Restore once per mount: depending on `position` would re-run after every save().
  * useEffect(() => {
  *   if (position) reader.current?.goToAnchor(position);
- * }, [position]);
+ * }, []);
  *
  * useEffect(() => {
  *   const off = reader.current?.subscribe('spreadChanged', () => {
@@ -1552,33 +1902,53 @@ interface UseSpreadOptions {
     enableKeyboard?: boolean;
     /** Page-turn animation duration in ms. @defaultValue 180 */
     turnDuration?: number;
+    /**
+     * Show one page at a time: the navigation index then counts pages instead
+     * of two-page spreads. Toggling it converts the index so the page on
+     * screen stays visible. @defaultValue false
+     */
+    single?: boolean;
     /** Called when the spread index changes (after the turn animation midpoint). */
     onChange?: (spreadIdx: number) => void;
 }
 /** Return value of {@link useSpread}. */
 interface UseSpreadReturn {
-    /** Current spread index. */
+    /** Current navigation index: a page index in single mode, a spread index otherwise. */
     spreadIdx: number;
-    /** Current spread result, or `null` until the layout is ready. */
+    /** Layout spread holding the visible page(s), or `null` until the layout is ready. */
     spread: SpreadResult | null;
-    /** Total number of pages. */
+    /** First page shown, in reading order. */
+    firstPage: number;
+    /** Index of {@link UseSpreadReturn.spread} in the layout (`ChapterLayout.getSpread`). */
+    layoutSpreadIdx: number;
+    /** Side of {@link UseSpreadReturn.spread} shown in single mode; `null` in double mode. */
+    singleSide: 'right' | 'left' | null;
+    /** Total number of pages, as of {@link UseSpreadReturn.spread}. */
     totalPages: number;
-    /** Total number of two-page spreads. */
+    /** Number of navigation positions: pages in single mode, two-page spreads otherwise. */
     totalSpreads: number;
     /** Whether the turn animation is currently in flight. */
     turning: boolean;
-    /** Advance one spread forward. */
+    /** Advance one position (page or spread) forward. */
     next: () => void;
-    /** Go back one spread. */
+    /** Go back one position. */
     prev: () => void;
-    /** Jump to an arbitrary spread index (clamped). */
+    /** Jump to an arbitrary navigation index (clamped). */
     goTo: (index: number) => void;
     /**
-     * Set the spread index immediately, with no page-turn animation, clamped to
-     * `[0, totalSpreads − 1]`. Use to restore a reading position after a reflow
+     * Set the navigation index immediately, with no page-turn animation, clamped
+     * to `[0, totalSpreads − 1]`. Use to restore a reading position after a reflow
      * re-layout (where an animated {@link goTo} would briefly flash spread 0).
      */
     setSpread: (index: number) => void;
+    /** Navigation index that shows the given page index. */
+    indexOfPage: (pageIdx: number) => number;
+    /**
+     * Anchor at the start of the text shown at navigation index `index`. A page an
+     * image blocks entirely holds no text, so the anchor then comes from the next
+     * page that does, even past `index`; `null` when no page from there on holds text.
+     */
+    anchorAt: (index: number) => InChapterAnchor | null;
     /** Manually refresh `spread` from `layout` at the current index. */
     refresh: () => void;
 }
@@ -1588,4 +1958,4 @@ interface UseSpreadReturn {
  */
 declare function useSpread(layout: ChapterLayout | null, options?: UseSpreadOptions): UseSpreadReturn;
 
-export { type AnnotationsStorage, type EditableEpubSelection, type EpubProjectChapterDraft, type ImageRect, type ManuscriptEditorChapter, type ManuscriptPageDimensions, type ManuscriptPreviewProps, MejiroChapterNav, type MejiroChapterNavMode, type MejiroChapterNavProps, type MejiroChapterNavVariant, MejiroDropZone, type MejiroDropZoneProps, MejiroEditor, type MejiroEditorProps, type MejiroExportPolicy, MejiroI18nProvider, MejiroImageOverlay, type MejiroImageOverlayProps, MejiroManuscriptEditor, type MejiroManuscriptEditorProps, MejiroNotationHighlighter, type MejiroNotationHighlighterProps, MejiroPage, MejiroPageIndicator, type MejiroPageIndicatorProps, type MejiroPageProps, MejiroPageView, type MejiroPageViewProps, MejiroReader, type MejiroReaderControlledProps, type MejiroReaderEventMap, type MejiroReaderFileProps, type MejiroReaderFit, type MejiroReaderHandle, type MejiroReaderMode, type MejiroReaderProps, type MejiroReaderSettingsSlot, type MejiroReaderUrlProps, MejiroScrollView, type MejiroScrollViewProps, MejiroSelectionLayer, type MejiroSelectionLayerProps, MejiroSettingsPanel, type MejiroSettingsPanelProps, MejiroShelf, type MejiroShelfProps, MejiroSpread, type MejiroSpreadMode, type MejiroSpreadProps, MejiroStats, type MejiroStatsProps, type MejiroTheme, type MejiroThemeName, MejiroToc, type MejiroTocProps, type MultiImageItem, type PageDimensions, type PageNumberDisplay, type ReadingPosition, type ReadingPositionStorage, type UseAnnotationsOptions, type UseAnnotationsReturn, type UseChapterLayoutOptions, type UseChapterLayoutReturn, type UseEditableEpubOptions, type UseEditableEpubReturn, type UseEpubOptions, type UseEpubProjectOptions, type UseEpubProjectReturn, type UseEpubReturn, type UseI18nOptions, type UseImageOverlayOptions, type UseImageOverlayReturn, type UseLibraryOptions, type UseLibraryReturn, type UseManuscriptDraftOptions, type UseManuscriptDraftReturn, type UseManuscriptLayoutOptions, type UseManuscriptLayoutReturn, type UseMejiroBookReturn, type UseMultiImageOverlayOptions, type UseMultiImageOverlayReturn, type UseReadingPositionOptions, type UseReadingPositionReturn, type UseSpreadOptions, type UseSpreadReturn, type VolumeInfo, format, resolveMessages, useAnnotations, useChapterLayout, useEditableEpub, useEpub, useEpubProject, useI18n, useImageOverlay, useLibrary, useManuscriptDraft, useManuscriptLayout, useMejiroBook, useMultiImageOverlay, useReadingPosition, useSpread };
+export { type AnnotationsStorage, type EpubProjectChapterDraft, type ImageRect, type ManuscriptAutosaveDraft, type ManuscriptEditorChapter, type ManuscriptPageDimensions, type ManuscriptPreviewProps, type ManuscriptRecomputeOptions, MejiroChapterNav, type MejiroChapterNavMode, type MejiroChapterNavProps, type MejiroChapterNavVariant, MejiroDropZone, type MejiroDropZoneProps, MejiroEditor, type MejiroEditorProps, type MejiroExportPolicy, MejiroI18nProvider, MejiroImageOverlay, type MejiroImageOverlayProps, MejiroManuscriptEditor, type MejiroManuscriptEditorProps, MejiroNotationHighlighter, type MejiroNotationHighlighterProps, MejiroPage, MejiroPageIndicator, type MejiroPageIndicatorProps, type MejiroPageProps, MejiroPageView, type MejiroPageViewProps, MejiroReader, type MejiroReaderCommonProps, type MejiroReaderControlledProps, type MejiroReaderEventMap, type MejiroReaderFileProps, type MejiroReaderFit, type MejiroReaderHandle, type MejiroReaderManuscriptProps, type MejiroReaderMode, type MejiroReaderProps, type MejiroReaderSettingsSlot, type MejiroReaderUrlProps, MejiroScrollView, type MejiroScrollViewProps, MejiroSelectionLayer, type MejiroSelectionLayerProps, MejiroSettingsPanel, type MejiroSettingsPanelProps, MejiroShelf, type MejiroShelfProps, MejiroSpread, type MejiroSpreadMode, type MejiroSpreadProps, MejiroStats, type MejiroStatsProps, type MejiroTheme, type MejiroThemeName, MejiroToc, type MejiroTocProps, type MultiImageItem, type PageDimensions, type PageNumberDisplay, type ReadingPosition, type ReadingPositionStorage, type RecomputeOptions, type UseAnnotationsOptions, type UseAnnotationsReturn, type UseChapterLayoutOptions, type UseChapterLayoutReturn, type UseEditableEpubOptions, type UseEditableEpubReturn, type UseEpubOptions, type UseEpubProjectOptions, type UseEpubProjectReturn, type UseEpubReturn, type UseI18nOptions, type UseImageOverlayOptions, type UseImageOverlayReturn, type UseLibraryOptions, type UseLibraryReturn, type UseManuscriptDraftOptions, type UseManuscriptDraftReturn, type UseManuscriptLayoutOptions, type UseManuscriptLayoutReturn, type UseMejiroBookOptions, type UseMejiroBookReturn, type UseMultiImageOverlayOptions, type UseMultiImageOverlayReturn, type UseReadingPositionOptions, type UseReadingPositionReturn, type UseSpreadOptions, type UseSpreadReturn, type VolumeInfo, format, resolveMessages, useAnnotations, useChapterLayout, useEditableEpub, useEpub, useEpubProject, useI18n, useImageOverlay, useLibrary, useManuscriptDraft, useManuscriptLayout, useMejiroBook, useMultiImageOverlay, useReadingPosition, useSpread };