@dp-bohrium/widget-sdk 0.0.1 → 0.0.3

package/README.md

@@ -1,36 +1,34 @@
 # @dp-bohrium/widget-sdk
 
-Widget developer SDK. Use `createWidgetClient` inside a production Widget
-Bundle. It announces the bundle to the Host, accepts the transferred
-`MessagePort`, and exposes the shared lifecycle and capability protocol
-without requiring Widget code to handle `window.postMessage` directly.
+Widget 开发者 SDK。在生产 Widget Bundle 内使用 `createWidgetClient`：向 Host
+宣告 Bundle、接收转移过来的 `MessagePort`，并暴露共享的生命周期与能力协议，
+无需直接处理 `window.postMessage`。
 
-Install the exact prerelease from the internal registry:
+从 npmjs 安装（默认最新版）：
 
 ```bash
-pnpm add @dp-bohrium/widget-sdk@0.0.1 \
-  --registry=https://registry.npmjs.org
+pnpm add @dp-bohrium/widget-sdk
 ```
 
-Host Runtime and Shrimp should keep consuming `@dp-bohrium/widget-contracts`.
-They must not install this package.
+Host 与控制面应继续只消费 `@dp-bohrium/widget-contracts`，不要安装本包。
 
 ```ts
 import { createWidgetClient } from "@dp-bohrium/widget-sdk";
 
 const widget = createWidgetClient({
-  widgetSdkVersion: "0.0.1",
+  // 填入已安装的 @dp-bohrium/widget-sdk 精确版本（npm view / package.json）
+  widgetSdkVersion: "REPLACE_WITH_INSTALLED_SDK_VERSION",
   async onInit(payload) {
-    // Initialize using the Host-provided locale, theme and capabilities.
+    // 使用 Host 下发的 locale、theme 与 capabilities 初始化。
     console.log(payload.locale);
-    await Promise.resolve(); // Load application state here.
+    await Promise.resolve(); // 在此加载应用状态。
   },
   onRender(request) {
-    // Render the complete snapshot for the selected slot.
+    // 按所选 Slot 渲染完整快照。
     console.log(request.slot);
   },
   onDispose({ reason, deadlineMs }) {
-    // Release local timers, subscriptions and workers.
+    // 释放本地定时器、订阅与 worker。
     console.log(reason, deadlineMs);
   },
 });
@@ -39,10 +37,11 @@ await widget.ready();
 widget.resize({ width: 600, height: 400 });
 ```
 
-## Host-managed network access
+## Host 托管的网络访问
 
-Declare `requestedCapabilities.network.fetch` in the Widget Manifest, then use the typed facade after
-`ready()` resolves. The Widget never receives Host credentials and does not call browser `fetch` directly:
+在 Widget Manifest 中声明 `requestedCapabilities.network.fetch`，在 `ready()`
+完成后再调用类型化 facade。Widget 不会收到 Host 凭据，也不应直接调用浏览器
+`fetch`：
 
 ```ts
 const controller = new AbortController();
@@ -63,17 +62,16 @@ if (result.ok) {
 }
 ```
 
-The Host decides whether to prompt, remember an exact Origin grant, select an opaque credential binding,
-follow a redirect, or deny the request. Calls before readiness, after disposal, or without a current
-`network.fetch` grant reject locally. Abort and timeout reuse the existing MessageChannel capability lifecycle.
-`requestCapability` remains available for protocol-level integrations, but `widget.network.fetch` is the
-supported network API for Widget application code.
+是否弹窗、记住精确 Origin 授权、选择不透明凭据绑定、跟随重定向或拒绝，均由
+Host 决定。在未就绪、已 dispose，或当前没有 `network.fetch` grant 时，调用会在
+本地拒绝。中止与超时复用既有 MessageChannel 能力生命周期。
+`requestCapability` 仍可用于协议级集成，但 Widget 应用代码应优先使用
+`widget.network.fetch`。
 
-## Host-governed panel presentation
+## Host 治理的面板呈现
 
