@dp-bohrium/widget-sdk 0.1.0 → 0.3.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

@@ -2,6 +2,32 @@
 
 本文件只记录影响使用者的变更：运行时 API、事件订阅、Manifest 要求。
 
+## 0.3.0
+
+### 破坏性变更
+
+**1. RenderRequest 与 content 删除旧字段：slot 改为 contribution、panelType 改为 id**
+
+- 已发布的 0.2.0 运行时仍读取 `request.slot`。本版改为用 `request.contribution` 收窄 `request.content`；`request.slot` 不再存在。
+- `content.panelType` 改为 `content.id`，其余 `content` 的 `slot` 改为 `contribution`。
+- `compileWidgetPluginManifest` 生成的宿主清单字段由 `widgetConfig.slot` 改为 `widgetConfig.contribution`；作者 Manifest 写法不变。
+
+### 修复
+
+**2. 同步公开类型文档**
+
+- SDK 与 contracts 锁定同一版本，公开类型说明与 schema 一致。widget-cli 单独以 `0.1.0` 发布，不进入这次 SDK Tag。
+
+## 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
 
 ### 新增

package/README.md

@@ -1,11 +1,14 @@
 # @dp-bohrium/widget-sdk
 
+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` 的边界见
-[Widget 激活事件与事件查询](../../docs/design/widget-activation-events-zh.md)。
+激活事件目录、`context.events` 与低层 `topic` 的边界以本包的 `AGENTS.md`、本 README
+和 `@dp-bohrium/widget-contracts` 中的类型与 Schema 为准。
 
 ## 环境要求
 
@@ -42,16 +45,26 @@ import type { WidgetContext } from "@dp-bohrium/widget-sdk";
 
 export function activate(context: WidgetContext) {
   context.render((request, renderContext) => {
-    renderSlot(request.slot, request.content, renderContext.phase);
+    renderContribution(request.contribution, request.content, renderContext.phase);
+  });
+  context.events.on("tool-call-result", () => {
+    void context.ui.present("floating");
   });
-  context.events.on("tool-call-result", (event) => showToolResult(event.payload));
 }
 ```
 
 CLI 生成的 `src/widget-host.ts` 会调用平台入口 `runWidgetHost(widget)`。
-这与 VS Code 的激活入口一致：开发者实现 `activate(context)`，可选实现 `deactivate()`；
-Widget Host/SDK 负责加载、等待初始化、报告启动失败和执行清理。普通插件代码不需要调用
-`ready()`，也不应该写 `plugin.ready().catch(() => {})`。`whenReady` 只保留给测试和高级宿主编排。
+这借鉴 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` 只用于
@@ -61,7 +74,8 @@ Widget Host/SDK 负责加载、等待初始化、报告启动失败和执行清
 
 - `ready()` 只在 `activate(context)` 返回（含其 Promise settle）之后才发给 Host，
   `handshakeTimeoutMs` 同时约束这一步；
-- 初始化失败时，SDK 先报结构化错误，再调用插件资源清理；
+- 初始化失败时，SDK 先报结构化错误，再调用已登记的插件资源清理；成功激活后的释放会
+  最多调用一次 `deactivate()`，已完成激活的异步清理可通过 `whenDisposed` 等待；
 - `context.render` 首帧和更新都会收到完整快照，通过 `renderContext.phase` 区分。
 
 ## 从 Manifest 到插件运行
@@ -87,13 +101,34 @@ Manifest 是插件的静态声明，SDK 代码是隔离 iframe 内的运行时
 }
 ```
 
+需要接管完整的会话右侧区域时，在同一个 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)` 约定。面板、工具结果和文件预览由
+所有公开插件类型都使用同一个 `activate(context)` 约定。面板和文件预览由
 Manifest 的 `contributes.widget` 决定；运行时代码只认识统一的 `context.events`、
 `context.render`、`context.capabilities` 和 `context.ui`。首帧和后续快照通过
 `renderContext.phase` 区分，不需要维护两套回调。
@@ -105,6 +140,8 @@ TypeScript 类型，不依赖某个 `defineManifest` 工厂。构建工具调用
 才需要传入第二个参数。`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
@@ -127,10 +164,11 @@ SDK 发布包会生成 `dist/index.d.ts` 与对应的 declaration map，并通
 
 ## 能力
 
-每项能力都要在 Manifest 的 `capabilities` 里声明，并由 Host 实际 grant；
-缺任一侧，调用在 Widget 本地即被拒绝。所有能力调用都必须在 `ready()` 之后。
+公开能力要在 Manifest 的 `capabilities` 里声明，并由 Host 实际 grant；
+`service.invoke` 需要由 Host binding 显式授权。缺任一侧，调用在 Widget 本地即被拒绝。
+所有能力调用都必须在 `ready()` 之后。
 
