frond-js 0.4.0

package/dist/types-B7mslPBY.d.ts

@@ -0,0 +1,166 @@
+/**
+ * EPUB CFI（Canonical Fragment Identifier）类型契约。
+ *
+ * 设计依据（T1.7 决策，2026-09-14）：
+ *
+ * - **判别联合**：单点与范围在类型上分开，`kind` 可穷尽判别。
+ *   范围的两端**恒非空** —— 省略 start 时显式归一，而不是留 `undefined`。
+ *   这正是基线 FI-010 的缺陷形状：foliate-js 的 `splitAt` 在分隔符只有 1 个时返回 2 段，
+ *   而 `parse` 按 3 段解构，导致 `end` 恒为 `undefined`、`collapse` 抛错或产出错误结果
+ *   （见 `docs/KNOWN-ISSUES.md` FI-010 与 `scripts/refs/fi010-cfi-range.mjs`）。
+ * - **零 DOM**：本模块只做「字符串 ↔ 路径结构」，不触碰 `NodeFilter` 与真实节点
+ *   （`docs/ARCHITECTURE.md` §3.1 / `docs/KNOWN-ISSUES.md` §3.3.5）。
+ *   `toRange` / `fromRange` / `toElement` 属渲染层，不在此处。
+ * - **不静默降级**：非法输入一律抛错，不得返回 `[[]]` 或 `index: null`
+ *   （`docs/KNOWN-ISSUES.md` §3.3.3）。
+ *
+ * 语法依据：EPUB CFI 规范 EBNF（idpf.org）——
+ *
+ * ```ebnf
+ * fragment = "epubcfi(" , ( path , [ range ] ) , ")" ;
+ * path     = step , local_path ;
+ * range    = "," , local_path , "," , local_path ;
+ * step     = "/" , integer , [ "[" , assertion , "]" ] ;
+ * offset   = ( ":" , integer ) , [ "[" , assertion , "]" ] ;
+ * assertion = ( ( value , [ "," , value ] ) | ( "," , value ) | ( parameter ) ) { parameter } ;
+ * ```
+ *
+ * 注意两个容易被忽略的点：
+ *
+ * 1. **`range` 恒为 2 个逗号** —— 范围是「父路径 + 起始子路径 + 结束子路径」的三元组。
+ *    「省略 start」的合法写法是 `epubcfi(P,,E)`（中间留空），**不是** 1 个逗号。
+ * 2. **断言分两类且位置不同** —— 元素步（偶数 index）上的断言是 **ID 断言**；
+ *    字符偏移（`:n`）后的断言是 **文本位置断言**。故 `id` 在 {@link CfiStep} 上，
+ *    而 `text` / `textAfter` 在 {@link CfiPoint} 上。
+ */
+/**
+ * 单个路径步骤（step）。
+ *
+ * CFI 路径形如 `/6/4[chap01ref]!/4[body01]/10[para05]/2/1:3[yyy]`，
+ * 按 `/` 切分后每个片段即一个 step。
+ */
+interface CfiStep {
+    /**
+     * 步骤索引。
+     *
+     * **奇偶有语义**：偶数指向子元素（含 `0` 与末尾虚拟元素），奇数指向字符数据块。
+     * 解析器不校验奇偶是否与真实文档树自洽 —— 那需要真实节点，属渲染层职责。
+     */
+    readonly index: number;
+    /**
+     * ID 断言，来自元素步的 `[chap01ref]`。
+     *
+     * 规范定位：出现在元素 step 之后，用于在位置漂移时按 ID 纠正目标位置。
+     * 排序/比较前必须逻辑上剥离（本模块不实现比较，仅保留原始信息）。
+     */
+    readonly id?: string;
+    /**
+     * side bias，来自参数 `;s=b`（before）或 `;s=a`（after）。
+     *
+     * 规范定位：**参数形式**，因此不参与 CFI 比较。
+     * 其他取值（非 `b` / `a`）抛 `FormatError`。
+     */
+    readonly side?: 'before' | 'after';
+}
+/**
+ * 一段路径：相邻两个 `!` 之间的部分。
+ *
+ * `!` 在 CFI 中表示 **indirection**（跳转进被引用的另一个文档），
+ * 因此一个 CFI 的路径是「段的序列」而非单一扁平数组。
+ */
+interface CfiPath {
+    /** 该段内的步骤，按出现顺序。至少一个。 */
+    readonly steps: readonly CfiStep[];
+}
+/**
+ * 单点 CFI。
+ *
+ * 例：`epubcfi(/6/4!/4/2/2:0)`
+ */
+interface CfiPoint {
+    readonly kind: 'point';
+    /** 按 `!` 分段的路径，至少一段。 */
+    readonly paths: readonly CfiPath[];
+    /** 字符偏移，来自末步之后的 `:3`。基于 UTF-16 码元，从 0 开始。 */
+    readonly offset?: number;
+    /**
+     * 文本断言的前导值，来自偏移后的 `[yyy]`。
+     *
+     * 表示期望出现在遇到点**之前**紧邻的子串（空白折叠后比较）。
+     */
+    readonly text?: string;
+    /**
+     * 文本断言的尾随值，来自 `[xx,y]` 或 `[,y]`。
+     *
+     * 表示期望出现在遇到点**之后**紧邻的子串。仅指定尾随值时写作 `[,y]`。
+     */
+    readonly textAfter?: string;
+    /** side bias，来自偏移后断言里的 `;s=b` / `;s=a`。 */
+    readonly side?: 'before' | 'after';
+    /**
+     * 规范化字符串，**含 `epubcfi()` 前缀**。
+     *
+     * 与 `serializeCfi()` 的返回值一致，便于下游直接使用而不必再序列化一次。
+     */
+    readonly value: string;
+}
+/**
+ * 范围 CFI。
+ *
+ * 规范（`range = "," , local_path , "," , local_path`）的两种合法写法：
+ *
+ * | 写法             | 语义                                                         | `parent`   |
+ * | ---------------- | ------------------------------------------------------------ | ---------- |
+ * | `epubcfi(P,S,E)` | 子路径拼接到父路径：`start = P+S`、`end = P+E`               | 非 `null`  |
+ * | `epubcfi(P,,E)`  | 起始子路径留空 → `start = P`（退化为父路径位置）、`end = P+E` | 非 `null`  |
+ *
+ * 另**有意接受一种简写**（登记于 `docs/API.md`「有意偏离规范之处」）：
+ *
+ * | 写法           | 本项目语义                                        | `parent` |
+ * | -------------- | ------------------------------------------------- | -------- |
+ * | `epubcfi(A,B)` | 仅 1 个逗号 → `start = A`、`end = B`（两条独立绝对路径） | `null`   |
+ *
+ * 简写形式按 EBNF 属**畸形输入**（`docs/KNOWN-ISSUES.md` FI-010 取证输入澄清）。
+ * 其语义定为「两条独立绝对路径」而非字面的 `epubcfi(A,,B)`，理由是后者会产出 `A+B`
+ * 的退化路径 —— 对 `scripts/refs/fi010-cfi-range.mjs` 的输入即 `/6/4!/4/2/2/6/4!/4/2/4`，
+ * 恰是基线错误输出的形状；而前者是唯一能让 `collapseCfi(range, true)` 产出有意义结果的解释。
+ *
+ * **省略 start 的范围是本项目的重点覆盖场景** —— 基线在此静默产出垃圾（FI-010）。
+ */
+interface CfiRange {
+    readonly kind: 'range';
+    /**
+     * 起点，**恒非空**。
+     *
+     * 规范形态下由「父路径 + 起始子路径」拼接而成；简写形式下即第一个路径。
+     * **始终是绝对路径** —— 消费方永远不需要自己做路径拼接。
+     */
+    readonly start: CfiPoint;
+    /** 终点，**恒非空**。与 `start` 口径一致（始终是绝对路径）。 */
+    readonly end: CfiPoint;
+    /**
+     * 规范形态的共同父路径；**仅 1 逗号简写形式为 `null`**。
+     *
+     * 存在是为保留原始书写形式以便精确回写（round-trip）：
+     * 非 `null` 时序列化输出 `epubcfi(P,S,E)` / `epubcfi(P,,E)`，
+     * `null` 时输出 `epubcfi(A,B)`。语义信息已完整包含在 `start` / `end` 中。
+     */
+    readonly parent: readonly CfiPath[] | null;
+    /** 规范化字符串，含 `epubcfi()` 前缀。 */
+    readonly value: string;
+}
+/**
+ * 解析后的 CFI。
+ *
+ * 用 `kind` 判别：
+ *
+ * ```ts
+ * const cfi = parseCfi(input);
+ * if (cfi.kind === 'range') {
+ *   // cfi.start / cfi.end 恒可用，无需判空
+ * }
+ * ```
+ */
+type Cfi = CfiPoint | CfiRange;
+
+export type { Cfi as C, CfiPath as a, CfiPoint as b, CfiRange as c, CfiStep as d };

