frond-js 0.4.0

package/dist/core/index.d.cts

@@ -0,0 +1,321 @@
+export { A as AbortError, F as FormatError, a as FrondError, b as FrondErrorCode, c as FrondErrorOptions, N as NetworkError, P as ParseError, S as SecurityError, d as StateError, e as createAbortError, i as isAbortError, f as isFrondError, l as linkSignals, o as onAbort, t as throwIfAborted } from '../abort-BY8vBk0v.cjs';
+import { P as ParseZipOptions, Z as ZipArchive } from '../types-BH88rUYt.cjs';
+export { a as ZipCompressionMethod, b as ZipEntry } from '../types-BH88rUYt.cjs';
+export { O as OperationOptions } from '../types-DQYmArgv.cjs';
+export { a as Book, b as BookFormat, c as BookMetadata, B as BookSource, C as ChapterItem, M as ManifestItem, d as MemoryBookSourceOptions, e as ReadingDirection, R as ResourceIO, f as ResourceItem, S as SpineItem, T as TocItem, g as createMemoryBookSource } from '../types-CPUqTEPW.cjs';
+import { C as Cfi } from '../types-B7mslPBY.cjs';
+export { a as CfiPath, b as CfiPoint, c as CfiRange, d as CfiStep } from '../types-B7mslPBY.cjs';
+
+/**
+ * XML 解析的类型定义（ADR-0006）。
+ *
+ * 设计约束：
+ * - **不实现完整 DOM**，只覆盖 EPUB 所需的受控子集（`container.xml` / OPF / NAV / NCX / SMIL）
+ * - **零 DOM、零运行时依赖**（H4 + H12），因此不使用 `DOMParser` 等平台 API
+ * - **命名空间只做前缀分离**，不做完整的 URI 解析与校验 —— EPUB 场景下按 `localName` 查找已足够
+ *
+ * 与标准 DOM 的差异是**有意的**：本模块产出的是解析结果，不是可变的活文档。
+ * 所有字段均为 `readonly`，调用方无法通过它修改文档结构。
+ */
+/** 文本节点。 */
+interface XmlText {
+    readonly type: 'text';
+    /** 文本内容。非 CDATA 段已完成实体解码。 */
+    readonly value: string;
+    /**
+     * 是否来自 CDATA 段。
+     *
+     * CDATA 内容**不做**实体解码（`&` 保持字面量），因此需要与普通文本区分。
+     */
+    readonly cdata: boolean;
+}
+/** 元素节点。 */
+interface XmlElement {
+    readonly type: 'element';
+    /** 原始标签名，含前缀。例如 `dc:title`。 */
+    readonly name: string;
+    /** 命名空间前缀。无前缀时为空字符串。 */
+    readonly prefix: string;
+    /** 去掉前缀的标签名。例如 `title`。查询请优先使用本字段。 */
+    readonly localName: string;
+    /**
+     * 属性表：原始属性名 → 属性值。
+     *
+     * - 键含前缀，例如 `xmlns:dc`、`full-path`
+     * - 值已完成实体解码
+     * - 保持文档中的出现顺序
+     */
+    readonly attributes: ReadonlyMap<string, string>;
+    /** 子节点，按文档顺序。 */
+    readonly children: readonly XmlNode[];
+}
+/** XML 节点。 */
+type XmlNode = XmlElement | XmlText;
+/** 解析选项。 */
+interface ParseXmlOptions {
+    /**
+     * 源标识，用于错误定位（REQ-EPUB-007）。
+     *
+     * 通常传入文件路径或条目名，例如 `META-INF/container.xml`。
+     * 解析失败时该值会出现在 `ParseError.message` 中。
+     */
+    readonly source?: string;
+    /**
+     * **元素**嵌套层数上限，根元素算第 1 层。
+     *
+     * 存在它只有一个理由：XML 解析是递归下降的，而输入**来自陌生人给的文件** ⇒
+     * 不设上限时「10 KB 的 `<n><n><n>…`」会把宿主进程拖进 `RangeError: Maximum call
+     * stack size exceeded` —— 那是**引擎崩溃**，不是「这本书解析失败」，既不返回给调用方
+     * （绕过 `FrondError` 体系），也救不回同一线程上别的书。
+     *
+     * 超限抛 `ParseError`，**发生在读到越界的那个开始标签时**（不等闭合标签）。
+     * 兄弟节点与自闭合元素不增加深度，故大量同层节点不受影响。
+     *
+     * @defaultValue 512 —— 真实 XHTML 章节的常见深度在两位数以内，本仓最深的用例是 300 层，
+     *   512 留了约 5 倍余量。
+     */
+    readonly maxDepth?: number;
+}
+
+/**
+ * 极简 XML 解析器（ADR-0006）。
+ *
+ * 设计取舍：
+ * - **单遍扫描**，不做 token 预切分；用 `charCodeAt` 判断而非正则，避免回溯
+ * - **不实现完整 DOM**：无命名空间 URI 解析、无 DTD 校验、无外部实体
+ * - **不静默降级**：任何非法结构一律抛 `ParseError`（对照 FI-005）
+ * - **递归深度有上限**：默认 512 层（`options.maxDepth`），超限同样抛 `ParseError` ——
+ *   输入是不可信文件，不设上限就是让一本畸形书有机会以 `RangeError` 打挂宿主进程
+ * - **零 DOM**：只用字符串操作，可在 Node / Worker / 浏览器一致运行
+ *
+ * 规范子集（EPUB 实际需要）：
+ * - XML 声明、DOCTYPE（含 PUBLIC 与内部子集，均跳过不解析）
+ * - 注释、处理指令（跳过）
+ * - CDATA（保留原文，不解码实体）
+ * - 元素 / 属性 / 文本、自闭合元素
+ * - 5 个预定义实体 + 十进制 / 十六进制字符引用
+ * - 换行规范化（XML 1.0 §2.11）：字面 CRLF、CR → LF；字符引用产生的 CR 不受影响
+ *
+ * 有意偏离规范之处（宽容处理，便于兼容真实世界文件）：
+ * - 结束标记允许尾随空白，如 `</a >`
+ * - 未识别实体与非法字符引用按字面量保留，而非报错
+ */
+
+/**
+ * 解析 XML 文本。
+ *
+ * 文档必须恰好包含一个根元素。解析失败时抛 {@link ParseError}，
+ * message 中包含 `options.source` 与出错偏移量，便于定位（REQ-EPUB-007）。
+ *
+ * @param source - XML 文本。
+ * @param options - 解析选项；`source` 用于错误定位，`maxDepth` 限定嵌套层数。
+ * @returns 根元素。
+ * @throws {ParseError} 文档结构非法，**或嵌套超过 `maxDepth`**（默认 512 层）——
+ *   后者是有意为之：不设上限时畸形文档会以 `RangeError` 打挂宿主进程，而不是「解析失败」。
+ */
+declare function parseXml(source: string, options?: ParseXmlOptions): XmlElement;
+
+/**
+ * XML 节点查询辅助。
+ *
+ * 这些函数是纯遍历，不修改文档。查询一律基于 `localName`，
+ * 忽略命名空间前缀 —— 对 EPUB 的 OPF / NAV / NCX 而言这已足够
+ * （见 ADR-0006 的取舍说明）。
+ */
+
+/**
+ * 按 `localName` 深度优先查找全部匹配元素。
+ *
+ * 匹配范围为 `root` 的**后代**，不含 `root` 自身。
+ *
+ * @param root - 查找起点。
+ * @param localName - 目标标签名（不含前缀）。
+ * @returns 按文档顺序排列的匹配元素；无匹配时为空数组。
+ */
+declare function findAll(root: XmlElement, localName: string): XmlElement[];
+/**
+ * 按 `localName` 查找首个匹配元素。
+ *
+ * @returns 首个匹配元素；无匹配时返回 `undefined`。
+ */
+declare function findFirst(root: XmlElement, localName: string): XmlElement | undefined;
+/**
+ * 读取元素属性。
+ *
+ * @param element - 目标元素。
+ * @param name - 属性名，**含前缀**（如 `xmlns:dc`）。
+ * @returns 属性值；属性不存在时返回 `undefined`。
+ */
+declare function getAttribute(element: XmlElement, name: string): string | undefined;
+/**
+ * 递归拼接元素的全部后代文本。
+ *
+ * CDATA 段的内容同样计入。不做空白规范化 —— 需要时由调用方处理。
+ *
+ * @returns 拼接后的文本；无文本节点时返回空字符串。
+ */
+declare function getText(element: XmlElement): string;
+/** 判断节点是否为元素。 */
+declare function isElement(node: XmlNode): node is XmlElement;
+
+/**
+ * ZIP 读取器（ADR-0007）。
+ *
+ * 实现策略：
+ * - **只信中央目录**：条目尺寸一律取自 central directory，忽略 local header 中的值。
+ *   流式写入的 ZIP（bit 3 = data descriptor）其 local header 尺寸恒为 0，因此不可信。
+ * - **单遍定位 EOCD**：从尾部倒扫，并用「注释长度必须恰好补齐文件末尾」校验，
+ *   避免把注释区里偶然出现的 EOCD 签名字节误判为记录头。
+ * - **不静默降级**：结构损坏抛 `ParseError`，不支持的特性抛 `FormatError`（对照 FI-005）。
+ * - **条目名与查询键同一个函数产出**（FI-X22）：中央目录里的名字在**解析那一刻**就送
+ *   `normalizeArchivePath` 归一化，因此 `entries[].name`、探测层看到的名字、
+ *   `entry()` / `read()` 的索引键与调用方传进来的路径**是同一份口径**。
+ *
+ * 已知边界（ADR-0007）：不支持 ZIP64 与加密条目 —— 检测到即抛错，不按 32 位误解析。
+ */
+
+/**
+ * 解析 ZIP 归档。
+ *
+ * 只读取中央目录，不解压任何条目 —— 解压发生在 {@link ZipArchive.read}。
+ *
+ * @param bytes - 完整 ZIP 字节。归档存活期间不要修改它。
+ * @param options - `source` 用于错误定位；`maxEntrySizeBytes` 限定单个条目的解压产物。
+ * @returns 只读归档视图。条目名已归一化（见 {@link ZipEntry.name}）。
+ * @throws {ParseError} 结构损坏（EOCD 缺失、签名错、偏移越界）。
+ * @throws {FormatError} 不支持的特性（压缩方法非 0/8、加密、ZIP64），**或条目名不是合法的
+ *   归档内路径 / 两条条目名归一化后互相歧义**（FI-X22）。
+ */
+declare function parseZip(bytes: Uint8Array, options?: ParseZipOptions): ZipArchive;
+
+/**
+ * 归档内路径解析。
+ *
+ * 这是**跨格式能力**：EPUB 的 rootfile `full-path`、manifest `href`，
+ * 以及 P3 的 FB2 / CBZ 资源定位都要用同一套规则，因此归 `core` 而非某个格式包
+ * （ARCHITECTURE §1 划分判据：若多种格式都要用则属 core）。
+ *
+ * 统一口径（FI-X22 起，本模块是归档路径的**唯一**归一化点）：
+ * - `\` 归一化为 `/`
+ * - 忽略空段与 `.` 段
+ * - `..` 仅在归档根目录之内回退；越界即抛 `FormatError`（防目录穿越）
+ * - **不做**百分号解码（ZIP 条目名本身不编码，解码会指向不存在的条目）
+ * - 拒绝空路径、规范化后为空的路径、控制字符
+ *
+ * 消费者（全部走同一份规则）：`core/zip/parse.ts` 的**条目名**（FI-X22 起，
+ * 在解析中央目录那一刻就送进来，故 `entries[].name` 与查询键不可能分叉）、
+ * EPUB 的 `container.ts` / `opf.ts` / `nav.ts`，以及渲染层的 `resources.ts`。
+ *
+ * 全部失败抛 `FormatError` —— 路径非法属「不符合规范」，而非「数据损坏」。
+ *
+ * 本模块零 DOM、零运行时依赖（H4 / H12）。
+ */
+/** 路径解析的上下文，仅用于生成可定位的错误消息（REQ-EPUB-007）。 */
+interface ArchivePathOptions {
+    /** 源标识，通常是文件名或 URL。 */
+    readonly source?: string;
+    /**
+     * 该路径在文档中的语义名，用于错误消息，例如 `rootfile 的 full-path`、`manifest href`。
+     *
+     * @defaultValue `'归档路径'`
+     */
+    readonly label?: string;
+}
+/**
+ * 把归档内路径规范化到「相对归档根」的绝对形式。
+ *
+ * @param rawPath - 原始路径，可含前导 `/`、`\`、`.` 与 `..`。
+ * @param options - 错误消息上下文。
+ * @returns 规范化后的路径，**不含前导 `/`**。
+ * @throws {FormatError} 路径为空、规范化后为空、含控制字符、或 `..` 越出归档根。
+ *
+ * @example
+ * ```ts
+ * normalizeArchivePath('/OPS/./package.opf'); // 'OPS/package.opf'
+ * normalizeArchivePath('OPS\\a.opf');          // 'OPS/a.opf'
+ * normalizeArchivePath('OPS/../../a.opf');     // throws FormatError
+ * ```
+ */
+declare function normalizeArchivePath(rawPath: string, options?: ArchivePathOptions): string;
+/**
+ * 相对基准目录解析一个 href。
+ *
+ * @param basePath - 基准目录（**不含**文件名），例如 OPF 所在目录 `'OPS'`。空串表示归档根。
+ * @param href - 待解析的引用，可含前导 `/`（视为相对归档根的绝对路径）。
+ * @param options - 错误消息上下文。
+ * @returns 规范化后的归档内路径，**不含前导 `/`**。
+ * @throws {FormatError} href **不是相对引用**（带 scheme、协议相对 `//…`、或纯 fragment）、
+ *   href 未指名任何条目、或解析结果越出归档根。
+ *
+ * ⚠️ 「必须是相对引用」这条判据立在**解析引用**这一侧，**不**立在
+ * {@link normalizeArchivePath} 那一侧 —— 后者现在还服务 ZIP 的**条目名**归一化
+ * （FI-X22 / 批次 E-8），而 `a:b.png` 这类带冒号的文件名在归档里完全合法（POSIX 允许 `:`）。
+ * 把 scheme 判据塞进归一化，等于让一整本档案因为一个合法文件名打不开。
+ *
+ * @example
+ * ```ts
+ * resolveArchivePath('OPS', 'images/a.png');   // 'OPS/images/a.png'
+ * resolveArchivePath('OPS/sub', '../a.opf');   // 'OPS/a.opf'
+ * resolveArchivePath('OPS', '/images/a.png');  // 'images/a.png'
+ * resolveArchivePath('OPS', 'http://x/a.png'); // throws FormatError
+ * ```
+ */
+declare function resolveArchivePath(basePath: string, href: string, options?: ArchivePathOptions): string;
+/**
+ * 取归档内路径的所在目录。
+ *
+ * 纯字符串操作，不做规范化、不抛错 —— 供调用方从 `opfPath` 推导 `basePath`。
+ *
+ * @param archivePath - 归档内路径。
+ * @returns 目录部分（不含结尾 `/`）；根目录下的文件返回空串。
+ *
+ * @example
+ * ```ts
+ * directoryOf('OPS/package.opf');      // 'OPS'
+ * directoryOf('OPS/sub/book.opf');     // 'OPS/sub'
+ * directoryOf('package.opf');          // ''
+ * ```
+ */
+declare function directoryOf(archivePath: string): string;
+
+/**
+ * 把 CFI 折叠为单点字符串。
+ *
+ * - 单点入参：原样返回其规范字符串（`toEnd` 无影响）
+ * - 范围入参：`toEnd` 为 `false`（默认）取起点，为 `true` 取终点
+ *
+ * 返回**含 `epubcfi()` 前缀**的字符串（与基线 `collapse` 的返回口径一致）。
+ */
+declare function collapseCfi(cfi: Cfi, toEnd?: boolean): string;
+
+/**
+ * 判定任意值是否为**已解析且结构完整**的 CFI 对象。
+ *
+ * 不只检查 `kind` —— 仅凭 `kind` 判定会让 `{ kind: 'point' }` 这类半成品蒙混过关，
+ * 消费方随后在 `paths` 上解引用就会崩。这里做结构校验，使判定结果真正可用。
+ */
+declare function isCfi(value: unknown): value is Cfi;
+/**
+ * 判定字符串是否为**可解析**的 CFI。
+ *
+ * 以「能否被 {@link parseCfi} 解析」为唯一判据 —— 不另立一套宽松的语法，
+ * 避免判定与解析口径漂移。因此对畸形 CFI（如 `epubcfi(/a/b)`）返回 `false`。
+ */
+declare function isCfiString(value: unknown): value is string;
+
+/**
+ * 解析 CFI 字符串。
+ *
+ * 接受带 `epubcfi()` 前缀或裸字符串两种入参。任何无法解析的输入抛
+ * `ParseError`；语法合法但违反规范的抛 `FormatError`。返回值为**冻结**对象。
+ */
+declare function parseCfi(input: string): Cfi;
+
+/**
+ * 序列化为规范 CFI 字符串（含 `epubcfi()` 前缀）。
+ *
+ * 结果与 `parseCfi()` 产出的 `value` 一致 —— 该不变式由测试保证。
+ */
+declare function serializeCfi(cfi: Cfi): string;
+
+export { type ArchivePathOptions, Cfi, type ParseXmlOptions, ParseZipOptions, type XmlElement, type XmlNode, type XmlText, ZipArchive, collapseCfi, directoryOf, findAll, findFirst, getAttribute, getText, isCfi, isCfiString, isElement, normalizeArchivePath, parseCfi, parseXml, parseZip, resolveArchivePath, serializeCfi };