-下面七项是当前的全部能力。grant 名与 Manifest 申请键不一定同名 —— `ui.presentation`
+下面列出的能力是当前 SDK 支持的能力。grant 名与 Manifest 申请键不一定同名 —— `ui.presentation`
 对应的作者侧申请键是 `capabilities.presentation`（编译后的 宿主格式字段才叫
 `requestedCapabilities.presentation`）。
 
@@ -143,7 +181,9 @@ SDK 发布包会生成 `dist/index.d.ts` 与对应的 declaration map，并通
 | `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 主动推送事件外，其余能力共用同一套调用范式，掌握下面这一个就会调其余能力：
 
@@ -169,14 +209,17 @@ if (result.ok) {
 - 中止与超时统一用 `{ 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 Result 的 `content.envelope` 是可选的结构化投影，包含受约束的状态、数据、指标、产物引用、
-  provenance、warning 和 missing；产物只携带 opaque id 与展示元数据，不携带下载 URL 或本机路径。
+- 外部插件的工具结果场景通过 `tool-call-result` 事件作为可选运行时信号；内部 Host/协议测试仍可使用低层 Tool Result RenderRequest
+  或展示槽位。插件应把结果转换成自己的 Panel 数据，再通过 `context.render` 更新面板。
 - 呈现只是**请求**。Host 可能降级到别的表面，成功结果里的 `surface` 才是真实表面；
   Widget 不能指定目标 Panel、身份、运行时 generation、坐标或层级。
 - 高层插件 API 使用 `context.events.on(handler)` 接收 Host 从当前 Runtime **主动推送**的

package/dist/compatibility/testing.js

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

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-export type { WidgetActivationEvent, WidgetActivationEvents, WidgetContribution, WidgetEventName, WidgetFilePreviewContribution, WidgetPanelContribution, WidgetPluginContributions, WidgetPluginManifest, WidgetToolPhase, WidgetToolResultContribution, } from "@dp-bohrium/widget-contracts";
+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,15 +1,12 @@
-import { c as WIDGET_SDK_VERSION, i as createWidgetClient } from "./runtime-B5kilTcQ.js";
+import { i as createWidgetClient, l as WIDGET_SDK_VERSION } from "./runtime-Drr96Awx.js";
 import { WIDGET_ACTIVATION_EVENTS, WIDGET_EVENT_NAMES, isWidgetActivationEvent, isWidgetEventName } from "@dp-bohrium/widget-contracts";
 //#region src/manifest.ts
-function compiledSlot(contribution) {
+function compiledContribution(contribution) {
 	switch (contribution.type) {
 		case "panel": return {
 			type: "panel",
-			panelType: contribution.id
-		};
-		case "tool-result": return {
-			type: "tool-result",
-			toolName: contribution.toolName
+			id: contribution.id,
+			...contribution.placement === void 0 ? {} : { placement: contribution.placement }
 		};
 		case "file-preview": return {
 			type: "file-preview",
@@ -21,11 +18,13 @@ function compiledSlot(contribution) {
 * 将开发者维护的插件清单编译为宿主可加载的宿主清单。
 *
 * 这是构建工具的边界函数，不是类型提示入口：作者直接编辑带 `$schema` 的 JSON，
-* SDK 版本从当前安装包读取，宿主入口默认落到 dist/widget.js，内部 slot 标识只在这里生成。
+* SDK 版本从当前安装包读取，宿主入口默认落到 dist/widget.js，内部 contribution 标识只在这里生成。
 */
 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,
@@ -35,7 +34,7 @@ function compileWidgetPluginManifest(manifest, options = {}) {
 			hostApiVersion: 1,
 			widgetSdkVersion: WIDGET_SDK_VERSION,
 			entry: options.hostEntry ?? "dist/widget.js",
-			slot: compiledSlot(manifest.contributes.widget),
+			contribution: compiledContribution(manifest.contributes.widget),
 			...activationEvents === void 0 ? {} : { activationEvents },
 			...manifest.capabilities === void 0 ? {} : { requestedCapabilities: manifest.capabilities },
 			...manifest.runtime === void 0 ? {} : { runtime: manifest.runtime },
@@ -44,13 +43,57 @@ function compileWidgetPluginManifest(manifest, options = {}) {
 	};
 }
 //#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).activate, options);
+	const client = createWidgetRuntime(typeof widget === "function" ? { activate: widget } : widget, options);
 	const whenReady = client.ready();
 	whenReady.catch((reason) => {
 		const error = toStartupError(reason);
@@ -62,19 +105,17 @@ function runWidgetHost(widget, options = {}) {
 	});
 	return {
 		whenReady,
+		whenDisposed: client.disposed(),
 		state: client.state,
 		dispose: client.dispose
 	};
 }
-function disposable(registration) {
-	return typeof registration === "function" ? { dispose: registration } : registration;
-}
-function createContext(client, payload, renderHandlers, registrations, signal) {
+function createContext(client, payload, renderHandlers, lifetime) {
 	return {
 		instanceId: payload.instanceId,
 		locale: payload.locale,
 		theme: payload.theme,
-		signal,
+		signal: lifetime.signal,
 		capabilities: {
 			granted: payload.capabilities,
 			request: (request, options) => client.requestCapability(request, options)
@@ -88,6 +129,8 @@ function createContext(client, payload, renderHandlers, registrations, signal) {
 			input
 		}, options) },
 		network: client.network,
+		services: client.services,
+		hostUser: client.hostUser,
 		ui: {
 			state: {
 				read: (key, options) => client.requestCapability({
@@ -106,47 +149,78 @@ function createContext(client, payload, renderHandlers, registrations, signal) {
 					}
 				}, 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 result = { dispose: typeof handlerOrName === "string" ? client.onEvent(handlerOrName, maybeHandler) : client.onEvent(handlerOrName) };
-			registrations.add(result);
-			return result;
+			const unsubscribe = typeof handlerOrName === "string" ? client.onEvent(handlerOrName, maybeHandler) : client.onEvent(handlerOrName);
+			return lifetime.add(unsubscribe);
 		} },
 		subscriptions: { add(registration) {
-			registrations.add(disposable(registration));
+			lifetime.add(registration);
 		} },
 		render(handler) {
 			renderHandlers.add(handler);
-			const result = { dispose: () => {
+			return lifetime.add({ dispose: () => {
 				renderHandlers.delete(handler);
-			} };
-			registrations.add(result);
-			return result;
+			} });
 		},
 		resize: (width, height) => client.resize(width, height)
 	};
 }
-function createWidgetRuntime(activate, options = {}) {
+function createWidgetRuntime(module, options = {}) {
 	let client;
-	let widgetDispose;
-	let context;
 	const renderHandlers = /* @__PURE__ */ new Set();
-	const registrations = /* @__PURE__ */ new Set();
-	const lifetime = new AbortController();
+	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,
-			async onInit(payload) {
-				context = createContext(client, payload, renderHandlers, registrations, lifetime.signal);
-				const registration = await activate(context);
-				if (registration !== void 0) {
-					widgetDispose = disposable(registration);
-					context.subscriptions.add(widgetDispose);
-				}
+			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 = {
@@ -157,20 +231,12 @@ function createWidgetRuntime(activate, options = {}) {
 					Promise.resolve(handler(request, renderContext)).catch(() => {});
 				} catch {}
 			},
-			onDispose() {
-				lifetime.abort();
-				for (const registration of [...registrations]) try {
-					Promise.resolve(registration.dispose()).catch(() => {});
-				} catch {}
-				registrations.clear();
-				renderHandlers.clear();
-				context = void 0;
-				widgetDispose = void 0;
-			}
+			onDispose: dispose
 		}
 	});
 	return {
 		ready: () => client.ready(),
+		disposed: () => disposedPromise,
 		state: () => client.currentState,
 		dispose: () => client.dispose()
 	};

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

@@ -8,6 +8,6 @@ export interface CompileWidgetPluginManifestOptions {
  * 将开发者维护的插件清单编译为宿主可加载的宿主清单。
  *
  * 这是构建工具的边界函数，不是类型提示入口：作者直接编辑带 `$schema` 的 JSON，
- * SDK 版本从当前安装包读取，宿主入口默认落到 dist/widget.js，内部 slot 标识只在这里生成。
+ * SDK 版本从当前安装包读取，宿主入口默认落到 dist/widget.js，内部 contribution 标识只在这里生成。
  */
 export declare function compileWidgetPluginManifest(manifest: WidgetPluginManifest, options?: CompileWidgetPluginManifestOptions): WidgetManifest;

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

@@ -37,7 +37,7 @@ function isProtocolPayload(type, payload) {
 			const revision = property(payload, "revision");
 			const context = property(payload, "context");
 			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);
+			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, "contribution") === "string" && typeof property(payload, "state") === "string" && isRecord(context) && isRecord(content);
 		}
 		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"));

package/dist/runtime/bootstrap.d.ts

@@ -1,7 +1,8 @@
-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";
@@ -60,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;
@@ -89,6 +92,8 @@ 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 流实时推送的全部聚合事件。 */

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 { 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, WidgetCapabilityRequestOptions, WidgetClientEvents, WidgetClientOptions, WidgetClientState, } from "./client.js";
-export { PRESENTATION_CONFIRMATION_TIMEOUT_MS, WidgetClient, } from "./client.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, c as WIDGET_SDK_VERSION, 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-B5kilTcQ.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, WIDGET_SDK_VERSION, WidgetClient, WidgetRuntimeClient, createWidgetClient, isWidgetHostConnectMessage, isWidgetProtocolMessage };
+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-Drr96Awx.js";
+import { i as isWidgetProtocolMessage, r as MessagePortTransport } from "../protocol-endpoint-CDz-YDGT.js";
+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-B5kilTcQ.js → runtime-Drr96Awx.js}

@@ -1,8 +1,8 @@
-import { r as MessagePortTransport, t as ProtocolEndpoint } from "./protocol-endpoint-I78q3jVT.js";
+import { r as MessagePortTransport, t as ProtocolEndpoint } from "./protocol-endpoint-CDz-YDGT.js";
 //#endregion
 //#region src/runtime/version.ts
 /** 从当前安装的 SDK package.json 读取版本，插件作者不需要重复填写。 */
-const WIDGET_SDK_VERSION = "0.1.0";
+const WIDGET_SDK_VERSION = "0.3.0";
 //#endregion
 //#region src/runtime/network.ts
 const failureReasons = /* @__PURE__ */ new Set([
@@ -82,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",
@@ -231,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,
@@ -398,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), {
@@ -795,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";
@@ -894,6 +1002,8 @@ function cloneGrantedCapabilities(capabilities) {
 */
 var WidgetRuntimeClient = class {
 	network;
+	services;
+	hostUser;
 	runtimeWindow;
 	options;
 	events;
@@ -944,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;
@@ -1010,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));
 	}
@@ -1162,4 +1293,4 @@ function createWidgetClient(options) {
 	return new WidgetRuntimeClient(options);
 }
 //#endregion
-export { isWidgetHostConnectMessage as a, WIDGET_SDK_VERSION as c, 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

@@ -1,6 +1,7 @@
-import type { CapabilityRequest, CapabilityResult, FileDownloadResult, FileReference, GrantedCapability, RenderRequest, TaskObservationBatch, Theme, UiStateResult, UiStateWriteResult, WidgetEventName, WidgetLiveEvent } from "@dp-bohrium/widget-contracts";
-import { type CreateWidgetClientOptions, type WidgetClientFactoryOptions, type WidgetClientState, type WidgetLiveEventContext, type WidgetLiveEventHandler } from "./runtime/index.js";
+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>;
 }
@@ -81,8 +82,19 @@ export type UiStateWriteCapabilityResult = {
 } | 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;
@@ -106,6 +118,10 @@ export interface WidgetContext {
     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: {
@@ -119,6 +135,8 @@ export interface WidgetHostOptions extends Omit<CreateWidgetClientOptions, "widg
     readonly events?: Pick<NonNullable<WidgetClientFactoryOptions["events"]>, "onError">;
     /** Widget Host 启动失败时的统一处理入口。 */
     readonly onStartupError?: (error: Error) => void;
+    /** 停用或资源释放错误，诊断失败不会影响其它资源释放。 */
+    readonly onCleanupError?: (error: Error) => void;
 }
 export interface WidgetModule {
     activate: WidgetActivation;
@@ -127,6 +145,8 @@ export interface WidgetModule {
 export interface WidgetHandle {
     /** 供测试、开发工具和 Host 编排等待激活完成。 */
     readonly whenReady: Promise<void>;
+    /** Host 释放 Guest 后完成；包含已完成激活插件的异步 deactivate 清理。 */
+    readonly whenDisposed: Promise<void>;
     readonly state: () => WidgetClientState;
     dispose(): void;
 }

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.1.0",
+  "version": "0.3.0",
   "description": "Bohrium Widget 开发者 SDK：在 Widget Bundle 内与 Host 建立 Bridge，并暴露生命周期与能力协议。",
   "license": "MIT",
   "type": "module",
@@ -38,6 +38,8 @@
   "files": [
     "dist",
     "README.md",
+    "AGENTS.md",
+    "llms.txt",
     "CHANGELOG.md",
     "LICENSE"
   ],
@@ -46,7 +48,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@dp-bohrium/widget-contracts": "0.1.0"
+    "@dp-bohrium/widget-contracts": "0.3.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.2.0",