package/dist/types-BH88rUYt.d.cts

@@ -0,0 +1,129 @@
+import { O as OperationOptions } from './types-DQYmArgv.cjs';
+
+/**
+ * ZIP 读取的类型定义（ADR-0007）。
+ *
+ * 设计约束：
+ * - **零依赖**：只用 `DataView` / `TextDecoder` / `DecompressionStream`，不用 `@zip.js/zip.js`
+ * - **零 DOM**：可在 Node / Worker / 浏览器一致运行（REQ-CORE-001）
+ * - **只读**：本模块不写入、不修改 ZIP，也不解压到磁盘
+ *
+ * 明确不支持（ADR-0007 的已知边界）：
+ * - ZIP64（>4 GB 条目）—— 检测到即抛 `FormatError`，**不静默按 32 位解析**
+ * - 加密条目 —— 属非目标（不做 DRM 解密）
+ * - 流式随机读 —— 当前一次性读入内存
+ */
+
+/**
+ * ZIP 压缩方法。
+ *
+ * 仅这两种在 EPUB 中合法（OCF 规范要求 `mimetype` 必须为 stored）。
+ * 其他方法（如 12 = bzip2、14 = LZMA）一律抛 `FormatError`。
+ */
+type ZipCompressionMethod = 0 | 8;
+/** ZIP 中央目录中的一个条目。 */
+interface ZipEntry {
+    /**
+     * 条目名，已按 UTF-8 解码，并**归一化到相对归档根的规范形**（FI-X22）。
+     *
+     * 规范化的规则与 `normalizeArchivePath`（`core/archive-path.ts`）**同一个函数**
+     * （该函数即查询键的产出者）：`\` → `/`、折掉 `.` 段与重复 `/`、去掉前导 `/`。因此
+     * `entries[].name`、`entry()` / `read()` 的索引键、EPUB / CBZ / FB2 解析出的路径
+     * 四处**不可能分叉** —— 曾分叉的形态是归档里存 `./META-INF/container.xml`
+     * 时，条目名列得出、读不出，且探测层直接判不出格式。
+     *
+     * 以 `/` 结尾表示目录条目 —— 那个结尾斜杠**只在目录条目上保留**：
+     * `probeZipContainer` 与 `collectCbzPages` 都按 `endsWith('/')` 排除目录，
+     * 把它一并折掉会让 `book.fb2/` 这种目录被当成正文。
+     *
+     * ⚠️ 归一化后**越出归档根**、**含控制字符**、或**规范化后为空**的名字不会出现在这里 ——
+     * 那三种在 `parseZip` 阶段就抛 `FormatError`（不留「存进去但取不出」的哑条目）。
+     */
+    readonly name: string;
+    /** 压缩方法。 */
+    readonly method: ZipCompressionMethod;
+    /** 压缩后字节数（取自中央目录）。 */
+    readonly compressedSize: number;
+    /** 解压后字节数（取自中央目录）。 */
+    readonly uncompressedSize: number;
+    /** 未压缩数据的 CRC-32 校验和。 */
+    readonly crc32: number;
+    /** 是否为目录条目（名字以 `/` 结尾）。目录条目无内容。 */
+    readonly isDirectory: boolean;
+}
+/** {@link parseZip} 的选项。 */
+interface ParseZipOptions {
+    /**
+     * 源标识，用于错误定位（REQ-EPUB-007）。
+     *
+     * 通常传文件名或 URL。失败时该值会出现在错误 message 中。
+     */
+    readonly source?: string;
+    /**
+     * **单个条目解压产物**的字节上限；超限即中止解压并抛 `ParseError`。
+     *
+     * 存在的理由：归档里的字节是不可信的，而 deflate 是**放大**通道 —— 实测 199 KB 的
+     * 压缩流可以解出 200 MB。中央目录声明的 `uncompressedSize` **也是文件说了算的数**，
+     * 拿它当校验依据只能事后拦（先物化、再比对），拦不住放大本身。
+     * 因此这里有两道：声明值的前置检查（拦「老实交代的大数」）+ 边解边数（拦「谎报小值」）。
+     *
+     * `stored`（未压缩）条目不受此上限约束 —— 其产物尺寸恒等于压缩尺寸，
+     * 而压缩尺寸已由「数据区间必须落在归档内」钉住，放大率天然是 1。
+     *
+     * @defaultValue 67108864（64 MiB）—— 本仓最大的合法单条目是 3.34 MB 的合成单章，
+     *   真实书最大章节约 2.9 MB，约 20 倍余量。
+     */
+    readonly maxEntrySizeBytes?: number;
+}
+/**
+ * 已解析的 ZIP 归档（只读视图）。
+ *
+ * 通过 {@link parseZip} 创建。实例持有原始字节，因此不要在归档存活期间修改
+ * 传入 `parseZip` 的那个 `Uint8Array`。
+ */
+interface ZipArchive {
+    /** 全部条目，按中央目录顺序。包含目录条目；**原文**重复名全部保留。 */
+    readonly entries: readonly ZipEntry[];
+    /**
+     * 按名字查条目。
+     *
+     * 查询键先走与条目名**同一个**归一化函数（FI-X22），于是 `a.png`、`./a.png`、
+     * `/a.png`、`a/./b.png` 这类写法指向同一个条目；目录条目的两个键
+     * （`images` 与 `images/`）也命中同一条。
+     *
+     * 原文重名时返回**最后一个**（ZIP 惯例：后写覆盖）。
+     * 「归一化后同名而原文不同」的两条不会走到这里 —— `parseZip` 已判红。
+     *
+     * @returns 匹配条目；不存在、**或查询键本身不是合法的归档内路径**（`''`、`'../x'`）时
+     * 返回 `undefined`。本方法**不抛错**。
+     */
+    entry(name: string): ZipEntry | undefined;
+    /**
+     * 读取并解压条目。
+     *
+     * - 返回**独立副本**，调用方修改它不会影响归档内的原始字节
+     * - 解压后校验 CRC-32 与长度，不匹配抛 `ParseError`
+     * - 对目录条目抛 `FormatError`
+     *
+     * @param name - 条目名（**先归一化再查**，规则见 {@link ZipEntry.name}；
+     *   大小写敏感，与 ZIP 内一致）。
+     * @param options - 取消信号。
+     * @throws {FormatError} 条目不存在、是目录、或压缩方法不支持。
+     *   查询键非法（`''`、`'../x'`）按**条目不存在**处理 —— 归档侧已保证不存在这类名字。
+     * @throws {ParseError} 数据损坏（CRC-32 或长度不匹配），**或解压产物超过
+     *   `parseZip` 的 `maxEntrySizeBytes`**。
+     * @throws {AbortError} 操作被取消。
+     */
+    read(name: string, options?: OperationOptions): Promise<Uint8Array>;
+    /**
+     * 读取条目并按 UTF-8 解码为文本。
+     *
+     * 用于 `META-INF/container.xml`、OPF、NAV 等 XML 资源。
+     * BOM 会被自动去除。
+     *
+     * @throws 同 {@link ZipArchive.read}。
+     */
+    readText(name: string, options?: OperationOptions): Promise<string>;
+}
+
+export type { ParseZipOptions as P, ZipArchive as Z, ZipCompressionMethod as a, ZipEntry as b };

