frond-js 0.4.0

package/dist/formats/epub/index.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+var chunkEZTIZO6R_cjs = require('../../chunk-EZTIZO6R.cjs');
+require('../../chunk-WCZTTQ7Z.cjs');
+require('../../chunk-NABYHI6X.cjs');
+require('../../chunk-SLI2YL25.cjs');
+require('../../chunk-IIV6VIUJ.cjs');
+require('../../chunk-G7DLWGBW.cjs');
+
+// src/formats/epub/index.ts
+var EPUB_MEDIA_TYPE = "application/epub+zip";
+
+Object.defineProperty(exports, "openBook", {
+  enumerable: true,
+  get: function () { return chunkEZTIZO6R_cjs.openBook; }
+});
+Object.defineProperty(exports, "parseContainer", {
+  enumerable: true,
+  get: function () { return chunkEZTIZO6R_cjs.parseContainer; }
+});
+Object.defineProperty(exports, "parseOpf", {
+  enumerable: true,
+  get: function () { return chunkEZTIZO6R_cjs.parseOpf; }
+});
+Object.defineProperty(exports, "parseToc", {
+  enumerable: true,
+  get: function () { return chunkEZTIZO6R_cjs.parseToc; }
+});
+exports.EPUB_MEDIA_TYPE = EPUB_MEDIA_TYPE;

package/dist/formats/epub/index.d.cts

