@caipira/vue-reader 0.0.1

package/README.md

@@ -0,0 +1,153 @@
+# @caipira/vue-reader
+
+Headless EPUB reader toolkit for Vue 3.
+
+This package provides a controller-first API and Vue composables for embedding a Readium-based reader in your app.
+
+## What is included
+
+- Headless reader controller (`createEpubReaderController`)
+- Vue composables (`useEpubReader`, state/navigation/settings helpers)
+- Reader settings helpers (`useReaderSettings`, `setReaderColors`)
+- Dictionary integration hooks (`setReaderDictionary`, `ReaderDictionaryApi`)
+
+The default loading strategy is `zip-fetcher` and should be used for production today.
+
+## Install
+
+```bash
+npm install @caipira/vue-reader
+```
+
+## Quick start (zip-fetcher default)
+
+```ts
+import { useTemplateRef } from 'vue';
+import {
+    useEpubReader,
+    useEpubReaderState,
+    useEpubReaderNavigation,
+    setReaderColors,
+} from '@caipira/vue-reader';
+
+const containerRef = useTemplateRef<HTMLDivElement>('containerRef');
+
+setReaderColors({
+    background: '#0f172a',
+    text: '#f8fafc',
+    highlight: '#facc15',
+});
+
+const reader = useEpubReader(() => props.src, containerRef, {
+    assets: {
+        fontBaseUrl: '/fonts',
+    },
+});
+
+const state = useEpubReaderState(reader);
+const navigation = useEpubReaderNavigation(reader);
+```
+
+## Dictionary API
+
+The reader uses your dictionary adapter to classify words as `known` or `unknown`.
+Unknown words are highlighted automatically in the viewport.
+
+Implement and register a dictionary adapter:
+
+```ts
+import type {
+    ReaderDictionaryApi,
+    ReaderDictionaryWordStatus,
+} from '@caipira/vue-reader';
+import { setReaderDictionary } from '@caipira/vue-reader';
+
+function createDictionary(): ReaderDictionaryApi {
+    const cache = new Map<string, ReaderDictionaryWordStatus>();
+
+    return {
+        async classifyWords(language, lemmas, contextKey) {
+            // Load/sync dictionary data for `language` once, then classify lemmas.
+            // `contextKey` can be used as a cache partition key.
+            const result = new Map<string, ReaderDictionaryWordStatus>();
+
+            for (const lemma of lemmas) {
+                const status = cache.get(lemma) ?? 'unknown';
+                result.set(lemma, status);
+            }
+
+            return result;
+        },
+        clear() {
+            cache.clear();
+        },
+    };
+}
+
+setReaderDictionary(createDictionary());
+```
+
+### Contract
+
+- `classifyWords(language, lemmas, contextKey)`
+  Returns a `Map<lemma, 'known' | 'unknown'>`.
+- `clear()`
+  Clears adapter caches when reader state is torn down.
+
+## Word highlighting and lookup flow
+
+When a dictionary is registered with `setReaderDictionary(...)`:
+
+- Unknown words are highlighted automatically.
+- Users can `Ctrl`+click (or `Cmd`+click on macOS) a word to trigger lookup.
+
+You can handle lookup events by extending your dictionary object with an optional `onWordLookup` callback (matching the UI integration):
+
+```ts
+import type { ReaderDictionaryApi } from '@caipira/vue-reader';
+import { setReaderDictionary } from '@caipira/vue-reader';
+
+const dictionary = createDictionary() as ReaderDictionaryApi & {
+    onWordLookup?: (payload: { language: string; word: string; context: string }) => void;
+};
+
+dictionary.onWordLookup = ({ language, word, context }) => {
+    // Open your dictionary UI (drawer/modal/popover) and query definitions.
+    openDictionaryDrawer({ language, word, context });
+};
+
+setReaderDictionary(dictionary);
+```
+
+The `context` value contains nearby text around the clicked word, useful for disambiguation.
+
+## Public API
+
+- `createEpubReaderController(srcRef, containerRef, options)`
+- `useEpubReaderController(src, containerRef, options)`
+- `useEpubReader(src, containerRef, options)`
+- `useEpubReaderState(controller)`
+- `useEpubReaderNavigation(controller)`
+- `useEpubReaderSettings(controller)`
+- `useEpubReaderControllerRef()`
+- `setEpubReaderController(controller)`
+- `setReaderColors({ background, text, highlight })`
+- `setReaderDictionary(dictionary)`
+- `useReaderDictionary()`
+
+## Adapters
+
+### Preferences adapter
+
+Use `preferences` to load and persist reader settings from your app-specific store.
+
+### Storage adapter
+
+Use `storage` to override default sessionStorage-based locator persistence.
+
+## Build
+
+```bash
+npm run typecheck
+npm run build
+```

