grimoire library

Classes

AnnotationCollection: The highlights and bookmarks kept for one book.
AnnotationQuery: Pure filtering, sorting, and section-grouping for highlights.
Book: A fully parsed book, independent of its source format.
BookmarkRecord: A quick bookmark: a named reading position — one section's document text at a character offset. The position is carried structurally (not as a serialized locator string) so hosts can re-target it into their own position vocabulary.
BookMetadata: Format-agnostic book metadata extracted from any supported book file.
BookProgression: Reading progression of a book as fractions of its canonical text.
BookSession: A progressive reading session over one book.
BoundaryEvent: A page turn hit the start/end of the current file.
ChromeToggleEvent: The center tap zone asked the host to toggle the chrome.
CustomHighlightColor: A highlight color outside the fixed palette, with one opaque #rrggbb value per theme brightness.
FontSizeBumpEvent: A wheel pinch/burst asking for a font size step.
FootnoteTapEvent: The reader tapped a link recognized as a footnote reference.
FragmentOffsetEvent: The viewer resolved a DOM fragment id to its documentText offset (reply to the locateFragment action).
GrimoirePageRenderer: Renders book pages off-screen and returns their pixels — the reader-level capability a parser cannot offer: a page only exists after layout, which is Grimoire's side of the boundary.
GrimoireView: Renders a parsed Book as a Calibre-style paginated reader.
HeadlessPageCapture: One off-screen WebView used by the page renderer to paint a book page and capture its pixels.
HeadlessPageCaptureFactory: Creates HeadlessPageCapture instances for the page renderer.
HighlightColor: A highlight color: a fixed HighlightPalette token or a custom light/dark hex pair, so a color picked against a light page stays readable on a dark page while keeping the persisted value stable.
HighlightRecord: A persistent highlight: a character range in one section's document text plus the surrounding context to relocate the range if offsets drift, and the EPUB CFI of the highlight start (stored alongside the character offsets for import/export interoperability).
HighlightTapEvent: A highlight was tapped by the user.
LinkTapEvent: A link was tapped (external http links are reported, not opened).
MathJaxLoader: Web variant of the MathJax loader: there is no disk cache, pages load the component straight from the CDN base (or a host-supplied mirror through baseUrl). Nothing is fetched ahead of time; the browser only downloads it when a math page requests the script.
MathJaxReadyEvent: MathJax finished typesetting the loaded page; column layout may have changed, so the reader re-flows and re-measures.
PageRenderTarget: Selects the page GrimoirePageRenderer paints.
PageTurnEvent: A horizontal swipe on a fixed-layout page (comic image page or PDF facsimile) asked the host to turn the page. Fixed-layout files are one file per page, so the host navigates the reading order instead of the JS column machinery.
PaletteHighlightColor: One of the fixed HighlightPalette colors.
PdfBook: A parsed PDF document.
PdfJsLoader: Web variant of the pdf.js loader: there is no disk cache, pages load the component straight from the CDN base (or a host-supplied mirror through baseUrl). Nothing is fetched ahead of time; the browser only downloads it when a facsimile page requests the script.
PdfJsSource: Platform-neutral handle the loader hands back after making the pdf.js component available.
PdfPasswordRequestEvent: The PDF document the viewer is rendering is password-protected and pdf.js refused to open it with the password supplied so far.
PositionEvent: The visible column / position changed.
ReadingSessionEvent: One stretch of active reading, for time tracking and Insights. A segment opens on the first reading event and closes after the controller's readingIdleTimeout without one, when a segment exceeds the internal cap, or when the controller is disposed.
ReadyEvent: The page finished booting (fires once per loaded file).
SelectionEvent: The text selection changed (empty text means cleared).
SessionPolicy: Byte and cover budgets of a progressive session.
ShortcutEvent: A keyboard shortcut the JS layer resolves to a host-side action.
TextLocator: A position or range in the document-text space of one reading-order section.
TextQuote: The exact text of a located range together with its immediate surrounding context — the W3C TextQuoteSelector analogue that lets fuzzy_relocation.dart re-anchor a TextLocator when the section text changed under its offsets.
TextSegment: One readable chunk (usually a sentence): start inclusive, end exclusive in the documentText space.
Unseal: Reads supported book formats through the current runtime's execution adapter.
ViewerBridge: Codec + event stream for the viewer bridge.
ViewerController: Drives the reader: two preloading webview engines, the book server, positions, bookmarks, highlights, search and settings.
ViewerEngine: A webview engine rendering one reader slot.
ViewerEngineFactory: Creates the engines used by a reader.
ViewerEvent: Events flowing from the viewer JS to Dart.
ViewerExportChapter: One chapter group of exportable entries.
ViewerExportItem: One exportable entry: a highlight or a bookmark.
ViewerExportModel: Immutable snapshot of a book's annotations, ready for rendering.
ViewerExportOptions: What goes into an export and how it is organized.
ViewerExportSource: The immutable annotation data needed to assemble an export document.
ViewerFixedLayoutSettings: Reader-side presentation overrides for fixed-layout EPUB pages.
ViewerHtmlExportOptions: Options for HTML export. All callbacks are optional: null callbacks render the built-in semantic defaults.
ViewerMargins: Per-side page margins in pixels (Calibre's margin_left/top/right/ bottom). In paged mode the left+right pair (horizontal writing) or top+bottom pair (vertical writing) doubles as the column gap, and the sides inset the rendered page; maxTextWidth and maxTextHeight cap the text block by growing the insets instead of shrinking the page (Calibre View.set_margins).
ViewerMarkdownExportOptions: Options for Markdown export. All callbacks are optional: null callbacks render the built-in defaults.
ViewerPageChange: A page turn: the visible location moved to another page (paged mode), chapter (any mode), or whole-percent progress (scroll mode). Persist reading progress from here instead of polling.
ViewerPosition: A reading position: file (by reading-order index) plus the character offset inside the file's text model.
ViewerSearchResult: A search hit inside the book.
ViewerSelection: A text selection reported by the viewer.
ViewerTheme: Color scheme and typography settings applied over the rendered book.
ViewerWordMark: A passive word mark: a word range in a file's text model plus the vocabulary state to render (the host's taxonomy — e.g. unknown/learning; anything class-name safe). Marks never intercept taps and never scroll the page.
ViewImageEvent: The reader tapped an inline image.

