wolfy-reader 0.1.0

package/dist/reader/index.js

@@ -0,0 +1,958 @@
+import { parsePosition, segmentSentences } from '../core/index.js';
+import { Paginator } from '../layout/index.js';
+import { searchBook } from '../search/index.js';
+import { isReflowingUpdate, mergeAppearance, themeStyleSheet, } from '../view/appearance.js';
+import { keyIntent, swipeIntent, tapIntent, } from './input.js';
+/** Something went wrong driving the reader; never a book decoding failure. */
+export class ReaderError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'ReaderError';
+    }
+}
+/**
+ * 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 function render(book, element, options = {}) {
+    return new ReaderImpl(book, element, options);
+}
+/** Split a raw href into its path (fragment removed) and optional fragment. */
+function splitFragment(href) {
+    const hash = href.indexOf('#');
+    if (hash === -1)
+        return { path: href };
+    return { path: href.slice(0, hash), fragment: decodeFragment(href.slice(hash + 1)) };
+}
+function decodeFragment(fragment) {
+    if (!fragment.includes('%'))
+        return fragment;
+    try {
+        return decodeURIComponent(fragment);
+    }
+    catch {
+        return fragment;
+    }
+}
+/** The last path segment of a reference, e.g. '../text/c3.xhtml' → 'c3.xhtml'. */
+function lastSegment(path) {
+    const clean = path.replace(/[?].*$/, '');
+    const slash = clean.lastIndexOf('/');
+    return slash === -1 ? clean : clean.slice(slash + 1);
+}
+/** Strip a single trailing file extension: 'c3.xhtml' → 'c3'. */
+function stripExtension(name) {
+    const dot = name.lastIndexOf('.');
+    return dot <= 0 ? name : name.slice(0, dot);
+}
+class ReaderImpl {
+    #book;
+    #paginator;
+    #element;
+    #sections;
+    #options;
+    #listeners = {
+        ready: new Set(),
+        positionchange: new Set(),
+        sectionchange: new Set(),
+        linkclick: new Set(),
+        selection: new Set(),
+        error: new Set(),
+    };
+    /** Internal-link back-stack: positions to return to via {@link back}. */
+    #backStack = [];
+    #sectionIndex = 0;
+    #mode;
+    #destroyed = false;
+    #ready = false;
+    /** Live appearance state (theme half). Merged by {@link setAppearance}. */
+    #appearance;
+    /** Reading direction; drives the RTL flip in every input mode. */
+    #direction;
+    /** Resolved input config: which modes are on and the tap-zone geometry. */
+    #keyboard;
+    #swipe;
+    #tapZones;
+    /** Serializes navigation so overlapping calls settle in order. */
+    #queue = Promise.resolve();
+    /** The host-side image-zoom overlay, mounted lazily on the first image tap. */
+    #zoom = null;
+    /**
+     * Observes the container so a resize re-paginates: page geometry is captured at
+     * render time, so a container that later shrinks leaves the frame scrolling and
+     * one that grows leaves a gap. Null where `ResizeObserver` is absent.
+     */
+    #resizeObserver = null;
+    /** Pending rAF handle coalescing a burst of resize notifications into one re-flow. */
+    #resizeFrame = null;
+    constructor(book, element, options) {
+        this.#book = book;
+        this.#element = element;
+        this.#sections = book.sections;
+        this.#options = options;
+        this.#mode = options.mode ?? 'paginated';
+        this.#direction = book.direction ?? 'ltr';
+        const input = options.input ?? {};
+        this.#keyboard = input.keyboard ?? true;
+        this.#swipe = input.swipe ?? true;
+        this.#tapZones = input.tapZones === false ? null : (input.tapZones ?? {});
+        // Seed the live appearance from the options. Only keys that were supplied are
+        // carried — `exactOptionalPropertyTypes` keeps "follow the OS" (theme absent)
+        // distinct from a forced theme, and an unset typography knob from a forced one.
+        // The typography half is applied at the first render (below), not merely
+        // retained: the seeded stylesheet rides the opening srcdoc and `columns` drives
+        // the opening paginate.
+        this.#appearance = {};
+        if (options.theme !== undefined)
+            this.#appearance = { ...this.#appearance, theme: options.theme };
+        if (options.customProperties !== undefined) {
+            this.#appearance = { ...this.#appearance, customProperties: options.customProperties };
+        }
+        if (options.fontFamily !== undefined)
+            this.#appearance = { ...this.#appearance, fontFamily: options.fontFamily };
+        if (options.fontSize !== undefined)
+            this.#appearance = { ...this.#appearance, fontSize: options.fontSize };
+        if (options.lineHeight !== undefined)
+            this.#appearance = { ...this.#appearance, lineHeight: options.lineHeight };
+        if (options.margin !== undefined)
+            this.#appearance = { ...this.#appearance, margin: options.margin };
+        if (options.textAlign !== undefined)
+            this.#appearance = { ...this.#appearance, textAlign: options.textAlign };
+        if (options.justify !== undefined)
+            this.#appearance = { ...this.#appearance, justify: options.justify };
+        if (options.hyphenate !== undefined)
+            this.#appearance = { ...this.#appearance, hyphenate: options.hyphenate };
+        if (options.columns !== undefined)
+            this.#appearance = { ...this.#appearance, columns: options.columns };
+        this.#paginator = new Paginator(element, {
+            themeCss: themeStyleSheet(this.#appearance),
+            // Baked into the frame's coordination script: with keyboard input off the
+            // frame stops preventDefault'ing nav keys it would forward to a deaf host.
+            keyboardNav: this.#keyboard,
+            onLinkClick: (href) => {
+                void this.#onLinkClick(href);
+            },
+            onError: (message) => {
+                this.#emit('error', new ReaderError(message));
+            },
+            onKey: (key) => {
+                if (this.#keyboard)
+                    this.#dispatchIntent(keyIntent(key, this.#direction));
+            },
+            onSwipe: (dx, dy) => {
+                if (this.#swipe)
+                    this.#dispatchIntent(swipeIntent(dx, dy, this.#direction));
+            },
+            onTap: (tap) => {
+                if (this.#tapZones !== null) {
+                    this.#dispatchIntent(tapIntent(tap, this.#tapZones, this.#direction));
+                }
+            },
+            onImageTap: (image) => {
+                this.#openZoom(image);
+            },
+            onSelection: (selection) => {
+                void this.#onSelection(selection);
+            },
+        });
+        // Kick off the initial render; `ready` fires when it settles.
+        void this.#run(() => this.#open());
+        this.#observeResize();
+    }
+    /**
+     * Watches the container for size changes and re-paginates on each, so the frame
+     * never scrolls (shrunk container) or shows a gap (grown one). Notifications are
+     * coalesced onto the next animation frame, then the re-flow is enqueued behind any
+     * in-flight navigation so it settles in order and holds the reading place. The
+     * `ResizeObserver` fires once on `observe()` at the current size — a no-op, since
+     * `Paginator.resize()` short-circuits when the size has not actually changed.
+     */
+    #observeResize() {
+        if (typeof ResizeObserver === 'undefined')
+            return;
+        this.#resizeObserver = new ResizeObserver(() => this.#onResize());
+        this.#resizeObserver.observe(this.#element);
+    }
+    #onResize() {
+        if (this.#destroyed || this.#resizeFrame !== null)
+            return;
+        this.#resizeFrame = requestAnimationFrame(() => {
+            this.#resizeFrame = null;
+            if (this.#destroyed || this.#paginator.section === null)
+                return;
+            void this.#run(() => this.#reflowToContainer());
+        });
+    }
+    async #reflowToContainer() {
+        if (this.#destroyed || this.#paginator.section === null)
+            return;
+        const state = await this.#paginator.resize();
+        // `null` means the size did not actually change (or the container is hidden):
+        // nothing re-laid out, so nothing to announce.
+        if (this.#destroyed || state === null)
+            return;
+        this.#emit('positionchange', this.#snapshot());
+    }
+    get position() {
+        return this.#snapshot();
+    }
+    get mode() {
+        return this.#mode;
+    }
+    on(event, handler) {
+        const set = this.#listeners[event];
+        set.add(handler);
+        return () => {
+            set.delete(handler);
+        };
+    }
+    next() {
+        return this.#run(() => this.#next());
+    }
+    prev() {
+        return this.#run(() => this.#prev());
+    }
+    nextSection() {
+        return this.#run(() => this.#gotoSection(this.#sectionIndex + 1, 'first'));
+    }
+    prevSection() {
+        return this.#run(() => this.#gotoSection(this.#sectionIndex - 1, 'first'));
+    }
+    goTo(target) {
+        return this.#run(() => this.#goTo(target));
+    }
+    back() {
+        return this.#run(() => this.#back());
+    }
+    setMode(mode) {
+        return this.#run(() => this.#setMode(mode));
+    }
+    setAppearance(appearance) {
+        return this.#run(() => this.#setAppearance(appearance));
+    }
+    /**
+     * Streams whole-book search hits. Not enqueued behind navigation — it reads the
+     * book's section bytes headlessly (decode → strip markup → match) and never drives
+     * the paginator or the frame, so it composes with reading rather than blocking it.
+     * Delegates to the headless `searchBook` generator; `goTo(hit.position)` jumps.
+     */
+    search(query, options = {}) {
+        return searchBook(this.#book, query, options);
+    }
+    /**
+     * Draws (or replaces) a decoration over the range `position` resolves to. Enqueued
+     * behind navigation so it settles in issue order against a concurrent re-layout;
+     * the paginator holds the intent and re-anchors it across every later re-layout, so
+     * a highlight survives a font-size or mode change. Draw-only — no annotation data is
+     * ever stored, serialized, or fetched. A soft-miss draws nothing (no throw).
+     */
+    decorate(id, position, opts) {
+        return this.#run(() => this.#decorate(id, position, opts.className));
+    }
+    /** Removes the decoration for `id`. Enqueued so it orders against navigation. */
+    undecorate(id) {
+        return this.#run(() => this.#undecorate(id));
+    }
+    sentences() {
+        return this.#runResult([], async () => {
+            const section = this.#paginator.section;
+            if (section === null)
+                return [];
+            // Segment the same frame-measured section text decorations resolve against, so
+            // every sentence Position both jumps (goTo) and highlights (decorate) cleanly.
+            const text = await this.#paginator.sectionText();
+            return segmentSentences(text, section.id);
+        });
+    }
+    async #decorate(id, position, className) {
+        if (this.#destroyed || this.#paginator.section === null)
+            return;
+        await this.#paginator.decorate(id, position, className);
+    }
+    async #undecorate(id) {
+        if (this.#destroyed)
+            return;
+        await this.#paginator.undecorate(id);
+    }
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.#destroyed = true;
+        this.#resizeObserver?.disconnect();
+        this.#resizeObserver = null;
+        if (this.#resizeFrame !== null) {
+            cancelAnimationFrame(this.#resizeFrame);
+            this.#resizeFrame = null;
+        }
+        this.#zoom?.destroy();
+        this.#zoom = null;
+        this.#paginator.destroy();
+        for (const event of Object.keys(this.#listeners)) {
+            this.#listeners[event].clear();
+        }
+        this.#backStack = [];
+    }
+    // --- Input dispatch -------------------------------------------------------
+    /**
+     * Route a resolved {@link NavIntent} (from keyboard/swipe/tap, already made
+     * direction-aware in `input.ts`) to the matching public navigation method. Each
+     * goes through the same serialized queue as programmatic navigation, so hand
+     * input interleaves in issue order. `none` is a no-op. Input is never gated on
+     * `prefers-reduced-motion`: pages must always turn. The only motion in the reader
+     * is the zoom overlay's open/close transition, which the overlay gates itself.
+     */
+    #dispatchIntent(intent) {
+        switch (intent) {
+            case 'next':
+                void this.next();
+                return;
+            case 'prev':
+                void this.prev();
+                return;
+            case 'nextSection':
+                void this.nextSection();
+                return;
+            case 'prevSection':
+                void this.prevSection();
+                return;
+            case 'start':
+                void this.goTo('start');
+                return;
+            case 'end':
+                void this.goTo('end');
+                return;
+            case 'none':
+                return;
+        }
+    }
+    // --- Image zoom overlay ---------------------------------------------------
+    /**
+     * Opens the host-side zoom overlay over the tapped image's already-served
+     * `data:` bytes. The overlay is a DOM element in the *host* document, outside the
+     * sandboxed frame — it mints no new frame resource and never a `blob:` URL. A
+     * non-`data:` src (a remote image the CSP already refuses in-frame) is ignored.
+     */
+    #openZoom(image) {
+        if (this.#destroyed || !image.src.startsWith('data:'))
+            return;
+        if (this.#zoom === null)
+            this.#zoom = new ImageZoom(this.#element);
+        this.#zoom.open(image.src, image.alt);
+    }
+    // --- Navigation queue -----------------------------------------------------
+    /**
+     * Runs `task` after all previously-queued navigation, so overlapping calls
+     * settle in the order they were issued. A task failure is reported through the
+     * `error` event and swallowed so it never breaks the chain; `destroy` short-
+     * circuits everything.
+     */
+    #run(task) {
+        const next = this.#queue.then(async () => {
+            if (this.#destroyed)
+                return;
+            try {
+                await task();
+            }
+            catch (error) {
+                if (!this.#destroyed) {
+                    this.#emit('error', error instanceof Error ? error : new ReaderError(String(error)));
+                }
+            }
+        });
+        this.#queue = next;
+        return next;
+    }
+    /**
+     * Like {@link #run} but returns the task's value, resolving to `fallback` when the
+     * reader is destroyed or the task throws (the error is reported through `error`).
+     * For read-only queries that must settle in order with navigation.
+     */
+    #runResult(fallback, task) {
+        const run = this.#queue.then(async () => {
+            if (this.#destroyed)
+                return fallback;
+            try {
+                return await task();
+            }
+            catch (error) {
+                if (!this.#destroyed) {
+                    this.#emit('error', error instanceof Error ? error : new ReaderError(String(error)));
+                }
+                return fallback;
+            }
+        });
+        this.#queue = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    // --- Lifecycle ------------------------------------------------------------
+    async #open() {
+        const start = this.#options.start;
+        if (start === undefined) {
+            await this.#gotoSection(0, 'first');
+        }
+        else {
+            await this.#goTo(start);
+        }
+        if (this.#destroyed)
+            return;
+        this.#ready = true;
+        this.#emit('ready', this.#snapshot());
+    }
+    // --- Section / page paint -------------------------------------------------
+    /**
+     * Paginates the section at `index` and lands on its first or last page. Fires
+     * `sectionchange` when the active section actually changes, then always fires
+     * `positionchange` once the page settles. Out-of-range indices are no-ops.
+     */
+    async #gotoSection(index, land) {
+        if (index < 0 || index >= this.#sections.length)
+            return;
+        const section = this.#sections[index];
+        const changed = this.#paginator.section === null || this.#sectionIndex !== index;
+        // Re-paginating is the expensive step (sanitize + chunk + measure). Skip it
+        // when we are already on this section — back(), a same-section fragment jump,
+        // or a Position within the current chapter — and just seek within the layout
+        // already in place.
+        if (changed) {
+            await this.#paginator.paginate(section, { mode: this.#mode, ...this.#requestExtras() });
+            this.#sectionIndex = index;
+        }
+        // Always establish the landing page explicitly. A multi-chunk section paints
+        // its chunks stacked until a page is selected, so entering on 'first' must
+        // seek page 0, not assume paginate left it there.
+        if (land === 'last') {
+            await this.#paginator.refine();
+            const state = this.#paginator.state;
+            await this.#paginator.goToPage(state === null ? 0 : Math.max(0, state.pageCount - 1));
+        }
+        else {
+            await this.#paginator.goToPage(0);
+        }
+        if (changed)
+            this.#emit('sectionchange', { index, sectionId: section.id });
+        this.#emit('positionchange', this.#snapshot());
+    }
+    /**
+     * The layout knobs the facade threads into every `paginate`: the page margin
+     * (`columnGap`) and the column count. Both are appearance-owned, so a section
+     * re-paginated after a mode switch or roll keeps the live typography rather than
+     * snapping back to the paginator defaults.
+     */
+    #requestExtras() {
+        const extras = {};
+        if (this.#appearance.margin !== undefined)
+            extras.columnGap = this.#appearance.margin;
+        if (this.#appearance.columns !== undefined)
+            extras.columnCount = this.#appearance.columns;
+        return extras;
+    }
+    // --- next / prev ----------------------------------------------------------
+    async #next() {
+        if (this.#paginator.section === null)
+            return;
+        const before = this.#paginator.page;
+        const after = await this.#paginator.nextPage();
+        if (after !== before) {
+            this.#emit('positionchange', this.#snapshot());
+            return;
+        }
+        // At the section's last page: roll to the next section's first page.
+        await this.#gotoSection(this.#sectionIndex + 1, 'first');
+    }
+    async #prev() {
+        if (this.#paginator.section === null)
+            return;
+        const before = this.#paginator.page;
+        const after = await this.#paginator.previousPage();
+        if (after !== before) {
+            this.#emit('positionchange', this.#snapshot());
+            return;
+        }
+        // At the section's first page: roll to the previous section's last page.
+        await this.#gotoSection(this.#sectionIndex - 1, 'last');
+    }
+    // --- goTo -----------------------------------------------------------------
+    async #goTo(target) {
+        if (target === 'start') {
+            await this.#gotoSection(0, 'first');
+            return;
+        }
+        if (target === 'end') {
+            await this.#gotoSection(this.#sections.length - 1, 'last');
+            return;
+        }
+        if (typeof target === 'number') {
+            await this.#gotoFraction(target);
+            return;
+        }
+        if (typeof target === 'string') {
+            await this.#gotoHref(target);
+            return;
+        }
+        if (isPosition(target)) {
+            await this.#gotoPosition(target);
+            return;
+        }
+        // TocItem.
+        await this.#gotoTocItem(target);
+    }
+    async #gotoFraction(fraction) {
+        const count = this.#sections.length;
+        if (count === 0)
+            return;
+        const clamped = Math.min(1, Math.max(0, fraction));
+        // Even-weight the book across sections (matching BookProgress.bookFraction),
+        // then land on the page nearest the residual fraction within that section.
+        const scaled = clamped * count;
+        const index = Math.min(count - 1, Math.floor(scaled));
+        const within = scaled - index;
+        await this.#gotoSection(index, 'first');
+        if (this.#destroyed)
+            return;
+        await this.#paginator.refine();
+        const state = this.#paginator.state;
+        if (state !== null && state.pageCount > 1) {
+            const page = Math.round(within * (state.pageCount - 1));
+            await this.#paginator.goToPage(page);
+        }
+        this.#emit('positionchange', this.#snapshot());
+    }
+    async #gotoPosition(position) {
+        const index = this.#indexOfSection(position.sectionId);
+        if (index === -1)
+            return; // soft miss: unknown section
+        await this.#gotoSection(index, 'first');
+        if (this.#destroyed)
+            return;
+        const page = await this.#paginator.pageOfPosition(position);
+        if (page >= 0)
+            await this.#paginator.goToPage(page);
+        this.#emit('positionchange', this.#snapshot());
+    }
+    async #gotoTocItem(item) {
+        const index = this.#indexOfSection(item.sectionId);
+        if (index === -1)
+            return; // soft miss
+        await this.#gotoSection(index, 'first');
+        if (this.#destroyed)
+            return;
+        if (item.fragment !== undefined)
+            await this.#seekFragment(item.fragment);
+        this.#emit('positionchange', this.#snapshot());
+    }
+    /**
+     * Resolves a content-internal href to a section (+ fragment) using ONLY public
+     * Book data, then navigates. The core exposes no href→section seam (sections are
+     * id-addressed; `Section.resolve` yields a `Resource`, not a section target), so
+     * this is a best-effort, format-neutral heuristic that degrades quietly on a
+     * miss — consistent with the Position soft-miss philosophy. In order:
+     *   1. the path (or its last segment) equals a `section.id`;
+     *   2. the last segment, or that segment minus its extension, matches a
+     *      `section.id` or a section id's own last segment / extension-less form;
+     *   3. the href carries a fragment that a `TocItem` also carries — borrow that
+     *      item's `sectionId`.
+     * A pure-fragment href (`#note`) seeks within the current section.
+     *
+     * Returns whether the href resolved and navigation happened — `false` on a
+     * soft miss — so the link-click path can decide whether a back-stack entry is
+     * warranted. `goTo` ignores the value.
+     */
+    async #gotoHref(href) {
+        const { path, fragment } = splitFragment(href);
+        if (path === '') {
+            // Pure fragment: within the current section.
+            if (fragment !== undefined)
+                await this.#seekFragment(fragment);
+            this.#emit('positionchange', this.#snapshot());
+            return fragment !== undefined;
+        }
+        // Prefer the format's own section-relative resolver: it maps the raw href to a
+        // section by the same authority the TOC uses (EPUB's resolved-path → id table),
+        // which the id/filename heuristic below cannot match against opaque manifest ids.
+        // Fall back to the heuristic for formats that expose no resolver.
+        const viaFormat = this.#paginator.section?.resolveHref?.(href);
+        let index = viaFormat === undefined ? -1 : this.#indexOfSection(viaFormat.sectionId);
+        const targetFragment = (viaFormat?.fragment ?? fragment);
+        if (index === -1)
+            index = this.#resolveHrefToSection(path, fragment);
+        if (index === -1)
+            return false; // soft miss
+        await this.#gotoSection(index, 'first');
+        if (this.#destroyed)
+            return false;
+        if (targetFragment !== undefined)
+            await this.#seekFragment(targetFragment);
+        this.#emit('positionchange', this.#snapshot());
+        return true;
+    }
+    /** Heuristic href-path → section index; -1 when nothing matches (soft miss). */
+    #resolveHrefToSection(path, fragment) {
+        // 1. Direct id match on the full path or its last segment.
+        const segment = lastSegment(path);
+        for (const candidate of [path, segment]) {
+            const direct = this.#indexOfSection(candidate);
+            if (direct !== -1)
+                return direct;
+        }
+        // 2. Filename / extension-less match against section ids and their tails.
+        const stem = stripExtension(segment);
+        for (let index = 0; index < this.#sections.length; index += 1) {
+            const id = this.#sections[index].id;
+            const idSegment = lastSegment(id);
+            if (id === segment ||
+                id === stem ||
+                idSegment === segment ||
+                idSegment === stem ||
+                stripExtension(idSegment) === stem) {
+                return index;
+            }
+        }
+        // 3. TOC fragment fallback: a toc item carrying this fragment names a section.
+        if (fragment !== undefined) {
+            const byFragment = this.#findTocByFragment(this.#book.toc, fragment);
+            if (byFragment !== undefined)
+                return this.#indexOfSection(byFragment);
+        }
+        return -1;
+    }
+    #findTocByFragment(items, fragment) {
+        for (const item of items) {
+            if (item.fragment === fragment)
+                return item.sectionId;
+            const nested = this.#findTocByFragment(item.children, fragment);
+            if (nested !== undefined)
+                return nested;
+        }
+        return undefined;
+    }
+    /**
+     * Best-effort seek to a fragment within the already-paginated section. The frame
+     * maps an element id to its character offset (`offsetOfElementId`), which the
+     * paginator turns into a page via `pageOfElementId`. A resolved id lands on that
+     * page; an unresolvable id (no such element) is a soft miss that lands on the
+     * section's first page — never a throw. Kept as a seam so callers need not
+     * special-case fragment presence.
+     */
+    async #seekFragment(fragment) {
+        const page = await this.#paginator.pageOfElementId(fragment);
+        // Soft miss (-1): the id is absent, so stay at the section's first page.
+        await this.#paginator.goToPage(page >= 0 ? page : 0);
+    }
+    // --- selection ------------------------------------------------------------
+    /**
+     * Turns a frame-forwarded selection (UTF-16 offset range + text over the section
+     * text) into a `Position` anchored at the range start and emits `selection`. The
+     * frame already dropped collapsed and empty-rect selections, so a callback here
+     * always carries real text. Position capture reads the section text but moves
+     * nothing, so it is not enqueued behind navigation.
+     */
+    async #onSelection(selection) {
+        if (this.#destroyed || this.#paginator.section === null)
+            return;
+        const position = await this.#paginator.positionOfOffsetRange(selection.start, selection.end);
+        if (this.#destroyed)
+            return;
+        this.#emit('selection', { text: selection.text, position });
+    }
+    // --- back-stack -----------------------------------------------------------
+    async #onLinkClick(href) {
+        if (this.#destroyed)
+            return;
+        this.#emit('linkclick', { href });
+        // Capture the pre-jump position, follow the link, and push only if the href
+        // actually resolved and navigated. An external (https:) or otherwise
+        // unresolvable href is a soft miss that moves nothing — pushing it would
+        // make the next back() a no-op "return" to where the user already is
+        // instead of the genuinely prior position. Queued so it settles in order
+        // with any concurrent navigation.
+        await this.#run(async () => {
+            const here = await this.#currentPosition();
+            const navigated = await this.#gotoHref(href);
+            if (navigated && here !== null)
+                this.#backStack.push(here);
+        });
+    }
+    async #back() {
+        const position = this.#backStack.pop();
+        if (position === undefined)
+            return;
+        await this.#gotoPosition(position);
+    }
+    // --- mode switch ----------------------------------------------------------
+    async #setMode(mode) {
+        if (mode === this.#mode)
+            return;
+        if (this.#paginator.section === null) {
+            this.#mode = mode;
+            return;
+        }
+        // The paginator itself captures a Position, re-paginates, and seeks back,
+        // so position is preserved across the switch (M1-2 machinery).
+        await this.#paginator.switchMode(mode);
+        this.#mode = mode;
+        this.#emit('positionchange', this.#snapshot());
+    }
+    // --- appearance -----------------------------------------------------------
+    /**
+     * Merges `appearance` over the live state, rebuilds the appearance stylesheet,
+     * and applies it to the current section preserving the reading place. Two paths,
+     * chosen by whether the *update* touches a reflowing typography knob:
+     *
+     * - **Non-reflowing** (theme colours / background only): `setThemeCss` re-assembles
+     *   the srcdoc, captures a `Position`, and seeks back. Geometry is invariant, so
+     *   the exact page is restored and the text does not reflow.
+     * - **Reflowing** (font family/size, line height, alignment, hyphenation, columns):
+     *   `applyAppearance` reuses the same capture → re-layout → resolve → restore
+     *   machinery as `setMode`, but geometry changes, so the anchor's *nearest* page is
+     *   restored (the reading place survives the reflow, page number may shift).
+     *
+     * A no-op change short-circuits inside the paginator. Before the first paint it
+     * records the appearance for the opening render.
+     */
+    async #setAppearance(appearance) {
+        const reflows = isReflowingUpdate(appearance);
+        this.#appearance = mergeAppearance(this.#appearance, appearance);
+        const css = themeStyleSheet(this.#appearance);
+        if (reflows) {
+            const geometry = {};
+            if (this.#appearance.columns !== undefined)
+                geometry.columnCount = this.#appearance.columns;
+            if (this.#appearance.margin !== undefined)
+                geometry.columnGap = this.#appearance.margin;
+            await this.#paginator.applyAppearance(css, geometry);
+        }
+        else {
+            await this.#paginator.setThemeCss(css);
+        }
+        if (this.#destroyed)
+            return;
+        // Emitted after the change settles so a host can refresh anything keyed on the
+        // settled state (parity with setMode). A reflowing knob may have moved the page
+        // number even though the reading place is held.
+        this.#emit('positionchange', this.#snapshot());
+    }
+    // --- helpers --------------------------------------------------------------
+    #indexOfSection(sectionId) {
+        return this.#sections.findIndex((section) => section.id === sectionId);
+    }
+    /** The current reading position as a `Position`, or null before the first paint. */
+    async #currentPosition() {
+        if (this.#paginator.section === null)
+            return null;
+        return this.#paginator.positionOfPage(this.#paginator.page);
+    }
+    #snapshot() {
+        if (this.#paginator.section === null || this.#paginator.state === null) {
+            return { section: this.#sectionIndex, progress: 0, chapterProgress: 0, page: 0, totalPages: 0 };
+        }
+        const progress = this.#paginator.bookProgress(this.#sectionIndex, this.#sections.length);
+        return {
+            section: this.#sectionIndex,
+            progress: progress.bookFraction,
+            chapterProgress: progress.fraction,
+            page: progress.page,
+            totalPages: progress.totalPages,
+        };
+    }
+    #emit(event, payload) {
+        // Copy so a handler unsubscribing mid-dispatch cannot skip a sibling.
+        for (const handler of [...this.#listeners[event]]) {
+            try {
+                handler(payload);
+            }
+            catch {
+                // A listener throwing must not derail the emit or the navigation.
+            }
+        }
+    }
+}
+/**
+ * The host-side image-zoom overlay. It lives entirely in the *host* document,
+ * outside the sandboxed frame: it renders the image's already-served `data:` bytes
+ * in a host DOM element, so it mints no new frame resource and — crucially — never
+ * a `blob:` URL (an opaque-origin frame cannot load a host blob URL; `data:` is the
+ * boundary-crossing form the whole view stack already relies on).
+ *
+ * Accessibility: it is a modal dialog with a focus TRAP (Tab cycles the close
+ * control and image), closes on Escape or a backdrop click, and restores focus to
+ * whatever the reader element held before it opened. Its open/close transition —
+ * the reader's only animation — is gated on `prefers-reduced-motion`; input and
+ * page-turning are never gated on the preference.
+ */
+class ImageZoom {
+    #anchor;
+    #doc;
+    #root = null;
+    #image = null;
+    #closeButton = null;
+    #previouslyFocused = null;
+    #onKeyDown = (event) => {
+        if (event.key === 'Escape') {
+            event.preventDefault();
+            this.close();
+            return;
+        }
+        if (event.key === 'Tab')
+            this.#trapTab(event);
+    };
+    constructor(anchor) {
+        this.#anchor = anchor;
+        const doc = anchor.ownerDocument;
+        if (doc === null)
+            throw new ReaderError('the reader element is not in a document');
+        this.#doc = doc;
+    }
+    open(src, alt) {
+        if (this.#root !== null) {
+            // Re-target an already-open overlay rather than stacking a second one.
+            this.#image.src = src;
+            this.#image.alt = alt;
+            return;
+        }
+        const active = this.#doc.activeElement;
+        this.#previouslyFocused = active instanceof HTMLElement ? active : this.#anchor;
+        const root = this.#doc.createElement('div');
+        root.setAttribute('role', 'dialog');
+        root.setAttribute('aria-modal', 'true');
+        root.setAttribute('aria-label', alt !== '' ? alt : 'Zoomed image');
+        Object.assign(root.style, {
+            position: 'fixed',
+            inset: '0',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            background: 'rgba(0, 0, 0, 0.85)',
+            zIndex: '2147483647',
+            padding: '4vmin',
+            boxSizing: 'border-box',
+            opacity: this.#reducedMotion() ? '1' : '0',
+            transition: this.#reducedMotion() ? 'none' : 'opacity 150ms ease',
+        });
+        root.addEventListener('pointerdown', (event) => {
+            if (event.target === root)
+                this.close();
+        });
+        const image = this.#doc.createElement('img');
+        image.src = src;
+        image.alt = alt;
+        image.tabIndex = 0;
+        Object.assign(image.style, {
+            maxWidth: '100%',
+            maxHeight: '100%',
+            objectFit: 'contain',
+            boxShadow: '0 4px 32px rgba(0, 0, 0, 0.5)',
+        });
+        const close = this.#doc.createElement('button');
+        close.type = 'button';
+        close.setAttribute('aria-label', 'Close');
+        close.textContent = '×';
+        Object.assign(close.style, {
+            position: 'absolute',
+            top: '2vmin',
+            right: '2vmin',
+            width: '2.5rem',
+            height: '2.5rem',
+            fontSize: '1.5rem',
+            lineHeight: '1',
+            cursor: 'pointer',
+            border: '0',
+            borderRadius: '50%',
+            background: 'rgba(255, 255, 255, 0.9)',
+            color: '#000',
+        });
+        close.addEventListener('click', () => {
+            this.close();
+        });
+        root.append(image, close);
+        this.#doc.body.append(root);
+        this.#root = root;
+        this.#image = image;
+        this.#closeButton = close;
+        this.#doc.addEventListener('keydown', this.#onKeyDown, true);
+        // Fade in on the next frame so the transition has a start value to animate from.
+        if (!this.#reducedMotion()) {
+            const view = this.#doc.defaultView;
+            if (view !== null)
+                view.requestAnimationFrame(() => (root.style.opacity = '1'));
+        }
+        close.focus();
+    }
+    close() {
+        const root = this.#root;
+        if (root === null)
+            return;
+        this.#doc.removeEventListener('keydown', this.#onKeyDown, true);
+        this.#root = null;
+        this.#image = null;
+        this.#closeButton = null;
+        const restore = this.#previouslyFocused;
+        this.#previouslyFocused = null;
+        root.remove();
+        this.#restoreFocus(restore);
+    }
+    /**
+     * Return focus to the reader region. The tap that opened the overlay came from
+     * inside the sandboxed frame, so the host's active element is usually the frame's
+     * body (not focusable from here) — fall back to the reader mount, made
+     * programmatically focusable with a temporary `tabindex` so focus lands on the
+     * reader rather than the document body.
+     */
+    #restoreFocus(saved) {
+        if (saved !== null && saved.isConnected && saved !== this.#doc.body) {
+            saved.focus();
+            if (this.#doc.activeElement === saved)
+                return;
+        }
+        const anchor = this.#anchor;
+        // A bare div is not focusable; a -1 tabindex makes it programmatically
+        // focusable without adding it to the tab order. Idempotent and benign.
+        if (!anchor.hasAttribute('tabindex'))
+            anchor.tabIndex = -1;
+        anchor.focus();
+    }
+    destroy() {
+        this.close();
+    }
+    /**
+     * Keep Tab focus inside the overlay: the close control and image are the stops.
+     * Tab is intercepted unconditionally and focus is moved explicitly so it can
+     * never escape the overlay — the reader region behind it is inert while open.
+     */
+    #trapTab(event) {
+        event.preventDefault();
+        const stops = this.#focusStops();
+        if (stops.length === 0)
+            return;
+        const active = this.#doc.activeElement;
+        const current = active === null ? -1 : stops.indexOf(active);
+        const step = event.shiftKey ? -1 : 1;
+        const nextIndex = current === -1 ? 0 : (current + step + stops.length) % stops.length;
+        stops[nextIndex].focus();
+    }
+    #focusStops() {
+        const stops = [];
+        if (this.#closeButton !== null)
+            stops.push(this.#closeButton);
+        if (this.#image !== null)
+            stops.push(this.#image);
+        return stops;
+    }
+    #reducedMotion() {
+        const view = this.#doc.defaultView;
+        return view !== null && view.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    }
+}
+/** Structural check for a `Position` (vs a TocItem, both objects). */
+function isPosition(value) {
+    return (typeof value.serialized === 'string' &&
+        typeof value.sectionId === 'string' &&
+        value.anchor !== undefined &&
+        value.children === undefined);
+}
+// Re-exported so a caller can rebuild a Position from its serialized form before
+// handing it to goTo — the facade never persists, but goTo(Position) is a target.
+export { parsePosition };
+//# sourceMappingURL=index.js.map