package/dist/composables/useEpubReaderStrategy.d.ts

@@ -0,0 +1,19 @@
+import type { ChapterBoundary } from '../types/common';
+export type ReaderProgress = {
+    progress: number;
+    resourceProgression: number;
+};
+export type ReaderProgressCalculator = (idx: number, rawProg?: number) => ReaderProgress;
+export type ReaderSourcePayload = {
+    publication?: unknown;
+    manifest?: unknown;
+    fetcher?: unknown;
+    chapterProgressions: Map<string, ChapterBoundary[]>;
+    createPositions?: (publication: unknown) => Promise<any[]>;
+    createProgressCalculator: (publication: unknown) => ReaderProgressCalculator;
+    onFrameLoaded?: (wnd: Window, chapterHref: string) => void;
+};
+export type ReaderSourceStrategy = {
+    load: (url: string) => Promise<ReaderSourcePayload>;
+    destroy: () => void;
+};

package/dist/composables/useEpubReaderStrategy.js

@@ -0,0 +1 @@
+export {};

package/dist/composables/useEpubReaderWasm.d.ts

@@ -0,0 +1,2 @@
+import type { ReaderSourceStrategy } from '../composables/useEpubReaderStrategy';
+export declare function useEpubReaderWasm(): ReaderSourceStrategy;

package/dist/composables/useEpubReaderWasm.js

@@ -0,0 +1,131 @@
+import { resolveHref } from '../services/browser/url';
+import { computePublicationChaptersSize } from '../services/common/progression';
+import { loadPublication, createPublication, unloadPublication, } from '../services/wasm/wasm-streamer';
+import { buildWeightsFromResolver } from '../services/common/progression';
+import { installFrameDocumentBridge } from '../services/wasm/frame-document-bridge';
+const isExternalRef = (value) => {
+    const ref = value.trim().toLowerCase();
+    return (ref === '' ||
+        ref.startsWith('#') ||
+        ref.startsWith('data:') ||
+        ref.startsWith('blob:') ||
+        ref.startsWith('javascript:') ||
+        ref.startsWith('mailto:') ||
+        ref.startsWith('tel:') ||
+        /^[a-z][a-z0-9+.-]*:/.test(ref));
+};
+const normalizeToStreamerUrl = (href, chapterHref, webpubPrefix) => {
+    const trimmed = href.trim();
+    if (isExternalRef(trimmed)) {
+        return href;
+    }
+    if (trimmed.startsWith(webpubPrefix)) {
+        return trimmed;
+    }
+    const resolved = resolveHref(chapterHref, trimmed);
+    if (isExternalRef(resolved)) {
+        return href;
+    }
+    return `${webpubPrefix}${resolved}`;
+};
+const normalizeFrameResourceUrls = (frameWindow, chapterHref, webpubPrefix) => {
+    const doc = frameWindow.document;
+    if (!doc)
+        return;
+    const attrMap = [
+        { selector: 'img[src]', attr: 'src' },
+        { selector: 'image[href]', attr: 'href' },
+        { selector: 'source[src]', attr: 'src' },
+        { selector: 'video[src]', attr: 'src' },
+        { selector: 'audio[src]', attr: 'src' },
+        { selector: 'track[src]', attr: 'src' },
+        { selector: 'script[src]', attr: 'src' },
+        { selector: 'link[href]', attr: 'href' },
+        { selector: 'source[srcset]', attr: 'srcset' },
+        { selector: 'img[srcset]', attr: 'srcset' },
+    ];
+    for (const { selector, attr } of attrMap) {
+        const nodes = doc.querySelectorAll(selector);
+        nodes.forEach((node) => {
+            const current = node.getAttribute(attr);
+            if (!current) {
+                return;
+            }
+            if (attr === 'srcset') {
+                const rewritten = current
+                    .split(',')
+                    .map((entry) => {
+                    const trimmed = entry.trim();
+                    if (!trimmed) {
+                        return trimmed;
+                    }
+                    const firstSpace = trimmed.search(/\s/);
+                    if (firstSpace < 0) {
+                        return normalizeToStreamerUrl(trimmed, chapterHref, webpubPrefix);
+                    }
+                    const urlPart = trimmed.slice(0, firstSpace);
+                    const descriptor = trimmed.slice(firstSpace);
+                    return `${normalizeToStreamerUrl(urlPart, chapterHref, webpubPrefix)}${descriptor}`;
+                })
+                    .join(', ');
+                node.setAttribute(attr, rewritten);
+                return;
+            }
+            const normalized = normalizeToStreamerUrl(current, chapterHref, webpubPrefix);
+            node.setAttribute(attr, normalized);
+        });
+    }
+};
+export function useEpubReaderWasm() {
+    let activeBookId = null;
+    let webpubPrefix = '';
+    let uninstallFrameDocumentBridge = null;
+    const load = async (url) => {
+        const bookId = btoa(url).replace(/[/+=]/g, '_');
+        activeBookId = bookId;
+        webpubPrefix = `/epub-streamer/webpub/${bookId}/`;
+        uninstallFrameDocumentBridge = installFrameDocumentBridge();
+        await loadPublication(bookId, url);
+        const publication = await createPublication(bookId);
+        const chaptersSize = await computePublicationChaptersSize(publication);
+        return {
+            publication,
+            chapterProgressions: new Map(),
+            createPositions: async (publication) => {
+                const pub = publication;
+                const manifestPositions = await pub.positionsFromManifest();
+                return (manifestPositions ?? [])
+                    .filter((locator) => !!locator)
+                    .map((locator, index) => {
+                    if (locator.locations) {
+                        return locator;
+                    }
+                    return locator.copyWithLocations({
+                        position: index + 1,
+                        progression: 0,
+                    });
+                });
+            },
+            createProgressCalculator: (publication) => buildWeightsFromResolver(publication, (href) => {
+                const baseHref = href.split('#')[0];
+                return chaptersSize.get(baseHref);
+            }),
+            onFrameLoaded: (wnd, chapterHref) => {
+                normalizeFrameResourceUrls(wnd, chapterHref, webpubPrefix);
+            },
+        };
+    };
+    const destroy = () => {
+        if (activeBookId) {
+            void unloadPublication(activeBookId);
+            activeBookId = null;
+        }
+        uninstallFrameDocumentBridge?.();
+        uninstallFrameDocumentBridge = null;
+        webpubPrefix = '';
+    };
+    return {
+        load,
+        destroy,
+    };
+}

