@libraz/mejiro-react 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -1,139 +1,12 @@
+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 * as react from 'react';
 import { ReactNode, CSSProperties, PointerEvent, TextareaHTMLAttributes, RefObject } from 'react';
 import { EpubBook, AssetResolver, EditableEpub, ManuscriptDialect, EpubChapter, EditableEpubBook, AnnotatedParagraph, AddImageInput, EditableEpubImage, EpubExportOptions, EpubProjectMetadata, EpubProject } from '@libraz/mejiro/epub';
-import { BookOptions, ChapterLayout, SpreadResult, PageResult, InChapterAnchor, ReadingAnchor, ManuscriptChapter, AnchorRect, AnchorRange, MejiroBook } from '@libraz/mejiro/book';
+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';
 
-/** All UI strings rendered by the bundled React components. */
-interface MejiroMessages {
-    /** Logo subtitle. */
-    readonly logoSubtitle: string;
-    /** Header "Open" button label. */
-    readonly openButton: string;
-    /** Header "Settings" button label. */
-    readonly settingsButton: string;
-    /** Header "Image" overlay button label. */
-    readonly imageButton: string;
-    /** ARIA label for removing an image overlay. */
-    readonly imageRemoveButton: string;
-    /** Loading-state body text. */
-    readonly loading: string;
-    /** ARIA label for the previous-spread nav zone. */
-    readonly prevSpread: string;
-    /** ARIA label for the next-spread nav zone. */
-    readonly nextSpread: string;
-    /** Settings panel group title — Font. */
-    readonly settingsFont: string;
-    /** Settings panel font-size label. */
-    readonly settingsSize: string;
-    /** Settings panel "decrease font size" button. */
-    readonly settingsSizeDown: string;
-    /** Settings panel "increase font size" button. */
-    readonly settingsSizeUp: string;
-    /** Settings panel group title — Layout. */
-    readonly settingsLayout: string;
-    /** Settings panel kinsoku label. */
-    readonly settingsKinsoku: string;
-    /** Settings panel hanging-punctuation label. */
-    readonly settingsHanging: string;
-    /** Settings panel line-spacing label. */
-    readonly settingsLineSpacing: string;
-    /** Settings panel "strict" kinsoku option. */
-    readonly settingsStrict: string;
-    /** Settings panel "loose" kinsoku option. */
-    readonly settingsLoose: string;
-    /** Settings panel "on" toggle option. */
-    readonly toggleOn: string;
-    /** Settings panel "off" toggle option. */
-    readonly toggleOff: string;
-    /** Drop zone primary text. */
-    readonly dropZoneTitle: string;
-    /** Drop zone secondary hint. */
-    readonly dropZoneHint: string;
-    /** TOC heading. */
-    readonly tocTitle: string;
-    /** TOC search placeholder. */
-    readonly tocSearchPlaceholder: string;
-    /** TOC empty-results template. Placeholder `{query}` is replaced. */
-    readonly tocEmpty: string;
-    /** Shelf heading. */
-    readonly shelfTitle: string;
-    /** Generic chapter-N template. Placeholder `{n}` is replaced. */
-    readonly chapterN: string;
-    /** Aria-live announcement template. Placeholders: `{spread}`, `{total}`. */
-    readonly spreadAnnouncement: string;
-    /** Embedded EPUB editor preview subtitle. */
-    readonly editorPreviewSubtitle: string;
-    /** EPUB editor panel title. */
-    readonly editorTitle: string;
-    /** EPUB editor empty-state title. */
-    readonly editorNoBookLoaded: string;
-    /** EPUB editor paragraph list section label. */
-    readonly editorParagraphs: string;
-    /** EPUB editor proofread section label. */
-    readonly editorProofread: string;
-    /** EPUB editor apply-text button label. */
-    readonly editorApplyText: string;
-    /** EPUB editor ruby section label. */
-    readonly editorRuby: string;
-    /** EPUB editor ruby usage hint. */
-    readonly editorRubyHint: string;
-    /** EPUB editor ruby selected-range template. Placeholders: `{start}`, `{end}`, `{count}`. */
-    readonly editorRubyRange: string;
-    /** EPUB editor ruby input placeholder. */
-    readonly editorRubyPlaceholder: string;
-    /** EPUB editor apply-ruby button label. */
-    readonly editorApplyRuby: string;
-    /** EPUB editor image section label. */
-    readonly editorImages: string;
-    /** EPUB editor insert-image button label. */
-    readonly editorInsertImageAfterParagraph: string;
-    /** EPUB editor export button label. */
-    readonly editorExportEpub: string;
-    /** Manuscript editor preview subtitle. */
-    readonly manuscriptPreviewSubtitle: string;
-    /** Manuscript editor panel title. */
-    readonly manuscriptTitle: string;
-    /** Manuscript editor ruby notation hint. */
-    readonly manuscriptRubyHint: string;
-    /** Manuscript editor metadata section label. */
-    readonly manuscriptMetadata: string;
-    /** Manuscript editor chapters section label. */
-    readonly manuscriptChapters: string;
-    /** Manuscript editor draft section label. */
-    readonly manuscriptDraft: string;
-    /** Manuscript editor cover chooser label. */
-    readonly manuscriptChooseCoverImage: string;
-    /** Manuscript editor default book title. */
-    readonly manuscriptDefaultTitle: string;
-    /** Manuscript editor default chapter title template. Placeholder `{n}` is replaced. */
-    readonly manuscriptDefaultChapterTitle: string;
-    /** Manuscript editor default draft body. */
-    readonly manuscriptDefaultBody: string;
-    /** Generic untitled fallback. */
-    readonly untitled: string;
-    /** Manuscript editor add-chapter button label. */
-    readonly manuscriptAddChapter: string;
-    /** Manuscript editor remove-chapter button label. */
-    readonly manuscriptRemove: string;
-    /** Manuscript editor emphasis-dots button label. */
-    readonly manuscriptEmphasisDots: string;
-    /** Manuscript editor tate-chu-yoko button label. */
-    readonly manuscriptTcy: string;
-    /** Manuscript editor emphasis button label. */
-    readonly manuscriptEm: string;
-    /** Manuscript editor strong button label. */
-    readonly manuscriptStrong: string;
-    /** ARIA label for the chapter drag handle. Placeholders: `{title}`. */
-    readonly manuscriptReorderHandle: string;
-}
-/** Built-in English catalog (the default). */
-declare const enMessages: MejiroMessages;
-/** Built-in Japanese catalog. */
-declare const jaMessages: MejiroMessages;
-/** Built-in locale identifiers. */
-type MejiroLocale = 'en' | 'ja';
 /** Provider that scopes a message catalog to its descendants. */
 declare function MejiroI18nProvider({ locale, messages, children, }: {
     locale?: MejiroLocale;
@@ -200,15 +73,6 @@ interface MejiroDropZoneProps {
  */
 declare function MejiroDropZone({ accept, validateFile, onFile, children, className, style, }: MejiroDropZoneProps): ReactNode;
 
-/** A font choice shown in the settings panel. */
-interface FontChoice {
-    /** CSS `font-family` value applied to the book. */
-    value: string;
-    /** Human-readable label. */
-    label: string;
-}
-/** Subset of {@link BookOptions} editable from the panel. */
-type EditableSettings = Pick<BookOptions, 'fontFamily' | 'fontSize' | 'lineSpacing' | 'mode' | 'enableHanging'>;
 /** Props for {@link MejiroSettingsPanel}. */
 interface MejiroSettingsPanelProps {
     /** Whether the panel is expanded. */
@@ -382,177 +246,6 @@ interface MejiroImageOverlayProps {
  */
 declare function MejiroImageOverlay({ rect, label, onOverlayPointerDown, onResizePointerDown, onClose, }: MejiroImageOverlayProps): ReactNode;
 
-interface ManuscriptEditorChapter {
-    id: string;
-    title: string;
-    body: string;
-}
-/**
- * Subset of {@link MejiroReader} props that the manuscript editor passes
- * through to the live preview. Properties driven by the editor itself
- * (`manuscript`, `fonts`, `chapter`, `onChapterChange`) are ignored if
- * supplied here.
- */
-interface ManuscriptPreviewProps {
-    subtitle?: string;
-    title?: string;
-    chapterNavMode?: 'select' | 'panel' | 'both' | 'none';
-    enableHeader?: boolean;
-    enableChapterNav?: boolean;
-    enableSettings?: boolean;
-    enableStats?: boolean;
-    enableKeyboard?: boolean;
-    enablePageIndicator?: boolean;
-    /**
-     * Toggle the surface-tap chrome-hide behavior of the embedded reader.
-     * Defaults to `false` here (the editor's preview is part of a side-by-side
-     * authoring workflow where tap-to-hide would surprise the author). Set
-     * to `true` to demo the fullscreen-reader behavior.
-     */
-    enableSurfaceTap?: boolean;
-    bare?: boolean;
-}
-interface MejiroManuscriptEditorProps {
-    /** Font choices passed to the preview reader. */
-    fonts?: FontChoice[];
-    /**
-     * Title. When `onTitleChange` is supplied, this is the controlled value
-     * (changes propagate from parent to the input). Otherwise it is the
-     * initial value and the editor manages its own title state.
-     */
-    title?: string;
-    /** Called whenever the title input changes. Enables controlled mode. */
-    onTitleChange?: (title: string) => void;
-    /**
-     * Author. Controlled when `onAuthorChange` is supplied; otherwise treated
-     * as the initial value.
-     */
-    author?: string;
-    /** Called whenever the author input changes. Enables controlled mode. */
-    onAuthorChange?: (author: string) => void;
-    /**
-     * Cover image. Controlled when `onCoverChange` is supplied; otherwise
-     * treated as the initial cover. Setting `null` clears the cover.
-     */
-    cover?: File | null;
-    /** Called whenever the cover changes. Enables controlled mode. */
-    onCoverChange?: (cover: File | null) => void;
-    /** Initial chapters. */
-    chapters?: ManuscriptEditorChapter[];
-    /**
-     * Called whenever the chapter draft settles (debounced by
-     * {@link MejiroManuscriptEditorProps.autosaveDelay}). Use to persist drafts
-     * to localStorage, IndexedDB, or upload to a server.
-     */
-    onAutosave?: (chapters: ManuscriptEditorChapter[]) => void | Promise<void>;
-    /** Autosave debounce in milliseconds. @defaultValue 800 */
-    autosaveDelay?: number;
-    /**
-     * Props forwarded to the embedded {@link MejiroReader} preview. Lets
-     * hosts customize subtitle / chapterNavMode / etc.; `manuscript`, `fonts`,
-     * `chapter`, and `onChapterChange` remain driven by the editor.
-     */
-    previewProps?: ManuscriptPreviewProps;
-    /**
-     * Resolves URL-only project assets (e.g. covers/illustrations registered as
-     * `{ url, ... }`) into bytes at export time. Forwarded to `project.export()`
-     * so authors can register signed-URL references without holding raw bytes
-     * client-side until publish.
-     */
-    assetResolver?: AssetResolver;
-    /** Called after export completes. */
-    onExport?: (buffer: ArrayBuffer) => void;
-}
-/** Manuscript-to-EPUB editor for author drafts from posting sites. */
-declare function MejiroManuscriptEditor({ fonts, title: titleProp, onTitleChange, author: authorProp, onAuthorChange, cover: coverProp, onCoverChange, chapters: initialChapters, onAutosave, autosaveDelay, previewProps, assetResolver, onExport, }: MejiroManuscriptEditorProps): ReactNode;
-
-/** Props for {@link MejiroNotationHighlighter}. */
-interface MejiroNotationHighlighterProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'onChange'> {
-    /** Source manuscript text. */
-    value: string;
-    /** Called whenever the textarea content changes. */
-    onChange: (next: string) => void;
-    /** Manuscript notation dialect. @defaultValue `'mejiro'` */
-    dialect?: ManuscriptDialect;
-    /** Class applied to the wrapper element. */
-    wrapperClassName?: string;
-    /** Inline style on the wrapper element. */
-    wrapperStyle?: CSSProperties;
-}
-/**
- * Textarea with a notation-highlight overlay. The overlay sits *behind* the
- * textarea and tints the background of manuscript notation tokens (ruby,
- * emphasis dots, tate-chu-yoko, em / strong, links, footnotes) so authors can
- * see at a glance which characters carry notation.
- *
- * The textarea is fully interactive; selection, undo / redo, and the
- * browser-native caret are unaffected. Notation kinds are exposed via
- * `data-token` attributes on the overlay spans so hosts can restyle them via
- * CSS (`.mejiro-notation-token[data-token="ruby"]` etc.).
- */
-declare const MejiroNotationHighlighter: react.ForwardRefExoticComponent<MejiroNotationHighlighterProps & react.RefAttributes<HTMLTextAreaElement>>;
-
-/** Props for the MejiroPage component. */
-interface MejiroPageProps {
-    /** Render page data from `buildRenderPage()`. */
-    page: RenderPage;
-    /** Additional CSS class name for the root element. */
-    className?: string;
-    /** Additional inline styles for the root element. */
-    style?: CSSProperties;
-}
-/**
- * Renders a mejiro page with vertical text layout.
- *
- * Converts a `RenderPage` data structure into DOM elements using
- * `mejiro-` prefixed CSS classes for layout.
- */
-declare function MejiroPage({ page, className, style }: MejiroPageProps): ReactNode;
-
-/** Props for {@link MejiroPageIndicator}. */
-interface MejiroPageIndicatorProps {
-    /** Current spread (1-based). */
-    current: number;
-    /** Total number of spreads. */
-    total: number;
-}
-/** Displays "current / total" spread position under the book. */
-declare function MejiroPageIndicator({ current, total }: MejiroPageIndicatorProps): ReactNode;
-
-/** Props for the MejiroPageView component. */
-interface MejiroPageViewProps {
-    /** Page result from {@link ChapterLayout.getSpread} or {@link ChapterLayout.getPage}. */
-    result: PageResult;
-    /** CSS font family for slot-based rendering (used when images are present). */
-    fontFamily?: FontFamily;
-    /** Line spacing multiplier for slot-based rendering (used when images are present). */
-    lineSpacing?: number;
-    /**
-     * Force slot-based rendering even when `result.hasImages` is false.
-     * Set to `true` when the layout has images on any spread, so that
-     * all pages use consistent slot-based rendering.
-     */
-    slotMode?: boolean;
-    /** Additional CSS class name for the root element. */
-    className?: string;
-    /** Additional inline styles for the root element. */
-    style?: CSSProperties;
-}
-/**
- * Renders a page from a {@link PageResult}.
- *
- * Automatically selects the rendering strategy:
- * - **Normal mode** (no images): Uses CSS `writing-mode: vertical-rl` via `<MejiroPage>`.
- * - **Slot mode** (images present): Uses absolute-positioned columns with per-line sizing.
- *
- * @example
- * ```tsx
- * const spread = layout.getSpread(0);
- * <MejiroPageView result={spread.right} fontFamily="serif" lineSpacing={1.8} />
- * ```
- */
-declare function MejiroPageView({ result, fontFamily, lineSpacing, slotMode, className, style, }: MejiroPageViewProps): ReactNode;
-
 type MejiroChapterNavMode = 'select' | 'panel' | 'both' | 'none';
 /**
  * Reading-flow mode for {@link MejiroReader}.
@@ -567,6 +260,22 @@ type MejiroReaderMode = 'paginated' | 'scroll';
  * - `auto` — switch based on the surface aspect ratio (single when portrait).
  */
 type MejiroSpreadMode = 'double' | 'single' | 'auto';
+/**
+ * Which page of a spread prints its page number: `'both'` (right = odd,
+ * left = even), only `'right'`, only `'left'`, or `'none'`.
+ */
+type PageNumberDisplay = 'both' | 'right' | 'left' | 'none';
+/**
+ * How the reader sizes itself inside its container.
+ * - `fill` — fill the container's given height; the spread is fitted inside it,
+ *   letterboxing if the box aspect doesn't match the spread (the default; the
+ *   host must give the reader a height).
+ * - `width` — self-size from width: the reader derives its own height from its
+ *   measured width and the page aspect ratio, so the spread fills exactly with
+ *   no letterbox and the host needs no height/aspect magic numbers. The host
+ *   only constrains the width.
+ */
+type MejiroReaderFit = 'fill' | 'width';
 /** Built-in reader theme presets. */
 type MejiroThemeName = 'light' | 'dark' | 'sepia' | 'high-contrast' | 'auto';
 /**
@@ -656,6 +365,23 @@ interface MejiroReaderHandle {
      */
     subscribe<E extends keyof MejiroReaderEventMap>(event: E, listener: MejiroReaderEventMap[E]): () => void;
 }
+/**
+ * Context passed to a {@link MejiroReaderCommonProps.renderSettings} render prop.
+ *
+ * Lets a host replace the built-in settings controls with its own UI while
+ * keeping the panel chrome and its open/close accordion. All fields are wired
+ * to the live reader.
+ */
+interface MejiroReaderSettingsSlot {
+    /** Current effective settings (font, size, line spacing, kinsoku, hanging). */
+    settings: EditableSettings;
+    /** Applies a partial settings change and re-flows the chapter. */
+    update: (partial: Partial<BookOptions>) => void;
+    /** Whether the settings panel is currently open. */
+    open: boolean;
+    /** Toggles the settings panel open/closed (same as the header button). */
+    toggle: () => void;
+}
 /** Props shared across every {@link MejiroReader} source mode. */
 interface MejiroReaderCommonProps {
     /**
@@ -667,7 +393,16 @@ interface MejiroReaderCommonProps {
      * { ...DEFAULT_BOOK_OPTIONS, fontFamily: '"Noto Serif JP"', fontSize: 18 }
      * ```
      */
-    options?: BookOptions;
+    options?: Partial<BookOptions>;
+    /**
+     * Page-geometry overrides forwarded to `MejiroBook.computePageSize`. Use to
+     * tune how the spread is sized inside the surface — most usefully to shrink
+     * the reserved margins so the pages fill their frame, e.g.
+     * `pageGeometry={{ gutterOffset: 0, headerOffset: 0 }}`. Also accepts
+     * `aspect`, `minWidth`, `minHeight`, `maxHeight`, and inner `padding`; omitted
+     * fields fall back to the built-in defaults.
+     */
+    pageGeometry?: ComputePageSizeOptions;
     /** Font choices for the settings panel. */
     fonts?: FontChoice[];
     /**
@@ -699,6 +434,16 @@ interface MejiroReaderCommonProps {
      * only the right page; `auto` flips to `single` for portrait viewports.
      */
     spreadMode?: MejiroSpreadMode;
+    /**
+     * How the reader sizes itself in its container. `fill` (default) fills the
+     * container height and letterboxes the spread; `width` makes the reader
+     * self-size — it derives its height from its width and the page aspect, so an
+     * embedding host only has to constrain the width (no height/aspect magic
+     * numbers, no letterbox). In `width` mode the reserved `gutterOffset` /
+     * `headerOffset` default to 0 so the spread fills edge-to-edge; override via
+     * {@link MejiroReaderProps.pageGeometry} if you still want them. @defaultValue 'fill'
+     */
+    fit?: MejiroReaderFit;
     /**
      * Enable surface-tap chrome toggling. Tapping the center of the spread
      * (away from buttons) hides the header and chapter panel; tapping again
@@ -769,6 +514,15 @@ interface MejiroReaderCommonProps {
     chapterNavMode?: MejiroChapterNavMode;
     /** Show the settings panel toggle. @defaultValue `!bare` */
     enableSettings?: boolean;
+    /**
+     * Replaces the built-in settings controls with custom UI while keeping the
+     * panel chrome and its open/close accordion. Receives a
+     * {@link MejiroReaderSettingsSlot} wired to the live reader, so a host can
+     * build its own settings form without a parallel `options` shadow. The header
+     * "Settings" button still toggles the panel. `enableSettings` remains the
+     * on/off switch.
+     */
+    renderSettings?: (slot: MejiroReaderSettingsSlot) => ReactNode;
     /** Show the image-overlay editing/demo button. @defaultValue false */
     enableImageOverlay?: boolean;
     /** Show the stats line. @defaultValue `!bare` */
@@ -777,6 +531,14 @@ interface MejiroReaderCommonProps {
     enableKeyboard?: boolean;
     /** Show the "n / total" indicator. @defaultValue `!bare` */
     enablePageIndicator?: boolean;
+    /**
+     * Which page of a spread shows its page number in the running head.
+     * `'both'` numbers each page (right = odd, left = even), `'right'` /
+     * `'left'` number only that side, `'none'` hides them (the
+     * {@link MejiroReaderProps.enablePageIndicator} "n / total" badge is
+     * independent). @defaultValue 'both'
+     */
+    pageNumbers?: PageNumberDisplay;
     /**
      * Reader-side annotations to render as highlights. Each annotation whose
      * `chapter` matches the current chapter is converted to spread-local
@@ -863,6 +625,190 @@ interface MejiroReaderManuscriptProps extends MejiroReaderCommonProps {
 type MejiroReaderProps = MejiroReaderControlledProps | MejiroReaderUrlProps | MejiroReaderFileProps | MejiroReaderManuscriptProps;
 declare const MejiroReader: react.ForwardRefExoticComponent<MejiroReaderProps & react.RefAttributes<MejiroReaderHandle>>;
 
+interface ManuscriptEditorChapter {
+    id: string;
+    title: string;
+    body: string;
+}
+/** Autosave payload emitted by {@link MejiroManuscriptEditor}. */
+interface ManuscriptAutosaveDraft {
+    title: string;
+    author: string;
+    cover: File | null;
+    chapters: ManuscriptEditorChapter[];
+}
+/**
+ * Subset of {@link MejiroReader} props that the manuscript editor passes
+ * through to the live preview. Properties driven by the editor itself
+ * (`manuscript`, `fonts`, `chapter`, `onChapterChange`) are ignored if
+ * supplied here.
+ */
+interface ManuscriptPreviewProps {
+    subtitle?: string;
+    title?: string;
+    chapterNavMode?: 'select' | 'panel' | 'both' | 'none';
+    enableHeader?: boolean;
+    enableChapterNav?: boolean;
+    enableSettings?: boolean;
+    enableStats?: boolean;
+    enableKeyboard?: boolean;
+    enablePageIndicator?: boolean;
+    /** Book options forwarded to the embedded reader preview. */
+    options?: Partial<BookOptions>;
+    /** Theme forwarded to the embedded reader preview. */
+    theme?: MejiroTheme;
+    /** Custom settings controls forwarded to the embedded reader preview. */
+    renderSettings?: (slot: MejiroReaderSettingsSlot) => ReactNode;
+    /**
+     * Toggle the surface-tap chrome-hide behavior of the embedded reader.
+     * Defaults to `false` here (the editor's preview is part of a side-by-side
+     * authoring workflow where tap-to-hide would surprise the author). Set
+     * to `true` to demo the fullscreen-reader behavior.
+     */
+    enableSurfaceTap?: boolean;
+    bare?: boolean;
+}
+interface MejiroManuscriptEditorProps {
+    /** Font choices passed to the preview reader. */
+    fonts?: FontChoice[];
+    /**
+     * Title. When `onTitleChange` is supplied, this is the controlled value
+     * (changes propagate from parent to the input). Otherwise it is the
+     * initial value and the editor manages its own title state.
+     */
+    title?: string;
+    /** Called whenever the title input changes. Enables controlled mode. */
+    onTitleChange?: (title: string) => void;
+    /**
+     * Author. Controlled when `onAuthorChange` is supplied; otherwise treated
+     * as the initial value.
+     */
+    author?: string;
+    /** Called whenever the author input changes. Enables controlled mode. */
+    onAuthorChange?: (author: string) => void;
+    /**
+     * Cover image. Controlled when `onCoverChange` is supplied; otherwise
+     * treated as the initial cover. Setting `null` clears the cover.
+     */
+    cover?: File | null;
+    /** Called whenever the cover changes. Enables controlled mode. */
+    onCoverChange?: (cover: File | null) => void;
+    /** Initial chapters. */
+    chapters?: ManuscriptEditorChapter[];
+    /**
+     * Called whenever the chapter draft settles (debounced by
+     * {@link MejiroManuscriptEditorProps.autosaveDelay}). Use to persist drafts
+     * to localStorage, IndexedDB, or upload to a server.
+     */
+    onAutosave?: (draft: ManuscriptAutosaveDraft) => void | Promise<void>;
+    /** Autosave debounce in milliseconds. @defaultValue 800 */
+    autosaveDelay?: number;
+    /**
+     * Props forwarded to the embedded {@link MejiroReader} preview. Lets
+     * hosts customize subtitle / chapterNavMode / etc.; `manuscript`, `fonts`,
+     * `chapter`, and `onChapterChange` remain driven by the editor.
+     */
+    previewProps?: ManuscriptPreviewProps;
+    /**
+     * Resolves URL-only project assets (e.g. covers/illustrations registered as
+     * `{ url, ... }`) into bytes at export time. Forwarded to `project.export()`
+     * so authors can register signed-URL references without holding raw bytes
+     * client-side until publish.
+     */
+    assetResolver?: AssetResolver;
+    /** Called after export completes. */
+    onExport?: (buffer: ArrayBuffer) => void;
+}
+/** Manuscript-to-EPUB editor for author drafts from posting sites. */
+declare function MejiroManuscriptEditor({ fonts, title: titleProp, onTitleChange, author: authorProp, onAuthorChange, cover: coverProp, onCoverChange, chapters: initialChapters, onAutosave, autosaveDelay, previewProps, assetResolver, onExport, }: MejiroManuscriptEditorProps): ReactNode;
+
+/** Props for {@link MejiroNotationHighlighter}. */
+interface MejiroNotationHighlighterProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'onChange'> {
+    /** Source manuscript text. */
+    value: string;
+    /** Called whenever the textarea content changes. */
+    onChange: (next: string) => void;
+    /** Manuscript notation dialect. @defaultValue `'mejiro'` */
+    dialect?: ManuscriptDialect;
+    /** Class applied to the wrapper element. */
+    wrapperClassName?: string;
+    /** Inline style on the wrapper element. */
+    wrapperStyle?: CSSProperties;
+}
+/**
+ * Textarea with a notation-highlight overlay. The overlay sits *behind* the
+ * textarea and tints the background of manuscript notation tokens (ruby,
+ * emphasis dots, tate-chu-yoko, em / strong, links, footnotes) so authors can
+ * see at a glance which characters carry notation.
+ *
+ * The textarea is fully interactive; selection, undo / redo, and the
+ * browser-native caret are unaffected. Notation kinds are exposed via
+ * `data-token` attributes on the overlay spans so hosts can restyle them via
+ * CSS (`.mejiro-notation-token[data-token="ruby"]` etc.).
+ */
+declare const MejiroNotationHighlighter: react.ForwardRefExoticComponent<MejiroNotationHighlighterProps & react.RefAttributes<HTMLTextAreaElement>>;
+
+/** Props for the MejiroPage component. */
+interface MejiroPageProps {
+    /** Render page data from `buildRenderPage()`. */
+    page: RenderPage;
+    /** Additional CSS class name for the root element. */
+    className?: string;
+    /** Additional inline styles for the root element. */
+    style?: CSSProperties;
+}
+/**
+ * Renders a mejiro page with vertical text layout.
+ *
+ * Converts a `RenderPage` data structure into DOM elements using
+ * `mejiro-` prefixed CSS classes for layout.
+ */
+declare function MejiroPage({ page, className, style }: MejiroPageProps): ReactNode;
+
+/** Props for {@link MejiroPageIndicator}. */
+interface MejiroPageIndicatorProps {
+    /** Current spread (1-based). */
+    current: number;
+    /** Total number of spreads. */
+    total: number;
+}
+/** Displays "current / total" spread position under the book. */
+declare function MejiroPageIndicator({ current, total }: MejiroPageIndicatorProps): ReactNode;
+
+/** Props for the MejiroPageView component. */
+interface MejiroPageViewProps {
+    /** Page result from {@link ChapterLayout.getSpread} or {@link ChapterLayout.getPage}. */
+    result: PageResult;
+    /** CSS font family for slot-based rendering (used when images are present). */
+    fontFamily?: FontFamily;
+    /** Line spacing multiplier for slot-based rendering (used when images are present). */
+    lineSpacing?: number;
+    /**
+     * Force slot-based rendering even when `result.hasImages` is false.
+     * Set to `true` when the layout has images on any spread, so that
+     * all pages use consistent slot-based rendering.
+     */
+    slotMode?: boolean;
+    /** Additional CSS class name for the root element. */
+    className?: string;
+    /** Additional inline styles for the root element. */
+    style?: CSSProperties;
+}
+/**
+ * Renders a page from a {@link PageResult}.
+ *
+ * Automatically selects the rendering strategy:
+ * - **Normal mode** (no images): Uses CSS `writing-mode: vertical-rl` via `<MejiroPage>`.
+ * - **Slot mode** (images present): Uses absolute-positioned columns with per-line sizing.
+ *
+ * @example
+ * ```tsx
+ * const spread = layout.getSpread(0);
+ * <MejiroPageView result={spread.right} fontFamily="serif" lineSpacing={1.8} />
+ * ```
+ */
+declare function MejiroPageView({ result, fontFamily, lineSpacing, slotMode, className, style, }: MejiroPageViewProps): ReactNode;
+
 /** Props for {@link MejiroScrollView}. */
 interface MejiroScrollViewProps {
     /** Layout containing the pages to render. */
@@ -885,7 +831,7 @@ interface MejiroScrollViewProps {
      * Visible page index reported to the parent as the user scrolls. The page
      * with the largest intersection with the viewport is treated as visible.
      */
-    onVisiblePageChange?: (pageIdx: number) => void;
+    onVisiblePageChange?: (pageIdx: number, source: 'user' | 'programmatic') => void;
     /**
      * Target page to scroll into view. When set, the view scrolls so that the
      * matching page sits at the top of the scroll container.
@@ -1040,13 +986,6 @@ interface UseMultiImageOverlayReturn {
  */
 declare function useMultiImageOverlay(layout: ChapterLayout | null, spreadIdx: number, options?: UseMultiImageOverlayOptions): UseMultiImageOverlayReturn;
 
-/** Per-page header data. */
-interface PageHeaderData {
-    /** Running title (left-aligned). */
-    title?: string;
-    /** Page number (right-aligned). `null` hides it. */
-    pageNumber?: number | null;
-}
 /** Props for {@link MejiroSpread}. */
 interface MejiroSpreadProps {
     /** Spread data to render. */
@@ -1168,34 +1107,8 @@ interface MejiroTocProps {
  */
 declare function MejiroToc({ epub, currentAnchor, searchable, title, searchPlaceholder, onSelect, }: MejiroTocProps): ReactNode;
 
-/**
- * A user-authored annotation on a book — a half-open range of in-chapter
- * anchors plus optional metadata (color, note). Pair with the `annotations`
- * prop on {@link MejiroReader} to render highlights, or with `goToAnchor` to
- * implement bookmarks.
- */
-interface Annotation {
-    /** Stable identifier. Auto-generated when omitted from {@link useAnnotations.add}. */
-    id: string;
-    /** Chapter the annotation lives in. */
-    chapter: number;
-    /** Range start (inclusive). */
-    start: InChapterAnchor;
-    /** Range end (exclusive). Equal to `start` for caret-style bookmarks. */
-    end: InChapterAnchor;
-    /** Free-form color identifier (e.g. `'yellow'`, `'#ffd166'`). */
-    color?: string;
-    /** Optional note text attached to the annotation. */
-    note?: string;
-    /** Unix epoch ms. Auto-set on {@link useAnnotations.add} when omitted. */
-    createdAt?: number;
-}
 /** Minimal storage interface required by {@link useAnnotations}. */
-interface AnnotationsStorage {
-    getItem(key: string): string | null;
-    setItem(key: string, value: string): void;
-    removeItem(key: string): void;
-}
+type AnnotationsStorage = MejiroStorage;
 /** Options for {@link useAnnotations}. */
 interface UseAnnotationsOptions {
     /** Storage key — usually scoped per-book (e.g. `mejiro:annotations:${bookId}`). */
@@ -1248,10 +1161,39 @@ declare function useAnnotations(options: UseAnnotationsOptions): UseAnnotationsR
 
 /** Options for {@link useChapterLayout}. */
 interface UseChapterLayoutOptions {
-    /** Listen for `window.resize` and re-flow on resize. @defaultValue true */
+    /** Observe the surface element for size changes and re-flow. @defaultValue true */
     enableResize?: boolean;
-    /** Debounce window (ms) for resize re-flows. @defaultValue 120 */
+    /** Debounce window (ms) applied to size-triggered re-flows. @defaultValue 120 */
     resizeDebounce?: number;
+    /**
+     * Resolver for page-geometry overrides forwarded to
+     * {@link MejiroBook.computePageSize} — e.g. to shrink the reserved
+     * `gutterOffset` / `headerOffset` so the pages fill their frame. Called on
+     * every (re)layout so it may return a value that changes over time.
+     */
+    pageGeometry?: () => ComputePageSizeOptions | undefined;
+    /**
+     * Capture the current reading position from the outgoing layout, just before
+     * a **reflow** (non-blank) re-layout replaces it. The returned anchor is
+     * exposed via {@link UseChapterLayoutReturn.pendingRestore} and should be
+     * applied once the new layout commits. Return `null` to skip preservation.
+     * Never called for blank (content-change) re-layouts.
+     *
+     * A reflow yields a brand-new {@link ChapterLayout} object, which resets any
+     * downstream spread index to 0; capturing here and restoring after keeps the
+     * reader on the same passage across resizes and font / option changes.
+     */
+    capturePosition?: (layout: ChapterLayout) => InChapterAnchor | null;
+}
+/** Options for {@link UseChapterLayoutReturn.recompute}. */
+interface RecomputeOptions {
+    /**
+     * Blank the current layout while the new one is computed. Use for content
+     * changes (chapter / book swaps); skip for size or option changes so the
+     * previous spread stays visible until the re-flow completes (no flicker).
+     * @defaultValue true
+     */
+    blank?: boolean;
 }
 /** Page dimensions returned by {@link MejiroBook.computePageSize}. */
 interface PageDimensions {
@@ -1272,14 +1214,37 @@ interface UseChapterLayoutReturn {
     /** Most recent layout time (ms). */
     elapsedMs: number;
     /** Force a fresh layout computation. */
-    recompute: () => Promise<void>;
+    recompute: (opts?: RecomputeOptions) => Promise<void>;
+    /**
+     * Anchor captured before the most recent reflow re-layout, awaiting
+     * restoration into the new {@link layout}. Consume it in a layout effect keyed
+     * on `layout` (after any index reset) and clear it back to `null`.
+     */
+    pendingRestore: RefObject<InChapterAnchor | null>;
 }
 /**
- * React hook that lays out the currently-selected chapter and re-flows on resize.
+ * React hook that lays out the currently-selected chapter and re-flows when the
+ * surface resizes.
+ *
+ * Re-layouts whenever `book`, `epub`, or `chapterIndex` change, against the
+ * dimensions of `surface`. The `surface` element is observed with a
+ * {@link ResizeObserver}: the first observation runs immediately (so a reader
+ * mounted before its container had a final box is still sized correctly on
+ * first paint), and later size changes trigger a debounced **full re-layout**.
  *
- * Re-layouts whenever `epub` or `chapterIndex` change. On `window.resize`,
- * page dimensions are recomputed and {@link ChapterLayout.resize} is called
- * instead of a full re-layout.
+ * A full re-layout — rather than a `ChapterLayout.resize()` fast-path — is used
+ * for size changes on purpose: the fast-path only stretches `pageWidth` and does
+ * not re-paginate, leaving sparse, half-empty pages after a non-trivial size
+ * delta. Because a full re-layout yields a new {@link ChapterLayout} object
+ * (resetting any downstream spread index to 0), the reading position is
+ * preserved across reflows via {@link UseChapterLayoutOptions.capturePosition}
+ * and {@link UseChapterLayoutReturn.pendingRestore}.
+ *
+ * @param book - The book instance to lay out with.
+ * @param epub - The current parsed EPUB.
+ * @param chapterIndex - Zero-based chapter index to lay out.
+ * @param surface - DOM ref for the reading surface used for page sizing.
+ * @param options - Behavior overrides.
  */
 declare function useChapterLayout(book: MejiroBook, epub: EpubBook | null, chapterIndex: number, surface: RefObject<HTMLElement | null>, options?: UseChapterLayoutOptions): UseChapterLayoutReturn;
 
@@ -1388,6 +1353,10 @@ interface UseEpubProjectOptions {
     assetResolver?: AssetResolver;
     onPreview?: (book: EpubBook) => void;
     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;
 }
 interface UseEpubProjectReturn {
     metadata: EpubProjectMetadata;
@@ -1411,16 +1380,24 @@ interface UseEpubProjectReturn {
 declare function useEpubProject(options?: UseEpubProjectOptions): UseEpubProjectReturn;
 
 /** Options for {@link useManuscriptDraft}. */
-interface UseManuscriptDraftOptions {
+interface UseManuscriptDraftOptions<TAutosave = ManuscriptEditorChapter[]> {
     /** Initial chapters. Defaults to a single empty chapter. */
     initialChapters?: ManuscriptEditorChapter[];
     /**
      * Called when the draft changes (debounced). Use to persist to
      * localStorage, IndexedDB, or upload to a server.
      */
-    onAutosave?: (chapters: ManuscriptEditorChapter[]) => void | Promise<void>;
+    onAutosave?: (draft: TAutosave) => void | Promise<void>;
+    /** Maps chapters to the autosave payload. Defaults to the chapter array. */
+    autosavePayload?: (chapters: ManuscriptEditorChapter[]) => TAutosave;
+    /** Extra key that triggers autosave when non-chapter metadata changes. */
+    autosaveKey?: string;
     /** Debounce delay in milliseconds. @defaultValue 800 */
     autosaveDelay?: number;
+    /** Creates the default title for a generated chapter. */
+    defaultChapterTitle?: (index: number) => string;
+    /** Creates the default body for a generated chapter. */
+    defaultChapterBody?: (index: number) => string;
 }
 /** Return value of {@link useManuscriptDraft}. */
 interface UseManuscriptDraftReturn {
@@ -1433,6 +1410,10 @@ interface UseManuscriptDraftReturn {
     addChapter(chapter?: Partial<ManuscriptEditorChapter>): void;
     removeChapter(index: number): void;
     reorderChapters(from: number, to: number): void;
+    /** Last autosave failure, if any. */
+    autosaveError: Error | null;
+    /** Immediately saves the latest dirty draft, if one exists. */
+    flushAutosave(): void;
 }
 /**
  * Reactive store for manuscript drafts.
@@ -1441,15 +1422,15 @@ interface UseManuscriptDraftReturn {
  * patching individual chapters, plus a debounced autosave hook that fires
  * `onAutosave` whenever the chapter list settles.
  */
-declare function useManuscriptDraft(options?: UseManuscriptDraftOptions): UseManuscriptDraftReturn;
+declare function useManuscriptDraft<TAutosave = ManuscriptEditorChapter[]>(options?: UseManuscriptDraftOptions<TAutosave>): UseManuscriptDraftReturn;
 
 /** Options for {@link useManuscriptLayout}. */
 interface UseManuscriptLayoutOptions {
     /** Manuscript notation dialect. @defaultValue `'mejiro'` */
     dialect?: ManuscriptDialect;
-    /** Listen for `window.resize` and re-flow on resize. @defaultValue true */
+    /** Observe the surface element for size changes and re-flow. @defaultValue true */
     enableResize?: boolean;
-    /** Debounce window (ms) for resize re-flows. @defaultValue 120 */
+    /** Debounce window (ms) applied to size-triggered re-flows. @defaultValue 120 */
     resizeDebounce?: number;
 }
 /** Page dimensions returned by {@link MejiroBook.computePageSize}. */
@@ -1481,9 +1462,9 @@ interface UseManuscriptLayoutReturn {
  * {@link useManuscriptDraft} for the chapter array and feed the resulting
  * {@link ChapterLayout} into {@link MejiroSpread} or {@link MejiroScrollView}.
  *
- * Re-layouts whenever `chapter`, `dialect`, or `book` change. On `window.resize`,
- * page dimensions are recomputed and {@link ChapterLayout.resize} is called
- * instead of a full re-layout.
+ * 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.
  */
 declare function useManuscriptLayout(book: MejiroBook, chapter: ManuscriptChapter | null, surface: RefObject<HTMLElement | null>, options?: UseManuscriptLayoutOptions): UseManuscriptLayoutReturn;
 
@@ -1508,18 +1489,8 @@ interface UseMejiroBookReturn {
  */
 declare function useMejiroBook(initial: BookOptions): UseMejiroBookReturn;
 
-/**
- * Persisted reading position. Anchor-shaped — pair with
- * {@link MejiroReaderHandle.goToAnchor} to restore the user's exact location
- * even after a reflow that invalidates spread indices.
- */
-type ReadingPositionValue = ReadingAnchor;
 /** Minimal storage interface required by {@link useReadingPosition}. */
-interface ReadingPositionStorage {
-    getItem(key: string): string | null;
-    setItem(key: string, value: string): void;
-    removeItem(key: string): void;
-}
+type ReadingPositionStorage = MejiroStorage;
 /** Options for {@link useReadingPosition}. */
 interface UseReadingPositionOptions {
     /** Storage key — usually scoped per-book (e.g. `mejiro:position:${bookId}`). */
@@ -1602,6 +1573,12 @@ interface UseSpreadReturn {
     prev: () => void;
     /** Jump to an arbitrary spread index (clamped). */
     goTo: (index: number) => void;
+    /**
+     * Set the spread index immediately, with no page-turn animation, clamped to
+     * `[0, totalSpreads − 1]`. Use to restore a reading position after a reflow
+     * re-layout (where an animated {@link goTo} would briefly flash spread 0).
+     */
+    setSpread: (index: number) => void;
     /** Manually refresh `spread` from `layout` at the current index. */
     refresh: () => void;
 }
@@ -1611,4 +1588,4 @@ interface UseSpreadReturn {
  */
 declare function useSpread(layout: ChapterLayout | null, options?: UseSpreadOptions): UseSpreadReturn;
 
-export { type Annotation, type AnnotationsStorage, type EditableEpubSelection, type EditableSettings, type EpubProjectChapterDraft, type FontChoice, type ImageRect, type ManuscriptEditorChapter, type ManuscriptPageDimensions, type ManuscriptPreviewProps, MejiroChapterNav, type MejiroChapterNavMode, type MejiroChapterNavProps, type MejiroChapterNavVariant, MejiroDropZone, type MejiroDropZoneProps, MejiroEditor, type MejiroEditorProps, type MejiroExportPolicy, MejiroI18nProvider, MejiroImageOverlay, type MejiroImageOverlayProps, type MejiroLocale, MejiroManuscriptEditor, type MejiroManuscriptEditorProps, type MejiroMessages, MejiroNotationHighlighter, type MejiroNotationHighlighterProps, MejiroPage, MejiroPageIndicator, type MejiroPageIndicatorProps, type MejiroPageProps, MejiroPageView, type MejiroPageViewProps, MejiroReader, type MejiroReaderControlledProps, type MejiroReaderEventMap, type MejiroReaderFileProps, type MejiroReaderHandle, type MejiroReaderMode, type MejiroReaderProps, type MejiroReaderUrlProps, MejiroScrollView, type MejiroScrollViewProps, MejiroSelectionLayer, type MejiroSelectionLayerProps, MejiroSettingsPanel, type MejiroSettingsPanelProps, MejiroShelf, type MejiroShelfProps, MejiroSpread, type MejiroSpreadMode, type MejiroSpreadProps, MejiroStats, type MejiroStatsProps, type MejiroTheme, type MejiroThemeName, MejiroToc, type MejiroTocProps, type MultiImageItem, type PageDimensions, type PageHeaderData, type ReadingPosition, type ReadingPositionStorage, type ReadingPositionValue, type UseAnnotationsOptions, type UseAnnotationsReturn, type UseChapterLayoutOptions, type UseChapterLayoutReturn, type UseEditableEpubOptions, type UseEditableEpubReturn, type UseEpubOptions, type UseEpubProjectOptions, type UseEpubProjectReturn, type UseEpubReturn, type UseI18nOptions, type UseImageOverlayOptions, type UseImageOverlayReturn, type UseLibraryOptions, type UseLibraryReturn, type UseManuscriptDraftOptions, type UseManuscriptDraftReturn, type UseManuscriptLayoutOptions, type UseManuscriptLayoutReturn, type UseMejiroBookReturn, type UseMultiImageOverlayOptions, type UseMultiImageOverlayReturn, type UseReadingPositionOptions, type UseReadingPositionReturn, type UseSpreadOptions, type UseSpreadReturn, type VolumeInfo, enMessages, format, jaMessages, resolveMessages, useAnnotations, useChapterLayout, useEditableEpub, useEpub, useEpubProject, useI18n, useImageOverlay, useLibrary, useManuscriptDraft, useManuscriptLayout, useMejiroBook, useMultiImageOverlay, useReadingPosition, useSpread };
+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 };