zreader 0.0.0-stage → 0.2.0

package/dist/core/index.d.ts

@@ -0,0 +1,262 @@
+import { R as ReaderClientOptions, a as ReaderSettings, P as Pad, b as BookProgress, H as Highlight, c as Bookmark, d as PadScope, A as Anchor, T as TocEntry } from '../types-xkdpkPxA.js';
+export { B as BookMeta, C as ChapterMeta, e as ChapterProgress, F as FONT_FAMILIES, f as FontFamily, g as HIGHLIGHT_COLORS, h as HighlightColor, I as ISODate, L as LEADINGS, i as Leading, M as MEASURES, j as Measure, k as PadScopeKind, l as TEXT_SIZES, m as THEMES, n as TextSize, o as ThemeName } from '../types-xkdpkPxA.js';
+export { B as BLOCK_TAGS, a as BLOCK_TAG_NAMES, c as createBlockIdAllocator, b as createSlugger, h as hashString, n as normalizeBlockText } from '../blocks-DwR7l7pz.js';
+
+/** Pluggable key/value storage. localStorage by default, memory for SSR/tests. */
+interface StorageAdapter {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+    keys(prefix?: string): string[];
+    /** Notified when another tab/window changes `key` (or any key if `key` is null). */
+    subscribe(listener: (key: string | null) => void): () => void;
+}
+declare class StorageQuotaError extends Error {
+    readonly key: string;
+    constructor(key: string, cause?: unknown);
+}
+declare function createMemoryAdapter(initial?: Record<string, string>): StorageAdapter & {
+    dump(): Record<string, string>;
+};
+/** Returns `null` when localStorage is unavailable (SSR, privacy mode, sandboxed iframes). */
+declare function getLocalStorage(): Storage | null;
+declare function createLocalStorageAdapter(storage?: Storage | null): StorageAdapter;
+/**
+ * Ask the browser not to evict our data (Safari ITP / storage pressure).
+ * Resolves to whether persistence is granted. Never throws.
+ */
+declare function requestPersistentStorage(): Promise<boolean>;
+
+interface Cell<T> {
+    /** Stable reference until the value changes (safe for useSyncExternalStore). */
+    get(): T;
+    set(next: T | ((prev: T) => T)): void;
+    subscribe(listener: () => void): () => void;
+}
+interface ReaderStoreOptions {
+    adapter?: StorageAdapter;
+    options?: Partial<ReaderClientOptions>;
+    /** Debounce for writes (ms). Writes are also flushed on `pagehide`. */
+    writeDelay?: number;
+    onError?: (error: unknown) => void;
+    now?: () => Date;
+    id?: () => string;
+}
+type ReaderStore = ReturnType<typeof createReaderStore>;
+declare function padKeySuffix(scope: PadScope): string;
+declare function defaultId(): string;
+declare function createReaderStore(opts?: ReaderStoreOptions): {
+    options: ReaderClientOptions;
+    adapter: StorageAdapter;
+    server: {
+        settings: ReaderSettings;
+        list: never[];
+        pad: Pad;
+        progress(bookId: string): BookProgress;
+    };
+    prefix: string;
+    settings: () => Cell<ReaderSettings>;
+    highlights: (bookId: string) => Cell<Highlight[]>;
+    bookmarks: (bookId: string) => Cell<Bookmark[]>;
+    progress: (bookId: string) => Cell<BookProgress>;
+    pad: (scope: PadScope) => Cell<Pad>;
+    updateSettings(patch: Partial<Omit<ReaderSettings, "updatedAt">>): void;
+    resetSettings(): void;
+    addHighlight(input: {
+        bookId: string;
+        chapterId: string;
+        anchor: Anchor;
+        color?: string;
+        note?: string;
+    }): Highlight;
+    updateHighlight(bookId: string, id: string, patch: Partial<Pick<Highlight, "color" | "note" | "anchor">>): void;
+    removeHighlight(bookId: string, id: string): void;
+    addBookmark(input: Omit<Bookmark, "id" | "createdAt" | "updatedAt">): Bookmark;
+    removeBookmark(bookId: string, id: string): void;
+    findChapterBookmark(bookId: string, chapterId: string): Bookmark | undefined;
+    /** Toggle a whole-chapter bookmark. Returns whether the chapter is now bookmarked. */
+    toggleChapterBookmark(bookId: string, chapterId: string, label?: string): boolean;
+    recordProgress(bookId: string, chapterId: string, p: {
+        blockId?: string;
+        percent: number;
+    }): void;
+    markChapterComplete(bookId: string, chapterId: string, completed?: boolean): void;
+    savePad(scope: PadScope, markdown: string, json?: unknown): void;
+    /** Append markdown to a pad from outside the editor (drops the JSON cache so the editor re-parses). */
+    appendToPad(scope: PadScope, markdown: string): void;
+    clearPad(scope: PadScope): void;
+    /** All storage keys owned by this store's prefix. */
+    keys(): string[];
+    flush: () => void;
+    connect: () => () => void;
+    /** Drop cached cells so the next read comes from storage (used after imports). */
+    reloadAll(): void;
+};
+/** Markdown blockquote for a passage, optionally linking back to its source. */
+declare function quoteToMarkdown(text: string, opts?: {
+    href?: string;
+    note?: string;
+}): string;
+/** Markdown snippet used when sending a highlight to the scratchpad. */
+declare function highlightToMarkdown(h: Pick<Highlight, "anchor" | "note">, href?: string): string;
+
+/**
+ * Every persisted value is wrapped in an envelope carrying its schema version so
+ * records written by older versions of the package can be migrated forward.
+ */
+interface Envelope<T = unknown> {
+    v: number;
+    data: T;
+}
+type RecordType = "settings" | "highlights" | "bookmarks" | "progress" | "pad";
+type Migration = (data: unknown) => unknown;
+/**
+ * `MIGRATIONS[type][i]` upgrades data from version `i + 1` to `i + 2`.
+ * Add a function here (never edit an old one) whenever a record shape changes.
+ */
+declare const MIGRATIONS: Record<RecordType, Migration[]>;
+declare function currentVersion(type: RecordType, migrations?: Record<RecordType, Migration[]>): number;
+declare function wrap<T>(type: RecordType, data: T, migrations?: Record<RecordType, Migration[]>): string;
+/** Parse + migrate. Returns `undefined` for missing, corrupt, or future-version data. */
+declare function unwrap(type: RecordType, raw: string | null, migrations?: Record<RecordType, Migration[]>): unknown;
+declare function isAnchor(x: unknown): x is Anchor;
+declare function isHighlight(x: unknown): x is Highlight;
+declare function isBookmark(x: unknown): x is Bookmark;
+
+declare const BACKUP_FORMAT = "zreader-backup";
+/** Backups written before the rename to zreader; still accepted on import. */
+declare const LEGACY_BACKUP_FORMATS: readonly string[];
+declare const BACKUP_VERSION = 1;
+interface Backup {
+    format: typeof BACKUP_FORMAT | "alr-backup";
+    schemaVersion: number;
+    exportedAt: string;
+    /** Keys are store-relative (prefix stripped), values are stored envelopes. */
+    records: Record<string, Envelope>;
+}
+declare function recordTypeForKey(key: string): RecordType | null;
+declare function exportBackup(store: ReaderStore, opts?: {
+    bookId?: string;
+}): Backup;
+declare class BackupFormatError extends Error {
+    constructor(message: string);
+}
+declare function parseBackup(input: string | unknown): Backup;
+interface ImportResult {
+    imported: number;
+    skipped: number;
+}
+/**
+ * Import a backup. `merge` (default) unions lists by id and keeps the most recently
+ * updated version of every record; `replace` wipes this store's keys first.
+ */
+declare function importBackup(store: ReaderStore, input: string | Backup, opts?: {
+    mode?: "merge" | "replace";
+}): ImportResult;
+/** Human-readable export of a book's highlights and notes. */
+declare function highlightsToMarkdown(title: string, highlights: Highlight[], chapterTitle?: (chapterId: string) => string): string;
+
+declare const CONTEXT_LENGTH = 32;
+interface TextSpan {
+    start: number;
+    end: number;
+}
+declare function quoteFor(text: string, start: number, end: number): {
+    exact: string;
+    prefix: string;
+    suffix: string;
+};
+type ResolveStrategy = "position" | "block" | "quote" | "fuzzy";
+/**
+ * Re-anchor a stored anchor in (possibly edited) chapter text.
+ * `blockOffset` is the current text offset of the anchor's block, if it still exists.
+ */
+declare function resolveInText(text: string, anchor: Anchor, blockOffset?: number): (TextSpan & {
+    strategy: ResolveStrategy;
+}) | null;
+/**
+ * Sentence containing `offset` within `blockText`. Offsets are block-relative.
+ */
+declare function sentenceAt(blockText: string, offset: number, locale?: string): TextSpan;
+/** Expand a block-relative span so it covers whole sentences. */
+declare function expandToSentences(blockText: string, start: number, end: number, locale?: string): TextSpan;
+/** Expand a span so it doesn't cut words in half, and trim surrounding whitespace. */
+declare function snapToWords(text: string, start: number, end: number): TextSpan;
+
+/**
+ * DOM side of anchoring: map between Ranges and chapter text offsets,
+ * resolve stored anchors, paint highlights (CSS Custom Highlight API) and
+ * hit-test taps. Never mutates the content DOM, so it is
+ * safe with React-rendered (MDX) and server-rendered (HTML) chapters alike.
+ */
+
+declare const BLOCK_ATTR = "data-block-id";
+declare const IGNORE_ATTR = "data-zr-ignore";
+interface Entry {
+    node: Text;
+    start: number;
+    end: number;
+}
+interface TextIndex {
+    root: Element;
+    text: string;
+    entries: Entry[];
+}
+/**
+ * Give blocks and headings the ids the build-time plugin would have given them
+ * (`zreader/rehype`), for content rendered without it: MDX compiled
+ * by your bundler, JSX, third-party HTML. Same traversal order, same hash, so ids
+ * match either way. No-op when the content already carries block ids.
+ * Only adds attributes; never changes text or structure.
+ */
+declare function ensureBlockIds(root: Element): {
+    assigned: number;
+};
+/** Table of contents from the headings in `root` (those with an `id`). */
+declare function collectToc(root: Element, depth?: [min: number, max: number]): TocEntry[];
+declare function buildTextIndex(root: Element): TextIndex;
+/** Text offset of a DOM boundary point. */
+declare function pointToOffset(index: TextIndex, container: Node, offset: number): number;
+declare function offsetToPoint(index: TextIndex, offset: number, preferNext?: boolean): {
+    node: Text;
+    offset: number;
+} | null;
+declare function rangeToSpan(index: TextIndex, range: Range): TextSpan | null;
+declare function spanToRange(index: TextIndex, span: TextSpan): Range | null;
+declare function blockElementAt(index: TextIndex, offset: number): Element | null;
+/** Text span covered by a block element. */
+declare function blockSpan(index: TextIndex, el: Element): TextSpan | null;
+declare function findBlock(root: Element, blockId: string): Element | null;
+declare function describeSpan(index: TextIndex, span: TextSpan, contentHash?: string): Anchor | null;
+declare function resolveAnchor(index: TextIndex, anchor: Anchor): TextSpan | null;
+/** Selection → word-snapped span inside root, or null. */
+declare function selectionSpan(index: TextIndex, selection: Selection | null): TextSpan | null;
+/** Sentence (chapter-relative span) at a chapter text offset. */
+declare function sentenceSpanAt(index: TextIndex, offset: number, locale?: string): TextSpan | null;
+/** Expand a chapter-relative span to whole sentences (within the start and end blocks). */
+declare function expandSpanToSentences(index: TextIndex, span: TextSpan, locale?: string): TextSpan;
+/** Chapter text offset under a viewport point (tap / click). */
+declare function offsetFromPoint(index: TextIndex, x: number, y: number): number | null;
+interface ResolvedHighlight {
+    highlight: Highlight;
+    span: TextSpan;
+    range: Range;
+}
+declare function supportsHighlightApi(): boolean;
+/** Registry names used for painting: `::highlight(zr-<color>)` and `::highlight(zr-active)`. */
+declare function highlightName(color: string, namespace?: string): string;
+/**
+ * Paint highlights with the CSS Custom Highlight API. The DOM is never mutated
+ * and no inline styles are written; colours come from `::highlight()` rules in
+ * the stylesheet. Returns a cleanup function (no-op where unsupported).
+ */
+declare function paintHighlights(resolved: ResolvedHighlight[], opts?: {
+    activeId?: string | null;
+    namespace?: string;
+}): () => void;
+declare function highlightAtOffset(resolved: ResolvedHighlight[], offset: number): ResolvedHighlight | null;
+
+declare const DEFAULT_CLIENT_OPTIONS: ReaderClientOptions;
+
+export { Anchor, BACKUP_FORMAT, BACKUP_VERSION, BLOCK_ATTR, BackupFormatError, BookProgress, Bookmark, CONTEXT_LENGTH, DEFAULT_CLIENT_OPTIONS, Highlight, IGNORE_ATTR, LEGACY_BACKUP_FORMATS, MIGRATIONS, Pad, PadScope, ReaderClientOptions, ReaderSettings, StorageQuotaError, TocEntry, blockElementAt, blockSpan, buildTextIndex, collectToc, createLocalStorageAdapter, createMemoryAdapter, createReaderStore, currentVersion, defaultId, describeSpan, ensureBlockIds, expandSpanToSentences, expandToSentences, exportBackup, findBlock, getLocalStorage, highlightAtOffset, highlightName, highlightToMarkdown, highlightsToMarkdown, importBackup, isAnchor, isBookmark, isHighlight, offsetFromPoint, offsetToPoint, padKeySuffix, paintHighlights, parseBackup, pointToOffset, quoteFor, quoteToMarkdown, rangeToSpan, recordTypeForKey, requestPersistentStorage, resolveAnchor, resolveInText, selectionSpan, sentenceAt, sentenceSpanAt, snapToWords, spanToRange, supportsHighlightApi, unwrap, wrap };
+export type { Backup, Cell, Envelope, ImportResult, ReaderStore, ReaderStoreOptions, RecordType, ResolveStrategy, ResolvedHighlight, StorageAdapter, TextIndex, TextSpan };