package/dist/composables/useEpubReaderZipFetcher.d.ts

@@ -0,0 +1,2 @@
+import type { ReaderSourceStrategy } from '../composables/useEpubReaderStrategy';
+export declare function useEpubReaderZipFetcher(): ReaderSourceStrategy;

package/dist/composables/useEpubReaderZipFetcher.js

@@ -0,0 +1,29 @@
+import ZipFetcher from '../services/browser/zip-fetcher';
+import { buildManifest } from '../services/browser/manifest';
+import { clearBlobUrlCache } from '../services/browser/url-rewrite';
+import { fetchEpub, unzipEpub } from '../services/browser/epub';
+import { buildWeightsFromZip, computeChapterProgressions, } from '../services/common/progression';
+export function useEpubReaderZipFetcher() {
+    const load = async (url) => {
+        const zip = await unzipEpub(await fetchEpub(url));
+        const manifest = buildManifest(zip);
+        const fetcher = new ZipFetcher(zip);
+        const chapterProgressions = manifest.toc
+            ? computeChapterProgressions(manifest.toc.items, zip)
+            : new Map();
+        const createProgressCalculator = (publication) => buildWeightsFromZip(publication, zip);
+        return {
+            manifest,
+            fetcher,
+            chapterProgressions,
+            createProgressCalculator,
+        };
+    };
+    const destroy = () => {
+        clearBlobUrlCache();
+    };
+    return {
+        load,
+        destroy,
+    };
+}

package/dist/services/browser/epub.d.ts

@@ -0,0 +1,4 @@
+import type { ZipData } from '../../types/browser';
+declare const fetchEpub: (url: string) => Promise<ArrayBuffer>;
+declare const unzipEpub: (buf: ArrayBuffer) => Promise<ZipData>;
+export { fetchEpub, unzipEpub };

package/dist/services/browser/epub.js