-Panel Widgets can ask the Host to present their current panel in a workspace,
-floating, or overlay surface. The same methods are available on the ordinary
-`createWidgetClient()` result and the low-level `WidgetClient`:
+Panel Widget 可以请求 Host 以 workspace、floating 或 overlay 表面呈现当前面板。
+普通 `createWidgetClient()` 结果与低层 `WidgetClient` 上均可使用相同方法：
 
 ```ts
 import { PRESENTATION_CONFIRMATION_TIMEOUT_MS } from "@dp-bohrium/widget-sdk";
@@ -87,8 +85,8 @@ const result = await widget.present("floating", {
 if (!result.ok) {
   showPresentationDenial(result.reason, result.message);
 } else if ("surface" in result.data) {
-  // The Host can report a different actual surface, such as a compact-mode
-  // downgrade from floating to overlay or workspace.
+  // Host 可能回报不同的实际表面，例如紧凑模式下从 floating 降级到 overlay
+  // 或 workspace。
   showCurrentSurface(result.data.surface);
 }
 
@@ -97,74 +95,59 @@ await widget.focusPresentationBoundary("forward");
 await widget.closePresentation();
 ```
 
-When the Host grants `ui.presentation` with the `overlay` surface, the ordinary
-client also installs keyboard cooperation for cross-origin Panel overlays. An
-unhandled, trusted, non-composing Escape requests `closePresentation()`. A Tab
-that is followed by focus leaving the iframe requests
-`focusPresentationBoundary("forward" | "backward")`; internal focus movement
-does not send anything. Frameworks with a custom focus manager can call the
-typed helper directly.
-
-The default confirmation timeout is 60 seconds. `timeoutMs` overrides it and
-`signal` cancels local waiting. A Host policy or user denial resolves normally
-as `{ ok: false, reason, message, retryable }`; client timeout, abort, dispose,
-or a malformed successful response rejects the Promise. Browser resize,
-visibility, focus, and pointer events are never treated as confirmation.
-
-These methods only request a presentation. The Host remains the final authority
-for grants, supported surfaces, confirmation, compact-mode downgrade, and the
-actual panel state. `isTrusted` and `defaultPrevented` are Widget-realm noise
-filters, not authorization: the MessageChannel identifies the current iframe
-instance but cannot prove a physical key or human activation. The Widget cannot
-name a target Panel, Host selector, identity, runtime generation, coordinate, or
-layer. The Host must recheck the current instance, top Overlay, focus epoch, and
-higher security layers before accepting either request.
-
-`ready()` is not sent to the Host until `onInit` returns or its Promise
-settles. If initialization fails, the SDK reports a structured `onError`
-event and then invokes `onDispose` so local resources can be released.
-`handshakeTimeoutMs` also bounds this initialization step after the Host
-connection has been established.
-
-When only `onUpdate` is supplied, the first complete `render` snapshot is also
-delivered to `onUpdate`.
-
-`WidgetClient` provides the framework-neutral, low-level runtime interface.
-Capability requests accept `{ timeoutMs, signal }`, so application lifecycle
-hooks can cancel pending reads without receiving late results. It is available
-from `@dp-bohrium/widget-sdk/runtime` for advanced integrations and protocol-level
-tests.
-
-The main entry exposes the production `createWidgetClient` factory. Low-level
-protocol classes and bootstrap constants are available from
-`@dp-bohrium/widget-sdk/runtime`; `MessagePortTransport` and the bootstrap
-messages are not part of the ordinary Widget API.
-
-`@dp-bohrium/widget-sdk/testing` provides `MemoryTransport` and
-`MockWidgetHost`. The Mock Host owns init/ready sequencing, first-render versus
-update selection, resize events, capability adapter responses, and terminal
-dispose behavior. It uses the same public contracts as production Hosts but
-does not claim production iframe, CSP, authorization, or resource-isolation
-guarantees. Contract validators stay in the unpublished
-`@dp-bohrium/widget-contract-testing` workspace package.
-
-Set `capabilityResult` for one deterministic default allow or denial. A supplied
-`handleCapability` remains the authoritative advanced handler when both are
-present. `host.capabilityRequests` returns an ordered defensive-copy snapshot,
-so tests can inspect requests without mutating Mock Host state.
-
-or fallback UI. If the Host iframe uses `sandbox="allow-scripts"` without
-`allow-same-origin`, load the bundled Widget as a classic script or IIFE
-unless the isolated origin serves CORS headers for `type="module"`.
-
-If the Host sends a malformed Bridge envelope or payload, the transport reports
-a structured `MESSAGE_INVALID` error and closes the connection. The Widget is
-not left waiting on a connection that the Host still considers active.
+当 Host 授予带 `overlay` 表面的 `ui.presentation` 时，普通 client 还会安装跨源
+Panel overlay 的键盘协作：未处理、受信、非 composing 的 Escape 会请求
+`closePresentation()`；Tab 之后焦点离开 iframe 会请求
+`focusPresentationBoundary("forward" | "backward")`；iframe 内焦点移动不会发消息。
+有自定义焦点管理器的框架可直接调用类型化 helper。
 
