@webskill/sdk 0.10.0 → 0.12.0

package/dist/browser.d.ts

@@ -1,6 +1,6 @@
-import { Ct as VerifyResult, L as FileStat, M as ArchiveLimits, R as FileSystemProvider, S as UiBridge, _t as SkillsLockfile, b as RenderResultRequest, c as InteractionResponse, dt as SkillManifest, l as LlmClient, m as LlmStreamEvent, o as InteractionPolicy, p as LlmResponse, s as InteractionRequest, st as SkillInstallSource, u as LlmCompleteInput, v as MemoryStore, wt as WebSkillError, xt as UnsignedPolicy, yt as TrustedKeyStore } from "./types-CrRcT-LM-DZAp8sWv.js";
-import { Dt as ScriptExecutor, Et as ScriptExecutionContext, Hn as parseBridgeRequest, Jt as ToolDefinition, O as ExternalSkillProvider, Xt as ToolResult, Y as NetworkPolicy, _ as BridgeCapabilities, b as BridgeResponse, f as ApprovalScope, k as ExternalToolSource, pn as WebSkillApi, vn as bridgeError, y as BridgeRequest } from "./index-DtFdMKBX.js";
-import { A as PagePerceptionReader, C as PageActionRequest, I as PerceptionCaptureOptions, O as PagePerceptionPolicy, P as PerceivedNode, R as PerceptionResult, _ as PageActionExecutor, w as PageActionScope, y as PageActionOutcome, z as PerceptionScope } from "./index-BF4E1a9j.js";
+import { Ct as VerifyResult, L as FileStat, M as ArchiveLimits, R as FileSystemProvider, S as UiBridge, _t as SkillsLockfile, b as RenderResultRequest, c as InteractionResponse, dt as SkillManifest, l as LlmClient, m as LlmStreamEvent, o as InteractionPolicy, p as LlmResponse, s as InteractionRequest, st as SkillInstallSource, u as LlmCompleteInput, v as MemoryStore, wt as WebSkillError, xt as UnsignedPolicy, yt as TrustedKeyStore } from "./types-DLctJep_-B5G4uk2u.js";
+import { Bt as ScriptExecutionContext, F as ExternalToolSource, Nn as WebSkillApi, P as ExternalSkillProvider, Rn as bridgeError, S as BridgeResponse, Vt as ScriptExecutor, cr as parseBridgeRequest, dn as ToolResult, it as NetworkPolicy, ln as ToolDefinition, m as ApprovalScope, nt as LinkedDocumentReader, x as BridgeRequest, y as BridgeCapabilities } from "./index-C9pzXLKy.js";
+import { H as PagePerceptionPolicy, J as PerceivedNode, L as PageActionScopeInput, Q as PerceptionResult, W as PagePerceptionReader, X as PerceptionCaptureOptions, et as PerceptionScopeInput, k as PageActionExecutor } from "./index-DFhU1uks.js";
 //#region ../browser/dist/index.d.ts
 //#region src/fs/featureDetection.d.ts
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -374,14 +374,25 @@ interface DomPerceptionReaderOptions {
    * 可操作范围（需求 23）。缺省即**不发任何句柄**，感知结果与 0.6.0 逐字相同。
    * 它与感知范围分开声明：可读不等于可操作（FR-23.1）。
    */
-  actionScope?: PageActionScope;
+  actionScope?: PageActionScopeInput;
 }
 /** DOM 遍历是同步的；不取像时比 `PagePerceptionReader` 窄，调用方无需 await @experimental */
 interface DomPerceptionReader extends PagePerceptionReader {
-  read(scope: PerceptionScope): readonly PerceivedNode[];
-  read(scope: PerceptionScope, capture: PerceptionCaptureOptions): Promise<PerceptionResult>;
+  read(scope: PerceptionScopeInput): readonly PerceivedNode[];
+  read(scope: PerceptionScopeInput, capture: PerceptionCaptureOptions): Promise<PerceptionResult>;
   /** 把句柄换回元素；未知或已过期的句柄返回 undefined。供执行器使用，不自建第二张表 */
   resolve(ref: string): Element | undefined;
+  /** 句柄所属的帧；主文档目标返回 undefined（FR-24.6 的确认卡措辞与审计据此区分） */
+  frameOf(ref: string): string | undefined;
+  /** 操作前的活动模态快照；与操作后做差集即「本次新打开的模态」（FR-25.6） */
+  modalSnapshot(): ReadonlySet<Element>;
+  /** 把新出现的模态纳入授权面，返回被提升的那个（没有则 undefined） */
+  elevateNewModals(before: ReadonlySet<Element>): Element | undefined;
+  /**
+   * 元素与模态的关系：不在模态里 / 在已提升的模态里 / 在未授权的模态里。
+   * 最后一种要给出可操作的拒绝理由，而不是笼统的「不在范围内」。
+   */
+  modalStateOf(element: Element): 'none' | 'elevated' | 'unelevated';
   /** 元素当前是否仍在可操作范围内（执行前的第二道闸门，AC-23.3） */
   inActionScope(element: Element): boolean;
 }