@@ -0,0 +1,22 @@
+import JSZip from 'jszip';
+const fetchEpub = async (url) => {
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(res.statusText || 'Failed to fetch EPUB');
+    }
+    return res.arrayBuffer();
+};
+const unzipEpub = async (buf) => {
+    const zip = await JSZip.loadAsync(buf);
+    const entries = {};
+    const tasks = [];
+    zip.forEach((relPath, entry) => {
+        tasks.push(entry.async('uint8array').then((data) => {
+            const key = relPath.replace(/\\/g, '/').replace(/^\.\//, '');
+            entries[key] = data;
+        }));
+    });
+    await Promise.all(tasks);
+    return entries;
+};
+export { fetchEpub, unzipEpub };

package/dist/services/browser/manifest.d.ts

@@ -0,0 +1,7 @@
+import type { ZipData } from '../../types/browser';
+import { Manifest } from '@readium/shared';
+/**
+ * Build a RWPM Manifest from the OPF file and related resources in the zip.
+ */
+declare const buildManifest: (zip: ZipData) => Manifest;
+export { buildManifest };

package/dist/services/browser/manifest.js

@@ -0,0 +1,224 @@
+import { Link, Links, Metadata, Manifest, Contributor, Contributors, LocalizedString, ReadingProgression, } from '@readium/shared';
+import { guessMediaType, getExt, resolveHref } from '../../services/browser/url';
+const parseNavDoc = (html, baseDir) => {
+    const doc = new DOMParser().parseFromString(html, 'text/html');
+    const nav = doc.querySelector('nav[epub\\:type="toc"]') ??
+        doc.querySelector('nav[type="toc"]') ??
+        doc.querySelector('nav#toc, .toc');
+    if (!nav) {
+        return [];
+    }
+    return Array.from(nav.querySelectorAll('a'))
+        .map((a) => {
+        const href = a.getAttribute('href');
+        const title = a.textContent?.trim();
+        if (!href || !title) {
+            return null;
+        }
+        return new Link({
+            href: resolveHref(baseDir, href),
+            type: 'application/xhtml+xml',
+            title,
+        });
+    })
+        .filter(Boolean);
+};
+const parseNcx = (xml, baseDir) => {
+    const doc = new DOMParser().parseFromString(xml, 'text/xml');
+    return Array.from(doc.querySelectorAll('navPoint'))
+        .map((np) => {
+        const content = np.querySelector('content');
+        const text = np.querySelector('navLabel > text');
+        const href = content?.getAttribute('src');
+        const title = text?.textContent?.trim();
+        if (!href || !title) {
+            return null;
+        }
+        return new Link({
+            href: resolveHref(baseDir, href),
+            type: 'application/xhtml+xml',
+            title,
+        });
+    })
+        .filter(Boolean);
+};
+const readText = (zip, path) => {
+    const data = zip[path];
+    if (!data) {
+        return undefined;
+    }
+    const decoder = new TextDecoder('utf-8');
+    return decoder.decode(data).replace(/^\uFEFF/, '');
+};
+const readXml = (zip, path) => {
+    const text = readText(zip, path);
+    if (!text) {
+        return undefined;
+    }
+    return new DOMParser().parseFromString(text, 'application/xml');
+};
+const getOpfPath = (zip) => {
+    const doc = readXml(zip, 'META-INF/container.xml');
+    if (!doc) {
+        return null;
+    }
+    const rf = doc.querySelector('rootfile');
+    return rf?.getAttribute('full-path') ?? null;
+};
+/**
+ * Build a RWPM Manifest from the OPF file and related resources in the zip.
+ */
+const buildManifest = (zip) => {
+    const opfPath = getOpfPath(zip);
+    if (!opfPath) {
+        throw new Error('Could not locate OPF (missing META-INF/container.xml)');
+    }
+    const baseDir = opfPath.substring(0, opfPath.lastIndexOf('/') + 1);
+    const opfDoc = readXml(zip, opfPath);
+    if (!opfDoc) {
+        throw new Error('Cannot parse OPF file');
+    }
+    const pkg = opfDoc.querySelector('package');
+    if (!pkg) {
+        throw new Error('Invalid OPF: missing <package>');
+    }
+    // Reading progression direction
+    const progressionDir = pkg.getAttribute('page-progression-direction') ?? pkg.getAttribute('dir');
+    const readingProgression = progressionDir === 'rtl' ? ReadingProgression.rtl : ReadingProgression.ltr;
+    // Metadata
+    const meta = pkg.querySelector('metadata');
+    const dc = (tag) => {
+        for (const child of meta?.children ?? []) {
+            const n = child.nodeName.toLowerCase();
+            if (n === `dc:${tag}` || child.localName === tag) {
+                return child.textContent ?? undefined;
+            }
+        }
+        return undefined;
+    };
+    const title = dc('title') || 'Untitled';
+    const author = dc('creator');
+    const lang = dc('language');
+    const identifier = dc('identifier');
+    const authors = author
+        ? new Contributors([
+            new Contributor({ name: new LocalizedString({ und: author }) }),
+        ])
+        : undefined;
+    const metadata = new Metadata({
+        title: new LocalizedString({ und: title }),
+        authors,
+        languages: lang ? [lang] : undefined,
+        identifier,
+        readingProgression,
+    });
+    // Manifest items
+    const items = pkg.querySelectorAll('manifest > item');
+    const idMap = new Map();
+    const hrefSet = new Set();
+    items.forEach((el) => {
+        const href = el.getAttribute('href');
+        if (!href) {
+            return;
+        }
+        const fullHref = baseDir + href;
+        const id = el.getAttribute('id') ?? fullHref;
+        const type = el.getAttribute('media-type') || guessMediaType(getExt(href));
+        const link = new Link({ href: fullHref, type });
+        idMap.set(id, link);
+        hrefSet.add(fullHref);
+    });
+    // Spine (reading order)
+    const spineLinks = [];
+    const spineHrefs = new Set();
+    const spineRefs = pkg.querySelectorAll('spine > itemref');
+    spineRefs.forEach((ref) => {
+        const idref = ref.getAttribute('idref');
+        if (!idref) {
+            return;
+        }
+        const link = idMap.get(idref);
+        if (link && !spineHrefs.has(link.href)) {
+            spineHrefs.add(link.href);
+            spineLinks.push(link);
+        }
+    });
+    const readingOrder = new Links(spineLinks);
+    // Resources (non-spine)
+    const resLinks = [];
+    hrefSet.forEach((h) => {
+        if (!spineHrefs.has(h)) {
+            const l = Array.from(idMap.values()).find((lk) => lk.href === h);
+            if (l)
+                resLinks.push(l);
+        }
+    });
+    const resources = new Links(resLinks);
+    // Table of contents (EPUB 3 nav / EPUB 2 NCX)
+    let toc = [];
+    const navItem = Array.from(items).find((el) => el.getAttribute('properties') === 'nav');
+    if (navItem) {
+        const navHref = navItem.getAttribute('href');
+        if (navHref) {
+            const navPath = baseDir + navHref;
+            const navDir = navPath.substring(0, navPath.lastIndexOf('/') + 1);
+            const html = readText(zip, navPath);
+            if (html) {
+                toc = parseNavDoc(html, navDir);
+            }
+        }
+    }
+    if (toc.length === 0) {
+        const ncxItem = Array.from(items).find((el) => el.getAttribute('media-type') === 'application/x-dtbncx+xml');
+        if (ncxItem) {
+            const ncxHref = ncxItem.getAttribute('href');
+            if (ncxHref) {
+                const ncxPath = baseDir + ncxHref;
+                const ncxDir = ncxPath.substring(0, ncxPath.lastIndexOf('/') + 1);
+                const xml = readText(zip, ncxPath);
+                if (xml) {
+                    toc = parseNcx(xml, ncxDir);
+                }
+            }
+        }
+    }
+    // Cross-reference TOC titles back to spine (reading order) links
+    // so that the navigator can report chapter titles on position changes.
+    //
+    // Many EPUBs use fragment anchors in the TOC (e.g. "part0000.xhtml#_Toc1")
+    // while the spine href has no fragment.  We match on the base href (no fragment)
+    // and take the *first* TOC title for that file as a fallback.  The
+    // positionChanged listener will do a more precise fragment-aware lookup.
+    if (toc.length > 0) {
+        // Map from base href (no fragment) → first TOC title for that file
+        const tocBaseTitleMap = new Map();
+        // Also keep the full TOC list for fragment-aware matching at runtime
+        const stripFragment = (href) => href.split('#')[0];
+        for (const tocLink of toc) {
+            if (!tocLink.title) {
+                continue;
+            }
+            const base = stripFragment(tocLink.href);
+            if (!tocBaseTitleMap.has(base)) {
+                tocBaseTitleMap.set(base, tocLink.title);
+            }
+        }
+        // Apply matched titles to spine links
+        for (const spineLink of spineLinks) {
+            const base = stripFragment(spineLink.href);
+            const title = tocBaseTitleMap.get(base);
+            if (title) {
+                spineLink.title = title;
+            }
+        }
+    }
+    return new Manifest({
+        context: ['https://readium.org/webpub-manifest/context.jsonld'],
+        metadata,
+        links: new Links([]),
+        readingOrder,
+        resources,
+        toc: toc.length > 0 ? new Links(toc) : undefined,
+    });
+};
+export { buildManifest };

package/dist/services/browser/url-rewrite.d.ts

@@ -0,0 +1,5 @@
+import type { ZipData } from '../../types/browser';
+declare const clearBlobUrlCache: () => void;
+declare const rewriteXhtmlUrls: (doc: Document, resourceHref: string, zip: ZipData) => void;
+declare const rewriteCssUrls: (css: string, resourceHref: string, zip: ZipData) => string;
+export { clearBlobUrlCache, rewriteXhtmlUrls, rewriteCssUrls };