+默认确认超时为 60 秒。可用 `timeoutMs` 覆盖，用 `signal` 取消本地等待。Host
+策略拒绝或用户拒绝会以 `{ ok: false, reason, message, retryable }` 正常兑现；
+客户端超时、中止、dispose 或畸形成功响应会 reject Promise。浏览器 resize、
+可见性、焦点与指针事件都不会被当成确认。
+
+这些方法只是提出呈现请求。grant、支持的表面、确认、紧凑模式降级与真实面板状态
+仍由 Host 最终裁决。`isTrusted` 与 `defaultPrevented` 只是 Widget 域内噪声过滤，
+不是授权：MessageChannel 能识别当前 iframe 实例，但不能证明物理按键或人类激活。
+Widget 不能指定目标 Panel、Host 选择器、身份、运行时 generation、坐标或层级。
+Host 在接受请求前必须复核当前实例、顶层 Overlay、焦点 epoch 与更高安全层。
+
+`ready()` 不会在 `onInit` 返回（或其 Promise settle）之前发给 Host。初始化失败时，
+SDK 会报告结构化 `onError`，再调用 `onDispose` 以便释放本地资源。
+`handshakeTimeoutMs` 也会在 Host 连接建立后约束该初始化步骤。
+
+若只提供了 `onUpdate`，首次完整 `render` 快照也会投递给 `onUpdate`。
+
+`WidgetClient` 提供框架无关的低层运行时接口。能力请求接受
+`{ timeoutMs, signal }`，应用生命周期钩子可取消在途读取、避免迟到结果。高级集成与
+协议级测试可从 `@dp-bohrium/widget-sdk/runtime` 使用。
+
+主入口暴露生产用 `createWidgetClient`。低层协议类与 bootstrap 常量见
+`@dp-bohrium/widget-sdk/runtime`；`MessagePortTransport` 与 bootstrap 消息不属于
+普通 Widget API。
+
+`@dp-bohrium/widget-sdk/testing` 提供 `MemoryTransport` 与 `MockWidgetHost`。
+Mock Host 负责 init/ready 时序、首帧 render 与 update 选择、resize 事件、能力
+adapter 响应与终态 dispose。它使用与生产 Host 相同的公开 contracts，但不等同于
+生产 iframe、CSP、授权或资源隔离保证。Schema 与类型校验以
+`@dp-bohrium/widget-contracts` 为准。
+
+可用 `capabilityResult` 给出确定性的默认允许或拒绝；若同时提供
+`handleCapability`，后者仍是权威的高级处理器。`host.capabilityRequests` 返回有序的
+防御性拷贝快照，测试可检查请求而不改动 Mock Host 状态。
+
+若 Host iframe 使用 `sandbox="allow-scripts"` 且没有 `allow-same-origin`，除非隔离
+源为 `type="module"` 提供 CORS，否则请将打包后的 Widget 以 classic script / IIFE
+加载。
+
+若 Host 发送畸形 Bridge 信封或载荷，transport 会报告结构化 `MESSAGE_INVALID`
+并关闭连接，不会让 Widget 继续等待一个 Host 仍视为活跃的连接。
 
 ## 受授权的事件订阅与工具 Hook（本地候选）
 
