@dp-bohrium/widget-sdk 0.0.7 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,33 @@
+# Widget SDK Agent 使用说明
+
+`@dp-bohrium/widget-sdk` 是 iframe 内 Widget 的运行时 SDK。Agent 先读取 `llms.txt`，再
+根据任务选择高层 Widget API、低层 Runtime API 或测试入口；不要自行实现 Bridge 握手。
+
+## 常用动作
+
+```bash
+pnpm add @dp-bohrium/widget-sdk
+```
+
+1. 用 `activate(context)` 实现 Widget；让 `bohr-widget` 生成 Host 入口。
+2. 在 Manifest 中声明所需 capability，再使用 `context.capabilities`、`context.files`、
+   `context.tasks`、`context.ui` 或 `context.network`。
+3. 在测试中使用 `@dp-bohrium/widget-sdk/testing` 的 `MockWidgetHost`；生产 Bundle 使用
+   根入口，不把 testing 入口打进产物。
+4. 低层协议集成只从 `@dp-bohrium/widget-sdk/runtime` 导入，并保留 contracts 的精确版本。
+
+## 错误恢复
+
+- 初始化或 Bridge 失败：记录结构化错误的 `code`、`phase`、`message`、`retryable`、
+  `correlationId`，先检查 Bundle、Host API、版本、握手和 channel，再决定是否重试。
+- 能力返回 `{ ok: false }`：根据 `reason` 和 `retryable` 分支处理；不要把拒绝当作异常，也
+  不要绕过 Host 直接访问凭据、文件路径或网络。
+- `MESSAGE_INVALID`、`CHANNEL_MISMATCH`、`CAPABILITY_UNDECLARED` 和
+  `CAPABILITY_DENIED` 先修 Manifest、Host grant 或协议版本，不要无限重试。
+- render/update 失败保留 `correlationId` 和当前 phase，确保界面仍能显示可恢复的空态。
+
+## 边界
+
+SDK 不授予权限、不上传或发布 Bundle、不决定 iframe/CSP 策略，也不保证脱离 Host 可以运行。
+`ok=true` 只表示当前调用被 Runtime/Host 接受；真实授权、渲染和生产绑定由 Host 与平台负责。
+发布包使用精确 SemVer；升级 SDK 时同步核对 contracts 版本和生成 Bundle 的 digest。

package/CHANGELOG.md

@@ -0,0 +1,110 @@
+# `@dp-bohrium/widget-sdk` 变更记录
+
+本文件只记录影响使用者的变更：运行时 API、事件订阅、Manifest 要求。
+
+## 0.2.0
+
+### 新增
+
+**1. Host 用户资料读取 facade**
+
+- 新增 `WidgetHostUserClient`（`createWidgetHostUserClient`），提供 `readProfile()` / `readEmail()` typed facade，内部仍走精确的 `host.user/profile.read` / `host.user/email.read` service.invoke。
+- 新增 `HostUserProfile`（`{ userId, displayName }`）、`HostUserEmail`（`{ email }`）及对应 Result 类型。
+- 无 grant 时仍在 iframe 内拒绝，不发送 Bridge request。
+
+## 0.1.0
+
+### 新增
+
+**1. 暴露受控文件下载、长任务观察和 UI 状态 API**
+
+- 新增 `context.files.download`、`context.tasks.watch` 和 `context.ui.state.read/write`，均受 Host grant、预算和作用域约束。
+
+**2. 暴露结构化 Tool Result envelope 类型**
+
+- SDK 类型和运行时辅助函数支持带状态、指标、产物引用、provenance、warning 与 missing 的结构化 Tool Result。
+
+说明：0.0.9 曾在 Git 中准备，但未创建发布 Tag 或进入 npm；本节变更作为新的兼容性边界随 0.1.0 发布。
+
+## 0.0.8
+
+### 修复
+
+- 与 `@dp-bohrium/widget-contracts` 0.0.8 保持版本一致。运行时 API、事件订阅与 Manifest 要求均无变化，从 0.0.7 升级无需改代码。
+
+说明：0.0.8 未单独发布；本节变更最终随 0.1.0 一并发布。
+
+## 0.0.7
+
+### 破坏性变更
+
+**1. onEvent 的事件载荷从 PublicWidgetEvent 变为 WidgetLiveEvent**
+
+新载荷只有 `type` 和 `payload` 两个字段。`schemaVersion`、`id`、`occurredAt`、`sessionId`、`workflowId`、`topic` 都不再下发，读这些字段的代码会失效。
+
+```ts
+// 0.0.6 及以前
+client.onEvent((event) => {
+  if (event.topic === "tools.lifecycle" && event.type === "tool-call") {
+    render(event.payload);
+  }
+});
+
+// 0.0.7 —— 按 type 分派，不再有 topic
+client.onEvent((event) => {
+  if (event.type === "tool-call") {
+    render(event.payload);
+  }
+});
+```
+
+需要 `sessionId` / `workflowId` 的，从 `init` 阶段拿到的上下文取，不要再从事件对象上读。
+
+**2. Manifest 的 widgetConfig.behaviors 移除，改为 widgetConfig.activationEvents**
+
+从对象数组改成字符串数组，保留旧字段的 Manifest 上传会被拒。完整迁移写法见 `@dp-bohrium/widget-contracts` 的变更记录。原先靠 `behaviors` 自动执行 `panel.open` 等 Host 动作的能力没有等价替代。
+
+### 新增
+
+- onEvent 新增按事件名订阅的重载，回调直接收到该类型的事件，不必再判断 event.type。
+
+  ```ts
+  client.onEvent("tool-call", (event) => render(event.payload));
+  ```
+
+  无参数形式仍然接收全部事件，行为不变。
+
+## 0.0.6
+
+### 新增
+
+- 支持接收 Host 通过 MessageChannel 主动推送的实时事件（`onEvent`），无需 HTTP 轮询。
+
+## 0.0.5
+
+### 新增
+
+- 支持消费事件驱动的 Widget 行为。
+
+## 0.0.4
+
+### 新增
+
+- Manifest 支持声明式地在 Session 启动时打开 Panel。
+
+## 0.0.3
+
+- 仅发布流程调整，无对外变更。
+
+## 0.0.2
+
+### 破坏性变更
+
+- 包迁移至 `@dp-bohrium` scope，旧 scope 不再发布新版本。
+
+## 0.0.1
+
+首个公开版本。
+
+- MessagePort Transport、Widget 生命周期、Host Bridge 能力。
+- Host 代理的网络请求能力。

package/README.md

@@ -1,8 +1,14 @@
 # @dp-bohrium/widget-sdk
 
-Widget 开发者 SDK。在生产 Widget Bundle 内使用 `createWidgetClient`：向 Host
-宣告 Bundle、接收转移过来的 `MessagePort`，并暴露共享的生命周期与能力协议，
-无需直接处理 `window.postMessage`。
+Agent 使用入口：先读 [`llms.txt`](./llms.txt) 获取文档索引，再读 [`AGENTS.md`](./AGENTS.md)
+获取安装、运行时调用和错误恢复规则。
+
+Widget 开发者 SDK。普通作者只实现 `activate(context)` 和可选的 `deactivate()`；CLI
+会生成 Widget Host 入口，负责向 Host 宣告 Bundle、接收转移过来的 `MessagePort`，并暴露共享的
+生命周期与能力协议。作者无需直接处理 `window.postMessage`，也无需手动启动插件。
+
+激活事件目录、`context.events` 与低层 `topic` 的边界以本包的 `AGENTS.md`、本 README
+和 `@dp-bohrium/widget-contracts` 中的类型与 Schema 为准。
 
 ## 环境要求
 
@@ -25,74 +31,165 @@ pnpm add @dp-bohrium/widget-sdk
 yarn add @dp-bohrium/widget-sdk
 ```
 
-在自己的 `package.json` 里钉死精确 SemVer，不要用 `^` 或裸 `latest`。
+需要在 TypeScript 中直接声明或在编辑器中解析 Manifest Schema 时，再把
+`@dp-bohrium/widget-contracts` 作为开发依赖安装；它是独立的类型/Schema 包，不需要通过
+`defineManifest()` 工厂获得提示。
+
+在自己的 `package.json` 里钉死精确 SemVer，不要用 `^` 或裸 `latest`。SDK 运行时会从已安装
+包自身读取版本，插件源码和 Manifest 不需要再次填写 SDK 版本。
 
 ## 快速开始
 
 ```ts