Enums

AnnotationSort: Ordering shared by annotation browsing and export snapshots.
BookFormat: The book formats supported by unseal.
BookJavaScriptPolicy: Controls JavaScript authored by the book's HTML.
BookPageCountMode: How much CPU the reader may spend measuring real book-wide page counts.
FixedPageZoomMode: How a fixed-layout EPUB page fits the viewport before user zoom.
HighlightDecoration: How a highlight draws over the text. Orthogonal to HighlightColor: a wavy underline in green is a valid combination (decoration is independent from the color token).
HighlightPalette: The fixed marker palette: five standard marker colors plus a separate proofreader-red token.
PageRenderKind: Which page of a book a render targets.
PdfReadingMode: How a PDF renders in the reader.
SearchMode: How a search query is interpreted.
ViewerExportItemKind: The kind of an exported entry.
ViewerExportLocationLinks: Which locator, if any, accompanies each exported item.
ViewerFootnoteMode: What tapping a footnote reference does.
ViewerLayoutMode: How the reader lays out pages.

Extensions

HighlightColorRendering on HighlightColor: Resolves Unseal's storage-safe color vocabulary into Flutter colors.
ViewerExportRendering on ViewerExportModel: Convenience rendering operations kept above the immutable document layer.

Constants

viewerHighlightPalette → const List<PaletteHighlightColor>: The marker colors offered by the built-in viewer controls.

Functions

buildViewerExportModel(ViewerExportSource source, {ViewerExportOptions options = const ViewerExportOptions()}) → ViewerExportModel: Snapshots annotations into an immutable export document.
decodeAnnotations(String json) → AnnotationCollection?: Decodes an encodeAnnotations envelope. Tolerant of per-entry damage: invalid entries are skipped, while a non-map or undecodable envelope, or an unknown (or missing) formatVersion, yields null. Missing collections decode to empty ones. Round-trips encodeAnnotations losslessly.
encodeAnnotations(AnnotationCollection collection) → String: Encodes collection as the versioned annotation envelope: {'formatVersion': 1, 'highlights': [...], 'bookmarks': [...]}.
locatorFromJson(Map<Object?, Object?> json) → BookLocator?: Decodes a BookLocator from a JSON map produced by locatorToJson.
locatorToJson(BookLocator locator) → Map<String, Object?>: Encodes locator into a versioned JSON map.
mergeBookmarks(List<BookmarkRecord> local, List<BookmarkRecord> incoming) → ({List<BookmarkRecord> bookmarks, bool changed}): Merges local and incoming bookmarks: a local and an incoming bookmark match when their bookmark titles match OR their position (sectionIndex, charOffset) matches — the earliest matching index winning when both lookups hit. Within a group the most recently timestamped copy wins and ties keep the local copy; the survivors are returned in reading position order, with the changed flag following the same rules as mergeHighlights.
mergeHighlights(List<HighlightRecord> local, List<HighlightRecord> incoming) → ({bool changed, List<HighlightRecord> highlights}): Merges local and incoming highlights: per HighlightRecord.id, the most recently timestamped copy wins and ties keep the local copy; the survivors are returned in reading position order.
relocateTextLocator(TextLocator locator, List<String> sectionTexts) → TextLocator?: Relocates locator against sectionTexts, the document texts of the reading-order sections.
segmentText(String text) → List<TextSegment>: Splits text into sentence segments.

Typedefs

ViewerHtmlPartFormatter = String? Function(ViewerExportItem item, ViewerExportChapter chapter): Per-part formatter for HTML export. Every callback that returns null (or is left null) falls back to the default rendering; a returned empty string omits that part entirely.
ViewerMarkdownPartFormatter = String? Function(ViewerExportItem item, ViewerExportChapter chapter): Per-part formatter for Markdown export. Every callback that returns null (or is left null) falls back to the default rendering; a returned empty string omits that part entirely.

Exceptions / Errors

SessionCancelledException: A pending operation was cancelled through BookSession.cancelPending.
SessionClosedException: The session was disposed; every operation — pending or new — fails until a new session opens.
SessionUnsupportedFormatException: The format cannot open as a progressive session (it has no random access container the session supports). Callers fall back to Unseal.read / Unseal.readFile.

Classes

Enums

Extensions

Constants

Functions

Typedefs

Exceptions / Errors

grimoire package

grimoire library