@likecoin/epub-ts 0.3.95 → 0.3.97

package/README.md

@@ -2,9 +2,21 @@
 
 A TypeScript fork of [epubjs](https://github.com/futurepress/epub.js) v0.3.93 by [Fred Chasen](https://github.com/fchasen) / [FuturePress](https://github.com/futurepress) — parse and render EPUB documents in the browser.
 
-This library is primarily developed for internal use at [3ook.com](https://3ook.com) and is provided as-is. It was mainly built with AI-assisted development.
+[![CI](https://github.com/likecoin/epub.ts/actions/workflows/ci.yml/badge.svg)](https://github.com/likecoin/epub.ts/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/%40likecoin%2Fepub-ts)](https://www.npmjs.com/package/@likecoin/epub-ts)
+[![License](https://img.shields.io/npm/l/%40likecoin%2Fepub-ts)](./LICENSE)
 
-## Install
+> **Note**: This library is primarily developed for internal use at [3ook.com](https://3ook.com) and is provided as-is. It was mainly built with AI-assisted development. For the original library, see [epubjs](https://github.com/futurepress/epub.js).
+
+## Features
+
+- **Drop-in replacement** for epubjs v0.3.93 — same API, just change the import
+- **TypeScript first** — full strict mode, typed emitter, generated `.d.ts` declarations
+- **Modern build** — Vite library build, ESM + CJS output
+- **Fewer dependencies** — removed `core-js`, `lodash`, `path-webpack`, `event-emitter`
+- **Named exports** — import individual classes like `Book`, `EpubCFI`, `Rendition`, etc.
+
+## Installation
 
 ```bash
 npm install @likecoin/epub-ts
@@ -12,18 +24,34 @@ npm install @likecoin/epub-ts
 
 ## Quick Start
 
-```js
+### ES Modules (recommended)
+
+```typescript
 import ePub from "@likecoin/epub-ts";
 
-// Same API as epubjs
 const book = ePub("/path/to/book.epub");
 const rendition = book.renderTo("viewer", { width: 600, height: 400 });
 rendition.display();
 ```
 
+### Browser (from ArrayBuffer)
+
+```typescript
+import ePub from "@likecoin/epub-ts";
+
+const fileInput = document.querySelector('input[type="file"]');
+fileInput.addEventListener("change", async (event) => {
+	const file = event.target.files[0];
+	const data = await file.arrayBuffer();
+	const book = ePub(data);
+	const rendition = book.renderTo("viewer", { width: 600, height: 400 });
+	rendition.display();
+});
+```
+
 ## Migration from epubjs
 
-This is a drop-in replacement. Change your import:
+Drop-in replacement. Change your import:
 
 ```diff
 - import ePub from "epubjs";
@@ -35,30 +63,108 @@ All APIs remain the same.
 ## Named Exports
 
 ```js
-import { Book, EpubCFI, Rendition, Contents, Layout } from "@likecoin/epub-ts";
+import {
+	Book, EpubCFI, Rendition, Contents, Layout,
+	Section, Spine, Locations, Navigation, PageList,
+	Resources, Packaging, Archive, Store,
+	Annotations, Themes, Mapping,
+} from "@likecoin/epub-ts";
 ```
 
-## What's Changed
+## API
+
+See the full [API documentation](https://likecoin.github.io/epub.ts/) for details on all classes, interfaces, and methods.
+
+Key classes:
+
+| Class | Description |
+|-------|-------------|
+| `Book` | Main EPUB representation — loading, parsing, manipulation |
+| `Rendition` | Renders a book to a DOM element |
+| `Contents` | Manages content within an iframe |
+| `EpubCFI` | EPUB Canonical Fragment Identifier parser |
+| `Locations` | Generates and manages reading locations |
+| `Navigation` | Table of contents and landmarks |
+| `Annotations` | Highlights, underlines, and marks |
+
+## Comparison with epubjs
+
+| Aspect | epub.ts | epubjs |
+|--------|---------|--------|
+| Language | TypeScript (strict mode) | JavaScript |
+| Build | Vite | webpack + Babel |
+| Tests | Vitest | Karma + Mocha |
+| Type definitions | Generated from source | Hand-written `.d.ts` |
+| Dependencies | 3 (`jszip`, `localforage`, `@xmldom/xmldom`) | 7+ (`core-js`, `lodash`, `event-emitter`, etc.) |
+| API compatibility | 100% (drop-in replacement) | — |
+| Bundle format | ESM + CJS | UMD |
+| Maintenance | Active | Inactive since 2022 |
+
+## Supported Environments
+
+| Environment | Notes |
+|-------------|-------|
+| Modern browsers | Chrome, Firefox, Safari, Edge (requires DOM) |
+| Vite / webpack | ESM or CJS imports |
+
+> **Note**: This library requires a DOM environment. Node.js support (parsing-only, no rendering) is planned but not yet available.
+
+## What's Changed from epubjs
 
 - Build: webpack + Babel → Vite
 - Tests: Karma + Mocha → Vitest
-- Source: JavaScript → TypeScript (incremental conversion)
+- Source: JavaScript → TypeScript (full strict mode)
 - Removed dependencies: `core-js`, `lodash`, `path-webpack`
 - Replaced `event-emitter` with inline typed emitter
 
 ## Development
 
+### Prerequisites
+
+- Node.js 18+
+- npm 9+
+
+### Setup
+
 ```bash
+git clone https://github.com/likecoin/epub.ts.git
+cd epub.ts
 npm install
-npm run build     # Vite library build → dist/
-npm test          # Vitest
-npm run typecheck # tsc --noEmit
 ```
 
+### Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run build` | Vite library build → `dist/` |
+| `npm test` | Run tests (Vitest) |
+| `npm run test:watch` | Run tests in watch mode |
+| `npm run typecheck` | TypeScript type checking (`tsc --noEmit`) |
+| `npm run lint` | ESLint |
+| `npm run lint:fix` | ESLint with auto-fix |
+| `npm run docs` | Generate API docs (HTML + Markdown) |
+
 ## Contributing
 
 See [PROJECT_STATUS.md](./PROJECT_STATUS.md) for current conversion progress and what to work on.
 
+For AI agents contributing to this project, see [AGENTS.md](./AGENTS.md).
+
 ## License
 
-BSD-2-Clause (same as epubjs)
+[BSD-2-Clause](./LICENSE) (same as epubjs)
+
+## Acknowledgments
+
+- [epubjs](https://github.com/futurepress/epub.js) by [Fred Chasen](https://github.com/fchasen) / [FuturePress](https://github.com/futurepress) — the original library this is forked from
+- [jszip](https://github.com/Stuk/jszip) — ZIP file handling
+- [@xmldom/xmldom](https://github.com/xmldom/xmldom) — XML parsing
+
+## Built by 3ook.com
+
+This project is built and maintained by the [3ook.com](https://3ook.com) team. 3ook is a Web3 eBook platform where authors can publish EPUB ebooks and readers can collect them as digital assets.
+
+## Related Projects
+
+- [epubjs](https://github.com/futurepress/epub.js) — Original EPUB reader library
+- [epubcheck-ts](https://github.com/likecoin/epubcheck-ts) — TypeScript EPUB validator (also by 3ook.com)

package/dist/annotations.d.ts

@@ -77,7 +77,7 @@ declare class Annotations {
     /**
      * iterate over annotations in the store
      */
-    each(..._args: any[]): any;
+    each(fn: (annotation: Annotation, key: string) => void): void;
     /**
      * Hook for injecting annotation into a view
      * @param {View} view

package/dist/archive.d.ts

@@ -51,9 +51,9 @@ declare class Archive {
     getBlob(url: string, mimeType?: string): Promise<Blob> | undefined;
     /**
      * Get Text from Archive by Url
-     * @param  {string} url
-     * @param  {string} [encoding]
-     * @return {string}
+     * @param url
+     * @param _encoding
+     * @return text content
      */
     getText(url: string, _encoding?: string): Promise<string> | undefined;
     /**

package/dist/book.d.ts

@@ -12,7 +12,8 @@ import { default as Rendition } from './rendition';
 import { default as Archive } from './archive';
 import { default as Store } from './store';
 import { default as DisplayOptions } from './displayoptions';
-import { IEventEmitter, BookOptions, RenditionOptions, RequestFunction } from './types';
+import { default as JSZip } from 'jszip';
+import { IEventEmitter, BookOptions, RenditionOptions, RequestFunction, PackagingManifestObject, PackagingMetadataObject } from './types';
 import { default as Section } from './section';
 interface BookLoadingState {
     manifest: defer;
@@ -25,14 +26,14 @@ interface BookLoadingState {
     displayOptions: defer;
 }
 interface BookLoadedState {
-    manifest: Promise<any>;
-    spine: Promise<any>;
-    metadata: Promise<any>;
-    cover: Promise<any>;
-    navigation: Promise<any>;
-    pageList: Promise<any>;
-    resources: Promise<any>;
-    displayOptions: Promise<any>;
+    manifest: Promise<PackagingManifestObject>;
+    spine: Promise<Spine>;
+    metadata: Promise<PackagingMetadataObject>;
+    cover: Promise<string>;
+    navigation: Promise<Navigation>;
+    pageList: Promise<PageList>;
+    resources: Promise<Resources>;
+    displayOptions: Promise<DisplayOptions>;
 }
 /**
  * An Epub representation with methods for the loading, parsing and manipulation
@@ -59,7 +60,7 @@ declare class Book implements IEventEmitter {
     isOpen: boolean;
     loading: BookLoadingState | undefined;
     loaded: BookLoadedState | undefined;
-    ready: Promise<any[]> | undefined;
+    ready: Promise<[PackagingManifestObject, Spine, PackagingMetadataObject, string, Navigation, Resources, DisplayOptions]> | undefined;
     isRendered: boolean;
     request: RequestFunction;
     spine: Spine | undefined;
@@ -188,7 +189,7 @@ declare class Book implements IEventEmitter {
      * @param  {string} [encoding]
      * @return {Archive}
      */
-    unarchive(input: string | ArrayBuffer | Blob, encoding?: string): Promise<any>;
+    unarchive(input: string | ArrayBuffer | Blob, encoding?: string): Promise<JSZip>;
     /**
      * Store the epubs contents
      * @private

package/dist/contents.d.ts

@@ -1,4 +1,5 @@
 import { default as EpubCFI } from './epubcfi';
+import { DOM_EVENTS } from './utils/constants';
 import { ViewportSettings, LayoutProps, EpubCFIPair, IEventEmitter } from './types';
 import { default as Section } from './section';
 /**
@@ -42,7 +43,7 @@ declare class Contents implements IEventEmitter {
     /**
         * Get DOM events that are listened for and passed along
         */
-    static get listenedEvents(): readonly ["keydown", "keyup", "keypressed", "mouseup", "mousedown", "mousemove", "click", "touchend", "touchstart", "touchmove"];
+    static get listenedEvents(): typeof DOM_EVENTS;
     /**
         * Get or Set width
         * @param {number} [w]
@@ -216,7 +217,7 @@ declare class Contents implements IEventEmitter {
      * @param {array | object} rules
      * @param {string} key If the key is the same, the CSS will be replaced instead of inserted
      */
-    addStylesheetRules(rules: any, key?: string): void;
+    addStylesheetRules(rules: Record<string, Record<string, string> | Array<Record<string, string>>> | Array<Array<string | string[]>>, key?: string): void;
     /**
      * Append a script tag to the document head
      * @param {string} src url
@@ -230,7 +231,7 @@ declare class Contents implements IEventEmitter {
     addClass(className: string): void;
     /**
      * Remove a class from the contents container
-     * @param {string} removeClass
+     * @param className - class name to remove
      */
     removeClass(className: string): void;
     /**