-import { createWidgetClient } from "@dp-bohrium/widget-sdk";
-
-const widget = createWidgetClient({
-  // 填已安装的精确版本，并与 manifest.json 的 widgetSdkVersion 写成同一个值。
-  widgetSdkVersion: "REPLACE_WITH_INSTALLED_SDK_VERSION",
-  async onInit(payload) {
-    // Host 下发 locale、theme 与已授予的 capabilities。
-    await applyHostContext(payload.locale, payload.theme, payload.capabilities);
-  },
-  onRender(request) {
-    // 按 Slot 渲染完整快照。
-    renderSlot(request.slot, request.content);
-  },
-  onDispose({ reason, deadlineMs }) {
-    // 释放定时器、订阅与 worker。
-    releaseLocalResources(reason, deadlineMs);
-  },
-});
-
-await widget.ready();
-widget.resize({ width: 600, height: 400 });
+import type { WidgetContext } from "@dp-bohrium/widget-sdk";
+
+export function activate(context: WidgetContext) {
+  context.render((request, renderContext) => {
+    renderSlot(request.slot, request.content, renderContext.phase);
+  });
+  context.events.on("tool-call-result", () => {
+    void context.ui.present("floating");
+  });
+}
 ```
 
+CLI 生成的 `src/widget-host.ts` 会调用平台入口 `runWidgetHost(widget)`。
+这借鉴 VS Code 的激活入口。最终模型按 Binding 建立一个 Extension Runtime，`activate(context)`
+在 Runtime 内只执行一次；工具、文件或面板目标是挂载到 Runtime 的 Surface Instance，拥有
+独立的快照和释放句柄，不会再次触发 `activate`。开发者实现 `activate(context)`，可选实现
+`deactivate()`；Widget Host/SDK 负责加载、等待初始化、报告启动失败和执行清理。普通插件
+代码不需要调用 `ready()`，也不应该写 `plugin.ready().catch(() => {})`。`whenReady` 只保留
+给测试和高级宿主编排；`whenDisposed` 可用于等待已完成激活插件的异步 `deactivate()`。
+停用不会等待一个永不结束的 `activate()`；若激活在停用后迟到完成，SDK 会在已 abort 的生命周期上补偿释放并调用一次 `deactivate()`，但这不再延长 `whenDisposed`。
+
+这是 SDK 的目标生命周期契约；当前 Widget Host 的动态加载仍由 Surface-bound Adapter 接线，
+Binding 级 Runtime Loader 尚未开放。插件可以按 Runtime/Surface 分层设计，但不能把当前版本
+当成“无界面必然已启动”的生产保证。
+
+`context.signal` 会在 Host 停用插件或 Bridge 断开时 `abort`。`context.render` 和 `context.events`
+会自动登记到当前插件生命周期；`subscriptions` 只用于
+第三方计时器、观察器或其它需要在停用时释放的资源。
+
 三条时序约定：
 
-- `ready()` 只在 `onInit` 返回（含其 Promise settle）之后才发给 Host，
+- `ready()` 只在 `activate(context)` 返回（含其 Promise settle）之后才发给 Host，
   `handshakeTimeoutMs` 同时约束这一步；
-- 初始化失败时，SDK 先报结构化 `onError`，再调 `onDispose`;
-- 若只提供 `onUpdate`，首帧完整 `render` 快照也会投递给 `onUpdate`。
+- 初始化失败时，SDK 先报结构化错误，再调用已登记的插件资源清理；成功激活后的释放会
+  最多调用一次 `deactivate()`，已完成激活的异步清理可通过 `whenDisposed` 等待；
+- `context.render` 首帧和更新都会收到完整快照，通过 `renderContext.phase` 区分。
+
+## 从 Manifest 到插件运行
+
+Manifest 是插件的静态声明，SDK 代码是隔离 iframe 内的运行时实现，Host 负责二者之间的生命周期编排。一个插件可以这样声明：
+
+```json
+{
+  "$schema": "@dp-bohrium/widget-contracts/schemas/widget-plugin-manifest.schema.json",
+  "name": "research",
+  "version": "1.0.0",
+  "entry": "src/widget.ts",
+  "displayName": "研究面板",
+  "description": "展示研究工具的结构化结果",
+  "activationEvents": ["session.start", "tool-call-result:ScholarSearch", "ui-tool-opened"],
+  "contributes": {
+    "widget": { "type": "panel", "id": "research", "surfaces": ["workspace", "floating"] }
+  },
+  "capabilities": {
+    "files": { "read": true },
+    "events": { "topics": ["tool-call-result", "workspace-file-opened"] }
+  }
+}
+```
+
+需要接管完整的会话右侧区域时，在同一个 Panel contribution 上声明结构性放置意图，并同时申请匹配的
+`ui.region` capability：
+
+```json
+{
+  "contributes": {
+    "widget": {
+      "type": "panel",
+      "id": "better-sidebar",
+      "placement": { "kind": "region", "region": "session.rightRail", "mode": "replace" }
+    }
+  },
+  "capabilities": {
+    "region": { "regions": ["session.rightRail"], "mode": "replace" }
+  }
+}
+```
+
+`placement` 只表达贡献点的结构性意图；区域租约、确认、几何、焦点、原生面板恢复和失败回退仍由 Host
+负责。没有匹配 capability 时，SDK 编译阶段直接拒绝清单。
+
+`activationEvents` 只决定 Host 何时创建插件运行时；它不授予事件读取权限，也不负责打开思考过程或某个面板。插件激活后通过 `context.events` 和 `context.render` 注册监听与渲染器。Host 会对每个事件和能力请求做白名单投影与授权，插件收到的事件可能是有限回放，也可能是实时事件。
+
+实现建议：事件处理器保持幂等，按 `toolCallId` 或 `requestId` 去重；不要从 iframe URL、DOM 或宿主绝对路径推断内部数据；当能力未授予时显示结构化空态并继续保留可渲染的主界面。声明但没有实际使用的能力会被 Host 记录为诊断信息，未声明能力的调用会被拒绝并结束当前 Bridge 会话。
+
+### 统一插件入口
+
+所有公开插件类型都使用同一个 `activate(context)` 约定。面板和文件预览由
+Manifest 的 `contributes.widget` 决定；运行时代码只认识统一的 `context.events`、
+`context.render`、`context.capabilities` 和 `context.ui`。首帧和后续快照通过
+`renderContext.phase` 区分，不需要维护两套回调。
+
+Manifest 的编辑器提示来自 `@dp-bohrium/widget-contracts` 发布的 JSON Schema 和
+TypeScript 类型，不依赖某个 `defineManifest` 工厂。构建工具调用
+`compileWidgetPluginManifest`，自动补齐 `schemaVersion`、`hostApiVersion`、SDK 版本和
+宿主加载字段；它会直接读取 Manifest 内的 `samples`，只有构建器从别处生成样例时
+才需要传入第二个参数。`createWidgetClient` 是协议级基础实现，不属于 Widget 作者 API；当前根入口只提供统一 Widget API，协议级代码应从
+`./runtime` 显式引入。
+
+受信任的内部 Host/协议测试仍可直接构造低层 Tool Result RenderRequest，但该能力不属于外部作者清单或公共示例。
+
+SDK 发布包会生成 `dist/index.d.ts` 与对应的 declaration map，并通过 `package.json` 的
+`types`/`exports` 暴露。插件安装 `@dp-bohrium/widget-sdk` 后，编辑器会直接获得
+`WidgetContext`、事件名、能力请求、渲染请求和生命周期返回值的类型提示；Manifest
+编辑器提示由 `@dp-bohrium/widget-contracts` 的 JSON Schema 和声明文件提供。
 
 ## 包入口
 
 | 入口 | 内容 | 用途 |
 | --- | --- | --- |
-| `.` | `createWidgetClient`、`PRESENTATION_CONFIRMATION_TIMEOUT_MS`，以及全部公开类型 | 生产 Widget |
+| `.` | `runWidgetHost`、`compileWidgetPluginManifest` 和全部公开类型 | 生成的生产 Bundle |
 | `./testing` | `MemoryTransport`、`MockWidgetHost` | 单元测试 |
 | `./runtime` | 低层 `WidgetClient`、transport 与 bootstrap 常量 | 协议级集成 |
-| `./package.json` | 已安装包的元数据 | 工具读取版本。源码与 Manifest 的 `widgetSdkVersion` 写成同一个精确版本字符串 |
+| `./package.json` | 已安装包的元数据 | SDK 和构建工具自动读取版本，作者无需复制版本字符串 |
+
+根入口只导出插件运行时和 Manifest 编译所需的少量值，其余均为类型。低层
+`MessagePortTransport` 与 bootstrap 消息不属于普通 Widget API。
 
-根入口只导出两个运行时值，其余均为类型。`MessagePortTransport` 与 bootstrap 消息
-不属于普通 Widget API。
+`runWidgetHost` 是生成的 `widget-host.ts` 使用的 Widget Host 启动边界；
+插件作者只维护 `widget.ts` 中的 `activate/deactivate`。
 
 ## 能力
 
-每项能力都要在 Manifest 的 `requestedCapabilities` 里声明，并由 Host 实际 grant；
-缺任一侧，调用在 Widget 本地即被拒绝。所有能力调用都必须在 `ready()` 之后。
+公开能力要在 Manifest 的 `capabilities` 里声明，并由 Host 实际 grant；
+`service.invoke` 需要由 Host binding 显式授权。缺任一侧，调用在 Widget 本地即被拒绝。
+所有能力调用都必须在 `ready()` 之后。
 
-下面五项是当前的全部能力。grant 名与 Manifest 申请键不一定同名 —— `ui.presentation`
-对应的申请键是 `requestedCapabilities.presentation`。
+下面列出的能力是当前 SDK 支持的能力。grant 名与 Manifest 申请键不一定同名 —— `ui.presentation`
+对应的作者侧申请键是 `capabilities.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` |
-
-五项共用同一套调用范式，掌握下面这一个就会调其余四个：
+| `files.list` / `files.metadata` / `files.read` | `files` | `context.capabilities.request({ operation, input })` |
+| `files.download` | `files.download` | `context.files.download({ file, suggestedName })` |
+| `events.read` | `events`（需列出 `topics`） | 低层分页订阅；`context.events.on(…)` 是 Host 主动推送，不需要该 grant |
+| `tasks.watch` | `tasks.watch` | `context.tasks.watch({ taskId, cursor, limit })` |
+| `ui.state` | `state`（`read` / `write`） | `context.ui.state.read(key)` / `write(key, value)` |
+| `actions.invoke` | `actions` | `context.capabilities.request({ operation: "actions.invoke", input })` |
+| `network.fetch` | `network` | `context.network.fetch(…)` |
+| `service.invoke` | 由 Host binding 显式授权 | `context.services.invoke({ service, action, payload })` |
+| `ui.presentation` | `presentation` | `context.ui.present(…)` / `changeSurface` / `close` |
+| `ui.region` | `region`（固定申请 `session.rightRail`） | `context.ui.region.acquire()` / `release()` |
+
+除 Host 主动推送事件外，其余能力共用同一套调用范式，掌握下面这一个就会调其余能力：
 
 ```ts
 const controller = new AbortController();
