@webskill/sdk 0.21.0 → 0.22.0

package/dist/browser.d.ts

@@ -1,6 +1,6 @@
-import { At as UnsignedPolicy, Dt as TrustedKeyStore, H as FileStat, Mt as VerifyResult, N as ArchiveLimits, Nt as WebSkillError, S as UiBridge, U as FileSystemProvider, W as FileWriteStream, b as RenderResultRequest, c as InteractionResponse, l as LlmClient, m as LlmStreamEvent, mt as SkillInstallSource, o as InteractionPolicy, p as LlmResponse, s as InteractionRequest, u as LlmCompleteInput, v as MemoryStore, vt as SkillManifest, wt as SkillsLockfile } from "./types-BvTV_05--BW8zDuEk.js";
-import { M as DocumentSurfaceHost, R as ExternalSkillProvider, Rr as parseBridgeRequest, S as BridgeResponse, Sn as ToolDefinition, Tn as ToolResult, Xt as ScriptExecutor, Yt as ScriptExecutionContext, ct as NetworkPolicy, fr as bridgeError, ir as WebSkillApi, m as ApprovalScope, ot as LinkedDocumentReader, x as BridgeRequest, y as BridgeCapabilities, z as ExternalToolSource } from "./index-DHopiH_m.js";
-import { At as PageActionRequest, Et as PageActionOutcome, H as DocxDocumentContent, It as PageAuditSink, Ln as XlsxDocumentContent, Lt as PagePerceptionPolicy, Mt as PageActionScopeInput, Nt as PageActionTarget, Qt as PerceptionResult, Rn as XlsxDocumentReader, U as DocxDocumentReader, Ut as PdfDocumentReader, Yt as PerceptionCaptureOptions, _n as SubtreeRejection, dt as NestedFrameRef, en as PerceptionScopeInput, qt as PerceivedNode, s as ConsentUi, wt as PageActionExecutor, zt as PagePerceptionReader } from "./index-CYLt5u4L.js";
+import { G as FileStat, It as VerifyResult, K as FileSystemProvider, Lt as WebSkillError, N as ArchiveLimits, Ot as SkillsLockfile, Pt as UnsignedPolicy, S as UiBridge, St as SkillManifest, b as RenderResultRequest, c as InteractionResponse, jt as TrustedKeyStore, l as LlmClient, m as LlmStreamEvent, o as InteractionPolicy, p as LlmResponse, q as FileWriteStream, s as InteractionRequest, u as LlmCompleteInput, v as MemoryStore, vt as SkillInstallSource } from "./types-CpDRZ0rA-BM5FI9oN.js";
+import { $ as ImageOmission, B as ExternalToolSource, C as BridgeResponse, N as DocumentSurfaceHost, Pn as ToolResult, S as BridgeRequest, Sr as bridgeError, Yr as parseBridgeRequest, b as BridgeCapabilities, ct as LinkedDocumentReader, en as ScriptExecutionContext, jn as ToolDefinition, m as ApprovalScope, mr as WebSkillApi, sr as ViewerImageFact, tn as ScriptExecutor, ut as NetworkPolicy, z as ExternalSkillProvider } from "./index-YPd8ZSEa.js";
+import { In as PerceptionScopeInput, K as DocxDocumentContent, Ln as PptxDocumentContent, Lr as XlsxDocumentContent, Pn as PerceptionResult, Rn as PptxDocumentReader, Rr as XlsxDocumentReader, Tn as PdfDocumentReader, Ut as NestedFrameRef, cn as PageActionRequest, dn as PageActionTarget, in as PageActionOutcome, jn as PerceptionCaptureOptions, kn as PerceivedNode, mn as PageAuditSink, nn as PageActionExecutor, q as DocxDocumentReader, sr as SubtreeRejection, u as ConsentUi, un as PageActionScopeInput, xn as PagePerceptionReader, yn as PagePerceptionPolicy } from "./index-CjwdZQOS.js";
 //#region ../browser/dist/index.d.ts
 //#region src/fs/featureDetection.d.ts
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -506,6 +506,160 @@ interface CompressResult {
  */
 declare function compressImageToBudget(file: Blob, maxBytes: number): Promise<CompressResult>;
 //#endregion
+//#region src/dom/imageCapture.d.ts
+/**
+ * 取像级别（0.6.0 FR-12.1）。裁决 D-3 已取消 L3 栅格化，只剩两级。
+ * @experimental
+ */
+type CaptureLevel = 'src' | 'canvas';
+/** @experimental */
+interface CapturedImage {
+  id: string;
+  mimeType: string;
+  /** base64，不含 `data:` 前缀 */
+  data: string;
+  level: CaptureLevel;
+  originalBytes: number;
+  /** 压缩后字节数；未压缩时与 `originalBytes` 相同 */
+  bytes: number;
+}
+/** @experimental */
+interface CaptureFailure {
+  id: string;
+  /** 必须说明是哪一级、为什么；只写 "image unavailable" 不足以让用户判断该怎么办 */
+  reason: string;
+  triedLevels: readonly CaptureLevel[];
+}
+/** @experimental */
+declare function isCaptureFailure<T extends object>(result: T | CaptureFailure): result is CaptureFailure;
+/** 只有这三种标签能取像；其余元素连取像入口都不进（FR-12.1，由 T-02-15 守门） @experimental */
+declare function isCapturableElement(element: Element): boolean;
+/**
+ * 投放与导出通道的目标集：`docx` 与 `pptxgenjs` 都不吃 WebP，
+ * 而 WebP 在现代网页上遍地都是。归一化放在写进 `src` 之前，
+ * 下游三处永远只见得到 PNG 与 JPEG（设计 12 §4.2）。
+ *
+ * 导出编码器判断「这张图嵌不嵌得进去」必须读同一份清单（0.22.0 FR-14.3）：
+ * 各写一遍就会出现「投放时归一成了 A，导出却认为 A 不受支持」。
+ * @experimental
+ */
+declare const DOCUMENT_IMAGE_MIME_TYPES: ReadonlySet<string>;
+/**
+ * 一张已归一化、可直接写进投放文档的图片（0.22.0 FR-11.6）。
+ * @experimental
+ */
+interface DocumentImage {
+  /** base64，不含 `data:` 前缀 */
+  data: string;
+  /** 一定是 `image/png` 或 `image/jpeg`——两个导出编码器的交集 */
+  mimeType: string;
+  width: number;
+  height: number;
+  bytes: number;
+}
+/**
+ * 把任意来源的图片字节归一成投放文档能显示、两个导出编码器都收得下的形态（0.22.0 FR-11.6）。
+ *
+ * 上传图、页面图、外链图在这里走的是**同一个函数**——AC-G1 要的不是三条分支行为一致，
+ * 而是根本只有一条分支，所以这个签名里没有「来源」这个参数。
+ *
+ * 宽高一律实测：像素数是投放载荷预算的硬兜底维度（FR-10.7），采信声明等于让被限制方自报限额。
+ * 失败抛错并带可执行的原因，由调用方转成丢图归因（FR-11.8）。
+ * @experimental
+ */
+declare function toDocumentImage(bytes: Uint8Array, options: {
+  maxBytes: number;
+  declaredMimeType?: string;
+}): Promise<DocumentImage>;
+/**
+ * 取一个元素的图像（0.6.0 FR-12.1）。
+ *
+ * 按元素类型分派，不做无意义的尝试：`<img>` 只走 L1，`<canvas>` / `<svg>` 只走 L2，
+ * 两者互不兜底。失败返回 `CaptureFailure` 而不是抛错——一张图抓不到不该让整次感知失败。
+ * @experimental
+ */ declare function captureElementImage(element: Element, options: {
+  id: string;
+  maxBytes: number;
+}): Promise<CapturedImage | CaptureFailure>;
+/**
+ * 取一张宿主页面上的图，并归一成投放 / 导出通道吃得下的形态（0.22.0 FR-12.1）。
+ *
+ * 取像本身**原样复用** `captureElementImage`：两级策略与「互不兜底」的裁决 D-3 一字未改。
+ * 这里只把归一化的目标集换成 `png` / `jpeg`——产物一旦落盘就该是下游直接能用的格式，
+ * 否则「投放看得见、导出才消失」会以另一种形态回来。
+ * @experimental
+ */
+declare function captureDocumentImage(element: Element, options: {
+  id: string;
+  maxBytes: number;
+}): Promise<DocumentImage | CaptureFailure>;
+//#endregion
+//#region src/net/fetchImage.d.ts
+/**
+ * 抓取失败的分类（0.22.0 分册 13 FR-13.4）。
+ *
+ * 分类存在的理由只有一个：`failed to fetch` 让模型无从判断该换一个 URL、该重试、
+ * 还是该放弃。每一档对应一个**不同的下一步**。
+ * @experimental
+ */
+type RemoteFetchFailure = 'blocked' | 'unreachable' | 'refused' | 'not-an-image' | 'too-large' | 'timeout';
+/** 单次抓取超时（设计 14 §5.1）。一个不响应的 URL 不得把整个 run 拖死 @experimental */
+declare const REMOTE_IMAGE_TIMEOUT_MS = 15000;
+/** 单张外链图的原始字节上界（设计 14 §5.1）。超限先压，压不下去才丢 @experimental */
+declare const MAX_REMOTE_IMAGE_BYTES: number;
+/** @experimental */
+interface RemoteImageFailure {
+  kind: RemoteFetchFailure;
+  /** 英文、可执行：说清是哪一类失败、以及下一步能做什么 */
+  reason: string;
+}
+/** @experimental */
+interface FetchRemoteImageOptions {
+  /** 归一化后的字节上界，与页面图共用同一个预算 */
+  maxBytes: number;
+  /** 原始响应体的上界；缺省 `MAX_REMOTE_IMAGE_BYTES` */
+  maxSourceBytes?: number;
+  timeoutMs?: number;
+  /** 仅供测试注入；缺省用全局 `fetch` */
+  fetch?: typeof globalThis.fetch;
+}
+/**
+ * 把一次抓取失败归档（AC-13.4）。
+ *
+ * 纯函数：实测表明扩展上 `http` 全通（设计 14 §1），「被浏览器阻断」在 e2e 里
+ * 根本构造不出来，所以这一档的正确性只能由单测按真实错误形态喂进来验。
+ * @experimental
+ */
+declare function classifyFetchFailure(error: unknown, response?: Response): RemoteFetchFailure;
+/**
+ * 抓一张外链图并归一成可直接写进文档的形态（分册 13 FR-13.1 ~ FR-13.5）。
+ *
+ * **授权不在这里**：调用方必须在调用之前拿到用户同意（AC-13.5 要求断言网络层零请求，
+ * 所以判定必须发生在 `fetch` 之前，不能靠拿到响应再丢弃）。
+ *
+ * SSRF 由 `assertRemoteUrlAllowed` 原样兜住，不另写一份（FR-13.5）。已知口子：
+ * 它校验的是**初始 URL**，跟随重定向落到私有网段它管不着（见 docs/deferred-items.md）。
+ * @experimental
+ */
+declare function fetchRemoteImage(url: string, options: FetchRemoteImageOptions): Promise<DocumentImage | RemoteImageFailure>;
+/** @experimental */
+declare function isRemoteImageFailure(result: DocumentImage | RemoteImageFailure): result is RemoteImageFailure;
+/**
+ * 宿主侧的外链抓取出口（与 `PageImageHost` 对称）。
+ *
+ * 注入与否就是「这个宿主抓不抓得到跨域字节」这个事实本身：
+ * 扩展的侧栏页能抓（实测，设计 14 §1），普通网页受同源策略抓不到，
+ * 于是在后者上工具压根不注册，而不是注册了每次都失败。
+ * @experimental
+ */
+interface RemoteImageHost {
+  fetch(url: string, maxBytes: number): Promise<DocumentImage | RemoteImageFailure>;
+}
+/** @experimental */
+declare function createRemoteImageHost(options?: {
+  fetch?: typeof globalThis.fetch;
+}): RemoteImageHost;
+//#endregion
 //#region src/dom/promotion.d.ts
 /**
  * 非标可交互元素的识别与角色提升（0.14.0 分册 15）。
@@ -525,9 +679,10 @@ interface RoleHint {
 /**
  * 句柄的用途（分册 14 §6.1）。`anchor` 只能做 `perceive_page` 的子树根，
  * 拿去 `act_on_page` 一律被拒——否则放宽读的范围会顺带放宽写的范围。
+ * `image`（0.22.0 FR-12.1）同理：它只能交给 `capture_page_image`。
  * @experimental
  */
-type HandleKind = 'action' | 'anchor';
+type HandleKind = 'action' | 'anchor' | 'image';
 interface DomPerceptionReaderOptions {
   /** 选择器求值的根；缺省 `globalThis.document` */
   document?: Document;
@@ -653,6 +808,17 @@ type PageAgentRequest = {
 } | {
   type: 'execute';
   request: PageActionRequest;
+} |
+/**
+ * 取一张页面上的图（0.22.0 分册 12）。与 `execute` 同样按 ref 投回原帧。
+ *
+ * 与 `perceive` 的 `capture` 是**两条流**：那条取了图是为了让模型看懂（会走视觉委派），
+ * 这条取了图是为了落产物、进文档。两者不得互相触发（需求总览 §4 第 2 条）。
+ */
+{
+  type: 'capture-image';
+  ref: string;
+  maxBytes: number;
 };
 /**
  * 应答。失败走 `error` 变体而**不是**让 `send()` reject：
@@ -672,6 +838,15 @@ type PageAgentReply = {
 } | {
   type: 'execute-result';
   outcome: PageActionOutcome;
+} |
+/**
+ * 取像结果。失败走 `result` 里的 `CaptureFailure` 而不是 `error` 变体：
+ * 「这张图取不到」是页面的事实，不是协议故障，而且 `triedLevels` 得原样带回去（FR-12.4）。
+ * 图片字节走 base64 字符串，**不是** `number[]`（AC-11.10）。
+ */
+{
+  type: 'capture-image-result';
+  result: DocumentImage | CaptureFailure;
 } | {
   type: 'error';
   code: string;
@@ -859,6 +1034,33 @@ interface RemotePageActionExecutorOptions {
  */
 declare function createRemotePageActionExecutor(options: RemotePageActionExecutorOptions): PageActionExecutor;
 //#endregion
+//#region src/remote/pageImage.d.ts
+/**
+ * 宿主页面取像端口（0.22.0 分册 12 FR-12.1）。
+ *
+ * 只有一个方法，且**不含授权**：授权卡、会话记忆、产物落盘都在引擎那一侧。
+ * 宿主交出来的就是「把这个句柄指的那张图变成字节」这一件事。
+ * @experimental
+ */
+interface PageImageHost {
+  capture(ref: string, maxBytes: number): Promise<DocumentImage | CaptureFailure>;
+}
+/** @experimental */
+interface RemotePageImageHostOptions {
+  transport: PageAgentTransport;
+  /** 单次取像超时毫秒；缺省 10000 */
+  timeoutMs?: number;
+}
+/**
+ * 跨上下文的取像端口（分册 12 §2）。
+ *
+ * 与 `createRemotePageActionExecutor` 同一条装配规矩：句柄表在页面那一侧，
+ * 这边只负责把一次请求送过去。**不与感知期的取像共用任何状态**——
+ * 那条流是为了让模型看懂，这条流是为了落产物，两者不得互相触发。
+ * @experimental
+ */
+declare function createRemotePageImageHost(options: RemotePageImageHostOptions): PageImageHost;
+//#endregion
 //#region src/remote/handler.d.ts
 /** @experimental */
 interface PageAgentHandlerOptions {
@@ -978,6 +1180,10 @@ interface FrameRouter {
   execute(request: PageAgentRequest & {
     type: 'execute';
   }): Promise<PageAgentReply>;
+  /** 取像（0.22.0 分册 12）：与 `execute` 同一条寻址规矩，句柄发自哪一帧就投回哪一帧 */
+  captureImage(request: PageAgentRequest & {
+    type: 'capture-image';
+  }): Promise<PageAgentReply>;
 }
 /**
  * 逐帧下钻并汇总（分册 16 FR-16.2 / FR-16.3 / FR-16.4，分册 11 FR-11.2）。
@@ -989,45 +1195,6 @@ interface FrameRouter {
  */
 declare function createFrameRouter<A>(options: FrameRouterOptions<A>): FrameRouter;
 //#endregion
-//#region src/dom/imageCapture.d.ts
-/**
- * 取像级别（0.6.0 FR-12.1）。裁决 D-3 已取消 L3 栅格化，只剩两级。
- * @experimental
- */
-type CaptureLevel = 'src' | 'canvas';
-/** @experimental */
-interface CapturedImage {
-  id: string;
-  mimeType: string;
-  /** base64，不含 `data:` 前缀 */
-  data: string;
-  level: CaptureLevel;
-  originalBytes: number;
-  /** 压缩后字节数；未压缩时与 `originalBytes` 相同 */
-  bytes: number;
-}
-/** @experimental */
-interface CaptureFailure {
-  id: string;
-  /** 必须说明是哪一级、为什么；只写 "image unavailable" 不足以让用户判断该怎么办 */
-  reason: string;
-  triedLevels: readonly CaptureLevel[];
-}
-/** @experimental */
-declare function isCaptureFailure(result: CapturedImage | CaptureFailure): result is CaptureFailure;
-/** 只有这三种标签能取像；其余元素连取像入口都不进（FR-12.1，由 T-02-15 守门） @experimental */
-declare function isCapturableElement(element: Element): boolean;
-/**
- * 取一个元素的图像（0.6.0 FR-12.1）。
- *
- * 按元素类型分派，不做无意义的尝试：`<img>` 只走 L1，`<canvas>` / `<svg>` 只走 L2，
- * 两者互不兜底。失败返回 `CaptureFailure` 而不是抛错——一张图抓不到不该让整次感知失败。
- * @experimental
- */ declare function captureElementImage(element: Element, options: {
-  id: string;
-  maxBytes: number;
-}): Promise<CapturedImage | CaptureFailure>;
-//#endregion
 //#region src/host/protocol.d.ts
 /** 主线程 → Worker 的 LLM 配置；mockResponses 供 E2E/测试注入确定性 Mock */
 interface LlmClientConfig {
@@ -1471,7 +1638,177 @@ declare function createXlsxBlockReader(): XlsxDocumentReader;
  */
 declare function readXlsxBlocks(bytes: Uint8Array): Promise<XlsxDocumentContent>;
 //#endregion
+//#region src/document/pptxBlocks.d.ts
+/** @experimental */
+declare function createPptxBlockReader(): PptxDocumentReader;
+/**
+ * @throws WebSkillError 归档损坏、缺 `ppt/presentation.xml`、XML 解析失败
+ * @experimental
+ */
+declare function readPptxBlocks(bytes: Uint8Array): Promise<PptxDocumentContent>;
+//#endregion
+//#region src/document/pptx.d.ts
+/**
+ * pptx 正文抽取（0.22.0 分册 18）。
+ *
+ * 与 `readPptxBlocks` 同源：文本形态只是把逐页的文本块按放映顺序拼起来，
+ * 两条路给出的文字因此**永远一致**——同一份文稿不会因为走哪条路而多出或少掉一段。
+ *
+ * ⚠️ 与 docx/xlsx 一样依赖 `DOMParser`，所以只在 `@webskill/browser`。
+ */
+/**
+ * **不抽取**的内容，逐条写明而不是笼统说「尽力而为」：
+ * 版式、动画、切换效果、母版与版式上的模板文字、图表的底层数据。
+ *
+ * 插图不在此列但也不在文本里：图要按页取，走 `read_document`。
+ */
+declare const PPTX_UNEXTRACTED: readonly ["layout and positioning", "animations and transitions", "master and layout placeholders", "chart source data", "pictures"];
+/** 抽不出任何文字时的占位，与 docx/xlsx 同款口径 @experimental */
+declare const PPTX_UNEXTRACTED_NOTICE: string;
+/**
+ * @throws WebSkillError 归档损坏、缺 `ppt/presentation.xml`、XML 解析失败
+ * @experimental
+ */
+declare function extractPptxText(bytes: Uint8Array): Promise<string>;
+//#endregion
+//#region src/document/xlsxTemplate.d.ts
+interface XlsxTemplateSheet {
+  readonly name: string;
+  /** dimension，如 `A1:H19` */
+  readonly range: string;
+  /** `formula` 在时这格由模板算出，不得填（FR-42.28）；共享公式已按本格行号展开 */
+  readonly cells: ReadonlyArray<{
+    readonly address: string;
+    readonly text: string;
+    readonly formula?: string;
+  }>;
+  readonly merges: readonly string[];
+  readonly columnWidths: readonly number[];
+}
+interface XlsxTemplateSkeleton {
+  readonly sheets: readonly XlsxTemplateSheet[];
+}
+interface XlsxCellFill {
+  readonly sheet?: string;
+  readonly address: string;
+  readonly value: string;
+}
+interface XlsxRowInsert {
+  readonly sheet?: string;
+  /** 1 基：新行从这一行开始插 */
+  readonly at: number;
+  readonly count: number;
+  /** 1 基：照抄哪一行的样式与行高。默认用 `at - 1` */
+  readonly copyStyleFrom?: number;
+}
+interface XlsxImagePlacement {
+  readonly sheet?: string;
+  /** 落点单元格；若它是某个合并区的左上角，图按整个合并区缩放 */
+  readonly address: string;
+  readonly bytes: Uint8Array;
+  /** `png` / `jpeg` */
+  readonly extension: string;
+  readonly contentType: string;
+}
+interface XlsxTemplateSpec {
+  readonly rows?: readonly XlsxRowInsert[];
+  readonly cells?: readonly XlsxCellFill[];
+  readonly images?: readonly XlsxImagePlacement[];
+}
+/** 读带坐标的骨架（FR-42.1）。模型据此决定往哪儿写。 */
+declare function readXlsxTemplate(bytes: Uint8Array): Promise<XlsxTemplateSkeleton>;
+/**
+ * 照模板出新文件。
+ *
+ * 顺序是**先插行、后填值**：填值用的地址是插行之后的坐标，反过来会逼模型心算偏移。
+ *
+ * @throws WebSkillError 模板不是 xlsx、地址不合法、目标不存在、插行越界
+ */
+declare function fillXlsxTemplate(bytes: Uint8Array, spec: XlsxTemplateSpec): Promise<Uint8Array>;
+//#endregion
+//#region src/document/docxTemplate.d.ts
+interface DocxTemplateParagraph {
+  /** 0 基，正文段落序号（表格内的段落不计入） */
+  readonly index: number;
+  readonly text: string;
+}
+interface DocxTemplateCell {
+  readonly table: number;
+  readonly row: number;
+  readonly column: number;
+  readonly text: string;
+  readonly gridSpan?: number;
+  readonly vMerge?: string;
+}
+interface DocxTemplateSkeleton {
+  readonly paragraphs: readonly DocxTemplateParagraph[];
+  readonly cells: readonly DocxTemplateCell[];
+}
+interface DocxTextFill {
+  readonly paragraph?: number;
+  readonly table?: number;
+  readonly row?: number;
+  readonly column?: number;
+  readonly value: string;
+}
+interface DocxImagePlacement {
+  readonly paragraph?: number;
+  readonly table?: number;
+  readonly row?: number;
+  readonly column?: number;
+  readonly bytes: Uint8Array;
+  readonly extension: string;
+  readonly contentType: string;
+}
+interface DocxTemplateSpec {
+  readonly texts?: readonly DocxTextFill[];
+  readonly images?: readonly DocxImagePlacement[];
+}
+/** 读带坐标的骨架（FR-42.1） */
+declare function readDocxTemplate(bytes: Uint8Array): Promise<DocxTemplateSkeleton>;
+/**
+ * 照模板出新文件。
+ *
+ * @throws WebSkillError 模板不是 docx、坐标指到不存在的表 / 行 / 列 / 段落、图片认不出来
+ */
+declare function fillDocxTemplate(bytes: Uint8Array, spec: DocxTemplateSpec): Promise<Uint8Array>;
+//#endregion
+//#region src/document/ooxmlPart.d.ts
+/** 解开后的包：部件名 → 字节。顺序即写回顺序。 */
+type OoxmlPackage = Map<string, Uint8Array>;
+/** @throws WebSkillError 归档损坏，或不是 OOXML（缺 `[Content_Types].xml`） */
+declare function readOoxmlPackage(bytes: Uint8Array): Promise<OoxmlPackage>;
+declare function writeOoxmlPackage(pkg: OoxmlPackage): Uint8Array;
+/**
+ * 结构自检（AC-42.27）。
+ *
+ * 「打开不提示修复」没法进 CI（本仓没有可脚本化的 Office 实现，见设计 10 §6.2），
+ * 但迄今实测出的坏文件成因都是结构性的：悬空关系、没登记的扩展名、解析不了的部件。
+ * 这三条能当场查出来，所以每次重封之前都查一遍。
+ *
+ * @returns 英文问题描述，空数组表示干净
+ */
+declare function auditOoxmlPackage(pkg: OoxmlPackage): string[];
+//#endregion
 //#region src/viewer/viewerCsp.d.ts
+/**
+ * 投放面图片来源的单一事实源（0.22.0 分册 13 FR-13.9）。
+ *
+ * **不含宿主自身**：两套宿主写法不同——站点写自己的 origin（opaque origin 下 `'self'` 匹配不上），
+ * 扩展的 sandbox 页写 `'self'`。能收敛的是**除宿主之外**放行了哪些来源，
+ * 而那恰恰是会漂走的部分（扩展的 sandbox CSP 此前整条 `img-src` 都不存在，等于全放）。
+ * @experimental
+ */
+declare const VIEWER_IMG_SRC_BASE: readonly string[];
+/**
+ * 降级形态（外链图，FR-13.6）额外需要的来源。
+ *
+ * ⚠️ 加它进来的代价见 `ViewerCspOptions.imgSrc`：投放面因此多了一条外发信道。
+ * `http:` 也在其中，因为需求裁决了「`http` 尽力而为」（分册 13 §2.2）——
+ * 抓得到就嵌字节，抓不到才落到这条外链上，此时拦掉它只会让图变成一个破图标。
+ * @experimental
+ */
+declare const VIEWER_IMG_SRC_REMOTE: readonly string[];
 /** 宿主可配置的白名单方向；技能声明不了这些（FR-18.3 第 3 条） */
 interface ViewerCspOptions {
   /**
@@ -1486,7 +1823,15 @@ interface ViewerCspOptions {
   hostOrigin: string;
   /** 文档可外发的目标；缺省 `'none'` —— 数据经 postMessage 下发，不需要外连 */
   connectSrc?: readonly string[];
-  /** 图片来源；缺省宿主自身 + `data:`（内联图不走网络） */
+  /**
+   * 图片来源；缺省宿主自身 + `data:`（内联图不走网络）。
+   *
+   * ⚠️ **放行外链图等于给投放面开了一条外发信道**：图片 URL 的路径与 query
+   * 能携带文档内容，`connect-src` 至今守着的那条线（0.11.0 AC-18.5）会因此被绕开一半。
+   * 因此它不是 SDK 的默认值，只能由宿主显式给出（0.22.0 FR-13.10 / FR-13.11）。
+   * 需要它的场景只有一个：宁主拓不到字节时，图以外链形态进文档（FR-13.6）。
+   * 放宽时用 `VIEWER_IMG_SRC_REMOTE`，不要自己拼一份。
+   */
   imgSrc?: readonly string[];
   /** 字体来源；缺省只有宿主自身，外链公文字体需宿主显式放行（FR-20.5） */
   fontSrc?: readonly string[];
@@ -1553,7 +1898,32 @@ interface OpenDocumentInput {
   /** 数据来源描述，进告知与审计 */
   dataSource: string;
   document: ViewerDocument;
-}
+  /**
+   * 已填进 `document.html` 的图片事实（0.22.0 FR-10.7）。
+   *
+   * 像素维度只能靠它：`document` 里图片是 base64 的压缩字节，
+   * 从载荷本身看不出解码后会占多少位图内存。
+   */
+  images?: readonly ViewerImageFact[];
+  /**
+   * 解析阶段丢掉的图片（0.22.0 FR-11.8）。
+   *
+   * 进审计而**不**参与预算核算：它们一个字节也没进载荷。留痕的意义在于
+   * 事后能回答「这份文档为什么缺了一张图」——那是本版要消灭的静默失败。
+   */
+  omissions?: readonly ImageOmission[];
+}
+/** 超软阈值时随确认一并交给宿主的事实；措辞由宿主写（FR-10.4） */
+interface PayloadSizeNotice {
+  /** 载荷的 UTF-16 code unit 数 */
+  units: number;
+  /** 图片解码后的总像素数 */
+  pixels: number;
+  /** 是哪一维进了软区间 */
+  trigger: PayloadDimension;
+}
+/** 载荷预算的两个维度（0.22.0 FR-10.7） */
+type PayloadDimension = 'bytes' | 'pixels' | 'both';
 interface DocumentSurfaceOptions {
   /** 宿主的 viewer 路由地址（必须能下发 CSP 响应头，见 viewerCsp.ts） */
   viewerUrl: string;
@@ -1561,10 +1931,23 @@ interface DocumentSurfaceOptions {
   confirm(input: {
     skillName: string;
     dataSource: string;
+    sizeNotice?: PayloadSizeNotice;
   }): Promise<boolean>;
   audit?: DocumentSurfaceAudit;
-  /** 投递载荷上限；超限拒绝而不是静默截断（AC-18.11） */
+  /**
+   * 载荷硬兜底；超限拒绝而不是静默截断（AC-18.11）。
+   *
+   * 名字里的 `Bytes` 是历史口径：实际比较的是 UTF-16 code unit 数（`PayloadCost.units`）。
+   * 逼近阈值的载荷必然是图片主导的，而 base64 是纯 ASCII，两者 1:1；
+   * CJK 文本会被低估约 3 倍，但要达到硬兜底得有上亿个汉字。
+   */
   maxPayloadBytes?: number;
+  /** 载荷软阈值；超过它照常打开，只是给 `confirm` 带一条 `sizeNotice`（FR-10.4/10.5） */
+  softPayloadBytes?: number;
+  /** 图片总像素硬兜底（FR-10.7） */
+  maxPayloadPixels?: number;
+  /** 图片总像素软阈值（FR-10.7） */
+  softPayloadPixels?: number;
   /** 握手超时；viewer 起不来时不能无限等 */
   handshakeTimeoutMs?: number;
   /** 仅供测试注入；缺省用 `window.open` */
@@ -1576,7 +1959,20 @@ interface WindowLike {
   close(): void;
   postMessage(message: unknown, targetOrigin: string): void;
 }
-declare const DEFAULT_MAX_VIEWER_PAYLOAD_BYTES = 2000000;
+/**
+ * 载荷硬兜底（0.22.0 FR-10.1）。
+ *
+ * 从 0.11.0 的 2 MB 提到这里，是因为那个值从未被论证过，而实测表明它离任何真实边界都很远：
+ * 128 MB 的结构化克隆只要 23 ms，V8 的字符串上限在 512 MB 左右才会抛 `RangeError`。
+ * 留 4 倍余量是给同一个标签页里的 React、图表库与对话历史用的。
+ */
+declare const DEFAULT_MAX_VIEWER_PAYLOAD_BYTES = 128000000;
+/** 载荷软阈值：到这里不是「慢」，而是「这份文档异常大」，值得先告诉用户一声 */
+declare const DEFAULT_SOFT_VIEWER_PAYLOAD_BYTES = 32000000;
+/** 像素硬兜底，约合 1 GB 位图；实测 60 张 4000×3000 达 2.7 GB，那是崩标签页的量级 */
+declare const DEFAULT_MAX_VIEWER_PAYLOAD_PIXELS = 256000000;
+/** 像素软阈值，约合 256 MB 位图；实测 60 M 像素仍然流畅 */
+declare const DEFAULT_SOFT_VIEWER_PAYLOAD_PIXELS = 64000000;
 /** 审计事件类型（与既有事件同一条链） */
 declare const DOCUMENT_SURFACE_AUDIT_EVENT = "document.surface.open";
 /**
@@ -2307,4 +2703,4 @@ interface WebOfficeToolSourceOptions {
  */
 declare function createWebOfficeToolSource(options: WebOfficeToolSourceOptions): ExternalToolSource;
 //#endregion
-export { type BlockedEventLike, type BridgeCapabilities, type BridgeRequest, type BridgeResponse, type BrowserHostBundle, type BrowserHostOptions, type BrowserHostOverrides, BrowserSkillManager, BrowserWorkerScriptExecutor, type BuiltinSkillManifest, type CameraAvailability, type CameraOptions, type CameraSession, type CaptureFailure, type CaptureLevel, type CapturePhotoOptions, type CapturedImage, type ChromeBuiltinAvailability, ChromeBuiltinLlmClient, type CompressResult, type ConfiguredLlmClient, DEFAULT_CAMERA_MAX_DIMENSION, DEFAULT_FRAME_BUDGET, DEFAULT_MAX_VIEWER_PAYLOAD_BYTES, DOCUMENT_SURFACE_AUDIT_EVENT, DOCX_IMAGE_WIDTH_RATIO, DOCX_UNEXTRACTED, type DictationAvailability, type DictationOptions, type DictationSession, type DocumentBlock, type DocumentLocationView, type DocumentSurfaceAudit, type DocumentSurfaceOptions, type DomPageActionExecutor, type DomPageActionOptions, type DomPerceptionReader, type DomPerceptionReaderOptions, type FetchLinkedDocumentOptions, type FrameBudget, type FrameDelivery, type FrameDispatcher, type FrameResolveContext, type FrameRouter, type FrameRouterOptions, HOST_PORT_MATRIX, type HandleKind, type HostChatbotAdapterShape, type HostConnectFacadeShape, type HostConsoleBackendShape, type HostKind, type HostSurface, type IframeSandboxOptions, IframeWorkerLike, type InspectHostWiringInput, LIST_WEBOFFICE_DOCUMENTS_TOOL, type LlmClientConfig, type LlmEntryConfig, type MainToWorkerMessage, type OpenDocumentInput, OpfsProvider, type PageAgentHandler, type PageAgentHandlerOptions, type PageAgentReply, type PageAgentRequest, type PageAgentTargetEntry, type PageAgentTransport, type PageDocumentIdentity, type PdfPage, type PortApplicability, type PortReport, type PortSpec, type PortStatus, type PresentationSlide, type PresentationSourceDocument, type PresentationSourceReader, type PresentationSourceSlide, READ_WEBOFFICE_DOCUMENT_TOOL, type RemotePageActionExecutorOptions, type RemotePerceptionReaderOptions, type RemoteTargetRegistry, type RemoteTargetRegistryOptions, type RoleHint, SANDBOX_PAGE_SCRIPT_SOURCE, SHARD_SOFT_LIMIT, type SandboxMode, type SandboxTokenDiff, type SeedSkillsFromHttpOptions, type SerializedError, type TargetResolution, TsTranspiler, type TypeScriptSupportOptions, VIEWER_SANDBOX_TOKENS, type ViewerBlockedHost, type ViewerBlockedNotice, type ViewerBlockedResult, type ViewerCspOptions, type ViewerDocument, type ViewerShellHost, type ViewerShellMount, type ViewerShellResult, type VisionCaptureOptions, WEBOFFICE_BUDGET, WEBOFFICE_UNEXTRACTED, WEB_OFFICE_OFFICE_TYPES, WEB_OFFICE_READ_METHODS, WEB_OFFICE_SUPPORTED_TYPES, WORKER_BOOTSTRAP_SOURCE, type WebOfficeAction, type WebOfficeApiSurface, type WebOfficeAuditRecord, type WebOfficeAuthorizationInput, type WebOfficeAuthorizationKey, type WebOfficeAuthorizationOutcome, type WebOfficeBudget, WebOfficeBudgetGuard, type WebOfficeChannel, type WebOfficeConsent, type WebOfficeContent, type WebOfficeDisplayHints, type WebOfficeExtractOptions, type WebOfficeFailure, type WebOfficeFingerprintResult, type WebOfficeHost, type WebOfficeInstanceRecord, type WebOfficeListing, WebOfficePolicy, type WebOfficePolicyOptions, type WebOfficeReadCursor, type WebOfficeReadOptions, type WebOfficeReadPort, type WebOfficeReadResult, type WebOfficeScrollPosition, type WebOfficeSupportedType, type WebOfficeToolSourceOptions, type WebOfficeVisionPort, type WindowLike, type WorkbookSheet, type WorkerEvent, type WorkerFactory, type WorkerLike, type WorkerRequest, WorkerRuntimeClient, type WorkerRuntimeClientDeps, type WorkerRuntimeHostOverrides, type WorkerScopeLike, WorkerUiBridge, XLSX_IMAGE_MIN_COLUMNS, XLSX_IMAGE_MIN_ROWS, XLSX_UNEXTRACTED, assertWebOfficeFingerprint, blockedMessage, bridgeError, callWebOfficeMethod, captureByScrolling, captureElementImage, capturePhoto, checkCameraAvailability, checkDictationAvailability, checkWebOfficeFingerprint, compressImageToBudget, contentKindOf, createBrowserChatbotHost, createDocumentSurfaceHost, createDocxBlockReader, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createFetchLinkedDocumentReader, createFrameRouter, createIframeWorker, createLlmClient, createPageAgentHandler, createRemotePageActionExecutor, createRemotePerceptionReader, createRemoteTargetRegistry, createWebOfficeHandle, createWebOfficeToolSource, createXlsxBlockReader, deleteMemoryEncryptionKey, describeScreenshotOverlap, diffSandboxTokens, documentKey, explainResolution, extractDocxText, extractWebOfficeContent, extractXlsxText, extractZipWeb, generateMemoryEncryptionKey, headingLevelOf, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, isWebOfficeReadMethod, missingPorts, openCamera, openDocumentSurface, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, readDocxBlocks, readXlsxBlocks, resolveWebOfficeAuthorization, seedSkillsFromHttp, sha256HexWeb, startDictation, startViewerShell, startWorkerRuntimeHost, viewerCspHeader, watchBlockedResources, webOfficeFailure };
+export { type BlockedEventLike, type BridgeCapabilities, type BridgeRequest, type BridgeResponse, type BrowserHostBundle, type BrowserHostOptions, type BrowserHostOverrides, BrowserSkillManager, BrowserWorkerScriptExecutor, type BuiltinSkillManifest, type CameraAvailability, type CameraOptions, type CameraSession, type CaptureFailure, type CaptureLevel, type CapturePhotoOptions, type CapturedImage, type ChromeBuiltinAvailability, ChromeBuiltinLlmClient, type CompressResult, type ConfiguredLlmClient, DEFAULT_CAMERA_MAX_DIMENSION, DEFAULT_FRAME_BUDGET, DEFAULT_MAX_VIEWER_PAYLOAD_BYTES, DEFAULT_MAX_VIEWER_PAYLOAD_PIXELS, DEFAULT_SOFT_VIEWER_PAYLOAD_BYTES, DEFAULT_SOFT_VIEWER_PAYLOAD_PIXELS, DOCUMENT_IMAGE_MIME_TYPES, DOCUMENT_SURFACE_AUDIT_EVENT, DOCX_IMAGE_WIDTH_RATIO, DOCX_UNEXTRACTED, type DictationAvailability, type DictationOptions, type DictationSession, type DocumentBlock, type DocumentImage, type DocumentLocationView, type DocumentSurfaceAudit, type DocumentSurfaceOptions, type DocxImagePlacement, type DocxTemplateCell, type DocxTemplateParagraph, type DocxTemplateSkeleton, type DocxTemplateSpec, type DocxTextFill, type DomPageActionExecutor, type DomPageActionOptions, type DomPerceptionReader, type DomPerceptionReaderOptions, type FetchLinkedDocumentOptions, type FetchRemoteImageOptions, type FrameBudget, type FrameDelivery, type FrameDispatcher, type FrameResolveContext, type FrameRouter, type FrameRouterOptions, HOST_PORT_MATRIX, type HandleKind, type HostChatbotAdapterShape, type HostConnectFacadeShape, type HostConsoleBackendShape, type HostKind, type HostSurface, type IframeSandboxOptions, IframeWorkerLike, type InspectHostWiringInput, LIST_WEBOFFICE_DOCUMENTS_TOOL, type LlmClientConfig, type LlmEntryConfig, MAX_REMOTE_IMAGE_BYTES, type MainToWorkerMessage, type OoxmlPackage, type OpenDocumentInput, OpfsProvider, PPTX_UNEXTRACTED, PPTX_UNEXTRACTED_NOTICE, type PageAgentHandler, type PageAgentHandlerOptions, type PageAgentReply, type PageAgentRequest, type PageAgentTargetEntry, type PageAgentTransport, type PageDocumentIdentity, type PageImageHost, type PayloadDimension, type PayloadSizeNotice, type PdfPage, type PortApplicability, type PortReport, type PortSpec, type PortStatus, type PresentationSlide, type PresentationSourceDocument, type PresentationSourceReader, type PresentationSourceSlide, READ_WEBOFFICE_DOCUMENT_TOOL, REMOTE_IMAGE_TIMEOUT_MS, type RemoteFetchFailure, type RemoteImageFailure, type RemoteImageHost, type RemotePageActionExecutorOptions, type RemotePageImageHostOptions, type RemotePerceptionReaderOptions, type RemoteTargetRegistry, type RemoteTargetRegistryOptions, type RoleHint, SANDBOX_PAGE_SCRIPT_SOURCE, SHARD_SOFT_LIMIT, type SandboxMode, type SandboxTokenDiff, type SeedSkillsFromHttpOptions, type SerializedError, type TargetResolution, TsTranspiler, type TypeScriptSupportOptions, VIEWER_IMG_SRC_BASE, VIEWER_IMG_SRC_REMOTE, VIEWER_SANDBOX_TOKENS, type ViewerBlockedHost, type ViewerBlockedNotice, type ViewerBlockedResult, type ViewerCspOptions, type ViewerDocument, type ViewerShellHost, type ViewerShellMount, type ViewerShellResult, type VisionCaptureOptions, WEBOFFICE_BUDGET, WEBOFFICE_UNEXTRACTED, WEB_OFFICE_OFFICE_TYPES, WEB_OFFICE_READ_METHODS, WEB_OFFICE_SUPPORTED_TYPES, WORKER_BOOTSTRAP_SOURCE, type WebOfficeAction, type WebOfficeApiSurface, type WebOfficeAuditRecord, type WebOfficeAuthorizationInput, type WebOfficeAuthorizationKey, type WebOfficeAuthorizationOutcome, type WebOfficeBudget, WebOfficeBudgetGuard, type WebOfficeChannel, type WebOfficeConsent, type WebOfficeContent, type WebOfficeDisplayHints, type WebOfficeExtractOptions, type WebOfficeFailure, type WebOfficeFingerprintResult, type WebOfficeHost, type WebOfficeInstanceRecord, type WebOfficeListing, WebOfficePolicy, type WebOfficePolicyOptions, type WebOfficeReadCursor, type WebOfficeReadOptions, type WebOfficeReadPort, type WebOfficeReadResult, type WebOfficeScrollPosition, type WebOfficeSupportedType, type WebOfficeToolSourceOptions, type WebOfficeVisionPort, type WindowLike, type WorkbookSheet, type WorkerEvent, type WorkerFactory, type WorkerLike, type WorkerRequest, WorkerRuntimeClient, type WorkerRuntimeClientDeps, type WorkerRuntimeHostOverrides, type WorkerScopeLike, WorkerUiBridge, XLSX_IMAGE_MIN_COLUMNS, XLSX_IMAGE_MIN_ROWS, XLSX_UNEXTRACTED, type XlsxCellFill, type XlsxImagePlacement, type XlsxRowInsert, type XlsxTemplateSheet, type XlsxTemplateSkeleton, type XlsxTemplateSpec, assertWebOfficeFingerprint, auditOoxmlPackage, blockedMessage, bridgeError, callWebOfficeMethod, captureByScrolling, captureDocumentImage, captureElementImage, capturePhoto, checkCameraAvailability, checkDictationAvailability, checkWebOfficeFingerprint, classifyFetchFailure, compressImageToBudget, contentKindOf, createBrowserChatbotHost, createDocumentSurfaceHost, createDocxBlockReader, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createFetchLinkedDocumentReader, createFrameRouter, createIframeWorker, createLlmClient, createPageAgentHandler, createPptxBlockReader, createRemoteImageHost, createRemotePageActionExecutor, createRemotePageImageHost, createRemotePerceptionReader, createRemoteTargetRegistry, createWebOfficeHandle, createWebOfficeToolSource, createXlsxBlockReader, deleteMemoryEncryptionKey, describeScreenshotOverlap, diffSandboxTokens, documentKey, explainResolution, extractDocxText, extractPptxText, extractWebOfficeContent, extractXlsxText, extractZipWeb, fetchRemoteImage, fillDocxTemplate, fillXlsxTemplate, generateMemoryEncryptionKey, headingLevelOf, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, isRemoteImageFailure, isWebOfficeReadMethod, missingPorts, openCamera, openDocumentSurface, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, readDocxBlocks, readDocxTemplate, readOoxmlPackage, readPptxBlocks, readXlsxBlocks, readXlsxTemplate, resolveWebOfficeAuthorization, seedSkillsFromHttp, sha256HexWeb, startDictation, startViewerShell, startWorkerRuntimeHost, toDocumentImage, viewerCspHeader, watchBlockedResources, webOfficeFailure, writeOoxmlPackage };