@@ -404,11 +415,19 @@ declare function createDomPerceptionReader(options?: DomPerceptionReaderOptions)
 interface DomPageActionOptions {
   /** 发放句柄的那个 reader；`resolve` / `inActionScope` 都从它取 */
   reader: DomPerceptionReader;
+  /**
+   * `attach` 的文件来源（FR-25.5）：**必须由用户手势触发**的选择器。
+   * 不注入即 `attach` 一律按「用户取消」处理 —— Agent 永远传不进本地路径。
+   */
+  pickFiles?: () => Promise<readonly File[] | undefined>;
 }
-/** DOM 操作是同步的；比 `PageActionExecutor` 窄，调用方无需 await @experimental */
-interface DomPageActionExecutor extends PageActionExecutor {
-  execute(request: PageActionRequest): PageActionOutcome;
-}
+/**
+ * @experimental
+ *
+ * ⚠️ 0.11.0 分册 25 起**不再是同步的**：`select` 要等下拉浮层出现，
+ * `attach` 要等用户在确认卡里选文件。接口本来就是 async，改的是这里的实现。
+ */
+type DomPageActionExecutor = PageActionExecutor;
 /** @experimental */
 declare function createDomPageActionExecutor(options: DomPageActionOptions): DomPageActionExecutor;
 //#endregion
@@ -792,4 +811,232 @@ interface BrowserHostOptions {
 }
 declare function createBrowserChatbotHost(options: BrowserHostOptions): BrowserHostBundle;
 //#endregion