package/dist/core/index.d.ts

@@ -0,0 +1,321 @@
+export { A as AbortError, F as FormatError, a as FrondError, b as FrondErrorCode, c as FrondErrorOptions, N as NetworkError, P as ParseError, S as SecurityError, d as StateError, e as createAbortError, i as isAbortError, f as isFrondError, l as linkSignals, o as onAbort, t as throwIfAborted } from '../abort-BY8vBk0v.js';
+import { P as ParseZipOptions, Z as ZipArchive } from '../types-B76GOMxj.js';
+export { a as ZipCompressionMethod, b as ZipEntry } from '../types-B76GOMxj.js';
+export { O as OperationOptions } from '../types-DQYmArgv.js';
+export { a as Book, b as BookFormat, c as BookMetadata, B as BookSource, C as ChapterItem, M as ManifestItem, d as MemoryBookSourceOptions, e as ReadingDirection, R as ResourceIO, f as ResourceItem, S as SpineItem, T as TocItem, g as createMemoryBookSource } from '../types-C-5eHSRH.js';
+import { C as Cfi } from '../types-B7mslPBY.js';
+export { a as CfiPath, b as CfiPoint, c as CfiRange, d as CfiStep } from '../types-B7mslPBY.js';
+
+/**
+ * XML 解析的类型定义（ADR-0006）。
+ *
+ * 设计约束：
+ * - **不实现完整 DOM**，只覆盖 EPUB 所需的受控子集（`container.xml` / OPF / NAV / NCX / SMIL）
+ * - **零 DOM、零运行时依赖**（H4 + H12），因此不使用 `DOMParser` 等平台 API
+ * - **命名空间只做前缀分离**，不做完整的 URI 解析与校验 —— EPUB 场景下按 `localName` 查找已足够
+ *
+ * 与标准 DOM 的差异是**有意的**：本模块产出的是解析结果，不是可变的活文档。
+ * 所有字段均为 `readonly`，调用方无法通过它修改文档结构。
+ */
+/** 文本节点。 */
+interface XmlText {
+    readonly type: 'text';
+    /** 文本内容。非 CDATA 段已完成实体解码。 */
+    readonly value: string;
+    /**
+     * 是否来自 CDATA 段。
+     *
+     * CDATA 内容**不做**实体解码（`&` 保持字面量），因此需要与普通文本区分。
+     */
+    readonly cdata: boolean;
+}
+/** 元素节点。 */
+interface XmlElement {
+    readonly type: 'element';
+    /** 原始标签名，含前缀。例如 `dc:title`。 */
+    readonly name: string;
+    /** 命名空间前缀。无前缀时为空字符串。 */
+    readonly prefix: string;
+    /** 去掉前缀的标签名。例如 `title`。查询请优先使用本字段。 */
+    readonly localName: string;
+    /**
+     * 属性表：原始属性名 → 属性值。
+     *
+     * - 键含前缀，例如 `xmlns:dc`、`full-path`
+     * - 值已完成实体解码
+     * - 保持文档中的出现顺序
+     */
+    readonly attributes: ReadonlyMap<string, string>;
+    /** 子节点，按文档顺序。 */
+    readonly children: readonly XmlNode[];
+}
+/** XML 节点。 */
+type XmlNode = XmlElement | XmlText;
+/** 解析选项。 */
+interface ParseXmlOptions {
+    /**
+     * 源标识，用于错误定位（REQ-EPUB-007）。
+     *
+     * 通常传入文件路径或条目名，例如 `META-INF/container.xml`。
+     * 解析失败时该值会出现在 `ParseError.message` 中。
+     */
+    readonly source?: string;
+    /**
+     * **元素**嵌套层数上限，根元素算第 1 层。
+     *
+     * 存在它只有一个理由：XML 解析是递归下降的，而输入**来自陌生人给的文件** ⇒
+     * 不设上限时「10 KB 的 `<n><n><n>…`」会把宿主进程拖进 `RangeError: Maximum call
+     * stack size exceeded` —— 那是**引擎崩溃**，不是「这本书解析失败」，既不返回给调用方
+     * （绕过 `FrondError` 体系），也救不回同一线程上别的书。
+     *
+     * 超限抛 `ParseError`，**发生在读到越界的那个开始标签时**（不等闭合标签）。
+     * 兄弟节点与自闭合元素不增加深度，故大量同层节点不受影响。
+     *
+     * @defaultValue 512 —— 真实 XHTML 章节的常见深度在两位数以内，本仓最深的用例是 300 层，
+     *   512 留了约 5 倍余量。
+     */
+    readonly maxDepth?: number;
+}
+
+/**
+ * 极简 XML 解析器（ADR-0006）。
+ *
+ * 设计取舍：
+ * - **单遍扫描**，不做 token 预切分；用 `charCodeAt` 判断而非正则，避免回溯
+ * - **不实现完整 DOM**：无命名空间 URI 解析、无 DTD 校验、无外部实体
+ * - **不静默降级**：任何非法结构一律抛 `ParseError`（对照 FI-005）
+ * - **递归深度有上限**：默认 512 层（`options.maxDepth`），超限同样抛 `ParseError` ——
+ *   输入是不可信文件，不设上限就是让一本畸形书有机会以 `RangeError` 打挂宿主进程
+ * - **零 DOM**：只用字符串操作，可在 Node / Worker / 浏览器一致运行
+ *
+ * 规范子集（EPUB 实际需要）：
+ * - XML 声明、DOCTYPE（含 PUBLIC 与内部子集，均跳过不解析）
+ * - 注释、处理指令（跳过）
+ * - CDATA（保留原文，不解码实体）
+ * - 元素 / 属性 / 文本、自闭合元素
+ * - 5 个预定义实体 + 十进制 / 十六进制字符引用
+ * - 换行规范化（XML 1.0 §2.11）：字面 CRLF、CR → LF；字符引用产生的 CR 不受影响
+ *
+ * 有意偏离规范之处（宽容处理，便于兼容真实世界文件）：
+ * - 结束标记允许尾随空白，如 `</a >`
+ * - 未识别实体与非法字符引用按字面量保留，而非报错
+ */
+
+/**
+ * 解析 XML 文本。
+ *
+ * 文档必须恰好包含一个根元素。解析失败时抛 {@link ParseError}，
+ * message 中包含 `options.source` 与出错偏移量，便于定位（REQ-EPUB-007）。
+ *
+ * @param source - XML 文本。
+ * @param options - 解析选项；`source` 用于错误定位，`maxDepth` 限定嵌套层数。
+ * @returns 根元素。
+ * @throws {ParseError} 文档结构非法，**或嵌套超过 `maxDepth`**（默认 512 层）——
+ *   后者是有意为之：不设上限时畸形文档会以 `RangeError` 打挂宿主进程，而不是「解析失败」。
+ */
+declare function parseXml(source: string, options?: ParseXmlOptions): XmlElement;
+
+/**
+ * XML 节点查询辅助。
+ *
+ * 这些函数是纯遍历，不修改文档。查询一律基于 `localName`，
+ * 忽略命名空间前缀 —— 对 EPUB 的 OPF / NAV / NCX 而言这已足够
+ * （见 ADR-0006 的取舍说明）。
+ */
+
+/**
+ * 按 `localName` 深度优先查找全部匹配元素。
+ *
+ * 匹配范围为 `root` 的**后代**，不含 `root` 自身。
+ *
+ * @param root - 查找起点。
+ * @param localName - 目标标签名（不含前缀）。
+ * @returns 按文档顺序排列的匹配元素；无匹配时为空数组。
+ */
+declare function findAll(root: XmlElement, localName: string): XmlElement[];
+/**
+ * 按 `localName` 查找首个匹配元素。
+ *
+ * @returns 首个匹配元素；无匹配时返回 `undefined`。
+ */
+declare function findFirst(root: XmlElement, localName: string): XmlElement | undefined;
+/**
+ * 读取元素属性。
+ *
+ * @param element - 目标元素。
+ * @param name - 属性名，**含前缀**（如 `xmlns:dc`）。
+ * @returns 属性值；属性不存在时返回 `undefined`。
+ */
+declare function getAttribute(element: XmlElement, name: string): string | undefined;
+/**
+ * 递归拼接元素的全部后代文本。
+ *
+ * CDATA 段的内容同样计入。不做空白规范化 —— 需要时由调用方处理。
+ *
+ * @returns 拼接后的文本；无文本节点时返回空字符串。
+ */
+declare function getText(element: XmlElement): string;
+/** 判断节点是否为元素。 */
+declare function isElement(node: XmlNode): node is XmlElement;
+
+/**
+ * ZIP 读取器（ADR-0007）。
+ *
+ * 实现策略：
+ * - **只信中央目录**：条目尺寸一律取自 central directory，忽略 local header 中的值。
+ *   流式写入的 ZIP（bit 3 = data descriptor）其 local header 尺寸恒为 0，因此不可信。
+ * - **单遍定位 EOCD**：从尾部倒扫，并用「注释长度必须恰好补齐文件末尾」校验，
+ *   避免把注释区里偶然出现的 EOCD 签名字节误判为记录头。
+ * - **不静默降级**：结构损坏抛 `ParseError`，不支持的特性抛 `FormatError`（对照 FI-005）。
+ * - **条目名与查询键同一个函数产出**（FI-X22）：中央目录里的名字在**解析那一刻**就送
+ *   `normalizeArchivePath` 归一化，因此 `entries[].name`、探测层看到的名字、
+ *   `entry()` / `read()` 的索引键与调用方传进来的路径**是同一份口径**。
+ *
+ * 已知边界（ADR-0007）：不支持 ZIP64 与加密条目 —— 检测到即抛错，不按 32 位误解析。
+ */
+
+/**
+ * 解析 ZIP 归档。
+ *
+ * 只读取中央目录，不解压任何条目 —— 解压发生在 {@link ZipArchive.read}。
+ *
+ * @param bytes - 完整 ZIP 字节。归档存活期间不要修改它。
+ * @param options - `source` 用于错误定位；`maxEntrySizeBytes` 限定单个条目的解压产物。
+ * @returns 只读归档视图。条目名已归一化（见 {@link ZipEntry.name}）。
+ * @throws {ParseError} 结构损坏（EOCD 缺失、签名错、偏移越界）。
+ * @throws {FormatError} 不支持的特性（压缩方法非 0/8、加密、ZIP64），**或条目名不是合法的
+ *   归档内路径 / 两条条目名归一化后互相歧义**（FI-X22）。
+ */
+declare function parseZip(bytes: Uint8Array, options?: ParseZipOptions): ZipArchive;
+
+/**
+ * 归档内路径解析。
+ *
+ * 这是**跨格式能力**：EPUB 的 rootfile `full-path`、manifest `href`，
+ * 以及 P3 的 FB2 / CBZ 资源定位都要用同一套规则，因此归 `core` 而非某个格式包
+ * （ARCHITECTURE §1 划分判据：若多种格式都要用则属 core）。
+ *
+ * 统一口径（FI-X22 起，本模块是归档路径的**唯一**归一化点）：
+ * - `\` 归一化为 `/`
+ * - 忽略空段与 `.` 段
+ * - `..` 仅在归档根目录之内回退；越界即抛 `FormatError`（防目录穿越）
+ * - **不做**百分号解码（ZIP 条目名本身不编码，解码会指向不存在的条目）
+ * - 拒绝空路径、规范化后为空的路径、控制字符
+ *
+ * 消费者（全部走同一份规则）：`core/zip/parse.ts` 的**条目名**（FI-X22 起，
+ * 在解析中央目录那一刻就送进来，故 `entries[].name` 与查询键不可能分叉）、
+ * EPUB 的 `container.ts` / `opf.ts` / `nav.ts`，以及渲染层的 `resources.ts`。
+ *
+ * 全部失败抛 `FormatError` —— 路径非法属「不符合规范」，而非「数据损坏」。
+ *
+ * 本模块零 DOM、零运行时依赖（H4 / H12）。
+ */
+/** 路径解析的上下文，仅用于生成可定位的错误消息（REQ-EPUB-007）。 */
+interface ArchivePathOptions {
+    /** 源标识，通常是文件名或 URL。 */
+    readonly source?: string;
+    /**
+     * 该路径在文档中的语义名，用于错误消息，例如 `rootfile 的 full-path`、`manifest href`。
+     *
+     * @defaultValue `'归档路径'`
+     */
+    readonly label?: string;
+}
+/**
+ * 把归档内路径规范化到「相对归档根」的绝对形式。
+ *
+ * @param rawPath - 原始路径，可含前导 `/`、`\`、`.` 与 `..`。
+ * @param options - 错误消息上下文。
+ * @returns 规范化后的路径，**不含前导 `/`**。
+ * @throws {FormatError} 路径为空、规范化后为空、含控制字符、或 `..` 越出归档根。
+ *
+ * @example
+ * ```ts
+ * normalizeArchivePath('/OPS/./package.opf'); // 'OPS/package.opf'
+ * normalizeArchivePath('OPS\\a.opf');          // 'OPS/a.opf'
+ * normalizeArchivePath('OPS/../../a.opf');     // throws FormatError
+ * ```
+ */
+declare function normalizeArchivePath(rawPath: string, options?: ArchivePathOptions): string;
+/**
+ * 相对基准目录解析一个 href。
+ *
+ * @param basePath - 基准目录（**不含**文件名），例如 OPF 所在目录 `'OPS'`。空串表示归档根。
+ * @param href - 待解析的引用，可含前导 `/`（视为相对归档根的绝对路径）。
+ * @param options - 错误消息上下文。
+ * @returns 规范化后的归档内路径，**不含前导 `/`**。
+ * @throws {FormatError} href **不是相对引用**（带 scheme、协议相对 `//…`、或纯 fragment）、
+ *   href 未指名任何条目、或解析结果越出归档根。
+ *
+ * ⚠️ 「必须是相对引用」这条判据立在**解析引用**这一侧，**不**立在
+ * {@link normalizeArchivePath} 那一侧 —— 后者现在还服务 ZIP 的**条目名**归一化
+ * （FI-X22 / 批次 E-8），而 `a:b.png` 这类带冒号的文件名在归档里完全合法（POSIX 允许 `:`）。
+ * 把 scheme 判据塞进归一化，等于让一整本档案因为一个合法文件名打不开。
+ *
+ * @example
+ * ```ts
+ * resolveArchivePath('OPS', 'images/a.png');   // 'OPS/images/a.png'
+ * resolveArchivePath('OPS/sub', '../a.opf');   // 'OPS/a.opf'
+ * resolveArchivePath('OPS', '/images/a.png');  // 'images/a.png'
+ * resolveArchivePath('OPS', 'http://x/a.png'); // throws FormatError
+ * ```
+ */
+declare function resolveArchivePath(basePath: string, href: string, options?: ArchivePathOptions): string;
+/**
+ * 取归档内路径的所在目录。
+ *
+ * 纯字符串操作，不做规范化、不抛错 —— 供调用方从 `opfPath` 推导 `basePath`。
+ *
+ * @param archivePath - 归档内路径。
+ * @returns 目录部分（不含结尾 `/`）；根目录下的文件返回空串。
+ *
+ * @example
+ * ```ts
+ * directoryOf('OPS/package.opf');      // 'OPS'
+ * directoryOf('OPS/sub/book.opf');     // 'OPS/sub'
+ * directoryOf('package.opf');          // ''
+ * ```
+ */
+declare function directoryOf(archivePath: string): string;
+
+/**
+ * 把 CFI 折叠为单点字符串。
+ *
+ * - 单点入参：原样返回其规范字符串（`toEnd` 无影响）
+ * - 范围入参：`toEnd` 为 `false`（默认）取起点，为 `true` 取终点
+ *
+ * 返回**含 `epubcfi()` 前缀**的字符串（与基线 `collapse` 的返回口径一致）。
+ */
+declare function collapseCfi(cfi: Cfi, toEnd?: boolean): string;
+
+/**
+ * 判定任意值是否为**已解析且结构完整**的 CFI 对象。
+ *
+ * 不只检查 `kind` —— 仅凭 `kind` 判定会让 `{ kind: 'point' }` 这类半成品蒙混过关，
+ * 消费方随后在 `paths` 上解引用就会崩。这里做结构校验，使判定结果真正可用。
+ */
+declare function isCfi(value: unknown): value is Cfi;
+/**
+ * 判定字符串是否为**可解析**的 CFI。
+ *
+ * 以「能否被 {@link parseCfi} 解析」为唯一判据 —— 不另立一套宽松的语法，
+ * 避免判定与解析口径漂移。因此对畸形 CFI（如 `epubcfi(/a/b)`）返回 `false`。
+ */
+declare function isCfiString(value: unknown): value is string;
+
+/**
+ * 解析 CFI 字符串。
+ *
+ * 接受带 `epubcfi()` 前缀或裸字符串两种入参。任何无法解析的输入抛
+ * `ParseError`；语法合法但违反规范的抛 `FormatError`。返回值为**冻结**对象。
+ */
+declare function parseCfi(input: string): Cfi;
+
+/**
+ * 序列化为规范 CFI 字符串（含 `epubcfi()` 前缀）。
+ *
+ * 结果与 `parseCfi()` 产出的 `value` 一致 —— 该不变式由测试保证。
+ */
+declare function serializeCfi(cfi: Cfi): string;
+
+export { type ArchivePathOptions, Cfi, type ParseXmlOptions, ParseZipOptions, type XmlElement, type XmlNode, type XmlText, ZipArchive, collapseCfi, directoryOf, findAll, findFirst, getAttribute, getText, isCfi, isCfiString, isElement, normalizeArchivePath, parseCfi, parseXml, parseZip, resolveArchivePath, serializeCfi };