wolfy-reader 0.1.0

package/dist/reader/index.d.ts

@@ -0,0 +1,231 @@
+/**
+ * The public reader facade: opens a decoded {@link Book} into a container element
+ * and returns a {@link Reader} that turns pages and sections, navigates to any
+ * target, follows internal links with a back-stack, reports position, emits
+ * events, and switches paginated↔scrolled without losing the reader's place.
+ *
+ * This module lives *outside* `src/core` on purpose. Core is headless by rule —
+ * nothing reachable from `src/core/index.ts` may import `src/view` or `src/layout`
+ * (`npm run check:core`). The PLAN §4 sketch shows `book.render(...)`; that method
+ * cannot exist on the core `Book`, so the shape is relocated here as a free
+ * function `render(book, element, options)` keeping the sketched object surface
+ * (`next/prev`, `nextSection/prevSection`, `goTo`, `back`, `position`, `on`,
+ * `setMode`, `destroy`).
+ *
+ * The facade owns no format vocabulary and never fetches or persists: bytes came
+ * in as a `Book`, page geometry comes from the {@link Paginator}, and reading
+ * positions are the headless `Position` model from core. It drives the paginator
+ * and reads the book; it never reaches past the paginator into frame geometry.
+ */
+import type { Book, Position, SentenceRange, TocItem } from '../core/index.ts';
+import { parsePosition } from '../core/index.ts';
+import { type LayoutMode } from '../layout/index.ts';
+import { type SearchHit, type SearchOptions } from '../search/index.ts';
+import { type Appearance, type TextAlign, type ThemeName } from '../view/appearance.ts';
+import { type InputConfig } from './input.ts';
+export type { InputConfig, TapZones } from './input.ts';
+export type { Appearance, TextAlign, ThemeName } from '../view/appearance.ts';
+export type { SearchHit, SearchOptions } from '../search/index.ts';
+/**
+ * Appearance and layout options for {@link render}. All optional. `mode` selects
+ * paginated (default) or scrolled layout. The theme and typography fields drive
+ * the appearance system and are applied at the first render; change any of them
+ * live afterward with {@link Reader.setAppearance}.
+ */
+export interface ReaderOptions {
+    /** 'paginated' (default) or 'scrolled'. */
+    readonly mode?: LayoutMode;
+    /**
+     * The theme applied to content: `'light' | 'dark' | 'sepia' | 'custom'`. Omit
+     * to follow the OS (`prefers-color-scheme`); a named theme overrides it. Change
+     * it live with {@link Reader.setAppearance}.
+     */
+    readonly theme?: ThemeName;
+    /**
+     * Bespoke `--wr-*` CSS custom properties, merged over the resolved theme. The
+     * escape hatch for a custom theme; keys may omit the leading `--`.
+     */
+    readonly customProperties?: Readonly<Record<string, string>>;
+    /** Body font size in CSS px. Applied at the first render; change it live with {@link Reader.setAppearance}. */
+    readonly fontSize?: number;
+    /** Body font family. Applied at the first render. */
+    readonly fontFamily?: string;
+    /** Body line height (unitless multiplier). Applied at the first render. */
+    readonly lineHeight?: number;
+    /** Page-edge margin in CSS px (also the inter-column gutter), threaded to the paginator as `columnGap`. */
+    readonly margin?: number;
+    /** Body text alignment: `'start'` (publisher default) or `'justify'`. */
+    readonly textAlign?: TextAlign;
+    /** Shorthand for `textAlign: 'justify'`. */
+    readonly justify?: boolean;
+    /** Whether the content root hyphenates. */
+    readonly hyphenate?: boolean;
+    /** Text columns per page: 1 (default) or 2. Applied at the first render. */
+    readonly columns?: 1 | 2;
+    /** Where to open. Any {@link GoToTarget}; defaults to the book's start. */
+    readonly start?: GoToTarget;
+    /**
+     * Human-input configuration: keyboard, swipe, tap zones. Additive and optional
+     * — omitting it enables all three with defaults. See {@link InputConfig}. Input
+     * is direction-aware: `Book.direction === 'rtl'` flips the horizontal axis.
+     */
+    readonly input?: InputConfig;
+}
+/**
+ * A navigation target for {@link Reader.goTo}. Six forms:
+ * - {@link TocItem} — its `sectionId` (+ optional `fragment`)
+ * - internal `href` string — resolved to a section (+ fragment), best-effort
+ * - {@link Position} — restored by content anchor
+ * - a number in `0..1` — a fraction through the whole book
+ * - `'start'` — the first section, first page
+ * - `'end'` — the last section, last page
+ */
+export type GoToTarget = TocItem | Position | string | number | 'start' | 'end';
+/** The reader's place in the book, assembled from the paginator and the book. */
+export interface ReaderPosition {
+    /** 0-based index of the active section in reading order. */
+    readonly section: number;
+    /** Fraction through the whole book, 0..1 — approximate across unlaid sections. */
+    readonly progress: number;
+    /** Fraction through the current chapter, 0..1. */
+    readonly chapterProgress: number;
+    /** 0-based current page within the section. */
+    readonly page: number;
+    /** Total pages in the section — an estimate until the layout is firm. */
+    readonly totalPages: number;
+}
+/** The events a {@link Reader} emits, with their payload types. */
+export interface ReaderEventMap {
+    /** Fires once, after the first section paints. Payload: the initial position. */
+    readonly ready: ReaderPosition;
+    /** Fires after any navigation settles. Payload: the settled position. */
+    readonly positionchange: ReaderPosition;
+    /** Fires when the active section changes. Payload: the new section index + id. */
+    readonly sectionchange: SectionChange;
+    /** Fires when an in-frame link is clicked, before it is followed. Payload: the raw href. */
+    readonly linkclick: LinkClick;
+    /** Fires when the user selects text in the frame. Payload: the text + a resolvable Position. */
+    readonly selection: SelectionEvent;
+    /** Fires when a navigation or render fails. Payload: the error. */
+    readonly error: Error;
+}
+export interface SectionChange {
+    /** 0-based index of the now-active section. */
+    readonly index: number;
+    /** The now-active section's id. */
+    readonly sectionId: string;
+}
+export interface LinkClick {
+    /** The raw authored href from the frame, exactly as reported. */
+    readonly href: string;
+}
+export interface SelectionEvent {
+    /** The selected text, exactly as the frame read it. */
+    readonly text: string;
+    /**
+     * A `Position` anchored at the selection's start. Resolves back against the
+     * section via {@link Reader.goTo}/`resolvePosition`, so a host can persist it
+     * (a bookmark or highlight anchor) and navigate to it later.
+     */
+    readonly position: Position;
+}
+export type ReaderEvent = keyof ReaderEventMap;
+export type ReaderEventHandler<E extends ReaderEvent> = (payload: ReaderEventMap[E]) => void;
+/** Removes a previously-registered handler. Idempotent. */
+export type Unsubscribe = () => void;
+/**
+ * A live reader over one book. Navigation methods are async and settle once the
+ * paginator has moved and the corresponding events have fired. Reads of
+ * {@link position} are synchronous snapshots of the last settled state.
+ */
+export interface Reader {
+    /** Turn one page forward, rolling to the next section's first page at the end. */
+    next(): Promise<void>;
+    /** Turn one page back, rolling to the previous section's last page at the start. */
+    prev(): Promise<void>;
+    /** Jump to the next section's first page. No-op at the last section. */
+    nextSection(): Promise<void>;
+    /** Jump to the previous section's first page. No-op at the first section. */
+    prevSection(): Promise<void>;
+    /** Navigate to any of the six {@link GoToTarget} forms. Soft-misses degrade quietly. */
+    goTo(target: GoToTarget): Promise<void>;
+    /** Pop the internal-link back-stack and restore the pushed position. No-op when empty. */
+    back(): Promise<void>;
+    /** Switch paginated↔scrolled without reload, preserving the reading position. */
+    setMode(mode: LayoutMode): Promise<void>;
+    /**
+     * Update the live appearance without losing the reading place. Covers the theme
+     * half (colours / background) and the typography half (font family/size, line
+     * height, margin, text alignment, justification, hyphenation, 1-or-2 columns).
+     * Partial: only the fields present in `appearance` change; `customProperties`
+     * shallow-merges over the current set. A colour-only change repaints the current
+     * page in place with no reflow; a reflowing typography knob (font, size, line
+     * height, columns) re-lays out and restores the reading place by content anchor,
+     * so the place survives even though the page number may shift.
+     */
+    setAppearance(appearance: Appearance): Promise<void>;
+    /**
+     * Full-text search over the whole book. Returns a **lazy async iterator** of
+     * {@link SearchHit}s, streaming each as its section is scanned — the book is never
+     * buffered whole, and stopping early (`break`) halts the scan (no later section is
+     * loaded). Each hit's `position` is jumpable: `await reader.goTo(hit.position)`
+     * lands on its page. Matching is normalized literal substring (case-insensitive,
+     * NFC, smart-punctuation- and whitespace-folded); it does not route through the
+     * frame — sections are decoded and scanned headlessly, independent of what is
+     * painted.
+     */
+    search(query: string, options?: SearchOptions): AsyncIterableIterator<SearchHit>;
+    /**
+     * Draws a decoration — a styled overlay — over the range `position` resolves to,
+     * keyed by `id`. Re-issuing the same `id` replaces that overlay; the `className`
+     * on `opts` is applied to every overlay box so a host stylesheet can colour it.
+     *
+     * **Draw-only, never stored.** The reader holds the decoration *intent* (id →
+     * position + class) in memory only, so it can re-anchor the overlay across a
+     * re-layout (font-size, mode, appearance) — it never persists, serializes, or
+     * fetches annotation data. A host owns all annotation storage: to make a highlight
+     * durable, persist the `position` (or its serialized string) yourself and re-call
+     * `decorate` on the next open. The overlay is pointer-transparent and layout-
+     * neutral: it never eats a selection or a click and never changes page geometry.
+     *
+     * A soft-miss — the anchor no longer resolves, or it belongs to a section other
+     * than the one on screen — draws nothing and throws nothing; the intent is kept, so
+     * navigating to that section (or re-laying out) redraws it.
+     */
+    decorate(id: string, position: Position, opts: {
+        className: string;
+    }): Promise<void>;
+    /** Removes the decoration drawn for `id` and drops its intent. No-op for an unknown id. */
+    undecorate(id: string): Promise<void>;
+    /**
+     * Sentence ranges for the current section, each with a `Position` anchored over
+     * the whole sentence. The **TTS enabler**: pair a sentence's `position` with
+     * {@link goTo} to jump and {@link decorate} to highlight it, and a host can step
+     * a speech engine sentence-by-sentence over the reading view. The library speaks
+     * nothing and stores nothing — it exposes ranges only. Returns `[]` before the
+     * first paint or for an empty section.
+     */
+    sentences(): Promise<readonly SentenceRange[]>;
+    /** A synchronous snapshot of the current place in the book. */
+    readonly position: ReaderPosition;
+    /** The layout mode currently in effect. */
+    readonly mode: LayoutMode;
+    /** Subscribe to an event; returns an unsubscribe function. */
+    on<E extends ReaderEvent>(event: E, handler: ReaderEventHandler<E>): Unsubscribe;
+    /** Tear everything down: paginator, frame, data: URLs, listeners, back-stack. Idempotent. */
+    destroy(): void;
+}
+/** Something went wrong driving the reader; never a book decoding failure. */
+export declare class ReaderError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Renders `book` into `element` and returns a live {@link Reader}. The reader is
+ * usable immediately; the first section paints asynchronously and a `ready` event
+ * fires once it does. Options are applied where they map today and otherwise
+ * retained for M3. Pass `options.start` to open somewhere other than the book's
+ * beginning.
+ */
+export declare function render(book: Book, element: HTMLElement, options?: ReaderOptions): Reader;
+export { parsePosition };
+//# sourceMappingURL=index.d.ts.map

package/dist/reader/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/reader/index.ts"],"names":[],"mappings":"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"}