frond-js 0.4.0

package/dist/render/index.d.cts

@@ -0,0 +1,116 @@
+import { C as Cfi } from '../types-B7mslPBY.cjs';
+import { O as OperationOptions } from '../types-DQYmArgv.cjs';
+
+/** 一次渲染请求的目标位置。 */
+interface RenderLocation {
+    /** 资源在容器内的相对路径。 */
+    readonly href: string;
+    /**
+     * 该位置对应的 **CFI**（章内位置）。**可选** —— T2.7 收窄。
+     *
+     * 收窄的理由：**章级跳转本来就没有章内位置**。`Reader` 的 `next` / `prev` /
+     * `goTo(spine 索引)` 只知道「第几章」，而 `core/cfi` 只提供字符串层的
+     * parse / serialize / collapse，**没有**「spine 索引 → CFI」的构造器。
+     *
+     * 合成的办法只有两种，都不能接受：① 在 `reader/` 里假定
+     * `epubcfi(/6/{2n}!/4)` 的前缀段 —— 把 EPUB 结构知识塞进编排层，且
+     * `cfi-locate.ts` 只解析**最后一段**，那段前缀**没有任何消费者会校验**；
+     * ② 只写 `epubcfi(/4)` —— 等于声称它是从 package 文档根出发的路径。
+     * 两者都是「假装知道」，而 `docs/PROMPT.md` 的纪律要求**如实表达**。
+     *
+     * 缺省时渲染层落到**章首**（`pageOfTarget` 直接返回 0）。
+     * 有章内位置时（`open({ initialLocation })` / `goTo(cfi)`）照常传入。
+     */
+    readonly cfi?: Cfi;
+    /**
+     * 章内**锚点**：内容文档内的**元素 id**（不含 `#`）。可选。
+     *
+     * ## 与 `cfi` 的分工（T3.2b ③c 新增，ADR-0011 修订）
+     *
+     * | 字段 | 是什么 | 来源 |
+     * | ---- | ------ | ---- |
+     * | `cfi` | **结构路径**（精确到字符偏移） | `goTo(CFI)` / `initialLocation` |
+     * | `fragment` | **元素 id**（粗粒度，只到元素） | 目录项（`TocItem.fragment`） |
+     *
+     * 二者**语义上互斥**：目录项的 `fragment` 要么是元素 id、要么本身是 CFI 字符串，
+     * 解析方（`reader/navigation.ts` 的 `locationForTocItem`）会把它归到**其中一个**字段，
+     * **不会同时给两个**。同时给出时**以 `cfi` 为准**（它是更精确的那一个）——
+     * 这是一条**优先级规则**，不是错误（两者都合法，只是精度不同）。
+     *
+     * ## 只接受元素 id —— 另外两种形态由上层先转换
+     *
+     * `TocItem.fragment` 有**三种**语义（元素 id / EPUB CFI / MOBI 字节偏移，
+     * 见 `core/model/types.ts` 的 `TocItem.fragment`）。本字段**只承载第一种**：
+     *
+     * - **CFI 字符串** → 由 `locationForTocItem` 解析进 `cfi`，**不会**流到这里；
+     * - **MOBI 的字节偏移** → **当前不可定位**，会被当作元素 id 去查、必然落空
+     *   ⇒ 回退章首。⚠️ **这是如实登记的已知缺口**（不是已覆盖），
+     *   修法是「改写正文插 `id`」的独立批次；登记见 `docs/API.md` §14.4。
+     *
+     * ## 落空是**正常数据情况**，回退章首
+     *
+     * 与 `cfi` 落空**同族**（书换版本 / 内容被清洗 / 锚点被删），不是编程错误：
+     * 渲染层回退到**章首**，而不是让整次翻页失败。口径与 `cfi-locate.ts` 的模块头一致
+     * —— 那里是「CFI 可能过期」，这里是「元素 id 可能已不存在」。
+     *
+     * 缺省时渲染层落到**章首**（与 `cfi` 缺省同一落点，但**理由不同**：
+     * 这里是「本来就没有章内位置」，`cfi` 落空是「有过但已失效」）。
+     */
+    readonly fragment?: string;
+    /** spine 中的索引。 */
+    readonly index: number;
+}
+/**
+ * 渲染层的**宿主抽象**（T2.1 定稿，ADR-0011，REQ-RENDER-003）。
+ *
+ * **为什么不是直接收 `HTMLElement`**：渲染层实际需要的只有两件事 ——
+ * 一个可以创建自己视图节点的挂载点，以及创建 iframe 等节点所需的文档。
+ * 把这两件事**具名**声明出来，宿主的最小要求一目了然。
+ *
+ * 更关键的是：契约一旦写成裸 `HTMLElement`，「渲染层只能作用于某个元素」
+ * 就被写死了 —— 这与 FI-007 要修的「基线硬编码 `<foliate-view>` 自定义元素」
+ * 是同一类耦合。具名结构让**需要什么**成为契约的内容，而不是把
+ * **宿主是什么**写进契约。
+ *
+ * ⚠️ 契约**刻意只声明这两个字段**：尺寸测量、滚动位置、样式等都由渲染层
+ * 通过 `element` 自行完成，不进契约 —— 契约越大，宿主实现负担越重、可替换性越差。
+ */
+interface RenderHost {
+    /** 挂载点。渲染层会在其中创建自己的视图节点。 */
+    readonly element: HTMLElement;
+    /** 该宿主所属的文档（用于创建 iframe 等节点）。 */
+    readonly ownerDocument: Document;
+}
+/**
+ * 渲染层接口（REQ-RENDER-003）。
+ *
+ * 设计意图：宿主可整体替换渲染策略（分页 / 滚动 / 自定义排版），
+ * 而无需触碰 core 的解析与建模逻辑。
+ *
+ * 实现者必须满足的契约（T2.1 定稿）：
+ *
+ * 1. **取消（H6 / H7）**：`options.signal` 已 abort 时，`mount` / `render` 必须抛
+ *    `AbortError`，且**不得留下半成品视图**（已创建的 iframe / `blob:` URL / 事件监听
+ *    都必须释放）。
+ * 2. **`unmount` 幂等且必须释放资源**：重复调用不抛错；必须 `revokeObjectURL`、
+ *    移除 iframe、解绑事件。
+ *
+ * > 更细的行为义务（`mount` 重复调用是否叠加视图、未挂载即 `render` 如何失败）
+ * > 留待默认实现落地时（T2.2+）在实现处钉死 —— 契约现在不写，是因为
+ * > **尚未有实现去兑现它**，先写下来只会变成无人验证的纸面条文。
+ */
+interface Renderer {
+    /**
+     * 挂载到宿主。
+     *
+     * `host` 在 P0 是 `unknown` 占位；**T2.1 收窄为 {@link RenderHost}** ——
+     * 刻意**不是**裸 `HTMLElement`，理由见 {@link RenderHost}。
+     */
+    mount(host: RenderHost, options?: OperationOptions): Promise<void>;
+    /** 渲染指定位置。 */
+    render(target: RenderLocation, options?: OperationOptions): Promise<void>;
+    /** 卸载并释放全部资源。必须幂等。 */
+    unmount(): void;
+}
+
+export type { RenderHost, RenderLocation, Renderer };

