@webskill/sdk 0.13.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/dist/agent.d.ts +3 -3
  2. package/dist/agent.js +2442 -3
  3. package/dist/{dist-ExSQky4C.js → approval-BnLLCOG0.js} +277 -2934
  4. package/dist/browser.d.ts +327 -8
  5. package/dist/browser.js +1017 -51
  6. package/dist/{openUiLibrary-BKXW7Iwx-CWWBVOkE.js → dist-CTsxblSD.js} +496 -28
  7. package/dist/{echarts-De78wXqV.js → echarts-BE7oV_Dl.js} +1 -1
  8. package/dist/{env-8cY40DXB-CGnEVZby.js → env-Bj1MI2Ww.js} +1 -1
  9. package/dist/errors-BDZNpC13.js +22 -0
  10. package/dist/{eventTypes-FllCrX-Z-DNDeHWoG.js → eventTypes-Y07N8IAC.js} +14 -2
  11. package/dist/external-_ZRQe-V9.js +53 -0
  12. package/dist/governance.d.ts +15 -3
  13. package/dist/governance.js +86 -4
  14. package/dist/{index-iBm9tJL_.d.ts → index-CQYo4tcT.d.ts} +469 -10
  15. package/dist/{index-C3XdItd_.d.ts → index-CU2md8R1.d.ts} +26 -18
  16. package/dist/{index-DkvBhJQy.d.ts → index-Oc3H89TJ.d.ts} +204 -4
  17. package/dist/index.d.ts +4 -4
  18. package/dist/index.js +1001 -5
  19. package/dist/kind-DxgS8LM-.js +77 -0
  20. package/dist/linkedDocument-xNXF-z8n.js +94 -0
  21. package/dist/llm-B7lLH0ZI.js +1767 -0
  22. package/dist/mcp.d.ts +56 -3
  23. package/dist/mcp.js +75 -5
  24. package/dist/memoryArtifactStore-D6dLeY55.js +48 -0
  25. package/dist/miniChart-owdCdaw-.js +533 -0
  26. package/dist/node.d.ts +3 -3
  27. package/dist/node.js +110 -13
  28. package/dist/openUiLibrary-CY_ADoe0.js +30 -0
  29. package/dist/openUiSpecLang-DuOCdw9G.js +1849 -0
  30. package/dist/pathSecurity-B1owvJAF.js +65 -0
  31. package/dist/processSandboxEntry.js +5 -1
  32. package/dist/renderResult-D9Q-Vu2x.js +143 -0
  33. package/dist/{rolldown-runtime-BOF7iYI8.js → rolldown-runtime-BHkdefai.js} +1 -2
  34. package/dist/sandboxWorkerEntry.js +5 -1
  35. package/dist/{dist-Bev6i6Ip.js → skill-CAJMsLod.js} +44 -314
  36. package/dist/{skillVersionStore-D-qHk9ZE-DheTIwAB.d.ts → skillVersionStore-B24Jjjry-C4zomhMZ.d.ts} +14 -2
  37. package/dist/surface-DVGiCmwq.js +145 -0
  38. package/dist/testing.d.ts +1 -1
  39. package/dist/testing.js +64 -3
  40. package/dist/{types-DLctJep_-B5G4uk2u.d.ts → types-C3V6lAeO-BIf7UB2e.d.ts} +79 -4
  41. package/dist/types-TUydnxaj.js +78 -0
  42. package/dist/ui-react.d.ts +12 -5
  43. package/dist/ui-react.js +128548 -4729
  44. package/dist/ui-vue.d.ts +1 -1
  45. package/dist/ui-vue.js +11 -2
  46. package/dist/ui.d.ts +3 -3
  47. package/dist/ui.js +1254 -3
  48. package/dist/urlSafety-CiSuCJvX.js +65 -0
  49. package/dist/webSkillApi-DOOyz2G5.js +106 -0
  50. package/dist/{webskillLitCatalog-D_zCqeQF-C9lrvvMr.js → webskillLitCatalog-DSqVFQjK.js} +11 -3
  51. package/package.json +1 -1
  52. package/dist/catalogComponents-BgAJN0p8-CYEXSk45.js +0 -124384
  53. package/dist/client-BCM6Z3yq-qUQNkKrK.js +0 -7787
  54. package/dist/dist-DqcL6jKO.js +0 -3509
  55. package/dist/dist-DxyxmXPU-DGC-dpXf.js +0 -5621
  56. package/dist/dist-GK6dtjRv.js +0 -1493
  57. package/dist/memoryArtifactStore-52Zn9npI-LbCQaqyx.js +0 -86
  58. package/dist/stdio-CFMoANJJ-BxrTeXh7.js +0 -31
  59. package/dist/testing-WPTyXQYt.js +0 -142
  60. package/dist/types-WovEf4ED-CZSDiiBU.js +0 -6215
