@libraz/mejiro-react 0.8.0 → 0.9.0

package/README.md

@@ -1,9 +1,11 @@
 # @libraz/mejiro-react
 
-[![npm version](https://img.shields.io/npm/v/@libraz/mejiro-react.svg)](https://www.npmjs.com/package/@libraz/mejiro-react)
-[![license](https://img.shields.io/npm/l/@libraz/mejiro-react.svg)](https://github.com/libraz/mejiro/blob/main/LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/libraz/mejiro/ci.yml?branch=main&label=CI)](https://github.com/libraz/mejiro/actions)
+[![npm](https://img.shields.io/npm/v/@libraz/mejiro-react)](https://www.npmjs.com/package/@libraz/mejiro-react)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/libraz/mejiro/blob/main/LICENSE)
+[![core](https://img.shields.io/npm/v/@libraz/mejiro?label=%40libraz%2Fmejiro)](https://www.npmjs.com/package/@libraz/mejiro)
 
-React components and hooks for [mejiro](https://www.npmjs.com/package/@libraz/mejiro) — vertical text rendering plus full-featured `MejiroReader` / `MejiroEditor` / `MejiroManuscriptEditor` components.
+**React components and hooks for [mejiro](https://www.npmjs.com/package/@libraz/mejiro).** Render vertical text yourself with the hooks, or drop in the `MejiroReader` / `MejiroEditor` / `MejiroManuscriptEditor` components, with `MejiroShelf` and `MejiroToc` for library and table-of-contents screens.
 
 ## Install
 
@@ -51,8 +53,15 @@ npx degit libraz/mejiro/examples/react my-reader
 npx degit libraz/mejiro/examples/react-shelf my-library
 npx degit libraz/mejiro/examples/react-editor my-editor
 npx degit libraz/mejiro/examples/react-manuscript my-author
+npx degit libraz/mejiro/examples/react-embed my-embed
+npx degit libraz/mejiro/examples/react-headless my-headless
 ```
 
+Templates are workspace members, so the copied `package.json` still carries
+`workspace:*` versions. Each starter's own `README.md` carries the exact
+one-liner that rewrites them to the matching published release — run it before
+`npm install`.
+
 ## Documentation
 
 - [React / Vue guide](https://github.com/libraz/mejiro/tree/main/docs/en/08-react-and-vue.md) — components, hooks, props, theming, SSR

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';
@@ -69,7 +70,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;
 
@@ -139,6 +142,12 @@ 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. */
@@ -148,9 +157,9 @@ interface MejiroEditorProps {
 }
 /**
  * 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 +175,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 +212,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 +226,10 @@ 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 or `spreadIdx` changes, so a re-layout or a page turn 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.
@@ -357,6 +373,11 @@ 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
+     * (typically a font that could not be loaded) is reported through
+     * {@link MejiroReaderProps.onError} rather than rejecting the promise.
      */
     setOptions(partial: Partial<BookOptions>): Promise<void>;
     /**
@@ -462,6 +483,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?: EpubParseLimits;
     /**
      * Custom EPUB fetcher used in place of the global `fetch`. Overrides
      * {@link fetchOptions} when set.
@@ -542,9 +570,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 +583,10 @@ 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 (typically a font that could not be loaded).
+     */
     onError?: (error: Error) => void;
     /** Called when the chapter index changes. */
     onChapterChange?: (chapter: number) => void;
@@ -668,6 +700,7 @@ interface ManuscriptPreviewProps {
     enableSurfaceTap?: boolean;
     bare?: boolean;
 }
+/** Props for {@link MejiroManuscriptEditor}. */
 interface MejiroManuscriptEditorProps {
     /** Font choices passed to the preview reader. */
     fonts?: FontChoice[];
@@ -695,6 +728,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 +749,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'> {
@@ -846,7 +898,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, }: MejiroScrollViewProps): ReactNode;
 
 /** Props for {@link MejiroSelectionLayer}. */
 interface MejiroSelectionLayerProps {
@@ -854,8 +906,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 +922,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;
 }
 /**
@@ -1010,7 +1068,11 @@ interface MejiroSpreadProps {
     leftHeader?: PageHeaderData;
     /** Image overlays on the current spread. */
     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,12 +1095,22 @@ 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.
@@ -1063,7 +1135,7 @@ interface MejiroSpreadProps {
  * Renders a two-page spread with the book frame, page chrome, navigation
  * zones, and image overlays. Used inside `mejiro-reader-surface`.
  */
-declare function MejiroSpread({ spread, pageWidth, pageHeight, contentHeight, fontFamily, fontSize, lineSpacing, turning, rightHeader, leftHeader, images, renderPageHeader, indicator, onPrev, onNext, onImagePointerDown, onImageResizePointerDown, onImageClose, anchorAtCoord, selectionRects, onSelectionChange, singlePage, onSwipe, onSurfaceTap, }: MejiroSpreadProps): ReactNode;
+declare function MejiroSpread({ spread, pageWidth, pageHeight, contentHeight, fontFamily, fontSize, lineSpacing, turning, rightHeader, leftHeader, images, slotMode, renderPageHeader, indicator, onPrev, onNext, onImagePointerDown, onImageResizePointerDown, onImageClose, anchorAtCoord, spreadIdx, selectionRects, onSelectionChange, singlePage, onSwipe, onSurfaceTap, }: MejiroSpreadProps): ReactNode;
 
 /** Props for {@link MejiroStats}. */
 interface MejiroStatsProps {
@@ -1116,6 +1188,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 */
@@ -1219,8 +1293,13 @@ interface UseChapterLayoutReturn {
      * 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`.
+     *
+     * 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
@@ -1248,10 +1327,6 @@ 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;
-}
 interface UseEditableEpubOptions {
     /** URL fetched and loaded on mount. */
     defaultUrl?: string;
@@ -1261,6 +1336,12 @@ 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>;
 }
 interface UseEditableEpubReturn {
     editor: EditableEpub | null;
@@ -1311,6 +1392,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,43 +1422,81 @@ interface UseEpubReturn {
  */
 declare function useEpub(options?: UseEpubOptions): UseEpubReturn;
 
+/** One chapter of the manuscript draft the hook keeps in React state. */
 interface EpubProjectChapterDraft {
     id: string;
     title: string;
     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 {
     metadata: EpubProjectMetadata;
     chapters: EpubProjectChapterDraft[];
     selectedChapter: number;
     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[];
     previewBook: EpubBook | null;
     previewError: Error | null;
     previewing: boolean;
     setMetadata: (patch: Partial<EpubProjectMetadata>) => void;
     setChapters: (chapters: EpubProjectChapterDraft[]) => void;
     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;
     patchChapter: (index: number, patch: Partial<EpubProjectChapterDraft>) => void;
     addChapter: (chapter?: Partial<EpubProjectChapterDraft>) => 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 —
+     * the same contract as `EpubProject.reorderChapters()`.
+     */
     reorderChapters: (from: number, to: number) => void;
     buildProject: () => EpubProject;
     exportEpub: () => Promise<ArrayBuffer>;
@@ -1432,6 +1557,24 @@ interface UseManuscriptLayoutOptions {
     enableResize?: boolean;
     /** Debounce window (ms) applied to size-triggered re-flows. @defaultValue 120 */
     resizeDebounce?: number;
+    /**
+     * Capture the current reading position from the outgoing layout, just before
+     * a **reflow** (non-blank) re-layout replaces it. The returned anchor is
+     * exposed via {@link UseManuscriptLayoutReturn.pendingRestore} and should be
+     * applied once the new layout commits. Return `null` to skip preservation.
+     * Never called for blank (content-change) re-layouts.
+     */
+    capturePosition?: (layout: ChapterLayout) => InChapterAnchor | null;
+}
+/** 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 {
@@ -1452,7 +1595,13 @@ interface UseManuscriptLayoutReturn {
     /** Most recent layout time (ms). */
     elapsedMs: number;
     /** Force a fresh layout computation. */
-    recompute: () => Promise<void>;
+    recompute: (opts?: ManuscriptRecomputeOptions) => Promise<void>;
+    /**
+     * Anchor captured before the most recent reflow re-layout, awaiting
+     * restoration into the new {@link layout}. Consume it in a layout effect keyed
+     * on `layout` (after any index reset) and clear it back to `null`.
+     */
+    pendingRestore: MutableRefObject<InChapterAnchor | null>;
 }
 /**
  * React hook that lays out a single manuscript chapter directly, skipping the
@@ -1465,9 +1614,36 @@ 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} and
+ * {@link UseManuscriptLayoutReturn.pendingRestore}.
  */
 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 — typically a font that
+     * could not be loaded. When supplied, failures are reported here and the
+     * promise returned by {@link UseMejiroBookReturn.setOptions} resolves instead
+     * of rejecting, so fire-and-forget callers cannot leave an unhandled
+     * rejection behind.
+     */
+    onError?: (error: Error) => void;
+}
 /** Return value of {@link useMejiroBook}. */
 interface UseMejiroBookReturn {
     /** The managed {@link MejiroBook} instance. Stable across renders. */
@@ -1475,9 +1651,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 +1663,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;
@@ -1588,4 +1768,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 };