-const result = await widget.network.fetch(
+const result = await context.network.fetch(
   { url: "https://api.example.org/papers", method: "GET", auth: "optional" },
   { signal: controller.signal, timeoutMs: 15_000 },
 );
@@ -105,19 +202,30 @@ if (result.ok) {
 }
 ```
 
-跨能力的六条约定：
+跨能力约定：
 
 - 失败以 `{ ok: false, reason, message, retryable }` 正常兑现；只有客户端超时、中止、
   dispose 和畸形响应才 reject。
 - 中止与超时统一用 `{ signal, timeoutMs }`，复用既有 MessageChannel 能力生命周期。
 - Widget 永远拿不到 Host 凭据，也不应直接调用浏览器 `fetch`：是否弹窗、记住 Origin
   授权、跟随重定向还是拒绝，全部由 Host 决定。
+- `context.services` 仅在 Host binding 授予 `service.invoke` 后可用。可调用的服务、操作、请求/响应
+  大小和有效期由 Host 的授权策略决定；未获授权时调用会被拒绝。认证状态由宿主侧管理，SDK 只收发
+  业务 payload，不会把 Cookie、Bearer Token 或其他凭据放入 iframe。
+- `context.files.download` 只提交文件引用和建议文件名；Host 在用户确认后经宿主
+  Download Adapter 惰性打开内容源。Widget 不会收到源 URL、保存路径或凭据。
+- `context.tasks.watch` 只读取一次受限任务快照和事件页；调用方用返回的 cursor 继续轮询。
+  它不创建、调度或取消任务，服务端负责任务授权、脱敏和终态保留。
+- `context.ui.state` 只保存按 Widget + Session 隔离的 JSON UI 状态；Host 按 key、单值大小、总字节数和调用
+  频率限流。它不能保存任务执行、凭据、文件内容或 Workspace 权限状态。
+- 外部插件的工具结果场景通过 `tool-call-result` 事件作为可选运行时信号；内部 Host/协议测试仍可使用低层 Tool Result RenderRequest
+  或展示槽位。插件应把结果转换成自己的 Panel 数据，再通过 `context.render` 更新面板。
 - 呈现只是**请求**。Host 可能降级到别的表面，成功结果里的 `surface` 才是真实表面；
   Widget 不能指定目标 Panel、身份、运行时 generation、坐标或层级。
-- 事件有两条路径，按需要选一条：`onEvent(handler)` 接收 Host 从当前 Runtime **主动
-  推送**的聚合事件，只按 `type` 分发，不依赖 Manifest Topic 或 `events.read` grant；
-  `subscribeEvents` / `onTool` 走兼容的**有界分页拉取**，带游标、可续读。
-- `subscribeEvents` / `onTool` 的所有订阅共享同一实例的 events 读预算，并各自遵守
+- 高层插件 API 使用 `context.events.on(handler)` 接收 Host 从当前 Runtime **主动推送**的
+  聚合事件，只按 `type` 分发，不依赖 Manifest Topic 或 `events.read` grant。需要直接使用有界
+  分页读取时，从 `@dp-bohrium/widget-sdk/runtime` 使用 `subscribeEvents` / `onTool`。
+- 低层 `subscribeEvents` / `onTool` 的所有订阅共享同一实例的 events 读预算，并各自遵守
   topic 最小轮询间隔 —— 订阅越多，单个 topic 刷新越慢。游标只在 `onBatch` 成功后
   提交，重新订阅需显式传回 `events.cursor`。工具 Hook 观察的是**已经发生的**服务端
   事实，不是执行前拦截器。
@@ -139,9 +247,10 @@ import { MockWidgetHost } from "@dp-bohrium/widget-sdk/testing";
 ## 限制
 
 - SDK 不做授权决策，能力是否可用最终由 Host 判定。
+- `tasks.watch` 是有界观察协议，不是调度器、执行器或取消 API；任务状态和事件由服务端投影。
 - `invokeAction` 不自动重试，回调完成也不代表工具执行完成。
 - `subscribeEvents` 的 `events.read` 是有界分页读取，不是 websocket；实时推送走
-  `onEvent`。当前版本没有单请求取消的 wire 消息：`unsubscribe` 会停止后续轮询并取消
+  `onEvent`。当前版本没有单请求取消的独立协议消息：`unsubscribe` 会停止后续轮询并取消
   本地等待，已发出的服务端读取可能完成，但结果被忽略。
 - Host 发来畸形 Bridge 信封或载荷时，transport 报结构化 `MESSAGE_INVALID` 并关闭
   连接，不会让 Widget 悬等。

package/dist/index.d.ts

@@ -1,2 +1,7 @@
-export type { CreateWidgetClientOptions, PresentationFocusDirection, PresentationSurface, SubscribeWidgetEventsOptions, WidgetCapabilityRequestOptions, WidgetClientEvents, WidgetClientFactoryOptions, WidgetClientOptions, WidgetClientState, WidgetDisposeEvent, WidgetEventBatchContext, WidgetEventSubscription, WidgetHostConnectMessage, WidgetLiveEventContext, WidgetLiveEventHandler, WidgetMessagePort, WidgetNetworkClient, WidgetNetworkFetchResult, WidgetRuntimeWindow, WidgetSize, WidgetToolHooks, WidgetTransport, } from "./runtime/index.js";
-export { createWidgetClient, PRESENTATION_CONFIRMATION_TIMEOUT_MS, } from "./runtime/index.js";
+export type { WidgetActivationEvent, WidgetActivationEvents, WidgetContribution, WidgetEventName, WidgetFilePreviewContribution, WidgetPanelContribution, WidgetPluginContributions, WidgetPluginManifest, WidgetToolPhase, } from "@dp-bohrium/widget-contracts";
+export { isWidgetActivationEvent, isWidgetEventName, WIDGET_ACTIVATION_EVENTS, WIDGET_EVENT_NAMES, } from "@dp-bohrium/widget-contracts";
+export type { CompileWidgetPluginManifestOptions } from "./manifest.js";
+export { compileWidgetPluginManifest } from "./manifest.js";
+export type { HostUserEmail, HostUserEmailResult, HostUserProfile, HostUserProfileResult, WidgetHostUserClient, } from "./runtime/service.js";
+export type { FileDownloadCapabilityResult, TaskWatchCapabilityResult, UiStateReadCapabilityResult, UiStateWriteCapabilityResult, WidgetActivation, WidgetCapabilityApi, WidgetContext, WidgetDisposable, WidgetEventApi, WidgetFileApi, WidgetHandle, WidgetHostOptions, WidgetModule, WidgetRenderContext, WidgetRenderHandler, WidgetTaskApi, WidgetUiApi, WidgetUiStateApi, } from "./widget.js";
+export { runWidgetHost } from "./widget.js";

package/dist/index.js

@@ -1,2 +1,248 @@
-import { i as createWidgetClient, o as PRESENTATION_CONFIRMATION_TIMEOUT_MS } from "./runtime-h-oTCwcs.js";
-export { PRESENTATION_CONFIRMATION_TIMEOUT_MS, createWidgetClient };
+import { i as createWidgetClient, l as WIDGET_SDK_VERSION } from "./runtime-Dute9ozh.js";
+import { WIDGET_ACTIVATION_EVENTS, WIDGET_EVENT_NAMES, isWidgetActivationEvent, isWidgetEventName } from "@dp-bohrium/widget-contracts";
+//#region src/manifest.ts
+function compiledSlot(contribution) {
+	switch (contribution.type) {
+		case "panel": return {
+			type: "panel",
+			panelType: contribution.id,
+			...contribution.placement === void 0 ? {} : { placement: contribution.placement }
+		};
+		case "file-preview": return {
+			type: "file-preview",
+			extensions: [...contribution.extensions]
+		};
+	}
+}
+/**
+* 将开发者维护的插件清单编译为宿主可加载的宿主清单。
+*
+* 这是构建工具的边界函数，不是类型提示入口：作者直接编辑带 `$schema` 的 JSON，
+* SDK 版本从当前安装包读取，宿主入口默认落到 dist/widget.js，内部 slot 标识只在这里生成。
+*/
+function compileWidgetPluginManifest(manifest, options = {}) {
+	const samples = options.samples ?? manifest.samples;
+	if (!samples || samples.length === 0) throw new Error("Widget Plugin Manifest must provide at least one sample before packaging");
+	const contribution = manifest.contributes.widget;
+	if (contribution.type === "panel" && contribution.placement?.kind === "region" && (manifest.capabilities?.region?.mode !== contribution.placement.mode || !manifest.capabilities.region.regions.includes(contribution.placement.region))) throw new Error("A region Widget contribution must declare a matching region capability");
+	const activationEvents = manifest.activationEvents ? [...manifest.activationEvents] : void 0;
+	return {
+		name: manifest.name,
+		...manifest.description === void 0 ? {} : { description: manifest.description },
+		widgetConfig: {
+			schemaVersion: 1,
+			hostApiVersion: 1,
+			widgetSdkVersion: WIDGET_SDK_VERSION,
+			entry: options.hostEntry ?? "dist/widget.js",
+			slot: compiledSlot(manifest.contributes.widget),
+			...activationEvents === void 0 ? {} : { activationEvents },
+			...manifest.capabilities === void 0 ? {} : { requestedCapabilities: manifest.capabilities },
+			...manifest.runtime === void 0 ? {} : { runtime: manifest.runtime },
+			samples
+		}
+	};
+}
+//#endregion
+//#region src/lifetime.ts
+function createWidgetLifetime(onError) {
+	const controller = new AbortController();
+	const resources = /* @__PURE__ */ new Map();
+	const pending = /* @__PURE__ */ new Set();
+	let closePromise;
+	function run(callback) {
+		const task = Promise.resolve().then(callback).catch((error) => {
+			try {
+				onError(error);
+			} catch {}
+		});
+		pending.add(task);
+		task.then(() => pending.delete(task));
+		return task;
+	}
+	function add(resource) {
+		const existing = resources.get(resource);
+		if (existing) return existing;
+		let disposed;
+		const handle = { dispose() {
+			if (disposed) return disposed;
+			disposed = run(() => typeof resource === "function" ? resource() : resource.dispose());
+			return disposed;
+		} };
+		resources.set(resource, handle);
+		if (controller.signal.aborted) handle.dispose();
+		return handle;
+	}
+	return {
+		signal: controller.signal,
+		add,
+		close() {
+			if (closePromise) return closePromise;
+			controller.abort();
+			for (const resource of [...resources.values()].reverse()) resource.dispose();
+			closePromise = (async () => {
+				while (pending.size) await Promise.all([...pending]);
+			})();
+			return closePromise;
+		}
+	};
+}
+//#endregion
+//#region src/widget.ts
+/**
+* Generated Widget Host 的唯一运行入口。Widget 作者只导出 activate/deactivate，
+* 不直接调用此函数；CLI 生成的 widget-host.ts 负责调用它。
+*/
+function runWidgetHost(widget, options = {}) {
+	const client = createWidgetRuntime(typeof widget === "function" ? { activate: widget } : widget, options);
+	const whenReady = client.ready();
+	whenReady.catch((reason) => {
+		const error = toStartupError(reason);
+		if (options.onStartupError) {
+			options.onStartupError(error);
+			return;
+		}
+		console.error(`[Widget 启动失败] ${error.message}`, error);
+	});
+	return {
+		whenReady,
+		whenDisposed: client.disposed(),
+		state: client.state,
+		dispose: client.dispose
+	};
+}
+function createContext(client, payload, renderHandlers, lifetime) {
+	return {
+		instanceId: payload.instanceId,
+		locale: payload.locale,
+		theme: payload.theme,
+		signal: lifetime.signal,
+		capabilities: {
+			granted: payload.capabilities,
+			request: (request, options) => client.requestCapability(request, options)
+		},
+		files: { download: (input, options) => client.requestCapability({
+			operation: "files.download",
+			input
+		}, options) },
+		tasks: { watch: (input, options) => client.requestCapability({
+			operation: "tasks.watch",
+			input
+		}, options) },
+		network: client.network,
+		services: client.services,
+		hostUser: client.hostUser,
+		ui: {
+			state: {
+				read: (key, options) => client.requestCapability({
+					operation: "ui.state",
+					input: {
+						action: "read",
+						key
+					}
+				}, options),
+				write: (key, value, options) => client.requestCapability({
+					operation: "ui.state",
+					input: {
+						action: "write",
+						key,
+						value
+					}
+				}, options)
+			},
+			region: {
+				acquire: (region, options) => client.acquireRegion(region, options),
+				release: (options) => client.releaseRegion(options)
+			},
+			present: (surface, options) => client.present(surface, options),
+			close: (options) => client.closePresentation(options),
+			changeSurface: (surface, options) => client.changePresentationSurface(surface, options)
+		},
+		events: { on(handlerOrName, maybeHandler) {
+			const unsubscribe = typeof handlerOrName === "string" ? client.onEvent(handlerOrName, maybeHandler) : client.onEvent(handlerOrName);
+			return lifetime.add(unsubscribe);
+		} },
+		subscriptions: { add(registration) {
+			lifetime.add(registration);
+		} },
+		render(handler) {
+			renderHandlers.add(handler);
+			return lifetime.add({ dispose: () => {
+				renderHandlers.delete(handler);
+			} });
+		},
+		resize: (width, height) => client.resize(width, height)
+	};
+}
+function createWidgetRuntime(module, options = {}) {
+	let client;
+	const renderHandlers = /* @__PURE__ */ new Set();
+	const reportCleanupError = (error) => options.onCleanupError?.(toStartupError(error));
+	const lifetime = createWidgetLifetime(reportCleanupError);
+	let activation;
+	let activationCompleted = false;
+	let disposed = false;
+	let deactivation;
+	let disposal;
+	let resolveDisposed;
+	const disposedPromise = new Promise((resolve) => {
+		resolveDisposed = resolve;
+	});
+	function runDeactivation() {
+		if (deactivation) return deactivation;
+		deactivation = Promise.resolve().then(() => module.deactivate?.()).catch((error) => {
+			reportCleanupError(error);
+		});
+		return deactivation;
+	}
+	function dispose() {
+		if (disposal) return;
+		disposed = true;
+		const cleanup = lifetime.close();
+		renderHandlers.clear();
+		disposal = (async () => {
+			await cleanup;
+			if (activationCompleted) await runDeactivation();
+		})().catch(reportCleanupError).finally(resolveDisposed);
+	}
+	client = createWidgetClient({
+		...options,
+		events: {
+			...options.events,
+			onInit(payload) {
+				const context = createContext(client, payload, renderHandlers, lifetime);
+				activation = Promise.resolve().then(async () => {
+					if (lifetime.signal.aborted) return;
+					const registration = await module.activate(context);
+					if (registration !== void 0) {
+						const resource = lifetime.add(registration);
+						if (lifetime.signal.aborted) await resource.dispose();
+					}
+					activationCompleted = true;
+					if (disposed) runDeactivation();
+				});
+				return activation;
+			},
+			onRender(request, update) {
+				const renderContext = {
+					phase: update ? "update" : "initial",
+					signal: lifetime.signal
+				};
+				for (const handler of [...renderHandlers]) try {
+					Promise.resolve(handler(request, renderContext)).catch(() => {});
+				} catch {}
+			},
+			onDispose: dispose
+		}
+	});
+	return {
+		ready: () => client.ready(),
+		disposed: () => disposedPromise,
+		state: () => client.currentState,
+		dispose: () => client.dispose()
+	};
+}
+function toStartupError(reason) {
+	return reason instanceof Error ? reason : new Error("Widget 启动失败", { cause: reason });
+}
+//#endregion
+export { WIDGET_ACTIVATION_EVENTS, WIDGET_EVENT_NAMES, compileWidgetPluginManifest, isWidgetActivationEvent, isWidgetEventName, runWidgetHost };

package/dist/lifetime.d.ts

@@ -0,0 +1,12 @@
+/** Guest 内单次启动的资源所有权；异步启动迟到的资源也必须立即释放。 */
+export interface LifetimeResource {
+    dispose(): void | PromiseLike<void>;
+}
+export interface LifetimeRegistration {
+    dispose(): Promise<void>;
+}
+export declare function createWidgetLifetime(onError: (error: unknown) => void): {
+    signal: AbortSignal;
+    add: (resource: LifetimeResource | (() => void | PromiseLike<void>)) => LifetimeRegistration;
+    close(): Promise<void>;
+};

package/dist/manifest.d.ts

@@ -0,0 +1,13 @@
+import type { WidgetManifest, WidgetPluginManifest } from "@dp-bohrium/widget-contracts";
+export interface CompileWidgetPluginManifestOptions {
+    readonly samples?: NonNullable<WidgetPluginManifest["samples"]>;
+    /** Host bundle entry. CLI supplies this after the project is built. */
+    readonly hostEntry?: string;
+}
+/**
+ * 将开发者维护的插件清单编译为宿主可加载的宿主清单。
+ *
+ * 这是构建工具的边界函数，不是类型提示入口：作者直接编辑带 `$schema` 的 JSON，
+ * SDK 版本从当前安装包读取，宿主入口默认落到 dist/widget.js，内部 slot 标识只在这里生成。
+ */
+export declare function compileWidgetPluginManifest(manifest: WidgetPluginManifest, options?: CompileWidgetPluginManifestOptions): WidgetManifest;

package/dist/runtime/bootstrap.d.ts

@@ -1,9 +1,12 @@
-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 { CapabilityRequest, CapabilityResult, InitPayload, PresentationCapabilityResult, RegionCapabilityResult, RenderRequest, WidgetError, WidgetLiveEvent } from "@dp-bohrium/widget-contracts";
+import { type PresentationFocusDirection, type PresentationSurface, type RegionName, 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";
+import { type WidgetHostUserClient, type WidgetServiceClient } from "./service.js";
+import { WIDGET_SDK_VERSION } from "./version.js";
 export declare const WIDGET_BOOTSTRAP_READY: "widget-bootstrap-ready";
 export declare const WIDGET_HOST_CONNECT: "widget-host-connect";
+export { WIDGET_SDK_VERSION };
 export interface WidgetHostConnectMessage {
     type: typeof WIDGET_HOST_CONNECT;
     protocolVersion: 1;
@@ -27,8 +30,10 @@ export interface WidgetLiveEventContext {
 }
 /** 由 Host 通过当前 MessageChannel 推送的实时 Workflow 事件处理器。 */
 export type WidgetLiveEventHandler = (event: WidgetLiveEvent, context: WidgetLiveEventContext) => void | Promise<void>;
+export type WidgetLiveEventName = WidgetLiveEvent["type"];
 export interface CreateWidgetClientOptions {
-    widgetSdkVersion: string;
+    /** 低层协议字段；Widget Host 会从已安装 SDK 自动读取 SDK 版本。 */
+    widgetSdkVersion?: string;
     hostApiVersion?: 1;
     handshakeTimeoutMs?: number;
     capabilityTimeoutMs?: number;
@@ -56,6 +61,8 @@ export declare function isWidgetHostConnectMessage(value: unknown): value is Wid
  */
 export declare class WidgetRuntimeClient {
     readonly network: WidgetNetworkClient;
+    readonly services: WidgetServiceClient;
+    readonly hostUser: WidgetHostUserClient;
     private readonly runtimeWindow;
     private readonly options;
     private readonly events;
@@ -85,12 +92,14 @@ export declare class WidgetRuntimeClient {
     present(surface: PresentationSurface, options?: WidgetCapabilityRequestOptions): Promise<PresentationCapabilityResult>;
     closePresentation(options?: WidgetCapabilityRequestOptions): Promise<PresentationCapabilityResult>;
     changePresentationSurface(surface: PresentationSurface, options?: WidgetCapabilityRequestOptions): Promise<PresentationCapabilityResult>;
+    acquireRegion(region: RegionName, options?: WidgetCapabilityRequestOptions): Promise<RegionCapabilityResult>;
+    releaseRegion(options?: WidgetCapabilityRequestOptions): Promise<RegionCapabilityResult>;
     focusPresentationBoundary(direction: PresentationFocusDirection, options?: WidgetCapabilityRequestOptions): Promise<PresentationCapabilityResult>;
     subscribeEvents(options: SubscribeWidgetEventsOptions): WidgetEventSubscription;
     /** 订阅 Host 从当前 Workflow 流实时推送的全部聚合事件。 */
     onEvent(handler: WidgetLiveEventHandler): () => void;
     /** 订阅 Host 从当前 Workflow 流实时推送的指定聚合事件。 */
-    onEvent(eventName: string, handler: WidgetLiveEventHandler): () => void;
+    onEvent(eventName: WidgetLiveEventName, 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, RenderRequest, WidgetError, WidgetLiveEvent } from "@dp-bohrium/widget-contracts";
+import type { CapabilityRequest, CapabilityResult, GrantedCapability, InitPayload, PresentationCapabilityRequest, PresentationCapabilityResult, RegionCapabilityRequest, RegionCapabilityResult, 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";
@@ -26,16 +26,22 @@ export interface WidgetCapabilityRequestOptions {
     signal?: AbortSignal;
 }
 export declare const PRESENTATION_CONFIRMATION_TIMEOUT_MS = 60000;
+export declare const REGION_CONFIRMATION_TIMEOUT_MS = 60000;
 type SurfacePresentationInput = Extract<PresentationCapabilityRequest["input"], {
     surface: unknown;
 }>;
 type FocusBoundaryPresentationInput = Extract<PresentationCapabilityRequest["input"], {
     action: "focus-boundary";
 }>;
+export type RegionCapabilityInput = RegionCapabilityRequest["input"];
 export type PresentationSurface = SurfacePresentationInput["surface"];
 export type PresentationFocusDirection = FocusBoundaryPresentationInput["direction"];
+export type RegionName = Extract<RegionCapabilityInput, {
+    region: unknown;
+}>["region"];
 type PresentationRequest = (request: CapabilityRequest, options: WidgetCapabilityRequestOptions) => Promise<CapabilityResult>;
 export declare function hasOverlayPresentationGrant(capabilities: readonly GrantedCapability[]): boolean;
+export declare function requestRegionCapability(request: PresentationRequest, capabilityRequest: RegionCapabilityRequest, options?: WidgetCapabilityRequestOptions): Promise<RegionCapabilityResult>;
 export declare function requestPresentationCapability(request: PresentationRequest, capabilityRequest: PresentationCapabilityRequest, options?: WidgetCapabilityRequestOptions): Promise<PresentationCapabilityResult>;
 export declare class WidgetClient {
     readonly network: WidgetNetworkClient;
@@ -66,6 +72,8 @@ export declare class WidgetClient {
     present(surface: PresentationSurface, options?: WidgetCapabilityRequestOptions): Promise<PresentationCapabilityResult>;
     closePresentation(options?: WidgetCapabilityRequestOptions): Promise<PresentationCapabilityResult>;
     changePresentationSurface(surface: PresentationSurface, options?: WidgetCapabilityRequestOptions): Promise<PresentationCapabilityResult>;
+    acquireRegion(region: RegionName, options?: WidgetCapabilityRequestOptions): Promise<RegionCapabilityResult>;
+    releaseRegion(options?: WidgetCapabilityRequestOptions): Promise<RegionCapabilityResult>;
     focusPresentationBoundary(direction: PresentationFocusDirection, options?: WidgetCapabilityRequestOptions): Promise<PresentationCapabilityResult>;
     dispose(): void;
     private finishDispose;

package/dist/runtime/index.d.ts

@@ -1,8 +1,10 @@
-export type { CreateWidgetClientOptions, WidgetClientFactoryOptions, WidgetDisposeEvent, WidgetHostConnectMessage, WidgetLiveEventContext, WidgetLiveEventHandler, WidgetRuntimeWindow, WidgetSize, } from "./bootstrap.js";
-export { createWidgetClient, isWidgetHostConnectMessage, WIDGET_BOOTSTRAP_READY, WIDGET_HOST_CONNECT, WidgetRuntimeClient, } from "./bootstrap.js";
-export type { PresentationFocusDirection, PresentationSurface, WidgetCapabilityRequestOptions, WidgetClientEvents, WidgetClientOptions, WidgetClientState, } from "./client.js";
-export { PRESENTATION_CONFIRMATION_TIMEOUT_MS, WidgetClient, } from "./client.js";
+export type { RegionCapabilityResult } from "@dp-bohrium/widget-contracts";
+export type { CreateWidgetClientOptions, WidgetClientFactoryOptions, WidgetDisposeEvent, WidgetHostConnectMessage, WidgetLiveEventContext, WidgetLiveEventHandler, WidgetLiveEventName, WidgetRuntimeWindow, WidgetSize, } from "./bootstrap.js";
+export { createWidgetClient, isWidgetHostConnectMessage, WIDGET_BOOTSTRAP_READY, WIDGET_HOST_CONNECT, WIDGET_SDK_VERSION, WidgetRuntimeClient, } from "./bootstrap.js";
+export type { PresentationFocusDirection, PresentationSurface, RegionName, WidgetCapabilityRequestOptions, WidgetClientEvents, WidgetClientOptions, WidgetClientState, } from "./client.js";
+export { PRESENTATION_CONFIRMATION_TIMEOUT_MS, REGION_CONFIRMATION_TIMEOUT_MS, WidgetClient, } from "./client.js";
 export type { SubscribeWidgetEventsOptions, WidgetEventBatchContext, WidgetEventSubscription, WidgetToolHooks, } from "./events.js";
 export type { WidgetNetworkClient, WidgetNetworkFetchResult, } from "./network.js";
+export type { HostUserEmail, HostUserEmailResult, HostUserProfile, HostUserProfileResult, WidgetHostUserClient, WidgetServiceClient, WidgetServiceInvokeInput, WidgetServiceInvokeResult, } from "./service.js";
 export type { WidgetMessagePort, WidgetTransport } from "./transport.js";
 export { isWidgetProtocolMessage, MessagePortTransport, } from "./transport.js";

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-h-oTCwcs.js";
+import { a as isWidgetHostConnectMessage, c as WidgetClient, i as createWidgetClient, l as WIDGET_SDK_VERSION, n as WIDGET_HOST_CONNECT, o as PRESENTATION_CONFIRMATION_TIMEOUT_MS, r as WidgetRuntimeClient, s as REGION_CONFIRMATION_TIMEOUT_MS, t as WIDGET_BOOTSTRAP_READY } from "../runtime-Dute9ozh.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 };
+export { MessagePortTransport, PRESENTATION_CONFIRMATION_TIMEOUT_MS, REGION_CONFIRMATION_TIMEOUT_MS, WIDGET_BOOTSTRAP_READY, WIDGET_HOST_CONNECT, WIDGET_SDK_VERSION, WidgetClient, WidgetRuntimeClient, createWidgetClient, isWidgetHostConnectMessage, isWidgetProtocolMessage };

package/dist/runtime/service.d.ts

@@ -0,0 +1,47 @@
+import type { CapabilityRequest, CapabilityResult, JsonValue } from "@dp-bohrium/widget-contracts";
+import type { WidgetCapabilityRequestOptions, WidgetClientState } from "./client.js";
+export type WidgetServiceInvokeInput = Extract<CapabilityRequest, {
+    operation: "service.invoke";
+}>["input"];
+export type WidgetServiceInvokeResult = Readonly<{
+    ok: true;
+    data: JsonValue;
+}> | Extract<CapabilityResult, {
+    ok: false;
+}>;
+export interface WidgetServiceClient {
+    invoke(input: WidgetServiceInvokeInput, options?: WidgetCapabilityRequestOptions): Promise<WidgetServiceInvokeResult>;
+}
+export interface HostUserProfile {
+    readonly userId: string;
+    readonly displayName: string;
+}
+export interface HostUserEmail {
+    readonly email: string | null;
+}
+export type HostUserProfileResult = Readonly<{
+    ok: true;
+    data: HostUserProfile;
+}> | Extract<CapabilityResult, {
+    ok: false;
+}>;
+export type HostUserEmailResult = Readonly<{
+    ok: true;
+    data: HostUserEmail;
+}> | Extract<CapabilityResult, {
+    ok: false;
+}>;
+export interface WidgetHostUserClient {
+    readProfile(options?: WidgetCapabilityRequestOptions): Promise<HostUserProfileResult>;
+    readEmail(options?: WidgetCapabilityRequestOptions): Promise<HostUserEmailResult>;
+}
+interface Dependencies {
+    readonly state: () => WidgetClientState;
+    readonly grant: () => Extract<import("@dp-bohrium/widget-contracts").GrantedCapability, {
+        name: "service.invoke";
+    }> | undefined;
+    readonly request: (request: CapabilityRequest, options?: WidgetCapabilityRequestOptions) => Promise<CapabilityResult>;
+}
+export declare function createWidgetServiceClient(dependencies: Dependencies): WidgetServiceClient;
+export declare function createWidgetHostUserClient(services: WidgetServiceClient): WidgetHostUserClient;
+export {};

package/dist/runtime/version.d.ts

@@ -0,0 +1,2 @@
+/** 从当前安装的 SDK package.json 读取版本，插件作者不需要重复填写。 */
+export declare const WIDGET_SDK_VERSION: string;

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

@@ -1,4 +1,9 @@
 import { r as MessagePortTransport, t as ProtocolEndpoint } from "./protocol-endpoint-I78q3jVT.js";
+//#endregion
+//#region src/runtime/version.ts
+/** 从当前安装的 SDK package.json 读取版本，插件作者不需要重复填写。 */
+const WIDGET_SDK_VERSION = "0.2.0";
+//#endregion
 //#region src/runtime/network.ts
 const failureReasons = /* @__PURE__ */ new Set([
 	"unsupported",
@@ -77,6 +82,7 @@ function invalidResult() {
 //#endregion
 //#region src/runtime/client.ts
 const PRESENTATION_CONFIRMATION_TIMEOUT_MS = 6e4;
+const REGION_CONFIRMATION_TIMEOUT_MS = 6e4;
 const presentationSurfaces = /* @__PURE__ */ new Set([
 	"workspace",
 	"floating",
@@ -226,6 +232,41 @@ function assertPresentationResult(input, result) {
 	}
 	if (!valid) throw new Error(`presentation protocol error: invalid success result for ${action}`);
 }
+function assertRegionResult(input, result) {
+	if (!isRecord$1(result) || !Object.hasOwn(result, "ok")) throw new Error(`region protocol error: invalid result for ${input.action}`);
+	if (property$1(result, "ok") === false) {
+		const message = property$1(result, "message");
+		if (hasExactKeys$1(result, [
+			"ok",
+			"reason",
+			"message",
+			"retryable"
+		]) && isCapabilityFailureReason(property$1(result, "reason")) && typeof message === "string" && message.length > 0 && typeof property$1(result, "retryable") === "boolean") return;
+		throw new Error(`region protocol error: invalid result for ${input.action}`);
+	}
+	if (!hasExactKeys$1(result, ["ok", "data"])) throw new Error(`region protocol error: invalid success result for ${input.action}`);
+	const data = property$1(result, "data");
+	const leaseId = isRecord$1(data) ? property$1(data, "leaseId") : void 0;
+	if (!(isRecord$1(data) && hasExactKeys$1(data, input.action === "acquire" ? [
+		"action",
+		"region",
+		"mode",
+		"leaseId"
+	] : [
+		"action",
+		"region",
+		"mode"
+	]) && property$1(data, "action") === input.action && property$1(data, "region") === "session.rightRail" && property$1(data, "mode") === "replace" && (input.action !== "acquire" || typeof leaseId === "string" && leaseId.length > 0))) throw new Error(`region protocol error: invalid success result for ${input.action}`);
+}
+function requestRegionCapability(request, capabilityRequest, options) {
+	return request(capabilityRequest, {
+		...options,
+		timeoutMs: options?.timeoutMs ?? 6e4
+	}).then((result) => {
+		assertRegionResult(capabilityRequest.input, result);
+		return result;
+	});
+}
 function requestPresentationCapability(request, capabilityRequest, options) {
 	return request(capabilityRequest, {
 		...options,
@@ -393,6 +434,21 @@ var WidgetClient = class {
 			}
 		}, options);
 	}
+	acquireRegion(region, options) {
+		return requestRegionCapability((request, requestOptions) => this.requestCapability(request, requestOptions), {
+			operation: "ui.region",
+			input: {
+				action: "acquire",
+				region
+			}
+		}, options);
+	}
+	releaseRegion(options) {
+		return requestRegionCapability((request, requestOptions) => this.requestCapability(request, requestOptions), {
+			operation: "ui.region",
+			input: { action: "release" }
+		}, options);
+	}
 	focusPresentationBoundary(direction, options) {
 		if (!this.overlayPresentationGranted) return Promise.reject(/* @__PURE__ */ new Error("Overlay presentation is not granted for focus cooperation"));
 		return requestPresentationCapability((request, requestOptions) => this.requestCapability(request, requestOptions), {
@@ -790,6 +846,63 @@ function createPresentationKeyboardAdapter(options) {
 	} };
 }
 //#endregion
+//#region src/runtime/service.ts
+function createWidgetServiceClient(dependencies) {
+	return Object.freeze({ invoke(input, options) {
+		const state = dependencies.state();
+		if (state === "disposed") return Promise.reject(/* @__PURE__ */ new Error("client is disposed"));
+		if (state !== "ready") return Promise.reject(/* @__PURE__ */ new Error("Widget service is not ready"));
+		if (!(dependencies.grant()?.services.find((entry) => entry.service === input.service))?.actions.includes(input.action)) return Promise.reject(/* @__PURE__ */ new Error("Widget service is not granted"));
+		return dependencies.request({
+			operation: "service.invoke",
+			input
+		}, options).then(validateServiceResult);
+	} });
+}
+function createWidgetHostUserClient(services) {
+	return Object.freeze({
+		readProfile(options) {
+			return services.invoke({
+				service: "host.user",
+				action: "profile.read",
+				payload: null
+			}, options).then((result) => validateHostUserResult(result, isHostUserProfile));
+		},
+		readEmail(options) {
+			return services.invoke({
+				service: "host.user",
+				action: "email.read",
+				payload: null
+			}, options).then((result) => validateHostUserResult(result, isHostUserEmail));
+		}
+	});
+}
+function validateHostUserResult(result, validate) {
+	if (result.ok === false) return result;
+	if (!validate(result.data)) throw new Error("service protocol error: invalid Host user result");
+	return {
+		ok: true,
+		data: result.data
+	};
+}
+function isHostUserProfile(value) {
+	return isExactRecord(value, ["userId", "displayName"]) && typeof value["userId"] === "string" && typeof value["displayName"] === "string";
+}
+function isHostUserEmail(value) {
+	return isExactRecord(value, ["email"]) && (typeof value["email"] === "string" || value["email"] === null);
+}
+function isExactRecord(value, keys) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const actualKeys = Object.keys(value);
+	return actualKeys.length === keys.length && keys.every((key) => actualKeys.includes(key));
+}
+function validateServiceResult(result) {
+	if (!result || typeof result !== "object" || Array.isArray(result)) throw new Error("service protocol error: invalid result");
+	if (result.ok === false) return result;
+	if (result.ok !== true || !("data" in result)) throw new Error("service protocol error: invalid result");
+	return result;
+}
+//#endregion
 //#region src/runtime/bootstrap.ts
 const WIDGET_BOOTSTRAP_READY = "widget-bootstrap-ready";
 const WIDGET_HOST_CONNECT = "widget-host-connect";
@@ -889,6 +1002,8 @@ function cloneGrantedCapabilities(capabilities) {
 */
 var WidgetRuntimeClient = class {
 	network;
+	services;
+	hostUser;
 	runtimeWindow;
 	options;
 	events;
@@ -939,6 +1054,12 @@ var WidgetRuntimeClient = class {
 			return this.requireClient().network.fetch(input, requestOptions);
 		} };
 		this.network = Object.freeze(network);
+		this.services = createWidgetServiceClient({
+			state: () => this.currentState,
+			grant: () => this.capabilities.find((capability) => capability.name === "service.invoke"),
+			request: (request, requestOptions) => this.requestCapability(request, requestOptions)
+		});
+		this.hostUser = createWidgetHostUserClient(this.services);
 		this.readyPromise = new Promise((resolve, reject) => {
 			this.resolveReady = resolve;
 			this.rejectReady = reject;
@@ -1005,6 +1126,21 @@ var WidgetRuntimeClient = class {
 			}
 		}, options);
 	}
+	acquireRegion(region, options) {
+		return requestRegionCapability((request, requestOptions) => this.requestCapability(request, requestOptions), {
+			operation: "ui.region",
+			input: {
+				action: "acquire",
+				region
+			}
+		}, options);
+	}
+	releaseRegion(options) {
+		return requestRegionCapability((request, requestOptions) => this.requestCapability(request, requestOptions), {
+			operation: "ui.region",
+			input: { action: "release" }
+		}, options);
+	}
 	focusPresentationBoundary(direction, options) {
 		return this.readyPromise.then(() => this.requireClient().focusPresentationBoundary(direction, options));
 	}
@@ -1101,7 +1237,7 @@ var WidgetRuntimeClient = class {
 			const clientOptions = {
 				transport: new MessagePortTransport(port),
 				channelId: event.data.channelId,
-				widgetSdkVersion: this.options.widgetSdkVersion,
+				widgetSdkVersion: this.options.widgetSdkVersion ?? WIDGET_SDK_VERSION,
 				initialPayload: event.data.initPayload,
 				...this.options.hostApiVersion === void 0 ? {} : { hostApiVersion: this.options.hostApiVersion },
 				...this.options.capabilityTimeoutMs === void 0 ? {} : { capabilityTimeoutMs: this.options.capabilityTimeoutMs },
@@ -1157,4 +1293,4 @@ function createWidgetClient(options) {
 	return new WidgetRuntimeClient(options);
 }
 //#endregion
-export { isWidgetHostConnectMessage as a, createWidgetClient as i, WIDGET_HOST_CONNECT as n, PRESENTATION_CONFIRMATION_TIMEOUT_MS as o, WidgetRuntimeClient as r, WidgetClient as s, WIDGET_BOOTSTRAP_READY as t };
+export { isWidgetHostConnectMessage as a, WidgetClient as c, createWidgetClient as i, WIDGET_SDK_VERSION as l, WIDGET_HOST_CONNECT as n, PRESENTATION_CONFIRMATION_TIMEOUT_MS as o, WidgetRuntimeClient as r, REGION_CONFIRMATION_TIMEOUT_MS as s, WIDGET_BOOTSTRAP_READY as t };

package/dist/widget.d.ts

@@ -0,0 +1,157 @@
+import type { CapabilityRequest, CapabilityResult, FileDownloadResult, FileReference, GrantedCapability, RegionCapabilityResult, RenderRequest, TaskObservationBatch, Theme, UiStateResult, UiStateWriteResult, WidgetEventName, WidgetLiveEvent } from "@dp-bohrium/widget-contracts";
+import { type CreateWidgetClientOptions, type RegionName, type WidgetClientFactoryOptions, type WidgetClientState, type WidgetLiveEventContext, type WidgetLiveEventHandler } from "./runtime/index.js";
+import type { WidgetNetworkClient } from "./runtime/network.js";
+import type { WidgetHostUserClient, WidgetServiceClient } from "./runtime/service.js";
+export interface WidgetDisposable {
+    dispose(): void | Promise<void>;
+}
+export type WidgetDisposeRegistration = WidgetDisposable | (() => void | Promise<void>);
+export interface WidgetRenderContext {
+    readonly phase: "initial" | "update";
+    readonly signal: AbortSignal;
+}
+export type WidgetRenderHandler = (request: RenderRequest, context: WidgetRenderContext) => void | PromiseLike<void>;
+export interface WidgetEventApi {
+    on(handler: WidgetLiveEventHandler): WidgetDisposable;
+    on<T extends WidgetEventName>(eventName: T, handler: (event: WidgetLiveEvent & {
+        readonly type: T;
+    }, context: WidgetLiveEventContext) => void | Promise<void>): WidgetDisposable;
+}
+export interface WidgetCapabilityApi {
+    readonly granted: readonly GrantedCapability[];
+    request(request: CapabilityRequest, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<CapabilityResult>;
+}
+export interface WidgetFileApi {
+    /** 请求 Host 在用户确认后通过宿主 Download Adapter 保存文件。 */
+    download(input: {
+        readonly file: FileReference;
+        readonly suggestedName: string;
+    }, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<FileDownloadCapabilityResult>;
+}
+export type FileDownloadCapabilityResult = {
+    readonly ok: true;
+    readonly data: FileDownloadResult;
+} | Extract<CapabilityResult, {
+    readonly ok: false;
+}>;
+export interface WidgetTaskApi {
+    /**
+     * 读取一次受 Host 限制的任务快照和事件页。调用方使用返回的 cursor
+     * 继续轮询；此 API 不创建、调度或取消任务。
+     */
+    watch(input: {
+        readonly taskId: string;
+        readonly cursor?: string;
+        readonly limit?: number;
+    }, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<TaskWatchCapabilityResult>;
+}
+export type TaskWatchCapabilityResult = {
+    readonly ok: true;
+    readonly data: TaskObservationBatch;
+} | Extract<CapabilityResult, {
+    readonly ok: false;
+}>;
+export interface WidgetUiStateApi {
+    read(key: string, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<UiStateReadCapabilityResult>;
+    write(key: string, value: import("@dp-bohrium/widget-contracts").JsonValue, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<UiStateWriteCapabilityResult>;
+}
+export type UiStateReadCapabilityResult = {
+    readonly ok: true;
+    readonly data: UiStateResult;
+} | Extract<CapabilityResult, {
+    readonly ok: false;
+}>;
+export type UiStateWriteCapabilityResult = {
+    readonly ok: true;
+    readonly data: UiStateWriteResult;
+} | Extract<CapabilityResult, {
+    readonly ok: false;
+}>;
+export interface WidgetUiRegionApi {
+    acquire(region: RegionName, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<RegionCapabilityResult>;
+    release(options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<RegionCapabilityResult>;
+}
+export interface WidgetUiApi {
+    readonly state: WidgetUiStateApi;
+    readonly region: WidgetUiRegionApi;
+    present(surface: "workspace" | "floating" | "overlay", options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<CapabilityResult>;
+    close(options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<CapabilityResult>;
+    changeSurface(surface: "workspace" | "floating" | "overlay", options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<CapabilityResult>;
+}
+export interface WidgetContext {
+    readonly instanceId: string;
+    readonly locale: string;
+    readonly theme: Theme;
+    /** Widget Host 的生命周期信号；Host 停用或 Bridge 断开时会 abort。 */
+    readonly signal: AbortSignal;
+    readonly capabilities: WidgetCapabilityApi;
+    readonly files: WidgetFileApi;
+    readonly tasks: WidgetTaskApi;
+    readonly network: WidgetNetworkClient;
+    /** 低层 service.invoke 入口；保留给自定义 Host service。 */
+    readonly services: WidgetServiceClient;
+    /** 经过 Host 独立授权的公共用户资料入口。 */
+    readonly hostUser: WidgetHostUserClient;
+    readonly ui: WidgetUiApi;
+    readonly events: WidgetEventApi;
+    readonly subscriptions: {
+        add(registration: WidgetDisposeRegistration): void;
+    };
+    render(handler: WidgetRenderHandler): WidgetDisposable;
+    resize(width: number, height: number): void;
+}
+export type WidgetActivation = (context: WidgetContext) => void | WidgetDisposeRegistration | PromiseLike<WidgetDisposeRegistration | void>;
+export interface WidgetHostOptions extends Omit<CreateWidgetClientOptions, "widgetSdkVersion" | "events" | "onInit" | "onRender" | "onUpdate" | "onEvent" | "onDispose"> {
+    readonly events?: Pick<NonNullable<WidgetClientFactoryOptions["events"]>, "onError">;
+    /** Widget Host 启动失败时的统一处理入口。 */
+    readonly onStartupError?: (error: Error) => void;
+    /** 停用或资源释放错误，诊断失败不会影响其它资源释放。 */
+    readonly onCleanupError?: (error: Error) => void;
+}
+export interface WidgetModule {
+    activate: WidgetActivation;
+    deactivate?: () => void | PromiseLike<void>;
+}
+export interface WidgetHandle {
+    /** 供测试、开发工具和 Host 编排等待激活完成。 */
+    readonly whenReady: Promise<void>;
+    /** Host 释放 Guest 后完成；包含已完成激活插件的异步 deactivate 清理。 */
+    readonly whenDisposed: Promise<void>;
+    readonly state: () => WidgetClientState;
+    dispose(): void;
+}
+/**
+ * Generated Widget Host 的唯一运行入口。Widget 作者只导出 activate/deactivate，
+ * 不直接调用此函数；CLI 生成的 widget-host.ts 负责调用它。
+ */
+export declare function runWidgetHost(widget: WidgetModule | WidgetActivation, options?: WidgetHostOptions): WidgetHandle;

package/llms.txt

@@ -0,0 +1,24 @@
+# @dp-bohrium/widget-sdk
+
+> Agent 读取索引：本包提供 Widget 的 `activate(context)` 运行时、Bridge 生命周期、能力
+> API、测试 Host 和低层 Runtime 入口。
+
+## 先读
+
+- [AGENTS.md](./AGENTS.md)：安装、入口选择、错误恢复和安全边界。
+- [README.md](./README.md)：快速开始、Manifest、能力和生命周期说明。
+- [package.json](./package.json)：精确版本、exports 和 Node 要求。
+
+## 选择入口
+
+- 生产 Widget：`@dp-bohrium/widget-sdk`
+- 单元测试：`@dp-bohrium/widget-sdk/testing`
+- 协议级集成：`@dp-bohrium/widget-sdk/runtime`
+- 配套类型和 Schema：`@dp-bohrium/widget-contracts`
+
+## 使用原则
+
+- 先在 Manifest 声明 capability，再等待 Host grant。
+- 用 `WidgetError` 的 `code/phase/retryable/correlationId` 诊断启动、渲染和能力失败。
+- `ok=false` 的能力结果是可处理状态，不要直接重试或绕过 Host。
+- SDK 本地通过不等于 iframe 已真实渲染、Bundle 已发布或 Agent 已绑定。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dp-bohrium/widget-sdk",
-  "version": "0.0.7",
+  "version": "0.2.0",
   "description": "Bohrium Widget 开发者 SDK：在 Widget Bundle 内与 Host 建立 Bridge，并暴露生命周期与能力协议。",
   "license": "MIT",
   "type": "module",
@@ -38,6 +38,9 @@
   "files": [
     "dist",
     "README.md",
+    "AGENTS.md",
+    "llms.txt",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "sideEffects": false,
@@ -45,7 +48,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@dp-bohrium/widget-contracts": "0.0.7"
+    "@dp-bohrium/widget-contracts": "0.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.2.0",