package/dist/browser.d.ts CHANGED
@@ -1,6 +1,6 @@
1
- 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";
2
- import { F as ExternalToolSource, Fn as WebSkillApi, Ht as ScriptExecutor, P as ExternalSkillProvider, S as BridgeResponse, Vn as bridgeError, Vt as ScriptExecutionContext, dr as parseBridgeRequest, it as NetworkPolicy, m as ApprovalScope, nt as LinkedDocumentReader, pn as ToolResult, un as ToolDefinition, x as BridgeRequest, y as BridgeCapabilities } from "./index-DkvBhJQy.js";
3
- 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-iBm9tJL_.js";
1
+ 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-C3V6lAeO-BIf7UB2e.js";
2
+ 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-Oc3H89TJ.js";
3
+ import { Ct as PerceptionCaptureOptions, Et as PerceptionResult, J as NestedFrameRef, Ot as PerceptionScopeInput, _t as PagePerceptionReader, ct as PageActionRequest, dt as PageActionTarget, ht as PagePerceptionPolicy, it as PageActionOutcome, nt as PageActionExecutor, ut as PageActionScopeInput, xt as PerceivedNode } from "./index-CQYo4tcT.js";
4
4
  //#region ../browser/dist/index.d.ts
5
5
  //#region src/fs/featureDetection.d.ts
6
6
  /** 检测当前环境是否可用 OPFS(navigator.storage.getDirectory) */