package/dist/render/index.d.ts

@@ -0,0 +1,116 @@
+import { C as Cfi } from '../types-B7mslPBY.js';
+import { O as OperationOptions } from '../types-DQYmArgv.js';
+
+/** 一次渲染请求的目标位置。 */
+interface RenderLocation {
+    /** 资源在容器内的相对路径。 */
+    readonly href: string;
+    /**
+     * 该位置对应的 **CFI**（章内位置）。**可选** —— T2.7 收窄。
+     *
+     * 收窄的理由：**章级跳转本来就没有章内位置**。`Reader` 的 `next` / `prev` /
+     * `goTo(spine 索引)` 只知道「第几章」，而 `core/cfi` 只提供字符串层的
+     * parse / serialize / collapse，**没有**「spine 索引 → CFI」的构造器。
+     *
+     * 合成的办法只有两种，都不能接受：① 在 `reader/` 里假定
+     * `epubcfi(/6/{2n}!/4)` 的前缀段 —— 把 EPUB 结构知识塞进编排层，且
+     * `cfi-locate.ts` 只解析**最后一段**，那段前缀**没有任何消费者会校验**；
+     * ② 只写 `epubcfi(/4)` —— 等于声称它是从 package 文档根出发的路径。
+     * 两者都是「假装知道」，而 `docs/PROMPT.md` 的纪律要求**如实表达**。
+     *
+     * 缺省时渲染层落到**章首**（`pageOfTarget` 直接返回 0）。
+     * 有章内位置时（`open({ initialLocation })` / `goTo(cfi)`）照常传入。
+     */
+    readonly cfi?: Cfi;
+    /**
+     * 章内**锚点**：内容文档内的**元素 id**（不含 `#`）。可选。
+     *
+     * ## 与 `cfi` 的分工（T3.2b ③c 新增，ADR-0011 修订）
+     *
+     * | 字段 | 是什么 | 来源 |
+     * | ---- | ------ | ---- |
+     * | `cfi` | **结构路径**（精确到字符偏移） | `goTo(CFI)` / `initialLocation` |
+     * | `fragment` | **元素 id**（粗粒度，只到元素） | 目录项（`TocItem.fragment`） |
+     *
+     * 二者**语义上互斥**：目录项的 `fragment` 要么是元素 id、要么本身是 CFI 字符串，
+     * 解析方（`reader/navigation.ts` 的 `locationForTocItem`）会把它归到**其中一个**字段，
+     * **不会同时给两个**。同时给出时**以 `cfi` 为准**（它是更精确的那一个）——
+     * 这是一条**优先级规则**，不是错误（两者都合法，只是精度不同）。
+     *
+     * ## 只接受元素 id —— 另外两种形态由上层先转换
+     *
+     * `TocItem.fragment` 有**三种**语义（元素 id / EPUB CFI / MOBI 字节偏移，
+     * 见 `core/model/types.ts` 的 `TocItem.fragment`）。本字段**只承载第一种**：
+     *
+     * - **CFI 字符串** → 由 `locationForTocItem` 解析进 `cfi`，**不会**流到这里；
+     * - **MOBI 的字节偏移** → **当前不可定位**，会被当作元素 id 去查、必然落空
+     *   ⇒ 回退章首。⚠️ **这是如实登记的已知缺口**（不是已覆盖），
+     *   修法是「改写正文插 `id`」的独立批次；登记见 `docs/API.md` §14.4。
+     *
+     * ## 落空是**正常数据情况**，回退章首
+     *
+     * 与 `cfi` 落空**同族**（书换版本 / 内容被清洗 / 锚点被删），不是编程错误：
+     * 渲染层回退到**章首**，而不是让整次翻页失败。口径与 `cfi-locate.ts` 的模块头一致
+     * —— 那里是「CFI 可能过期」，这里是「元素 id 可能已不存在」。
+     *
+     * 缺省时渲染层落到**章首**（与 `cfi` 缺省同一落点，但**理由不同**：
+     * 这里是「本来就没有章内位置」，`cfi` 落空是「有过但已失效」）。
+     */
+    readonly fragment?: string;
+    /** spine 中的索引。 */
+    readonly index: number;
+}
+/**
+ * 渲染层的**宿主抽象**（T2.1 定稿，ADR-0011，REQ-RENDER-003）。
+ *
+ * **为什么不是直接收 `HTMLElement`**：渲染层实际需要的只有两件事 ——
+ * 一个可以创建自己视图节点的挂载点，以及创建 iframe 等节点所需的文档。
+ * 把这两件事**具名**声明出来，宿主的最小要求一目了然。
+ *
+ * 更关键的是：契约一旦写成裸 `HTMLElement`，「渲染层只能作用于某个元素」
+ * 就被写死了 —— 这与 FI-007 要修的「基线硬编码 `<foliate-view>` 自定义元素」
+ * 是同一类耦合。具名结构让**需要什么**成为契约的内容，而不是把
+ * **宿主是什么**写进契约。
+ *
+ * ⚠️ 契约**刻意只声明这两个字段**：尺寸测量、滚动位置、样式等都由渲染层
+ * 通过 `element` 自行完成，不进契约 —— 契约越大，宿主实现负担越重、可替换性越差。
+ */
+interface RenderHost {
+    /** 挂载点。渲染层会在其中创建自己的视图节点。 */
+    readonly element: HTMLElement;
+    /** 该宿主所属的文档（用于创建 iframe 等节点）。 */
+    readonly ownerDocument: Document;
+}
+/**
+ * 渲染层接口（REQ-RENDER-003）。
+ *
+ * 设计意图：宿主可整体替换渲染策略（分页 / 滚动 / 自定义排版），
+ * 而无需触碰 core 的解析与建模逻辑。
+ *
+ * 实现者必须满足的契约（T2.1 定稿）：
+ *
+ * 1. **取消（H6 / H7）**：`options.signal` 已 abort 时，`mount` / `render` 必须抛
+ *    `AbortError`，且**不得留下半成品视图**（已创建的 iframe / `blob:` URL / 事件监听
+ *    都必须释放）。
+ * 2. **`unmount` 幂等且必须释放资源**：重复调用不抛错；必须 `revokeObjectURL`、
+ *    移除 iframe、解绑事件。
+ *
+ * > 更细的行为义务（`mount` 重复调用是否叠加视图、未挂载即 `render` 如何失败）
+ * > 留待默认实现落地时（T2.2+）在实现处钉死 —— 契约现在不写，是因为
+ * > **尚未有实现去兑现它**，先写下来只会变成无人验证的纸面条文。
+ */
+interface Renderer {
+    /**
+     * 挂载到宿主。
+     *
+     * `host` 在 P0 是 `unknown` 占位；**T2.1 收窄为 {@link RenderHost}** ——
+     * 刻意**不是**裸 `HTMLElement`，理由见 {@link RenderHost}。
+     */
+    mount(host: RenderHost, options?: OperationOptions): Promise<void>;
+    /** 渲染指定位置。 */
+    render(target: RenderLocation, options?: OperationOptions): Promise<void>;
+    /** 卸载并释放全部资源。必须幂等。 */
+    unmount(): void;
+}
+
+export type { RenderHost, RenderLocation, Renderer };

package/dist/render/index.js

@@ -0,0 +1 @@
+

package/dist/types-B76GOMxj.d.ts

@@ -0,0 +1,129 @@
+import { O as OperationOptions } from './types-DQYmArgv.js';
+
+/**
+ * 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-B7mslPBY.d.cts

@@ -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 };