-新增 `subscribeEvents`、`onTool` 和 `invokeAction`。Manifest 声明与 Host 实际 grant 必须同时包含 topic/action，旧 Host 不会自动获得这些能力；发布时需一起升级 contracts 和消费者。订阅类型从包根与 `/runtime` 导出。
+新增 `subscribeEvents`、`onTool` 和 `invokeAction`。Manifest 声明与 Host 实际
+grant 必须同时包含 topic/action；旧 Host 不会自动获得这些能力，发布时需一起升级
+contracts 与消费者。订阅类型从包根与 `/runtime` 导出。
 
 ```ts
 const events = client.subscribeEvents({
@@ -192,10 +175,17 @@ events.unsubscribe();
 hooks.unsubscribe();
 ```
 
-Hook 观察已经发生的服务端工具事实，不是执行前拦截器；不允许通过 iframe 回调改写参数、审批或控制 durable 执行。`tools.inspect` 是当前 Shrimp 的只读动作 provider，返回工具身份和最新可读取状态；其他 action 由 Host/provider 显式实现并授权。SDK 不自动重试动作，也不把回调完成解释为工具执行完成。
-
-所有订阅共享实例的 events 请求预算，并各自遵守 topic 最小间隔。游标仅在 `onBatch` 成功后提交；消费者异常、权限撤销和不可恢复的历史错误会关闭订阅并调用 `onError`。`unsubscribe` 和 Host dispose 释放订阅、排队请求和本地在途等待，忽略迟到结果；异步回调需检查传入 signal 后再更新自己的状态。`closed` 表示订阅已关闭，并不等待用户未完成的回调结束。重新订阅时显式传入已保存 cursor。
+Hook 观察已经发生的服务端工具事实，不是执行前拦截器；不允许通过 iframe 回调改写
+参数、审批或控制 durable 执行。`tools.inspect` 是常见的只读动作
+provider 示例，返回工具身份和最新可读取状态；其他 action 由 Host/provider 显式实现并
+授权。SDK 不自动重试动作，也不把回调完成解释为工具执行完成。
 
-维护者可复验包在仓库 `examples/forge/tool-observer`，不包含在开发者 npm 包中。
+所有订阅共享实例的 events 请求预算，并各自遵守 topic 最小间隔。游标仅在
+`onBatch` 成功后提交；消费者异常、权限撤销和不可恢复的历史错误会关闭订阅并调用
+`onError`。`unsubscribe` 和 Host dispose 释放订阅、排队请求和本地在途等待，忽略
+迟到结果；异步回调需检查传入 signal 后再更新自己的状态。`closed` 表示订阅已关闭，
+并不等待用户未完成的回调结束。重新订阅时显式传入已保存 cursor。
 
-每次 events.read 是有界、非阻塞读取；当前 V1 没有单请求取消 wire 消息，unsubscribe 会停止后续轮询并取消本地等待，已经发出的服务端读取可能完成但其结果被忽略。Host 实例卸载另通过既有 lease/AbortSignal 释放在途宿主请求。
+每次 events.read 是有界、非阻塞读取；当前 V1 没有单请求取消 wire 消息，
+unsubscribe 会停止后续轮询并取消本地等待，已经发出的服务端读取可能完成但其结果被
+忽略。Host 实例卸载另通过既有 lease/AbortSignal 释放在途宿主请求。

package/package.json

@@ -1,12 +1,25 @@
 {
   "name": "@dp-bohrium/widget-sdk",
-  "version": "0.0.1",
-  "description": "Widget developer SDK runtime client for Bohrium Widget Platform.",
+  "version": "0.0.3",
+  "description": "Bohrium Widget 开发者 SDK：在 Widget Bundle 内与 Host 建立 Bridge，并暴露生命周期与能力协议。",
   "license": "MIT",
   "type": "module",
   "engines": {
     "node": ">=20"
   },
+  "keywords": [
+    "bohrium",
+    "dp-bohrium",
+    "widget",
+    "sdk",
+    "iframe",
+    "messagechannel",
+    "host-bridge",
+    "runtime"
+  ],
+  "author": "Bohrium",
+  "homepage": "https://www.npmjs.com/package/@dp-bohrium/widget-sdk",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -27,11 +40,12 @@
     "README.md",
     "LICENSE"
   ],
+  "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@dp-bohrium/widget-contracts": "0.0.1"
+    "@dp-bohrium/widget-contracts": "0.0.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.2.0",