@coco-vexel/coco-office 0.0.0-stage → 1.0.0

package/dist/view-DX2YAG5A.d.cts

@@ -0,0 +1,1199 @@
+import { a as Package } from './types-BVkkdcfh.cjs';
+
+/**
+ * OOXML 常用命名空间 URI 常量。
+ *
+ * 所有 XPath / DOM 查询必须按 URI 比较(不依赖前缀)—— serializer 可能改前缀,URI 不变。
+ * 来源:docs/01 附录 A。
+ */
+/** Word 正文命名空间 */
+declare const W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+/** 关系(.rels 文件 / r:id 引用) */
+declare const R_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+/** DrawingML(Word / Excel / PPT 共用) */
+declare const A_NS = "http://schemas.openxmlformats.org/drawingml/2006/main";
+/** DrawingML wordprocessing 容器(wp:inline / wp:anchor / wp:extent / wp:wrap*) */
+declare const WP_NS = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
+/** DrawingML picture(pic:pic) */
+declare const PIC_NS = "http://schemas.openxmlformats.org/drawingml/2006/picture";
+/** DrawingML chart(c:chart 引用) */
+declare const CHART_NS = "http://schemas.openxmlformats.org/drawingml/2006/chart";
+/** DrawingML diagram(SmartArt;dgm:relIds) */
+declare const DGM_NS = "http://schemas.openxmlformats.org/drawingml/2006/diagram";
+/** Word 2010+ wordprocessing shape(wps:wsp / wps:txbx) */
+declare const WPS_NS = "http://schemas.microsoft.com/office/word/2010/wordprocessingShape";
+/** Word 2010+ wordprocessing group(wpg:wgp) */
+declare const WPG_NS = "http://schemas.microsoft.com/office/word/2010/wordprocessingGroup";
+/** Word 2010+ wordprocessing canvas(wpc:wpc) */
+declare const WPC_NS = "http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas";
+/** Markup Compatibility(Choice / Fallback) */
+declare const MC_NS = "http://schemas.openxmlformats.org/markup-compatibility/2006";
+/** VML(旧版形状降级；v:line / v:rect / v:shape，多见于 mc:Fallback) */
+declare const VML_NS = "urn:schemas-microsoft-com:vml";
+/** Word 2010+ 扩展(w14:paraId / w14:textId) */
+declare const W14_NS = "http://schemas.microsoft.com/office/word/2010/wordml";
+/** Flat OPC 包格式 */
+declare const PKG_NS = "http://schemas.microsoft.com/office/2006/xmlPackage";
+/** xml:space 等 xml 标准命名空间 */
+declare const XML_NS = "http://www.w3.org/XML/1998/namespace";
+
+/**
+ * `getRunText` / `getParagraphText` 可选参数（task-20260623-core-tab-faithful-read）。
+ *
+ * - `structuralWhitespace: true`：保真读模式——按 appendSegmentsToRun 的精确逆运算，
+ *   `<w:tab/>` → `\t`、`<w:br/>` （无 w:type 或 w:type="textWrapping"）→ `\n`。
+ * - 缺省 / `false`：现行为（只拼 `<w:t>`），**偏移算术安全**。
+ */
+interface RunTextOptions {
+    /**
+     * 启用结构空白保真读：`<w:tab/>` → `\t`，`<w:br/>` → `\n`。
+     * **仅用于内容读取**，不得用于偏移算术（bookmark/comment/replaceText 等）。
+     */
+    structuralWhitespace?: boolean;
+}
+/** 段落 `<w:p>` 下所有直接 `<w:r>` 子元素(不递归到嵌套段落 / smartTag 等) */
+declare function getParagraphRuns(paragraph: Element): Element[];
+/**
+ * 取 run 的文本。
+ *
+ * - 默认（opts 缺省 / `structuralWhitespace: false`）：只拼 `<w:t>` 文本，忽略 `<w:br>` / `<w:tab>`。
+ *   **偏移算术安全**：`<w:tab/>` 算 0 长，保持 bookmark/comment/replaceText 偏移稳定。
+ * - `structuralWhitespace: true`：保真读——按文档顺序遍历子节点：
+ *   `<w:t>` → textContent、`<w:tab/>` → `\t`、`<w:br/>` （无 w:type 或 textWrapping）→ `\n`。
+ *   这是 `appendSegmentsToRun` 的精确逆运算。
+ */
+declare function getRunText(run: Element, opts?: RunTextOptions): string;
+/**
+ * 段落的纯文本（所有直接 run 的文本拼接）。
+ *
+ * - 默认（opts 缺省）：只拼 `<w:t>`，偏移算术安全。
+ * - `structuralWhitespace: true`：保真读，透传到 `getRunText`。
+ */
+declare function getParagraphText(paragraph: Element, opts?: RunTextOptions): string;
+/** splitRunAt 返回值 */
+interface SplitResult {
+    /** 原 run,文本截取到 [0, offset) */
+    before: Element;
+    /**
+     * 分裂出的新 run,文本为 [offset, end)。
+     * 与 `before` 共享 `<w:rPr>` 结构(深拷贝,不共享对象引用)。
+     * offset=0 或 offset=runLen 时为 null(未发生分裂)
+     */
+    after: Element | null;
+}
+/**
+ * 在 run 的文本 offset 处拆分。
+ *
+ * - `offset === 0` 或 `offset === getRunText(run).length` → 不拆,返回 { before: run, after: null }
+ * - 其它情况 → 新 run 插入到原 run 的 nextSibling 位置,返回 { before: run, after: newRun }
+ *
+ * 本期限制:run 必须恰有 1 个 `<w:t>` 子;否则抛错(多 <w:t>、<w:br>、<w:tab> 等复杂结构交给
+ * 后续 #28 的扩展实现)。
+ */
+declare function splitRunAt(run: Element, offset: number): SplitResult;
+
+/**
+ * style-queries —— styles.xml 解析与样式索引构建（#181）。
+ *
+ * 职责：
+ *   - `buildStylesIndex(pkg)`：扫 Package 找 styles.xml，构建 Map<styleId, StyleInfo>
+ *   - `listStyles(stylesIdx, opts?)`：按可选 type 过滤后返回数组
+ *   - `getStyleById(stylesIdx, styleId)`：O(1) 精确查找
+ *
+ * 健壮性契约：
+ *   - styles.xml 不存在 → 返回空 Map，不抛错
+ *   - `w:type` 未知值 → fallback 到 'paragraph'（OOXML 规范默认）
+ *   - `w:name` 子元素缺失 → name fallback 到 styleId 本身
+ *   - 同一 styleId 重复定义 → 后者覆盖前者（与 Word 行为一致）
+ *   - basedOn 环路 → SDK 不检测，消费方遍历时须自行防环
+ *
+ * 不暴露 `builtIn` 字段：`<w:builtIn/>` 元素在实际文档中不一致（Word 某些版本省略），
+ * 单向可信（存在则肯定是内置，不存在不代表是自定义）会误导消费方。
+ * 消费方应通过 `name` + basedOn 链判断语义角色。
+ */
+
+/** OOXML 定义的四种样式类型（`w:style@w:type`）。 */
+type StyleType = 'paragraph' | 'character' | 'table' | 'numbering';
+interface StyleInfo {
+    /** `w:style@w:styleId`。段落 `w:pStyle@w:val` 引用的 key，大小写敏感。 */
+    styleId: string;
+    /**
+     * `w:name@w:val`。
+     * - OOXML 规范：内置样式（如 Heading 1、Normal）的 name 永远是英文规范名，
+     *   不随文档语言变化。消费方可据此判断语义角色。
+     * - 自定义样式：name 为用户输入，可能是中文或任意字符串。
+     * - 若 `<w:name>` 元素缺失（非规范文档），fallback 到 `styleId`。
+     */
+    name: string;
+    /**
+     * `w:style@w:type`。
+     * 未知值 fallback 到 `'paragraph'`（OOXML 规范默认类型）。
+     */
+    type: StyleType;
+    /**
+     * 父样式的 `styleId`（`w:basedOn@w:val`）。
+     * 根样式（如 Normal）无继承关系，此字段不存在。
+     *
+     * ⚠ 消费方遍历 basedOn 链时须自行防环，SDK 不检测循环继承。
+     */
+    basedOn?: string;
+    /**
+     * 样式定义中的大纲级别（`w:style/w:pPr/w:outlineLvl@w:val`），0–8。
+     * 0 = 标题 1，1 = 标题 2，…，8 = 标题 9；9 表示正文（不视为标题）。
+     *
+     * WPS / Word 的自定义标题样式（如"公文-一级标题"）通常不 basedOn heading 1，
+     * 而是在此字段直接编码级别。消费方可将其作为 basedOn 链之外的第二信号。
+     *
+     * 字段不存在 = 样式未设置大纲级别（继承自父样式或使用默认值）。
+     */
+    outlineLevel?: number;
+}
+interface ListStylesOptions {
+    /** 按样式类型过滤。不传则返回全部样式（含所有类型）。 */
+    type?: StyleType;
+}
+/**
+ * 扫 Package 构建样式索引。
+ *
+ * - styles.xml 不存在 → 返回空 Map，不抛错
+ * - 同一 styleId 重复出现 → 后者覆盖（与 Word 行为一致）
+ */
+declare function buildStylesIndex(pkg: Package): Map<string, StyleInfo>;
+/**
+ * 列出样式索引中的所有样式。
+ *
+ * @param stylesIdx  由 `buildStylesIndex` 构建的 Map
+ * @param opts       可选过滤（目前支持按 type 过滤）
+ */
+declare function listStyles(stylesIdx: Map<string, StyleInfo>, opts?: ListStylesOptions): StyleInfo[];
+/**
+ * 按 styleId 精确查找，O(1)。
+ * styleId 大小写敏感（与 OOXML 规范一致）。
+ */
+declare function getStyleById(stylesIdx: Map<string, StyleInfo>, styleId: string): StyleInfo | null;
+
+/**
+ * Word 装载期三索引(docs/03 §13.1 / §13.6)。
+ *
+ * - paraIdx:paraId(大写 8 hex)→ <w:p> Element
+ * - bookmarkIdx:name → { start: <w:bookmarkStart>; end: <w:bookmarkEnd>; partPath }
+ * - commentIdx:id(number)→ { comment?: <w:comment>; anchors: { start?, end?, ref? } }
+ *
+ * 同时完成装载期书签校验:**空名抛错**;**重名容错**(保留第一个、忽略后续,绝不崩 ——
+ * 真实文档常见重复的 `_GoBack` 等编辑痕迹书签)。未来由 #15 WordError 统一,先用 Error + code。
+ *
+ * 性能目标:10 万段落 < 100ms(Chrome/Node;WPS WebView 宽松到 < 300ms)。由 `ensureParaIds`
+ * 同样走 getElementsByTagNameNS 保证,这里复用同一枚举路径。
+ */
+
+/** 书签校验错误 code(暂不挂 WordError;#15 会统一到 WordErrorCode) */
+type BookmarkLoadErrorCode = 'BOOKMARK_NAME_DUPLICATE_ON_LOAD' | 'BOOKMARK_NAME_EMPTY_ON_LOAD';
+/** 装载期抛出的书签错误 */
+declare class BookmarkLoadError extends Error {
+    readonly code: BookmarkLoadErrorCode;
+    readonly details: Record<string, unknown>;
+    constructor(code: BookmarkLoadErrorCode, message: string, details?: Record<string, unknown>);
+}
+interface BookmarkEntry {
+    /** `<w:bookmarkStart>` 元素 */
+    start: Element;
+    /** `<w:bookmarkEnd>` 元素;若装载数据里缺失可能为 null */
+    end: Element | null;
+    /** 所在 part 的 path(如 'word/document.xml') */
+    partPath: string;
+}
+interface CommentEntry {
+    /** `<w:comment>` 元素(来自 comments.xml);若无 comments.xml 可能为 null */
+    comment: Element | null;
+    /** 锚点三件套(在 document.xml / headers / footers 等 body-side part 上) */
+    anchors: {
+        start: Element | null;
+        end: Element | null;
+        ref: Element | null;
+    };
+}
+interface PackageIndices {
+    /** paraId → <w:p> */
+    paraIdx: Map<string, Element>;
+    /** bookmark name → entry(含 start/end/partPath) */
+    bookmarkIdx: Map<string, BookmarkEntry>;
+    /** comment id → entry(comment 主体 + 三锚点) */
+    commentIdx: Map<number, CommentEntry>;
+    /**
+     * styleId → StyleInfo（来自 styles.xml）。
+     * styles.xml 不存在时为空 Map。
+     * 消费方按 styleId 做 O(1) 查找，沿 basedOn 链判断语义角色时须自行防环。
+     */
+    stylesIdx: Map<string, StyleInfo>;
+    /**
+     * tableId（'tbl-NNNN'）→ <w:tbl> Element（#185）。
+     * 装载期按文档顺序分配，包含所有 part 的所有表格（含嵌套）。
+     * 供 listTables / getTableById / plan executor（deleteTable）使用。
+     */
+    tblIdx: Map<string, Element>;
+    /**
+     * drawingId（'dr-NNNN'）→ <w:drawing> Element（#189）。
+     * 装载期按文档顺序分配，包含所有 Word 内容 part 的所有 drawing。
+     * 供 listDrawings / getDrawingById / 占位图替换（#190）使用。
+     *
+     * 注意：嵌套在 group / canvas 内的子 drawing 也会被收入（保持枚举层完整暴露），
+     * 上层（#191 / #192）按需用 hasDrawingAncestor 自行决定合并策略。
+     */
+    drawingIdx: Map<string, Element>;
+}
+
+/**
+ * 扫 Package 构建三索引。
+ *
+ * - **装载期书签校验**:遇空名抛 `BookmarkLoadError`(code = BOOKMARK_NAME_EMPTY_ON_LOAD);
+ *   遇重名**容错**(保留第一个、忽略后续,不抛错 —— `_GoBack` 等编辑痕迹书签可安全忽略)
+ * - 孤儿 `bookmarkEnd`(无匹配 start)忽略
+ * - 缺 `bookmarkEnd` 的书签仍入索引,`entry.end` 为 null
+ * - 不抛错的其它不一致(comment 无 <w:comment> 主体、anchors 不全)进索引,由调用方决定是否告警
+ */
+declare function buildIndices(pkg: Package): PackageIndices;
+
+/**
+ * Word 跨 stories 枚举(docs/03 §10)。
+ *
+ * 一个 Word 文档可能包含 6 类 story:
+ *   | 类型     | contentType 尾缀         | 根元素                            | 数量 |
+ *   | body     | .document.main+xml       | <w:document>/<w:body>             | 1    |
+ *   | header   | .header+xml              | <w:hdr>                           | 0..N |
+ *   | footer   | .footer+xml              | <w:ftr>                           | 0..N |
+ *   | footnote | .footnotes+xml 内每个    | 单个 <w:footnote>(该 part 多个)  | 0..M |
+ *   | endnote  | .endnotes+xml 内每个     | 单个 <w:endnote>                  | 0..M |
+ *   | comment  | .comments+xml 内每个     | 单个 <w:comment>                  | 0..M |
+ *
+ * **关键约束**:枚举实现**必须**走 `Document#getElementsByTagNameNS`。
+ * `fontoxpath` 的 `//w:p` 无谓词 XPath 在 10 万段落上慢 460×(见 bench/xml-stack-worker)。
+ * CI 的 `pnpm check:xpath` 会在源码里扫到此类调用即失败(scripts/check-no-unqualified-xpath.mjs)。
+ */
+
+type StoryKind = 'body' | 'header' | 'footer' | 'footnote' | 'endnote' | 'comment';
+/**
+ * Story 唯一标识:
+ *   - 'body' — 唯一主 body
+ *   - 'header:<part path>' / 'footer:<part path>' — 1 part 1 story
+ *   - 'footnote:<id>' / 'endnote:<id>' / 'comment:<id>' — 多 sub-story 按 w:id 区分
+ */
+type StoryId = 'body' | `header:${string}` | `footer:${string}` | `footnote:${number}` | `endnote:${number}` | `comment:${number}`;
+interface Story {
+    id: StoryId;
+    kind: StoryKind;
+    /** story 的根 Element(body = <w:body>,footnote = 单个 <w:footnote>,依此类推) */
+    root: Element;
+    /** 所在 part 的 path */
+    partPath: string;
+}
+interface ListStoriesOptions {
+    /** 仅枚举指定 kinds(默认全枚举)*/
+    kinds?: StoryKind[];
+}
+/**
+ * 枚举 Package 内所有 stories。
+ *
+ * 按 contentType 尾缀识别 part,内部用 `getElementsByTagNameNS` 提取根元素或
+ * sub-story 元素。**不做**任何带谓词/路径的 XPath。
+ */
+declare function listStories(pkg: Package, opts?: ListStoriesOptions): Story[];
+/**
+ * 取 story 根下的所有 <w:p> 元素。
+ *
+ * - body / header / footer:story root 整个子树的 w:p
+ * - footnote / endnote / comment:单个 sub-story root 下的 w:p(不跨 sub-story)
+ */
+declare function getStoryParagraphs(story: Story): Element[];
+/**
+ * 反查元素所属 story(#25)。用 `Node.contains()` 逐个比对,命中首个返回。
+ *
+ * 一个 pkg 内 stories 数量通常 <20,contains 是 ~O(depth) 的祖先遍历,整体代价
+ * 可忽略。找不到(元素不在任何已识别 story 的子树里)返回 null 。
+ */
+declare function findStoryFor(pkg: Package, el: Element): Story | null;
+/**
+ * scope 枚举解析为 Story 列表(#24 / #26 共用)。
+ *
+ * - `'body'` —— 只枚举 body
+ * - `'all'` —— 全部 6 类 story
+ * - `StoryId[]` —— 精确筛选;**未命中的 id 忽略**(调用方自己负责正确性)
+ */
+declare function resolveScope(pkg: Package, scope: 'body' | 'all' | StoryId[]): Story[];
+
+/**
+ * listParagraphs —— 段落查询纯工具(docs/03 §9 / docs/03.1 §1.6,#24)。
+ *
+ * 职责:按 scope / filter / textFormat / pagination 返回 ParagraphInfo 列表。
+ *
+ * 架构:**纯函数**,拿 pkg 给结果,不知道文档尺寸、不做智能默认。"默认分页"
+ * 是 `{ mode: 'byCount', pageSize: 25, pageIndex: 0 }`,要全量请显式传
+ * `{ pagination: { mode: 'all' } }`(2026-04-22 从早期"≤500 段自动 all"的智能
+ * 默认撤回;见 docs/03 §9.2 的历史说明)。
+ *
+ * 实现约束:
+ *   - 段落枚举走 `getStoryParagraphs`(基于 `getElementsByTagNameNS`),**不**用
+ *     fontoxpath。10 万段落上 `//w:p` 慢 460× —— CI 的 `pnpm check:xpath` 会在
+ *     源码里扫到此类无谓词 XPath 即失败。
+ *   - `filter.contains` 是 O(N) 子串匹配,大档慢(docs 已标注)。
+ *   - `hasComments` / `hasRevisions` / `hasBookmarks` 用 `el.getElementsByTagNameNS(...).length > 0`
+ *     检测段内是否存在对应标记元素,不递归手遍。
+ */
+
+/** list scope —— 'body' / 'all' 或显式 StoryId 列表 */
+type ListParagraphsScope = 'body' | 'all' | StoryId[];
+/** text 返回格式。'preview' = 首 100 字 */
+type ListParagraphsTextFormat = 'full' | 'preview';
+interface ListParagraphsFilter {
+    /** 等值匹配 `<w:pPr>/<w:pStyle w:val>` */
+    styleId?: string;
+    /** **O(N) 子串匹配**,区分大小写。大档谨慎使用。 */
+    contains?: string;
+    /** 段内是否含 comment 标记(commentRangeStart / commentReference / commentRangeEnd) */
+    hasComments?: boolean;
+    /** 段内是否含 revision 标记(Tier 1 只看 w:ins / w:del,不含 rPrChange/pPrChange) */
+    hasRevisions?: boolean;
+    /**
+     * 排除位于表格单元格（`<w:tc>`）内的段落。
+     *
+     * 表格内容由独立的 tables phase 处理，段落 phase 只关心主文本流段落。
+     * 开启后会对每个段落向上遍历祖先链（深度通常 ≤5），找到 `<w:tc>` 即排除。
+     */
+    excludeTableCells?: boolean;
+}
+type ListParagraphsPagination = {
+    mode: 'all';
+} | {
+    mode: 'byCount';
+    pageSize: number;
+    pageIndex: number;
+} | {
+    mode: 'byChar';
+    charPerPage: number;
+    pageIndex: number;
+};
+/**
+ * 段落直接格式属性（#182）。
+ *
+ * 仅包含在 `<w:pPr>` 上**直接设置**的值，不做样式继承计算。
+ * 消费方（如骨架化引擎）可将这些值与 styleId 组合为聚类 key，
+ * 区分同一样式但有手工格式覆盖的段落。
+ *
+ * 所有字段均为可选——未直接设置的属性不出现在结果中（继承自样式或默认值）。
+ */
+interface ParagraphFormat {
+    /**
+     * 水平对齐（`w:pPr/w:jc@w:val`）。
+     * `'both'` 对应 OOXML 的 "both"（两端对齐）。
+     */
+    alignment?: 'left' | 'center' | 'right' | 'both' | 'distribute';
+    /**
+     * 缩进（`w:pPr/w:ind`），单位 twips（1/20 磅）。
+     * `firstLine` 正值为首行缩进，负值为悬挂缩进（来自 `w:hanging`）。
+     */
+    indent?: {
+        left?: number;
+        right?: number;
+        /** 首行缩进（正）或悬挂缩进（负，源自 `w:hanging`） */
+        firstLine?: number;
+    };
+    /**
+     * 段间距（`w:pPr/w:spacing`），单位 twips（line 例外：受 lineRule 影响）。
+     */
+    spacing?: {
+        before?: number;
+        after?: number;
+        line?: number;
+        lineRule?: 'auto' | 'exact' | 'atLeast';
+    };
+    /**
+     * 段落级默认字体大小（`w:pPr/w:rPr/w:sz@w:val ÷ 2`），单位磅。
+     * 仅当段落属性中显式设置了 `w:rPr/w:sz` 时有值；继承自样式的字号不在此字段。
+     */
+    fontSize?: number;
+    /**
+     * 段落级默认粗体（`w:pPr/w:rPr/w:b`）。
+     * `true`  = 显式开启；`false` = 显式关闭（`w:val="0"`）；
+     * 字段不存在 = 未直接设置（继承自样式）。
+     */
+    bold?: boolean;
+    /**
+     * 大纲级别（`w:pPr/w:outlineLvl@w:val`），0–8 对应标题 1–9，9 表示正文。
+     * WPS / Word 的自定义标题样式通常在此字段直接编码级别，即使 basedOn 是 Normal。
+     * 字段不存在 = 未在段落级直接设置（继承自样式或默认值）。
+     */
+    outlineLevel?: number;
+    /**
+     * 段落是否直接挂有编号属性（`w:pPr/w:numPr` 存在且含 `w:numId@w:val != "0"`）。
+     * 用于列表检测：有编号属性的段落通常是列表项。
+     */
+    hasNumbering?: boolean;
+    /**
+     * 段落是否强制从新页起始（`w:pPr/w:pageBreakBefore`，#211）。
+     * true = 渲染该段时从新页开始（封面段的强信号之一）。
+     * 字段不存在 = 未在段落级直接设置（继承自样式或默认 false）。
+     */
+    pageBreakBefore?: boolean;
+    /**
+     * 段落是否承载节属性（`w:pPr/w:sectPr` 存在，#211）。
+     * true = 该段是其所属节的最后一段，节边界在此结束。
+     * 与 doc.sections.list() 的 lastParaId 字段对应。
+     */
+    hasSectionBreak?: boolean;
+    /**
+     * 段落内是否含手工分页符（`w:r/w:br[@w:type="page"]`，#211）。
+     * 与 pageBreakBefore 互补 —— 后者作用于段首，前者可出现在段中/段尾。
+     * 字段不存在 = 段内无手工分页符。
+     */
+    hasManualPageBreak?: boolean;
+    /**
+     * 段落级默认字体颜色（`w:pPr/w:rPr/w:color@w:val`，task-20260615-redhead-fingerprint）。
+     * 段标 run 颜色，作用于无独立 rPr 的 run。值为 6 位十六进制 `RRGGBB`（如 `FF0000`）或 `auto`。
+     * 仅当段落属性中显式设置了 `w:pPr/w:rPr/w:color` 时有值；继承自样式的颜色不在此字段。
+     *
+     * 用途（骨架化 / 排版的视觉簇判据）：判定"封面式文头"等需区分色异段（如红头）。
+     * 注意：行内首 run 的颜色单独由 {@link firstRunColor} 提供——很多文档把红色编码在 run 级
+     * 而非段标级，两者互补使用。
+     */
+    color?: string;
+    /**
+     * 段落**首个**直属 run（`w:r/w:rPr/w:color@w:val`）的字体颜色（task-20260615-redhead-fingerprint）。
+     * 值为 6 位十六进制 `RRGGBB` 或 `auto`。仅当首个直属 run 显式设了 `w:color` 时有值。
+     *
+     * 与 {@link color}（段标级）互补：红头/标题等视觉显著段的颜色常落在 run 级 rPr 而非段标 rPr，
+     * 需读首 run 才能拿到。取**首个直属 run**（非表格/文本框下钻），与 getParagraphText 的直属 run
+     * 语义对齐；段内多 run 颜色不一致时只反映首 run（满足"段首视觉身份"判据，不做整段聚合）。
+     */
+    firstRunColor?: string;
+}
+interface ListParagraphsOptions {
+    /** 默认 'body' */
+    scope?: ListParagraphsScope;
+    filter?: ListParagraphsFilter;
+    /** 默认 'full' */
+    textFormat?: ListParagraphsTextFormat;
+    /** 默认 `{ mode: 'byCount', pageSize: 25, pageIndex: 0 }`(不再有"智能默认") */
+    pagination?: ListParagraphsPagination;
+    /**
+     * 是否在结果中包含段落直接格式属性（`ParagraphFormat`）。
+     * 默认 `false`。开启后每个 `ParagraphInfo.format` 会携带从 `<w:pPr>` 读取的直接设置值。
+     * 仅包含直接设置的属性，不做样式继承计算。
+     */
+    includeFormat?: boolean;
+    /**
+     * 启用结构空白保真读（task-20260623-core-tab-faithful-read）。
+     * `true` 时 `ParagraphInfo.text` 含 `\t`（制表符）和 `\n`（软换行），
+     * 是 `appendSegmentsToRun` 的精确逆运算。
+     * 默认 `false`：只拼 `<w:t>`，偏移算术安全（与历史行为完全一致）。
+     */
+    structuralWhitespace?: boolean;
+    /**
+     * 是否在结果中包含段落所在表格的坐标信息（task-20260625-para-table-info）。
+     * 默认 `false`。
+     *
+     * 开启后，位于表格单元格内的段落会携带 `ParagraphInfo.table`（tableId / row / col）。
+     * 表格外段落的 `table` 字段不出现。
+     *
+     * 与 `includeFormat` 是独立开关：表格归属是结构信息，不是格式。
+     * 开启时会对每个段落做一次祖先链遍历（深度 ≤ 5），
+     * 并在首次调用时构建 `<w:tbl> Element → tableId` 反查映射（O(表格数)）。
+     */
+    includeTableInfo?: boolean;
+}
+interface ParagraphInfo {
+    paraId: string;
+    story: StoryId;
+    /** textFormat='preview' 时为首 100 字 */
+    text: string;
+    /** preview 模式被截断时为 true;full 模式/未截断不给 */
+    truncated?: boolean;
+    /** `<w:pStyle w:val>` 未设则缺 */
+    styleId?: string;
+    hasRevisions?: boolean;
+    hasComments?: boolean;
+    hasBookmarks?: boolean;
+    /**
+     * 段落子树是否含 OMML 公式对象（`<m:oMath>`，math namespace）。
+     * Word「插入→公式」生成的公式对象。纯文字写的"公式"（如 "F=ma"）不算。
+     * 含则为 true；不含时不给（与 hasComments 等同风格）。
+     */
+    hasMath?: boolean;
+    /**
+     * 段落直接格式属性。仅在 `listParagraphs` 传入 `includeFormat: true` 时存在。
+     * 不包含从样式继承的属性值。
+     */
+    format?: ParagraphFormat;
+    /**
+     * 段落所在表格坐标。仅当 `includeTableInfo=true` 且段落位于表格单元格内时存在。
+     *
+     * - `tableId`：与 `doc.tables.list()` / `getTable()` 使用的 id 完全一致（装载期
+     *   `buildIndices` 分配的 `tbl-NNNN`）。
+     * - `row`：所在 `<w:tr>` 在该表中的 0 基行号。
+     * - `col`：所在 `<w:tc>` 在该行中的 0 基列号（物理序号）。
+     *
+     * 注：`col` 是物理 `<w:tc>` 序号，**不**做 gridSpan / vMerge 的逻辑列号校正——
+     * 含合并单元格的表格中，物理序号与逻辑列号可能不同。v1 取物理序号已能满足
+     * "区分表格内/外编号序列"的主场景；如需精确逻辑列号，可在 v2 补充。
+     *
+     * 嵌套表格时报**最内层**的表格。
+     */
+    table?: {
+        tableId: string;
+        row: number;
+        col: number;
+    };
+}
+interface ListResult {
+    paragraphs: ParagraphInfo[];
+    pagination: {
+        mode: 'all' | 'byCount' | 'byChar';
+        pageIndex: number;
+        totalPages: number;
+        totalParagraphs: number;
+        hasNext: boolean;
+        /**
+         * 保留字段,当前实现恒不填(#24 把"≤500 段自动 all"的智能默认撤回,改为恒定
+         * byCount(25,0)默认;docs/03 §9.2)。调用方不应依赖。
+         */
+        autoPaginated?: boolean;
+    };
+}
+/** 默认分页:首页、25 条 */
+declare const DEFAULT_PAGINATION: ListParagraphsPagination;
+/** preview 截断字数 */
+declare const PREVIEW_CHAR_LIMIT = 100;
+declare function listParagraphs(pkg: Package, opts?: ListParagraphsOptions): ListResult;
+/**
+ * 按 paraId 精确取段。走 paraIdx → O(1) 命中后反查 story。不存在或所属 story 识别
+ * 不出(理论上只在 pkg 与 indices 脱钩时发生)返回 null。
+ *
+ * 总是返回 full 文本(无 textFormat/preview 选项,与 docs/03.1 §2 的签名一致)。
+ */
+declare function getParagraphByParaId(pkg: Package, indices: PackageIndices, paraId: string): ParagraphInfo | null;
+/**
+ * 从单个 `<w:p>` Element 构建 ParagraphInfo。
+ *
+ * 在 listParagraphs 内部给每个命中段落调用;**也供 `getParagraph`(#25)复用** ——
+ * 它通过 paraIdx 拿到 Element 后,用 `findStoryFor` 找到 story,再调这里组装。
+ */
+declare function buildParagraphInfo(story: StoryId, p: Element, textFormat?: ListParagraphsTextFormat, includeFormat?: boolean, runTextOpts?: RunTextOptions): ParagraphInfo;
+
+/**
+ * Comment 只读查询(docs/03.1 §1.5 / §2,#26)。
+ *
+ * 批注由两部分组成:
+ *   - **主体**(`<w:comment>` in comments.xml):id / author / date / 批注正文
+ *   - **锚点**(`<w:commentRangeStart>` / `<w:commentRangeEnd>` / `<w:commentReference>`
+ *     in body / headers / footers 等):标识被批注的范围
+ *
+ * `PackageIndices.commentIdx` 已在装载期把两边按 `w:id`(数字)串联。这里做:
+ *   - 读主体拿 author / date / text
+ *   - 用锚点 start / end 判 rangeKind(复用 [range-kind.ts](./range-kind.ts) 的
+ *     `classifyRange`)
+ *   - 由 start 元素反查 story(`findStoryFor`)
+ *
+ * 跟 bookmark 的字段差异:
+ *   - BookmarkInfo 的 `text` 字段 → CommentInfo 的 `anchorText` 字段(语义更明确)
+ *   - 没有 `hidden` 概念
+ */
+
+type CommentId = number;
+interface CommentInfo {
+    id: CommentId;
+    /** w:author,缺则 '' */
+    author: string;
+    /** w:date(ISO 8601);缺则 '' */
+    date: string;
+    /** 批注正文:`<w:comment>` 内所有 `<w:t>` 拼接 */
+    text: string;
+    rangeKind: 'paragraph' | 'text' | 'complex';
+    /** rangeKind = 'paragraph' | 'text' 时给(批注锚定的段落 paraId) */
+    paraId?: string;
+    /** rangeKind = 'text' 时给(start/end 之间的正文片段) */
+    anchorText?: string;
+}
+/**
+ * 枚举所有批注。
+ *
+ * 顺序按 `commentIdx` 的迭代序(Map 插入序;装载期按 part 遍历 + w:id 升序扫到)。
+ *
+ * 主体缺失(`entry.comment === null`)或锚点无 start/end 的批注 **被跳过** ——
+ * 调用方看到的永远是"主体 + 至少一个锚点"都有的条目。
+ */
+declare function listComments(indices: PackageIndices): CommentInfo[];
+/** 按 id 取单条批注。不存在或主体缺失返回 null */
+declare function getComment(indices: PackageIndices, id: CommentId): CommentInfo | null;
+
+/**
+ * Revision(修订)只读查询(docs/03.1 §1.5 / §2,#26 + #33)。
+ *
+ * **Tier 1 覆盖面**:只看 `<w:ins>` / `<w:del>` —— 这是 run 级的插入/删除修订,
+ * 承载 w:id / w:author / w:date 属性,以及子树内的 `<w:t>`(ins)/ `<w:delText>`(del)
+ * 作为涉及文本。
+ *
+ * **Tier 2 属性级修订**(#33 起显式拒绝):
+ *   - `<w:rPrChange>`(run 属性变更,在 `<w:rPr>` 里)
+ *   - `<w:pPrChange>`(段落属性变更,在 `<w:pPr>` 里)
+ *   - `<w:sectPrChange>` / `<w:tblPrChange>` / `<w:trPrChange>` / `<w:tcPrChange>` 等
+ *   - `<w:numberingChange>` / `<w:moveFrom>` / `<w:moveTo>` 等
+ *
+ * 扫到任一 Tier 2 元素即抛 `UNSUPPORTED_OOXML_FEATURE`(`listRevisions` 与
+ * `acceptRevisions` / `rejectRevisions` 共用此守护,保证读写一致)。
+ *
+ * scope 控制枚举的 story 集合(与 `listParagraphs` 共用 `resolveScope`)。
+ */
+
+type RevisionId = string;
+interface RevisionInfo {
+    revId: RevisionId;
+    kind: 'insert' | 'delete';
+    author: string;
+    date: string;
+    story: StoryId;
+    /** 修订归属的段落(若 ins/del 嵌在 `<w:p>` 里才有;极少数嵌在 `<w:body>` 直子层位的则缺) */
+    paraId?: string;
+    /** 涉及的文本(ins:全部 `<w:t>` 拼接;del:全部 `<w:delText>` 拼接)。为空串时省略 */
+    text?: string;
+}
+interface ListRevisionsOptions {
+    /** 默认 'body' */
+    scope?: 'body' | 'all' | StoryId[];
+}
+declare function listRevisions(pkg: Package, opts?: ListRevisionsOptions): RevisionInfo[];
+
+/**
+ * Section（节）查询（#211 / docs/03.1 §2）。
+ *
+ * 节边界由"承载 `<w:sectPr>` 的段"标定：
+ *   - 主 body 的最后一个 `<w:sectPr>` 是 body 直接子元素（不属于任何段），是最后一节
+ *   - 其余节的 sectPr 嵌在 `<w:p>/<w:pPr>/<w:sectPr>`，该段是节的最后一段
+ *
+ * 算法：遍历 body 直属节点（doc-order），收集 `<w:p>`，遇含 sectPr 的段闭合一节
+ *      （lastParaId = 该段 paraId）；body 末尾的散 sectPr 闭合最后一节。
+ *
+ * 节信息字段（消费方主要诉求来自 skeleton #195 封面检测）：
+ *   - sectionIndex / firstParaId / lastParaId：边界
+ *   - type：'nextPage' / 'continuous' / 'evenPage' / 'oddPage' / 'nextColumn'（缺省 = nextPage，OOXML 默认）
+ *   - headerRefs / footerRefs：resolve 到 partName，跨节比对页眉页脚是否相同
+ *   - titlePage：'首页不同' 设置（封面强信号）
+ */
+
+type SectionType = 'nextPage' | 'continuous' | 'evenPage' | 'oddPage' | 'nextColumn';
+type HeaderFooterType = 'default' | 'first' | 'even';
+interface HeaderFooterRef {
+    type: HeaderFooterType;
+    /** rels 目标 part 路径（如 'word/header1.xml'） */
+    partName: string;
+}
+interface SectionInfo {
+    sectionIndex: number;
+    firstParaId: string;
+    /** 节末段的 paraId（承载 sectPr 的段；最后一节为 body 末尾散 sectPr 时回退到 body 最后段）*/
+    lastParaId: string;
+    type?: SectionType;
+    headerRefs?: HeaderFooterRef[];
+    footerRefs?: HeaderFooterRef[];
+    /** w:sectPr/w:titlePg 存在 = 首页不同（封面强信号）*/
+    titlePage?: boolean;
+}
+declare function listSections(pkg: Package): SectionInfo[];
+
+/**
+ * 表格枚举与结构分析（#185）
+ *
+ * 为骨架化 M2 阶段（表格分类/取样/域化）提供表格数据。
+ *
+ * 设计原则：
+ * - 只走 getElementsByTagNameNS，禁用 XPath（性能约束，同 list-paragraphs.ts）
+ * - tableId 由 buildIndices 在装载期分配（tbl-0001 起），存入 tblIdx
+ * - 默认只枚举主文档 body（scope: 'body'），不含嵌套表格（includeNested: false）
+ * - 前后邻段落（prevParaId / nextParaId）只取紧邻兄弟 <w:p>，供题注绑定（#193）
+ */
+
+/**
+ * 行高（对照 columnWidths）。w:tr/w:trPr/w:trHeight。
+ *
+ * 空行塌缩正是 hRule+val 没带过去所致，两者必须一起读/写。
+ */
+interface RowHeight {
+    /** w:trHeight/@w:val，行高 twips（1 twip = 1/20 磅）*/
+    val: number;
+    /** w:trHeight/@w:hRule：auto(默认,最小高度) / atLeast(至少) / exact(精确)。
+     *  缺省（无 hRule 属性）按 OOXML 默认 'auto'。*/
+    hRule: 'auto' | 'atLeast' | 'exact';
+}
+/**
+ * 单个物理 <w:tc> 的 span 信息，携带文本与合并状态。
+ * cellGrid[i][j] 对应第 i 行第 j 个物理 <w:tc>。
+ */
+interface TableCellInfo {
+    /** 单元格纯文本（多段以 \n 连接），与 cells[i][j] 完全一致 */
+    text: string;
+    /** 水平合并跨列数（<w:gridSpan w:val>，无则默认 1） */
+    gridSpan: number;
+    /**
+     * 垂直合并状态：
+     *  'restart'  = 纵向合并的起始格（<w:vMerge w:val="restart"/>）
+     *  'continue' = 被并入上方格的续行占位格（<w:vMerge/> 无 val 或 val="continue"）
+     *  null       = 无纵向合并
+     */
+    vMerge: 'restart' | 'continue' | null;
+    /** Direct cell width from w:tcPr/w:tcW, in twips. */
+    width?: number;
+    /** Direct cell shading from w:tcPr/w:shd. */
+    shading?: {
+        fill?: string;
+        color?: string;
+        val?: string;
+    };
+    /** Direct vertical alignment from w:tcPr/w:vAlign. */
+    verticalAlignment?: 'top' | 'center' | 'bottom' | 'both';
+    /**
+     * 单元格首段（首个直属 `<w:p>`）的 paraId（w14:paraId）。无首段或首段缺 paraId 时 undefined。
+     *
+     * 用途（task-bug2-cell-image，决策点 C）：merge 重建表后要往**正确 cell** 插单元格图，
+     * 而 clone 出来的表 cell 段 paraId 是 cloneTableAfter 重分配的新值——调用方拿不到。
+     * 暴露 firstParaId 后，调用方对 clone 表再 `tables.list({includeCellTexts:true})` 即可拿到
+     * 每个 cell 首段 paraId，用 `plan.insertImageAfter(firstParaId)` 把图插进该 cell（insertImageAfter
+     * 在 anchor 的 parentNode 内插段——anchor 在 `<w:tc>` 里，新图段就落在该 cell 内）。
+     *
+     * 与 replaceTableCellText 无冲突：后者只动 cell **首段**的 run，插在首段之后的独立图段不受影响。
+     */
+    firstParaId?: string;
+    /**
+     * Direct paragraph ids in this cell, in cell content order.
+     *
+     * Nested table paragraphs are not included.
+     */
+    paragraphIds: string[];
+    /**
+     * Direct content blocks in this cell, in OOXML child-node order.
+     *
+     * Paragraph drawings are emitted as drawing blocks as well, so callers can
+     * preserve flows such as text paragraphs, then an image, then more text.
+     */
+    blocks: TableCellBlockInfo[];
+    /**
+     * 本单元格内直属 `<w:drawing>`（图片/形状等）的 drawingId 列表（与 drawingIdx 同 ID 空间）。
+     *
+     * 用途（task-bug2-cell-image，决策点 A1）：表格单元格内的图此前在 cellGrid 这层就丢了
+     * （cellGrid 只搬 cell 文字），导致单元格图在 structure 抽取阶段成孤儿（图字节在 word/media
+     * 但 body 无 blip 引用）。收录 drawingId 后，typeset 抽表时把 cell 图当 content 带出、merge
+     * 重建时用 `drawing.getImageBytes()` + `insertImageAfter(firstParaId)` 把图插回对应 cell。
+     *
+     * 收录范围：只取**本 cell 子树内、且不在嵌套表/嵌套 cell 内**的 drawing（嵌套表 cell 的图归属
+     * 嵌套表自己的 cellGrid，不上浮污染外层）。空（无图）时为 `[]`（与 cells 同条件填充，
+     * 字段恒在便于下游免判 undefined）。
+     */
+    imageDrawingIds: string[];
+}
+type TableCellBlockInfo = {
+    type: 'paragraph';
+    paraId: string;
+    text: string;
+} | {
+    type: 'drawing';
+    drawingId: string;
+    paraId?: string;
+} | {
+    type: 'table';
+    tableId: string;
+};
+interface TableInfo {
+    /** 分配的表格 ID（装载期顺序，'tbl-0001' 起），供 plan executor 引用 */
+    tableId: string;
+    /** 所在 part 路径（如 'word/document.xml'）*/
+    partPath: string;
+    /** 在本次枚举结果中的顺序（1-based）*/
+    index: number;
+    /** 是否嵌套在另一个表格内（祖先链上存在 <w:tbl>）*/
+    isNested: boolean;
+    /** 行数（w:tr 直接子元素数量）*/
+    rowCount: number;
+    /** 列数（w:tblGrid/w:gridCol 数量；无 tblGrid 时为 0）*/
+    colCount: number;
+    /** 是否有合并单元格（gridSpan > 1 或存在 vMerge）*/
+    hasMerge: boolean;
+    /** 表格样式 ID（w:tblPr/w:tblStyle @w:val），未设时 undefined */
+    tableStyleId?: string;
+    /** 是否包含图片（w:drawing 元素）*/
+    hasImages: boolean;
+    /** 是否包含嵌套表格（直接子孙 <w:tbl>）*/
+    hasNestedTables: boolean;
+    /**
+     * 紧邻前一个兄弟 <w:p> 的 paraId，用于题注绑定（#193）。
+     * 仅检查紧邻兄弟：若前一个兄弟不是 <w:p>（如另一个 <w:tbl>）则为 undefined。
+     */
+    prevParaId?: string;
+    /**
+     * 紧邻后一个兄弟 <w:p> 的 paraId，用于题注绑定（#193）。
+     * 仅检查紧邻兄弟。
+     */
+    nextParaId?: string;
+    /**
+     * 每列的列宽（twips，来自 `<w:tblGrid>/<w:gridCol w:w="...">`）。
+     *
+     * - `columnWidths[i]` = 第 i 列的 `w:w` 值（1 twip = 1/20 磅）
+     * - 无 `<w:tblGrid>` 时为 `[]`（空数组）
+     * - `tblLayout=fixed` 的表格列宽完全由此决定；`auto` 布局表格也记录但仅供参考
+     * - 供 merger 套用源表列宽（task-core-table-grid：克隆模板时保真列宽）
+     */
+    columnWidths: number[];
+    /**
+     * 每行行高，doc 序，每行一个；该行无 <w:trHeight> 则为 null。
+     *
+     * - `rowHeights[i]` = 第 i 行的 w:trPr/w:trHeight val+hRule
+     * - 恒填（不依赖 includeCellTexts）
+     * - 只取直属 <w:tr>，不误抓嵌套表行
+     * - 供 merger 套用源表行高（空行塌缩修复）
+     */
+    rowHeights: (RowHeight | null)[];
+    /**
+     * 单元格文本网格（#186）。仅当 `includeCellTexts: true` 时填充。
+     *
+     * - `cells[i][j]` = 第 i 行第 j 列单元格的纯文本
+     * - 单元格内含多段时用 `\n` 连接（保留分段信号，供 has-multi-content 判定）
+     * - 嵌套表格内的段落不展开（不污染外层网格）
+     */
+    cells?: string[][];
+    /**
+     * 单元格网格（span-aware），仅当 `includeCellTexts: true` 时填充（与 cells 同条件）。
+     *
+     * - `cellGrid[i][j]` 对应第 i 行第 j 个**物理** `<w:tc>`，携带 gridSpan/vMerge
+     * - 与 cells 同源同序：`cells[i][j] === cellGrid[i][j].text`
+     * - 嵌套表内段落不展开（与 extractCellTexts 一致）
+     */
+    cellGrid?: TableCellInfo[][];
+}
+interface ListTablesOptions {
+    /** 枚举范围（默认 'body'）*/
+    scope?: 'body' | 'all';
+    /** 是否包含嵌套在其他表格内的表格（默认 false，只返回顶层表格）*/
+    includeNested?: boolean;
+    /**
+     * 是否抽取单元格文本（#186）。默认 false（保持 #185 默认行为）。
+     *
+     * 开启后每张 TableInfo 会带 `cells: string[][]`，用于关键词匹配/分类。
+     * 性能：每张表会枚举所有 <w:tc> 及其直属 <w:p>，按需开启。
+     */
+    includeCellTexts?: boolean;
+}
+/**
+ * 枚举文档表格，按文档顺序返回（与 tblIdx 插入顺序一致）。
+ *
+ * - `scope: 'body'`（默认）—— 仅主文档 <w:body>
+ * - `includeNested: false`（默认）—— 跳过嵌套在其他表格内的表格
+ */
+declare function listTables(pkg: Package, indices: PackageIndices, opts?: ListTablesOptions): TableInfo[];
+/**
+ * 按 tableId 精确取单个表格，O(1)。不存在返回 null。
+ * 入参 `includeCellTexts` 与 `listTables` 同义（默认 false）。
+ */
+declare function getTableById(pkg: Package, indices: PackageIndices, tableId: string, opts?: {
+    includeCellTexts?: boolean;
+}): TableInfo | null;
+/** 一张格内图的预解析字节（按源 <a:blip @r:embed> 原始 rId 索引）。 */
+interface TableVerbatimImage {
+    originalRId: string;
+    bytes: Uint8Array;
+    contentType: string;
+}
+/** verbatim 取一张表的自包含 payload（供跨文档搬表 insertTableFrom）。 */
+interface TableVerbatim {
+    /** `<w:tbl>` 子树序列化字符串（命名空间随子树带入）。 */
+    tableXml: string;
+    /** 表内所有格内图的预解析字节（按原 rId）。原 rId 解析不到字节的图不收（搬入时 warn 降级）。 */
+    images: TableVerbatimImage[];
+}
+/**
+ * 按 tableId verbatim 取一张表的 OOXML 子树 + 其格内图字节，打包成自包含 payload。
+ *
+ * 这是"数据表 = 内容块"（§13.9）的**源侧读取**：调用方（typeset）拿到此 payload 后用
+ * `plan.insertTableFrom(...)` 把整表 verbatim 搬进输出文档（与图片 getImageBytes→insertImageAfter
+ * 同构）。表的行/列/值/合并/嵌套/格内图全保真——这里只做读取 + 序列化 + 解析格内图字节，
+ * **不裁剪、不重建**。
+ *
+ * tableId 不存在 → 返回 null。
+ */
+declare function getTableVerbatim(pkg: Package, indices: PackageIndices, tableId: string): TableVerbatim | null;
+
+/**
+ * Drawing 对象枚举（#189）
+ *
+ * 为骨架化 M3 阶段（图片分类/Shape 分类/占位图替换）提供 drawing 数据。
+ *
+ * 边界（实施前澄清，见 #189 评论）：
+ * - **本模块只做"枚举 + 形态信号"**，不下 A / B / C 业务分类结论
+ * - C 类细分（水印 / 装饰线 / 背景图）需语义判断，属于 #191
+ * - 分组键计算、代表样本选取属于 #191 / #192
+ * - 占位图替换属于 #190
+ *
+ * 设计原则（对齐 #185 list-tables.ts）：
+ * - 只走 getElementsByTagNameNS / 直接子节点遍历，禁用 XPath（性能约束）
+ * - drawingId 由 buildIndices 装载期分配（'dr-0001' 起），存入 drawingIdx
+ * - 默认枚举主文档 body（scope: 'body'）
+ * - 提供 isInHeaderFooter 字段，让 #191 直接识别 C 类页眉页脚 logo（无需自己查 part 路径）
+ */
+
+/** 锚定方式：inline（行内嵌入）/ anchor（浮动定位）*/
+type DrawingAnchoringMode = 'inline' | 'anchor';
+/**
+ * Drawing 内容形态（**OOXML 子树类型**，非 A/B/C 业务分类）。
+ *
+ * 识别优先级：a:graphicData @uri → 命中预设 URI 之一时按表分发；都不命中时落 'other'。
+ * 'textBox' 是 'shape' 的特化（wps:wsp 内含 w:txbxContent），单独抽出便于 #192 处理。
+ *
+ * | kind     | URI 或子元素信号                                                          | 典型场景 |
+ * |----------|---------------------------------------------------------------------------|----------|
+ * | picture  | uri = .../picture                                                          | 嵌入/浮动图片 |
+ * | chart    | uri = .../chart                                                            | Word 原生图表 |
+ * | smartArt | uri = .../diagram                                                          | SmartArt（1.0/2010+）|
+ * | shape    | uri = .../wordprocessingShape，且 **无** w:txbxContent                     | 形状（无文字） |
+ * | textBox  | uri = .../wordprocessingShape，且 **有** w:txbxContent                     | 文本框 / 标注 |
+ * | group    | uri = .../wordprocessingGroup                                              | 形状组合 |
+ * | canvas   | uri = .../wordprocessingCanvas                                             | 绘图画布 |
+ * | other    | 都不命中                                                                   | 未来扩展占位 |
+ */
+type DrawingKind = 'picture' | 'chart' | 'smartArt' | 'shape' | 'textBox' | 'group' | 'canvas' | 'other';
+type TextBoxBlockInfo = {
+    type: 'paragraph';
+    paraId: string;
+    text: string;
+} | {
+    type: 'drawing';
+    drawingId: string;
+    paraId?: string;
+} | {
+    type: 'table';
+    tableId: string;
+};
+/**
+ * 文字环绕方式（仅 anchor 有）。
+ *
+ * - none：wp:wrapNone（不环绕；配合 behindDoc 形成"衬于文字下方/上方"）
+ * - square：wp:wrapSquare（四周型 / 矩形环绕）
+ * - tight：wp:wrapTight（紧密型）
+ * - through：wp:wrapThrough（穿越型）
+ * - topAndBottom：wp:wrapTopAndBottom（上下型）
+ * - behind：wp:wrapNone + behindDoc="1"（衬于文字下方）
+ * - inFront：wp:wrapNone + behindDoc="0"（浮于文字上方）
+ */
+type DrawingWrapType = 'none' | 'square' | 'tight' | 'through' | 'topAndBottom' | 'behind' | 'inFront';
+/** 浮动定位的单方向描述（原值透传，由 #191 自行二次解释）*/
+interface DrawingPositionAxis {
+    /** wp:positionH/V @relativeFrom 原值（如 'page' / 'margin' / 'column' / 'character' / 'paragraph' / 'line'）*/
+    relativeFrom?: string;
+    /** wp:posOffset 文本内容（EMU 整数）。和 align 二选一。*/
+    posOffset?: number;
+    /** wp:align 文本内容（'left' / 'center' / 'right' / 'top' / 'bottom' / 'inside' / 'outside'）。和 posOffset 二选一。*/
+    align?: string;
+}
+/** 浮动位置（仅 anchor 有）*/
+interface DrawingPosition {
+    horizontal?: DrawingPositionAxis;
+    vertical?: DrawingPositionAxis;
+}
+interface DrawingInfo {
+    /** 装载期分配的 ID（'dr-NNNN'，从 0001 起），供 #190 / #191 / #192 引用 */
+    drawingId: string;
+    /** 所在 part 路径（'word/document.xml' / 'word/header1.xml' 等）*/
+    partPath: string;
+    /** 枚举结果顺序（1-based，与文档顺序一致）*/
+    index: number;
+    /** 锚定方式：inline 行内嵌入 / anchor 浮动定位 */
+    anchoringMode: DrawingAnchoringMode;
+    /** 内容形态（OOXML 层级，非业务分类）*/
+    kind: DrawingKind;
+    /**
+     * 显示尺寸（EMU；1 inch = 914400 EMU）。
+     * 来源：wp:extent @cx @cy。
+     * 未声明或解析失败时为 { cx: 0, cy: 0 }（保持字段必存在，避免下游需要判 undefined）。
+     */
+    extentEMU: {
+        cx: number;
+        cy: number;
+    };
+    /** 文字环绕方式（仅 anchor，inline 不含此字段）*/
+    wrap?: DrawingWrapType;
+    /** 浮动位置（仅 anchor，inline 不含此字段）*/
+    position?: DrawingPosition;
+    /**
+     * 承载此 drawing 的段落 paraId（w:p @w14:paraId）。
+     *
+     * 多数情况下，drawing 挂在 w:r 下、该 w:r 属于某个 w:p，本字段就是这个 w:p 的 paraId。
+     *
+     * **关键例外（CR 设计说明）**：嵌套在 **TextBox 内**（即位于 `w:txbxContent` 子树）
+     * 的 drawing，本字段为 `undefined`。这是**主动设计**：textBox 内段落与外层段落是两套
+     * 独立的段落流，把外层段落 paraId 挂给文本框内 drawing 会让"删段落 → 顺带删图"等
+     * 操作误伤外层段落。下游需要文本框内图片的段落引用时，应：
+     *  1. 用 `runIndex === undefined && anchorParaId === undefined` 识别该情形
+     *  2. 自行向上找最近的 `w:txbxContent`，再用其外层 anchor 段落定位
+     *
+     * 缺 paraId 时也为 undefined（合法但少见；由 ensureParaIds 在装载期补齐，但本字段
+     * 不依赖这一保证）。
+     */
+    anchorParaId?: string;
+    /**
+     * 在所在段落里的 run 序号（0-based，承载 drawing 的 w:r 在父 w:p 直接子 w:r 中的位置）。
+     * 同段多 drawing 时用于区分；用于题注绑定（#193）/ 占位图替换（#190）的精确引用。
+     */
+    runIndex?: number;
+    /**
+     * 是否位于页眉页脚 part（contentType 以 .header+xml / .footer+xml 结尾）。
+     *
+     * 这是**形态信号**，不是 C 类结论。#191 在做 A/B/C 业务分类时：
+     * - true + kind = picture → 大概率 C 类页眉页脚 logo，由 .dot 原生保留
+     * - 其余情况由 #191 自行判断
+     */
+    isInHeaderFooter: boolean;
+    /**
+     * 形态信号：是否含 pic:pic 子树（A 类正向信号）。
+     * - kind = 'picture' 时必为 true
+     * - 理论上 chart/shape 也可能套 pic:pic，此时 kind 不变但本字段为 true
+     */
+    hasPicReference: boolean;
+    /**
+     * Shape 专属：是否为「线条 / 连接线（line / connector）」几何。仅 kind = 'shape' 时可能为 true，
+     * 其余 kind（picture/chart/.../textBox/group/canvas/other）一律 undefined。
+     *
+     * **形态信号，非业务结论**。下游（skeleton #192 shape-role）用它把版记横线一类「纯几何线条」
+     * 与矩形/椭圆等装饰噪声区分开：线条原样保留，其余几何仍按现状裁掉。
+     *
+     * 识别（命中任一即 true，从强到弱）：
+     *  1. DrawingML 预设几何：`<a:prstGeom prst="...">` 的 prst 命中线条/连接线预设
+     *     （line / straightConnector1 / bentConnectorN / curvedConnectorN，N=2..5；见 LINE_CONNECTOR_PRESETS）
+     *  2. 连接线非可视属性：wps:wsp 内含 `<wps:cNvCnPr>`（connector non-visual props；
+     *     普通 shape 用 wps:cNvSpPr，连接线用 wps:cNvCnPr）
+     *  3. VML 回退：子树含 `<v:line>`（mc:Fallback 内的旧版降级线条）
+     *
+     * 母版实测（生成的公文__会议纪要.docx）：版记 3 根横线均 prst="line" + wps:cNvCnPr + v:line 三信号齐全；
+     * 红头艺术字文本框是 prst="rect" + wps:cNvSpPr，不命中。
+     */
+    isLineOrConnector?: boolean;
+    /**
+     * Shape / TextBox 专属：是否有边框（a:spPr/a:ln 存在且未声明 a:noFill）。
+     * 非 shape/textBox 一律 undefined。
+     */
+    hasBorder?: boolean;
+    /**
+     * Shape / TextBox 专属：是否有填充（a:spPr 下含 a:solidFill / a:gradFill / a:blipFill / a:pattFill）。
+     * 显式 a:noFill 视作无填充。非 shape/textBox 一律 undefined。
+     */
+    hasFill?: boolean;
+    /**
+     * TextBox 专属：是否含实质内部文字（w:txbxContent 内 w:t 文本拼接后非空）。
+     * 非 textBox 一律 undefined。
+     */
+    hasInnerText?: boolean;
+    /**
+     * TextBox 专属：内部文字原文（w:txbxContent 内全部 w:t 文本按文档顺序拼接后 trim）。
+     *
+     * 供下游（skeleton #192 / typeset 投影）读取红头艺术字等内容型文本框的原文做语义命名/字段化
+     * （如「江临市滨河区人民政府」「专题会议纪要」）。
+     *
+     * 语义：
+     *  - 仅 kind = 'textBox' 时可能有值；非 textBox 一律 undefined。
+     *  - trim 后为空（无文字 / 仅空白）→ undefined（与 hasInnerText=false 对应）。
+     *  - 多段 / 多 run 文本框按 w:t 出现顺序直接拼接，**不插入换行/空格**（保持与 hasInnerText
+     *    同源的拼接口径）；下游需要分段语义时应自行用 paragraphs API 处理，本字段只给原文快照。
+     */
+    innerText?: string;
+    /**
+     * TextBox 专属：文本框内容流里的段落 paraId，按文档顺序排列。
+     *
+     * 这些 paraId 指向 `w:txbxContent` 内部段落。调用方可通过
+     * `doc.paragraphs.get(paraId)` 或 `TextBoxDrawing.getParagraphs()` 继续进行段落/文字级操作。
+     * 非 textBox 一律 undefined。
+     */
+    innerParagraphIds?: string[];
+    /**
+     * TextBox 专属：文本框内容流的直接内容块，按 OOXML child-node 顺序排列。
+     *
+     * 目前包含 direct paragraph、paragraph 内 direct drawing，以及 direct table。
+     * 非 textBox 一律 undefined。
+     */
+    innerBlocks?: TextBoxBlockInfo[];
+    /**
+     * TextBox 专属：首个内部段落的对齐（w:txbxContent 第一段 w:pPr/w:jc @val）。
+     *
+     * 注：文本框内可能多段且对齐不同，#192 需自行决定如何取代表值；本字段只提供首段值便于快速分组。
+     * 非 textBox 或无 jc 设置一律 undefined。
+     */
+    innerTextAlign?: string;
+}
+interface ListDrawingsOptions {
+    /**
+     * 枚举范围（默认 'body'）。
+     * - 'body'：仅主文档 body（不含页眉页脚 / 注释 / 脚注尾注）
+     * - 'all'：所有 stories（body + headers + footers + footnotes + endnotes + comments）
+     *
+     * 注意：#189 的 isInHeaderFooter 字段只在 'all' 模式下才可能为 true；
+     * 'body' 模式下页眉页脚 drawing 不会被枚出。
+     */
+    scope?: 'body' | 'all';
+    /**
+     * 启用结构空白保真读（task-20260623-core-tab-faithful-read）。
+     * `true` 时 TextBox 的 `innerText` 含 `\t`（制表符）和 `\n`（软换行）——
+     * 是 `appendSegmentsToRun` 的精确逆运算。
+     * 默认 `false`：只拼 `<w:t>`（与历史行为一致）。
+     */
+    structuralWhitespace?: boolean;
+}
+/** 判断 drawing 是否嵌套在另一个 drawing 内（用于 group / canvas 内子图过滤的预判）*/
+declare function hasDrawingAncestor(drawing: Element): boolean;
+/**
+ * 枚举文档 drawing 对象，按文档顺序返回（与 drawingIdx 插入顺序一致）。
+ *
+ * - `scope: 'body'`（默认）—— 仅主文档 body 内的 drawing
+ * - `scope: 'all'` —— 包含 headers / footers / footnotes / endnotes / comments
+ *
+ * **不做**业务分类（A/B/C）/ 分组键计算 / 代表样本选取 —— 这些属于 #191/#192。
+ * 嵌套在另一个 drawing 内的子 drawing（如 group 的成员、canvas 的成员）**会被一并枚出**，
+ * 由调用方按 hasDrawingAncestor 自行决定是否合并到外层（保持枚举层"完整暴露"的原则）。
+ */
+declare function listDrawings(pkg: Package, indices: PackageIndices, opts?: ListDrawingsOptions): DrawingInfo[];
+/**
+ * 按 drawingId 精确取单个 drawing。不存在返回 null。
+ *
+ * **index 字段语义**：返回 drawing 在 **全局 drawingIdx 插入顺序**中的 1-based 位置
+ *  —— 与 `listDrawings({ scope: 'all' })` 的 index 一致；与 `listDrawings({ scope: 'body' })`
+ * 的 1-based 位置**不一定**相等（后者可能过滤掉了页眉页脚 drawing）。
+ *
+ * 复杂度：drawingIdx 查找 O(1)；全局序号扫描 O(N)，N = 包内 drawing 总数。
+ * 调用方需要严格按 scope 取序号时应直接走 listDrawings。
+ *
+ * 旧实现复用了 list-tables.ts 的 `index: 0` 哨兵，下游用 `index` 排序/引用会拿到
+ * 错误值（CR BUG-1）—— 改为真实序号。
+ */
+declare function getDrawingById(pkg: Package, indices: PackageIndices, drawingId: string): DrawingInfo | null;
+/**
+ * 装载期构建 drawingIdx：枚举 Package 中所有 Word 内容 part 的 <w:drawing>，
+ * 按文档顺序分配 'dr-NNNN' ID。由 buildIndices 调用。
+ *
+ * 内部函数风格对齐 buildTableIndex（list-tables.ts）。
+ */
+declare function buildDrawingIndex(parts: Iterable<{
+    contentType: string;
+    xmlDom?: {
+        getElementsByTagNameNS(ns: string, local: string): {
+            length: number;
+        } & Record<number, Element>;
+    };
+}>): Map<string, Element>;
+
+interface ImageBytesResult {
+    bytes: Uint8Array;
+    contentType: string;
+    extentEMU: {
+        cx: number;
+        cy: number;
+    };
+}
+/**
+ * 读取 drawingId 对应 picture 的原始图片字节。
+ * drawingId 不存在 / 非 picture / media 找不到 → 返回 null（不抛）。
+ */
+declare function getImageBytesSync(pkg: Package, indices: {
+    drawingIdx: Map<string, Element>;
+}, drawingId: string): ImageBytesResult | null;
+
+export { type TableVerbatimImage as $, A_NS as A, type BookmarkEntry as B, type CommentInfo as C, type DrawingInfo as D, type ListParagraphsScope as E, type ListParagraphsTextFormat as F, type ListStoriesOptions as G, type HeaderFooterRef as H, type ImageBytesResult as I, PIC_NS as J, PKG_NS as K, type ListParagraphsOptions as L, MC_NS as M, PREVIEW_CHAR_LIMIT as N, type ParagraphFormat as O, type PackageIndices as P, R_NS as Q, type RevisionInfo as R, type StoryId as S, type TableInfo as T, type RunTextOptions as U, type SectionType as V, type SplitResult as W, type Story as X, type StoryKind as Y, type StyleType as Z, type TableCellBlockInfo as _, type ListResult as a, VML_NS as a0, W14_NS as a1, WPC_NS as a2, WPG_NS as a3, WPS_NS as a4, WP_NS as a5, W_NS as a6, XML_NS as a7, buildDrawingIndex as a8, buildIndices as a9, buildParagraphInfo as aa, buildStylesIndex as ab, findStoryFor as ac, getComment as ad, getDrawingById as ae, getParagraphByParaId as af, getParagraphRuns as ag, getParagraphText as ah, getRunText as ai, getStoryParagraphs as aj, getStyleById as ak, getTableById as al, getTableVerbatim as am, hasDrawingAncestor as an, listComments as ao, listDrawings as ap, listParagraphs as aq, listRevisions as ar, listSections as as, listStories as at, listStyles as au, listTables as av, resolveScope as aw, splitRunAt as ax, getImageBytesSync as ay, type ParagraphInfo as b, type CommentId as c, type ListRevisionsOptions as d, type ListStylesOptions as e, type StyleInfo as f, type ListTablesOptions as g, type TableVerbatim as h, type ListDrawingsOptions as i, type SectionInfo as j, type RowHeight as k, type TableCellInfo as l, BookmarkLoadError as m, type BookmarkLoadErrorCode as n, CHART_NS as o, type CommentEntry as p, DEFAULT_PAGINATION as q, DGM_NS as r, type DrawingAnchoringMode as s, type DrawingKind as t, type DrawingPosition as u, type DrawingPositionAxis as v, type DrawingWrapType as w, type HeaderFooterType as x, type ListParagraphsFilter as y, type ListParagraphsPagination as z };