@@ -39,7 +39,7 @@ declare class OpfsProvider implements FileSystemProvider {
39
39
  *
40
40
  * 协议(宿主 ↔ Worker):
41
41
  * - 宿主 → Worker:{type:'load', id, source, networkPolicy?} 请求加载脚本定义
42
- * - 宿主 → Worker:{type:'execute', id, skillName, runId, source, args, networkPolicy?} 请求执行
42
+ * - 宿主 → Worker:{type:'execute', id, skillName, runId, source, args, networkPolicy?, documentSurface?} 请求执行
43
43
  * - Worker → 宿主:{type:'load-result', id, ok, definition?, error?}
44
44
  * - Worker → 宿主:{type:'execute-result', id, ok, value?, stdout, stderr, error?}
45
45
  * - Worker → 宿主:{type:'bridge', request} 能力桥 RPC(readReference/writeArtifact/confirm)
@@ -204,7 +204,10 @@ declare class BrowserWorkerScriptExecutor implements ScriptExecutor {
204
204
  */
205
205
  declare class IframeWorkerLike implements WorkerLike {
206
206
  #private;
207
- constructor(iframe: HTMLIFrameElement, hostWindow: Window, channelId: string);
207
+ constructor(iframe: HTMLIFrameElement, hostWindow: Window, channelId: string, readyTimeout?: {
208
+ readonly ms: number;
209
+ readonly documentUrl: string;
210
+ });
208
211
  get ready(): boolean;
209
212
  get channelId(): string;
210
213
  markReady(): void;
@@ -216,10 +219,43 @@ declare class IframeWorkerLike implements WorkerLike {
216
219
  terminate(): void;
217
220
  }
218
221
  /**
219
- * 创建 opaque iframe 沙箱 Worker:sandbox="allow-scripts" srcdoc iframe 承载 classic Worker。
222
+ * 静态沙箱页的中继脚本源码(分册 12 / FR-12.3)。
223
+ *
224
+ * 宿主把它落成一个独立文件并用 `<script src>` 引入——**不得内联**:
225
+ * sandbox 页虽允许 `unsafe-inline`,但外链能让「沙箱页脚本 = SDK 原样产物」在审计时可核对。
226
+ *
227
+ * 与 srcdoc 形态的两点区别,都源于「静态页在加载完时还不知道要跑什么」:
228
+ * - **引导源码**随宿主的 `sandbox-init` 消息到达,而不是内嵌在文档里;
229
+ * - **channelId** 由第一条来自 `parent` 的消息 latch。SDK 导出的是一份与宿主无关的源码,
230
+ * 不可能预知宿主这次生成的 id。latch 前先认 `event.source === parent`:少了这句,
231
+ * 任何把本页嵌进去的第三方 frame 都能抢先 latch 一个自己的 id,
232
+ * 让真正的宿主消息全部被丢弃——一个纯粹的拒绝服务面。
233
+ *
234
+ * 本源码不含任何扩展 API:sandbox 页拿不到它们(实证)。
235
+ * `ENVELOPE` 与宿主侧同源(同一个模块常量),两边各写一份字面量会在改名时静默失配。
236
+ * @experimental
237
+ */
238
+ declare const SANDBOX_PAGE_SCRIPT_SOURCE: string;
239
+ /**
240
+ * 静态沙箱文档形态的选项(分册 12 / FR-12.1)。
241
+ *
242
+ * MV3 下 srcdoc 继承父页 `extension_pages` CSP,内联脚本必被拒,
243
+ * 因此扩展宿主必须指定一个自带 sandbox CSP 的静态页。
244
+ * @experimental
245
+ */
246
+ interface IframeSandboxOptions {
247
+ /** 沙箱文档地址(扩展宿主传扩展内 URL);不给即沿用 srcdoc */
248
+ documentUrl?: string;
249
+ /** 承载 iframe 的文档,缺省为全局 `document` */
250
+ doc?: Document;
251
+ /** 等 `sandbox-ready` 的上限,缺省 10000。仅 `documentUrl` 形态有效 */
252
+ readyTimeoutMs?: number;
253
+ }
254
+ /**
255
+ * 创建 opaque iframe 沙箱 Worker:srcdoc(默认)或宿主指定的静态沙箱页承载 classic Worker。
220
256
  * 返回 IframeWorkerLike(协议与 blob Worker 完全一致:load/execute/bridge/network-blocked)。
221
257
  */
222
- declare function createIframeWorker(bootstrapSource: string, doc?: Document): IframeWorkerLike;
258
+ declare function createIframeWorker(bootstrapSource: string, options?: Document | IframeSandboxOptions): IframeWorkerLike;
223
259
  //#endregion
224
260
  //#region src/navigator.d.ts
225
261
  declare global {
@@ -366,6 +402,21 @@ interface CompressResult {
366
402
  */
367
403
  declare function compressImageToBudget(file: Blob, maxBytes: number): Promise<CompressResult>;
368
404
  //#endregion
405
+ //#region src/dom/promotion.d.ts
406
+ /**
407
+ * 非标可交互元素的识别与角色提升(0.14.0 分册 15)。
408
+ *
409
+ * 现代前端用 `div` / `span` 做按钮是常态,它们在无障碍树里全落到 `generic`,
410
+ * 于是拿不到句柄——模型读得到那几个字,却点不动。本模块补的就是这一段判定。
411
+ *
412
+ * 整套逻辑默认关闭,由 `createDomPerceptionReader` 的 `promoteRoles` 开启(D-15-1)。
413
+ */
414
+ /** 宿主声明的角色逃生舱:四种通用信号都不带的元素,由宿主点名(FR-15.6) */
415
+ interface RoleHint {
416
+ role: string;
417
+ selectors: readonly string[];
418
+ }
419
+ //#endregion
369
420
  //#region src/dom/perception.d.ts
370
421
  interface DomPerceptionReaderOptions {
371
422
  /** 选择器求值的根;缺省 `globalThis.document` */
@@ -375,6 +426,31 @@ interface DomPerceptionReaderOptions {
375
426
  * 它与感知范围分开声明:可读不等于可操作(FR-23.1)。
376
427
  */
377
428
  actionScope?: PageActionScopeInput;
429
+ /**
430
+ * 非标可交互元素的角色提升(分册 15)。缺省 `false`,行为与 0.13.0 逐字相同(D-15-1)。
431
+ *
432
+ * 它改的是「同一个 `include` 命中的元素判成什么角色」,**不是**「读哪些元素」:
433
+ * 范围外的元素不会因为提升而进快照。
434
+ */
435
+ promoteRoles?: boolean;
436
+ /**
437
+ * 宿主注入的行为事实:该元素是否挂过 click 类监听器(FR-15.1 信号 0)。
438
+ * 探针要改页面的 `EventTarget.prototype`,那是扩展的活;SDK 只认这个钩子(D-15-5)。
439
+ */
440
+ interactiveHint?: (element: Element) => boolean;
441
+ /**
442
+ * 逃生舱:四种通用信号都不带的元素,由宿主显式声明其角色(FR-15.6)。
443
+ * 性质与范围白名单相同——改它就是改模型的可操作面,只能在装配期声明。
444
+ */
445
+ roleHints?: readonly RoleHint[];
446
+ /**
447
+ * 嵌套帧自动下钻(分册 16)。缺省 `false`,行为与 0.13.0 逐字相同(D-16-2)。
448
+ *
449
+ * 开启后,范围内**未授权**的嵌套帧不再只给一句「没读」:有 http(s) 地址的进
450
+ * `PerceptionResult.nestedFrames` 交给外壳继续投递,无地址的同源帧就地内联。
451
+ * 0.13.0 D-18-3 的「不自动下钻」已被 0.14.0 分册 16 §0.1 推翻。
452
+ */
453
+ discoverNestedFrames?: boolean;
378
454
  }
379
455
  /** DOM 遍历是同步的;不取像时比 `PagePerceptionReader` 窄,调用方无需 await @experimental */
380
456
  interface DomPerceptionReader extends PagePerceptionReader {
@@ -431,6 +507,241 @@ type DomPageActionExecutor = PageActionExecutor;
431
507
  /** @experimental */
432
508
  declare function createDomPageActionExecutor(options: DomPageActionOptions): DomPageActionExecutor;
433
509
  //#endregion
510
+ //#region src/remote/types.d.ts
511
+ /**
512
+ * 跨上下文页面代理的传输端口(分册 13 / FR-13.1)。
513
+ *
514
+ * SDK 不关心底下是扩展消息、`MessagePort` 还是 WebSocket;
515
+ * 只要求一次请求对应一次应答,且请求 / 应答都能被 structured clone 搬运。
516
+ * @experimental
517
+ */
518
+ interface PageAgentTransport {
519
+ send(request: PageAgentRequest): Promise<PageAgentReply>;
520
+ }
521
+ /** @experimental */
522
+ type PageAgentRequest = {
523
+ type: 'perceive';
524
+ scope: PerceptionScopeInput;
525
+ capture?: PerceptionCaptureOptions;
526
+ } | {
527
+ type: 'execute';
528
+ request: PageActionRequest;
529
+ };
530
+ /**
531
+ * 应答。失败走 `error` 变体而**不是**让 `send()` reject:
532
+ * structured clone 不保留原型,跨上下文的 reject 到本地就是一个没有错误码的 `Error`。
533
+ * 显式回码,本地再重建 `WebSkillError`,错误码才能穿过边界。
534
+ * @experimental
535
+ */
536
+ type PageAgentReply = {
537
+ type: 'perceive-result';
538
+ result: PerceptionResult;
539
+ targets: readonly PageAgentTargetEntry[];
540
+ } | {
541
+ type: 'execute-result';
542
+ outcome: PageActionOutcome;
543
+ } | {
544
+ type: 'error';
545
+ code: string;
546
+ message: string;
547
+ };
548
+ /**
549
+ * 感知期随结果一并回传的句柄描述表(D-13-3);**不进模型上下文**。
550
+ *
551
+ * 不塞进 `PerceivedNode`:那会改 `@webskill/agent` 的公开契约,
552
+ * 且这些字段对本地形态毫无意义(本地执行器直接读 DOM)。
553
+ * @experimental
554
+ */
555
+ interface PageAgentTargetEntry {
556
+ ref: string;
557
+ role: string;
558
+ name?: string;
559
+ secret?: boolean;
560
+ frame?: string;
561
+ elevated?: boolean;
562
+ }
563
+ //#endregion
564
+ //#region src/remote/registry.d.ts
565
+ /**
566
+ * 感知期写入、执行期读取的句柄描述表(分册 13 / FR-13.3)。
567
+ *
568
+ * 由**宿主创建并同时交给 reader 和 executor**——两者共享同一个实例是本册的装配前提。
569
+ * 工厂单独导出就是为了让这件事在宿主代码里显式可见,
570
+ * 而不是藏在某个工厂内部让人以为「自己会连上」。
571
+ * @experimental
572
+ */
573
+ interface RemoteTargetRegistry {
574
+ /** 用新一批条目**整体替换**旧表 */
575
+ replace(entries: readonly PageAgentTargetEntry[]): void;
576
+ get(ref: string): PageActionTarget | undefined;
577
+ readonly size: number;
578
+ }
579
+ /** @experimental */
580
+ declare function createRemoteTargetRegistry(): RemoteTargetRegistry;
581
+ //#endregion
582
+ //#region src/remote/reader.d.ts
583
+ /** @experimental */
584
+ interface RemotePerceptionReaderOptions {
585
+ transport: PageAgentTransport;
586
+ /** 与执行器共享的句柄表;两者必须传同一个实例 */
587
+ targets: RemoteTargetRegistry;
588
+ /** 单次感知超时毫秒;缺省 10000 */
589
+ timeoutMs?: number;
590
+ }
591
+ /**
592
+ * 跨上下文的页面感知(分册 13 / FR-13.2)。
593
+ *
594
+ * 把句柄描述表写进 registry,**只把 `result` 返回给调用方**——
595
+ * 返回值就是标准 `PerceptionResult`,不夹带任何新字段(AC-13.2)。
596
+ * @experimental
597
+ */
598
+ declare function createRemotePerceptionReader(options: RemotePerceptionReaderOptions): PagePerceptionReader;
599
+ //#endregion
600
+ //#region src/remote/executor.d.ts
601
+ /** @experimental */
602
+ interface RemotePageActionExecutorOptions {
603
+ transport: PageAgentTransport;
604
+ /** 与 reader 共享的句柄表;两者必须传同一个实例 */
605
+ targets: RemoteTargetRegistry;
606
+ /** 单次执行超时毫秒;缺省 10000 */
607
+ timeoutMs?: number;
608
+ }
609
+ /**
610
+ * 跨上下文的页面操作执行器(分册 13 / FR-13.3)。
611
+ * @experimental
612
+ */
613
+ declare function createRemotePageActionExecutor(options: RemotePageActionExecutorOptions): PageActionExecutor;
614
+ //#endregion
615
+ //#region src/remote/handler.d.ts
616
+ /** @experimental */
617
+ interface PageAgentHandlerOptions {
618
+ /**
619
+ * 可操作范围。**由页面侧声明**,不接受请求方传入——
620
+ * 从请求里读它等于让 agent 自行声明自己能操作什么,是权限提升。
621
+ */
622
+ actionScope?: PageActionScopeInput;
623
+ document?: Document;
624
+ /** `attach` 的文件来源;必须由用户手势触发。不注入即 `attach` 一律按「用户取消」处理 */
625
+ pickFiles?: () => Promise<readonly File[] | undefined>;
626
+ /** 非标可交互元素的角色提升(分册 15);缺省关闭 */
627
+ promoteRoles?: boolean;
628
+ /** 宿主注入的 click 监听器事实(FR-15.1 信号 0) */
629
+ interactiveHint?: (element: Element) => boolean;
630
+ /** 宿主声明的角色逃生舱(FR-15.6) */
631
+ roleHints?: readonly RoleHint[];
632
+ /** 嵌套帧自动发现(分册 16);缺省关闭 */
633
+ discoverNestedFrames?: boolean;
634
+ }
635
+ /** @experimental */
636
+ interface PageAgentHandler {
637
+ handle(request: PageAgentRequest): Promise<PageAgentReply>;
638
+ }
639
+ /**
640
+ * 页面侧处理器(分册 13 / FR-13.7)。
641
+ *
642
+ * 必须是工厂而不是裸函数:`DomPerceptionReader` **是有状态的**——
643
+ * `resolve(ref)` 依赖上一次感知发出的句柄表,模态提升状态也跨调用累积。
644
+ * 每次请求新建 reader,`execute` 就永远 resolve 不到 `perceive` 发出的 ref。
645
+ *
646
+ * 它**不自己收发消息**:只做「请求进、应答出」。监听消息通道、判断消息是不是给自己的、
647
+ * 回不回 `true`——那些全是宿主的事,本包不得出现任何扩展 API。
648
+ * @experimental
649
+ */
650
+ declare function createPageAgentHandler(options?: PageAgentHandlerOptions): PageAgentHandler;
651
+ //#endregion
652
+ //#region src/remote/frameRouter.d.ts
653
+ /**
654
+ * 一次感知能铺开的上限(0.14.0 分册 16 FR-16.4)。
655
+ *
656
+ * 兜底的是**帧数与节点总量**,不是层数。0.13.0 D-18-8 用深度上限兜底,
657
+ * 前提是「路径由宿主写死」;自动发现一进来那个前提就没了:
658
+ * 三层的页面可能只有 5 个节点,两层的门户可能挂着 40 个 iframe。
659
+ * 层数是错的度量,总量才是。
660
+ * @experimental
661
+ */
662
+ interface FrameBudget {
663
+ maxFrames: number;
664
+ maxNodes: number;
665
+ }
666
+ /** @experimental */
667
+ declare const DEFAULT_FRAME_BUDGET: FrameBudget;
668
+ /**
669
+ * 一次投递的回执。
670
+ *
671
+ * `documentUrl` 是应答**实际来自**的文档地址,用于导航漂移判定:
672
+ * 投递地址是上一刻算出来的,那一帧完全可能在往返之间导航走。
673
+ * @experimental
674
+ */
675
+ interface FrameDelivery {
676
+ reply: PageAgentReply;
677
+ documentUrl: string;
678
+ }
679
+ /**
680
+ * 解析嵌套帧时宿主能拿到的上下文。
681
+ *
682
+ * `visited` 由路由器攒、由宿主读:去重需要比较地址,而地址对路由器是不透明的
683
+ * (D-11-1)。让宿主自己在 dispatcher 里存一份则解决不了生命周期——
684
+ * dispatcher 是长期对象,一次编排结束后没人通知它清空。
685
+ * @experimental
686
+ */
687
+ interface FrameResolveContext<A> {
688
+ /** 发现这个嵌套帧的那一帧的地址 */
689
+ readonly parent: A;
690
+ /** 本次感知已投递过的地址,按投递顺序 */
691
+ readonly visited: readonly A[];
692
+ }
693
+ /**
694
+ * 宿主实现的那一半(分册 11 FR-11.1):**寻址**。
695
+ *
696
+ * 地址类型 `A` 对路由器完全不透明:不比较、不序列化、不持久化,
697
+ * 只在同一次编排内原样传递。扩展宿主用帧号,`postMessage` 宿主用 URL,
698
+ * 两者不需要迁就同一个形状。
699
+ * @experimental
700
+ */
701
+ interface FrameDispatcher<A> {
702
+ /** 从哪里开始下钻 */
703
+ mainFrame(): A | Promise<A>;
704
+ /** 把一次请求送到某个地址 */
705
+ send(address: A, request: PageAgentRequest): Promise<FrameDelivery>;
706
+ /**
707
+ * 把某一帧报上来的嵌套帧引用换成可投递的地址。
708
+ *
709
+ * 解析不出(跨源、不可达、不在宿主白名单里、已经读过)时返回 `undefined`,
710
+ * 该帧被跳过并留说明,**不算错误**。这是帧可达性的唯一出口:
711
+ * SDK 不带任何缺省白名单,也不因为「导出了」就替宿主放行一帧(D-11-4)。
712
+ */
713
+ resolveNestedFrame(nested: NestedFrameRef, context: FrameResolveContext<A>): Promise<A | undefined> | A | undefined;
714
+ }
715
+ /** @experimental */
716
+ interface FrameRouterOptions<A> {
717
+ dispatcher: FrameDispatcher<A>;
718
+ budget?: Partial<FrameBudget>;
719
+ /**
720
+ * 主帧的帧名(D-11-3)。不给则主帧节点**不带** `frame`——
721
+ * 主帧就是「这个页面」,给它加一段前缀只会让每个节点都变吵。
722
+ * 主帧本身就是外壳里的一帧时(模型要能区分外壳与业务帧)才给。
723
+ */
724
+ mainFrameLabel?: string;
725
+ }
726
+ /** @experimental */
727
+ interface FrameRouter {
728
+ perceive(request: PageAgentRequest & {
729
+ type: 'perceive';
730
+ }): Promise<PageAgentReply>;
731
+ execute(request: PageAgentRequest & {
732
+ type: 'execute';
733
+ }): Promise<PageAgentReply>;
734
+ }
735
+ /**
736
+ * 逐帧下钻并汇总(分册 16 FR-16.2 / FR-16.3 / FR-16.4,分册 11 FR-11.2)。
737
+ *
738
+ * 编排本身与浏览器 API 无关:它只认 `PageAgentRequest` / `PageAgentReply`,
739
+ * 寻址全压在宿主实现的 `FrameDispatcher` 里。因此这个模块可以在 Service Worker
740
+ * 里实例化,也可以服务不按帧号寻址的宿主。
741
+ * @experimental
742
+ */
743
+ declare function createFrameRouter<A>(options: FrameRouterOptions<A>): FrameRouter;
744
+ //#endregion
434
745
  //#region src/dom/imageCapture.d.ts
435
746
  /**
436
747
  * 取像级别(0.6.0 FR-12.1)。裁决 D-3 已取消 L3 栅格化,只剩两级。
@@ -986,6 +1297,14 @@ declare const DOCUMENT_SURFACE_AUDIT_EVENT = "document.surface.open";
986
1297
  * 无 `allow-top-navigation` 改不了它的地址。
987
1298
  */
988
1299
  declare function openDocumentSurface(input: OpenDocumentInput, options: DocumentSurfaceOptions): Promise<WindowLike>;
1300
+ /**
1301
+ * 把 `openDocumentSurface` 柯里化成 `DocumentSurfaceHost`(0.15.0 分册 13 FR-13.3)。
1302
+ *
1303
+ * **只绑定选项,不新增任何逻辑**:体积上限、握手超时、`DOCUMENT_SURFACE_DECLINED`
1304
+ * 与审计事件全部沿用上面那一份实现(FR-13.5「逐条不变」的实现基础)。
1305
+ * @experimental
1306
+ */
1307
+ declare function createDocumentSurfaceHost(options: DocumentSurfaceOptions): DocumentSurfaceHost;
989
1308
  //#endregion
990
1309
  //#region src/viewer/shell.d.ts
991
1310
  /**
@@ -1062,4 +1381,4 @@ declare function watchBlockedResources(host: ViewerBlockedHost, notice: ViewerBl
1062
1381
  /** 提示文案的单一来源;判据直接引用,不各写一份字面量 */
1063
1382
  declare function blockedMessage(origins: readonly string[]): string;
1064
1383
  //#endregion
1065
- 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, XLSX_UNEXTRACTED, blockedMessage, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createBrowserChatbotHost, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createFetchLinkedDocumentReader, createIframeWorker, createLlmClient, deleteMemoryEncryptionKey, extractDocxText, extractXlsxText, extractZipWeb, generateMemoryEncryptionKey, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, missingPorts, openDocumentSurface, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startViewerShell, startWorkerRuntimeHost, viewerCspHeader, watchBlockedResources };
1384
+ 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_FRAME_BUDGET, 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, type FrameBudget, type FrameDelivery, type FrameDispatcher, type FrameResolveContext, type FrameRouter, type FrameRouterOptions, HOST_PORT_MATRIX, 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 PortApplicability, type PortReport, type PortSpec, type PortStatus, type RemotePageActionExecutorOptions, type RemotePerceptionReaderOptions, type RemoteTargetRegistry, type RoleHint, SANDBOX_PAGE_SCRIPT_SOURCE, 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, XLSX_UNEXTRACTED, blockedMessage, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createBrowserChatbotHost, createDocumentSurfaceHost, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createFetchLinkedDocumentReader, createFrameRouter, createIframeWorker, createLlmClient, createPageAgentHandler, createRemotePageActionExecutor, createRemotePerceptionReader, createRemoteTargetRegistry, deleteMemoryEncryptionKey, extractDocxText, extractXlsxText, extractZipWeb, generateMemoryEncryptionKey, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, missingPorts, openDocumentSurface, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startViewerShell, startWorkerRuntimeHost, viewerCspHeader, watchBlockedResources };