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

package/dist/word.d.cts

@@ -0,0 +1,3042 @@
+import { S as StoryId, P as PackageIndices, L as ListParagraphsOptions, a as ListResult, b as ParagraphInfo, C as CommentInfo, c as CommentId$1, d as ListRevisionsOptions, R as RevisionInfo, e as ListStylesOptions, f as StyleInfo, g as ListTablesOptions, T as TableInfo, h as TableVerbatim, i as ListDrawingsOptions, D as DrawingInfo, I as ImageBytesResult, j as SectionInfo, k as RowHeight, l as TableCellInfo } from './view-DX2YAG5A.cjs';
+export { A as A_NS, B as BookmarkEntry, m as BookmarkLoadError, n as BookmarkLoadErrorCode, o as CHART_NS, p as CommentEntry, q as DEFAULT_PAGINATION, r as DGM_NS, s as DrawingAnchoringMode, t as DrawingKind, u as DrawingPosition, v as DrawingPositionAxis, w as DrawingWrapType, H as HeaderFooterRef, x as HeaderFooterType, y as ListParagraphsFilter, z as ListParagraphsPagination, E as ListParagraphsScope, F as ListParagraphsTextFormat, G as ListStoriesOptions, M as MC_NS, J as PIC_NS, K as PKG_NS, N as PREVIEW_CHAR_LIMIT, O as ParagraphFormat, Q as R_NS, U as RunTextOptions, V as SectionType, W as SplitResult, X as Story, Y as StoryKind, Z as StyleType, _ as TableCellBlockInfo, $ as TableVerbatimImage, a0 as VML_NS, a1 as W14_NS, a2 as WPC_NS, a3 as WPG_NS, a4 as WPS_NS, a5 as WP_NS, a6 as W_NS, a7 as XML_NS, a8 as buildDrawingIndex, a9 as buildIndices, aa as buildParagraphInfo, ab as buildStylesIndex, ac as findStoryFor, ad as getComment, ae as getDrawingById, af as getParagraphByParaId, ag as getParagraphRuns, ah as getParagraphText, ai as getRunText, aj as getStoryParagraphs, ak as getStyleById, al as getTableById, am as getTableVerbatim, an as hasDrawingAncestor, ao as listComments, ap as listDrawings, aq as listParagraphs, ar as listRevisions, as as listSections, at as listStories, au as listStyles, av as listTables, aw as resolveScope, ax as splitRunAt } from './view-DX2YAG5A.cjs';
+import { a as Package } from './types-BVkkdcfh.cjs';
+import { b as SnapshotInfo, C as ChangeLog, S as SnapshotStorageAdapter } from './types-C2vQfM-b.cjs';
+
+/**
+ * w14:paraId 装载时 normalize —— docs/03 §11.2 / §13.6。
+ *
+ * 语义:
+ *   - 扫 Package 里所有 XML part,对缺 `w14:paraId` 的 `<w:p>` 分配随机 8 位十六进制 id
+ *   - **package 全局唯一**(body / headers / footers / footnotes / endnotes / comments 同集合)
+ *   - 发生分配的 part 被 markDirty,便于后续 toZip / toFlatOpc 重 serialize
+ *   - 10 万段落 ≈ 40ms(实测基线,见 bench/xml-stack-worker)
+ */
+
+interface EnsureParaIdsResult {
+    /** 本次新分配的 paraId 数量 */
+    added: number;
+    /** 扫描到的 <w:p> 总数(含既有 paraId) */
+    total: number;
+    /** 发生分配的 part path 列表 */
+    touchedParts: string[];
+}
+/**
+ * 为 Package 内所有缺 w14:paraId 的 <w:p> 分配随机 id(package 全局唯一)。
+ *
+ * 发生分配的 part 会被 markDirty。
+ */
+declare function ensureParaIds(pkg: Package): EnsureParaIdsResult;
+
+/**
+ * Bookmark 只读查询(docs/03.1 §1.5 / §2,#25)。
+ *
+ * 基于 `PackageIndices.bookmarkIdx`(#13 建好)做 O(1) 反查,没有任何 fontoxpath
+ * 调用。rangeKind 判定走 DOM 遍历(孩子顺序 + 同 `<w:p>` 判断)。
+ *
+ * 三类 rangeKind(docs/03.1 §1.5):
+ *   - `'paragraph'` —— start / end 在**同一 `<w:p>`** 中,且 `<w:bookmarkStart>`
+ *     之前没有任何内容节点、`<w:bookmarkEnd>` 之后也没有 —— 即书签覆盖整段的"内容区"
+ *   - `'text'` —— 同一 `<w:p>`,但 start / end 不在段首/段尾(书签仅覆盖段内文本片段)
+ *   - `'complex'` —— 跨段落、缺 end、start / end parent 不同、或 parent 不是 `<w:p>`
+ *     (表 cell、body 直子等),core 不简单建模,只标 kind
+ *
+ * `hidden`:name 以 `_` 开头(如 `_Toc123` / `_GoBack` / `_Hlk12345`)。`listBookmarks`
+ * 默认过滤;`getBookmark(name)` 不过滤(调用方已知 name)。
+ */
+
+type BookmarkName$1 = string;
+interface BookmarkInfo {
+    name: BookmarkName$1;
+    story: StoryId;
+    rangeKind: 'paragraph' | 'text' | 'complex';
+    /** rangeKind = 'paragraph' | 'text' 时给(书签所属的段落 paraId,大写 8 hex) */
+    paraId?: string;
+    /** rangeKind = 'text' 时给(start / end 之间所有 `<w:t>` 的纯文本拼接) */
+    text?: string;
+    /** name 以 `_` 开头时 true;否则缺字段 */
+    hidden?: boolean;
+}
+interface ListBookmarksOptions {
+    /** 默认 false。true 时返回所有书签,包括 `_` 开头的隐藏书签 */
+    includeHidden?: boolean;
+    /**
+     * 名字前缀过滤(大小写敏感)。提供时只返回 `name.startsWith(prefix)` 的书签。
+     *
+     * 配合 `InsertParagraphSpec.bookmark.prefix` 的规则化命名(`{prefix}_{anchorParaId}` /
+     * 冲突时 `{prefix}_{anchorParaId}_2` 等)使用,可批量回查"某语义标签下的所有书签"。
+     * `_` 开头的隐藏书签若未设置 `includeHidden=true` 仍被过滤(prefix 与 hidden 是
+     * 独立轴)。
+     */
+    prefix?: string;
+}
+declare function listBookmarks(pkg: Package, indices: PackageIndices, opts?: ListBookmarksOptions): BookmarkInfo[];
+declare function getBookmark(pkg: Package, indices: PackageIndices, name: BookmarkName$1): BookmarkInfo | null;
+
+type ContextSearchScope = 'body' | 'all';
+interface ContextSearchInclude {
+    paragraphs?: boolean;
+    tables?: boolean;
+    headings?: boolean;
+    bookmarks?: 'none' | 'metadata' | 'coveredText';
+    comments?: 'none' | 'anchors';
+    revisions?: 'none' | 'flag' | 'visibleText';
+    headersFooters?: boolean;
+    footnotesEndnotes?: boolean;
+}
+interface ContextSearchOptions {
+    query: string;
+    keywords?: string[];
+    scope?: ContextSearchScope;
+    include?: ContextSearchInclude;
+    context?: {
+        before?: number;
+        after?: number;
+    };
+    limit?: number;
+    bookmarkFilter?: {
+        name?: string;
+        prefix?: string;
+        includeHidden?: boolean;
+    };
+}
+interface ContextSearchResult {
+    matches: ContextSearchMatch[];
+    truncated?: boolean;
+}
+interface ContextSearchMatch {
+    matchId: string;
+    score: number;
+    reason: 'keyword' | 'bookmark' | 'heading' | 'table' | 'metadata';
+    target: ContextSearchTarget;
+    text: string;
+    highlights?: ContextSearchHighlight[];
+    before?: ContextBlock[];
+    after?: ContextBlock[];
+    headingPath?: string[];
+    flags?: {
+        hasComments?: boolean;
+        hasRevisions?: boolean;
+    };
+    bookmarks?: ContextBookmark[];
+}
+interface ContextSearchHighlight {
+    text: string;
+    start: number;
+    end: number;
+}
+type ContextSearchTarget = {
+    kind: 'paragraph';
+    paraId: string;
+    story: string;
+} | {
+    kind: 'tableCell';
+    tableId: string;
+    row: number;
+    col: number;
+    paraId?: string;
+    story: string;
+} | {
+    kind: 'bookmark';
+    bookmarkName: string;
+    rangeKind: 'paragraph' | 'text' | 'complex';
+    paraId?: string;
+    story: string;
+} | {
+    kind: 'heading';
+    paraId: string;
+    story: string;
+};
+interface ContextBlock {
+    paraId: string;
+    story: string;
+    text: string;
+    table?: {
+        tableId: string;
+        row: number;
+        col: number;
+    };
+}
+interface ContextBookmark {
+    name: string;
+    rangeKind: 'paragraph' | 'text' | 'complex';
+    writable: boolean;
+}
+declare function searchContext(pkg: Package, indices: PackageIndices, options: ContextSearchOptions): ContextSearchResult;
+
+/**
+ * TOC 域查询（#197）。
+ *
+ * 识别文档中的 TOC（目录）域：
+ *   - complex field：`<w:fldChar w:fldCharType="begin">` … `end`，depth 计数跳过嵌套子域
+ *   - simple field：`<w:fldSimple w:instr="TOC ...">` 单段闭合
+ *
+ * 只识别域名前缀匹配 `/^TOC\b/i` 的域，PAGEREF / HYPERLINK 等子域不收集。
+ *
+ * 嵌套处理：depth 计数器跟踪 fldChar 深度；instr 只在 depth=1（最外层）时收集。
+ * complex TOC 的 firstParaId/lastParaId 是 begin/end fldChar 所在段；中间段也在区间内。
+ */
+
+interface TocFieldRange {
+    /** 文档顺序索引（0-based） */
+    tocIndex: number;
+    /** TOC 域第一段的 paraId（complex field = fldChar begin 段；simple field = fldSimple 段）*/
+    firstParaId: string;
+    /** TOC 域最后一段的 paraId（complex field = fldChar end 段；simple field = firstParaId）*/
+    lastParaId: string;
+    /**
+     * 域指令文本（拼接所有 instrText / fldSimple@w:instr，trim 后）。
+     * 示例：`'TOC \\o "1-3" \\h \\z \\u'`
+     */
+    instr: string;
+}
+declare function listTocFields(pkg: Package): TocFieldRange[];
+
+/**
+ * change-events —— `WordDocument.on('change', ...)` 的类型定义。
+ *
+ * 文档变更事件在 `kernel.applyPlan()` 成功后触发,涵盖两条入口:
+ *   - `doc.plan().apply()`        →  source = 'plan'
+ *   - `doc.executeCode(script)`   →  source = 'script'(脚本内调 `doc.applyPlan`)
+ *
+ * **不**触发的场景:
+ *   - 空 plan(`ops.length === 0`)—— kernel 直接返回,不算一次变更
+ *   - applyPlan 抛错回滚 —— 文档状态未变
+ *   - 脚本绕过 kernel.applyPlan 直接改 `doc.getPackage()` 的 DOM —— v1 不覆盖,
+ *     此类用法被视作"自负其责";后续可加 dirty-watcher,但代价大。
+ *
+ * Payload 默认只带 `ops` + `result` + `source`,**不**带全文档 —— 全文档输出
+ * (toFlatOpc / toZip)在 worker 模式下要 RPC + serialize,10 万段落级别可达数百 ms,
+ * 不是"白送"的开销。订阅时通过 `fullDocument: 'flatOpc' | 'zip'` 显式开启,本模块
+ * 在派发前由 WordDocument 一次性拉取(多订阅者共享)。
+ */
+
+/**
+ * Kernel 内部的 change event payload —— 走 worker 边界时被 structured-clone,
+ * 因此所有字段必须是 plain JSON。
+ */
+interface KernelChangeEvent {
+    /** 触发本次 apply 的 op 队列(完整传出,便于审计 / 重放) */
+    ops: Op[];
+    /** kernel.applyPlan 的返回值 */
+    result: ApplyResult;
+    /**
+     * 'plan'   = 走 RPC `applyPlan`(`doc.plan().apply()` 路径)
+     * 'script' = 走 `doc.applyPlan(...)`(`doc.executeCode(...)` 内部脚本路径)
+     *
+     * 由触发层(kernel-handlers / script-execute)显式标注;kernel.applyPlan 自己不知道
+     * 来源,只接收 `opts.source`。
+     */
+    source: 'plan' | 'script';
+}
+/**
+ * `WordDocument.on('change', handler)` 收到的 payload。比 KernelChangeEvent 多了
+ * 可选的全文档字段 —— 是否填充由订阅时的 `fullDocument` 决定。
+ */
+interface ChangeEvent extends KernelChangeEvent {
+    /** 仅当 `subscribe.fullDocument === 'flatOpc'` 时存在 */
+    flatOpc?: string;
+    /** 仅当 `subscribe.fullDocument === 'zip'` 时存在 */
+    zip?: Uint8Array;
+}
+/** 订阅选项;默认 `fullDocument: 'none'`(只发 metadata,不付全文档输出代价)。 */
+interface ChangeSubscribeOptions {
+    /**
+     * - `'none'`(默认):payload 只含 `{ ops, result, source }`
+     * - `'flatOpc'`:派发前调一次 `toFlatOpc()`,payload.flatOpc 填充 XML 字符串
+     * - `'zip'`:派发前调一次 `toZip()`,payload.zip 填充 docx 字节
+     *
+     * **代价警示**:`'flatOpc'` / `'zip'` 在 worker 模式下要 RPC + structured-clone
+     * 整篇文档,大文档一次几百 ms;只在确实要"快照式消费"时启用。多订阅者共享同一次
+     * 拉取,因此打开多个 'flatOpc' 订阅不会重复跑。
+     */
+    fullDocument?: 'none' | 'flatOpc' | 'zip';
+}
+/** 订阅回调;可同步可 async。WordDocument 串行 await 每个订阅者,保证派发顺序与变更顺序一致。 */
+type ChangeListener = (ev: ChangeEvent) => void | Promise<void>;
+/** RPC event 通道里 word change 事件的 `event` 字符串常量。 */
+declare const WORD_CHANGE_EVENT = "word.change";
+
+type DomainCacheState = 'empty' | 'ready' | 'dirty';
+type DomainCacheName = 'all' | 'paragraphs' | 'tables';
+interface ParagraphDomainCacheSnapshot {
+    state: DomainCacheState;
+    listAllBodyReady: boolean;
+    cachedParagraphIds: string[];
+    dirtyReason?: string;
+    buildCount: number;
+}
+interface WordDomainCacheSnapshot {
+    revision: number;
+    paragraphs: ParagraphDomainCacheSnapshot;
+    tables: TableDomainCacheSnapshot;
+}
+interface TableDomainCacheSnapshot {
+    state: DomainCacheState;
+    cachedProfiles: string[];
+    cachedTableIds: string[];
+    dirtyReason?: string;
+    buildCount: number;
+}
+
+/** Kernel.load 的输入 */
+type KernelLoadSource = {
+    type: 'zip';
+    bytes: Uint8Array;
+} | {
+    type: 'flat-opc';
+    xml: string;
+};
+interface KernelLoadParams {
+    source: KernelLoadSource;
+    docId: string;
+}
+/**
+ * 装载 / rebuild 进度回调。
+ *
+ * - load 使用 `'fetch' | 'parse' | 'normalize'`(LoadPhase 对齐)
+ * - rebuildFromParts(#22)使用 `'parse' | 'build-indices' | 'done'`
+ *
+ * 上层 WordDocument.rollback 会把 phase 作为字符串透传,不强制 union 收敛。
+ */
+type KernelProgress = (phase: string, pct?: number) => void;
+/**
+ * Kernel —— 持有单一 WordDocument 的内部状态。
+ *
+ * 一个 WordDocument 代理对应一个 Kernel。生命周期由代理控制:load → 多次操作 → dispose。
+ */
+declare class Kernel {
+    private pkg?;
+    private indices?;
+    private docId?;
+    private initialBytes?;
+    private initialFlatOpc?;
+    private disposed;
+    private readonly domainCache;
+    /**
+     * change 事件订阅者(applyPlan 成功后 fan-out)。InlineTransport 直接订阅;worker
+     * 模式下 worker 内创建 Kernel 时由 worker entry 订阅一个把事件 post 到主线程的
+     * 中转 listener(详见 kernel-worker-shared.ts)。
+     *
+     * 监听器异常被静默吞掉 —— 一个订阅者抛错不该影响其它订阅者,也不该影响 applyPlan
+     * 的返回值(applyPlan 已经成功提交,事件只是事后通知)。
+     */
+    private readonly changeListeners;
+    /**
+     * applyPlan 互斥链 —— 串行化所有 applyPlan 调用,不论来源(plan / script)。
+     *
+     * 必要性:applyPlan 内部对 `pkg.parts[*].xmlDom` 做 deepClone(transaction
+     * snapshot)+ 同步 mutate + 索引重建。多个 applyPlan 在 microtask 边界穿插
+     * 时:
+     *   - 多份 deepClone 同时占内存(50w 字 doc × 并发数 → WPS WebView OOM)
+     *   - A 的 dispatch 与 B 的 dispatch 在共享 xmlDom 上交错,paraIdx 错位
+     *   - A 的回滚 snapshot 包含 B 的 mutation,A 失败回滚会 wipe B 的写
+     *   - finally 里 buildIndices 互相覆盖
+     *
+     * 用 promise chain 串行化:每次 applyPlan 等前一个完成才进入 inner。链上
+     * resolve 永不 reject —— 把 inner 的成功/失败结果在外层 await 时直接抛给
+     * 调用方,链本身只保证"前一个跑完了"。
+     */
+    private _applyPlanChain;
+    load(params: KernelLoadParams, onProgress?: KernelProgress): Promise<void>;
+    toZip(): Promise<Uint8Array>;
+    toFlatOpc(): Promise<string>;
+    /**
+     * 段落查询。纯同步,基于当前已装载的 pkg。
+     *
+     * 所有策略(scope / filter / textFormat / pagination)由入参决定,kernel **不**
+     * 做"智能默认"——未传 pagination 时按 `DEFAULT_PAGINATION`(byCount(25,0))返回
+     * 第一页;要全量请显式 `{ pagination: { mode: 'all' } }`(docs/03 §9.2)。
+     *
+     * 纯逻辑实现在 `list-paragraphs.ts`,本方法只做:装载态校验 + pkg 传入 + 错误
+     * 包装(validation Error → WordError,附 docId)。
+     */
+    listParagraphs(opts?: ListParagraphsOptions): ListResult;
+    /**
+     * 按 paraId 精确取段(#25)。走 paraIdx → O(1) 查找;不存在返回 null。
+     * paraId 大小写不敏感(索引 key 是大写 8 hex)。
+     */
+    getParagraph(paraId: string): ParagraphInfo | null;
+    /**
+     * 枚举书签(#25)。默认过滤 `_` 开头的隐藏书签(_Toc... / _GoBack / _Hlk...),
+     * `opts.includeHidden=true` 可拿到全部。返回顺序遵循 bookmarkIdx 的迭代序 ——
+     * JS Map 按插入序,装载期从上到下、逐 part 逐 `<w:bookmarkStart>` 收集。
+     */
+    listBookmarks(opts?: ListBookmarksOptions): BookmarkInfo[];
+    /**
+     * 按 name 精确取书签(#25)。走 bookmarkIdx;不存在返回 null。
+     * 不做 hidden 过滤 —— 调用方已知 name,通常就是来找隐藏书签的。
+     */
+    getBookmark(name: BookmarkName$1): BookmarkInfo | null;
+    /**
+     * 枚举批注(#26)。走 commentIdx,按 Map 插入序(= 装载期 part 顺序 + w:id 升序)
+     * 返回。主体缺失或无锚点的 entry 被跳过 —— 调用方看到的都是"可用"的批注。
+     */
+    listComments(): CommentInfo[];
+    /**
+     * 按 id 取批注(#26)。不存在或主体缺失返回 null 。
+     */
+    getComment(id: CommentId$1): CommentInfo | null;
+    /**
+     * 枚举修订(#26 + #33,Tier 1)。只覆盖 `<w:ins>` / `<w:del>` 标签级修订。
+     *
+     * **#33 加强**:扫到 `<w:rPrChange>` / `<w:pPrChange>` / `sectPrChange` /
+     * `numberingChange` / `moveFrom` / `moveTo` 等 Tier 2 属性级修订 → 抛
+     * `UNSUPPORTED_OOXML_FEATURE`(以前是默默忽略)。读写共用守护,与
+     * `acceptRevisions` / `rejectRevisions` 行为一致。
+     *
+     * scope 与 `listParagraphs` 一致:默认 'body',可传 'all' 或 `StoryId[]`。
+     */
+    listRevisions(opts?: ListRevisionsOptions): RevisionInfo[];
+    getRevision(revId: string, opts?: ListRevisionsOptions): RevisionInfo | null;
+    searchContext(opts: ContextSearchOptions): ContextSearchResult;
+    /** 列出 styles.xml 中的样式，可按 type 过滤。styles.xml 不存在时返回空数组。 */
+    listStyles(opts?: ListStylesOptions): StyleInfo[];
+    /** 按 styleId 精确查找，O(1)。不存在返回 null。 */
+    getStyle(styleId: string): StyleInfo | null;
+    /** 枚举表格，默认只返回主文档 body 的顶层表格。*/
+    listTables(opts?: ListTablesOptions): TableInfo[];
+    /** 按 tableId 精确取单个表格，O(1)。不存在返回 null。 */
+    getTable(tableId: string): TableInfo | null;
+    /**
+     * 按 tableId verbatim 取一张表的 OOXML 子树 + 格内图字节
+     * （task-20260616-table-content-driven，供跨文档搬表 insertTableFrom）。
+     * 不存在返回 null。
+     */
+    getTableVerbatim(tableId: string): TableVerbatim | null;
+    /** 枚举 drawing 对象，默认只返回主文档 body 内的 drawing。*/
+    listDrawings(opts?: ListDrawingsOptions): DrawingInfo[];
+    /** 按 drawingId 精确取单个 drawing，O(1)。不存在返回 null。 */
+    getDrawing(drawingId: string): DrawingInfo | null;
+    /**
+     * 读取 drawingId 对应 picture 的原始图片字节（task-insert-image）。
+     * drawingId 不存在 / 非 picture / media 找不到 → 返回 null（不抛）。
+     */
+    getImageBytes(drawingId: string): ImageBytesResult | null;
+    /** 枚举主 body 的所有节（#211）。doc-order 排序。*/
+    listSections(): SectionInfo[];
+    /** 枚举主 body 的所有 TOC 域（#197）。doc-order 排序。*/
+    listTocFields(): TocFieldRange[];
+    /**
+     * 执行 WordPlan 提交的 op 队列(docs/03.1 §3.2)。
+     *
+     * **#27 作用域**:本方法只承担 **Plan 容器 + ApplyResult 结构 + 错误状态机**。
+     * 真正的 op executor 由后续 PR 分别落地(见 `plan.ts` 顶部注释)。因此本版本:
+     *   - ops 为空 → 返回 `EMPTY_APPLY_RESULT`(WordPlanImpl 侧通常已拦,这里兜底)
+     *   - ops 非空 → 抛 `UNSUPPORTED_OOXML_FEATURE`,message 指向待落地的 issue
+     *
+     * 注意:事务原子性(#16 runTransaction)+ 索引同步 + trackChanges 包装,都在首个
+     * executor(#28)落地时接入。本 PR 不引入 executor registry,避免为空抽象付代价;
+     * #28 直接在这里改成 switch(op.type) 即可。
+     */
+    /**
+     * 执行 Plan op 队列(docs/03.1 §3.2)。
+     *
+     * 流程:
+     *   1. 预扫 affected parts(每个 op 触达的 part path)
+     *   2. `runTransaction` 包裹 dispatch 循环 —— 任一 op throw → 全回滚
+     *   3. 成功后重建三索引(paraIdx / bookmarkIdx / commentIdx)—— executor 可能
+     *      增删元素,最简单的保真方式是 buildIndices 一次性重跑
+     *
+     * 返回 Promise 因 runTransaction 是 async;#27 的 sync 签名承诺在 RPC 层
+     * (handler `await` + `transport.call` 自带 await)对调用方完全透明。
+     */
+    applyPlan(params: ApplyPlanParams, opts?: {
+        source?: 'plan' | 'script';
+    }): Promise<ApplyResult>;
+    validatePlan(params: ApplyPlanParams): Promise<PlanValidationResult>;
+    private _applyPlanInner;
+    /**
+     * 订阅 applyPlan 成功事件。返回取消订阅函数。
+     *
+     * 监听器同步触发(在 applyPlan 内部 fan-out),抛错被吞掉(不影响其它订阅者
+     * 与 applyPlan 返回)。要做 async 工作请在监听器内自行 catch 并 fire-and-forget。
+     */
+    onChange(listener: (ev: KernelChangeEvent) => void): () => void;
+    private emitChange;
+    /**
+     * 序列化当前 pkg 为 snapshot 用的 parts 数组。
+     * 优化:
+     *   - dirty=false 且有 _originalBytes → 直接复用原始字节(零 serialize,Uint8Array 引用共享)
+     *   - dirty=true 的 XML part → slimdom serialize
+     *   - 二进制 part → 用 bytes / _originalBytes
+     */
+    serializeParts(): SnapshotPartEntry[];
+    /**
+     * 从 snapshot 的 parts 数组重建 pkg + 三索引。
+     *
+     * 覆盖原 pkg:调用方应在 rollback 前确保 dispose/ 清理 transient 状态(如 changelog)。
+     * 重建后 ensureParaIds + buildIndices 再跑一次,保证索引准确(docs/03.2 §10)。
+     *
+     * onProgress 分阶段上报(docs/03.2 §6):
+     *   - `'parse'`        每个 part 被 parse 完成时,pct 0→100
+     *   - `'build-indices'` buildIndices 开始前,pct 0
+     *   - `'done'`         全部完成,pct 100
+     */
+    rebuildFromParts(parts: readonly SnapshotPartEntry[], onProgress?: KernelProgress): void;
+    dispose(): void;
+    /** @internal */
+    getDocId(): string | undefined;
+    /** @internal */
+    getPackage(): Package | undefined;
+    /** @internal */
+    getIndices(): PackageIndices | undefined;
+    /** @internal */
+    getInitialBytes(): Uint8Array | undefined;
+    /** @internal */
+    getInitialFlatOpc(): string | undefined;
+    /** @internal */
+    isDisposed(): boolean;
+    /** @internal */
+    debugCacheSnapshot(): WordDomainCacheSnapshot;
+    /** @internal */
+    debugInvalidateCache(domain?: DomainCacheName, reason?: string): void;
+    private assertLoaded;
+    private assertNotDisposed;
+}
+/** Kernel.serializeParts / rebuildFromParts 的 entry 形态(与 SnapshotPayload.parts 一致) */
+interface SnapshotPartEntry {
+    path: string;
+    contentType: string;
+    bytes: Uint8Array;
+}
+
+type KernelMethod = 'load' | 'toZip' | 'toFlatOpc' | 'dispose' | 'serializeParts' | 'rebuildFromParts' | 'paragraphs.list' | 'paragraphs.get' | 'bookmarks.list' | 'bookmarks.get' | 'comments.list' | 'comments.get' | 'context.search' | 'revisions.list' | 'revisions.get' | 'styles.list' | 'styles.get' | 'tables.list' | 'tables.get' | 'tables.getVerbatim' | 'drawings.list' | 'drawings.get' | 'drawings.getImageBytes' | 'validatePlan' | 'sections.list' | 'tocFields.list' | 'applyPlan';
+
+/**
+ * Transport —— WordDocument(主线程代理)与 Kernel 之间的分发抽象。
+ *
+ * 两种实现:
+ *   - `InlineTransport`:kernel 跑在主线程,call 直接委托到 kernelHandlers
+ *   - `WorkerTransport`(worker-transport.ts):kernel 跑在 Worker,call 通过 postMessage
+ *     编码成 RPC 消息,等待 response
+ *
+ * Transport 对外形态相同 → WordDocument 不需感知模式。
+ */
+
+interface Transport {
+    /** 调用 kernel 方法;onProgress 用于流式进度(装载等) */
+    call<T>(method: KernelMethod, args: unknown[], onProgress?: KernelProgress): Promise<T>;
+    /**
+     * 在 kernel 同上下文执行一段用户脚本(04.2 §六)。与 `call` 平级,**不**进
+     * `KernelMethod` 联合 —— `KernelMethod` 表"数据 API",脚本执行是另一类能力。
+     *
+     * @param code 用户 JS 源码;函数体形态(允许顶层 await / return)
+     * @param args 传给脚本的参数,经 structured clone 过 worker 边界
+     * @param timeoutMs 超时毫秒数;0 = 不超时
+     * @param signal 可选 AbortSignal(#151):
+     *               - WorkerTransport:abort 触发 → terminate worker + reload 路径
+     *                 (复用 #144 timeout reload 实施;pending RPC reject 为 \`WORKER_RELOADED\`)
+     *               - InlineTransport:abort 触发 → race 拒绝(主线程立即返回,但脚本
+     *                 仍在主线程后台跑直到自然结束 —— inline 无 worker 可 terminate)
+     * @returns 脚本顶层 return 的值(structured-cloneable)
+     * @throws  语法错误 / 脚本运行错 / 超时 / abort
+     */
+    executeScript(code: string, args: Record<string, unknown> | undefined, timeoutMs: number, signal?: AbortSignal): Promise<unknown>;
+    /** 释放底层资源(worker 模式下 terminate worker) */
+    dispose(): Promise<void>;
+    /**
+     * 可选:订阅 reload 完成事件。Worker 模式下每次 crash + reload 成功后触发;
+     * InlineTransport 不触发(inline 无 reload 语义)。返回取消订阅函数。
+     *
+     * 主要用途(#23):SnapshotApi 订阅此事件,在 worker reload 完成后重建内存态
+     * (nextId / changelog)——worker reload 会丢失主线程侧的自增栈,需要从 adapter
+     * 重读已持久化快照重建 nextId。详见 docs/03.2 §9.1。
+     *
+     * Listener 可返回 Promise;transport 会串行 await 每个 listener 完成后再 flush
+     * reload 期间排队的 RPC,避免 queued 的 take() 在 nextId 重建前执行。
+     */
+    onReload?(listener: () => void | Promise<void>): () => void;
+    /**
+     * 订阅 kernel 推出的 change 事件(applyPlan 成功后触发,涵盖 plan / script 两条入口)。
+     * 返回取消订阅函数。
+     *
+     * - InlineTransport:直接转发 kernel.onChange
+     * - WorkerTransport:监听 RpcEvent('word.change'),fan-out 给本地订阅者
+     *
+     * payload 是 `KernelChangeEvent`(精简版,不含全文档);WordDocument 上层根据订阅
+     * 选项再决定是否拉取 toFlatOpc / toZip。监听器同步触发,抛错被吞掉。
+     */
+    onChange(listener: (ev: KernelChangeEvent) => void): () => void;
+}
+/** Inline:kernel 直接在主线程 */
+declare class InlineTransport implements Transport {
+    readonly kernel: Kernel;
+    constructor();
+    call<T>(method: KernelMethod, args: unknown[], onProgress?: KernelProgress): Promise<T>;
+    executeScript(code: string, args: Record<string, unknown> | undefined, timeoutMs: number, signal?: AbortSignal): Promise<unknown>;
+    dispose(): Promise<void>;
+    onChange(listener: (ev: KernelChangeEvent) => void): () => void;
+}
+
+/**
+ * WordError —— Word core 的统一错误模型(docs/03.1 §4)。
+ *
+ * 所有面向消费方的错误都用 WordError 抛出。`code` 枚举覆盖装载期 / 查询 / 变更前置 / Plan 状态
+ * 四大类。`docId` 由 core 自动填充(WordDocument 内捕获底层错误后重抛时注入),方便日志
+ * 与多文档场景定位。
+ */
+type WordErrorCode = 'PACKAGE_CORRUPT' | 'PACKAGE_UNSUPPORTED_FORMAT' | 'BOOKMARK_NAME_DUPLICATE_ON_LOAD' | 'BOOKMARK_NAME_EMPTY_ON_LOAD' | 'WORKER_CREATION_FAILED' | 'WORKER_RELOADED' | 'PARA_NOT_FOUND' | 'BOOKMARK_NOT_FOUND' | 'COMMENT_NOT_FOUND' | 'REVISION_NOT_FOUND' | 'TABLE_NOT_FOUND' | 'DRAWING_NOT_FOUND' | 'TEXT_NOT_FOUND_IN_PARA' | 'BOOKMARK_NAME_EXISTS' | 'BOOKMARK_NAME_INVALID' | 'ANCHOR_CONFLICT' | 'UNSUPPORTED_OOXML_FEATURE' | 'INVALID_ARGUMENT' | 'PLAN_ALREADY_APPLIED' | 'PLAN_EMPTY' | 'CONTENT_LOST';
+declare class WordError extends Error {
+    readonly code: WordErrorCode;
+    readonly docId: string;
+    readonly details: Record<string, unknown>;
+    constructor(code: WordErrorCode, message: string, docId: string, details?: Record<string, unknown>);
+}
+
+/**
+ * SDT (Structured Document Tag, Content Control) XML 构建器 —— #188 表格域化。
+ *
+ * 设计:
+ *   - 三种子类型: Plain Text / Date Picker / Rich Text
+ *   - 输出 inline SDT (作 <w:r> 兄弟出现在 <w:p> 内), 段落 pPr 由调用方保留
+ *   - SDT id 由调用方传入 (典型: hash 输入对象保证幂等), 避免 builder 维护全局状态
+ *   - rPr 可由调用方拷贝原 run 的 rPr 传入, 保留字体 / 颜色 / 字号等字符属性
+ *
+ * SDT id 取值: OOXML 规定 32-bit signed integer; Word 加载时容错并按需重分配,
+ * 调用方不必严格保证全局唯一, hash 取值即可。
+ *
+ * 参考: ECMA-376 §17.5 Structured Document Tags。
+ */
+/**
+ * SDT 配置 (JSON-serializable, 可走 plan op RPC)。
+ *
+ * `rPr` 字符属性透传不在 spec 内 —— DOM Element 不能 JSON 序列化, 由 executor 在
+ * 替换时从原 run 直接克隆并传给 `buildInlineSdt` 的 `rPr` 参数。
+ */
+interface SdtSpecBase {
+    /** UI 显示名 (Word "Click here..." 上方的提示标签) */
+    alias: string;
+    /**
+     * 程序匹配 tag (后续模板填充阶段按 tag 定位 SDT)。
+     * 缺省时按 `alias` trim + 空白转 `_`。
+     */
+    tag?: string;
+    /** 占位提示文本; 缺省 `"请输入" + alias` */
+    placeholderText?: string;
+}
+interface PlainTextSdtSpec extends SdtSpecBase {
+    kind: 'text';
+}
+interface DateSdtSpec extends SdtSpecBase {
+    kind: 'date';
+    /** 日期格式 (e.g. "yyyy-M-d"), 缺省 "yyyy-M-d" */
+    dateFormat?: string;
+    /** Locale, 缺省 "zh-CN" */
+    locale?: string;
+}
+interface RichTextSdtSpec extends SdtSpecBase {
+    kind: 'richText';
+}
+type SdtSpec = PlainTextSdtSpec | DateSdtSpec | RichTextSdtSpec;
+/**
+ * 构建一个 inline SDT 元素 (`<w:sdt>`), 用于段落内 run 替换场景。
+ *
+ * 结构:
+ *   <w:sdt>
+ *     <w:sdtPr>
+ *       (rPr?)
+ *       <w:alias w:val="..."/>
+ *       <w:tag   w:val="..."/>
+ *       <w:id    w:val="..."/>
+ *       <w:placeholder><w:docPart w:val="DefaultPlaceholder_-1854013440"/></w:placeholder>
+ *       <w:showingPlcHdr/>
+ *       (类型标记: <w:text/> | <w:date.../> | <w:richText/>)
+ *     </w:sdtPr>
+ *     <w:sdtContent>
+ *       <w:r>(rPr?)<w:t xml:space="preserve">placeholderText</w:t></w:r>
+ *     </w:sdtContent>
+ *   </w:sdt>
+ *
+ * @param doc       owner Document (来自 paragraph.ownerDocument)
+ * @param spec      SDT 配置 (JSON-serializable)
+ * @param id        32-bit 整数 ID; 推荐用 hashSdtId(tableId, row, col, alias) 算
+ * @param rPr       可选, 从原 run 克隆的 `<w:rPr>` —— 字符属性透传, 同时挂到
+ *                  sdtPr 与 sdtContent 内 placeholder run 上
+ */
+declare function buildInlineSdt(doc: Document, spec: SdtSpec, id: number, rPr?: Element): Element;
+/**
+ * 由 (tableId, row, col, alias) 算 SDT id (djb2 hash → 32-bit signed)。
+ *
+ * 幂等性保证: 同一组输入永远产出同一 id, 重跑骨架化不会因 id 变化制造无意义 diff。
+ */
+declare function hashSdtId(tableId: string, row: number, col: number, alias: string): number;
+
+/**
+ * WordPlan —— 变更 builder + apply 机制(docs/03.1 §3,#27)。
+ *
+ * 职责(本 PR):
+ *   - 11 个链式 builder 方法 `return this`,**不返回 op 句柄**;每个方法只把 op
+ *     push 进内部队列,错误集中到 `apply()` 抛(契约 §4.2)
+ *   - `apply()` 状态机:
+ *       - 二次 apply → `PLAN_ALREADY_APPLIED`
+ *       - 空 plan → console.warn 不抛(契约默认语义;严格模式留未来)
+ *       - 非空 plan → transport RPC 到 kernel 的 `applyPlan`
+ *   - 多 plan 并存独立,不共享状态(每次 `doc.plan()` 新实例)
+ *
+ * **不含**任何 op 的真正执行 —— executor 一 PR 一张,#28 起陆续落地:
+ *   - #28: replaceParagraph / replaceTextInParagraph
+ *   - #29: insertParagraphBefore/After / deleteParagraph
+ *   - #34: createBookmark / deleteBookmark
+ *   - #35: addComment / deleteComment
+ *   - #31/#32: acceptRevisions / rejectRevisions
+ *
+ * 当前 kernel 侧 `applyPlan` 对任何非空 ops 直接抛 `UNSUPPORTED_OOXML_FEATURE`。
+ */
+
+type ParaId = string;
+type BookmarkName = string;
+type CommentId = number;
+type RevisionId = string;
+/** 段落级定位 */
+interface ParagraphRange {
+    paraId: ParaId;
+}
+/** 段落内关键词定位 */
+interface TextRange$1 {
+    paraId: ParaId;
+    text: string;
+    /** 默认 'first' */
+    scope?: 'first' | 'all';
+}
+type Range = ParagraphRange | TextRange$1;
+type RevisionScope = {
+    scope: 'all';
+} | {
+    scope: 'paragraph';
+    paraId: ParaId;
+} | {
+    scope: 'revision';
+    revId: RevisionId;
+};
+interface ParagraphDirectFormat {
+    alignment?: 'left' | 'center' | 'right' | 'both' | 'distribute';
+    outlineLevel?: number;
+    pageBreakBefore?: boolean;
+    indent?: {
+        left?: number;
+        right?: number;
+        /**
+         * Positive value writes first-line indent; negative value writes hanging indent.
+         */
+        firstLine?: number;
+    };
+    spacing?: {
+        before?: number;
+        after?: number;
+        line?: number;
+        lineRule?: 'auto' | 'exact' | 'atLeast';
+    };
+}
+interface TableCellDirectFormat {
+    shading?: {
+        /** 6-digit hex fill color without '#', or 'auto'. */
+        fill?: string;
+        /** 6-digit hex foreground color without '#', or 'auto'. */
+        color?: string;
+        /** OOXML shading pattern. Defaults to 'clear' when only fill is provided. */
+        val?: string;
+    };
+    verticalAlignment?: 'top' | 'center' | 'bottom' | 'both';
+    /** Cell width in twips, written as tcW type='dxa'. */
+    width?: number;
+}
+interface InsertParagraphSpec {
+    text: string;
+    /** 'inherit'(默认)继承 anchor 的 `<w:pPr>`;字符串为 styleId */
+    style?: 'inherit' | string;
+    /**
+     * 控制新段内容 run 的 `<w:rPr>` 来源。
+     *
+     * - `'default'`(默认)：裸 run,不附加任何 rPr,行为与未传时完全一致。
+     * - `'inherit'`：克隆 anchor 段**首个直属 `<w:r>`** 的 `<w:rPr>`(深拷贝 cloneNode(true))
+     *   并应用到新段的内容 run。常用于「簇展开」场景:样式写在直接格式(rPr)而非命名样式上。
+     *   anchor 无直属 run 或首 run 无 rPr 时退化为 `'default'`(不报错)。
+     *   与 `color` 共存时:先继承 rPr,再由 color 覆盖/追加 `<w:color>`(color 优先级更高)。
+     *   与 `style` 正交:style 管 pPr,runFormat 管 rPr,可独立组合。
+     */
+    runFormat?: 'inherit' | 'default';
+    /**
+     * 整段文字的字体颜色,6 位十六进制无 `#`(如 `'0070C0'` 标准蓝)。
+     * 留空则继承样式默认色。
+     * 颜色作为 run-level `<w:rPr><w:color w:val="..."/></w:rPr>` 写入新段唯一 run。
+     */
+    color?: string;
+    /**
+     * 从指定段（任意 `paraId`）克隆 pPr + 首 run rPr 到新段（全文重组场景）。
+     *
+     * - **优先级最高**：同时传 `style` / `runFormat` 时以 `styleSource` 为准（pPr + rPr 都来自 styleSource）。
+     * - pPr：深拷贝 `<w:pPr>`；styleSource 段无 pPr 则新段也不加 pPr（退化，不报错）。
+     * - rPr：克隆 styleSource 段**首个直属 `<w:r>`** 的 `<w:rPr>`；无直属 run 或首 run 无 rPr 则退化裸 run（不报错）。
+     * - styleSource 段**不存在**时抛 `PARA_NOT_FOUND`。
+     * - styleSource 段自身只读，不被修改。
+     * - 与 `color` 共存：先克隆 rPr，再 color 覆盖/追加 `<w:color>`（color 优先，同 #12）。
+     * - `styleSource === anchor` 时退化为 `style:'inherit' + runFormat:'inherit'` 效果（#12 兼容）。
+     */
+    styleSource?: ParaId;
+    /**
+     * 可选:插入段的同时**原子地**建一个跨段书签,range 涵盖 anchor 段 → 新插段。
+     *
+     * 调用方只声明命名规则(`prefix`),不传具体名 —— 系统按 `{prefix}_{anchorParaId}`
+     * 生成,冲突自动追加 `_2`/`_3` 后缀;实际名通过 `ApplyResult.createdBookmarks[i].name`
+     * 回传(同一 entry 的 `range` 给 fromParaId / toParaId)。
+     *
+     * `prefix` 校验:必须匹配 `^[A-Za-z_][A-Za-z0-9_]*$`(允许 `_` 起头作 Word hidden
+     * bookmark);最终名长度受 OOXML 40 字符上限约束,过长抛 `BOOKMARK_NAME_INVALID`。
+     *
+     * trackChanges=true 时本字段触发 `UNSUPPORTED_OOXML_FEATURE`(与 createBookmark
+     * 的现状一致,#31 再统一处理)。
+     */
+    bookmark?: {
+        prefix: string;
+    };
+    /**
+     * 段落大纲级别（Word outline level），写入 `<w:pPr><w:outlineLvl w:val="N"/>`。
+     *
+     * - 取值 **0–8**（对应 Word「1 级标题…9 级标题」；heading-1→0, heading-2→1, …）。
+     * - 省略（`undefined`）：不写 outlineLvl，保持 styleSource 克隆来的 pPr 原样。
+     * - 0–8：在新段 pPr 写入/覆盖 `<w:outlineLvl>`（显式值优先于 styleSource 克隆来的）。
+     * - 越界（< 0 或 > 8）：抛 `INVALID_ARGUMENT`。
+     */
+    outlineLevel?: number;
+    /**
+     * 段前分页（Word「段前分页」），写入 `<w:pPr><w:pageBreakBefore/>`。
+     *
+     * - `true`：该段强制从新页起始（比手工 `<w:br type="page"/>` 更鲁棒：绑在段上不随内容漂移）。
+     * - 省略（`undefined`）/ `false`：不写该元素（继承样式或默认）。
+     */
+    pageBreakBefore?: boolean;
+}
+interface PlanOptions {
+    /** 默认 false */
+    trackChanges?: boolean;
+    /** 默认走 `WordDocument.setDefaultAuthor` 配置的值 */
+    author?: string;
+    /** 默认 `new Date()` */
+    date?: Date;
+}
+type Op = {
+    type: 'replaceParagraph';
+    paraId: ParaId;
+    text: string;
+    onAnchorConflict: 'error' | 'drop';
+    /** 保留段内含图形的 run（w:drawing / w:pict / wps:wsp / v:line / w:object）。
+     *  默认 false（现有行为：整段所有 run 全删）。
+     *  true 时：只删纯文字 run，图形 run 原位保留；新文字 run 插在首个被删文字 run 位置。 */
+    keepInlineGraphics?: boolean;
+} | {
+    type: 'replaceTextInParagraph';
+    paraId: ParaId;
+    search: string;
+    replacement: string;
+    scope: 'first' | 'all';
+} | {
+    type: 'formatTextInParagraph';
+    paraId: ParaId;
+    search: string;
+    format: {
+        bold?: boolean;
+        color?: string;
+        italic?: boolean;
+        underline?: boolean;
+        highlight?: string;
+        fontSize?: number;
+        fontFamily?: string;
+    };
+    scope: 'first' | 'all';
+} | {
+    type: 'formatParagraph';
+    paraId: ParaId;
+    format: ParagraphDirectFormat;
+} | {
+    type: 'insertParagraphBefore';
+    anchorParaId: ParaId;
+    spec: InsertParagraphSpec;
+} | {
+    type: 'insertParagraphAfter';
+    anchorParaId: ParaId;
+    spec: InsertParagraphSpec;
+} | {
+    type: 'insertParagraphAtBodyStart';
+} | {
+    type: 'deleteParagraph';
+    paraId: ParaId;
+    onAnchorConflict: 'error' | 'drop';
+} | {
+    type: 'createBookmark';
+    name: BookmarkName;
+    range: Range;
+} | {
+    type: 'deleteBookmark';
+    name: BookmarkName;
+} | {
+    type: 'addComment';
+    range: Range;
+    text: string;
+    author?: string;
+    /** RPC 友好:按 ISO 8601 字符串序列化;builder 端接 Date,push 前 toISOString */
+    date?: string;
+} | {
+    type: 'deleteComment';
+    commentId: CommentId;
+} | {
+    type: 'acceptRevisions';
+    scope: RevisionScope;
+} | {
+    type: 'rejectRevisions';
+    scope: RevisionScope;
+} | {
+    type: 'addTableComment';
+    tableId: string;
+    text: string;
+    author?: string;
+    /** ISO 8601 字符串 */
+    date?: string;
+} | {
+    type: 'deleteTable';
+    tableId: string;
+    onAnchorConflict: 'error' | 'drop';
+} | {
+    type: 'replaceTableCellWithSdt';
+    tableId: string;
+    /** 0-based 行索引(对应 TableInfo.cells 网格的 i)*/
+    row: number;
+    /** 0-based 列索引(对应 cells[i] 的 j) */
+    col: number;
+    sdt: SdtSpec;
+    onAnchorConflict: 'error' | 'drop';
+} | {
+    type: 'deleteTableRow';
+    tableId: string;
+    /** 0-based 行索引(按删除时刻表格状态计) */
+    row: number;
+    onAnchorConflict: 'error' | 'drop';
+} | {
+    type: 'replaceTableCellText';
+    tableId: string;
+    /** 0-based 行索引(对应 TableInfo.cells 网格的 i)*/
+    row: number;
+    /** 0-based 列索引(对应 cells[i] 的 j)*/
+    col: number;
+    text: string;
+    onAnchorConflict: 'error' | 'drop';
+} | {
+    type: 'formatTableCell';
+    tableId: string;
+    /** 0-based row index, matching TableInfo.cellGrid[row][col]. */
+    row: number;
+    /** 0-based column index, matching TableInfo.cellGrid[row][col]. */
+    col: number;
+    format: TableCellDirectFormat;
+} | {
+    type: 'insertTableCellParagraph';
+    tableId: string;
+    /** 0-based row index, matching TableInfo.cellGrid[row][col]. */
+    row: number;
+    /** 0-based column index, matching TableInfo.cellGrid[row][col]. */
+    col: number;
+    /** Plain text for the new paragraph. */
+    text: string;
+    /** Insert before the first direct cell content block or after the last one. */
+    position: 'start' | 'end';
+} | {
+    type: 'replaceDrawingWithPlaceholder';
+    drawingId: string;
+} | {
+    type: 'deleteDrawing';
+    drawingId: string;
+} | {
+    type: 'replaceShapeInnerText';
+    drawingId: string;
+    placeholder: string;
+} | {
+    type: 'insertTableRow';
+    tableId: string;
+    templateRow: number;
+    position: number | 'end';
+    cellTexts?: string[];
+} | {
+    type: 'cloneTableAfter';
+    anchorParaId: ParaId;
+    sourceTableId: string;
+} | {
+    type: 'insertImageAfter';
+    anchorParaId: ParaId;
+    bytes: Uint8Array;
+    contentType: string;
+    widthEmu: number;
+    heightEmu: number;
+} | {
+    type: 'insertTableFrom';
+    anchorParaId: ParaId;
+    tableXml: string;
+    images?: Array<{
+        originalRId: string;
+        bytes: Uint8Array;
+        contentType: string;
+    }>;
+    styleTblPrXml?: string;
+} | {
+    type: 'setTableColumnWidths';
+    tableId: string;
+    widths: number[];
+} | {
+    type: 'setTableRowHeights';
+    tableId: string;
+    heights: (RowHeight | null)[];
+} | {
+    type: 'setUpdateFields';
+    enabled: boolean;
+};
+interface ApplyResult {
+    /** 插入段落产生的新 paraId,按 op 顺序 */
+    insertedParagraphs: Array<{
+        opIndex: number;
+        anchorParaId: ParaId;
+        position: 'before' | 'after';
+        newParaId: ParaId;
+    }>;
+    /**
+     * `insertParagraphAtBodyStart` 在 body 起始合成的空段 paraId，按 op 顺序。
+     * 调用方据此拿到锚点 paraId 做后续重建（与 insertedParagraphs 分开，语义清晰）。
+     */
+    insertedBodyStartParaIds: ParaId[];
+    /** 新建批注分配的 commentId,按 op 顺序 */
+    createdComments: Array<{
+        opIndex: number;
+        commentId: CommentId;
+    }>;
+    /**
+     * 新建书签清单。
+     *
+     * - 显式 `createBookmark` op 产生的:`name` 是调用方传入的;`range` 给段落 ID
+     *   (ParagraphRange 时 fromParaId === toParaId,TextRange 同段所以也相等)
+     * - `insertParagraphAfter` 通过 `spec.bookmark` 触发的:`name` 是按规则解析后的实际名
+     *   (规则冲突会有 `_2/_3` 后缀);`range.fromParaId` = anchor,`range.toParaId` = newParaId
+     */
+    createdBookmarks: Array<{
+        opIndex: number;
+        name: BookmarkName;
+        range: {
+            fromParaId: ParaId;
+            toParaId: ParaId;
+        };
+    }>;
+    acceptedRevisions: number;
+    rejectedRevisions: number;
+    /**
+     * 实际替换的表格单元格数 (#188 / #204)。
+     *
+     * `replaceTableCellWithSdt` op 在 `onAnchorConflict='drop'` 模式下遇锚点会
+     * **静默跳过**, 该计数只统计真正完成替换的单元格数, 调用方据此报告准确域化数。
+     */
+    replacedTableCells: number;
+    /** Diagnostic timing, present only when the kernel collects apply timing. */
+    debugTiming?: {
+        ops: number;
+        affectedParts: number;
+        collectAffectedPartsMs?: number;
+        collectStoriesMs?: number;
+        collectStoryLookups?: number;
+        collectStoryLookupMs?: number;
+        collectByType?: Array<{
+            type: Op['type'];
+            count: number;
+            ms: number;
+            storyLookups: number;
+            storyLookupMs: number;
+        }>;
+        transactionMs: number;
+        indicesMs: number;
+        totalMs: number;
+        kernelMs?: number;
+        byType: Array<{
+            type: Op['type'];
+            count: number;
+            ms: number;
+        }>;
+    };
+}
+interface PlanValidationIssue {
+    code: WordErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+interface PlanValidationItem {
+    opIndex: number;
+    opType: Op['type'];
+    status: 'valid' | 'invalid' | 'unvalidated';
+    issue?: PlanValidationIssue;
+}
+interface PlanValidationResult {
+    valid: boolean;
+    items: PlanValidationItem[];
+}
+/** 空结果常量(空 plan / 内部初始化用)*/
+declare const EMPTY_APPLY_RESULT: ApplyResult;
+interface WordPlan {
+    replaceParagraph(paraId: ParaId, text: string, opts?: {
+        onAnchorConflict?: 'error' | 'drop';
+        keepInlineGraphics?: boolean;
+    }): this;
+    replaceTextInParagraph(paraId: ParaId, search: string, replacement: string, opts?: {
+        scope?: 'first' | 'all';
+    }): this;
+    formatTextInParagraph(paraId: ParaId, search: string, format: {
+        bold?: boolean;
+        color?: string;
+        italic?: boolean;
+        underline?: boolean;
+        highlight?: string;
+        fontSize?: number;
+        fontFamily?: string;
+    }, opts?: {
+        scope?: 'first' | 'all';
+    }): this;
+    formatParagraph(paraId: ParaId, format: ParagraphDirectFormat): this;
+    insertParagraphBefore(anchorParaId: ParaId, spec: InsertParagraphSpec): this;
+    insertParagraphAfter(anchorParaId: ParaId, spec: InsertParagraphSpec): this;
+    /**
+     * 无锚点在 `<w:body>` 起始插一个空段，新 paraId 通过
+     * `ApplyResult.insertedBodyStartParaIds` 回传。
+     *
+     * 用途：body 完全无段落（极简/特殊文档，正文段被骨架删光）时，重建需要一个真实落点锚段。
+     * 与 insertParagraphBefore/After 不同——后者必须有 anchor 段；本 op 不依赖任何已有段。
+     */
+    insertParagraphAtBodyStart(): this;
+    deleteParagraph(paraId: ParaId, opts?: {
+        onAnchorConflict?: 'error' | 'drop';
+    }): this;
+    acceptRevisions(scope: RevisionScope): this;
+    rejectRevisions(scope: RevisionScope): this;
+    createBookmark(spec: {
+        name: BookmarkName;
+        range: Range;
+    }): this;
+    deleteBookmark(name: BookmarkName): this;
+    addComment(spec: {
+        range: Range;
+        text: string;
+        author?: string;
+        date?: Date;
+    }): this;
+    deleteComment(commentId: CommentId): this;
+    /** Resolve and validate supported operation targets without mutating the document. */
+    validate(): Promise<PlanValidationResult>;
+    /**
+     * 给表格挂批注(#186 表格分类与保留决策的"决策理由可追溯"载体)。
+     * 实现上批注挂在表格首单元格的首段落,语义入口走 tableId。
+     */
+    addTableComment(spec: {
+        tableId: string;
+        text: string;
+        author?: string;
+        date?: Date;
+    }): this;
+    /**
+     * 删除整张表格(#186 不保留表格的裁剪入口)。
+     * 表格内段落若含活锚点(书签/批注),按 onAnchorConflict 处理。
+     */
+    deleteTable(tableId: string, opts?: {
+        onAnchorConflict?: 'error' | 'drop';
+    }): this;
+    /**
+     * 把表格指定单元格首段的 runs 替换为 inline SDT (#188 表格域化)。
+     *
+     * - (row, col) 对应 `TableInfo.cells[row][col]` 网格坐标(tr 顺序 × tc 顺序)
+     * - 段落 pPr / 单元格 tcPr / 边框 / 合并关系全部保留
+     * - 原首段 runs 的首 rPr 自动透传到 SDT 内 placeholder run, 字体 / 颜色 / 字号不丢
+     * - 单元格首段含锚点 (书签 / 批注) 时按 onAnchorConflict 处理 ('error' 抛 / 'drop' 跳过)
+     * - 单元格首段不存在或单元格不存在时抛 PARA_NOT_FOUND
+     */
+    replaceTableCellWithSdt(spec: {
+        tableId: string;
+        row: number;
+        col: number;
+        sdt: SdtSpec;
+        onAnchorConflict?: 'error' | 'drop';
+    }): this;
+    /**
+     * 替换表格指定单元格首段的内容为单个纯文字 run（排版回填）。
+     *
+     * - (row, col) 对应 TableInfo.cells[row][col] 网格坐标
+     * - **单元格 tcPr（底纹 shd / 边框 / 对齐 vAlign / 列宽 tcW）完全保留**（只动首段内部）
+     * - 首段 pPr 保留；原首 run 的 rPr（字体/字号/颜色）透传到新文字 run
+     * - 单元格首段含锚点（书签/批注）时按 onAnchorConflict 处理（'error' 抛 / 'drop' 跳过不替换）
+     * - 单元格不存在 → TABLE_NOT_FOUND；首段不存在 → PACKAGE_CORRUPT
+     * - trackChanges=true 暂不支持，抛 UNSUPPORTED_OOXML_FEATURE
+     */
+    replaceTableCellText(spec: {
+        tableId: string;
+        row: number;
+        col: number;
+        text: string;
+        onAnchorConflict?: 'error' | 'drop';
+    }): this;
+    formatTableCell(spec: {
+        tableId: string;
+        row: number;
+        col: number;
+        format: TableCellDirectFormat;
+    }): this;
+    insertTableCellParagraph(spec: {
+        tableId: string;
+        row: number;
+        col: number;
+        text: string;
+        position: 'start' | 'end';
+    }): this;
+    /**
+     * 删除表格指定行 (#188 §7.2 行级裁剪)。
+     *
+     * - `row` 是 op 执行时的行索引；同一 plan 内连续删多行时调用方按**降序**传入，
+     *   避免索引漂移（删 row 3 后原 row 4 变成新的 row 3）
+     * - 行内段落含活锚点 (书签 / 批注) 时按 `onAnchorConflict` 处理 ('error' 抛 / 'drop' 跳过)
+     * - 删除最后一行会让表格只剩 tblPr / tblGrid —— Word 允许 0 行表格但显示异常，
+     *   调用方应在外层保证至少留一行（典型场景：可变行数表保留表头 + 1~N 样例行）
+     */
+    deleteTableRow(tableId: string, row: number, opts?: {
+        onAnchorConflict?: 'error' | 'drop';
+    }): this;
+    /**
+     * 把 drawing 的图片内容替换为共享占位图 (#190)。
+     *
+     * - 仅接受 kind = 'picture' 的 drawing；其它 kind(chart / smartArt / shape / textBox /
+     *   group / canvas / other)抛 UNSUPPORTED_OOXML_FEATURE,需走 deleteDrawing 或 #192
+     * - **布局完全保持**:wp:inline / wp:anchor、wp:extent、wrap、position、anchorParaId
+     *   都不动,只改 a:blip/@r:embed 指向共享 placeholder
+     * - 同一文档内多次调用幂等:共用一份 word/media/placeholder.png + 单条 image rel
+     * - 替换后若旧 media 在全包无其它引用,自动清理对应 rels 条目 + binary part
+     *   (保证「原始图片二进制不出现在输出文档中」的验收条件)
+     * - drawingId 不存在抛 DRAWING_NOT_FOUND
+     * - trackChanges=true 暂不支持,抛 UNSUPPORTED_OOXML_FEATURE
+     */
+    replaceDrawingWithPlaceholder(drawingId: string): this;
+    /**
+     * 删除 drawing(B/C 类裁剪入口)。
+     *
+     * - 不限制 kind,任何 drawing 都可删
+     * - 物理删 w:drawing;承载它的 w:r 若仅含该 drawing 一并删除
+     * - 同样清理孤儿 media / rels(逻辑与 replaceDrawingWithPlaceholder 共享)
+     * - drawingId 不存在抛 DRAWING_NOT_FOUND
+     * - trackChanges=true 暂不支持,抛 UNSUPPORTED_OOXML_FEATURE
+     */
+    deleteDrawing(drawingId: string): this;
+    /**
+     * 把 Shape / TextBox 内部文字替换为统一占位文字 (#210,#192 内容型保留依赖)。
+     *
+     * - 仅接受含 `w:txbxContent` 的 drawing(textBox / shape-with-text)
+     *   其它 kind(picture / chart / smartArt / group / canvas / shape-without-text / other)
+     *   抛 UNSUPPORTED_OOXML_FEATURE,需走 replaceDrawingWithPlaceholder 或 deleteDrawing
+     * - **外壳完全保留**:w:drawing 整个 wp:inline / wp:anchor / wsp:spPr / wp:extent /
+     *   wrap / position 一字不动
+     * - 内部 `w:txbxContent` 被重写为**单段单 run** placeholder 文本;原首段
+     *   `w:pPr/w:jc` 对齐保留(沿用 innerTextAlign 维度)
+     * - 内部 hyperlink / 嵌套 picture 的 rels 引用按 deleteDrawing 同源清理
+     * - 占位文字走默认 run 样式(v1 不保留原首段 run rPr 字体 / 字号 / 颜色)
+     * - drawingId 不存在抛 DRAWING_NOT_FOUND
+     * - trackChanges=true 暂不支持,抛 UNSUPPORTED_OOXML_FEATURE
+     */
+    replaceShapeInnerText(drawingId: string, placeholder: string): this;
+    /**
+     * 克隆表格某一行作模板，在指定位置插入新行（可变行数表回填）。（#14）
+     *
+     * - `templateRow`：0-based，克隆此行的单元格结构（tcPr 含底纹 shd / 边框 /
+     *   对齐 vAlign / 列宽 tcW + 首段 pPr + 首 run rPr 全保留）
+     * - `position`：插入后新行所在的 0-based 行索引（insert-before 语义）；
+     *   传 'end' 追加到末尾。范围 [0, rowCount]，rowCount 等价 'end'
+     * - `cellTexts`：可选，新行各列文字（保留各列 rPr）。
+     *   - 不传：克隆模板行原样（含模板原文字）
+     *   - 传 L 个元素：列 i ∈ [0, min(L,C)) 替换为 cellTexts[i]；列 i ∈ [L,C) 清空；多余忽略
+     * - 克隆行内锚点（书签/批注）一律剥离；行内每个 <w:p> 重新分配 paraId
+     * - 表格不存在 / templateRow 越界 / position 越界 → TABLE_NOT_FOUND
+     * - trackChanges=true 暂不支持 → UNSUPPORTED_OOXML_FEATURE
+     */
+    insertTableRow(spec: {
+        tableId: string;
+        templateRow: number;
+        position: number | 'end';
+        cellTexts?: string[];
+    }): this;
+    /**
+     * 把已有表格深克隆一份，插入到指定段落之后（排版重建：模板表克隆到多处）。（#15）
+     *
+     * - `sourceTableId`：克隆哪张表。深克隆整个 `<w:tbl>`（tblPr/tblGrid/所有行/
+     *   单元格 tcPr/pPr/rPr 全保留）。源表自身**只读，不被修改**。
+     * - `anchorParaId`：克隆表插到此段之后（与 insertParagraphAfter 同语义：
+     *   插到 anchor 的下一个兄弟之前）。anchor 应为 body story 直属段落。
+     * - 克隆表内**锚点（书签/批注 5 类）一律剥离**；克隆表内**每个 `<w:p>`
+     *   重新分配 paraId**，保 paraId 全局唯一。
+     * - anchorParaId 不存在 → PARA_NOT_FOUND；sourceTableId 不存在 → TABLE_NOT_FOUND。
+     * - trackChanges=true 暂不支持 → UNSUPPORTED_OOXML_FEATURE。
+     * - v1 不在 ApplyResult 回传新表 tableId；apply 后用 `doc.tables.list()` 按文档顺序定位。
+     */
+    cloneTableAfter(spec: {
+        anchorParaId: ParaId;
+        sourceTableId: string;
+    }): this;
+    /**
+     * 在指定段落之后新插一个段，段内含一个 inline 图片（task-insert-image）。
+     *
+     * - `anchorParaId`：新段插到此段之后（与 insertParagraphAfter 同语义）
+     * - `bytes`：图片二进制（`Uint8Array`，跨端，绝不碰 node fs/Buffer）
+     * - `contentType`：'image/png' | 'image/jpeg' | 'image/gif' | 'image/bmp' | 'image/tiff'
+     * - `widthEmu` / `heightEmu`：wp:extent@cx/cy（EMU 单位，1 英寸 = 914400 EMU）
+     * - anchor 不存在 → `PARA_NOT_FOUND`
+     * - 不支持的 contentType → `UNSUPPORTED_OOXML_FEATURE`
+     * - trackChanges=true → `UNSUPPORTED_OOXML_FEATURE`
+     */
+    insertImageAfter(anchorParaId: ParaId, spec: {
+        bytes: Uint8Array;
+        contentType: string;
+        widthEmu: number;
+        heightEmu: number;
+    }): this;
+    /**
+     * 跨文档 verbatim 搬一张表进当前文档，插到 anchorParaId 段之后
+     * （task-20260616-table-content-driven，"数据表 = 内容块" §13.9）。
+     *
+     * - `anchorParaId`：搬入的表插到此段之后（与 cloneTableAfter 同语义）。
+     * - `tableXml`：源文档 `<w:tbl>` 子树序列化字符串。调用方（typeset，持源 doc）用
+     *   `serializeToWellFormedString(tblElement)` 取得；命名空间随子树带入，无需额外声明。
+     * - `images`：格内图预解析字节，按源 `<a:blip @r:embed>` 的**原始 rId** 索引；executor 在
+     *   host 新建 media part + image rel + content-type，把 embed 改写成新 rId。缺某 rId → 该
+     *   blip embed 清掉 + warn（结构/文字仍保真，仅该格图降级）。
+     * - `styleTblPrXml`：可选，模板数据表 `<w:tblPr>` 序列化串。提供则整体替换搬入表的 tblPr
+     *   （tblStyle/边框/tblLook/宽度 → 归一到模板样式，覆盖内容表自带样式）。
+     * - 表内锚点（书签/批注 5 类）一律剥离；每个 `<w:p>` 重分配 paraId（全局唯一）。
+     * - 行/列/值/合并/嵌套表/格内图全部 verbatim 来自 tableXml，executor 不重建/不裁剪/不对位。
+     * - anchor 不存在 → `PARA_NOT_FOUND`；tableXml 非 `<w:tbl>` → `INVALID_ARGUMENT`；
+     *   trackChanges=true → `UNSUPPORTED_OOXML_FEATURE`。
+     * - v1 不在 ApplyResult 回传新表 tableId；apply 后用 `doc.tables.list()` 按文档顺序定位。
+     */
+    insertTableFrom(spec: {
+        anchorParaId: ParaId;
+        tableXml: string;
+        images?: Array<{
+            originalRId: string;
+            bytes: Uint8Array;
+            contentType: string;
+        }>;
+        styleTblPrXml?: string;
+    }): this;
+    /**
+     * 设表格列宽：同步更新 `<w:tblGrid>` gridCol w:w **和** 每个单元格 `<w:tcW>`
+     * （task-core-table-grid：merger 保真源表列宽）。
+     *
+     * - `tableId`：目标表格（来自 `tables.list()` 的 tableId）。
+     * - `widths`：新列宽数组（twips，1 twip = 1/20 磅）。长度必须等于该表格的
+     *   `colCount`（gridCol 数量）——不等则抛 `INVALID_ARGUMENT`（防止截断/越界）。
+     * - 同步设每个单元格 `<w:tcW w:type="dxa">`（Word 渲染优先 tcW over gridCol）：
+     *   合并单元格（gridSpan > 1）的 tcW = 跨列宽之和；vMerge 续行单元格正常处理。
+     * - tableId 不存在 → `TABLE_NOT_FOUND`。
+     * - trackChanges=true → `UNSUPPORTED_OOXML_FEATURE`（暂不支持）。
+     */
+    setTableColumnWidths(spec: {
+        tableId: string;
+        widths: number[];
+    }): this;
+    /**
+     * 设表格行高（task-core-table-rowheight：merger 保真源表行高）。
+     *
+     * - `tableId`：目标表格（来自 `tables.list()` 的 tableId）。
+     * - `heights`：每行行高数组，长度必须等于该表格的 `rowCount`——不等则抛 `INVALID_ARGUMENT`。
+     *   - `RowHeight`：在该行 `<w:trPr>` 写入/替换 `<w:trHeight w:val="N" w:hRule="..."/>`。
+     *   - `null`：删除该行的 `<w:trHeight>`（即「不指定行高」）。
+     * - `heights[i]` 套到物理第 i 行 `<w:tr>`（与 `TableInfo.rowHeights` 1:1）。
+     * - tableId 不存在 → `TABLE_NOT_FOUND`。
+     * - trackChanges=true → `UNSUPPORTED_OOXML_FEATURE`（暂不支持）。
+     */
+    setTableRowHeights(spec: {
+        tableId: string;
+        heights: (RowHeight | null)[];
+    }): this;
+    /**
+     * 在 settings.xml 写入/更新 `<w:updateFields>`，让含 TOC 域的文档打开时自动更新域。
+     * （task-core-update-fields）
+     *
+     * - `enabled=true`：在 settings.xml 根 `<w:settings>` 写入/更新
+     *   `<w:updateFields w:val="true"/>`——Word/WPS 打开文档时自动重生成所有域（TOC/PAGEREF/SEQ 等）。
+     * - `enabled=false`：写 `<w:updateFields w:val="false"/>`（显式禁用，语义更清晰）。
+     * - 幂等：settings.xml 已有 `<w:updateFields>` 则改 `w:val`，不重复插入元素。
+     * - settings.xml 不存在 → 抛 `UNSUPPORTED_OOXML_FEATURE`（后续跟进新建 settings part）。
+     */
+    setUpdateFields(enabled: boolean): this;
+    apply(): Promise<ApplyResult>;
+    /** 只读 op 队列,用于调试 / 日志 / 测试 */
+    readonly ops: ReadonlyArray<Op>;
+    /** apply 是否已被调用过(成功与否都置 true,防止二次 apply)*/
+    readonly applied: boolean;
+    /** Plan 创建时的选项,只读 */
+    readonly options: Readonly<Required<Pick<PlanOptions, 'trackChanges'>> & Omit<PlanOptions, 'trackChanges'>>;
+}
+interface WordPlanImplInit {
+    docId: string;
+    transport: Transport;
+    options: PlanOptions;
+}
+declare class WordPlanImpl implements WordPlan {
+    private readonly docId;
+    private readonly transport;
+    private readonly _options;
+    private readonly _ops;
+    private _applied;
+    constructor(init: WordPlanImplInit);
+    get ops(): ReadonlyArray<Op>;
+    get applied(): boolean;
+    get options(): Readonly<WordPlan['options']>;
+    replaceParagraph(paraId: ParaId, text: string, opts?: {
+        onAnchorConflict?: 'error' | 'drop';
+        keepInlineGraphics?: boolean;
+    }): this;
+    replaceTextInParagraph(paraId: ParaId, search: string, replacement: string, opts?: {
+        scope?: 'first' | 'all';
+    }): this;
+    formatTextInParagraph(paraId: ParaId, search: string, format: {
+        bold?: boolean;
+        color?: string;
+        italic?: boolean;
+        underline?: boolean;
+        highlight?: string;
+        fontSize?: number;
+        fontFamily?: string;
+    }, opts?: {
+        scope?: 'first' | 'all';
+    }): this;
+    formatParagraph(paraId: ParaId, format: ParagraphDirectFormat): this;
+    insertParagraphBefore(anchorParaId: ParaId, spec: InsertParagraphSpec): this;
+    insertParagraphAfter(anchorParaId: ParaId, spec: InsertParagraphSpec): this;
+    insertParagraphAtBodyStart(): this;
+    deleteParagraph(paraId: ParaId, opts?: {
+        onAnchorConflict?: 'error' | 'drop';
+    }): this;
+    acceptRevisions(scope: RevisionScope): this;
+    rejectRevisions(scope: RevisionScope): this;
+    createBookmark(spec: {
+        name: BookmarkName;
+        range: Range;
+    }): this;
+    deleteBookmark(name: BookmarkName): this;
+    addComment(spec: {
+        range: Range;
+        text: string;
+        author?: string;
+        date?: Date;
+    }): this;
+    deleteComment(commentId: CommentId): this;
+    addTableComment(spec: {
+        tableId: string;
+        text: string;
+        author?: string;
+        date?: Date;
+    }): this;
+    deleteTable(tableId: string, opts?: {
+        onAnchorConflict?: 'error' | 'drop';
+    }): this;
+    replaceTableCellWithSdt(spec: {
+        tableId: string;
+        row: number;
+        col: number;
+        sdt: SdtSpec;
+        onAnchorConflict?: 'error' | 'drop';
+    }): this;
+    deleteTableRow(tableId: string, row: number, opts?: {
+        onAnchorConflict?: 'error' | 'drop';
+    }): this;
+    replaceTableCellText(spec: {
+        tableId: string;
+        row: number;
+        col: number;
+        text: string;
+        onAnchorConflict?: 'error' | 'drop';
+    }): this;
+    formatTableCell(spec: {
+        tableId: string;
+        row: number;
+        col: number;
+        format: TableCellDirectFormat;
+    }): this;
+    insertTableCellParagraph(spec: {
+        tableId: string;
+        row: number;
+        col: number;
+        text: string;
+        position: 'start' | 'end';
+    }): this;
+    replaceDrawingWithPlaceholder(drawingId: string): this;
+    deleteDrawing(drawingId: string): this;
+    replaceShapeInnerText(drawingId: string, placeholder: string): this;
+    insertTableRow(spec: {
+        tableId: string;
+        templateRow: number;
+        position: number | 'end';
+        cellTexts?: string[];
+    }): this;
+    cloneTableAfter(spec: {
+        anchorParaId: ParaId;
+        sourceTableId: string;
+    }): this;
+    insertImageAfter(anchorParaId: ParaId, spec: {
+        bytes: Uint8Array;
+        contentType: string;
+        widthEmu: number;
+        heightEmu: number;
+    }): this;
+    insertTableFrom(spec: {
+        anchorParaId: ParaId;
+        tableXml: string;
+        images?: Array<{
+            originalRId: string;
+            bytes: Uint8Array;
+            contentType: string;
+        }>;
+        styleTblPrXml?: string;
+    }): this;
+    setTableColumnWidths(spec: {
+        tableId: string;
+        widths: number[];
+    }): this;
+    setTableRowHeights(spec: {
+        tableId: string;
+        heights: (RowHeight | null)[];
+    }): this;
+    setUpdateFields(enabled: boolean): this;
+    apply(): Promise<ApplyResult>;
+    validate(): Promise<PlanValidationResult>;
+    private ensureOpen;
+}
+/**
+ * `kernel.applyPlan` 接收的结构。`date` 是 ISO 8601 字符串(序列化友好),kernel
+ * 端需要时用 `new Date(str)` 解回。
+ */
+interface ApplyPlanParams {
+    ops: Op[];
+    options: {
+        trackChanges: boolean;
+        author?: string;
+        date?: string;
+    };
+}
+
+interface RangeClassification {
+    kind: 'paragraph' | 'text' | 'complex';
+    /** 'paragraph' / 'text' 命中时,containing `<w:p>` 的 paraId(大写 8 hex) */
+    paraId?: string;
+    /** 'text' 命中时,start/end 之间所有 `<w:t>` 的纯文本拼接 */
+    text?: string;
+}
+declare function classifyRange(start: Element | null, end: Element | null): RangeClassification;
+
+/**
+ * Core-Word 读 API 的 namespace 子对象(#92,docs/03.1 §2)。
+ *
+ * 把 Phase B 原本平铺在 `WordDocument` 上的 7 个读方法按实体聚合为 4 个子 API:
+ *
+ *   | 旧(平铺) | 新(namespace) |
+ *   |---|---|
+ *   | `doc.listParagraphs(opts)` | `doc.paragraphs.list(opts)` |
+ *   | `doc.getParagraph(id)` | `doc.paragraphs.get(id)` |
+ *   | `doc.listBookmarks(opts)` | `doc.bookmarks.list(opts)` |
+ *   | `doc.getBookmark(name)` | `doc.bookmarks.get(name)` |
+ *   | `doc.listComments()` | `doc.comments.list()` |
+ *   | `doc.getComment(id)` | `doc.comments.get(id)` |
+ *   | `doc.listRevisions(opts)` | `doc.revisions.list(opts)` |
+ *
+ * 动机:Phase F 起属性层(`format.*`)+ sections / tables / drawings / styles /
+ * hyperlinks / fields 若继续平铺会让主类表面爆炸。namespace 聚合后新实体扩展只
+ * 需往 `WordDocument` 加一个 `readonly` 字段(见 docs/03.1 §2 的 "未来扩展")。
+ *
+ * 命名规范(docs/03.1 §2.1):
+ * - 子 API 方法用动词短命名 `list` / `get`,不重复实体名
+ * - 过滤/分页选项保留顶层类型名(`ListParagraphsOptions` 不简化)
+ * - 返回值类型名不变
+ *
+ * RPC method name 同步迁移:`paragraphs.list` / `paragraphs.get` / `bookmarks.list`
+ * / `bookmarks.get` / `comments.list` / `comments.get` / `revisions.list`。协议
+ * 版本不 bump —— 这是 method name rename,非协议结构变更。
+ */
+
+interface ParagraphApi {
+    /**
+     * Lists paragraphs and returns live paragraph handles.
+     */
+    list(opts?: ListParagraphsOptions): Promise<ParagraphList>;
+    /**
+     * Gets one paragraph by `paraId`.
+     *
+     * Returns `null` when the paragraph no longer exists.
+     */
+    get(paraId: string): Promise<Paragraph | null>;
+}
+interface ParagraphList {
+    paragraphs: Paragraph[];
+    pagination: ListResult['pagination'];
+}
+interface LiveObjectWriteOptions {
+    /**
+     * Enables tracked-change markup for the write operation when supported.
+     */
+    trackChanges?: boolean;
+    /**
+     * Author metadata used by comments and tracked changes.
+     */
+    author?: string;
+    /**
+     * Date metadata used by comments and tracked changes.
+     */
+    date?: Date;
+}
+interface ContextApi {
+    /**
+     * Searches local document content and returns actionable context matches.
+     */
+    search(opts: ContextSearchOptions): Promise<ContextSearchResult>;
+}
+interface RevisionBulkOptions extends LiveObjectWriteOptions {
+    /**
+     * Bulk revision writes currently target all supported revisions.
+     */
+    scope?: 'all';
+}
+interface ParagraphDeleteOptions extends LiveObjectWriteOptions {
+    /**
+     * Controls what happens when deleting the paragraph would affect anchors such
+     * as bookmarks or comments.
+     */
+    onAnchorConflict?: 'error' | 'drop';
+}
+interface ParagraphInsertOptions extends LiveObjectWriteOptions {
+    /**
+     * Controls the new paragraph's paragraph/run style source.
+     */
+    style?: 'inherit' | string;
+    /**
+     * Controls whether the new paragraph run inherits the anchor run format.
+     */
+    runFormat?: 'inherit' | 'default';
+}
+interface ParagraphReplaceOptions extends LiveObjectWriteOptions {
+    /**
+     * Controls what happens when replacing a paragraph would affect anchors such
+     * as bookmarks or comments.
+     */
+    onAnchorConflict?: 'error' | 'drop';
+    /**
+     * Preserves inline drawings/objects while replacing text runs.
+     */
+    keepInlineGraphics?: boolean;
+}
+interface ParagraphInsertImageSpec {
+    /** Image bytes. The SDK accepts browser-safe Uint8Array data. */
+    bytes: Uint8Array;
+    /** Image MIME type, for example `image/png` or `image/jpeg`. */
+    contentType: string;
+    /** Rendered width in EMU. 1 inch = 914400 EMU. */
+    widthEmu: number;
+    /** Rendered height in EMU. 1 inch = 914400 EMU. */
+    heightEmu: number;
+}
+interface ParagraphInsertTableSpec {
+    /**
+     * Text matrix used to create a simple Word table. Missing cells in ragged
+     * rows are created as empty cells.
+     */
+    rows: string[][];
+    /** Column widths in twips. Defaults to 2400 twips for each column. */
+    columnWidths?: number[];
+    /** Optional Word table style id, written as `w:tblStyle`. */
+    tableStyleId?: string;
+}
+/**
+ * Live handle for one document paragraph.
+ *
+ * Snapshot fields such as `paraId` and `story` come from the read that created
+ * the handle. Methods read or write the current document state.
+ */
+interface Paragraph extends ParagraphInfo {
+    /** Stable paragraph identifier. */
+    readonly paraId: ParaId;
+    /** Alias of `paraId`, kept for object-style APIs. */
+    readonly id: ParaId;
+    /** Document story that contains this paragraph. */
+    readonly story: ParagraphInfo['story'];
+    /**
+     * Reads the current metadata for this paragraph.
+     */
+    getInfo(opts?: Pick<ListParagraphsOptions, 'includeFormat' | 'textFormat'>): Promise<ParagraphInfo | null>;
+    /**
+     * Reads the current plain text of this paragraph.
+     */
+    getText(): Promise<string | null>;
+    /**
+     * Replaces this paragraph with plain text.
+     */
+    replaceWith(text: string, opts?: ParagraphReplaceOptions): Promise<ApplyResult>;
+    /**
+     * Sets horizontal paragraph alignment.
+     */
+    setAlignment(value: NonNullable<ParagraphDirectFormat['alignment']>, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Sets paragraph outline level. Values 0-8 correspond to heading levels 1-9.
+     */
+    setOutlineLevel(value: number, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Sets whether this paragraph starts on a new page.
+     */
+    setPageBreakBefore(value: boolean, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Sets paragraph indentation in twips.
+     */
+    setIndent(value: NonNullable<ParagraphDirectFormat['indent']>, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Sets paragraph spacing in twips.
+     */
+    setSpacing(value: NonNullable<ParagraphDirectFormat['spacing']>, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Inserts a new paragraph before this paragraph.
+     */
+    insertBefore(text: string, opts?: ParagraphInsertOptions): Promise<ApplyResult>;
+    /**
+     * Inserts a new paragraph after this paragraph.
+     */
+    insertAfter(text: string, opts?: ParagraphInsertOptions): Promise<ApplyResult>;
+    /**
+     * Inserts a new inline image paragraph after this paragraph.
+     */
+    insertImageAfter(spec: ParagraphInsertImageSpec, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Inserts a simple text table after this paragraph.
+     *
+     * For high-fidelity table copy, use `table.getVerbatim()` with
+     * `doc.plan().insertTableFrom(...)`.
+     */
+    insertTableAfter(spec: ParagraphInsertTableSpec, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Deletes this paragraph from the document.
+     */
+    delete(opts?: ParagraphDeleteOptions): Promise<ApplyResult>;
+    /**
+     * Adds a comment to this whole paragraph.
+     */
+    addComment(text: string, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Creates a bookmark around this whole paragraph.
+     */
+    createBookmark(name: BookmarkName$1, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Creates a text range handle by searching inside this paragraph.
+     *
+     * The returned range is lazy: it resolves the search when a range method is
+     * executed.
+     */
+    findText(search: string, opts?: {
+        scope?: 'first' | 'all';
+    }): TextRange;
+}
+/**
+ * Live handle for text matched inside one paragraph.
+ */
+interface TextRange {
+    /**
+     * Replaces the matched text with plain text.
+     */
+    replaceWith(text: string, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Deletes the matched text.
+     */
+    delete(opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Sets bold formatting on the matched text.
+     */
+    setBold(value: boolean, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Sets font color on the matched text.
+     */
+    setColor(value: string, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Sets italic formatting on the matched text.
+     */
+    setItalic(value: boolean, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Sets single underline on the matched text.
+     */
+    setUnderline(value: boolean, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Sets Word highlight color on the matched text.
+     */
+    setHighlight(value: string, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Sets font size in points on the matched text.
+     */
+    setFontSize(value: number, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Sets font family on the matched text.
+     */
+    setFontFamily(value: string, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Adds a comment to the matched text.
+     */
+    addComment(text: string, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Creates a bookmark around the matched text.
+     */
+    createBookmark(name: BookmarkName$1, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+}
+interface BookmarkApi {
+    /**
+     * Lists bookmarks and returns live bookmark handles.
+     */
+    list(opts?: ListBookmarksOptions): Promise<Bookmark[]>;
+    /**
+     * Gets one bookmark by name.
+     *
+     * Returns `null` when the bookmark no longer exists.
+     */
+    get(name: BookmarkName$1): Promise<Bookmark | null>;
+}
+/**
+ * Live handle for one document bookmark.
+ */
+interface Bookmark extends BookmarkInfo {
+    /** Alias of `name`, kept for object-style APIs. */
+    readonly id: BookmarkName$1;
+    /**
+     * Reads current metadata for this bookmark.
+     */
+    getInfo(): Promise<BookmarkInfo | null>;
+    /**
+     * Reads the current text covered by this bookmark when it can be expressed as
+     * a paragraph or text range.
+     */
+    getText(): Promise<string | null>;
+    /**
+     * Returns the paragraph that contains this bookmark when available.
+     */
+    getParagraph(): Promise<Paragraph | null>;
+    /**
+     * Deletes this bookmark anchor pair.
+     */
+    delete(opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+}
+interface CommentApi {
+    /**
+     * Lists comments and returns live comment handles.
+     */
+    list(): Promise<Comment[]>;
+    /**
+     * Gets one comment by id.
+     *
+     * Returns `null` when the comment no longer exists.
+     */
+    get(id: CommentId$1): Promise<Comment | null>;
+}
+/**
+ * Live handle for one document comment.
+ */
+interface Comment extends CommentInfo {
+    /**
+     * Reads current metadata for this comment.
+     */
+    getInfo(): Promise<CommentInfo | null>;
+    /**
+     * Reads the current comment body text from `comments.xml`.
+     */
+    getText(): Promise<string | null>;
+    /**
+     * Reads the current document text covered by this comment anchor.
+     */
+    getAnchorText(): Promise<string | null>;
+    /**
+     * Returns the paragraph that contains this comment anchor when available.
+     */
+    getParagraph(): Promise<Paragraph | null>;
+    /**
+     * Deletes this comment body and its anchors.
+     */
+    delete(opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+}
+interface RevisionApi {
+    /**
+     * Lists revisions and returns live revision handles.
+     */
+    list(opts?: ListRevisionsOptions): Promise<Revision[]>;
+    /**
+     * Gets one revision by `revId`.
+     *
+     * Returns `null` when the revision no longer exists.
+     */
+    get(revId: RevisionInfo['revId'], opts?: ListRevisionsOptions): Promise<Revision | null>;
+    /**
+     * Accepts all supported revisions.
+     */
+    accept(opts?: RevisionBulkOptions): Promise<ApplyResult>;
+    /**
+     * Rejects all supported revisions.
+     */
+    reject(opts?: RevisionBulkOptions): Promise<ApplyResult>;
+}
+/**
+ * Live handle for one document revision.
+ *
+ * `revision.accept/reject` operate on this single revision id. Use
+ * `doc.revisions.accept/reject` for all supported revisions.
+ */
+interface Revision extends RevisionInfo {
+    /** Stable alias of `revId`, kept for object-style APIs. */
+    readonly id: RevisionInfo['revId'];
+    /**
+     * Reads current metadata for this revision.
+     */
+    getInfo(opts?: ListRevisionsOptions): Promise<RevisionInfo | null>;
+    /**
+     * Reads the revision text when available.
+     */
+    getText(): Promise<string | null>;
+    /**
+     * Returns the paragraph that contains this revision when available.
+     */
+    getParagraph(): Promise<Paragraph | null>;
+    /**
+     * Accepts this revision.
+     */
+    accept(opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Rejects this revision.
+     */
+    reject(opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+}
+interface StylesApi {
+    /**
+     * 列出 styles.xml 中的所有样式（或按 type 过滤）。
+     * styles.xml 不存在时返回空数组。
+     */
+    list(opts?: ListStylesOptions): Promise<StyleInfo[]>;
+    /**
+     * 按 styleId 精确查找，O(1)。
+     * styleId 大小写敏感。不存在时返回 null。
+     */
+    get(styleId: string): Promise<StyleInfo | null>;
+}
+interface TablesApi {
+    /**
+     * 枚举文档表格（#185）。
+     * - scope: 'body'（默认）只返回主文档 body 中的表格
+     * - includeNested: false（默认）跳过嵌套在其他表格内的表格
+     */
+    /**
+     * Lists tables in the document and returns live table handles.
+     *
+     * The returned `Table` values contain a snapshot of the table metadata at
+     * list time, and also expose methods that can read fresh state or write back
+     * to the same table.
+     */
+    list(opts?: ListTablesOptions): Promise<Table[]>;
+    /**
+     * 按 tableId 精确取单个表格，O(1)。不存在返回 null。
+     */
+    /**
+     * Gets one table by `tableId`.
+     *
+     * Returns `null` when the table no longer exists.
+     */
+    get(tableId: string): Promise<Table | null>;
+    /**
+     * 按 tableId verbatim 取一张表的 OOXML 子树 + 格内图字节（自包含 payload）。
+     * 供跨文档搬表 `plan.insertTableFrom(...)`（"数据表 = 内容块" §13.9）。不存在返回 null。
+     */
+    /**
+     * Exports the raw OOXML subtree and related media for a table.
+     *
+     * This is an advanced API for high-fidelity table copying. Normal table
+     * reads and writes should use `list`, `get`, and the methods on `Table`.
+     */
+    getVerbatim(tableId: string): Promise<TableVerbatim | null>;
+}
+interface TableDeleteOptions extends LiveObjectWriteOptions {
+    /**
+     * Controls what happens when deleting the table would affect anchors such as
+     * bookmarks or comments.
+     */
+    onAnchorConflict?: 'error' | 'drop';
+}
+interface TableCellWriteOptions extends LiveObjectWriteOptions {
+    /**
+     * Controls what happens when replacing cell text would affect anchors such
+     * as bookmarks or comments.
+     */
+    onAnchorConflict?: 'error' | 'drop';
+}
+interface TableRowDeleteOptions extends LiveObjectWriteOptions {
+    /**
+     * Controls what happens when deleting the row would affect anchors such as
+     * bookmarks or comments.
+     */
+    onAnchorConflict?: 'error' | 'drop';
+}
+/**
+ * Live handle for one document table.
+ *
+ * A `Table` is both a metadata snapshot and an operation handle:
+ * snapshot fields such as `tableId`, `rowCount`, `colCount`, and `cells` come
+ * from the read that created the handle, while methods such as `getInfo` and
+ * `replaceCellText` read or write the current document state.
+ */
+interface Table extends TableInfo {
+    /** Stable alias of `tableId`, kept for object-style APIs. */
+    readonly id: string;
+    /**
+     * Creates a live handle for one cell, addressed by zero-based row and column.
+     */
+    cell(row: number, col: number): TableCell;
+    /**
+     * Creates a live handle for one row, addressed by zero-based row index.
+     */
+    row(row: number): TableRow;
+    /**
+     * Creates a live handle for one column, addressed by zero-based column index.
+     */
+    column(col: number): TableColumn;
+    /**
+     * Reads the current metadata for this table.
+     *
+     * Use this after writes when you need fresh row, column, width, height, or
+     * cell information.
+     */
+    getInfo(opts?: ListTablesOptions): Promise<TableInfo | null>;
+    /**
+     * Exports this table as raw OOXML plus related media.
+     *
+     * This is intended for high-fidelity copy/move flows, not routine editing.
+     */
+    getVerbatim(): Promise<TableVerbatim | null>;
+    /**
+     * Reads the current plain text of this table.
+     *
+     * Cell text is joined using tabs between columns and line breaks between
+     * rows.
+     */
+    getText(opts?: ListTablesOptions): Promise<string | null>;
+    /**
+     * Reads the current table cell text as a two-dimensional array.
+     *
+     * Returns `null` when the table no longer exists.
+     */
+    getCells(opts?: ListTablesOptions): Promise<string[][] | null>;
+    /** Adds a comment to the whole table range. */
+    addComment(text: string, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /** Deletes this table from the document. */
+    delete(opts?: TableDeleteOptions): Promise<ApplyResult>;
+    /**
+     * Replaces the text of one cell, addressed by zero-based row and column.
+     */
+    replaceCellText(row: number, col: number, text: string, opts?: TableCellWriteOptions): Promise<ApplyResult>;
+    /** Deletes one row, addressed by zero-based row index. */
+    deleteRow(row: number, opts?: TableRowDeleteOptions): Promise<ApplyResult>;
+    /**
+     * Inserts one row.
+     *
+     * `templateRow` is the zero-based source row used for row structure.
+     * `position` is the zero-based insertion position, or `'end'`.
+     */
+    insertRow(spec: {
+        templateRow: number;
+        position: number | 'end';
+        cellTexts?: string[];
+    }, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Sets table grid column widths in twips.
+     *
+     * The array length should match the table column count.
+     */
+    setColumnWidths(widths: number[], opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Sets row heights.
+     *
+     * Pass `null` for a row that should keep its current height.
+     */
+    setRowHeights(heights: (RowHeight | null)[], opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+}
+/**
+ * Live handle for one table cell.
+ */
+interface TableCell {
+    /** Parent table id. */
+    readonly tableId: string;
+    /** Zero-based row index. */
+    readonly row: number;
+    /** Zero-based column index. */
+    readonly col: number;
+    /**
+     * Reads the current cell metadata.
+     */
+    getInfo(opts?: ListTablesOptions): Promise<TableCellInfo | null>;
+    /**
+     * Reads direct content blocks in this cell, preserving cell content order.
+     */
+    getBlocks(opts?: ListTablesOptions): Promise<TableCellBlock[] | null>;
+    /**
+     * Reads live paragraph handles for direct paragraphs in this cell.
+     */
+    getParagraphs(opts?: ListTablesOptions): Promise<Paragraph[]>;
+    /**
+     * Reads the current plain text of this cell.
+     */
+    getText(opts?: ListTablesOptions): Promise<string | null>;
+    /**
+     * Creates a text range handle by searching inside this cell's paragraphs.
+     */
+    findText(search: string, opts?: {
+        scope?: 'first' | 'all';
+    }): CellTextRange;
+    /**
+     * Replaces this cell with plain text.
+     */
+    replaceWith(text: string, opts?: TableCellWriteOptions): Promise<ApplyResult>;
+    /**
+     * Inserts a new paragraph before the first direct content block in this cell.
+     */
+    insertParagraphAtStart(text: string, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Inserts a new paragraph after the last direct content block in this cell.
+     */
+    insertParagraphAtEnd(text: string, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Sets direct cell background shading fill color.
+     */
+    setShading(fill: string, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Sets direct cell vertical alignment.
+     */
+    setVerticalAlignment(value: NonNullable<TableCellDirectFormat['verticalAlignment']>, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Sets direct cell width in twips.
+     */
+    setWidth(width: number, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+}
+type TableCellBlock = {
+    type: 'paragraph';
+    paragraph: Paragraph;
+    paraId: string;
+    text: string;
+    index: number;
+} | {
+    type: 'drawing';
+    drawing: Drawing | null;
+    drawingId: string;
+    paraId?: string;
+    index: number;
+} | {
+    type: 'table';
+    table: Table | null;
+    tableId: string;
+    index: number;
+};
+/**
+ * Live handle for text matched inside a table cell.
+ */
+interface CellTextRange {
+    replaceWith(text: string, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    delete(opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    setBold(value: boolean, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    setColor(value: string, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    setItalic(value: boolean, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    setUnderline(value: boolean, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    setHighlight(value: string, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    setFontSize(value: number, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    setFontFamily(value: string, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    addComment(text: string, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    createBookmark(name: BookmarkName$1, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+}
+/**
+ * Live handle for one table row.
+ */
+interface TableRow {
+    /** Parent table id. */
+    readonly tableId: string;
+    /** Zero-based row index. */
+    readonly index: number;
+    /**
+     * Reads the current cell texts for this row.
+     */
+    getCells(opts?: ListTablesOptions): Promise<string[] | null>;
+    /**
+     * Reads the current plain text of this row.
+     *
+     * Cell text is joined using tabs.
+     */
+    getText(opts?: ListTablesOptions): Promise<string | null>;
+    /**
+     * Deletes this row.
+     */
+    delete(opts?: TableRowDeleteOptions): Promise<ApplyResult>;
+    /**
+     * Inserts a row before this row, using this row as the structural template.
+     */
+    insertBefore(cellTexts?: string[], opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Inserts a row after this row, using this row as the structural template.
+     */
+    insertAfter(cellTexts?: string[], opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Sets the row height. Pass `null` to remove the explicit row height.
+     */
+    setHeight(height: RowHeight | null, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+}
+/**
+ * Live handle for one table column.
+ */
+interface TableColumn {
+    /** Parent table id. */
+    readonly tableId: string;
+    /** Zero-based column index. */
+    readonly index: number;
+    /**
+     * Reads the current cell texts for this column.
+     */
+    getCells(opts?: ListTablesOptions): Promise<string[] | null>;
+    /**
+     * Reads the current plain text of this column.
+     *
+     * Cell text is joined using line breaks.
+     */
+    getText(opts?: ListTablesOptions): Promise<string | null>;
+    /**
+     * Sets this column width in twips.
+     */
+    setWidth(width: number, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+}
+interface SectionsApi {
+    /**
+     * 列出主 body 的所有节（#211）。节按 doc-order 排序。
+     * 无 body 或文档无 sectPr 时返回空数组。
+     */
+    list(): Promise<SectionInfo[]>;
+}
+interface TocFieldsApi {
+    /**
+     * 枚举主 body 中的所有 TOC 域（#197）。doc-order 排序。
+     * 无 TOC 域时返回空数组。
+     */
+    list(): Promise<TocFieldRange[]>;
+}
+interface DrawingsApi {
+    /**
+     * 枚举文档 drawing 对象（#189）。
+     * - scope: 'body'（默认）只返回主文档 body 内的 drawing
+     * - scope: 'all' 包含 headers / footers / footnotes / endnotes / comments
+     *
+     * 本 API 只暴露形态信号（kind / extent / wrap / position / isInHeaderFooter 等），
+     * 不下 A / B / C 业务分类结论 —— 那是 #191 / #192 的事。
+     */
+    list(opts?: ListDrawingsOptions): Promise<Drawing[]>;
+    /**
+     * Lists picture drawings only.
+     *
+     * Prefer this over filtering `list()` when the task is explicitly about
+     * images.
+     */
+    listPictures(opts?: ListDrawingsOptions): Promise<PictureDrawing[]>;
+    /**
+     * Lists textbox drawings only.
+     *
+     * Prefer this when the task is explicitly about text boxes.
+     */
+    listTextBoxes(opts?: ListDrawingsOptions): Promise<TextBoxDrawing[]>;
+    /**
+     * Lists plain shape drawings only.
+     *
+     * This does not include pictures, text boxes, charts, SmartArt, groups, or
+     * canvases.
+     */
+    listShapes(opts?: ListDrawingsOptions): Promise<ShapeDrawing[]>;
+    /**
+     * 按 drawingId 精确取单个 drawing，O(1)。不存在返回 null。
+     */
+    get(drawingId: string): Promise<Drawing | null>;
+}
+interface DrawingImageBytes {
+    bytes: Uint8Array;
+    contentType: string;
+    extentEMU: {
+        cx: number;
+        cy: number;
+    };
+}
+/**
+ * Live handle for one drawing object.
+ */
+interface Drawing extends DrawingInfo {
+    /** Stable alias of `drawingId`, kept for object-style APIs. */
+    readonly id: string;
+    /**
+     * Reads current drawing metadata.
+     */
+    getInfo(): Promise<DrawingInfo | null>;
+    /**
+     * Reads original image bytes when this drawing is a picture.
+     */
+    getImageBytes(): Promise<DrawingImageBytes | null>;
+    /**
+     * Deletes this drawing.
+     */
+    delete(opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Replaces a picture drawing with the shared placeholder image.
+     */
+    replaceWithPlaceholder(opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Replaces text inside a shape/textbox drawing.
+     */
+    replaceShapeInnerText(placeholder: string, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+}
+/** `WordDocument.assertNotDisposed` 的桥接签名;避免 sub-apis.ts 反向依赖 WordDocument */
+/**
+ * Live handle for a picture drawing.
+ */
+interface PictureDrawing extends Drawing {
+    readonly kind: 'picture';
+    /**
+     * Reads original image bytes for this picture drawing.
+     */
+    getImageBytes(): Promise<DrawingImageBytes | null>;
+    /**
+     * Replaces this picture with the shared placeholder image while preserving layout.
+     */
+    replaceWithPlaceholder(opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+    /**
+     * Deletes this picture drawing.
+     */
+    delete(opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+}
+/**
+ * Live handle for a textbox drawing.
+ */
+interface TextBoxDrawing extends Drawing {
+    readonly kind: 'textBox';
+    /**
+     * Reads the text currently inside this textbox.
+     *
+     * Returns `null` if the drawing no longer exists or is no longer a textbox.
+     */
+    getText(): Promise<string | null>;
+    /**
+     * Lists live paragraph handles inside this textbox.
+     */
+    getParagraphs(): Promise<Paragraph[]>;
+    /**
+     * Reads direct content blocks inside this textbox, preserving textbox content order.
+     */
+    getBlocks(): Promise<TextBoxBlock[]>;
+    /**
+     * Replaces all textbox content with a single paragraph containing `text`.
+     */
+    replaceText(text: string, opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+}
+type TextBoxBlock = {
+    type: 'paragraph';
+    paragraph: Paragraph;
+    paraId: string;
+    text: string;
+    index: number;
+} | {
+    type: 'drawing';
+    drawing: Drawing | null;
+    drawingId: string;
+    paraId?: string;
+    index: number;
+} | {
+    type: 'table';
+    table: Table | null;
+    tableId: string;
+    index: number;
+};
+/**
+ * Live handle for a plain shape drawing.
+ */
+interface ShapeDrawing extends Drawing {
+    readonly kind: 'shape';
+    /**
+     * Reads current plain-shape metadata such as border/fill and line hints.
+     */
+    getInfo(): Promise<(DrawingInfo & {
+        kind: 'shape';
+    }) | null>;
+    /**
+     * Deletes this plain shape drawing.
+     */
+    delete(opts?: LiveObjectWriteOptions): Promise<ApplyResult>;
+}
+
+/**
+ * WorkerTransport —— 主线程侧的 RPC 客户端。kernel 跑在 Worker,本类负责:
+ *   - 生成 request id
+ *   - postMessage 给 Worker
+ *   - 监听 Worker 回投的 response/error/progress,关联到对应 pending request
+ *   - 返回 Promise,主线程侧消费者像 InlineTransport 一样调用
+ *   - **Worker crash → terminate + reload**(#19,docs/03 §4.7)
+ *
+ * **支持的 Worker 运行时**:
+ *   - Node `worker_threads`(测试路径,#17 本 PR 主要覆盖)
+ *   - 浏览器 `Worker`(代码路径已预留,但本 PR 未在 CI 里验证;#18 / 浏览器示例补齐)
+ *
+ * 错误:Worker 回投的 `SerializableError` 被重建为 `WordError`(如 `code` 存在)或
+ * 原生 `Error`(非 WordError 情况)。
+ *
+ * **Reload 语义(#19)**:
+ *   - 未配置 reload:port 崩溃 → 所有 pending 以底层 error reject(旧行为,防御性兜底)
+ *   - 配置 reload:port 崩溃 → 旧 pending 全部以 `WordError{WORKER_RELOADED}` reject;
+ *     起新 port,重放 load;期间到达的 `call()` 排队,reload 完成后按序 flush
+ */
+
+/**
+ * 抽象 WorkerPort —— Node worker_threads 的 `Worker` 与浏览器 `Worker` 接口不完全一致,
+ * 本接口是公约数。
+ */
+interface WorkerPortLike {
+    postMessage(data: unknown, transferList?: unknown[]): void;
+    /** 注册消息监听 */
+    onMessage(listener: (data: unknown) => void): void;
+    /** 注册错误监听(Worker 内部 crash;Node 侧 exit!=0 也折进这里) */
+    onError(listener: (err: unknown) => void): void;
+    /** terminate —— 返回 Promise 便于 await(某些 API 是 sync void,包成 Promise) */
+    terminate(): Promise<void>;
+}
+/** Reload 所需参数(#19);缺省即关闭 reload,onError 退化为 reject all pending */
+interface WorkerReloadConfig {
+    /** 起一个新 WorkerPortLike(与原 port 同 bundle、同配置) */
+    factory: () => WorkerPortLike | Promise<WorkerPortLike>;
+    /** reload 时重放的 load 参数(保留原始字节 / flat-opc 字符串) */
+    loadParams: KernelLoadParams;
+    /** docId —— WORKER_RELOADED 错误注入用 */
+    docId: string;
+}
+interface WorkerTransportOptions {
+    /** 预先创建好的 WorkerPortLike;创建逻辑由调用方负责(环境差异太大,不在本类里) */
+    port: WorkerPortLike;
+    /** 可选 reload 配置(#19);未传则 worker 崩溃后不重启 */
+    reload?: WorkerReloadConfig;
+}
+type TransportState = 'idle' | 'reloading' | 'disposed';
+declare class WorkerTransport implements Transport {
+    private port;
+    private readonly reloadConfig?;
+    private readonly pending;
+    /** reload 期间新到达的 call() 排队于此,reload 完成后按 FIFO 执行 */
+    private readonly queued;
+    private nextId;
+    private state;
+    /** reload 重放 load RPC 的 promise,dispose 时 await 避免竞态 */
+    private reloadingPromise?;
+    /**
+     * 给 port handler 用的代际序号。每次 reload 把 generation++,旧 port 的 onMessage/onError
+     * 回调里捕获了创建时的 gen,gen 与当前不符就静默丢弃 —— 避免旧 port 的延迟 exit 事件
+     * 错误地触发第二次 reload。
+     */
+    private portGeneration;
+    /**
+     * reload 完成后触发的监听器列表(#23)。SnapshotApi 订阅此以在 worker 重建后
+     * 重新初始化内存栈(nextId / changelog)。每次 reload 成功后、flush queued 前
+     * **串行 await** 所有监听器,避免 queued 的 take() 拿到陈旧 nextId 与 adapter
+     * 里已持久化的 id 撞车。
+     */
+    private readonly reloadListeners;
+    /**
+     * change 事件订阅者(WordDocument.on('change', ...) 的底层挂载点)。worker 内
+     * 每次 applyPlan 成功会 post 一条 RpcEvent('word.change'),本类在 handleIncoming
+     * 里 fan-out 给这里的所有 listener。
+     */
+    private readonly changeListeners;
+    constructor(opts: WorkerTransportOptions);
+    call<T>(method: KernelMethod, args: unknown[], onProgress?: KernelProgress): Promise<T>;
+    /**
+     * 04.2 §六:走独立 RPC method `'script.execute'`,**不**进 KernelMethod 联合。
+     * worker-entry 在收到该 method 时分支到 script-execute,绕过 kernelHandlers。
+     *
+     * **超时语义(04.2 §四,#144):**
+     *
+     * - 主线程持有**硬超时**:`timeoutMs > 0` 时 setTimeout;超时未 resolve → 调
+     *   `handleWorkerError` 主动触发 reload 路径。所有 pending 以 `WordError(WORKER_RELOADED)`
+     *   reject;`worker.terminate()` + 起新 worker + 重放 `load`。
+     * - **不**把 `timeoutMs` 传给 worker —— worker 内 `script-execute.ts` 用 `0` 表示不 race,
+     *   完全交主线程 terminate(避免 worker 内对死循环类同步阻塞无能为力)。
+     * - `timeoutMs === 0` → 主线程不设硬超时(可能 hang,由调用方风险自负)。
+     *
+     * **Abort 语义(#151):**
+     *
+     * - 接 \`AbortSignal\`;abort 触发与 timeout 走**同一条路径**(handleWorkerError →
+     *   reload)。pending RPC 以 \`WordError(WORKER_RELOADED)\` reject;\`worker.terminate()\`
+     *   立即终止正在运行的脚本(包括同步死循环类阻塞)。
+     * - 上层(plugin / agent)负责把 abort cause 转为 \`AgentAbortError\`(L2),不影响
+     *   transport 层契约:transport 只管 reload,语义解读由 agent。
+     */
+    executeScript(code: string, args: Record<string, unknown> | undefined, timeoutMs: number, signal?: AbortSignal): Promise<unknown>;
+    dispose(): Promise<void>;
+    private attachPortHandlers;
+    private sendCall;
+    private handleIncoming;
+    private handleWorkerError;
+    private reloadAfterCrash;
+    /**
+     * 注册 reload 完成回调(#23)。返回取消订阅函数。listener 可返回 Promise,
+     * reload 流程会串行 await 每个 listener 完成后再 flush queued RPC。
+     *
+     * 触发时机:worker crash → new port + load 重放成功 → state 切回 idle 之后、
+     * flush queued 之前。SnapshotApi 在此重建 nextId(从 adapter.list 读已有快照)。
+     */
+    onReload(listener: () => void | Promise<void>): () => void;
+    onChange(listener: (ev: KernelChangeEvent) => void): () => void;
+    /**
+     * @internal test-only:手动模拟一次 worker 崩溃。
+     * 触发 reload 流程(若 reloadConfig 已配),供 `worker-reload.test.ts` 使用。
+     */
+    _triggerCrashForTest(err?: Error): void;
+    /** @internal test-only:查状态机,用于断言 reload 完成 */
+    _getStateForTest(): TransportState;
+}
+
+/**
+ * SnapshotApi —— WordDocument.snapshots 子 API(docs/03.2 §2)。
+ *
+ * 职责:
+ *   - `take(reason?, details?)`:通过 transport 让 kernel 序列化 parts,捆装 info + parts 为
+ *     SnapshotPayload,交给 adapter.save,返回 id
+ *   - `rollback(id, opts?)`:从 adapter.load 取回 payload,通过 transport 让 kernel 用 parts
+ *     重建 pkg;消费语义 —— 成功后 adapter.delete;支持 `opts.onProgress` 分阶段上报
+ *     (parse / build-indices / done,docs/03.2 §6)
+ *   - `list / delete / clear`:直通 adapter
+ *   - `recordChange / changes`:**主线程同步**,不过 transport(零 RPC 开销;docs/03.2 §7)
+ *
+ * 新增 #22:
+ *   - FIFO 上限(默认 10,`SnapshotApiInit.maxSnapshots` 可配),take 成功后若超限则按
+ *     `adapter.list` 的自增顺序淘汰最早的(`adapter.delete`)
+ *   - `rollback` 的 `onProgress` 透传给 transport.call,InlineTransport 直达,
+ *     WorkerTransport 通过 RpcProgress 穿过 Worker 边界
+ */
+
+/** 默认 FIFO 上限(docs/03.2 §3.2) */
+declare const DEFAULT_MAX_SNAPSHOTS = 10;
+/** rollback 的进度回调:phase 分 'parse' | 'build-indices' | 'done'(docs/03.2 §6) */
+type RollbackProgress = (phase: string, pct?: number) => void;
+interface RollbackOptions {
+    onProgress?: RollbackProgress;
+}
+/**
+ * `take` 可选参数(#108,docs/03.2 §3.3)。
+ *
+ * - `pin: true` —— 标记该快照 **不参与 FIFO 淘汰**;即使达到 `maxSnapshots`,
+ *   FIFO 也会跳过 pinned 的条目,转而淘汰最老的**非 pinned** 快照。
+ * - `pin: undefined | false` —— 与不传 options 等价,普通快照。
+ *
+ * **使用约束**(agent 层自行约束,core 不强制):pinned 主要给 SDK 内部使用
+ * (例 `WordAgent.create` 的 session-start 快照),plugin 层的 `AgentContext.snapshots`
+ * 应强制 `pin: false`,避免 plugin 把存储塞满 pinned 导致 FIFO 失效。
+ */
+interface TakeOptions {
+    pin?: boolean;
+    /**
+     * 可选逻辑去重域。提供后，若该域最新快照的 contentHash 与当前文档相同，
+     * `take` 直接返回已有 id，不创建新快照。不同 owner/用途必须使用不同 key。
+     */
+    dedupeKey?: string;
+}
+interface SnapshotApi {
+    /**
+     * 保存当前文档状态为一个新快照,返回自增 id(snap-0 / snap-1 / ...)。
+     * 已累加的 changelog 项会一次性吸入新快照的 `changesCaptured`,然后主线程 changelog 清零。
+     *
+     * 超过 `maxSnapshots`(默认 10,docs/03.2 §3.2)时,按 `adapter.list` 返回顺序淘汰
+     * 最早的**非 pinned** 快照;pinned 快照永不淘汰(#108,docs/03.2 §3.3)。
+     *
+     * **能力边界**:若存储里的非 pinned 名额都满而仍要继续 take 普通快照,SDK 会尝试
+     * 按正常 FIFO 淘汰最老非 pinned;若所有快照都是 pinned,则新 take 会直接成功
+     * 保存(超出 maxSnapshots 但无可淘汰目标),SDK 发 `console.warn` 提示;
+     * 上游自行控制 pinned 数量。
+     */
+    take(reason?: string, details?: unknown, options?: TakeOptions): Promise<string>;
+    /**
+     * 用给定 id 的快照覆盖当前文档状态,但**不删除**快照。
+     *
+     * 供需要把恢复结果提交到外部宿主的场景使用:宿主应先 restore,待外部写回成功后
+     * 再显式 delete。这样宿主写回失败时仍可重试同一快照。
+     */
+    restore(id: string, opts?: RollbackOptions): Promise<void>;
+    /**
+     * 用给定 id 的快照覆盖当前文档状态,**消费式**:成功后该快照被 adapter.delete。
+     * 其它快照不受影响。
+     *
+     * `opts.onProgress` 按阶段回调:'parse'(0→100)/ 'build-indices'(0)/ 'done'(100)。
+     */
+    rollback(id: string, opts?: RollbackOptions): Promise<void>;
+    /** 按 id 自增序返回所有快照的 meta(不含 parts 字节) */
+    list(): Promise<SnapshotInfo[]>;
+    /** 按 id 删除某个快照。不存在时静默(幂等) */
+    delete(id: string): Promise<void>;
+    /** 清空该 docId 下的所有快照 */
+    clear(): Promise<void>;
+    /** 主线程同步累加一条 change,下次 take 时会一并吸入 */
+    recordChange(change: {
+        toolName: string;
+        summary?: unknown;
+    }): void;
+    /** 读当前未吸入的 change 数组(主线程同步) */
+    changes(): ChangeLog[];
+    /**
+     * **内部用**:WordDocument 首次装载时从 adapter 恢复 nextId。失败会向上抛，
+     * 防止在无法读取历史时从 snap-0 开始覆盖持久数据。
+     */
+    initializeFromStorage(): Promise<void>;
+    /**
+     * **内部/测试用**:worker reload 完成后由 transport 自动触发,主线程不应直接调。
+     *
+     * 语义(#23,docs/03.2 §9.1):
+     *   - 从 adapter.list(docId) 读已持久化快照,把 `nextId` 重设为 `max(snap-<N>) + 1`
+     *   - `changelog` 清零(reload 期间主线程的 changelog 视为丢失,无法恢复)
+     *   - adapter 里已保存的字节不受影响,rollback 仍可用
+     */
+    reinitializeAfterReload(): Promise<void>;
+}
+
+/**
+ * WordDocument —— Word core 的顶层句柄(docs/03.1 §2)。
+ *
+ * 本 PR(#17)把装载 / 输出 / dispose 的真实执行改走 `Transport` 抽象:
+ *   - **inline 模式**:`InlineTransport` 直接在主线程创建 Kernel,零 RPC 开销
+ *   - **worker 模式**:`WorkerTransport` 把调用序列化成 RPC 消息经 postMessage 发给
+ *     Worker 内的 Kernel(Node worker_threads 路径在本 PR 就绪,浏览器 Worker 路径
+ *     留 #18 / 浏览器示例)
+ *
+ * 对消费方完全透明:`WordDocument.fromZip(buf, { mode: 'worker' })` 与 inline 行为一致,
+ * 只是 Kernel 跑在另一线程。`_getPackage` / `_getIndices` 在 worker 模式下会抛错(
+ * Package 在另一线程,无法直接返回引用)。查询类 API(#24 起)将改走 RPC 方法。
+ */
+
+type RuntimeMode = 'auto' | 'worker' | 'inline';
+/**
+ * 模式决策的"为什么"。配合 `mode` 让外部平台一眼看清落 inline 还是 worker、以及是哪条规则。
+ *
+ * - `explicit-inline` / `explicit-worker`:消费方在 LoadOptions.mode 显式指定
+ * - `auto/inside-worker-thread`:已在 Node worker_threads 子线程内,拒绝再 spawn
+ * - `auto/node-with-worker-config`:Node 主线程 + 配了 workerFactory / workerBundleUrl
+ * - `auto/node-no-worker-config`:Node 主线程但 worker 基础设施未配,静默 fallback
+ * - `auto/browser-factory`:浏览器侧消费方提供了 workerFactory
+ * - `auto/browser-global`:浏览器侧粗检测到全局 Worker 构造器
+ * - `auto/fallback`:都不命中的兜底
+ */
+type ModeSource = 'explicit-inline' | 'explicit-worker' | 'auto/inside-worker-thread' | 'auto/node-with-worker-config' | 'auto/node-no-worker-config' | 'auto/browser-factory' | 'auto/browser-global' | 'auto/fallback';
+interface ModeDecision {
+    mode: 'worker' | 'inline';
+    source: ModeSource;
+}
+/** onProgress 回调的 phase 枚举 */
+type LoadPhase = 'fetch' | 'parse' | 'normalize';
+interface LoadOptions {
+    /**
+     * 文档身份标识(必填)。宿主提供,典型值 = 文件路径 hash。
+     * - 作为 WordError.docId 自动注入
+     * - 作为快照系统命名空间 key(详见 docs/03.2)
+     */
+    docId: string;
+    /**
+     * 运行时模式(docs/03 §4.2):
+     * - `'inline'`:主线程运行 kernel
+     * - `'worker'`:显式要求 Worker;不可用时抛 WORKER_CREATION_FAILED
+     * - `'auto'`(默认):按 §4.3 顺序检测;不可用时静默 fallback 到 inline
+     */
+    mode?: RuntimeMode;
+    /**
+     * 装载时模式决策回调(#TBD,docs/03 §4.3)。
+     *
+     * - 设了:用 `decision.mode` / `decision.source` 自定义打点,**不再走默认 console.info**
+     * - 未设:走默认 `console.info('[coco-office:word] mode=... source=... docId=...')`
+     *
+     * 平台侧可借此把决策写入自有日志体系,或在 UI 上展示当前 SDK 的执行模式。
+     */
+    onModeResolved?: (decision: ModeDecision, docId: string) => void;
+    onProgress?: (phase: LoadPhase, pct?: number) => void;
+    snapshotStorage?: SnapshotStorageAdapter;
+    /**
+     * 快照 FIFO 上限,未设则用 `DEFAULT_MAX_SNAPSHOTS`(10,docs/03.2 §3.2)。
+     * 必须 >= 1 的整数;测试场景可调低方便验证淘汰行为。
+     */
+    maxSnapshots?: number;
+}
+/** 宿主可以自定义 Worker 创建方式(测试 / 非标准环境)*/
+type WorkerFactory = () => WorkerPortLike | Promise<WorkerPortLike>;
+declare class WordDocument {
+    readonly docId: string;
+    readonly mode: 'worker' | 'inline';
+    /** 决策来源(配合 `mode` 让外部平台看清是哪条规则把它送到这个模式的) */
+    readonly modeSource: ModeSource;
+    readonly paragraphs: ParagraphApi;
+    readonly bookmarks: BookmarkApi;
+    readonly comments: CommentApi;
+    readonly context: ContextApi;
+    readonly revisions: RevisionApi;
+    readonly styles: StylesApi;
+    /** 表格枚举与结构分析（#185）*/
+    readonly tables: TablesApi;
+    /** Drawing 对象枚举（#189）*/
+    readonly drawings: DrawingsApi;
+    /** 节（section）枚举（#211）*/
+    readonly sections: SectionsApi;
+    /** TOC 域枚举（#197）*/
+    readonly tocFields: TocFieldsApi;
+    /** 快照子 API(docs/03.2);每个 WordDocument 独立实例 */
+    readonly snapshots: SnapshotApi;
+    private readonly transport;
+    private readonly initialBytes?;
+    private readonly initialFlatOpc?;
+    readonly snapshotStorage: SnapshotStorageAdapter;
+    private disposed;
+    /**
+     * change 订阅者表。每个条目记 listener + 它的订阅选项。第一次有人订阅时绑
+     * `transport.onChange`(由 `subscribeTransportLazy()` 控制),最后一个取消订阅时
+     * 不解绑(简化实现;listener 集合空时 dispatch 是 no-op)。
+     *
+     * 派发顺序:每个 listener 各自串行(`tail` 链),不同 listener 并行。这样保证
+     * 同一订阅者按变更发生顺序看到事件,即便其 handler 是 async + 上一次 toFlatOpc
+     * 还没回。跨订阅者不串行,避免一个慢 handler 卡住别人。
+     */
+    private readonly changeSubscribers;
+    private changeTransportUnsubscribe?;
+    private constructor();
+    static createBlank(opts: LoadOptions): Promise<WordDocument>;
+    static fromZip(buf: Uint8Array | ArrayBuffer, opts: LoadOptions): Promise<WordDocument>;
+    static fromFlatOpc(xml: string, opts: LoadOptions): Promise<WordDocument>;
+    toZip(): Promise<Uint8Array>;
+    toFlatOpc(): Promise<string>;
+    dispose(): Promise<void>;
+    /**
+     * 在与本文档同上下文(worker / inline)中执行一段用户脚本。
+     *
+     * 04.2 §六 冻结的运行时环境:
+     * - 脚本以 `new Function('doc', 'args', 'fs', body)(doc, args, fs)` 形式跑
+     * - `doc` = worker 内 Kernel 实例;脚本可同步访问 `doc.listParagraphs()` 等
+     * - `args` = structured-cloneable 入参
+     * - `fs` v1 在 worker 内不传(主线程 plugin 已用过)
+     * - 顶层允许 `await`;`return expression` 即结果
+     *
+     * **agent 层 `execute_code` / `execute_file` tool 通过本方法桥接到执行通道**(04.2 §五)。
+     *
+     * @param code  JS 源码;函数体形态
+     * @param args  传给脚本的参数
+     * @param timeoutMs 超时毫秒数,默认 30000;0 = 不超时
+     * @param signal 可选 AbortSignal(#151):abort 触发 → worker 立即 terminate + reload;
+     *               inline 模式下 race 拒绝(主线程立即返回,但脚本仍后台跑)
+     * @throws  语法错误 / 脚本运行错 / 超时 / abort
+     *
+     * @see docs/04.2-脚本执行-Tool设计.md §二 §六
+     */
+    executeCode(code: string, args?: Record<string, unknown>, timeoutMs?: number, signal?: AbortSignal): Promise<unknown>;
+    /**
+     * 订阅文档变更事件。在 kernel.applyPlan 成功后触发,涵盖两条入口:
+     *
+     *   - `doc.plan().apply()`        →  ev.source === 'plan'
+     *   - `doc.executeCode(script)`   →  ev.source === 'script'(脚本调 `doc.applyPlan`)
+     *
+     * **不**触发的场景:空 plan;applyPlan 抛错回滚;脚本绕过 kernel.applyPlan 直接
+     * 改 `doc.getPackage()` 的 DOM(v1 不覆盖,见 change-events.ts 注释)。
+     *
+     * **fullDocument 选项**:默认 `'none'`(只发 `{ ops, result, source }`),不付输出
+     * 代价。设为 `'flatOpc'` / `'zip'` 时,WordDocument 在派发前调一次对应方法把全文
+     * 档塞进 payload —— **每次变更一次开销**,worker 模式下还要再 RPC + structured-clone,
+     * 大文档可达几百 ms。多订阅者同次事件共享拉取,因此打开多个 'flatOpc' 订阅不会
+     * 重复跑 toFlatOpc。
+     *
+     * **派发顺序**:同一订阅者按变更发生顺序串行调用 handler(即便 handler 是 async),
+     * 不同订阅者并行 —— 一个慢 handler 不会卡住别人。
+     *
+     * @returns 取消订阅函数。重复调用安全(幂等)。
+     */
+    on(event: 'change', handler: ChangeListener, opts?: ChangeSubscribeOptions): () => void;
+    private subscribeTransportLazy;
+    /**
+     * 把 kernel 推上来的 KernelChangeEvent 转成对外 ChangeEvent,fan-out 给订阅者。
+     * 优化:多订阅者要同一种全文档输出时只拉一次。每个订阅者自己串行(tail chain),
+     * 跨订阅者并行。
+     */
+    private dispatchChange;
+    /**
+     * 创建新 WordPlan(docs/03.1 §2 / §3)。
+     *
+     * - 同步返回,不走 RPC;链式方法只把 op push 进队列,真正 RPC 在 `apply()` 触发
+     * - 多 plan 可并存,各自独立状态(每次调用返回新实例)
+     * - `opts.author` 缺省时走 `WordDocument.setDefaultAuthor` 配置的值;都缺则空串
+     * - `opts.trackChanges` 默认 false
+     * - `opts.date` 默认 `new Date()`(在 addComment 等 op 里实际需要时再取)
+     *
+     * **能力实现进度**(#27 仅提供容器与 apply 状态机;op executor 分批落地):
+     *   - 段落修改 → #28
+     *   - 段落插入 / 删除 → #29
+     *   - 书签 → #34
+     *   - 批注 → #35
+     *   - 修订 accept/reject → #31 / #32
+     *
+     * 本 PR 期间,任何非空 plan 的 `apply()` 会抛 `UNSUPPORTED_OOXML_FEATURE`。
+     */
+    plan(opts?: PlanOptions): WordPlan;
+    /**
+     * Appends a plain-text paragraph at the end of the main document body.
+     */
+    appendParagraph(text: string, opts?: ParagraphInsertOptions): Promise<ApplyResult>;
+    /** @internal 仅 inline 模式可用(Package 跨 Worker 边界不可直接引用)*/
+    _getPackage(): Package;
+    /** @internal 仅 inline 模式可用 */
+    _getIndices(): PackageIndices;
+    /** @internal inline-only cache diagnostics for core tests. */
+    _debugCacheSnapshot(): WordDomainCacheSnapshot;
+    /** @internal inline-only cache invalidation for consistency tests. */
+    _debugInvalidateCache(domain?: DomainCacheName, reason?: string): void;
+    /** @internal 装载时的初始字节(#19 worker reload 需要)*/
+    _getInitialBytes(): Uint8Array | undefined;
+    /** @internal 装载时的初始 Flat OPC 字符串 */
+    _getInitialFlatOpc(): string | undefined;
+    /** @internal #19 测试用:拿到底层 transport 实例(模拟 worker crash) */
+    _getTransport(): Transport;
+    private assertNotDisposed;
+    static setDefaultMode(mode: RuntimeMode): void;
+    /**
+     * 不创建实例,查当前环境 `'auto'` 模式会选什么。真实反映决策结果
+     * (docs/03 §4.3):
+     *
+     *   1. 已在 Node worker_threads 上下文中 → inline(避免二次 spawn)
+     *   2. Node 环境:
+     *        - 配了 workerFactory / workerBundleUrl → worker
+     *        - 否则 → inline
+     *   3. 浏览器(或类浏览器)环境:
+     *        - 配了 workerFactory → worker
+     *        - 全局 `Worker` 存在 → worker(粗检测,真实 ping 见 #52)
+     *        - 否则 → inline
+     *   4. 以上都不满足 → inline
+     */
+    static detectMode(): 'worker' | 'inline';
+    /**
+     * 同 `detectMode()`,但返回决策来源,便于平台诊断为什么 auto 落到了某个模式。
+     */
+    static detectModeDecision(): ModeDecision;
+    static setDefaultAuthor(author: string): void;
+    /** 配置自定义 Worker 工厂(测试 / 非 Node-worker_threads 环境)*/
+    static setWorkerFactory(factory: WorkerFactory | undefined): void;
+    /** 配置 Node worker_threads 加载的 bundle URL(通常是 tsup 产物 dist/kernel-worker.mjs)*/
+    static setWorkerBundleUrl(url: string | URL | undefined): void;
+    /** 配置全局默认快照存储。未设 + LoadOptions 也未传 → `InMemorySnapshotStorage`(每次装载独立实例) */
+    static setDefaultSnapshotStorage(adapter: SnapshotStorageAdapter | undefined): void;
+    /** @internal */
+    static _getDefaultAuthor(): string;
+    /** @internal */
+    static _getDefaultMode(): RuntimeMode;
+    /** @internal */
+    static _resetDefaults(): void;
+}
+
+/**
+ * 跨 parts 事务 —— docs/03 §13.5 的落地。
+ *
+ * Plan.apply 的底层原语:在一组 part 上执行可能失败的 work,失败时回滚到 work 前状态。
+ *
+ * 设计:
+ *   - 进入事务前,对 `affectedPartPaths` 里每个已存在的 part 做深拷贝快照(xmlDom / bytes / _dirty)
+ *   - 记录哪些 path 在 work 开始时**不存在**(新建场景)
+ *   - work 内可自由变更 part(包括新增 / 删除 / 改 xmlDom)
+ *   - 抛错时:
+ *     * 原本存在的 part → 从快照恢复 xmlDom / bytes / _dirty
+ *     * 原本不存在但 work 新增的 part → 从 pkg 删除
+ *   - 成功时:保持 work 结束时的状态(work 自己负责 markDirty)
+ *
+ * 当前实现:deepClone 整个 xmlDom,在 10 万段落档上约 1-2s,优化(反向 op 记录)留后续 issue。
+ */
+
+/**
+ * 在 `pkg` 上执行可能失败的 `work`。事务作用域仅覆盖 `affectedPartPaths` 列出的 parts:
+ *   - work 抛错 → 被列出的 parts 回滚到进入事务前状态(xmlDom / bytes / _dirty),新增的 parts 删除
+ *   - work 成功 → 返回 work 的结果
+ *
+ * **调用方职责**:
+ *   - `affectedPartPaths` 必须包含 work 里**所有可能触达**的 part 路径(读 + 写 + 新增)
+ *   - 未在列表里的 part 即便被 work 改动,回滚时不会被恢复
+ */
+declare function runTransaction<T>(pkg: Package, affectedPartPaths: readonly string[], work: () => Promise<T> | T): Promise<T>;
+
+/**
+ * XQuery Update Facility 封装 —— docs/03 §13.2 的 "PUL apply" 行。
+ *
+ * 对 fontoxpath 的 `evaluateUpdatingExpression` + `executePendingUpdateList` 做轻量包装:
+ *   - 输入:XQuery Update 表达式 + 上下文节点
+ *   - 输出:PUL 条目数量(mutations) + 应用后的 xdmValue
+ *
+ * 用法例:
+ *   ```ts
+ *   await applyXQueryUpdate(
+ *     paraElement,
+ *     'replace value of node ./w:r/w:t with "new text"',
+ *     { namespaceResolver: (p) => p === 'w' ? W_NS : null }
+ *   );
+ *   ```
+ *
+ * 注意：fontoxpath 没有 package.json `exports` 字段，其 main 是 UMD bundle，
+ * Node.js ESM 加载器无法静态解析命名导出，因此改用惰性动态 import()。
+ * Node.js 在 ESM 中 import() 一个 CJS/UMD 模块时，会将其 module.exports 包装
+ * 成 { default: <module.exports> }，故下方通过 `.default` 取出完整 API。
+ *
+ * 注意：XQuery 表达式自身性能需要调用方注意 —— 参见 docs/03 §13.2 的 460× 悬崖(
+ * 无谓词 //w:p 在 10 万段落上 36s)；本函数不做防御，调用方应只传写针对特定 element
+ * 的精确表达式。
+ */
+interface XQueryUpdateOptions {
+    /** 命名空间 prefix → URI 的解析器。默认 null（表达式不含 prefix） */
+    namespaceResolver?: (prefix: string) => string | null;
+    /** 外部变量（$name → 值） */
+    variables?: Record<string, unknown>;
+}
+interface XQueryUpdateResult {
+    /** PUL 条目数量（该次应用的变更数） */
+    mutations: number;
+    /** 表达式返回值（XQuery Update 通常无返回值，此处保持 opaque） */
+    xdmValue: unknown[];
+}
+declare function applyXQueryUpdate(contextNode: Node, expression: string, options?: XQueryUpdateOptions): Promise<XQueryUpdateResult>;
+
+/**
+ * Worker RPC 协议 —— docs/03 §4.1 / §4.7。
+ *
+ * 主线程(WordDocument 代理)与 Worker 内 kernel 之间通过 postMessage 交换五类消息:
+ *   - request:  { kind: 'request',  id, method, args }     —— 主 → Worker
+ *   - response: { kind: 'response', id, result }           —— Worker → 主(成功)
+ *   - error:    { kind: 'error',    id, error }            —— Worker → 主(失败)
+ *   - progress: { kind: 'progress', id, phase, pct? }      —— Worker → 主(onProgress 回调)
+ *   - event:    { kind: 'event',    event, payload }       —— Worker → 主(server-push,
+ *               与某个 request 无关;v1 仅用于 'word.change')
+ *
+ * id 是一个 UUID-ish 字符串,主线程用它关联 pending request 与返回的 response/error。
+ *
+ * 错误使用 serializable 形态(code / message / docId / details),跨 Worker 边界后主
+ * 线程用它重建 `WordError` 实例 → 抛给调用方。
+ */
+
+/** 主线程 → Worker 的方法调用 */
+interface RpcRequest {
+    kind: 'request';
+    id: string;
+    method: string;
+    args: unknown[];
+}
+/** Worker → 主线程:方法成功返回 */
+interface RpcResponse {
+    kind: 'response';
+    id: string;
+    result: unknown;
+}
+/** Worker → 主线程:方法抛错。错误以字段形态序列化,主线程侧重建 WordError */
+interface RpcError {
+    kind: 'error';
+    id: string;
+    error: SerializableError;
+}
+/** 序列化后的错误负载(跨 Worker 边界友好) */
+interface SerializableError {
+    /** WordError.code;如果抛的是非 WordError,此字段为 undefined,主线程包装成 PACKAGE_CORRUPT */
+    code?: WordErrorCode;
+    message: string;
+    /** WordError.docId;非 WordError 时可能为空串 */
+    docId?: string;
+    details?: Record<string, unknown>;
+    /** 原始错误 name(Error/TypeError/...),调试用 */
+    name?: string;
+    /** 原始 stack(调试用;跨 worker 后行号不可靠,仅参考) */
+    stack?: string;
+}
+/** Worker → 主线程:onProgress 回调 */
+interface RpcProgress {
+    kind: 'progress';
+    /** 关联的 request id */
+    id: string;
+    phase: string;
+    pct?: number;
+}
+/**
+ * Worker → 主线程:server-push 事件。与某个 request 无关,因此**没有** id 字段。
+ * v1 仅用于 `'word.change'`(applyPlan 成功后从 worker 推到主线程,主线程 fan-out
+ * 给 `WordDocument.on('change', ...)` 订阅者)。
+ *
+ * payload 必须 structured-cloneable;接收侧按 event 名做类型 narrowing。
+ */
+interface RpcEvent {
+    kind: 'event';
+    event: string;
+    payload: unknown;
+}
+type RpcMessage = RpcRequest | RpcResponse | RpcError | RpcProgress | RpcEvent;
+
+/**
+ * 浏览器 `Worker` → `WorkerPortLike` 适配器。
+ *
+ * 用于配合 `WordDocument.setWorkerFactory()`:消费方拿到自己 bundler 解析出的 worker
+ * 实例(Vite `?worker`、`new Worker(new URL(...))`、或预构造的 Worker)后,直接传进来:
+ *
+ * ```ts
+ * import KernelWorker from '@coco-vexel/coco-office/kernel-worker-browser?worker';
+ * import { WordDocument, createBrowserWorkerPort } from '@coco-vexel/coco-office/word';
+ *
+ * WordDocument.setWorkerFactory(() => createBrowserWorkerPort(new KernelWorker()));
+ * ```
+ *
+ * 仅在浏览器 / WPS 等具备 `Worker` 全局的环境可用。Node 路径请用 `createNodeWorkerPort`。
+ */
+
+/**
+ * 把已构造好的浏览器 `Worker`(或 WPS Chromium 内的等价实例)包成 `WorkerPortLike`。
+ *
+ * `terminate()` 同步触发底层 `worker.terminate()`,并 resolve(浏览器 API 是 sync void,
+ * 这里包成 Promise 与 Node 路径对齐)。
+ */
+declare function createBrowserWorkerPort(worker: Worker): WorkerPortLike;
+
+type WordCodePlanApiDomain = 'document' | 'paragraph' | 'bookmark' | 'table' | 'drawing' | 'range' | 'comment' | 'revision' | 'style' | 'section' | 'context' | 'toc' | 'snapshot';
+type WordCodePlanApiKind = 'locator' | 'read' | 'write' | 'format' | 'lifecycle';
+type WordCodePlanReceiverMap = {
+    doc: WordDocument;
+    'doc.paragraphs': ParagraphApi;
+    'doc.bookmarks': BookmarkApi;
+    'doc.comments': CommentApi;
+    'doc.context': ContextApi;
+    'doc.revisions': RevisionApi;
+    'doc.styles': StylesApi;
+    'doc.tables': TablesApi;
+    'doc.drawings': DrawingsApi;
+    'doc.sections': SectionsApi;
+    'doc.tocFields': TocFieldsApi;
+    'doc.snapshots': SnapshotApi;
+    paragraph: Paragraph;
+    range: TextRange;
+    bookmark: Bookmark;
+    comment: Comment;
+    revision: Revision;
+    table: Table;
+    cell: TableCell;
+    row: TableRow;
+    column: TableColumn;
+    drawing: Drawing;
+    picture: PictureDrawing;
+    textBox: TextBoxDrawing;
+    shape: ShapeDrawing;
+};
+type ReceiverName = keyof WordCodePlanReceiverMap;
+type MethodName<T> = {
+    [K in keyof T]-?: T[K] extends (...args: never[]) => unknown ? K : never;
+}[keyof T] & string;
+type WordCodePlanSdkApiPath = {
+    [R in ReceiverName]: `${R}.${MethodName<WordCodePlanReceiverMap[R]>}`;
+}[ReceiverName];
+interface WordCodePlanApiManifestEntry {
+    path: WordCodePlanSdkApiPath;
+    domain: WordCodePlanApiDomain;
+    kind: WordCodePlanApiKind;
+    codeplan: boolean;
+    requiresAwait: boolean;
+    reason?: string;
+}
+declare const WORD_CODEPLAN_API_MANIFEST_VERSION = 1;
+declare const WORD_CODEPLAN_API_MANIFEST: readonly WordCodePlanApiManifestEntry[];
+declare const WORD_CODEPLAN_ALLOWED_API_PATHS: WordCodePlanSdkApiPath[];
+
+export { type ApplyPlanParams, type ApplyResult, type Bookmark, type BookmarkApi, type BookmarkInfo, type BookmarkName$1 as BookmarkName, type CellTextRange, type ChangeEvent, type ChangeListener, type ChangeSubscribeOptions, type Comment, type CommentApi, CommentId$1 as CommentId, CommentInfo, type ContextApi, type ContextBlock, type ContextBookmark, type ContextSearchHighlight, type ContextSearchInclude, type ContextSearchMatch, type ContextSearchOptions, type ContextSearchResult, type ContextSearchTarget, DEFAULT_MAX_SNAPSHOTS, type DateSdtSpec, type Drawing, type DrawingImageBytes, DrawingInfo, type DrawingsApi, EMPTY_APPLY_RESULT, type EnsureParaIdsResult, InlineTransport, type InsertParagraphSpec, Kernel, type KernelChangeEvent, type KernelLoadParams, type KernelLoadSource, type ListBookmarksOptions, ListDrawingsOptions, ListParagraphsOptions, ListResult, ListRevisionsOptions, ListStylesOptions, ListTablesOptions, type LiveObjectWriteOptions, type LoadOptions, type LoadPhase, type ModeDecision, type ModeSource, type Op, PackageIndices, type ParaId, type Paragraph, type ParagraphApi, type ParagraphDeleteOptions, ParagraphInfo, type ParagraphInsertImageSpec, type ParagraphInsertOptions, type ParagraphInsertTableSpec, type ParagraphList, type ParagraphRange, type ParagraphReplaceOptions, type PictureDrawing, type PlainTextSdtSpec, type PlanOptions, type PlanValidationIssue, type PlanValidationItem, type PlanValidationResult, type Range, type RangeClassification, type Revision, type RevisionApi, type RevisionId, RevisionInfo, type RevisionScope, type RichTextSdtSpec, type RollbackOptions, type RollbackProgress, RowHeight, type RpcError, type RpcEvent, type RpcMessage, type RpcProgress, type RpcRequest, type RpcResponse, type RuntimeMode, type SdtSpec, SectionInfo, type SectionsApi, type SerializableError, type ShapeDrawing, type SnapshotApi, type SnapshotPartEntry, StoryId, StyleInfo, type StylesApi, type Table, type TableCell, type TableCellBlock, TableCellInfo, type TableColumn, TableInfo, type TableRow, TableVerbatim, type TablesApi, type TextBoxDrawing, type TextRange, type TextRange$1 as TextRangeDescriptor, type TocFieldRange, type TocFieldsApi, type Transport, WORD_CHANGE_EVENT, WORD_CODEPLAN_ALLOWED_API_PATHS, WORD_CODEPLAN_API_MANIFEST, WORD_CODEPLAN_API_MANIFEST_VERSION, type WordCodePlanApiDomain, type WordCodePlanApiKind, type WordCodePlanApiManifestEntry, type WordCodePlanSdkApiPath, WordDocument, WordError, type WordErrorCode, type WordPlan, WordPlanImpl, type WordPlanImplInit, type WorkerFactory, type WorkerPortLike, WorkerTransport, type XQueryUpdateOptions, type XQueryUpdateResult, applyXQueryUpdate, buildInlineSdt, classifyRange, createBrowserWorkerPort, ensureParaIds, getBookmark, hashSdtId, listBookmarks, listTocFields, runTransaction, searchContext };