@webskill/sdk 0.20.0 → 0.21.0

package/dist/browser.d.ts

@@ -1,6 +1,6 @@
-import { Ct as SkillsLockfile, Et as TrustedKeyStore, H as FileStat, Mt as WebSkillError, N as ArchiveLimits, S as UiBridge, U as FileSystemProvider, _t as SkillManifest, b as RenderResultRequest, c as InteractionResponse, jt as VerifyResult, kt as UnsignedPolicy, l as LlmClient, m as LlmStreamEvent, o as InteractionPolicy, p as LlmResponse, pt as SkillInstallSource, s as InteractionRequest, u as LlmCompleteInput, v as MemoryStore } from "./types-Btpdd1y--BcxQ10Fa.js";
-import { Kt as ScriptExecutionContext, M as DocumentSurfaceHost, R as ExternalSkillProvider, S as BridgeResponse, Un as WebSkillApi, Yn as bridgeError, ct as NetworkPolicy, gn as ToolDefinition, m as ApprovalScope, ot as LinkedDocumentReader, qt as ScriptExecutor, x as BridgeRequest, y as BridgeCapabilities, yn as ToolResult, yr as parseBridgeRequest, z as ExternalToolSource } from "./index-BDyXe-a5.js";
-import { $ as NestedFrameRef, Ct as PagePerceptionPolicy, It as PerceptionScopeInput, Pt as PerceptionResult, Tt as PagePerceptionReader, Xt as SubtreeRejection, ft as PageActionOutcome, gt as PageActionRequest, jt as PerceptionCaptureOptions, kt as PerceivedNode, ut as PageActionExecutor, vt as PageActionScopeInput, yt as PageActionTarget } from "./index-DQ3-6GFu.js";
+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";
 //#region ../browser/dist/index.d.ts
 //#region src/fs/featureDetection.d.ts
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -19,6 +19,12 @@ declare class OpfsProvider implements FileSystemProvider {
   appendText(p: string, content: string): Promise<void>;
   readBinary(p: string): Promise<Uint8Array>;
   writeBinary(p: string, content: Uint8Array): Promise<void>;
+  /**
+   * 分块写入（FR-18.2c）。`createWritable()` 本身就是写 swap 文件、`close()` 才提交，
+   * 所以未完成的内容不会被读到；但 `getFileHandle(create:true)` 会先落下一个空文件，
+   * 因此 abort 时要把“本次新建”的那个空壳删掉，不给后续读取留残件（FR-18.2e）。
+   */
+  createWriteStream(p: string): Promise<FileWriteStream>;
   exists(p: string): Promise<boolean>;
   stat(p: string): Promise<FileStat>;
   list(p: string): Promise<FileStat[]>;
@@ -1435,6 +1441,36 @@ declare const XLSX_UNEXTRACTED: readonly ["styles", "conditional formatting", "m
  */
 declare function extractXlsxText(bytes: Uint8Array): Promise<string>;
 //#endregion
+//#region src/document/docxBlocks.d.ts
+/** 图宽占正文宽度的门槛：低于它的是签名章、页眉 logo、装饰线（FR-22.9） @experimental */
+declare const DOCX_IMAGE_WIDTH_RATIO = 0.3;
+/** @experimental */
+declare function createDocxBlockReader(): DocxDocumentReader;
+/**
+ * @throws WebSkillError 归档损坏、缺 `word/document.xml`、XML 解析失败
+ * @experimental
+ */
+declare function readDocxBlocks(bytes: Uint8Array): Promise<DocxDocumentContent>;
+//#endregion
+//#region src/document/xlsxBlocks.d.ts
+/**
+ * xlsx → 行流 + 图（0.21.0 分册 22 · FR-22.10/22.11）。
+ *
+ * 图不是浮在表外的附件，它压着某几行几列——按锚点插回行流里，
+ * 模型才知道「这张图说的是上面那几行」。
+ */
+/** 值得单独烧一次多模态的图：至少跨 2 列、3 行（FR-22.11） @experimental */
+declare const XLSX_IMAGE_MIN_COLUMNS = 2;
+/** @experimental */
+declare const XLSX_IMAGE_MIN_ROWS = 3;
+/** @experimental */
+declare function createXlsxBlockReader(): XlsxDocumentReader;
+/**
+ * @throws WebSkillError 归档损坏、旧版 `.xls`、缺 `xl/workbook.xml`、工作表关系解不开、XML 解析失败
+ * @experimental
+ */
+declare function readXlsxBlocks(bytes: Uint8Array): Promise<XlsxDocumentContent>;
+//#endregion
 //#region src/viewer/viewerCsp.d.ts
 /** 宿主可配置的白名单方向；技能声明不了这些（FR-18.3 第 3 条） */
 interface ViewerCspOptions {
@@ -1464,6 +1500,20 @@ interface ViewerCspOptions {
 declare function viewerCspHeader(options: ViewerCspOptions): string;
 /** 本版固定的 sandbox token（供判据与装配文档引用，避免第二份清单） */
 declare const VIEWER_SANDBOX_TOKENS: readonly string[];
+/** `diffSandboxTokens` 的结果；两个方向分开报，守卫才说得出是哪一侧漂了 */
+interface SandboxTokenDiff {
+  /** SDK 要求、宿主没给的 token；非空即投放面拿不到它该有的能力 */
+  missingInHost: string[];
+  /** 宿主多给的 token；不是错，但必须有署名 */
+  extraInHost: string[];
+}
+/**
+ * 比对 SDK 的固定清单与宿主实际下发的清单（分册 15 AC-15.2）。
+ *
+ * 宿主可以是超集——扩展的 `view.html` 与站点的 viewer 不是同一个宿主，
+ * 但多出来的每一个 token 都得有人认领，否则清单就在悳悳中漂走。
+ */
+declare function diffSandboxTokens(sdk: readonly string[], host: readonly string[]): SandboxTokenDiff;
 //#endregion
 //#region src/viewer/documentSurface.d.ts
 /**
@@ -1622,4 +1672,639 @@ declare function watchBlockedResources(host: ViewerBlockedHost, notice: ViewerBl
 /** 提示文案的单一来源；判据直接引用，不各写一份字面量 */
 declare function blockedMessage(origins: readonly string[]): string;
 //#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_UNEXTRACTED, type DictationAvailability, type DictationOptions, type DictationSession, 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, type LlmClientConfig, type LlmEntryConfig, type MainToWorkerMessage, type OpenDocumentInput, OpfsProvider, type PageAgentHandler, type PageAgentHandlerOptions, type PageAgentReply, type PageAgentRequest, type PageAgentTargetEntry, type PageAgentTransport, type PageDocumentIdentity, type PortApplicability, type PortReport, type PortSpec, type PortStatus, type RemotePageActionExecutorOptions, type RemotePerceptionReaderOptions, type RemoteTargetRegistry, type RemoteTargetRegistryOptions, type RoleHint, SANDBOX_PAGE_SCRIPT_SOURCE, SHARD_SOFT_LIMIT, type SandboxMode, 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, WORKER_BOOTSTRAP_SOURCE, type WindowLike, type WorkerEvent, type WorkerFactory, type WorkerLike, type WorkerRequest, WorkerRuntimeClient, type WorkerRuntimeClientDeps, type WorkerRuntimeHostOverrides, type WorkerScopeLike, WorkerUiBridge, XLSX_UNEXTRACTED, blockedMessage, bridgeError, captureElementImage, capturePhoto, checkCameraAvailability, checkDictationAvailability, compressImageToBudget, createBrowserChatbotHost, createDocumentSurfaceHost, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createFetchLinkedDocumentReader, createFrameRouter, createIframeWorker, createLlmClient, createPageAgentHandler, createRemotePageActionExecutor, createRemotePerceptionReader, createRemoteTargetRegistry, deleteMemoryEncryptionKey, documentKey, explainResolution, extractDocxText, extractXlsxText, extractZipWeb, generateMemoryEncryptionKey, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, missingPorts, openCamera, openDocumentSurface, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, seedSkillsFromHttp, sha256HexWeb, startDictation, startViewerShell, startWorkerRuntimeHost, viewerCspHeader, watchBlockedResources };
+//#region src/weboffice/types.d.ts
+/**
+ * WPS WebOffice 接入的环境无关契约（0.21.0 分册 11 FR-11.5 / 分册 12 FR-12.1）。
+ *
+ * 这里只有类型与常量，没有任何 `chrome.*` 与 DOM——扩展是消费方，不是唯一可能的消费方。
+ * 劫持本身（依赖 MV3 的 `world:"MAIN"`）留在扩展里。
+ */
+/**
+ * SDK v2.0.5 的 `OfficeType` 枚举。
+ *
+ * 值取自真实发行包 `web-office-sdk-solution-v2.0.5.umd.js` 里 `WebOfficeSDK.OfficeType`
+ * 的运行时快照——注意 `Dbt`/`KSheet` 是**长值**，与包内另一处 URL 拼装用的单字母枚举
+ * 不是同一个对象。早先按单字母登记，导致真实站点上指纹恒不匹配、挂钩静默退场（DV-16）。
+ *
+ * **这份常量是唯一事实源**：MAIN world 注入包不许 import 本模块（会把 SDK 代码
+ * 带进页面世界），只能抄一份，两处由 `test/webOfficeMirrors.test.ts` 比对。
+ * @experimental
+ */
+declare const WEB_OFFICE_OFFICE_TYPES: {
+  readonly Spreadsheet: "s";
+  readonly Writer: "w";
+  readonly Presentation: "p";
+  readonly Pdf: "f";
+  readonly Otl: "o";
+  readonly Dbt: "dbt";
+  readonly KSheet: "ksheet";
+};
+/** 本版支持抽取的四种。其余三种按 FR-12.1a 归因失败，不猜 @experimental */
+declare const WEB_OFFICE_SUPPORTED_TYPES: readonly ["w", "s", "p", "f"];
+type WebOfficeSupportedType = (typeof WEB_OFFICE_SUPPORTED_TYPES)[number];
+/** 登记表里一条实例。`handle` 之外的字段都来自 MAIN world，**只能进文案** @experimental */
+interface WebOfficeInstanceRecord {
+  /** ISOLATED 侧生成的不可预测 id；不复用 WPS 的 instanceId（FR-11.3a） */
+  handle: string;
+  /** 原样取自 init 参数，不做校验——它决定读法，不参与授权（分册 14 §3.1） */
+  officeType: string;
+  /** 仅用于展示与去重，不做信任判定（FR-11.3 / §4.2） */
+  fileId?: string;
+  /** 承载它的 iframe id；`init` 返回时往往还没建出来 */
+  iframeId?: string;
+  documentUrl: string;
+  state: 'initialising' | 'ready' | 'failed';
+}
+/** 一次抽取的产物。`kind` 由 officeType 映射，不由内容推断（FR-12.1a） @experimental */
+type WebOfficeContent = {
+  kind: 'document';
+  title?: string;
+  blocks: DocumentBlock[];
+} | {
+  kind: 'workbook';
+  sheets: WorkbookSheet[];
+} | {
+  kind: 'presentation';
+  slides: PresentationSlide[];
+} | {
+  kind: 'pdf';
+  source: 'text' | 'vision';
+  pages: PdfPage[];
+};
+/** @experimental */
+interface DocumentBlock {
+  type: 'heading' | 'paragraph' | 'listItem' | 'tableRow';
+  /** 只在样式名精确匹配 `Heading 1..6` / `标题 1..6` 时出现；不靠字号猜（FR-12.2c） */
+  level?: number;
+  text: string;
+}
+/** @experimental */
+interface WorkbookSheet {
+  name: string;
+  /** 空单元格是 `null`，与空字符串区分（与分册 10 FR-10.2a 同口径） */
+  rows: (string | number | boolean | null)[][];
+  /** 还剩多少没读。取剩下的走 `WebOfficeReadResult.next`（FR-12.6c） */
+  truncated?: {
+    rows: number;
+    columns: number;
+  };
+  /** 预算先用完了，这张表一行都没读到。名字仍然列出——整张表凭空消失才是最坏的截断 */
+  unread?: true;
+}
+/** @experimental */
+interface PresentationSlide {
+  index: number;
+  title?: string;
+  body: string[];
+  notes?: string;
+  /** shape 总数多于取到文本的 shape 数时出现：图片/图表里的字没读到（FR-12.4c） */
+  unreadableShapes?: number;
+  /** 这一页自己插的图（FR-12.4d）。只有走原件直链解包时才有 */
+  imageIds?: string[];
+}
+/** @experimental */
+interface PdfPage {
+  /**
+   * `source==='text'` 时是文档页码；
+   * `source==='vision'` 时是**截屏序号**——视觉通道只有滚动位置，不知道文档分页。
+   * 上层不得当页码用（分册 13 §5.4）。
+   */
+  index: number;
+  text?: string;
+  /**
+   * 这一页对应的图片分片 id。两种来源：
+   * `source==='vision'` 时是那一屏的截屏；
+   * `source==='text'` 时是从原件字节渲染出的**整页图**——
+   * 这一页文字读不出、或页上有 ≥15% 面积的图时才有（FR-23.3）。
+   */
+  imageId?: string;
+}
+/**
+ * 续读游标（FR-12.6c）。坐标自包含，**不在实例侧存任何状态**——
+ * 实例的生命周期由页面控制（SPA 一次路由切换就没了），
+ * 存游标就得回答「游标失效后怎么办」，而完整坐标没有这个问题。
+ * @experimental
+ */
+interface WebOfficeReadCursor {
+  /** 工作簿：从第几张表继续（0 基，不含 WPS 的内部表） */
+  sheet?: number;
+  /** 工作簿：该表内从第几行继续（0 基） */
+  row?: number;
+  /** 文档：从第几个段落继续（0 基） */
+  block?: number;
+  /** PDF：从第几页继续（0 基） */
+  page?: number;
+}
+/**
+ * 一次读取的完整结果：内容 + 诚实的边角料。
+ * 截断与未抽取项都在这里，因为它们要和内容一起进模型上下文（FR-12.6a）。
+ * @experimental
+ */
+interface WebOfficeReadResult {
+  content: WebOfficeContent;
+  /** 触顶的预算项，英文短句，模型据此知道内容不全 */
+  truncation?: string[];
+  /** 还有后续内容时给出的续读坐标；缺席即读完了（FR-12.6c） */
+  next?: WebOfficeReadCursor;
+  /** 视觉通道的相邻截屏重叠说明（AC-12.5） */
+  overlapNote?: string;
+  /**
+   * 有图但本次没取的单元（分册 26 FR-26.2）。
+   * 空清单时**缺席**：报一个 0 会让模型以为自己确认过没有图。
+   */
+  deferred?: {
+    images: number;
+    units: WebOfficeReadCursor[];
+    note: string;
+  };
+}
+/**
+ * 本版**不抽取**什么。逐条写出来而不是笼统说「尽力而为」——
+ * 用户要能知道自己没看到的是哪些东西（FR-12.10）。
+ * @experimental
+ */
+declare const WEBOFFICE_UNEXTRACTED: readonly ["styling, fonts, colours and borders", "images and charts (a screenshot captures them, but nothing is extracted from them)", "tracked changes and comments", "formula expressions (only cached values are read)", "hidden rows, hidden columns and hidden slides are not marked as hidden", "headers and footers", "embedded objects (OLE)"];
+/** 读取的通道。`vision` 要截整个可见标签页，因此授权与记忆都与 jssdk 分开（FR-13.4c） @experimental */
+type WebOfficeChannel = 'jssdk' | 'vision';
+//#endregion
+//#region src/weboffice/fingerprint.d.ts
+/**
+ * 版本护栏（FR-11.6）。指纹只用 `init` 之前就看得到的东西：版本不认识时不能有任何读取尝试（AC-11.8）。
+ *
+ * 判据是**结构指纹**而不是 `WebOfficeSDK.version`。v2.0.5 确实带 `version` 静态属性
+ * （分册 11 §1.2 的实测表原先漏记了这一项，DV-16 已补），但护栏要挡的是「形状变了」，
+ * 版本号相同而形状变化、或号变而形状不变，都不该改变结论。
+ */
+/** 判定的输入形状：页面赋进来的那个对象上的 `OfficeType` @experimental */
+interface WebOfficeFingerprintResult {
+  supported: boolean;
+  /** 不支持时的英文原因，写明检测到什么、期望什么（FR-11.6b） */
+  reason?: string;
+}
+/**
+ * 逐条比对 `OfficeType`：七项全中放行，多出来的新类型也放行（WPS 加一种文档类型
+ * 不该让整个能力失效），缺一项或值不同即拒绝。
+ * @experimental
+ */
+declare function checkWebOfficeFingerprint(officeType: unknown): WebOfficeFingerprintResult;
+/** 便利包装：不支持时抛结构化错误，供调用点一行接入 @experimental */
+declare function assertWebOfficeFingerprint(officeType: unknown): void;
+//#endregion
+//#region src/weboffice/failures.d.ts
+/**
+ * 失败归因（FR-11.7 / AC-11.9）。
+ *
+ * 「读不到这份文档」有五种完全不同的原因，用户的下一步也完全不同：
+ * 换个页面、等一会儿、这个 SDK 我们不认识、这种文档没有这个能力、网络不通。
+ * 混成一个 `TOOL_UNSUPPORTED` 就等于什么也没说。
+ */
+type WebOfficeFailure = {
+  kind: 'no-instance';
+} | {
+  kind: 'not-ready';
+} | {
+  kind: 'unsupported-version';
+  detected: string;
+} | {
+  kind: 'capability-absent';
+  officeType: string;
+  method: string;
+} | {
+  kind: 'timeout';
+};
+/** @experimental */
+declare function webOfficeFailure(failure: WebOfficeFailure): WebSkillError;
+//#endregion
+//#region src/weboffice/handle.d.ts
+/**
+ * 跨世界引用实例用的 id（FR-11.3a / AC-11.6）。
+ *
+ * 生成过程**不读任何入参**——不读 WPS 的 instanceId、不读 fileId、不读 DOM 顺序。
+ * 那些值页面全都看得到也改得了，用它们派生等于让「不可预测」变成一句话。
+ * 调用点必须在 ISOLATED 侧：MAIN 世界生成的任何值页面都读得到（分册 12 §3）。
+ */
+/** @experimental */
+declare function createWebOfficeHandle(): string;
+//#endregion
+//#region src/weboffice/port.d.ts
+/**
+ * 抽取协调器与桥之间的唯一接口（分册 13 §8 的硬性结构要求）。
+ *
+ * 协调器只认这个端口，不认扩展的消息通道——否则预算、截断、
+ * 错误归因这些判据全都得开浏览器才能测，而它们本身没有一行浏览器代码。
+ * @experimental
+ */
+interface WebOfficeReadPort {
+  /** `api.ready` 下发的方法名快照。一个实例只探一次，缓存归实现方（FR-12.8b） */
+  describe(handle: string): Promise<WebOfficeApiSurface>;
+  /** 调一个只读方法。返回值来自 MAIN world，**不可信**，用前必须判形状 */
+  call(handle: string, method: string, args?: readonly unknown[]): Promise<unknown>;
+  /** ②级：iframe 内被窥探到的原始 PDF 字节；没有即 undefined（FR-12.5b） */
+  takeCapturedPdf?(handle: string): Promise<Uint8Array | undefined>;
+  /** ⓪级：原件直链取回的演示文稿字节；没有即 undefined（FR-12.4d） */
+  takeCapturedPresentation?(handle: string): Promise<Uint8Array | undefined>;
+}
+/**
+ * 演示文稿原件的解包器（FR-12.4d）。
+ *
+ * 与 `PdfDocumentReader` 同一个道理：实现要 zip 库，只有浏览器扩展用得上，
+ * 所以 SDK 只留接口，实现由宿主注入。**这里不是渲染器**——pptx 包里没有页面图。
+ * @experimental
+ */
+interface PresentationSourceReader {
+  read(bytes: Uint8Array): Promise<PresentationSourceDocument>;
+}
+/** @experimental */
+interface PresentationSourceDocument {
+  readonly slides: readonly PresentationSourceSlide[];
+}
+/** @experimental */
+interface PresentationSourceSlide {
+  /** 形状顺序的文本，已去空 */
+  readonly texts: readonly string[];
+  /** 演讲者备注；没有即空串 */
+  readonly notes: string;
+  /** 只属于这一页的图。母版/版式上的模板底图不在其中（FR-12.4d 纪律 1） */
+  readonly images: readonly {
+    readonly mimeType: string;
+    readonly data: string;
+  }[];
+  /** 这一页上解不了的媒体数（tiff/emf/wmf/视频）。进 FR-12.4c 的分母 */
+  readonly skippedMedia: number;
+}
+/** @experimental */
+interface WebOfficeApiSurface {
+  readonly methods: ReadonlySet<string>;
+  /** 探测时刻，用于诊断上游漂移 */
+  readonly capturedAt: number;
+}
+/**
+ * 视觉通道的宿主出口。滚动在 iframe 内的 MAIN world 做（父页面滚不动跨源 iframe），
+ * 截屏在扩展页做（`captureVisibleTab` 是唯一能拍到跨源 iframe 的途径）。
+ * @experimental
+ */
+interface WebOfficeVisionPort {
+  /** 滚一屏并回报位置；到底时 `done` 为真 */
+  scroll(handle: string): Promise<WebOfficeScrollPosition>;
+  /** 拍一张并压到预算内；tab 已切走时抛错（FR-13.5c） */
+  capture(handle: string): Promise<{
+    mimeType: string;
+    data: string;
+  }>;
+}
+/** @experimental */
+interface WebOfficeScrollPosition {
+  scrollTop: number;
+  viewportHeight: number;
+  done: boolean;
+  /** 3s 内没等到渲染稳定就拍了（分册 13 §5.2）；模型要知道这一张可能没画完 */
+  unsettled?: boolean;
+}
+/**
+ * 只读方法白名单（需求 §4.3 的第一层结构性阻断）。
+ *
+ * 调用器只接受这里面的名字，写方法从来不在里面——「只读」因此是结构上的，
+ * 不是靠调用方自律。第二层是 `test/webOfficeReadOnly.test.ts` 的静态守卫。
+ * @experimental
+ */
+declare const WEB_OFFICE_READ_METHODS: {
+  /** Writer 分支 A：一次取回全文 */
+  readonly documentText: "GetDocumentText";
+  /** Writer 分支 B：段落级遍历，带样式名 */
+  readonly paragraphs: "GetParagraphs";
+  /** 表格：工作表名清单 */
+  readonly sheetNames: "GetSheetNames";
+  /** 表格分支 A：区域级取值，一次一块 */
+  readonly usedRange: "GetUsedRange";
+  /** 表格分支 B：行级取值 */
+  readonly sheetRows: "GetSheetRows";
+  /** 表格分支 C：只有单元格级 → 按 FR-12.3a 转视觉通道 */
+  readonly cell: "GetCell";
+  readonly slideCount: "GetSlideCount";
+  readonly slideTitle: "GetSlideTitle";
+  readonly slideBody: "GetSlideBody";
+  readonly slideNotes: "GetSlideNotes";
+  readonly pdfPageCount: "GetPageCount";
+  readonly pdfPageText: "GetPageText";
+};
+/** @experimental */
+declare function isWebOfficeReadMethod(method: string): boolean;
+/** 预算（FR-12.6）。三个计数器都装在发起读取的这一侧——MAIN world 的代码页面能改 @experimental */
+declare const WEBOFFICE_BUDGET: {
+  readonly roundTrips: 200;
+  readonly totalMs: 60000;
+  readonly cellsPerRead: 20000;
+  readonly visionPages: 50;
+  /**
+   * 区域级取值一次取多少**行**。
+   * 单位是行不是格（DV-9）：按格数折算行数的话，同一份表列数一多往返次数就跟着涨，
+   * 「列数从 20 加到 40 往返次数不变」这条验收就过不了。
+   */
+  readonly rowsPerChunk: 200;
+  /** 文本类内容的截断口径与附件一致，不另立标准 */
+  readonly textChars: number;
+};
+type WebOfficeBudget = typeof WEBOFFICE_BUDGET;
+/**
+ * 触到预算就停，并把停的原因留下——与分册 10「一律拒绝」相反：
+ * 那边产出的是给人下载的文件，少几行没有线索；这边产出的是给模型看的上下文，
+ * 截断有标记就是诚实的（FR-12.6a）。
+ * @experimental
+ */
+declare class WebOfficeBudgetGuard {
+  #private;
+  constructor(budget?: WebOfficeBudget, now?: () => number);
+  /**
+   * 让预算守卫顺带看住本次 run 的取消信号。
+   *
+   * 每个读取循环都已经在每一轮开头问一次 `spent()`，取消挂在这里就等于挂在了
+   * 所有循环上；散在各处单独判 `signal.aborted` 迟早会漏掉一条分支——
+   * 而漏掉的那条正是「按了终止却还在读」的那条。
+   */
+  stopOn(signal: AbortSignal): void;
+  get roundTrips(): number;
+  get truncation(): readonly string[];
+  /** 触顶即返回 true，调用方停止继续读并保留已读到的部分 */
+  spent(): boolean;
+  countRoundTrip(): void;
+  note(message: string): void;
+}
+/**
+ * 调一个只读方法：先查白名单，再查描述符，最后才调（FR-12.8a）。
+ *
+ * 「描述符里没有」与「调用失败」必须是两个错误码——混成一个，用户就无法判断
+ * 是「换个文档试试」还是「这功能不支持」。
+ * @experimental
+ */
+declare function callWebOfficeMethod(port: WebOfficeReadPort, surface: WebOfficeApiSurface, guard: WebOfficeBudgetGuard, handle: string, officeType: string, method: string, args?: readonly unknown[]): Promise<unknown>;
+//#endregion
+//#region src/weboffice/extract.d.ts
+/**
+ * 抽取协调器（分册 12）。
+ *
+ * 全部判据——走哪条分支、什么时候停、截断怎么说——都在这一层，
+ * 与它对话的只有 `WebOfficeReadPort`，因此十一条验收里有八条不用开浏览器就能测。
+ */
+/** @experimental */
+interface WebOfficeExtractOptions {
+  handle: string;
+  /** 原样来自 init 参数；决定读法，不参与授权判定 */
+  officeType: string;
+  mode?: 'auto' | 'vision' | 'images';
+  /** 上一次返回的 `next`。不传即从头读（FR-12.6c） */
+  from?: WebOfficeReadCursor;
+  vision?: WebOfficeVisionPort;
+  /** ②级：iframe 里窥到的原始 PDF 字节 → 文本。扩展注入 pdfjs，SDK 不打包它 */
+  pdfExtractor?(bytes: Uint8Array): Promise<string>;
+  /**
+   * ⓪级：同一份字节 → 逐页文本 + 整页渲染（FR-23.1）。
+   * 类型取分册 22 已导出的那个端口，扩展里两条路共用同一份实现。
+   */
+  pdfDocumentReader?: PdfDocumentReader;
+  /** ⓪级（演示文稿）：原件字节 → 逐页文本与本页插图（FR-12.4d） */
+  presentationReader?: PresentationSourceReader;
+  guard?: WebOfficeBudgetGuard;
+  /** 本次 run 的取消信号；用户按下终止后不再继续往下读（FR-13.9） */
+  signal?: AbortSignal;
+  onImage?(image: {
+    id: string;
+    mimeType: string;
+    data: string;
+  }): void;
+}
+/**
+ * 样式名 → 标题级别。**只认精确匹配**（FR-12.2c）：
+ * 靠字号或粗体猜标题，猜错的那份大纲比没有大纲更误导人。
+ * @experimental
+ */
+declare function headingLevelOf(style: unknown): number | undefined;
+/** officeType → 内容形态（FR-12.1a）。三种不支持的类型在这里就被挡住 @experimental */
+declare function contentKindOf(officeType: string): WebOfficeContent['kind'] | undefined;
+/** @experimental */
+declare function extractWebOfficeContent(port: WebOfficeReadPort, options: WebOfficeExtractOptions): Promise<WebOfficeReadResult>;
+//#endregion
+//#region src/weboffice/vision.d.ts
+/**
+ * 视觉通道（FR-12.7）。它不是「①②都失败时才走的兜底分支」——
+ * 那样它在测试里一次都不会执行。`mode: 'vision'` 是显式入口（FR-12.5e）。
+ */
+/**
+ * 相邻两屏重叠的说明（AC-12.5）。
+ *
+ * 去重**不裁图**：裁重叠带需要精确像素对齐，裁错就是丢内容。
+ * 改成如实告知——模型知道两张图有一段是同一片内容就不会把它数两遍。
+ * @experimental
+ */
+declare function describeScreenshotOverlap(positions: readonly WebOfficeScrollPosition[]): string | undefined;
+/** @experimental */
+interface VisionCaptureOptions {
+  handle: string;
+  vision: WebOfficeVisionPort;
+  guard?: WebOfficeBudgetGuard;
+  maxPages?: number;
+  /** 图片分片 id 的前缀；同一次读取内唯一即可 */
+  idPrefix?: string;
+  /** 收图片分片的出口：协调器把它们交给工具层拼进 ToolResult */
+  onImage(image: {
+    id: string;
+    mimeType: string;
+    data: string;
+  }): void;
+}
+/**
+ * 滚一屏、拍一张，直到到底或触顶。
+ * `PdfPage.index` 在这里填的是**截屏序号**，不是文档页码——视觉通道只有滚动位置。
+ * @experimental
+ */
+declare function captureByScrolling(options: VisionCaptureOptions): Promise<WebOfficeReadResult>;
+//#endregion
+//#region src/weboffice/authTypes.d.ts
+/** 三种动作各自确认。列出、读取、截屏对用户是三件不同的事（FR-13.4c） @experimental */
+type WebOfficeAction = 'list' | 'read' | 'capture';
+/**
+ * 判定用的钥匙——**全部来自扩展自己**，页面改不了。
+ *
+ * 分界线是「这个值能不能让一次本该弹卡的操作变成不弹卡」：
+ * `origin` 能（记忆按站点粒度），所以它必须可信；
+ * `officeType` 不能（它只决定怎么读、卡上显示成什么），所以它可以来自页面。
+ * @experimental
+ */
+interface WebOfficeAuthorizationKey {
+  /** 由扩展从 tab / frame 信息取得，不是页面自称的 */
+  readonly origin: string;
+  readonly tabId: number;
+  /** ISOLATED 侧生成的不可预测 id */
+  readonly handle: string;
+}
+/**
+ * 卡上要显示、但**页面说了算**的东西（FR-13.2a）。
+ * `claimed` 前缀就是标注本身：渲染层拿到的每个字段名都在提醒它是谁说的。
+ *
+ * 判定模块不 import 本类型——不是「记得别用」，是结构上够不着。
+ * @experimental
+ */
+interface WebOfficeDisplayHints {
+  readonly claimedOfficeType?: string;
+  readonly claimedFileId?: string;
+}
+/**
+ * 「不再询问」的记忆端口。**粒度归宿主**：SDK 不知道装配方把记忆记在
+ * 站点、标签页还是单份文档上，写死就是替宿主谎报授权范围（与 D-20-2 同一条思路）。
+ *
+ * 宿主实现了记忆就**必须**实现 `describeScope`：卡上那句「这个站点」的
+ * 唯一合法来源是宿主，SDK 没资格替它宣称。
+ * @experimental
+ */
+interface WebOfficeConsent {
+  recall(action: WebOfficeAction, key: WebOfficeAuthorizationKey): boolean | Promise<boolean>;
+  remember(action: WebOfficeAction, key: WebOfficeAuthorizationKey): void | Promise<void>;
+  describeScope?(action: WebOfficeAction, key: WebOfficeAuthorizationKey): string | undefined;
+}
+/**
+ * 一次读取的留痕（FR-13.6）。
+ *
+ * **没有内容字段，也不会有**：审计要回答的是「什么时候、在哪个站点、读了什么类型的东西」。
+ * 把文档正文抄进审计日志，等于把一次披露变成两次——而且第二次是持久化的。
+ * @experimental
+ */
+interface WebOfficeAuditRecord {
+  at: string;
+  origin: string;
+  action: WebOfficeAction;
+  /** 页面自称的类型，字段名保留 `claimed` 以免日后被当成事实读 */
+  claimedOfficeType?: string;
+  channel: WebOfficeChannel;
+  /** 这次是靠记忆放行的还是当场问的 */
+  rememberHit: boolean;
+}
+//#endregion
+//#region src/weboffice/policy.d.ts
+/**
+ * 扩展（或别的宿主）提供的 WebOffice 接入面。**不注入即整条能力不存在**：
+ * 工具不注册，模型看不到它——与下载文件、页面操作同一条思路。
+ * @experimental
+ */
+interface WebOfficeHost {
+  /** 当前上下文里已捕获的实例。每次调用重新枚举，顺带清掉 iframe 已消失的那些 */
+  list(): Promise<readonly WebOfficeInstanceRecord[]>;
+  /**
+   * handle → 可信钥匙。**只能由宿主给**：origin 与 tabId 是授权判定的输入，
+   * 让页面参与提供它们，等于把「记住这个站点」变成页面可以自选的东西。
+   */
+  keyOf(handle: string): Promise<WebOfficeAuthorizationKey | undefined>;
+  read: WebOfficeReadPort;
+  /** 视觉通道。不注入即需要截屏的文档读不了，而不是静默给空内容 */
+  vision?: WebOfficeVisionPort;
+  /** 原始 PDF 字节 → 文本。扩展装 pdfjs，SDK 不打包它 */
+  pdfExtractor?(bytes: Uint8Array): Promise<string>;
+  /**
+   * 原始 PDF 字节 → 逐页文本 + 整页渲染（FR-23.1）。不注入即 PDF 里的图读不到，
+   * 而不是报错——与 `vision` / `pdfExtractor` 同口径（FR-23.7）。
+   * 它**不参与授权判定**：渲染源是已经在本地的字节，不读屏幕（FR-23.6）。
+   */
+  pdfDocumentReader?: PdfDocumentReader;
+  /**
+   * 演示文稿原件字节 → 逐页文本与本页插图（FR-12.4d）。
+   * 不注入即 PPT 只走 jssdk 形状遍历，口径同 `pdfDocumentReader`。
+   */
+  presentationReader?: PresentationSourceReader;
+}
+/** @experimental */
+interface WebOfficePolicyOptions {
+  host?: WebOfficeHost;
+  /** 授权卡出口。**必填**：接不上就构造不出策略，没有 fail-open 这条路 */
+  ui: ConsentUi;
+  consent?: WebOfficeConsent;
+  audit?: PageAuditSink;
+  auditTarget?: string;
+  now?(): string;
+  /** 等待用的延时。默认 `setTimeout`；测试注入立即兑现的版本，免得为一条时序判据真等几秒 */
+  sleep?(ms: number): Promise<void>;
+}
+/** 模型看得到的实例摘要。字段名带 `claimed` 的都来自页面 @experimental */
+interface WebOfficeListing {
+  handle: string;
+  claimedOfficeType: string;
+  claimedFileId?: string;
+  ready: boolean;
+}
+/** @experimental */
+interface WebOfficeReadOptions {
+  handle?: string;
+  mode?: 'auto' | 'vision' | 'images';
+  /** 上一次返回的 `next`，取剩下的那部分（FR-12.6c） */
+  from?: WebOfficeReadCursor;
+  /** 同一 run 内的重复请求不重弹卡，也不重复记拒绝（FR-13.7） */
+  runId: string;
+  /** 本次 run 的取消信号；一份上百页的文档读到一半被叫停，就得真的停 */
+  signal?: AbortSignal;
+  onImage?(image: {
+    id: string;
+    mimeType: string;
+    data: string;
+  }): void;
+}
+/**
+ * WebOffice 读取策略（分册 13）。
+ *
+ * 三道闸门：宿主接没接、用户认不认、这次要不要额外的截屏授权。
+ * 视觉通道的授权是**懒的**——`auto` 模式一路降级到截屏时才弹，
+ * 因为在那之前谁也不知道这份文档需不需要拍照。
+ * @experimental
+ */
+declare class WebOfficePolicy {
+  #private;
+  constructor(options: WebOfficePolicyOptions);
+  get enabled(): boolean;
+  list(runId: string): Promise<readonly WebOfficeListing[]>;
+  read(options: WebOfficeReadOptions): Promise<WebOfficeReadResult>;
+}
+//#endregion
+//#region src/weboffice/authorization.d.ts
+/**
+ * 授权判定（分册 13 FR-13.3）。
+ *
+ * 本模块**只 import `WebOfficeAuthorizationKey`**，不 import `WebOfficeDisplayHints`：
+ * 页面自称的值想混进判定，得先有人在这里加一行 import——那是 review 看得见的动作，
+ * 而不是某次改动里悄悄多读了一个字段。
+ */
+/** @experimental */
+interface WebOfficeAuthorizationInput {
+  action: WebOfficeAction;
+  key: WebOfficeAuthorizationKey;
+  channel: WebOfficeChannel;
+  ui: ConsentUi;
+  consent?: WebOfficeConsent;
+  /**
+   * 卡上要显示的、来自页面的自称值。**只透传进 `details`，判定一个字节都不读**。
+   * 类型是宽松的字符串字典而不是具体接口：这里根本不该有「知道它长什么样」的能力。
+   */
+  display?: Readonly<Record<string, string>>;
+  /** 卡 id 的序号，来自调用方的计数器 */
+  seq: number;
+}
+/** @experimental */
+interface WebOfficeAuthorizationOutcome {
+  approved: boolean;
+  /** 靠记忆放行的这次没有弹卡 */
+  rememberHit: boolean;
+}
+/** @experimental */
+declare function resolveWebOfficeAuthorization(input: WebOfficeAuthorizationInput): Promise<WebOfficeAuthorizationOutcome>;
+//#endregion
+//#region src/weboffice/toolSource.d.ts
+declare const LIST_WEBOFFICE_DOCUMENTS_TOOL = "list_weboffice_documents";
+declare const READ_WEBOFFICE_DOCUMENT_TOOL = "read_weboffice_document";
+/** @experimental */
+interface WebOfficeToolSourceOptions {
+  policy: WebOfficePolicy;
+}
+/**
+ * 把 WebOffice 读取接到工具协议上（分册 13 §7）。
+ *
+ * 宿主没接或开关没开时 `listToolSpecs()` 返回空数组——模型连它的存在都看不到。
+ * @experimental
+ */
+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 };