frond-js 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 frond-js contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,247 @@
+# frond-js
+
+> 中文版 → [README.md](./README.md)
+
+A **zero-runtime-dependency** ebook reading engine: parses EPUB / MOBI(KF8) / FB2 / CBZ / PDF into a
+single book model and paginates them in the browser. The `core` layer does not depend on the DOM, so
+the same code runs in both Node and the browser.
+
+⭐ **It is an engine, not a reader app.** This library ships **no user interface** — no toolbar, no progress
+bar, no swipe gestures, and it **does not take over the keyboard or mouse**: turn pages by calling
+`reader.next()` / `reader.prev()` / `reader.goTo(i)`; which key that is bound to, whether gestures exist and
+how focus moves are **the host's business**. That is what keeps hosts from inheriting UI they did not ask
+for (see [docs/PRD.md](./docs/PRD.md) §1.2).
+
+> ⚠️ This project is in the **`0.x`** stage and the API is not frozen. Versioning and SemVer
+> commitments are documented in [docs/CHANGELOG.md](./docs/CHANGELOG.md) and
+> [docs/API.md](./docs/API.md).
+
+## Supported formats
+
+⚠️ "Implemented" and "evidenced" are two different things. The table below deliberately keeps two
+separate columns — **real-publication samples** and **cross-implementation / third-party checks**:
+
+| Format      | Extensions          | Impl | Real-publication samples                                                                       | Cross-implementation / third-party checks                                                                                                                                                                                                                                              |
+| ----------- | ------------------- | ---- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| EPUB        | `.epub`             | ✅   | ✅ **2** (z-library; ⚠️ both use **NCX** — the EPUB 3 **NAV** path has never seen a real book) | ✅ 10 EPUB 3 fixtures are produced by an **independent implementation** (the project's own writer is not used) and triple-checked with `unzip -t` / `7z l` / Python `zipfile`; CFI is compared character-by-character against [foliate-js](https://github.com/johnfactotum/foliate-js) |
+| MOBI / AZW3 | `.mobi` / `.azw3`   | ✅   | ✅ **6** (Project Gutenberg) + 1 (z-library)                                                   | ✅ Chapter-by-chapter comparison against PyPI `mobi` (a Python port of KindleUnpack)                                                                                                                                                                                                   |
+| FB2         | `.fb2` / `.fb2.zip` | ✅   | ✅ **2** + 1 (z-library)                                                                       | ✅ Synthetic fixtures are produced by an independent Python script                                                                                                                                                                                                                     |
+| CBZ         | `.cbz`              | ✅   | ✅ **1** (z-library comics)                                                                    | ⚠️ Synthetic fixtures only, cross-checked with Python `zipfile` — **no cross-implementation oracle**                                                                                                                                                                                   |
+| PDF         | `.pdf`              | ✅   | ✅ **1**（z-library · 87 MB · scanned + OCR）                                                  | ⚠️ Adapter over `pdfjs-dist`; fixture readings come from a **real PDF.js**; page-image timings still **do not extrapolate**. ⭐ **A real book exposed a limitation**: scanned pages (JPEG 2000 / JBIG2 images) can render as **entirely blank without any error** (see **FI-X37**)     |
+
+⚠️ **Known gaps (not glossed over):**
+
+- The 10 EPUB fixtures are called "real" inside this project, where "real" means "**a valid EPUB
+  produced by an independent implementation and verified by third-party tools**" — it does **not**
+  mean "downloaded from a publisher". ⚠️ As of 2026-09-19 **two actual published books have gone
+  through the EPUB path** (readings in
+  [`tests/fixtures/real-books/README.md`](./tests/fixtures/real-books/README.md)) — but both carry
+  their table of contents as **NCX**, so the **EPUB 3 NAV path still has no real-book evidence**
+  (FI-X21 is neither confirmed nor ruled out).
+- MOBI's **HUFF/CDIC compression path** (`compression = 17480`) **still lacks a real-book sample**:
+  the implementation is done, but every committed real sample uses `compression = 2` (real
+  HUFF/CDIC files live in LGPL/GPL repositories and are, by convention, not committed here).
+- The **per-chapter fingerprints of `kf8-nested.mobi` have not yet been compared** against an
+  independent implementation.
+- **CBZ and PDF now each have one real published book** (2026-09-19 / 2026-09-22; readings in
+  [`tests/fixtures/real-books/README.md`](./tests/fixtures/real-books/README.md)); PDF page-image
+  timings still **do not extrapolate** (only one macOS Chromium has been measured).
+- ⚠️ **Scanned PDFs need host-supplied wasm decoders**: when page content is JPEG 2000 / JBIG2, PDF.js
+  needs extra **wasm assets** to decode it. This library **neither bundles those bytes nor guesses where
+  they live** ⇒ **without that configuration such books render fully blank, with no error at all**
+  (`state` stays `ready`, paging works).
+  ✅ Since **W-3** there is a supported way to configure it: hand the directory URLs to `Reader`; they are
+  forwarded **verbatim** to PDF.js —
+
+  ```text
+  new Reader({
+    host,
+    // ⚠️ Each URL must be a string ending in `/`: without the trailing slash PDF.js throws,
+    // while a non-string is silently treated as "not provided".
+    pdf: { wasmUrl: '/vendor/pdfjs/wasm/' },
+  });
+  ```
+
+  (This is a **configuration fragment**, not one of the two copy-paste-runnable examples above — on
+  purpose: `tests/e2e/readme-examples.spec.ts` counts only `ts` fences and runs each of them.)
+
+  ⚠️ If a scanned book was opened **first** in the same page without the addresses, later books can still
+  come out blank ⇒ set the addresses **before opening any PDF** (the phenomenon is registered; its
+  mechanism is not). Registered as **FI-X37**; details and the real-book readings in
+  [`tests/fixtures/pdf/README.md`](./tests/fixtures/pdf/README.md), boundary §4.
+
+## Features
+
+- **Compile-time layering**: four layers — `core` / `render` / `formats` / `reader` — with a
+  one-directional dependency graph enforced by ESLint `no-restricted-imports` and two tsconfigs.
+  `core` (including `formats`) must compile **without the `"dom"` lib** — that is the only way the
+  "one codebase, three targets" requirement can be verified automatically; trust alone always rots.
+- **Zero runtime dependencies**: `core` has none; `pdfjs-dist` is an **optional peer**, needed only
+  if you use PDF.
+- **Per-format code splitting**: format parsers are loaded on demand and **do not count against the
+  `core` size budget**.
+- **Injectable IO**: implement `BookSource` (`size` / `read(range)` / `close()`) to plug in custom
+  storage (OPFS, remote ranges, in-memory caches, …). A reference implementation,
+  `createMemoryBookSource`, ships in the box.
+- **Pluggable rendering**: implement `Renderer` to replace the whole rendering strategy
+  (paginated / scrolled / custom layout) without touching parsing or modeling.
+- **Uniform cancellation**: every async API accepts `OperationOptions.signal`; aborting throws
+  `AbortError` and releases whatever was allocated.
+
+## Installation
+
+```bash
+pnpm add frond-js
+```
+
+Requires **Node ≥ 20**. For PDF support, also install the optional peer:
+
+```bash
+pnpm add pdfjs-dist
+```
+
+## Runtime requirements
+
+| Target                                  | Requirement                                          |
+| --------------------------------------- | ---------------------------------------------------- |
+| Browsers                                | Chrome / Edge ≥ 111, Firefox ≥ 115, Safari ≥ 16.4    |
+| Node (headless parsing / modeling only) | ≥ 20                                                 |
+| **Development and testing** (this repo) | **Node ≥ 22.13** (`devDependencies` pins PDF.js 6.x) |
+
+⚠️ The table above lists **target runtimes**, **not** "verified on these versions": the matrix comes
+from `docs/PROMPT.md` §4.1, and there is currently **no cross-browser version testing** —
+`pnpm test:browser` runs on a single local Chromium.
+
+⚠️ Note the **Node version asymmetry**: consumers only need `≥ 20` (`package.json` `engines`), but
+**developing and testing inside this repository** requires `≥ 22.13`.
+
+Runtime feature dependencies: ES2022, `AbortSignal`, `CompressionStream` / `DecompressionStream`,
+`DOMParser` (injected through an **optional adapter** on Node — the library does **not** hard-depend
+on jsdom).
+
+## Quick start (browser)
+
+```ts
+import { Reader } from 'frond-js';
+
+const reader = new Reader({
+  host: { element: document.getElementById('viewer')!, ownerDocument: document },
+});
+
+const bytes = new Uint8Array(await (await fetch('/book.epub')).arrayBuffer());
+await reader.open(bytes);
+await reader.next();
+
+console.log(reader.state); // 'ready'
+```
+
+`open` accepts five input shapes: `ArrayBuffer` / `Uint8Array` / `Blob` / `string` (a URL) /
+`BookSource`.
+
+In **Node** there is no DOM, so only the `core`-side parsing entry point is usable:
+
+```ts
+import { openBook } from 'frond-js/formats/epub';
+
+const { book, toc } = await openBook(bytes, { source: 'book.epub' });
+console.log(book.metadata.title, toc.length);
+```
+
+> Neither snippet is invented:
+> [tests/e2e/readme-examples.spec.ts](./tests/e2e/readme-examples.spec.ts) **extracts these two blocks
+> verbatim and actually runs them** against the `dist/` build, on every `pnpm e2e` — break one token in an
+> example and the corresponding test goes red. The host page
+> [tests/e2e/fixtures/readme.html](./tests/e2e/fixtures/readme.html) only provides the DOM and an import
+> map; it contains **no usage code of its own**.
+
+## Two constraints you must know about
+
+**① The host element must have a definite height.** A host with `height: auto` collapses the
+renderer's wrapper to zero (its children are all absolutely positioned), and pagination then
+**silently** produces the wrong page count — no error, just wrong numbers.
+
+```css
+#viewer {
+  width: 800px;
+  height: 600px;
+}
+```
+
+**② `toc` is only readable while `ready`.** Reading it in any other state throws `StateError` and
+**does not return an empty array** — an empty array is indistinguishable from "this book genuinely
+has no table of contents", so returning one would hand the caller false information.
+
+## Entry points
+
+| Entry                   | Contents                                                                                                                         |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `frond-js`              | `Reader`, `READER_STATES` / `canTransition`, the error hierarchy, abort utilities, public types                                  |
+| `frond-js/core`         | ZIP reading, XML parsing, archive-path resolution, the book model (incl. `TocItem`), CFI, injectable IO, errors, abort utilities |
+| `frond-js/render`       | `Renderer` / `RenderHost` / `RenderLocation` types (⚠️ currently **types only**)                                                 |
+| `frond-js/formats/epub` | EPUB parser: `openBook` / `parseContainer` / `parseOpf` / `parseToc` / `EPUB_MEDIA_TYPE` (dynamic import)                        |
+
+⚠️ The parsers for the other formats (MOBI / FB2 / CBZ / PDF) are **not exported from any entry** —
+`Reader` loads them automatically based on format detection. The full signature contract lives in
+[docs/API.md](./docs/API.md) §1.
+
+## Development and verification
+
+```bash
+pnpm install
+pnpm verify # all ten gates must be green
+```
+
+`pnpm verify` runs, in order:
+`format:check → lint → typecheck → test → test:browser → build → size → release:check → api:check → docs:check → e2e`.
+
+⚠️ The English list above had drifted to **ten** rings and was missing `release:check` — corrected on 2026-09-19.
+
+⭐ **The first nine rings also run on Gitee Go for every push** (pipeline `frond-js-verify-L1`,
+[build history](https://gitee.com/eltongu/frond-js/gitee_go/pipelines?codeRef=master&codeType=branch);
+setup and pitfalls in [docs/CI.md](./docs/CI.md)). **Measured: 1 min 37 s.** The runtime is pinned by
+`.nvmrc` and **installed + hard-asserted inside the job** — the runner default is not trusted (it ships
+Node 16).
+
+The two browser rings (`test:browser` / `e2e`) run in a second pipeline, `frond-js-verify-L2`,
+**and are green** (`test:browser`: 1826 passed / 15.4 s; `e2e`: 4 passed / 29.9 s). ⚠️ It is **not**
+auto-triggered — measured on this Gitee Go instance, **only a "match everything" filter works**
+(`branches.prefix: ['']`); across six observations `precise`, non-empty `prefix` and `tags.*` all
+produced **zero** builds, so fine-grained triggering is simply unavailable. The entry point is the
+"Run" button on the pipeline page, plus an in-repo switch `.workflow/L2-ENABLE`
+(present = run, absent = exit immediately).
+⚠️ **FI-X25 (handled via direction ③)**: that 2-CPU CI machine is ~4× slower than the dev machine,
+and `e2e`'s "chapter switch p95 < 50 ms" measured **49.3 ms** on CI — only 1.4% of headroom, so it
+would go red at random. ⇒ absolute millisecond budgets are **printed but not asserted** on CI
+(`PERF_ABSOLUTE_BUDGET=0`, set on that one L2 line only); **local `pnpm verify` still asserts**.
+⚠️ The cost: CI no longer catches performance regressions — only the baseline device does.
+
+The three test commands are **not interchangeable** (they run different things):
+
+| Command             | What it runs                                                                      |
+| ------------------- | --------------------------------------------------------------------------------- |
+| `pnpm test`         | Unit and integration tests over `src/`, in **Node** (the only source of coverage) |
+| `pnpm test:browser` | **The same source**, executed in **Chromium** (verifies cross-target consistency) |
+| `pnpm e2e`          | The **`dist/` build output**, in a real browser (includes perf and size gates)    |
+
+⚠️ If `pnpm install` fails during the **import phase** with `ERR_PNPM_CODEBUDDY_BROKER_DENY`, the
+terminal has injected a Node filesystem-proxy shim; the workaround is in
+[AGENTS.md](./AGENTS.md) §3.1.6.
+
+## Documentation
+
+| Document                                       | Contents                                        |
+| ---------------------------------------------- | ----------------------------------------------- |
+| [docs/PRD.md](./docs/PRD.md)                   | Requirements and acceptance criteria            |
+| [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Layering, dependency direction, ADRs            |
+| [docs/API.md](./docs/API.md)                   | **The promised signature contract** (+ history) |
+| [docs/CHANGELOG.md](./docs/CHANGELOG.md)       | Changelog and version plan                      |
+| [docs/MILESTONES.md](./docs/MILESTONES.md)     | Milestones and hand-off cards                   |
+| [docs/KNOWN-ISSUES.md](./docs/KNOWN-ISSUES.md) | Known-issue registry (including open decisions) |
+| [docs/ATTRIBUTION.md](./docs/ATTRIBUTION.md)   | Third-party sources and license registry        |
+
+## License
+
+[MIT](./LICENSE) · Copyright (c) 2026 frond-js contributors
+
+Third-party sources and licenses — including the provenance and license status of the test fixtures
+— are registered in [docs/ATTRIBUTION.md](./docs/ATTRIBUTION.md).

package/README.md

@@ -0,0 +1,211 @@
+# frond-js
+
+> English version → [README.en.md](./README.en.md)
+
+一个**零运行时依赖**的电子书阅读引擎：把 EPUB / MOBI(KF8) / FB2 / CBZ / PDF 解析成统一的书模型，
+并在浏览器里分页渲染。`core` 侧不依赖 DOM，同一套代码可在 Node 与浏览器中运行。
+
+⭐ **它是引擎，不是阅读器。** 本库**不带任何界面** —— 没有工具栏、进度条、翻页手势，也**不接管键盘与鼠标**：
+翻页要调 `reader.next()` / `reader.prev()` / `reader.goTo(i)`，绑到哪个键、要不要做手势、焦点怎么走，
+**都是宿主的事**。这样宿主才不会被迫接受一套它不想要的 UI（详见 [docs/PRD.md](./docs/PRD.md) §1.2）。
+
+> ⚠️ 本项目处于 **`0.x`** 阶段，API 尚未冻结。版本号约定与 SemVer 承诺见
+> [docs/CHANGELOG.md](./docs/CHANGELOG.md) 与 [docs/API.md](./docs/API.md)。
+
+## 支持格式
+
+⚠️ 「已实现」与「有证据」是两件事。下表刻意分开两列 —— **真实出版物样本** 与 **跨实现 / 第三方校验**：
+
+| 格式        | 扩展名              | 实现 | 真实出版物样本                                                               | 跨实现 / 第三方校验                                                                                                                                                                                    |
+| ----------- | ------------------- | ---- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| EPUB        | `.epub`             | ✅   | ✅ **2 本**（z-library；⚠️ 目录均为 **NCX**，EPUB 3 **NAV 路径未跑过真书**） | ✅ 10 份 EPUB 3 fixture 由**独立实现**产出（不调用本项目写入器），经 `unzip -t` / `7z l` / Python `zipfile` 三重校验；CFI 与 [foliate-js](https://github.com/johnfactotum/foliate-js) 逐字符对拍       |
+| MOBI / AZW3 | `.mobi` / `.azw3`   | ✅   | ✅ **6 份**（Project Gutenberg）+ 1 本（z-library）                          | ✅ 与 PyPI `mobi`（KindleUnpack 的 Python 移植）逐章对拍                                                                                                                                               |
+| FB2         | `.fb2` / `.fb2.zip` | ✅   | ✅ **2 份** + 1 本（z-library）                                              | ✅ 合成件由独立 Python 脚本产出                                                                                                                                                                        |
+| CBZ         | `.cbz`              | ✅   | ✅ **1 本**（z-library 漫画）                                                | ⚠️ 仅合成件 + Python `zipfile` 交叉校验，**无跨实现对照**                                                                                                                                              |
+| PDF         | `.pdf`              | ✅   | ✅ **1**（z-library · 87 MB · 扫描 + OCR 件）                                | ⚠️ 适配 `pdfjs-dist`；夹具读数由**真 PDF.js** 跑出；页图渲染读数仍**不可外推**。⭐ **真书上暴露一条限制**：扫描版（JPEG 2000 / JBIG2 图像）在浏览器侧可能**整本出空白页而不报任何错**（见 **FI-X37**） |
+
+⚠️ **已知缺口（不粉饰）**：
+
+- EPUB 的 10 份 fixture 在本项目里叫「真实」，其定义是「**由独立实现产出、经第三方工具校验的合法 EPUB**」。
+  ⚠️ 2026-09-19 起**已有 2 本真实出版物跑通 EPUB 链路**（读数见
+  [`tests/fixtures/real-books/README.md`](./tests/fixtures/real-books/README.md)）—— 但两本的目录**都是 NCX**，
+  所以 **EPUB 3 NAV 这条路径至今没有真书证据**（FI-X21 既未确认也未否掉）。
+- MOBI 的 **HUFF/CDIC 压缩路径**（`compression = 17480`）**真书样本仍缺**：实现已完成，
+  但入库的真实样本 `compression` 全是 `2`（真实 HUFF/CDIC 文件都在 LGPL/GPL 仓库，按约定不入库）。
+- `kf8-nested.mobi` 的**逐章指纹尚未与独立实现对拍**。
+- **CBZ 与 PDF 各已有 1 本真书样本**（2026-09-19 / 2026-09-22，读数见
+  [`tests/fixtures/real-books/README.md`](./tests/fixtures/real-books/README.md)）；但 PDF 的页图渲染读数
+  仍**不可外推**到别的机器或别的文档（只在一台 macOS 的 Chromium 上跑过）。
+- ⚠️ **扫描版 PDF 需要宿主提供 wasm 解码器**：页内容是 JPEG 2000 / JBIG2 图像时，PDF.js 要额外的
+  **wasm 资源**才解得动。本库**不打包这些字节、也不猜它们在哪** ⇒ **不给配置时这类书会整本渲染成空白，
+  而不抛任何错误**（`state` 仍是 `ready`、翻页照常）。
+  ✅ 自 **W-3** 起有受支持的配法：把目录地址交给 `Reader`，**逐字**转发给 PDF.js ——
+
+  ```text
+  new Reader({
+    host,
+    // ⚠️ 每个地址必须是字符串且以 `/` 结尾：缺尾斜杠 PDF.js 会抛，非字符串则被静默当成「没给」。
+    pdf: { wasmUrl: '/vendor/pdfjs/wasm/' },
+  });
+  ```
+
+  （这是一段**配置片段**，不是上面那两段可复制运行的示例 —— 刻意的，`tests/e2e/readme-examples.spec.ts`
+  只数 `ts` 围栏并逐段真跑。）
+
+  ⚠️ 同一页面里**先**打开过一本没给地址的扫描书，之后再给也仍可能是空白 ⇒ 地址要在打开任何 PDF **之前**配好
+  （这条现象已登记，机理未取证）。登记为 **FI-X37**；细则与真书读数见
+  [`tests/fixtures/pdf/README.md`](./tests/fixtures/pdf/README.md) 的 §四。
+
+## 特性
+
+- **编译期分层**：`core` / `render` / `formats` / `reader` 四层，依赖方向单向，由 ESLint
+  `no-restricted-imports` 与两份 tsconfig 强制。`core`（含 `formats`）必须在**不含 `"dom"` lib**
+  的条件下编译通过 —— 这是「三端一致」能被自动验证的唯一方式，靠自觉必然腐化。
+- **零运行时依赖**：`core` 的运行时依赖为 0；`pdfjs-dist` 是**可选 peer**，只有用到 PDF 才需要装。
+- **格式独立分包**：格式解析器按需动态加载，**不计入 `core` 的体积预算**。
+- **可注入 IO**：实现 `BookSource`（`size` / `read(range)` / `close()`）即可接入自定义存储
+  （OPFS、远端分片、内存缓存……）。内置参考实现 `createMemoryBookSource`。
+- **可插拔渲染**：实现 `Renderer` 可整体替换渲染策略（分页 / 滚动 / 自定义排版），而不触碰解析与建模。
+- **统一的取消语义**：所有异步 API 接受 `OperationOptions.signal`；abort 后抛 `AbortError` 并释放已占资源。
+
+## 安装
+
+```bash
+pnpm add frond-js
+```
+
+需要 **Node ≥ 20**。若要使用 PDF，再装可选 peer：
+
+```bash
+pnpm add pdfjs-dist
+```
+
+## 运行时要求
+
+| 目标                            | 要求                                                  |
+| ------------------------------- | ----------------------------------------------------- |
+| 浏览器                          | Chrome / Edge ≥ 111、Firefox ≥ 115、Safari ≥ 16.4     |
+| Node（仅 headless 解析 / 建模） | ≥ 20                                                  |
+| **开发与测试**（本仓库自身）    | **Node ≥ 22.13**（`devDependencies` 钉了 PDF.js 6.x） |
+
+⚠️ 上表是**目标运行时**，**不是**「已在这些版本上验证过」：矩阵取自 `docs/PROMPT.md` §4.1，
+而目前**没有跨浏览器版本的实际测试** —— `pnpm test:browser` 只在本机的一份 Chromium 上跑。
+
+⚠️ 注意 **Node 版本的不对称**：消费者只需 `≥ 20`（`package.json` 的 `engines`），
+但**在本仓库里开发 / 测试**需要 `≥ 22.13`。
+
+运行时特性依赖：ES2022、`AbortSignal`、`CompressionStream` / `DecompressionStream`、`DOMParser`
+（Node 侧通过**可选适配器注入**，本库**不硬依赖 jsdom**）。
+
+## 快速开始（浏览器）
+
+```ts
+import { Reader } from 'frond-js';
+
+const reader = new Reader({
+  host: { element: document.getElementById('viewer')!, ownerDocument: document },
+});
+
+const bytes = new Uint8Array(await (await fetch('/book.epub')).arrayBuffer());
+await reader.open(bytes);
+await reader.next();
+
+console.log(reader.state); // 'ready'
+```
+
+`open` 接受 `ArrayBuffer` / `Uint8Array` / `Blob` / `string`（URL）/ `BookSource` 五种输入形态。
+
+在 **Node** 里没有 DOM，只能用 `core` 侧的解析入口：
+
+```ts
+import { openBook } from 'frond-js/formats/epub';
+
+const { book, toc } = await openBook(bytes, { source: 'book.epub' });
+console.log(book.metadata.title, toc.length);
+```
+
+> 上面两段不是凭空写的：[tests/e2e/readme-examples.spec.ts](./tests/e2e/readme-examples.spec.ts)
+> **把这两段原文抽出来真跑一遍**（被测对象是 `dist/` 构建产物，随 `pnpm e2e` 每次执行）
+> ⇒ 示例改坏一个 token，对应那条用例就会红。宿主页面见
+> [tests/e2e/fixtures/readme.html](./tests/e2e/fixtures/readme.html)，它只提供 DOM 与 import map、**不含任何用法代码**。
+
+## 两个必须知道的约束
+
+**① 宿主必须有确定高度。** 宿主元素的 `height: auto` 会让渲染层的 wrapper 塌成 0
+（子元素全绝对定位），分页会**静默**得到错误页数 —— 不报错，只是页数是错的。
+
+```css
+#viewer {
+  width: 800px;
+  height: 600px;
+}
+```
+
+**② `toc` 只在 `ready` 下可读。** 非 `ready` 时抛 `StateError`，**不返回空数组** ——
+空数组与「这本书确实没有目录」在类型上无法区分，返回它就是把假信息交给调用方。
+
+## 入口一览
+
+| 入口                    | 内容                                                                                                    |
+| ----------------------- | ------------------------------------------------------------------------------------------------------- |
+| `frond-js`              | `Reader`、`READER_STATES` / `canTransition`、错误体系、abort 工具、公共类型                             |
+| `frond-js/core`         | ZIP 读取、XML 解析、归档路径解析、书模型（含 `TocItem`）、CFI、可注入 IO、错误体系、abort 工具          |
+| `frond-js/render`       | `Renderer` / `RenderHost` / `RenderLocation` 类型（⚠️ 当前**只导出类型**）                              |
+| `frond-js/formats/epub` | EPUB 解析器：`openBook` / `parseContainer` / `parseOpf` / `parseToc` / `EPUB_MEDIA_TYPE`（动态 import） |
+
+⚠️ 其余格式（MOBI / FB2 / CBZ / PDF）的解析器**不从任何入口导出** —— 它们由 `Reader` 在打开时
+按探测结果自动加载。完整签名契约见 [docs/API.md](./docs/API.md) §1。
+
+## 开发与验证
+
+```bash
+pnpm install
+pnpm verify # 十一环全绿才算过
+```
+
+`pnpm verify` 依次跑：
+`format:check → lint → typecheck → test → test:browser → build → size → release:check → api:check → docs:check → e2e`。
+
+⭐ **前九环由 Gitee Go 在每次 push 时代跑**（流水线 `frond-js-verify-L1`，
+[构建历史](https://gitee.com/eltongu/frond-js/gitee_go/pipelines?codeRef=master&codeType=branch)；
+开通与踩坑见 [docs/CI.md](./docs/CI.md)）。**实测 1 分 37 秒**。运行时由 `.nvmrc` 钉住并在 CI 里
+**自装 + 硬断言** —— 不信运行器给的默认值（它给的是 Node 16）。
+
+两个浏览器环（`test:browser` / `e2e`）由第二条流水线 `frond-js-verify-L2` 跑，**已全绿**
+（`test:browser` 1826 passed / 15.4 秒；`e2e` 4 passed / 29.9 秒）。⚠️ 它**不是**自动触发 ——
+实测这个 Gitee Go 实例上**只有「匹配一切」的过滤规则生效**（`branches.prefix: ['']`），
+`precise`、非空 `prefix`、以及 `tags.*` 合计六次观测**全部零构建** ⇒ 精细触发拿不到。
+入口固定为流水线页的「运行」按钮，外加一道仓内开关 `.workflow/L2-ENABLE`（在才跑，不在就秒退）。
+⚠️ **FI-X25（已按方向③处置）**：CI 那台 2 CPU 的机器比本机慢约 4 倍，
+`e2e` 的「切章 p95 < 50 ms」在 CI 上实测 **49.3 ms** —— 只剩 1.4% 余量，会随机红。
+⇒ 绝对毫秒预算在 CI 上**只打印、不判红**（`PERF_ABSOLUTE_BUDGET=0`，只有 L2 那一行设）；
+**本地 `pnpm verify` 照旧断言**。⚠️ 代价：CI 不再拦性能退化，只在基准设备上拦。
+
+三条测试命令**不可互换**（它们跑的东西不同）：
+
+| 命令                | 跑什么                                                     |
+| ------------------- | ---------------------------------------------------------- |
+| `pnpm test`         | `src/` 的单元与集成测试，**Node** 环境（唯一的覆盖率来源） |
+| `pnpm test:browser` | **同一套源码**，在 **Chromium** 里跑（验证跨端一致性）     |
+| `pnpm e2e`          | **`dist/` 构建产物**，在真实浏览器里跑（含性能与体积门禁） |
+
+⚠️ 若 `pnpm install` 在**导入阶段**报 `ERR_PNPM_CODEBUDDY_BROKER_DENY`，那是终端注入了 Node
+文件系统代理 shim，处方见 [AGENTS.md](./AGENTS.md) §3.1.6。
+
+## 文档
+
+| 文档                                           | 内容                                 |
+| ---------------------------------------------- | ------------------------------------ |
+| [docs/PRD.md](./docs/PRD.md)                   | 需求与验收标准                       |
+| [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | 分层、依赖方向、关键设计决策（ADR）  |
+| [docs/API.md](./docs/API.md)                   | **对外承诺的签名契约**（含变更记录） |
+| [docs/CHANGELOG.md](./docs/CHANGELOG.md)       | 变更日志与版本规划                   |
+| [docs/MILESTONES.md](./docs/MILESTONES.md)     | 阶段里程碑与交接卡                   |
+| [docs/KNOWN-ISSUES.md](./docs/KNOWN-ISSUES.md) | 已知问题登记（含未拍板项）           |
+| [docs/ATTRIBUTION.md](./docs/ATTRIBUTION.md)   | 第三方来源与许可登记                 |
+
+## 许可
+
+[MIT](./LICENSE) · Copyright (c) 2026 frond-js contributors
+
+第三方来源与许可登记见 [docs/ATTRIBUTION.md](./docs/ATTRIBUTION.md)（含测试夹具的来源与许可状态）。

package/dist/abort-BY8vBk0v.d.cts

@@ -0,0 +1,99 @@
+/**
+ * frond-js 统一错误体系。
+ *
+ * 设计约束（ARCHITECTURE §6 / REQ-CORE-003）：
+ * - 禁止抛出裸 `Error` 或字符串
+ * - 每个错误携带稳定的 `code`，下游可据此分支，不依赖 message 文案
+ * - `cause` 保留原始错误，不丢失调用栈
+ */
+/** 稳定错误码。属于公共契约，变更需走 SemVer。 */
+type FrondErrorCode = 'ERR_PARSE' | 'ERR_FORMAT' | 'ERR_NETWORK' | 'ERR_SECURITY' | 'ERR_ABORT' | 'ERR_STATE';
+interface FrondErrorOptions {
+    /** 原始错误，用于保留调用栈。 */
+    readonly cause?: unknown;
+}
+/**
+ * 所有 frond-js 错误的基类。
+ *
+ * 不要直接实例化本类；请使用具体的子类。
+ */
+declare class FrondError extends Error {
+    /** 稳定错误码，用于程序化分支。 */
+    readonly code: FrondErrorCode;
+    constructor(code: FrondErrorCode, message: string, options?: FrondErrorOptions);
+}
+/** 解析失败：ZIP 损坏、XML 非法、结构缺失。 */
+declare class ParseError extends FrondError {
+    constructor(message: string, options?: FrondErrorOptions);
+}
+/** 格式不支持或不符合规范。 */
+declare class FormatError extends FrondError {
+    constructor(message: string, options?: FrondErrorOptions);
+}
+/** 资源加载失败。 */
+declare class NetworkError extends FrondError {
+    constructor(message: string, options?: FrondErrorOptions);
+}
+/** 触发安全策略（例如 CSP 拦截、脚本执行被拒）。 */
+declare class SecurityError extends FrondError {
+    constructor(message: string, options?: FrondErrorOptions);
+}
+/**
+ * 操作被取消。
+ *
+ * `name` 恒为 `'AbortError'`，与 `DOMException` 的语义对齐（H7）。
+ */
+declare class AbortError extends FrondError {
+    constructor(message?: string, options?: FrondErrorOptions);
+}
+/** 非法状态迁移（H5：禁止隐式标志位）。 */
+declare class StateError extends FrondError {
+    constructor(message: string, options?: FrondErrorOptions);
+}
+/** 判断任意值是否为 frond-js 错误。 */
+declare function isFrondError(value: unknown): value is FrondError;
+/**
+ * 判断任意值是否为取消错误。
+ *
+ * 同时识别 frond-js 的 {@link AbortError} 与宿主环境的 `DOMException`
+ * （`name === 'AbortError'`），因为 `AbortSignal.reason` 可能来自外部。
+ */
+declare function isAbortError(value: unknown): boolean;
+
+/**
+ * 取消与资源清理工具（H6 / H7）。
+ *
+ * 约定：
+ * - 所有异步 API 接受 `AbortSignal`
+ * - abort 后抛出 {@link AbortError}，**不得吞掉**
+ * - abort 必须释放资源（`revokeObjectURL` / `worker.terminate()` / iframe 清理 / 事件解绑）
+ */
+/** 创建一个携带原始原因的 {@link AbortError}。 */
+declare function createAbortError(reason?: unknown): AbortError;
+/**
+ * 若 signal 已 abort，立即抛出 {@link AbortError}。
+ *
+ * 用作异步流程中的检查点，避免在已取消的操作上继续分配资源。
+ */
+declare function throwIfAborted(signal?: AbortSignal): void;
+/**
+ * 合并多个 signal：任一 abort 即整体 abort。
+ *
+ * 全部为 `undefined` 时返回 `undefined`，便于直接透传给下游。
+ */
+declare function linkSignals(...signals: (AbortSignal | undefined)[]): AbortSignal | undefined;
+/**
+ * 注册 abort 回调，返回解绑函数。
+ *
+ * 若 signal 已 abort，回调会被**同步立即执行**。
+ * 解绑函数幂等，可在资源清理路径中无条件调用。
+ *
+ * @example
+ * ```ts
+ * const detach = onAbort(signal, () => URL.revokeObjectURL(url));
+ * // ... 正常结束时同样要调用 detach()，避免回调悬挂
+ * ```
+ */
+declare function onAbort(signal: AbortSignal | undefined, handler: () => void): () => void;
+
+export { AbortError as A, FormatError as F, NetworkError as N, ParseError as P, SecurityError as S, FrondError as a, type FrondErrorCode as b, type FrondErrorOptions as c, StateError as d, createAbortError as e, isFrondError as f, isAbortError as i, linkSignals as l, onAbort as o, throwIfAborted as t };