@@ -0,0 +1,286 @@
+import { Z as ZipArchive } from '../../types-BH88rUYt.cjs';
+import { a as Book, T as TocItem, B as BookSource } from '../../types-CPUqTEPW.cjs';
+import { O as OperationOptions } from '../../types-DQYmArgv.cjs';
+
+/**
+ * EPUB 解析（OCF 容器 / OPF package）的公共类型。
+ *
+ * 本模块属于 `frond-js/formats/epub`，经 subpath export 与动态 import 按需加载，
+ * **不计入 core 的 30KB gzip 预算**（ADR-0001）。
+ *
+ * 依赖方向：只依赖 `frond-js/core`，不得依赖 `render/`、`reader/`（ARCHITECTURE §1）。
+ */
+
+/**
+ * OCF 规范定义的 package document 媒体类型。
+ *
+ * 目前只支持这一种。其他媒体类型（如 `text/xml`）在 rootfile 选择阶段被跳过。
+ */
+type EpubPackageMediaType = 'application/oebps-package+xml';
+/** {@link parseContainer} 的解析结果。 */
+interface EpubContainer {
+    /**
+     * package document（OPF）在归档内的路径。
+     *
+     * 已完成规范化：前导 `/` 与 `.` 段被移除，`\` 归一化为 `/`，
+     * `..` 仅在归档根目录之内回退。**可直接交给归档读取层**。
+     */
+    readonly opfPath: string;
+    /** 被选中 rootfile 声明的媒体类型。 */
+    readonly mediaType: EpubPackageMediaType;
+}
+/** {@link parseContainer} 的选项。 */
+interface ParseContainerOptions extends OperationOptions {
+    /** 源标识，用于错误定位（REQ-EPUB-007）。通常传文件名或 URL。 */
+    readonly source?: string;
+    /**
+     * container 文档在归档内的路径。
+     *
+     * 默认 `META-INF/container.xml`（OCF 规范固定位置）。
+     * 仅用于错误定位或兼容非标准归档，正常 EPUB 无需设置。
+     */
+    readonly containerPath?: string;
+}
+/** {@link parseOpf} 的选项。 */
+interface ParseOpfOptions extends OperationOptions {
+    /**
+     * 源标识，用于错误定位（REQ-EPUB-007）。通常传文件名或 URL。
+     *
+     * 缺省时退化为 OPF 的归档路径，仍能定位到具体文件。
+     */
+    readonly source?: string;
+}
+/** {@link parseToc} 的选项。 */
+interface ParseTocOptions extends OperationOptions {
+    /**
+     * 源标识，用于错误定位（REQ-EPUB-007）。通常传文件名或 URL。
+     *
+     * 缺省时退化为目录文档（NAV 或 NCX）在归档内的路径。
+     */
+    readonly source?: string;
+}
+/** {@link openBook} 的选项。 */
+interface OpenBookOptions extends OperationOptions {
+    /**
+     * 源标识，用于错误定位（REQ-EPUB-007）。通常传文件名或 URL。
+     *
+     * 缺省时**逐层退化**为该层实际访问的归档路径（container → OPF → NAV/NCX），
+     * 而不是一个笼统的占位串 —— 这样错误 message 总能指到真正出问题的那个文件。
+     */
+    readonly source?: string;
+}
+/**
+ * {@link openBook} 的结果。
+ *
+ * 为什么是「三件套」而不是直接返回 `Book`：
+ *
+ * - **`toc` 不放进 `Book`**（T1.8 决策）。目录解析需要额外一次归档读取，
+ *   而 `parseOpf` 是纯 OPF 解析、不应隐式触发 IO（见 `docs/API.md` §10.3）。
+ *   把 `toc` 挂在编排结果上，`Book` 就能保持「只由 OPF 决定」的干净语义。
+ * - **`archive` 一并返回**。渲染层要按 `ManifestItem.href` / `TocItem.href`
+ *   读取 XHTML / CSS / 图片，而这些路径只有归档能解。若不返回，调用方就得
+ *   自己再调一次 `parseZip` —— 而 `parseZip` 是同步且不可取消的，
+ *   等于让调用方多付一次全量中央目录扫描，还绕开了 `signal`。
+ *   这里返回的归档**不复制字节**，只持有传入 `Uint8Array` 的引用。
+ */
+interface OpenedBook {
+    /** 已解析的归档（只读视图）。生命周期与传入的字节绑定。 */
+    readonly archive: ZipArchive;
+    /** 书籍模型：metadata / manifest / spine / 目录线索。**不含 `toc`**。 */
+    readonly book: Book;
+    /** 目录树，按文档顺序。无目录（既无 NAV 也无 NCX）时为空数组。 */
+    readonly toc: readonly TocItem[];
+}
+
+/**
+ * OCF container 解析（T1.4）。
+ *
+ * 读取 `META-INF/container.xml`，解析 `rootfiles`，选择受支持的 package
+ * document，输出其在归档内的路径。**本层不解析 OPF 内容** —— 那是 T1.5 的职责。
+ *
+ * 错误分类（沿用 T1.3 的二分原则）：
+ * - 结构损坏（XML 非法）→ `ParseError`
+ * - 不符合 OCF 规范（container 缺失、无受支持 rootfile、路径越界、空路径、控制字符）
+ *   → `FormatError`
+ *
+ * 依赖方向：只依赖 `frond-js/core`（ARCHITECTURE §1 / §3.4）。
+ */
+
+/**
+ * 解析 OCF container，定位 package document（OPF）。
+ *
+ * @param archive - 已解析的 ZIP 归档。
+ * @param options - 取消信号、源标识、container 路径覆盖。
+ * @returns OPF 在归档内的规范化路径与其媒体类型。
+ * @throws {FormatError} container 缺失、无受支持的 rootfile、路径越界或非法。
+ * @throws {ParseError} container XML 结构损坏。
+ * @throws {AbortError} 操作被取消。
+ */
+declare function parseContainer(archive: ZipArchive, options?: ParseContainerOptions): Promise<EpubContainer>;
+
+/**
+ * OPF package document 解析（T1.5）。
+ *
+ * 把 OPF 转成跨格式的 `Book` 模型（`frond-js/core` 的 `model/types.ts`）。
+ * 覆盖 REQ-EPUB-003（元数据）与 REQ-EPUB-004（spine 顺序与 `linear`）。
+ *
+ * 错误分类（沿用 T1.3 的二分原则）：
+ * - 结构损坏（XML 非法）              → `ParseError`
+ * - 不符合 OPF 规范（缺必需字段、重复 id、
+ *   未知 idref、路径越界、根元素不对）  → `FormatError`
+ *
+ * 设计取舍：
+ * - **不静默生成不完整模型**（规格 §4.2）：`itemref@idref` 悬空、manifest 重复 `id`、
+ *   缺少 `title` / `identifier` / `language` 一律抛错。
+ * - 唯一例外是**可选线索**：`spine@toc` 悬空时 `ncxPath` 置空而不报错 ——
+ *   它只是 EPUB 2 遗留的目录提示，且 EPUB 3 已弃用；与 `dcterms:modified` 同理，
+ *   不因一个可选线索缺失就拒掉整本能读的书。
+ *
+ * 依赖方向：只依赖 `frond-js/core`（ARCHITECTURE §1 / §3.4）。
+ */
+
+/**
+ * 解析 OPF package document，产出 `Book` 模型。
+ *
+ * @param archive - 已解析的 ZIP 归档。
+ * @param opfPath - OPF 在归档内的路径（通常来自 {@link parseContainer}）。
+ * @param options - 取消信号与源标识。
+ * @returns 只读的 `Book`：`format` / metadata / `resources` / `chapters`（跨格式层）
+ *   与 `manifest` / `spine` / `manifestIndex` / `opfPath` / `basePath` / 目录线索（EPUB 专属层）。
+ *   `resources` 由 `manifest`、`chapters` 由 `spine` **派生**（ADR-0014）。
+ *   `direction`（通用可选层）来自 `spine@page-progression-direction`，缺省 / `default` /
+ *   非法值一律**缺席**（不是 `undefined` 值，见 `resolveDirection`）。
+ * @throws {FormatError} 缺必需字段、重复 id、未知 idref、路径非法、根元素不对。
+ * @throws {ParseError} OPF XML 结构损坏。
+ * @throws {AbortError} 操作被取消。
+ */
+declare function parseOpf(archive: ZipArchive, opfPath: string, options?: ParseOpfOptions): Promise<Book>;
+
+/**
+ * EPUB 目录解析（T1.6）：NAV（EPUB 3）与 NCX（EPUB 2 降级）。
+ *
+ * 覆盖 REQ-EPUB-001（目录可读）与 REQ-EPUB-002（EPUB 2 降级）。
+ *
+ * 选择规则（规格 §4.3）：
+ * 1. manifest 中 `properties` 含 `nav` 的 XHTML 目录文档（EPUB 3）**优先**
+ * 2. 缺少 NAV 时，用 `spine@toc` 指向的 NCX（EPUB 2）
+ * 3. 两者线索都没有 → 空目录
+ *
+ * ⚠️ NAV **存在但损坏**时不回退到 NCX —— 「缺少」与「损坏」是两回事，
+ * 静默降级会掩盖真实缺陷（与 T1.5「不静默生成不完整模型」一致）。
+ *
+ * 口径（T1.6 Step 1 已确认）：
+ * - `TocItem.href` **不含** fragment，与 `ManifestItem.href` 一致；
+ *   fragment 单独成字段，因此 `href` 可直接交给归档读取层
+ * - 只含 fragment 的链接（`#top`）→ `href` = 引用文档自身路径，**永不为空**
+ * - 缺 `href` / 缺 `content@src` → `FormatError`；label 缺失则宽容为空串
+ *   （label 只影响展示，缺目标则目录项无法使用）
+ *
+ * 相对链接按**引用它的文档**（NAV / NCX 文件）所在目录解析，而非 OPF 目录 ——
+ * 这是 EPUB 规范的定义。两者通常同目录，此时结果与「按 OPF 基准」一致。
+ *
+ * 错误分类（沿用 T1.3 的二分原则）：
+ * - 结构损坏（XML 非法）          → `ParseError`
+ * - 不符合规范（缺链接、路径越界）→ `FormatError`
+ *
+ * 依赖方向：只依赖 `frond-js/core`（ARCHITECTURE §1 / §3.4）。
+ */
+
+/**
+ * 解析书籍目录。
+ *
+ * NAV（EPUB 3）优先，缺失时降级到 NCX（EPUB 2）。线索来自 {@link parseOpf}
+ * 产出的 `Book.tocItem` / `Book.ncxPath`；两者都没有时返回空数组。
+ *
+ * @param archive - 已解析的 ZIP 归档。
+ * @param book - 已解析的 `Book`（通常来自 {@link parseOpf}）。
+ * @param options - 取消信号与源标识。
+ * @returns 目录树；无目录时为空数组。每一项的 `href` 可直接交给归档读取层。
+ * @throws {FormatError} 目录项缺目标、路径越界、NAV/NCX 文档在归档中缺失。
+ * @throws {ParseError} 目录文档 XML 结构损坏。
+ * @throws {AbortError} 操作被取消。
+ */
+declare function parseToc(archive: ZipArchive, book: Book, options?: ParseTocOptions): Promise<readonly TocItem[]>;
+
+/**
+ * EPUB 端到端编排（T1.8）。
+ *
+ * 把 `parseZip → parseContainer → parseOpf → parseToc` 串成一条链，
+ * 让调用方用一次调用完成「字节 → `{ archive, book, toc }`」。
+ *
+ * 为什么不把这四步塞进一个函数体内部、而是保持四个独立导出：
+ * 分层各有用途 —— 只想读元数据时不必解析目录（省一次归档读取），
+ * 只想验容器时不必读 OPF。编排层只是**给最常见的完整路径**提供一个便捷入口，
+ * 不取代分层 API（`docs/API.md` §9–§11）。
+ *
+ * 本模块属于 `frond-js/formats/epub`，经 subpath export 与动态 import 按需加载，
+ * **不计入 core 的 30KB gzip 预算**（ADR-0001）。
+ *
+ * 依赖方向：只依赖 `frond-js/core`，不得依赖 `render/`、`reader/`（ARCHITECTURE §1）。
+ */
+
+/**
+ * 从 EPUB 字节打开一本书：ZIP → container.xml → OPF → NAV / NCX 目录。
+ *
+ * 等价于手工串联：
+ * ```ts
+ * const archive = parseZip(bytes);
+ * const { opfPath } = await parseContainer(archive);
+ * const book = await parseOpf(archive, opfPath);
+ * const toc = await parseToc(archive, book);
+ * ```
+ * 但有三处编排层的额外保证：
+ *
+ * 1. **`signal` 在 `parseZip` 之前就被检查**。`parseZip` 是同步且不可取消的，
+ *    已取消的调用不应白白扫一遍中央目录（H6 / H7）。
+ * 2. **`source` 缺省时逐层退化**，而不是填一个笼统的占位串 ——
+ *    于是错误 message 总会指到真正出问题的那个文件（REQ-EPUB-007）。
+ * 3. **接受可注入的字节源**（REQ-CORE-005）：除裸 `Uint8Array` 外，还可传入
+ *    {@link BookSource}，宿主借此接入内存 / OPFS / 远端分片，core 无需感知差异。
+ *
+ * 后续三层（container / OPF / 目录）各自在入口处重新检查 `signal`，
+ * 因此取消在任意两次归档读取之间都能及时生效，无需在此重复检查。
+ *
+ * @param source - 完整 EPUB 归档字节，或提供它的 {@link BookSource}。
+ *   传 `Uint8Array` 时**不会被复制**，返回的 `archive` 持有其引用。
+ *   传 `BookSource` 时**一次性读全** `[0, size)` —— 见
+ *   `core/formats/bytes.ts` 的 `resolveBookBytes`（T3.0.3 起由注册表与本函数共用同一实现）。
+ * @param options - 取消信号与源标识。
+ * @returns `{ archive, book, toc }`；无目录时 `toc` 为空数组。
+ * @throws {FormatError} 归档结构非法（ZIP64 / 加密 / 条目缺失）、OCF 或 OPF 语义违规、
+ *   目录文档缺失；或字节源未提供合法总长 / 返回字节数与总长不符。
+ * @throws {ParseError} container / OPF / 目录文档 XML 结构损坏。
+ * @throws {AbortError} 操作被取消。
+ */
+declare function openBook(source: Uint8Array | BookSource, options?: OpenBookOptions): Promise<OpenedBook>;
+
+/**
+ * `frond-js/formats/epub` — EPUB 3 解析器入口。
+ *
+ * 已实现：**T1.4 OCF container**（`parseContainer`）、**T1.5 OPF package**（`parseOpf`）、
+ * **T1.6 NAV / NCX 目录**（`parseToc`）、**T1.8 端到端编排**（`openBook`）。
+ *
+ * 分层 API 与编排 API 并存：`openBook` 是「字节 → `{ archive, book, toc }`」的
+ * 便捷入口，但**不取代** `parseContainer` / `parseOpf` / `parseToc` ——
+ * 只想读元数据时不必解析目录，只想验容器时不必读 OPF。
+ *
+ * CFI（T1.7）不在本入口 —— 它属**跨格式复用能力**，位于 `frond-js/core`
+ * （划分判据见 `docs/ARCHITECTURE.md` §1）。
+ *
+ * 本入口以 subpath export + 动态 import 方式按需加载，因此
+ * **不计入 core 的 30KB gzip 预算**（ADR-0001）。
+ *
+ * ⚠️ **`epubAdapter`（格式适配层端口）刻意不从本入口 re-export**（T3.0.3 决定）：
+ * 它实现的是 `core/formats/types.ts` 的 `FormatAdapter`，而该端口**未从任何入口公开**，
+ * 且 `ReaderOptions` 也没有注册表注入点 ⇒ 公开它等于发布一个「消费者既无法命名其类型、
+ * 也无法注入」的 API。**加公开面以后再加是非破坏性的，收回却是破坏性的**，
+ * 故先保持内部；等第三方格式包有真实消费者时再定公开面（见 ADR-0013「落地时的修订」）。
+ * 内部消费方（`src/reader/formats.ts`、单测）直接 import `./adapter.js`。
+ *
+ * 依赖方向：只依赖 `frond-js/core`，不得依赖 `render/`、`reader/`（ARCHITECTURE §1 / §3.4）。
+ */
+
+/** EPUB 容器媒体类型（OCF 规范定义）。 */
+declare const EPUB_MEDIA_TYPE = "application/epub+zip";
+
+export { EPUB_MEDIA_TYPE, type EpubContainer, type EpubPackageMediaType, type OpenBookOptions, type OpenedBook, type ParseContainerOptions, type ParseOpfOptions, type ParseTocOptions, openBook, parseContainer, parseOpf, parseToc };