-export { type BridgeCapabilities, type BridgeRequest, type BridgeResponse, type BrowserHostBundle, type BrowserHostOptions, type BrowserHostOverrides, BrowserSkillManager, BrowserWorkerScriptExecutor, type CaptureFailure, type CaptureLevel, type CapturedImage, type ChromeBuiltinAvailability, ChromeBuiltinLlmClient, type CompressResult, type ConfiguredLlmClient, type DictationAvailability, type DictationOptions, type DictationSession, type DomPageActionExecutor, type DomPageActionOptions, type DomPerceptionReader, type DomPerceptionReaderOptions, HOST_PORT_MATRIX, type HostChatbotAdapterShape, type HostConnectFacadeShape, type HostConsoleBackendShape, type HostKind, type HostSurface, IframeWorkerLike, type InspectHostWiringInput, type LlmClientConfig, type LlmEntryConfig, type MainToWorkerMessage, OpfsProvider, type PortApplicability, type PortReport, type PortSpec, type PortStatus, type SandboxMode, type SerializedError, TsTranspiler, type TypeScriptSupportOptions, WORKER_BOOTSTRAP_SOURCE, type WorkerEvent, type WorkerFactory, type WorkerLike, type WorkerRequest, WorkerRuntimeClient, type WorkerRuntimeClientDeps, type WorkerRuntimeHostOverrides, type WorkerScopeLike, WorkerUiBridge, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createBrowserChatbotHost, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createIframeWorker, createLlmClient, deleteMemoryEncryptionKey, extractZipWeb, generateMemoryEncryptionKey, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, missingPorts, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startWorkerRuntimeHost };
+//#region src/net/fetchLinkedDocument.d.ts
+interface FetchLinkedDocumentOptions {
+  /**
+   * 宿主页面 origin，用于同源判定。缺省取 `location.origin`。
+   *
+   * **显式传 `undefined` 不等于取缺省**：拿不到 origin 时上游会一律按跨源处理，
+   * 即每次都问用户。那是保守方向，不是缺陷。
+   */
+  origin?: string;
+  /** 注入点存在只为可测；生产装配留空即用全局 fetch */
+  fetch?: typeof globalThis.fetch;
+  /** 单次请求超时，缺省 30s */
+  timeoutMs?: number;
+}
+/**
+ * 默认的链接文档读取实现（分册 22 §2.2）。
+ *
+ * 出站准入（scheme / 私有地址）与同源判定都在**引擎侧**完成，这里只负责取字节：
+ * 把判定散到实现里，宿主换一个 reader 就能绕过整套闸门。
+ * @experimental
+ */
+declare function createFetchLinkedDocumentReader(options?: FetchLinkedDocumentOptions): LinkedDocumentReader;
+//#endregion
+//#region src/document/docx.d.ts
+/**
+ * docx 正文抽取（分册 22 §2.4 / FR-23.7）。
+ *
+ * **零新增依赖**：zip 用仓内既有的 `unzipWithLimits`（自带解压体积上限，
+ * 顺带挡住 zip 炸弹），XML 用浏览器原生 `DOMParser`。
+ *
+ * ⚠️ `DOMParser` 是浏览器 API，Node 没有 —— 所以这个模块只在 `@webskill/browser`。
+ * Node 宿主没有 docx 能力，这是**显式声明**的限制（AC-G15），不是静默降级；
+ * 收紧到 Node 侧的备案是 D55。
+ */
+/**
+ * **不抽取**的内容，逐条写明而不是笼统说「尽力而为」：
+ * 样式、标题层级、图片、批注、修订、页眉页脚、脚注。
+ *
+ * 模型拿到的是纯正文文本流。把「这是 H1」这类信息也抽出来需要解析
+ * `styles.xml` 的样式继承链，那是另一个量级的工作，本版不做。
+ */
+declare const DOCX_UNEXTRACTED: readonly ["styles", "heading levels", "images", "comments", "tracked changes", "headers and footers", "footnotes"];
+/**
+ * 从 docx 字节里抽出正文文本。
+ *
+ * @throws WebSkillError 归档损坏、缺 `word/document.xml`、XML 解析失败
+ */
+declare function extractDocxText(bytes: Uint8Array): Promise<string>;
+//#endregion
+//#region src/viewer/viewerCsp.d.ts
+/** 宿主可配置的白名单方向；技能声明不了这些（FR-18.3 第 3 条） */
+interface ViewerCspOptions {
+  /**
+   * 提供 viewer 路由的宿主来源，例如 `https://app.example`。**必填**。
+   *
+   * ⚠️ 这里**不能**用 `'self'`：文档被 `sandbox` 指令推进了 opaque origin，
+   * 而 `'self'` 匹配的是文档自身的来源——opaque origin 匹配不上任何 URL，
+   * 于是外壳自己的脚本先被挡住，页面变成一片空白。
+   * 同理，宿主还必须给 viewer 的静态资源回 `Access-Control-Allow-Origin`：
+   * 模块脚本是带 `crossorigin` 的跨源请求，`Origin: null` 拿不到默认放行。
+   */
+  hostOrigin: string;
+  /** 文档可外发的目标；缺省 `'none'` —— 数据经 postMessage 下发，不需要外连 */
+  connectSrc?: readonly string[];
+  /** 图片来源；缺省宿主自身 + `data:`（内联图不走网络） */
+  imgSrc?: readonly string[];
+  /** 字体来源；缺省只有宿主自身，外链公文字体需宿主显式放行（FR-20.5） */
+  fontSrc?: readonly string[];
+}
+/**
+ * 生成 viewer 路由的 `Content-Security-Policy` 响应头值。
+ *
+ * 宿主只能**加白名单来源**，加不了 sandbox token —— 隔离边界的策略不由被隔离方
+ * 也不由宿主的白名单配置决定。
+ */
+declare function viewerCspHeader(options: ViewerCspOptions): string;
+/** 本版固定的 sandbox token（供判据与装配文档引用，避免第二份清单） */
+declare const VIEWER_SANDBOX_TOKENS: readonly string[];
+//#endregion
+//#region src/viewer/documentSurface.d.ts
+/**
+ * 文档投放面（0.11.0 分册 18）。
+ *
+ * ⚠️ **三个必须避开的实现陷阱**（FR-18.4）——「生成 HTML → Blob → 新窗口」
+ * 是最自然的实现路径，也是**安全性归零**的路径：
+ *
+ * | 写法                                            | 为什么不安全                                   |
+ * | ----------------------------------------------- | ---------------------------------------------- |
+ * | `URL.createObjectURL(blob)` + `window.open`     | **`blob:` 继承创建者 origin** → 同源，隔离归零 |
+ * | `window.open('about:blank')` + `document.write` | 同样继承 origin                                |
+ * | `data:` URL 顶层导航                            | 现代浏览器已禁止；历史钓鱼载体                 |
+ *
+ * 正确形态只有一种：`window.open(viewerUrl)` 指向宿主的 **HTTP 路由**，
+ * 由响应头下发 `sandbox` 指令让顶层文档自己进 opaque origin。
+ */
+/** 投递给 viewer 的一份文档 */
+interface ViewerDocument {
+  /** 技能产出的 HTML 片段（**不受信**，外壳按数据写入） */
+  html: string;
+  /** 技能的样式表文本 */
+  css?: string;
+  /** 单向下发的数据；文档内的筛选是本地过滤，不回传（FR-18.7） */
+  data?: unknown;
+}
+interface DocumentSurfaceAudit {
+  append(event: {
+    type: string;
+    target: string;
+    data?: Record<string, unknown>;
+  }): Promise<unknown>;
+}
+interface OpenDocumentInput {
+  /** 产出这份文档的技能名；告知与留痕都要它（FR-18.6） */
+  skillName: string;
+  /** 数据来源描述，进告知与审计 */
+  dataSource: string;
+  document: ViewerDocument;
+}
+interface DocumentSurfaceOptions {
+  /** 宿主的 viewer 路由地址（必须能下发 CSP 响应头，见 viewerCsp.ts） */
+  viewerUrl: string;
+  /** 打开前的告知；返回 false 即取消（FR-18.6 第 1 条） */
+  confirm(input: {
+    skillName: string;
+    dataSource: string;
+  }): Promise<boolean>;
+  audit?: DocumentSurfaceAudit;
+  /** 投递载荷上限；超限拒绝而不是静默截断（AC-18.11） */
+  maxPayloadBytes?: number;
+  /** 握手超时；viewer 起不来时不能无限等 */
+  handshakeTimeoutMs?: number;
+  /** 仅供测试注入；缺省用 `window.open` */
+  open?(url: string, target: string): WindowLike | null;
+}
+/** 只用到的那部分窗口接口，便于单测替身 */
+interface WindowLike {
+  closed: boolean;
+  close(): void;
+  postMessage(message: unknown, targetOrigin: string): void;
+}
+declare const DEFAULT_MAX_VIEWER_PAYLOAD_BYTES = 2000000;
+/** 审计事件类型（与既有事件同一条链） */
+declare const DOCUMENT_SURFACE_AUDIT_EVENT = "document.surface.open";
+/**
+ * 打开一个文档投放面。
+ *
+ * `window.open` **必须在用户手势里调**，否则被浏览器拦截；不能在 run 收尾时自动开。
+ * 也**不加 `noopener`** —— 需要句柄才能把内容 post 进去。反控面不靠 `noopener` 封，
+ * 靠沙箱本身：无 `allow-same-origin` 读不到 opener 的任何东西，
+ * 无 `allow-top-navigation` 改不了它的地址。
+ */
+declare function openDocumentSurface(input: OpenDocumentInput, options: DocumentSurfaceOptions): Promise<WindowLike>;
+//#endregion
+//#region src/viewer/shell.d.ts
+/**
+ * viewer 外壳（0.11.0 分册 18 §2.4）。
+ *
+ * 外壳**受信**，技能内容**不受信**，两者同处一个文档。边界：
+ * - 外壳：收 `postMessage`、写 DOM；
+ * - 技能 HTML/CSS：只作为**数据**写入。经 `innerHTML` 写入时其中的 `<script>`
+ *   本就不执行，这与「技能不写 JS」（FR-18.5）一致，**不是缺陷**。
+ *
+ * 真正的交互来自外壳挂载的预置组件（分册 19），不是技能自带脚本。
+ */
+interface ViewerShellHost {
+  addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+  removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+  readonly opener: {
+    postMessage(message: unknown, targetOrigin: string): void;
+  } | null;
+}
+interface ViewerShellMount {
+  /** 技能 HTML 的落点 */
+  content: {
+    innerHTML: string;
+  };
+  /** 技能样式的落点 */
+  style: {
+    textContent: string | null;
+  };
+}
+interface ViewerShellResult {
+  /** 停止监听（窗口关闭 / 测试收尾） */
+  dispose(): void;
+}
+/**
+ * 启动外壳：等主应用的 hello → 回报 ready → 收文档 → 写进 DOM。
+ *
+ * `channelId` 必须由**主应用**在 hello 里给定并全程比对。opaque origin 下
+ * `event.origin` 恒为 `"null"`，任何沙箱页面都一样，靠 origin 分辨不了来源；
+ * 而 `event.source` 在这一侧只能确认「来自 opener」，确认不了是哪一次投放。
+ */
+declare function startViewerShell(host: ViewerShellHost, mount: ViewerShellMount, onData?: (data: unknown) => void): ViewerShellResult;
+//#endregion
+//#region src/viewer/blockedResources.d.ts
+/**
+ * viewer 里被 CSP 拦下的资源提示（0.11.0 分册 20 FR-20.5）。
+ *
+ * 外链公文字体默认不在白名单里，文档会**静静地**降级到系统字体。
+ * 打印预览与实际输出不一致是最糟的体验，所以这条降级必须让用户看见——
+ * 「不报错」不等于「不吭声」。
+ */
+interface ViewerBlockedNotice {
+  /** 提示文案的落点；只写 `textContent`，永不 `innerHTML` */
+  textContent: string | null;
+}
+interface ViewerBlockedHost {
+  addEventListener(type: 'securitypolicyviolation', listener: (event: BlockedEventLike) => void): void;
+  removeEventListener(type: 'securitypolicyviolation', listener: (event: BlockedEventLike) => void): void;
+}
+/** 只用到的那部分 `SecurityPolicyViolationEvent`，便于单测替身 */
+interface BlockedEventLike {
+  effectiveDirective: string;
+  blockedURI: string;
+}
+interface ViewerBlockedResult {
+  dispose(): void;
+}
+/**
+ * 监听 CSP 违规并把被拦资源汇总成一句话。
+ *
+ * 必须在**文档写入之前**挂上：违规事件不补发，晚一步就永远收不到。
+ * 同一个来源只报一次——一份文档引十个图标会刷出十条同样的提示。
+ */
+declare function watchBlockedResources(host: ViewerBlockedHost, notice: ViewerBlockedNotice): ViewerBlockedResult;
+/** 提示文案的单一来源；判据直接引用，不各写一份字面量 */
+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 CaptureFailure, type CaptureLevel, type CapturedImage, type ChromeBuiltinAvailability, ChromeBuiltinLlmClient, type CompressResult, type ConfiguredLlmClient, DEFAULT_MAX_VIEWER_PAYLOAD_BYTES, DOCUMENT_SURFACE_AUDIT_EVENT, DOCX_UNEXTRACTED, type DictationAvailability, type DictationOptions, type DictationSession, type DocumentSurfaceAudit, type DocumentSurfaceOptions, type DomPageActionExecutor, type DomPageActionOptions, type DomPerceptionReader, type DomPerceptionReaderOptions, type FetchLinkedDocumentOptions, HOST_PORT_MATRIX, type HostChatbotAdapterShape, type HostConnectFacadeShape, type HostConsoleBackendShape, type HostKind, type HostSurface, IframeWorkerLike, type InspectHostWiringInput, type LlmClientConfig, type LlmEntryConfig, type MainToWorkerMessage, type OpenDocumentInput, OpfsProvider, type PortApplicability, type PortReport, type PortSpec, type PortStatus, type SandboxMode, type SerializedError, 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, blockedMessage, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createBrowserChatbotHost, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createFetchLinkedDocumentReader, createIframeWorker, createLlmClient, deleteMemoryEncryptionKey, extractDocxText, extractZipWeb, generateMemoryEncryptionKey, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, missingPorts, openDocumentSurface, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startViewerShell, startWorkerRuntimeHost, viewerCspHeader, watchBlockedResources };