@dp-bohrium/widget-sdk 0.0.6 → 0.0.7

package/README.md

@@ -4,32 +4,48 @@ Widget 开发者 SDK。在生产 Widget Bundle 内使用 `createWidgetClient`：
 宣告 Bundle、接收转移过来的 `MessagePort`，并暴露共享的生命周期与能力协议，
 无需直接处理 `window.postMessage`。
 
-从 npmjs 安装（默认最新版）：
+## 环境要求
+
+| 项 | 要求 |
+| --- | --- |
+| Node.js | ≥ 20（仅构建期；产物运行在浏览器 iframe 内） |
+| 源码格式 | 纯 ESM，必须经打包器处理后交付 |
+| 运行环境 | 必须由 Bohrium Host 加载，脱离 Host 无法完成握手 |
+| 产物格式 | Host iframe 为 `sandbox="allow-scripts"` 且无 `allow-same-origin` 时，打成 classic script / IIFE（隔离源下 `type="module"` 需要 CORS） |
+
+## 安装
+
+写 Widget 装本包。Host 与控制面只消费协议类型，装
+[`@dp-bohrium/widget-contracts`](https://www.npmjs.com/package/@dp-bohrium/widget-contracts)
+即可。
 
 ```bash
+npm install @dp-bohrium/widget-sdk
 pnpm add @dp-bohrium/widget-sdk
+yarn add @dp-bohrium/widget-sdk
 ```
 
-Host 与控制面应继续只消费 `@dp-bohrium/widget-contracts`，不要安装本包。
+在自己的 `package.json` 里钉死精确 SemVer，不要用 `^` 或裸 `latest`。
+
+## 快速开始
 
 ```ts
 import { createWidgetClient } from "@dp-bohrium/widget-sdk";
 
 const widget = createWidgetClient({
-  // 填入已安装的 @dp-bohrium/widget-sdk 精确版本（npm view / package.json）
+  // 填已安装的精确版本，并与 manifest.json 的 widgetSdkVersion 写成同一个值。
   widgetSdkVersion: "REPLACE_WITH_INSTALLED_SDK_VERSION",
   async onInit(payload) {
-    // 使用 Host 下发的 locale、theme 与 capabilities 初始化。
-    console.log(payload.locale);
-    await Promise.resolve(); // 在此加载应用状态。
+    // Host 下发 locale、theme 与已授予的 capabilities。
+    await applyHostContext(payload.locale, payload.theme, payload.capabilities);
   },
   onRender(request) {
-    // 按所选 Slot 渲染完整快照。
-    console.log(request.slot);
+    // 按 Slot 渲染完整快照。
+    renderSlot(request.slot, request.content);
   },
   onDispose({ reason, deadlineMs }) {
-    // 释放本地定时器、订阅与 worker。
-    console.log(reason, deadlineMs);
+    // 释放定时器、订阅与 worker。
+    releaseLocalResources(reason, deadlineMs);
   },
 });
 
@@ -37,155 +53,100 @@ await widget.ready();
 widget.resize({ width: 600, height: 400 });
 ```
 
-## Host 托管的网络访问
+三条时序约定：
+
+- `ready()` 只在 `onInit` 返回（含其 Promise settle）之后才发给 Host，
+  `handshakeTimeoutMs` 同时约束这一步；
+- 初始化失败时，SDK 先报结构化 `onError`，再调 `onDispose`;
+- 若只提供 `onUpdate`，首帧完整 `render` 快照也会投递给 `onUpdate`。
+
+## 包入口
+
+| 入口 | 内容 | 用途 |
+| --- | --- | --- |
+| `.` | `createWidgetClient`、`PRESENTATION_CONFIRMATION_TIMEOUT_MS`，以及全部公开类型 | 生产 Widget |
+| `./testing` | `MemoryTransport`、`MockWidgetHost` | 单元测试 |
+| `./runtime` | 低层 `WidgetClient`、transport 与 bootstrap 常量 | 协议级集成 |
+| `./package.json` | 已安装包的元数据 | 工具读取版本。源码与 Manifest 的 `widgetSdkVersion` 写成同一个精确版本字符串 |
+
+根入口只导出两个运行时值，其余均为类型。`MessagePortTransport` 与 bootstrap 消息
+不属于普通 Widget API。
+
+## 能力
 
-在 Widget Manifest 中声明 `requestedCapabilities.network.fetch`，在 `ready()`
-完成后再调用类型化 facade。Widget 不会收到 Host 凭据，也不应直接调用浏览器
-`fetch`：
+每项能力都要在 Manifest 的 `requestedCapabilities` 里声明，并由 Host 实际 grant；
+缺任一侧，调用在 Widget 本地即被拒绝。所有能力调用都必须在 `ready()` 之后。
+
+下面五项是当前的全部能力。grant 名与 Manifest 申请键不一定同名 —— `ui.presentation`
+对应的申请键是 `requestedCapabilities.presentation`。
+
+| grant 名 | Manifest 申请键 | SDK 调用 |
+| --- | --- | --- |
+| `files.list` / `files.metadata` / `files.read` | `files` | `widget.requestCapability({ operation, input })` |
+| `events.read` | `events`（需列出 `topics`） | 拉取 `widget.subscribeEvents(…)` / `widget.onTool(…)` |
+| `actions.invoke` | `actions` | `widget.invokeAction(…)` |
+| `network.fetch` | `network` | `widget.network.fetch(…)` |
+| `ui.presentation` | `presentation` | `widget.present(…)` / `changePresentationSurface` / `focusPresentationBoundary` / `closePresentation` |
+
+五项共用同一套调用范式，掌握下面这一个就会调其余四个：
 
 ```ts
 const controller = new AbortController();
 const result = await widget.network.fetch(
-  {
-    url: "https://api.example.org/papers",
-    auth: "optional",
-    method: "GET",
-    headers: { accept: "application/json" },
-  },
+  { url: "https://api.example.org/papers", method: "GET", auth: "optional" },
   { signal: controller.signal, timeoutMs: 15_000 },
 );
 
 if (result.ok) {
   consume(result.data.status, result.data.headers, result.data.body);
 } else {
+  // 策略拒绝、用户拒绝、未授权都走这里，不是 throw。
   showNetworkFailure(result.reason, result.retryable);
 }
 ```
 
-是否弹窗、记住精确 Origin 授权、选择不透明凭据绑定、跟随重定向或拒绝，均由
-Host 决定。在未就绪、已 dispose，或当前没有 `network.fetch` grant 时，调用会在
-本地拒绝。中止与超时复用既有 MessageChannel 能力生命周期。
-`requestCapability` 仍可用于协议级集成，但 Widget 应用代码应优先使用
-`widget.network.fetch`。
-
-## Host 治理的面板呈现
-
-Panel Widget 可以请求 Host 以 workspace、floating 或 overlay 表面呈现当前面板。
-普通 `createWidgetClient()` 结果与低层 `WidgetClient` 上均可使用相同方法：
+跨能力的六条约定：
+
+- 失败以 `{ ok: false, reason, message, retryable }` 正常兑现；只有客户端超时、中止、
+  dispose 和畸形响应才 reject。
+- 中止与超时统一用 `{ signal, timeoutMs }`，复用既有 MessageChannel 能力生命周期。
+- Widget 永远拿不到 Host 凭据，也不应直接调用浏览器 `fetch`：是否弹窗、记住 Origin
+  授权、跟随重定向还是拒绝，全部由 Host 决定。
+- 呈现只是**请求**。Host 可能降级到别的表面，成功结果里的 `surface` 才是真实表面；
+  Widget 不能指定目标 Panel、身份、运行时 generation、坐标或层级。
+- 事件有两条路径，按需要选一条：`onEvent(handler)` 接收 Host 从当前 Runtime **主动
+  推送**的聚合事件，只按 `type` 分发，不依赖 Manifest Topic 或 `events.read` grant；
+  `subscribeEvents` / `onTool` 走兼容的**有界分页拉取**，带游标、可续读。
+- `subscribeEvents` / `onTool` 的所有订阅共享同一实例的 events 读预算，并各自遵守
+  topic 最小轮询间隔 —— 订阅越多，单个 topic 刷新越慢。游标只在 `onBatch` 成功后
+  提交，重新订阅需显式传回 `events.cursor`。工具 Hook 观察的是**已经发生的**服务端
+  事实，不是执行前拦截器。
+
+## 测试
 
 ```ts
-import { PRESENTATION_CONFIRMATION_TIMEOUT_MS } from "@dp-bohrium/widget-sdk";
-
-const presentationAbort = new AbortController();
-const result = await widget.present("floating", {
-  timeoutMs: PRESENTATION_CONFIRMATION_TIMEOUT_MS,
-  signal: presentationAbort.signal,
-});
-
-if (!result.ok) {
-  showPresentationDenial(result.reason, result.message);
-} else if ("surface" in result.data) {
-  // Host 可能回报不同的实际表面，例如紧凑模式下从 floating 降级到 overlay
-  // 或 workspace。
-  showCurrentSurface(result.data.surface);
-}
-
-await widget.changePresentationSurface("overlay");
-await widget.focusPresentationBoundary("forward");
-await widget.closePresentation();
+import { MockWidgetHost } from "@dp-bohrium/widget-sdk/testing";
 ```
 
-当 Host 授予带 `overlay` 表面的 `ui.presentation` 时，普通 client 还会安装跨源
-Panel overlay 的键盘协作：未处理、受信、非 composing 的 Escape 会请求
-`closePresentation()`；Tab 之后焦点离开 iframe 会请求
-`focusPresentationBoundary("forward" | "backward")`；iframe 内焦点移动不会发消息。
-有自定义焦点管理器的框架可直接调用类型化 helper。
-
-默认确认超时为 60 秒。可用 `timeoutMs` 覆盖，用 `signal` 取消本地等待。Host
-策略拒绝或用户拒绝会以 `{ ok: false, reason, message, retryable }` 正常兑现；
-客户端超时、中止、dispose 或畸形成功响应会 reject Promise。浏览器 resize、
-可见性、焦点与指针事件都不会被当成确认。
-
-这些方法只是提出呈现请求。grant、支持的表面、确认、紧凑模式降级与真实面板状态
-仍由 Host 最终裁决。`isTrusted` 与 `defaultPrevented` 只是 Widget 域内噪声过滤，
-不是授权：MessageChannel 能识别当前 iframe 实例，但不能证明物理按键或人类激活。
-Widget 不能指定目标 Panel、Host 选择器、身份、运行时 generation、坐标或层级。
-Host 在接受请求前必须复核当前实例、顶层 Overlay、焦点 epoch 与更高安全层。
-
-`ready()` 不会在 `onInit` 返回（或其 Promise settle）之前发给 Host。初始化失败时，
-SDK 会报告结构化 `onError`，再调用 `onDispose` 以便释放本地资源。
-`handshakeTimeoutMs` 也会在 Host 连接建立后约束该初始化步骤。
-
-若只提供了 `onUpdate`，首次完整 `render` 快照也会投递给 `onUpdate`。
-
-`WidgetClient` 提供框架无关的低层运行时接口。能力请求接受
-`{ timeoutMs, signal }`，应用生命周期钩子可取消在途读取、避免迟到结果。高级集成与
-协议级测试可从 `@dp-bohrium/widget-sdk/runtime` 使用。
-
-主入口暴露生产用 `createWidgetClient`。低层协议类与 bootstrap 常量见
-`@dp-bohrium/widget-sdk/runtime`；`MessagePortTransport` 与 bootstrap 消息不属于
-普通 Widget API。
-
-`@dp-bohrium/widget-sdk/testing` 提供 `MemoryTransport` 与 `MockWidgetHost`。
-Mock Host 负责 init/ready 时序、首帧 render 与 update 选择、resize 事件、能力
-adapter 响应与终态 dispose。它使用与生产 Host 相同的公开 contracts，但不等同于
-生产 iframe、CSP、授权或资源隔离保证。Schema 与类型校验以
-`@dp-bohrium/widget-contracts` 为准。
+`MockWidgetHost` 负责 init/ready 时序、首帧 render 与 update 选择、resize 事件、
+能力 adapter 响应与终态 dispose；`capabilityResult` 给出确定性的默认允许/拒绝，
+同时提供 `handleCapability` 时后者优先。`host.capabilityRequests` 返回有序的防御性
+拷贝，断言不会改动 Mock 状态。
 
-可用 `capabilityResult` 给出确定性的默认允许或拒绝；若同时提供
-`handleCapability`，后者仍是权威的高级处理器。`host.capabilityRequests` 返回有序的
-防御性拷贝快照，测试可检查请求而不改动 Mock Host 状态。
+它使用与生产 Host 相同的公开 contracts，但**不等同于**生产 iframe、CSP、授权或资源
+隔离保证。
 
-若 Host iframe 使用 `sandbox="allow-scripts"` 且没有 `allow-same-origin`，除非隔离
-源为 `type="module"` 提供 CORS，否则请将打包后的 Widget 以 classic script / IIFE
-加载。
-
-若 Host 发送畸形 Bridge 信封或载荷，transport 会报告结构化 `MESSAGE_INVALID`
-并关闭连接，不会让 Widget 继续等待一个 Host 仍视为活跃的连接。
-
-## 受授权的事件订阅与工具 Hook（本地候选）
-
-新增 `subscribeEvents`、`onTool` 和 `invokeAction`。Manifest 声明与 Host 实际
-grant 必须同时包含 topic/action；旧 Host 不会自动获得这些能力，发布时需一起升级
-contracts 与消费者。订阅类型从包根与 `/runtime` 导出。
-
-```ts
-const events = client.subscribeEvents({
-  topic: "jobs.progress",
-  onBatch(batch, { signal }) {
-    if (signal.aborted) return;
-    // 只应用本批真实事件；batch.reset 时替换旧状态。
-    renderProgress(batch.events);
-  },
-  onError: showSubscriptionError,
-});
-const hooks = client.onTool({
-  onToolCall: showStarted,
-  onToolResult: showCompleted,
-  onToolError: showFailed,
-  onToolCancelled: showCancelled,
-}, { onError: showSubscriptionError });
-const result = await client.invokeAction({
-  action: "tools.inspect",
-  idempotencyKey: crypto.randomUUID(),
-  arguments: { toolCallId },
-});
-const resumeCursor = events.cursor;
-events.unsubscribe();
-hooks.unsubscribe();
-```
+## 限制
 
-Hook 观察已经发生的服务端工具事实，不是执行前拦截器；不允许通过 iframe 回调改写
-参数、审批或控制 durable 执行。`tools.inspect` 是常见的只读动作
-provider 示例，返回工具身份和最新可读取状态；其他 action 由 Host/provider 显式实现并
-授权。SDK 不自动重试动作，也不把回调完成解释为工具执行完成。
+- SDK 不做授权决策，能力是否可用最终由 Host 判定。
+- `invokeAction` 不自动重试，回调完成也不代表工具执行完成。
+- `subscribeEvents` 的 `events.read` 是有界分页读取，不是 websocket；实时推送走
+  `onEvent`。当前版本没有单请求取消的 wire 消息：`unsubscribe` 会停止后续轮询并取消
+  本地等待，已发出的服务端读取可能完成，但结果被忽略。
+- Host 发来畸形 Bridge 信封或载荷时，transport 报结构化 `MESSAGE_INVALID` 并关闭
+  连接，不会让 Widget 悬等。
+- Schema 与类型校验以 `@dp-bohrium/widget-contracts` 为准。
 
-所有订阅共享实例的 events 请求预算，并各自遵守 topic 最小间隔。游标仅在
-`onBatch` 成功后提交；消费者异常、权限撤销和不可恢复的历史错误会关闭订阅并调用
-`onError`。`unsubscribe` 和 Host dispose 释放订阅、排队请求和本地在途等待，忽略
-迟到结果；异步回调需检查传入 signal 后再更新自己的状态。`closed` 表示订阅已关闭，
-并不等待用户未完成的回调结束。重新订阅时显式传入已保存 cursor。
+## 许可证
 
-每次 events.read 是有界、非阻塞读取；当前 V1 没有单请求取消 wire 消息，
-unsubscribe 会停止后续轮询并取消本地等待，已经发出的服务端读取可能完成但其结果被
-忽略。Host 实例卸载另通过既有 lease/AbortSignal 释放在途宿主请求。
+MIT。

package/dist/compatibility/testing.js

@@ -1,4 +1,4 @@
-import { n as MemoryTransport, t as ProtocolEndpoint } from "../protocol-endpoint-ZmZWaN92.js";
+import { n as MemoryTransport, t as ProtocolEndpoint } from "../protocol-endpoint-I78q3jVT.js";
 //#region src/runtime/mock-host.ts
 const widgetMessageTypes = /* @__PURE__ */ new Set([
 	"ready",

package/dist/index.js

@@ -1,2 +1,2 @@
-import { i as createWidgetClient, o as PRESENTATION_CONFIRMATION_TIMEOUT_MS } from "./runtime-Bva0ricl.js";
+import { i as createWidgetClient, o as PRESENTATION_CONFIRMATION_TIMEOUT_MS } from "./runtime-h-oTCwcs.js";
 export { PRESENTATION_CONFIRMATION_TIMEOUT_MS, createWidgetClient };

package/dist/{protocol-endpoint-ZmZWaN92.js → protocol-endpoint-I78q3jVT.js}

@@ -39,7 +39,7 @@ function isProtocolPayload(type, payload) {
 			const content = property(payload, "content");
 			return property(payload, "schemaVersion") === 1 && typeof property(payload, "requestId") === "string" && typeof property(payload, "instanceId") === "string" && typeof revision === "number" && Number.isSafeInteger(revision) && revision >= 1 && typeof property(payload, "slot") === "string" && typeof property(payload, "state") === "string" && isRecord(context) && isRecord(content);
 		}
-		case "event": return property(payload, "schemaVersion") === 1 && typeof property(payload, "id") === "string" && typeof property(payload, "occurredAt") === "string" && typeof property(payload, "sessionId") === "string" && typeof property(payload, "workflowId") === "string" && typeof property(payload, "topic") === "string" && typeof property(payload, "type") === "string" && isRecord(property(payload, "payload"));
+		case "event": return typeof property(payload, "type") === "string" && isRecord(property(payload, "payload"));
 		case "capability-result": return typeof property(payload, "requestId") === "string" && isRecord(property(payload, "result"));
 		case "error": return typeof property(payload, "code") === "string" && typeof property(payload, "phase") === "string" && typeof property(payload, "message") === "string" && typeof property(payload, "retryable") === "boolean" && typeof property(payload, "correlationId") === "string";
 		case "dispose": return typeof property(payload, "reason") === "string" && isFiniteNonNegative(property(payload, "deadlineMs"));

package/dist/runtime/bootstrap.d.ts

@@ -1,4 +1,4 @@
-import type { CapabilityRequest, CapabilityResult, InitPayload, PresentationCapabilityResult, PublicWidgetEvent, RenderRequest, WidgetError } from "@dp-bohrium/widget-contracts";
+import type { CapabilityRequest, CapabilityResult, InitPayload, PresentationCapabilityResult, RenderRequest, WidgetError, WidgetLiveEvent } from "@dp-bohrium/widget-contracts";
 import { type PresentationFocusDirection, type PresentationSurface, type WidgetCapabilityRequestOptions, type WidgetClientEvents, type WidgetClientState } from "./client.js";
 import { type SubscribeWidgetEventsOptions, type WidgetEventSubscription, type WidgetToolHooks } from "./events.js";
 import type { WidgetNetworkClient } from "./network.js";
@@ -26,7 +26,7 @@ export interface WidgetLiveEventContext {
     readonly signal: AbortSignal;
 }
 /** 由 Host 通过当前 MessageChannel 推送的实时 Workflow 事件处理器。 */
-export type WidgetLiveEventHandler = (event: PublicWidgetEvent, context: WidgetLiveEventContext) => void | Promise<void>;
+export type WidgetLiveEventHandler = (event: WidgetLiveEvent, context: WidgetLiveEventContext) => void | Promise<void>;
 export interface CreateWidgetClientOptions {
     widgetSdkVersion: string;
     hostApiVersion?: 1;
@@ -87,12 +87,10 @@ export declare class WidgetRuntimeClient {
     changePresentationSurface(surface: PresentationSurface, options?: WidgetCapabilityRequestOptions): Promise<PresentationCapabilityResult>;
     focusPresentationBoundary(direction: PresentationFocusDirection, options?: WidgetCapabilityRequestOptions): Promise<PresentationCapabilityResult>;
     subscribeEvents(options: SubscribeWidgetEventsOptions): WidgetEventSubscription;
-    /**
-     * 订阅 Host 从当前 Workflow 流实时推送的事件。
-     *
-     * Topic 授权由 Host 在发送前按 Manifest 与 Grant 过滤；这里不发起 HTTP 轮询。
-     */
+    /** 订阅 Host 从当前 Workflow 流实时推送的全部聚合事件。 */
     onEvent(handler: WidgetLiveEventHandler): () => void;
+    /** 订阅 Host 从当前 Workflow 流实时推送的指定聚合事件。 */
+    onEvent(eventName: string, handler: WidgetLiveEventHandler): () => void;
     onTool(hooks: WidgetToolHooks, options: Pick<SubscribeWidgetEventsOptions, "cursor" | "onError">): WidgetEventSubscription;
     invokeAction(input: Extract<CapabilityRequest, {
         operation: "actions.invoke";

package/dist/runtime/client.d.ts

@@ -1,4 +1,4 @@
-import type { CapabilityRequest, CapabilityResult, GrantedCapability, InitPayload, PresentationCapabilityRequest, PresentationCapabilityResult, PublicWidgetEvent, RenderRequest, WidgetError } from "@dp-bohrium/widget-contracts";
+import type { CapabilityRequest, CapabilityResult, GrantedCapability, InitPayload, PresentationCapabilityRequest, PresentationCapabilityResult, RenderRequest, WidgetError, WidgetLiveEvent } from "@dp-bohrium/widget-contracts";
 import { type WidgetNetworkClient } from "./network.js";
 import type { WidgetTransport } from "./transport.js";
 export type WidgetClientState = "created" | "waiting-ready" | "ready" | "disposed";
@@ -16,8 +16,8 @@ export interface WidgetClientEvents {
     onInit?: (payload: InitPayload) => void | PromiseLike<void>;
     onRender?: (request: RenderRequest, update: boolean) => void;
     onUpdate?: (request: RenderRequest) => void;
-    /** 接收 Host 从当前 Workflow 流主动推送的公开事件。 */
-    onEvent?: (event: PublicWidgetEvent) => void;
+    /** 接收 Host 从当前 Runtime 主动推送的聚合事件。 */
+    onEvent?: (event: WidgetLiveEvent) => void;
     onError?: (error: WidgetError) => void;
     onDispose?: (reason: string, deadlineMs?: number) => void;
 }

package/dist/runtime/index.js

@@ -1,3 +1,3 @@
-import { a as isWidgetHostConnectMessage, i as createWidgetClient, n as WIDGET_HOST_CONNECT, o as PRESENTATION_CONFIRMATION_TIMEOUT_MS, r as WidgetRuntimeClient, s as WidgetClient, t as WIDGET_BOOTSTRAP_READY } from "../runtime-Bva0ricl.js";
-import { i as isWidgetProtocolMessage, r as MessagePortTransport } from "../protocol-endpoint-ZmZWaN92.js";
+import { a as isWidgetHostConnectMessage, i as createWidgetClient, n as WIDGET_HOST_CONNECT, o as PRESENTATION_CONFIRMATION_TIMEOUT_MS, r as WidgetRuntimeClient, s as WidgetClient, t as WIDGET_BOOTSTRAP_READY } from "../runtime-h-oTCwcs.js";
+import { i as isWidgetProtocolMessage, r as MessagePortTransport } from "../protocol-endpoint-I78q3jVT.js";
 export { MessagePortTransport, PRESENTATION_CONFIRMATION_TIMEOUT_MS, WIDGET_BOOTSTRAP_READY, WIDGET_HOST_CONNECT, WidgetClient, WidgetRuntimeClient, createWidgetClient, isWidgetHostConnectMessage, isWidgetProtocolMessage };

package/dist/{runtime-Bva0ricl.js → runtime-h-oTCwcs.js}

@@ -1,4 +1,4 @@
-import { r as MessagePortTransport, t as ProtocolEndpoint } from "./protocol-endpoint-ZmZWaN92.js";
+import { r as MessagePortTransport, t as ProtocolEndpoint } from "./protocol-endpoint-I78q3jVT.js";
 //#region src/runtime/network.ts
 const failureReasons = /* @__PURE__ */ new Set([
 	"unsupported",
@@ -1023,16 +1023,18 @@ var WidgetRuntimeClient = class {
 		if (this.disposed || this.currentState === "disposed") subscription.unsubscribe();
 		return subscription;
 	}
-	/**
-	* 订阅 Host 从当前 Workflow 流实时推送的事件。
-	*
-	* Topic 授权由 Host 在发送前按 Manifest 与 Grant 过滤；这里不发起 HTTP 轮询。
-	*/
-	onEvent(handler) {
+	onEvent(eventNameOrHandler, maybeHandler) {
 		if (this.disposed) throw new Error("client is disposed");
-		this.liveEventHandlers.add(handler);
+		const handler = typeof eventNameOrHandler === "string" ? maybeHandler : eventNameOrHandler;
+		if (!handler) throw new TypeError("event handler is required");
+		const eventName = typeof eventNameOrHandler === "string" ? eventNameOrHandler : void 0;
+		const subscribedHandler = eventName === void 0 ? handler : (event, context) => {
+			if (event.type !== eventName) return;
+			return handler(event, context);
+		};
+		this.liveEventHandlers.add(subscribedHandler);
 		return () => {
-			this.liveEventHandlers.delete(handler);
+			this.liveEventHandlers.delete(subscribedHandler);
 		};
 	}
 	onTool(hooks, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dp-bohrium/widget-sdk",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Bohrium Widget 开发者 SDK：在 Widget Bundle 内与 Host 建立 Bridge，并暴露生命周期与能力协议。",
   "license": "MIT",
   "type": "module",
@@ -45,7 +45,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@dp-bohrium/widget-contracts": "0.0.6"
+    "@dp-bohrium/widget-contracts": "0.0.7"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.2.0",