package/dist/formats/epub/index.d.ts

@@ -0,0 +1,286 @@
+import { Z as ZipArchive } from '../../types-B76GOMxj.js';
+import { a as Book, T as TocItem, B as BookSource } from '../../types-C-5eHSRH.js';
+import { O as OperationOptions } from '../../types-DQYmArgv.js';
+
+/**
+ * EPUB 解析（OCF 容器 / OPF package）的公共类型。
+ *
+ * 本模块属于 `frond-js/formats/epub`，经 subpath export 与动态 import 按需加载，
+ * **不计入 core 的 30KB gzip 预算**（ADR-0001）。
+ *
+ * 依赖方向：只依赖 `frond-js/core`，不得依赖 `render/`、`reader/`（ARCHITECTURE §1）。
+ */
+
+/**
+ * OCF 规范定义的 package document 媒体类型。
+ *
+ * 目前只支持这一种。其他媒体类型（如 `text/xml`）在 rootfile 选择阶段被跳过。
+ */
+type EpubPackageMediaType = 'application/oebps-package+xml';
+/** {@link parseContainer} 的解析结果。 */
+interface EpubContainer {
+    /**
+     * package document（OPF）在归档内的路径。
+     *
+     * 已完成规范化：前导 `/` 与 `.` 段被移除，`\` 归一化为 `/`，
+     * `..` 仅在归档根目录之内回退。**可直接交给归档读取层**。
+     */
+    readonly opfPath: string;
+    /** 被选中 rootfile 声明的媒体类型。 */
+    readonly mediaType: EpubPackageMediaType;
+}
+/** {@link parseContainer} 的选项。 */
+interface ParseContainerOptions extends OperationOptions {
+    /** 源标识，用于错误定位（REQ-EPUB-007）。通常传文件名或 URL。 */
+    readonly source?: string;
+    /**
+     * container 文档在归档内的路径。
+     *
+     * 默认 `META-INF/container.xml`（OCF 规范固定位置）。
+     * 仅用于错误定位或兼容非标准归档，正常 EPUB 无需设置。
+     */
+    readonly containerPath?: string;
+}
+/** {@link parseOpf} 的选项。 */
+interface ParseOpfOptions extends OperationOptions {
+    /**
+     * 源标识，用于错误定位（REQ-EPUB-007）。通常传文件名或 URL。
+     *
+     * 缺省时退化为 OPF 的归档路径，仍能定位到具体文件。
+     */
+    readonly source?: string;
+}
+/** {@link parseToc} 的选项。 */
+interface ParseTocOptions extends OperationOptions {
+    /**
+     * 源标识，用于错误定位（REQ-EPUB-007）。通常传文件名或 URL。
+     *
+     * 缺省时退化为目录文档（NAV 或 NCX）在归档内的路径。
+     */
+    readonly source?: string;
+}
+/** {@link openBook} 的选项。 */
+interface OpenBookOptions extends OperationOptions {
+    /**
+     * 源标识，用于错误定位（REQ-EPUB-007）。通常传文件名或 URL。
+     *
+     * 缺省时**逐层退化**为该层实际访问的归档路径（container → OPF → NAV/NCX），
+     * 而不是一个笼统的占位串 —— 这样错误 message 总能指到真正出问题的那个文件。
+     */
+    readonly source?: string;
+}
+/**
+ * {@link openBook} 的结果。
+ *
+ * 为什么是「三件套」而不是直接返回 `Book`：
+ *
+ * - **`toc` 不放进 `Book`**（T1.8 决策）。目录解析需要额外一次归档读取，
+ *   而 `parseOpf` 是纯 OPF 解析、不应隐式触发 IO（见 `docs/API.md` §10.3）。
+ *   把 `toc` 挂在编排结果上，`Book` 就能保持「只由 OPF 决定」的干净语义。
+ * - **`archive` 一并返回**。渲染层要按 `ManifestItem.href` / `TocItem.href`
+ *   读取 XHTML / CSS / 图片，而这些路径只有归档能解。若不返回，调用方就得
+ *   自己再调一次 `parseZip` —— 而 `parseZip` 是同步且不可取消的，
+ *   等于让调用方多付一次全量中央目录扫描，还绕开了 `signal`。
+ *   这里返回的归档**不复制字节**，只持有传入 `Uint8Array` 的引用。
+ */
+interface OpenedBook {
+    /** 已解析的归档（只读视图）。生命周期与传入的字节绑定。 */
+    readonly archive: ZipArchive;
+    /** 书籍模型：metadata / manifest / spine / 目录线索。**不含 `toc`**。 */
+    readonly book: Book;
+    /** 目录树，按文档顺序。无目录（既无 NAV 也无 NCX）时为空数组。 */
+    readonly toc: readonly TocItem[];
+}
+
+/**
+ * OCF container 解析（T1.4）。
+ *
+ * 读取 `META-INF/container.xml`，解析 `rootfiles`，选择受支持的 package
+ * document，输出其在归档内的路径。**本层不解析 OPF 内容** —— 那是 T1.5 的职责。
+ *
+ * 错误分类（沿用 T1.3 的二分原则）：
+ * - 结构损坏（XML 非法）→ `ParseError`
+ * - 不符合 OCF 规范（container 缺失、无受支持 rootfile、路径越界、空路径、控制字符）
+ *   → `FormatError`
+ *
+ * 依赖方向：只依赖 `frond-js/core`（ARCHITECTURE §1 / §3.4）。
+ */
+
+/**
+ * 解析 OCF container，定位 package document（OPF）。
+ *
+ * @param archive - 已解析的 ZIP 归档。
+ * @param options - 取消信号、源标识、container 路径覆盖。
+ * @returns OPF 在归档内的规范化路径与其媒体类型。
+ * @throws {FormatError} container 缺失、无受支持的 rootfile、路径越界或非法。
+ * @throws {ParseError} container XML 结构损坏。
+ * @throws {AbortError} 操作被取消。
+ */
+declare function parseContainer(archive: ZipArchive, options?: ParseContainerOptions): Promise<EpubContainer>;
+
+/**
+ * OPF package document 解析（T1.5）。
+ *
+ * 把 OPF 转成跨格式的 `Book` 模型（`frond-js/core` 的 `model/types.ts`）。
+ * 覆盖 REQ-EPUB-003（元数据）与 REQ-EPUB-004（spine 顺序与 `linear`）。
+ *
+ * 错误分类（沿用 T1.3 的二分原则）：
+ * - 结构损坏（XML 非法）              → `ParseError`
+ * - 不符合 OPF 规范（缺必需字段、重复 id、
+ *   未知 idref、路径越界、根元素不对）  → `FormatError`
+ *
+ * 设计取舍：
+ * - **不静默生成不完整模型**（规格 §4.2）：`itemref@idref` 悬空、manifest 重复 `id`、
+ *   缺少 `title` / `identifier` / `language` 一律抛错。
+ * - 唯一例外是**可选线索**：`spine@toc` 悬空时 `ncxPath` 置空而不报错 ——
+ *   它只是 EPUB 2 遗留的目录提示，且 EPUB 3 已弃用；与 `dcterms:modified` 同理，
+ *   不因一个可选线索缺失就拒掉整本能读的书。
+ *
+ * 依赖方向：只依赖 `frond-js/core`（ARCHITECTURE §1 / §3.4）。
+ */
+
+/**
+ * 解析 OPF package document，产出 `Book` 模型。
+ *
+ * @param archive - 已解析的 ZIP 归档。
+ * @param opfPath - OPF 在归档内的路径（通常来自 {@link parseContainer}）。
+ * @param options - 取消信号与源标识。
+ * @returns 只读的 `Book`：`format` / metadata / `resources` / `chapters`（跨格式层）
+ *   与 `manifest` / `spine` / `manifestIndex` / `opfPath` / `basePath` / 目录线索（EPUB 专属层）。
+ *   `resources` 由 `manifest`、`chapters` 由 `spine` **派生**（ADR-0014）。
+ *   `direction`（通用可选层）来自 `spine@page-progression-direction`，缺省 / `default` /
+ *   非法值一律**缺席**（不是 `undefined` 值，见 `resolveDirection`）。
+ * @throws {FormatError} 缺必需字段、重复 id、未知 idref、路径非法、根元素不对。
+ * @throws {ParseError} OPF XML 结构损坏。
+ * @throws {AbortError} 操作被取消。
+ */
+declare function parseOpf(archive: ZipArchive, opfPath: string, options?: ParseOpfOptions): Promise<Book>;
+
+/**
+ * EPUB 目录解析（T1.6）：NAV（EPUB 3）与 NCX（EPUB 2 降级）。
+ *
+ * 覆盖 REQ-EPUB-001（目录可读）与 REQ-EPUB-002（EPUB 2 降级）。
+ *
+ * 选择规则（规格 §4.3）：
+ * 1. manifest 中 `properties` 含 `nav` 的 XHTML 目录文档（EPUB 3）**优先**
+ * 2. 缺少 NAV 时，用 `spine@toc` 指向的 NCX（EPUB 2）
+ * 3. 两者线索都没有 → 空目录
+ *
+ * ⚠️ NAV **存在但损坏**时不回退到 NCX —— 「缺少」与「损坏」是两回事，
+ * 静默降级会掩盖真实缺陷（与 T1.5「不静默生成不完整模型」一致）。
+ *
+ * 口径（T1.6 Step 1 已确认）：
+ * - `TocItem.href` **不含** fragment，与 `ManifestItem.href` 一致；
+ *   fragment 单独成字段，因此 `href` 可直接交给归档读取层
+ * - 只含 fragment 的链接（`#top`）→ `href` = 引用文档自身路径，**永不为空**
+ * - 缺 `href` / 缺 `content@src` → `FormatError`；label 缺失则宽容为空串
+ *   （label 只影响展示，缺目标则目录项无法使用）
+ *
+ * 相对链接按**引用它的文档**（NAV / NCX 文件）所在目录解析，而非 OPF 目录 ——
+ * 这是 EPUB 规范的定义。两者通常同目录，此时结果与「按 OPF 基准」一致。
+ *
+ * 错误分类（沿用 T1.3 的二分原则）：
+ * - 结构损坏（XML 非法）          → `ParseError`
+ * - 不符合规范（缺链接、路径越界）→ `FormatError`
+ *
+ * 依赖方向：只依赖 `frond-js/core`（ARCHITECTURE §1 / §3.4）。
+ */
+
+/**
+ * 解析书籍目录。
+ *
+ * NAV（EPUB 3）优先，缺失时降级到 NCX（EPUB 2）。线索来自 {@link parseOpf}
+ * 产出的 `Book.tocItem` / `Book.ncxPath`；两者都没有时返回空数组。
+ *
+ * @param archive - 已解析的 ZIP 归档。
+ * @param book - 已解析的 `Book`（通常来自 {@link parseOpf}）。
+ * @param options - 取消信号与源标识。
+ * @returns 目录树；无目录时为空数组。每一项的 `href` 可直接交给归档读取层。
+ * @throws {FormatError} 目录项缺目标、路径越界、NAV/NCX 文档在归档中缺失。
+ * @throws {ParseError} 目录文档 XML 结构损坏。
+ * @throws {AbortError} 操作被取消。
+ */
+declare function parseToc(archive: ZipArchive, book: Book, options?: ParseTocOptions): Promise<readonly TocItem[]>;
+
+/**
+ * EPUB 端到端编排（T1.8）。
+ *
+ * 把 `parseZip → parseContainer → parseOpf → parseToc` 串成一条链，
+ * 让调用方用一次调用完成「字节 → `{ archive, book, toc }`」。
+ *
+ * 为什么不把这四步塞进一个函数体内部、而是保持四个独立导出：
+ * 分层各有用途 —— 只想读元数据时不必解析目录（省一次归档读取），
+ * 只想验容器时不必读 OPF。编排层只是**给最常见的完整路径**提供一个便捷入口，
+ * 不取代分层 API（`docs/API.md` §9–§11）。
+ *
+ * 本模块属于 `frond-js/formats/epub`，经 subpath export 与动态 import 按需加载，
+ * **不计入 core 的 30KB gzip 预算**（ADR-0001）。
+ *
+ * 依赖方向：只依赖 `frond-js/core`，不得依赖 `render/`、`reader/`（ARCHITECTURE §1）。
+ */
+
+/**
+ * 从 EPUB 字节打开一本书：ZIP → container.xml → OPF → NAV / NCX 目录。
+ *
+ * 等价于手工串联：
+ * ```ts
+ * const archive = parseZip(bytes);
+ * const { opfPath } = await parseContainer(archive);
+ * const book = await parseOpf(archive, opfPath);
+ * const toc = await parseToc(archive, book);
+ * ```
+ * 但有三处编排层的额外保证：
+ *
+ * 1. **`signal` 在 `parseZip` 之前就被检查**。`parseZip` 是同步且不可取消的，
+ *    已取消的调用不应白白扫一遍中央目录（H6 / H7）。
+ * 2. **`source` 缺省时逐层退化**，而不是填一个笼统的占位串 ——
+ *    于是错误 message 总会指到真正出问题的那个文件（REQ-EPUB-007）。
+ * 3. **接受可注入的字节源**（REQ-CORE-005）：除裸 `Uint8Array` 外，还可传入
+ *    {@link BookSource}，宿主借此接入内存 / OPFS / 远端分片，core 无需感知差异。
+ *
+ * 后续三层（container / OPF / 目录）各自在入口处重新检查 `signal`，
+ * 因此取消在任意两次归档读取之间都能及时生效，无需在此重复检查。
+ *
+ * @param source - 完整 EPUB 归档字节，或提供它的 {@link BookSource}。
+ *   传 `Uint8Array` 时**不会被复制**，返回的 `archive` 持有其引用。
+ *   传 `BookSource` 时**一次性读全** `[0, size)` —— 见
+ *   `core/formats/bytes.ts` 的 `resolveBookBytes`（T3.0.3 起由注册表与本函数共用同一实现）。
+ * @param options - 取消信号与源标识。
+ * @returns `{ archive, book, toc }`；无目录时 `toc` 为空数组。
+ * @throws {FormatError} 归档结构非法（ZIP64 / 加密 / 条目缺失）、OCF 或 OPF 语义违规、
+ *   目录文档缺失；或字节源未提供合法总长 / 返回字节数与总长不符。
+ * @throws {ParseError} container / OPF / 目录文档 XML 结构损坏。
+ * @throws {AbortError} 操作被取消。
+ */
+declare function openBook(source: Uint8Array | BookSource, options?: OpenBookOptions): Promise<OpenedBook>;
+
+/**
+ * `frond-js/formats/epub` — EPUB 3 解析器入口。
+ *
+ * 已实现：**T1.4 OCF container**（`parseContainer`）、**T1.5 OPF package**（`parseOpf`）、
+ * **T1.6 NAV / NCX 目录**（`parseToc`）、**T1.8 端到端编排**（`openBook`）。
+ *
+ * 分层 API 与编排 API 并存：`openBook` 是「字节 → `{ archive, book, toc }`」的
+ * 便捷入口，但**不取代** `parseContainer` / `parseOpf` / `parseToc` ——
+ * 只想读元数据时不必解析目录，只想验容器时不必读 OPF。
+ *
+ * CFI（T1.7）不在本入口 —— 它属**跨格式复用能力**，位于 `frond-js/core`
+ * （划分判据见 `docs/ARCHITECTURE.md` §1）。
+ *
+ * 本入口以 subpath export + 动态 import 方式按需加载，因此
+ * **不计入 core 的 30KB gzip 预算**（ADR-0001）。
+ *
+ * ⚠️ **`epubAdapter`（格式适配层端口）刻意不从本入口 re-export**（T3.0.3 决定）：
+ * 它实现的是 `core/formats/types.ts` 的 `FormatAdapter`，而该端口**未从任何入口公开**，
+ * 且 `ReaderOptions` 也没有注册表注入点 ⇒ 公开它等于发布一个「消费者既无法命名其类型、
+ * 也无法注入」的 API。**加公开面以后再加是非破坏性的，收回却是破坏性的**，
+ * 故先保持内部；等第三方格式包有真实消费者时再定公开面（见 ADR-0013「落地时的修订」）。
+ * 内部消费方（`src/reader/formats.ts`、单测）直接 import `./adapter.js`。
+ *
+ * 依赖方向：只依赖 `frond-js/core`，不得依赖 `render/`、`reader/`（ARCHITECTURE §1 / §3.4）。
+ */
+
+/** EPUB 容器媒体类型（OCF 规范定义）。 */
+declare const EPUB_MEDIA_TYPE = "application/epub+zip";
+
+export { EPUB_MEDIA_TYPE, type EpubContainer, type EpubPackageMediaType, type OpenBookOptions, type OpenedBook, type ParseContainerOptions, type ParseOpfOptions, type ParseTocOptions, openBook, parseContainer, parseOpf, parseToc };

package/dist/formats/epub/index.js

@@ -0,0 +1,11 @@
+export { openBook, parseContainer, parseOpf, parseToc } from '../../chunk-SJVOYNTF.js';
+import '../../chunk-JJVXT3AC.js';
+import '../../chunk-D4KWSEZD.js';
+import '../../chunk-UY2YRCFC.js';
+import '../../chunk-U4264IQH.js';
+import '../../chunk-B2L2YVXD.js';
+
+// src/formats/epub/index.ts
+var EPUB_MEDIA_TYPE = "application/epub+zip";
+
+export { EPUB_MEDIA_TYPE };