package/dist/types-C-5eHSRH.d.ts

@@ -0,0 +1,379 @@
+import { O as OperationOptions } from './types-DQYmArgv.js';
+
+/**
+ * 可注入的字节源与资源加载抽象（REQ-CORE-005）。
+ *
+ * 通过实现这些接口，宿主可以接入任意存储后端（内存、OPFS、远端分片、加密容器），
+ * core 无需感知网络与文件系统差异 —— 测试里因此可以注入纯内存实现，
+ * **不触碰网络与文件系统**。
+ *
+ * 本模块属于 `frond-js/core`，**不得依赖 DOM，也不得依赖 render / reader**
+ * （ARCHITECTURE §1 依赖方向单向，H4）。
+ */
+
+/**
+ * 可注入的字节源抽象。
+ *
+ * 实现者必须满足以下契约（`createMemoryBookSource` 是内置参考实现）：
+ *
+ * 1. **区间语义**：`read({ start, end })` 返回覆盖**闭开区间** `[start, end)`
+ *    的字节，长度恒为 `end - start`；`[0, 0)` 是合法输入，返回零长度数组。
+ * 2. **取消（H6 / H7）**：`options.signal` 已 abort 时必须抛 `AbortError`，
+ *    **且不得返回任何字节**。
+ * 3. **关闭后不可读**：`close()` 之后调用 `read` 必须抛 `StateError`
+ *    —— 「已释放」与「读到空数据」是两回事，静默返回空会让缺陷延后暴露。
+ * 4. **区间越界即报错**：越界、起止倒置、非整数一律抛 `FormatError`，
+ *    **不截断、不补齐**（对照 FI-005 的「不静默降级」）。
+ */
+interface BookSource {
+    /** 总字节数；未知时为 `null`。 */
+    readonly size: number | null;
+    /**
+     * 按需读取指定字节区间。
+     *
+     * @param range 闭开区间 `[start, end)`
+     * @param options 取消信号
+     * @throws {AbortError} 操作被取消
+     * @throws {StateError} 源已 `close()`
+     * @throws {FormatError} 区间非法（越界 / 起止倒置 / 非整数）
+     */
+    read(range: {
+        readonly start: number;
+        readonly end: number;
+    }, options?: OperationOptions): Promise<Uint8Array>;
+    /** 释放底层资源。必须幂等（重复调用不抛错）。 */
+    close(): void;
+}
+/**
+ * 书内资源的加载抽象（图片、样式、字体等）。
+ *
+ * 与 {@link BookSource} 的分工：`BookSource` 面向**整本书的字节流**（可按偏移随机读），
+ * `ResourceIO` 面向**书内已定位的资源**（按 `href` 取整块）。
+ *
+ * ## 契约（自 T2.8 起生效）
+ *
+ * 1. **`href` 是归档路径**，不是相对路径、也不是 URL —— 相对引用的解析由渲染层
+ *    按「引用所在文档」完成（`core/archive-path`），实现方拿到的已经是可直接查表的形式。
+ * 2. **取不到时抛 `FormatError`**（不是返回空、也不是 `undefined`）—— 「归档里没有
+ *    这个条目」与「读到了零字节」是两回事，静默返回空会把缺陷延后到「图片不显示」才暴露。
+ *    ⚠️ 与 `ResourceLoader` 的分工正在此处：后者用 `undefined` 表示「没有」，
+ *    适配层负责把 `FormatError` 翻译成 `undefined`（见 `src/reader/reader.ts`）。
+ * 3. **只对内置默认渲染器生效**：调用方自备 `renderer` 时，`Reader` **不**透传 `io`
+ *    —— `Renderer` 契约里没有承载资源来源的位置，「谁渲染、谁负责取资源」。
+ * 4. **只管书内资源，不管章节**：章节是 XML 文本，走归档的 `readText`
+ *    （自带 UTF-8 解码与 BOM 处理），不经过这里。
+ *
+ * 存在的意义是让宿主接远端分片或加密容器（见本模块头部）。
+ */
+interface ResourceIO {
+    /**
+     * 读取指定资源对应的字节。
+     *
+     * @param href **归档路径**（如 `OPS/images/cover.png`）
+     * @param options 取消信号
+     * @throws {AbortError} 操作被取消（H6 / H7）
+     * @throws {FormatError} 归档里没有这个路径
+     */
+    load(href: string, options?: OperationOptions): Promise<Uint8Array>;
+}
+/** {@link createMemoryBookSource} 的选项。 */
+interface MemoryBookSourceOptions {
+    /**
+     * 源标识，**仅用于错误 message**，便于定位是哪个源出的问题
+     * （与 `ParseZipOptions.source` 同口径）。缺省为 `'<anonymous>'`。
+     */
+    readonly source?: string;
+}
+/**
+ * 用一段已有字节造一个内存 {@link BookSource}（REQ-CORE-005 的内置参考实现）。
+ *
+ * 用途：让宿主（尤其**测试**）在不触碰网络与文件系统的前提下注入字节源 ——
+ * REQ-CORE-005 的验收标准「测试中可注入内存 IO，无需网络」正是由它满足。
+ *
+ * 两处刻意的实现选择：
+ *
+ * - **零复制**：`read` 返回 `subarray` 视图而非副本，与 T1.8「`archive` 不复制字节」
+ *   同一口径。代价是调用方修改返回的数组会穿透到底层字节 —— 需要隔离时请自行传入副本。
+ * - **`close()` 有实义**：关闭后 `read` 抛 `StateError`，而不是静默返回空数组。
+ *   「已释放」与「读到空数据」是两回事，静默返回空会让缺陷延后到很难定位的地方。
+ *
+ * @param bytes - 底层字节。**不被复制**，返回的源持有其视图。
+ * @param options - 仅 `source`（错误 message 用的标签）。
+ */
+declare function createMemoryBookSource(bytes: Uint8Array, options?: MemoryBookSourceOptions): BookSource;
+
+/**
+ * 通用书籍模型（`frond-js/core`）。
+ *
+ * 这是**跨格式契约**：EPUB、FB2、CBZ、MOBI 最终都产出同一个 `Book`，
+ * 渲染层与 Reader 只面向本模型编程，不感知格式差异
+ * （ARCHITECTURE §1 / §3.4 的数据流终点）。
+ *
+ * 设计约束：
+ * - **只读**：模型一旦产出即不可变，禁止渲染层反向修改
+ * - **零 DOM、零运行时依赖**（H4 / H12）
+ * - 本文件**只有类型**，不产生运行时代码，因此不计入覆盖率分母
+ */
+/**
+ * 出版元数据。字段口径见 T1.5 决策 + **FI-X38 修订**（2026-09-22）：三个字段**类型上恒为 `string`**
+ * （无来源就给空串，不改成可选）；而「**缺了就拒开**」只适用于该格式既有判据本就要求它的场合 ——
+ * EPUB 的 `dc:identifier`、FB2 的 `document-info/id` 判红不变；MOBI 的 EXTH 104（ISBN）/ 113（ASIN）
+ * 是 **Kindle 产物**、规范不要求 ⇒ 缺失给 `""`（**不再拒开**）；PDF / CBZ 本无标识符来源 ⇒ 恒 `""`。
+ * ⚠️ 三条不变：不拿 PalmDB 名 / 文件名顶替标识符（那是造假不是回退）；`creators` 仍非必填；
+ * `title` 在 MOBI 侧仍要求「EXTH 503 与完整书名至少有一个」。
+ */
+interface BookMetadata {
+    /** `dc:title`。EPUB 3 要求至少一个，取**第一个**。 */
+    readonly title: string;
+    /** 全部 `dc:creator`，按文档顺序。可为空数组（创作者非必填）。 */
+    readonly creators: readonly string[];
+    /** `dc:language`。EPUB 3 要求至少一个，取**第一个**。 */
+    readonly language: string;
+    /** `dc:identifier`（优先取 `unique-identifier` 指向的那条）。 */
+    readonly identifier: string;
+    /**
+     * `dcterms:modified`。
+     *
+     * ⚠️ EPUB 3 规范要求该字段，但真实文件常缺失。缺失**不报错**（T1.5 决策）：
+     * 为合规而拒掉现实中能正常阅读的书，代价高于收益。
+     */
+    readonly modified?: string;
+}
+/** manifest 中的一个资源条目。 */
+interface ManifestItem {
+    /** `id`。在同一个 OPF 内必须唯一。 */
+    readonly id: string;
+    /**
+     * `href`，**已相对 OPF 所在目录规范化**（不含前导 `/`，可直接交给归档读取层）。
+     *
+     * 有意处理：`#` 之后的 fragment 被剥离（manifest href 的 fragment 无意义，
+     * 保留会导致资源读取失败）；**不做**百分号解码（ZIP 条目名本身不编码）。
+     */
+    readonly href: string;
+    /** `media-type`。 */
+    readonly mediaType: string;
+    /**
+     * `properties`，按空白拆分后的数组。
+     *
+     * EPUB 3 的 `nav`、`scripted`、`svg` 等标记在此。EPUB 2 无该属性 → 空数组。
+     */
+    readonly properties: readonly string[];
+}
+/** spine 中的一个阅读顺序项。 */
+interface SpineItem {
+    /** `idref`，指向 manifest 条目。 */
+    readonly idref: string;
+    /** `linear`：`false` 表示 `linear="no"`（辅助内容，如封面、版权页）。默认 `true`。 */
+    readonly linear: boolean;
+    /** 在 spine 中的顺序，从 0 开始。 */
+    readonly index: number;
+    /** 已解析的 manifest 条目。**解析期已校验存在性**，调用方无需再查表。 */
+    readonly item: ManifestItem;
+}
+/**
+ * 目录中的一个条目。
+ *
+ * **跨格式契约**：EPUB（NAV / NCX）、FB2（`<section>` 嵌套标题）、
+ * MOBI（索引）最终都产出同一模型，渲染层与 Reader 只面向它编程。
+ *
+ * 与 {@link ManifestItem} 的关系：两者的 `href` **口径一致** —— 都**不含** fragment。
+ * 目录项多出来的 fragment 单独成字段，因此 `href` 可以直接交给归档读取层，
+ * 调用方不必再判断「这个 href 要不要拆」。这是 T1.6 的取舍：
+ * 拆解在**解析时做一次**，而不是让每个消费方各拆一次。
+ */
+interface TocItem {
+    /** 显示文本。取源文档原文（仅折叠两侧空白）。 */
+    readonly label: string;
+    /**
+     * 目标文档在归档内的路径，**已规范化且不含 fragment**。
+     *
+     * 相对链接按**引用它的文档**（NAV / NCX 文件）所在目录解析。
+     * 该目录通常与 OPF 同目录，此时等价于 {@link Book.basePath}。
+     */
+    readonly href: string;
+    /**
+     * `#` 之后的定位信息，**不含 `#`**。无 fragment（或 fragment 为空串）时该字段不存在。
+     *
+     * 内容可能是元素 id（`"s2"`）、EPUB CFI（`"epubcfi(/6/4!/4/2)"`）—— 本模型**不解释**它，
+     * 交由 CFI 解析（`src/core/cfi/**`）与渲染层按需处理。
+     *
+     * ✅ **MOBI 的两个版本都已收编为元素 id**（MOBI6 见 T3.2b ④，KF8 见 T3.2b ③b）：
+     *
+     * - **MOBI6**：正文是**单个** HTML 文档，目录靠 `guide` 的 `<reference type="toc" filepos=N>`
+     *   指向**目录页**，目录页里的锚点又是 `<a filepos=N>` —— `N` 是**字节**偏移（不是字符下标）。
+     *   `openMobi` 先用 `shiftOffset` 把它换算到改写后的空间，再在目标开标签上**就地**
+     *   注入 `id="mobi-toc-N"`（`src/formats/mobi/anchors.ts`）⇒ 本字段拿到的是**元素 id**。
+     *   落点不是开标签时**保留原字节偏移字符串**（降级，不抛错）⇒ 那一条仍定位不到。
+     * - **KF8**：目录数据来自 **INDX 表**（不是正文超链接）。`parseKf8Toc` 把
+     *   `insertpos + off − skelpos(章)` 换算成全局 `flow[0]` 偏移，再在**重写之前**的章节字节里
+     *   反搜最近的 `id=` / `name=` ⇒ 本字段拿到的是**元素 id**（`src/formats/mobi/kf8toc.ts`）。
+     *   反搜不到时该字段**不写**（而非写空串）。
+     *
+     * ⇒ **消费方不要把 `fragment` 无条件当元素 id 用**：取不到就只是「定位不到」，
+     * 而不是「文档有问题」。形态只剩**两种**（元素 id / CFI 字符串），
+     * 判据是**前缀**（见 `src/reader/navigation.ts` 的 `locationForTocItem`）。
+     */
+    readonly fragment?: string;
+    /** 子条目，按文档顺序。无子项时为空数组。 */
+    readonly children: readonly TocItem[];
+}
+/**
+ * 支持的书籍格式。**`Book` 的判别字段**（T3.0.2 / ADR-0014 新增）。
+ *
+ * 有了它，调用方不必靠「哪些字段是 `undefined`」反推拿到的是什么格式。
+ */
+type BookFormat = 'epub' | 'fb2' | 'mobi' | 'cbz' | 'pdf';
+/**
+ * 书级**阅读方向**（D-7 新增）—— {@link Book.direction} 的取值。
+ *
+ * ## 为什么不含 `'default'`
+ *
+ * EPUB 的 `spine@page-progression-direction` 合法值是 `ltr` / `rtl` / `default`，
+ * 而 `default` 的语义是「**没有声明方向**」。把它收进类型会让每个消费方都要处理
+ * 一个「第三种方向」，而它其实等价于「没有值」⇒ 解析时直接映射为 `undefined`，
+ * 本类型只留两个**真的方向**。
+ *
+ * ## 与 CSS `direction` 的关系
+ *
+ * 消费方把它写成内容文档的 `<html dir="…">`，浏览器据此映射出 CSS `direction`
+ * （`src/render/default/sandbox.ts`）。⚠️ 它是**书的元数据**，与 `paginator.ts`
+ * 从 `getComputedStyle()` 读到的**计算值**是两件事 —— 后者是前者的下游结果。
+ */
+type ReadingDirection = 'ltr' | 'rtl';
+/**
+ * 通用资源条目（跨格式）。
+ *
+ * **EPUB 的 {@link ManifestItem} 是它的超集**（多 `id` 与 `properties`）——
+ * 非 OPF 格式（CBZ 的图片序列、MOBI 的记录表）只需给出「归档内路径 + 媒体类型」。
+ */
+interface ResourceItem {
+    /** 归档内路径，**已规范化**（口径同 {@link ManifestItem.href}）。 */
+    readonly href: string;
+    /** 媒体类型。 */
+    readonly mediaType: string;
+}
+/**
+ * 通用阅读顺序条目（跨格式）。
+ *
+ * **EPUB 的 {@link SpineItem} 是它的超集**（多 `idref` / `index` / 已解析的 `item`）。
+ */
+interface ChapterItem {
+    /** 归档内路径，**已规范化**（口径同 {@link ManifestItem.href}）。 */
+    readonly href: string;
+    /** 媒体类型。 */
+    readonly mediaType: string;
+    /** 是否属主阅读顺序（EPUB 的 `linear="no"` 对应 `false`）。 */
+    readonly linear: boolean;
+}
+/**
+ * 一本已解析的书。
+ *
+ * 数据流（规格 §3）：
+ * `BookInput/BookSource → ZIP → container.xml → OPF → metadata + manifest + spine
+ *  → NAV or NCX → Book + CFI → Renderer → Reader`
+ *
+ * ## 字段分层（T3.0.2 / ADR-0014）
+ *
+ * `Book` 是**跨格式契约**，但字段里混着两套口径，现显式分层：
+ *
+ * | 层            | 字段                                                                   | 非 OPF 格式下的取值             |
+ * | ------------- | ---------------------------------------------------------------------- | ------------------------------- |
+ * | **通用**      | `format` / `metadata` / `resources` / `chapters`                       | **必须有值**                    |
+ * | **通用（可选）** | `direction`                                                          | **不存在**（`undefined`）       |
+ * | **EPUB 专属** | `opfPath` / `basePath`                                                 | **不存在**（`undefined`）       |
+ * | **EPUB 专属** | `manifest` / `spine` / `manifestIndex` / `tocItem` / `ncxPath`         | 空数组 / 空 `Map` / `undefined` |
+ *
+ * ⚠️ **「本格式没有这个概念」≠「解析失败」** —— 前者是**如实为空**，后者抛错。
+ *
+ * ### 可选化的判据：该字段的「没有」**有没有诚实的空值**（T3.2a 定稿）
+ *
+ * - `opfPath` / `basePath`：**没有**。填 `''` 会被读成「OPF 在归档根目录」，
+ *   那是**假信息** —— 非 OPF 格式根本没有 OPF。故改为可选：`undefined`
+ *   表示「本格式没有 OPF 这个概念」，与「解析失败」区分开。
+ * - `manifest` / `spine` / `manifestIndex`：**有**。`[]` / `new Map()` 直白地
+ *   表示「没有条目」，不指认任何具体位置，故保持必填、取空值。
+ *
+ * ⚠️ **`spine` 保持必填**另有一条独立理由：`reader/` 仍有一处读它 ——
+ * `spineIndexFromCfi`，因为 CFI 的 `/6/2n` 描述的就是 **EPUB package 文档内**的
+ * 位置，本就是 OPF 概念（非 OPF 格式收到 CFI 报 `FormatError` 是**诚实**的）。
+ * **导航面（定位 / 翻页）自 T3.2a 起读 `chapters`**（`reader/navigation.ts`），
+ * 非 OPF 格式因此可读 —— 这条由 `tests/reader/navigation.test.ts` 守住。
+ */
+interface Book {
+    /**
+     * 本 `Book` 的来源格式（**判别字段**）。
+     *
+     * **必填**：EPUB 解析器产出 `'epub'`；后续 FB2 / CBZ / MOBI / PDF 适配器各自产出自己的值。
+     */
+    readonly format: BookFormat;
+    readonly metadata: BookMetadata;
+    /**
+     * 通用资源表，按文档顺序。
+     *
+     * EPUB 下由 {@link manifest} **派生** —— 由**同一个函数**产出（ADR-0014 的「单一事实来源」）。
+     */
+    readonly resources: readonly ResourceItem[];
+    /**
+     * 通用阅读顺序，按阅读顺序。
+     *
+     * EPUB 下由 {@link spine} **派生**：`chapters[i].href === spine[i].item.href`
+     * 由单测**逐项断言**守住 —— **不靠约定靠断言**（同 ADR-0008 的「唯一写入点」思路）。
+     */
+    readonly chapters: readonly ChapterItem[];
+    /**
+     * 书级阅读方向（`ltr` / `rtl`）。**未声明时为 `undefined`**（D-7 新增）。
+     *
+     * 唯一来源是 EPUB 的 `spine@page-progression-direction`（`formats/epub/opf.ts`）：
+     * `ltr` / `rtl` 原样取值，`default` 与**任何非法值**都映射为 `undefined`
+     * —— 「非法方向 = 没有方向」，与 `spine@toc` 悬空时 `ncxPath` 置空同一口径
+     * （T1.5 对**可选线索**的处置：不因一个可选线索有瑕疵就拒掉整本能读的书）。
+     *
+     * ⚠️ **它是「书的元数据」，不是「内容文档的排版结果」**：消费方（渲染层）把它写成
+     * `<html dir="…">`，浏览器再据此得出 CSS `direction`。`paginator.ts` 读的是后者
+     * （计算值）—— 两者不在同一层，别把这里的值当成排版事实。
+     *
+     * ⚠️ **竖排（`writing-mode: vertical-rl`）不在本字段的表达范围内**：那是 CSS 的事，
+     * 由书籍自己的样式表声明，`Book` 不解析样式表（详见 `paginator.ts` 的镜像轴说明）。
+     */
+    readonly direction?: ReadingDirection;
+    /**
+     * package document（OPF）在归档内的路径。**非 OPF 格式下不存在**（T3.2a 可选化）。
+     *
+     * ⚠️ **与 `spine` 的取舍相反**（那里刻意保持必填）：`spine` 的「没有」有**诚实的空值**
+     * （空数组，语义是「没有阅读顺序项」）；而 `opfPath` 的「没有」**没有** ——
+     * 填 `''` 会被读成「OPF 在归档根目录」，那是**假信息**。
+     * 因此这里可选：`undefined` 表示「本格式没有 OPF 这个概念」，与「解析失败」区分开。
+     */
+    readonly opfPath?: string;
+    /**
+     * OPF 所在目录，用于解析书内其他相对引用。根目录时为 `''`。
+     *
+     * **非 OPF 格式下不存在**（理由同 {@link opfPath}）。
+     */
+    readonly basePath?: string;
+    /** 全部 manifest 条目，按文档顺序。 */
+    readonly manifest: readonly ManifestItem[];
+    /** 全部 spine 项，按阅读顺序（`index` 递增）。 */
+    readonly spine: readonly SpineItem[];
+    /**
+     * 按 `id` 索引的 manifest，用于 O(1) 查找。
+     *
+     * 键与 {@link manifest} 中的条目一一对应。**重复 id 在解析期即抛错**，
+     * 因此这里不会出现覆盖。
+     */
+    readonly manifestIndex: ReadonlyMap<string, ManifestItem>;
+    /**
+     * EPUB 3 的导航文档条目（manifest 中 `properties` 含 `nav` 者）。
+     *
+     * 仅**识别**，不解析 —— 目录解析属 T1.6。
+     */
+    readonly tocItem?: ManifestItem;
+    /**
+     * EPUB 2 的 NCX 路径（已规范化，相对归档根），来自 `spine@toc`。
+     *
+     * 仅**识别**，不解析 —— 目录解析属 T1.6。
+     */
+    readonly ncxPath?: string;
+}
+
+export { type BookSource as B, type ChapterItem as C, type ManifestItem as M, type ResourceIO as R, type SpineItem as S, type TocItem as T, type Book as a, type BookFormat as b, type BookMetadata as c, type MemoryBookSourceOptions as d, type ReadingDirection as e, type ResourceItem as f, createMemoryBookSource as g };