@heybox/hb-sdk 0.8.2-alpha.1 → 0.8.2-alpha.5

package/dist/index.cjs.js

@@ -279,12 +279,34 @@ function isPlainObject$1(value) {
  * @remarks
  * 该错误用于表示握手失败、bridge 调用失败、父容器运行时错误等
  * 非 HTTP 结果错误。其 `code` 字段可用于业务分支处理，
- * `data` 仅作为可选调试信息，不保证结构稳定。
+ * `data` 仅作为可选调试信息，不保证结构稳定。错误码是跨 Host 的分支契约；
+ * `message` 只用于日志和开发者提示，不应作为机器判断条件。
+ *
+ * 常见处理类别包括：`INVALID_PARAMS`（修正调用参数）、`PERMISSION_NOT_DECLARED`
+ * 或 `PERMISSION_DENIED`（检查 Manifest/平台批准）、`USER_GESTURE_REQUIRED`
+ *（改为用户点击后重试）、`AUTHORIZATION_CANCELLED`（结束当前流程），以及
+ * `METHOD_FORBIDDEN`（当前 Host 不支持该能力）。具体能力还可能返回模块专属错误码。
+ * 不要把所有错误都当作可重试错误，也不要把 `data` 当成稳定的序列化协议。
+ *
+   * @example
+   * ```ts
+   * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+   *
+   * try {
+   *   await hbSDK.auth.login({ scopes: ['profile'] })
+ * } catch (error) {
+ *   if (error instanceof HbMiniProgramSDKError && error.code === 'USER_GESTURE_REQUIRED') {
+ *     showRetryButton()
+ *     return
+ *   }
+ *   throw error
+ * }
+ * ```
  */
 class HbMiniProgramSDKError extends Error {
-    /** 稳定错误码。 */
+    /** 稳定错误码；业务分支应比较该字段，不要比较 `message`。 */
     code;
-    /** 可选调试数据。 */
+    /** 可选调试数据；结构由具体错误码决定，可能随 Host 版本变化。 */
     data;
     constructor(error) {
         super(error.message);
@@ -316,20 +338,22 @@ function createSDKError(code, message, data) {
  *
  * @remarks
  * 仅在请求已经成功走完 bridge / runtime / 宿主调用链、但最终 HTTP 状态不满足
- * `validateStatus` 时抛出。它不表示握手失败或 bridge 级错误。
+ * `validateStatus` 时抛出。它不表示握手失败或 bridge 级错误。网络请求没有收到
+ * 可判定的 HTTP 响应时，SDK 会抛出 `HbMiniProgramSDKError` 或原始 transport 错误，
+ * 不应把本类当作网络不可达的统一错误类型。
  *
  * @typeParam T - 标准化响应数据的类型。
  */
 class HbMiniProgramNetworkError extends Error {
-    /** HTTP 状态码。 */
+    /** HTTP 状态码；由 `validateStatus` 判定为失败的响应状态。 */
     status;
-    /** 标准化响应数据。 */
+    /** 标准化响应数据；类型由 `network.request<T>()` 的泛型参数决定。 */
     data;
-    /** 标准化响应头。 */
+    /** 标准化响应头；敏感响应头会在进入错误对象前被脱敏或移除。 */
     headers;
-    /** SDK 公共请求配置快照。 */
+    /** SDK 公共请求配置快照；可能含原始 URL、请求头或请求数据，记录日志前必须自行脱敏。 */
     config;
-    /** 完整标准化响应。 */
+    /** 完整标准化响应，包含状态、头、数据和请求配置。 */
     response;
     /**
      * @param response - 已完成请求的标准化网络响应。
@@ -564,9 +588,31 @@ function restoreMethod(history, name, patchedValue, original) {
     }
 }
 
+/**
+ * 所有小程序 iframe bridge envelope 共用的固定 namespace。
+ *
+ * @remarks 该值用于排除无关 `postMessage` 数据，不负责验证消息来源；接收方仍须校验 source 和 nonce，
+ * 并在 origin 可以固定且协议模式要求时校验 origin。
+ */
 const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
+/**
+ * 新消息默认发送的当前 bridge wire 版本。
+ *
+ * @remarks 接收 guard 为握手协商继续接受 v1 与 v2 envelope；cancel 与 operation progress 等 v2-only 消息仍必须使用 v2。
+ */
 const MINI_PROGRAM_MESSAGE_VERSION = 2;
+/**
+ * Runtime 在 iframe URL 中传递 bridge nonce 的 query 参数名。
+ *
+ * @remarks nonce 用于把消息关联到当前 iframe 实例，不是独立的身份认证凭据；接收方还必须校验 source，
+ * 并在 origin 可以固定且协议模式要求时校验 origin。
+ */
 const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
+/**
+ * SDK 发起 bridge 握手时使用的保留 method。
+ *
+ * @remarks `type: 'handshake'` 的消息必须使用该 method；Runtime 的可选握手响应也可携带该 method 供 SDK 识别环境快照。
+ */
 const SDK_HANDSHAKE_METHOD = 'sdk.handshake';
 const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe';
 const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report';
@@ -630,6 +676,76 @@ const COMPANION_SESSION_ACK_OUTPUT_METHOD = 'companion.session.ackOutput';
 const COMPANION_OPEN_ATTACHMENT_METHOD = 'companion.openAttachment';
 const COMPANION_SHOW_NOTIFICATION_METHOD = 'companion.showNotification';
 
+/**
+ * 判断不可信输入是否具有受支持的小程序 bridge 消息结构。
+ *
+ * @param value - 从 `MessageEvent.data`、反序列化结果或其他外部边界取得的未知值。`null`、数组和非对象值会直接返回 `false`。
+ * @returns 输入满足 v1/v2 envelope 及当前 `type` 的最低结构要求时返回 `true`，并将 TypeScript 类型收窄为
+ * {@link MiniProgramBridgeMessage}；否则返回 `false`。
+ *
+ * @remarks
+ * 所有通过的消息都必须使用 {@link MINI_PROGRAM_MESSAGE_NAMESPACE}，`version` 必须为 `1` 或 `2`，
+ * `nonce` 必须为非空字符串。随后按 `type` 执行以下最低校验：
+ *
+ * - `handshake`（v1/v2）：`id` 非空，`method` 固定为 {@link SDK_HANDSHAKE_METHOD}，`error` 必须为 `undefined`；
+ *   `payload` 必须是对象，且包含非空 `href`、字符串 `userAgent` 和非空 `sdkVersion`。
+ * - `request`（v1/v2）：`id` 与 `method` 都是非空字符串，且 `error` 必须为 `undefined`；`payload` 不在此处校验。
+ * - `response`（v1/v2）：`id` 非空；`method` 可省略，提供时必须非空；`error` 可省略，提供时必须含非空
+ *   `code` 与字符串 `message`。该最低结构允许 `payload` 与合法 `error` 同时存在，终态语义由消费端决定。
+ * - 普通 `event`（v1/v2）：`method` 非空、`error` 必须为 `undefined`，`id` 可省略或为非空字符串；事件名和
+ *   `payload` 不在此处校验。
+ * - `operation.progress` 与 `cancel` 只接受 v2。progress 还要求非空 `id` 和受支持的下载或 companion
+ *   prepare 进度 payload；cancel 要求非空 `id`，且 `method`、`payload`、`error` 都必须为 `undefined`。
+ *
+ * 返回 `true` 只表示 wire envelope 可识别，不建立信任或授权边界。该函数不会校验
+ * `MessageEvent.source` / `origin`，只检查 nonce 非空而不会与当前 iframe 的预期 nonce 比较，也不会确认
+ * 握手状态、协商后的版本、请求 ID 是否重复或对应 pending request。除握手和 operation progress 外，它也不校验
+ * payload schema；不会把普通 `method` / 事件名限制在公开目录，不会检查 Manifest 权限、Runtime 权限状态、
+ * Host 支持、可信用户手势或业务策略。顶层 envelope、握手 payload 与 bridge error 中的额外字段也不会被拒绝。
+ *
+ * [MINI_PROGRAM_MESSAGE_VERSION](/reference/symbols/protocol/constants/MINI_PROGRAM_MESSAGE_VERSION)
+ * 是新消息的发送版本，不是本 guard 的唯一接收版本；接受 v1 是兼容行为，
+ * 调用方仍须在握手后确认消息版本与已协商版本一致。method 是否公开及其权限 requirement 应查询
+ * [MINI_PROGRAM_PROTOCOL_CAPABILITIES](/reference/symbols/protocol/constants/MINI_PROGRAM_PROTOCOL_CAPABILITIES)，
+ * 权限快照应先交给
+ * [parseMiniProgramRuntimePermissions](/reference/symbols/protocol/functions/parseMiniProgramRuntimePermissions) 解析。
+ *
+ * 类型谓词只收窄到宽泛的 {@link MiniProgramBridgeMessage}：`payload` 仍为 `unknown`，`method` 等字段仍保持可选。
+ * 需要精确处理 v2 cancel 或 operation progress 时，应在检查判别字段后使用
+ * [MiniProgramBridgeCancelMessage](/reference/symbols/protocol/interfaces/MiniProgramBridgeCancelMessage) 或
+ * [MiniProgramBridgeProgressMessage](/reference/symbols/protocol/interfaces/MiniProgramBridgeProgressMessage)。
+ *
+ * @example
+ * ```ts
+ * import {
+ *   MINI_PROGRAM_PROTOCOL_CAPABILITIES,
+ *   isMiniProgramBridgeMessage,
+ * } from '@heybox/hb-sdk/protocol';
+ *
+ * const publicMethods = new Set<string>(
+ *   MINI_PROGRAM_PROTOCOL_CAPABILITIES.map(({ method }) => method),
+ * );
+ *
+ * window.addEventListener('message', (event) => {
+ *   if (event.source !== iframe.contentWindow) return;
+ *   if (expectedOrigin && expectedOrigin !== '*' && event.origin !== expectedOrigin) return;
+ *   if (!isMiniProgramBridgeMessage(event.data)) return;
+ *   if (event.data.nonce !== expectedNonce) return;
+ *
+ *   if (event.data.type === 'request') {
+ *     const method = event.data.method;
+ *     if (!method || !publicMethods.has(method)) return;
+ *     // 继续检查握手状态、权限与 method 对应的 payload。
+ *   }
+ * });
+ * ```
+ *
+ * @see [MiniProgramBridgeMessage](/reference/symbols/protocol/interfaces/MiniProgramBridgeMessage) 宽泛的顶层 envelope 类型。
+ * @see [MINI_PROGRAM_MESSAGE_VERSION](/reference/symbols/protocol/constants/MINI_PROGRAM_MESSAGE_VERSION) 新消息的默认发送版本。
+ * @see [MINI_PROGRAM_BRIDGE_NONCE_PARAM](/reference/symbols/protocol/constants/MINI_PROGRAM_BRIDGE_NONCE_PARAM) iframe URL 中的 nonce 参数名。
+ * @see [MINI_PROGRAM_PROTOCOL_CAPABILITIES](/reference/symbols/protocol/constants/MINI_PROGRAM_PROTOCOL_CAPABILITIES) 公开 method 与权限 requirement 目录。
+ * @see [parseMiniProgramRuntimePermissions](/reference/symbols/protocol/functions/parseMiniProgramRuntimePermissions) Runtime 权限快照解析器。
+ */
 function isMiniProgramBridgeMessage(value) {
     if (!isRecord$2(value))
         return false;
@@ -660,6 +776,60 @@ function isMiniProgramBridgeMessage(value) {
     }
     return false;
 }
+/**
+ * 判断未知值是否为以 `/` 分隔的规范逻辑相对路径。
+ *
+ * @param value - 来自 files API、derived ref、Host payload 或其他不可信边界的候选路径。
+ * @returns 值是满足协议语法的字符串时返回 `true`，并将 TypeScript 类型收窄为 `string`；否则返回 `false`。
+ *
+ * @remarks
+ * 该 guard 直接检查输入字符串，规则如下：
+ *
+ * - 必须是非空字符串；空串和非字符串值失败。
+ * - 不能以 `/` 开头或结尾，因此 `/absolute`、`nested/` 与 `/` 失败。
+ * - 不能包含反斜杠 `\\`、U+0000-U+001F 控制字符或 U+007F；Windows 风格分隔符不会被转换。
+ * - 按 `/` 分段后，每段必须非空且不能精确等于 `.` 或 `..`，因此连续 `/`、`nested/./file` 与
+ *   `nested/../file` 失败。
+ *
+ * 只拒绝完整的 dot segment：`.env`、`..cache`、`file.` 与包含普通点号的名称都可通过；单独的 `'.'`
+ * 本身失败。{@link isMiniProgramDirectoryRef} 在外层显式允许 `relativePath: '.'` 表示 root 目录自身，
+ * {@link isMiniProgramFileRef} 则始终要求本 guard 通过，因此文件引用不能指向 root 自身。
+ *
+ * 该函数不 trim 空白、不 URL/percent decode、不 Unicode normalize、不折叠分隔符，也不应用平台保留名或
+ * 字符规则。空白段、`%2e%2e`、全角字符和 `C:/file` 等只要满足上述原始字符串规则就可能通过；路径长度、
+ * 段长度和段数量也没有在此限制。调用方不能把“通过”解释为操作系统级 canonical path。
+ *
+ * 返回 `true` 只证明语法可作为协议逻辑相对路径，不证明目标存在、末段是文件还是目录、root/handle 属于
+ * 当前 session/origin、`filesystem` 权限已启用、访问 mode 允许当前操作或 Host 支持该 capability。
+ * `normalizeRelativePath()` 这类 SDK/Runtime helper 只是复用本 predicate：合法时原样返回同一个字符串，非法时
+ * 转成对应 SDK/bridge 错误；它不会进一步规范化路径。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramRelativePath } from '@heybox/hb-sdk/protocol';
+ *
+ * const paths: unknown[] = [
+ *   'data.json',
+ *   'nested/data.json',
+ *   '.env',
+ *   '.',
+ *   '../secret',
+ *   'nested//file',
+ *   'nested\\file',
+ * ];
+ *
+ * const validPaths = paths.filter(isMiniProgramRelativePath);
+ * // ['data.json', 'nested/data.json', '.env']
+ * console.log(validPaths);
+ * ```
+ *
+ * @see [isMiniProgramFileRef](/reference/symbols/protocol/functions/isMiniProgramFileRef) 始终使用本规则的 derived 文件引用。
+ * @see [isMiniProgramDirectoryRef](/reference/symbols/protocol/functions/isMiniProgramDirectoryRef) 额外允许 `'.'` 的 derived 目录引用。
+ * @see [isMiniProgramPathRootRef](/reference/symbols/protocol/functions/isMiniProgramPathRootRef) 与相对路径组合的逻辑 root guard。
+ * @see [PathRoot](/reference/symbols/root/interfaces/PathRoot) 提供 `file()` / `directory()` 的 SDK 路径入口。
+ * @see [FileSystem](/reference/symbols/root/interfaces/FileSystem) `files.sandbox` 逻辑路径能力。
+ * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 已授权目录下的相对路径能力。
+ */
 function isMiniProgramRelativePath(value) {
     if (typeof value !== 'string' || !value || value.startsWith('/') || value.endsWith('/')) {
         return false;
@@ -668,6 +838,64 @@ function isMiniProgramRelativePath(value) {
         return false;
     return value.split('/').every((segment) => Boolean(segment) && segment !== '.' && segment !== '..');
 }
+/**
+ * 判断未知值是否可作为 derived file/directory ref 的逻辑路径 root。
+ *
+ * @param value - 来自文件引用、目录引用或其他不可信 wire 边界的候选 root。
+ * @returns 值满足 sandbox root 或 direct directory root 任一结构时返回 `true`，并将 TypeScript 类型
+ * 收窄为 {@link MiniProgramPathRootRef} 判别联合；否则返回 `false`。
+ *
+ * @remarks
+ * 支持两个以 `kind` 区分的分支：
+ *
+ * - Sandbox root：`{ kind: 'sandbox' }`。对通常的对象字面量，除 `kind` 外不能携带任何字段。
+ * - Directory root：`{ kind: 'directory', handleId }`。`handleId` 必须是非空字符串；空白字符串仍满足
+ *   本 guard 的最低结构，格式、长度和归属由 Runtime 继续校验。
+ *
+ * direct file ref、derived directory ref、普通路径字符串以及其他 `kind` 都不能作为 PathRoot。特别是
+ * `{ kind: 'directory', root, relativePath }` 会因额外 canonical 外字段而失败：derived ref 只能引用 sandbox
+ * 或 direct directory root，不能递归嵌套另一层 derived root。
+ *
+ * 两个分支都会拒绝 canonical 集合之外的可枚举自有字符串键，包括值为 `undefined` 的额外键。检查基于
+ * `Object.keys()`，因此非枚举属性、symbol 键和继承属性不会被列入；必需属性本身也不要求是自有或可枚举
+ * 属性。该函数不会复制、冻结或规范化输入。
+ *
+ * 返回 `true` 只建立结构类型收窄，不证明 directory `handleId` 由当前 Runtime 签发、属于当前 session/origin、
+ * 仍然有效且确为目录，也不证明 `filesystem` 权限、目录访问 mode、provenance 或 Host capability。sandbox
+ * 标记同样不自行建立隔离边界；Runtime 必须把它解析到当前 Mini-program 的私有 root 并执行实际权限策略。
+ *
+ * {@link isMiniProgramFileRef} 与 {@link isMiniProgramDirectoryRef} 都用该 guard 校验 derived ref 的 `root`；
+ * 它只校验 root 身份，不校验各自的 `relativePath`。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramPathRootRef } from '@heybox/hb-sdk/protocol';
+ *
+ * const candidates: unknown[] = [
+ *   { kind: 'sandbox' },
+ *   { kind: 'directory', handleId: 'directory_1' },
+ * ];
+ *
+ * for (const candidate of candidates) {
+ *   if (!isMiniProgramPathRootRef(candidate)) continue;
+ *   if (candidate.kind === 'sandbox') {
+ *     console.log('private sandbox root');
+ *   } else {
+ *     console.log('authorized directory root', candidate.handleId);
+ *   }
+ * }
+ *
+ * isMiniProgramPathRootRef({ kind: 'file', handleId: 'file_1' }); // false
+ * isMiniProgramPathRootRef({ kind: 'directory', root: { kind: 'sandbox' }, relativePath: 'nested' }); // false
+ * ```
+ *
+ * @see [MiniProgramPathRootRef](/reference/symbols/protocol/types/MiniProgramPathRootRef) sandbox/direct-directory 联合类型。
+ * @see [isMiniProgramFileRef](/reference/symbols/protocol/functions/isMiniProgramFileRef) 使用 PathRoot 的 derived 文件引用。
+ * @see [isMiniProgramDirectoryRef](/reference/symbols/protocol/functions/isMiniProgramDirectoryRef) 使用 PathRoot 的 derived 目录引用。
+ * @see [PathRoot](/reference/symbols/root/interfaces/PathRoot) SDK 公开的逻辑路径 root 能力。
+ * @see [FilesModule](/reference/symbols/root/interfaces/FilesModule) 提供 `files.sandbox` 与目录 picker 的入口。
+ * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 可作为 derived path root 的目录代理。
+ */
 function isMiniProgramPathRootRef(value) {
     if (!isRecord$2(value))
         return false;
@@ -675,6 +903,65 @@ function isMiniProgramPathRootRef(value) {
         return hasOnlyKeys(value, ['kind']);
     return value.kind === 'directory' && isNonEmptyString$1(value.handleId) && hasOnlyKeys(value, ['kind', 'handleId']);
 }
+/**
+ * 判断未知值是否为 direct handle 或 path-derived 文件引用。
+ *
+ * @param value - 来自 descriptor、capability payload 或其他不可信 wire 边界的候选文件引用。
+ * @returns 值满足 {@link MiniProgramFileRef} 任一分支的最低结构时返回 `true`，并将 TypeScript 类型
+ * 收窄为 direct/derived 文件引用联合；否则返回 `false`。
+ *
+ * @remarks
+ * 两个分支都要求 `kind === 'file'`，并对通常的对象字面量使用互斥的 canonical key 集合：
+ *
+ * - Direct ref：`{ kind: 'file', handleId }`。`handleId` 必须是非空字符串；不能同时携带 `root` 或
+ *   `relativePath`。
+ * - Derived ref：`{ kind: 'file', root, relativePath }`。不能携带 `handleId`；`root` 必须通过
+ *   {@link isMiniProgramPathRootRef}，即精确的 `{ kind: 'sandbox' }`，或带非空 `handleId` 的 direct
+ *   directory root。file ref 与再次嵌套的 derived directory ref 都不能作为 root。
+ *
+ * Derived ref 的 `relativePath` 必须通过 {@link isMiniProgramRelativePath}：非空、不以 `/` 开头或结尾，
+ * 不含空段、`.` / `..` 点段、反斜杠、U+0000-U+001F 控制字符或 U+007F。文件必须指向 root 下的具体路径，
+ * 因此与 {@link isMiniProgramDirectoryRef} 不同，`relativePath: '.'` 不合法。该 guard 不会 URL decode、
+ * Unicode normalize、解析平台分隔符、限制路径长度，或确认末段是文件而不是目录。
+ *
+ * direct 与 derived 分支都会拒绝 canonical 集合之外的可枚举自有字符串键，包括值为 `undefined` 的额外键。
+ * 检查基于 `Object.keys()`，因此非枚举属性、symbol 键和继承属性不会被列入；必需属性本身也不要求是自有
+ * 或可枚举属性。返回对象不会被复制、冻结或规范化。
+ *
+ * 返回 `true` 只证明当前结构可按 wire 类型读取，不证明 direct `handleId` 或 root handle 由当前 Runtime 签发、
+ * 属于当前 session/origin、仍然有效且类型匹配，也不证明目标文件存在、`filesystem` 权限已启用、访问 mode
+ * 允许当前操作或 Host 支持对应 capability。Runtime 在实际解析 ref 时仍须查询 handle registry，执行权限、
+ * provenance 与目标类型校验，并解析 derived path。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramFileRef } from '@heybox/hb-sdk/protocol';
+ *
+ * const candidate: unknown = {
+ *   kind: 'file',
+ *   root: { kind: 'directory', handleId: 'directory_1' },
+ *   relativePath: 'screenshots/cover.png',
+ * };
+ *
+ * if (isMiniProgramFileRef(candidate)) {
+ *   if ('handleId' in candidate) {
+ *     console.log('direct', candidate.handleId);
+ *   } else {
+ *     console.log('derived', candidate.root, candidate.relativePath);
+ *   }
+ * }
+ *
+ * isMiniProgramFileRef({ kind: 'file', handleId: 'file_1' }); // true
+ * isMiniProgramFileRef({ kind: 'file', root: { kind: 'sandbox' }, relativePath: '.' }); // false
+ * ```
+ *
+ * @see [MiniProgramFileRef](/reference/symbols/protocol/types/MiniProgramFileRef) direct/derived 联合类型。
+ * @see [isMiniProgramPathRootRef](/reference/symbols/protocol/functions/isMiniProgramPathRootRef) derived ref 的 root guard。
+ * @see [isMiniProgramRelativePath](/reference/symbols/protocol/functions/isMiniProgramRelativePath) derived 文件路径规则。
+ * @see [isMiniProgramFileDescriptor](/reference/symbols/protocol/functions/isMiniProgramFileDescriptor) 包含名称和 mode 的文件 descriptor guard。
+ * @see [isMiniProgramDirectoryRef](/reference/symbols/protocol/functions/isMiniProgramDirectoryRef) 可用 `'.'` 指向 root 自身的目录引用 guard。
+ * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 使用文件引用的公开 I/O 代理。
+ */
 function isMiniProgramFileRef(value) {
     if (!isRecord$2(value) || value.kind !== 'file')
         return false;
@@ -683,6 +970,65 @@ function isMiniProgramFileRef(value) {
     }
     return (isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
 }
+/**
+ * 判断未知值是否为 direct handle 或 path-derived 目录引用。
+ *
+ * @param value - 来自 descriptor、capability payload 或其他不可信 wire 边界的候选目录引用。
+ * @returns 值满足 {@link MiniProgramDirectoryRef} 任一分支的最低结构时返回 `true`，并将 TypeScript 类型
+ * 收窄为 direct/derived 目录引用联合；否则返回 `false`。
+ *
+ * @remarks
+ * 两个分支都要求 `kind === 'directory'`，并对通常的对象字面量使用互斥的 canonical key 集合：
+ *
+ * - Direct ref：`{ kind: 'directory', handleId }`。`handleId` 必须是非空字符串；不能同时携带 `root` 或
+ *   `relativePath`。
+ * - Derived ref：`{ kind: 'directory', root, relativePath }`。不能携带 `handleId`；`root` 必须通过
+ *   {@link isMiniProgramPathRootRef}，即精确的 `{ kind: 'sandbox' }`，或带非空 `handleId` 的 direct
+ *   directory root。file ref 与再次嵌套的 derived directory ref 都不能作为 root。
+ *
+ * Derived ref 的 `relativePath` 可以是 `'.'`，表示 root 目录自身；这是目录引用专属规则，普通
+ * {@link isMiniProgramRelativePath} 和 file ref 都不接受 `'.'`。其他相对路径必须非空，不以 `/` 开头或结尾，
+ * 不含空段、`.` / `..` 点段、反斜杠、U+0000-U+001F 控制字符或 U+007F。该校验不会 URL decode、
+ * Unicode normalize、解析平台分隔符、限制长度，或判断路径指向的目录是否存在。
+ *
+ * direct 与 derived 分支都会拒绝 canonical 集合之外的可枚举自有字符串键，包括值为 `undefined` 的额外键。
+ * 检查基于 `Object.keys()`，因此非枚举属性、symbol 键和继承属性不会被列入；必需属性本身也不要求是自有
+ * 或可枚举属性。返回对象不会被复制、冻结或规范化。
+ *
+ * 返回 `true` 只证明当前结构可按 wire 类型读取，不证明 direct `handleId` 或 root handle 由当前 Runtime 签发、
+ * 属于当前 session/origin、仍然有效且确为目录，也不证明目标存在、`filesystem` 权限已启用、访问模式允许
+ * 当前操作或 Host 支持对应 capability。Runtime 在实际解析 ref 时仍须查询 handle registry、执行权限与
+ * provenance 校验，并解析 derived path。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramDirectoryRef } from '@heybox/hb-sdk/protocol';
+ *
+ * const candidate: unknown = {
+ *   kind: 'directory',
+ *   root: { kind: 'directory', handleId: 'directory_1' },
+ *   relativePath: 'screenshots/2026',
+ * };
+ *
+ * if (isMiniProgramDirectoryRef(candidate)) {
+ *   if ('handleId' in candidate) {
+ *     console.log('direct', candidate.handleId);
+ *   } else {
+ *     console.log('derived', candidate.root, candidate.relativePath);
+ *   }
+ * }
+ *
+ * isMiniProgramDirectoryRef({ kind: 'directory', root: { kind: 'sandbox' }, relativePath: '.' }); // true
+ * isMiniProgramDirectoryRef({ kind: 'directory', handleId: 'd1', relativePath: '.' }); // false：分支键混用
+ * ```
+ *
+ * @see [MiniProgramDirectoryRef](/reference/symbols/protocol/types/MiniProgramDirectoryRef) direct/derived 联合类型。
+ * @see [isMiniProgramPathRootRef](/reference/symbols/protocol/functions/isMiniProgramPathRootRef) derived ref 的 root guard。
+ * @see [isMiniProgramRelativePath](/reference/symbols/protocol/functions/isMiniProgramRelativePath) 非 `'.'` 相对路径规则。
+ * @see [isMiniProgramDirectoryDescriptor](/reference/symbols/protocol/functions/isMiniProgramDirectoryDescriptor) 包含名称和 mode 的目录 descriptor guard。
+ * @see [isMiniProgramFileRef](/reference/symbols/protocol/functions/isMiniProgramFileRef) 不接受 root 自身 `'.'` 的文件引用 guard。
+ * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 使用目录引用的公开路径操作代理。
+ */
 function isMiniProgramDirectoryRef(value) {
     if (!isRecord$2(value) || value.kind !== 'directory')
         return false;
@@ -691,9 +1037,117 @@ function isMiniProgramDirectoryRef(value) {
     }
     return (isMiniProgramPathRootRef(value.root) && (value.relativePath === '.' || isMiniProgramRelativePath(value.relativePath)) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
 }
+/**
+ * 判断未知值是否为使用普通 `ArrayBuffer` 存储的 `Uint8Array` 字节视图。
+ *
+ * @param value - 来自 bridge payload、Host 返回值或其他不可信边界的候选字节数据。
+ * @returns 值是当前 realm 的 `Uint8Array`（或其子类），且 `buffer` 是 `ArrayBuffer` 时返回 `true`，
+ * 并将 TypeScript 类型收窄为 `Uint8Array`；否则返回 `false`。
+ *
+ * @remarks
+ * `Uint8Array` 的每个索引元素由 JavaScript 保证为 `0` 到 `255` 的整数。本 guard 接受空视图、非零
+ * `byteOffset` 以及只覆盖底层 buffer 一部分的视图；它不要求视图覆盖整个 `ArrayBuffer`，也不限制
+ * `byteLength`、文件大小或 Companion stdio 消息大小。
+ *
+ * 普通数组无论是否稀疏、`ArrayBuffer` 本身、`DataView`、`Int8Array`、`Uint8ClampedArray` 及其他 typed array
+ * 都会被拒绝。使用 `SharedArrayBuffer` 作为 backing buffer 的 `Uint8Array` 也会被拒绝。由于判断依赖
+ * `instanceof`，由另一个 JavaScript realm 创建且未经过 structured clone 重建的 `Uint8Array` 可能无法通过；
+ * 当前 realm 的 `Uint8Array` 子类则可能通过。
+ *
+ * 该函数不会枚举键，因此挂在 `Uint8Array` 实例上的额外自有属性不会导致失败；它也不会检查 buffer
+ * 是否已 detached、数据来源是否可信、内容是否符合业务格式，或调用方是否拥有文件/Companion 权限。
+ * 返回 `true` 后仍得到原来的可变视图，而不是副本或冻结值。跨异步边界持有或交给其他消费者前，建议使用
+ * `new Uint8Array(value)` 创建只包含当前视图字节的快照。
+ *
+ * 文件 `readBytes()` 用它识别 Host 返回的
+ * [FileReadBytesResult](/reference/symbols/protocol/types/FileReadBytesResult)，`writeBytes()` 的
+ * [FileWriteBytesPayload](/reference/symbols/protocol/interfaces/FileWriteBytesPayload) `content` 也采用同一字节表示；
+ * 路径、句柄类型和访问模式由文件引用与 descriptor guards 单独校验。Companion stdio 的 stdin、stdout 和 stderr
+ * 同样传输 `Uint8Array`，但 Session ownership、controller generation、stream、sequence、framing、容量与权限
+ * 都不属于本 guard 的职责。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramByteArray } from '@heybox/hb-sdk/protocol';
+ *
+ * const candidate: unknown = new Uint8Array([0, 128, 255]);
+ * if (!isMiniProgramByteArray(candidate)) {
+ *   throw new TypeError('需要 ArrayBuffer-backed Uint8Array');
+ * }
+ *
+ * // guard 只做结构收窄；复制后再跨异步边界使用。
+ * const snapshot = new Uint8Array(candidate);
+ *
+ * isMiniProgramByteArray([0, 128, 255]); // false：普通数组不是 wire 字节视图
+ * isMiniProgramByteArray(new DataView(new ArrayBuffer(3))); // false
+ * ```
+ *
+ * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) `readBytes()` 与 `writeBytes()` 的业务入口。
+ * @see [FileReadBytesResult](/reference/symbols/protocol/types/FileReadBytesResult) 文件二进制读取结果。
+ * @see [FileWriteBytesPayload](/reference/symbols/protocol/interfaces/FileWriteBytesPayload) 文件二进制写入 payload。
+ * @see [CompanionStdio](/reference/symbols/root/interfaces/CompanionStdio) Companion 原始字节 stdin/stdout/stderr。
+ * @see [isMiniProgramFileDescriptor](/reference/symbols/protocol/functions/isMiniProgramFileDescriptor) 文件 descriptor guard。
+ * @see [isMiniProgramDirectoryDescriptor](/reference/symbols/protocol/functions/isMiniProgramDirectoryDescriptor) 目录 descriptor guard。
+ */
 function isMiniProgramByteArray(value) {
     return value instanceof Uint8Array && value.buffer instanceof ArrayBuffer;
 }
+/**
+ * 判断未知值是否具有文件元数据快照的最低 wire 结构。
+ *
+ * @param value - 来自 `file.stat` Host 返回值、bridge response 或其他不可信边界的候选元数据。
+ * @returns `kind`、`size` 与可选时间字段满足 {@link MiniProgramFileStat} 结构时返回 `true`，并将
+ * TypeScript 类型收窄为文件元数据；否则返回 `false`。
+ *
+ * @remarks
+ * 对通常的对象字面量，仅允许 `kind`、`size`、`modifiedAt`、`createdAt` 四个 canonical key：
+ *
+ * - `kind` 必须固定为 `'file'`。
+ * - `size` 必须是 `0` 到 `Number.MAX_SAFE_INTEGER` 范围内的整数。`0` 表示空文件；负数、小数、`NaN`、
+ *   `Infinity`、unsafe integer、bigint 和数字字符串都会被拒绝。文件 API 将该值解释为字节数，但本 guard
+ *   只验证数字结构，不能证明 Host 使用了正确单位。
+ * - `modifiedAt` 与 `createdAt` 相互独立且都可省略，也可显式为 `undefined`；提供时必须是非负有限 number。
+ *   与 `size` 不同，时间值不要求是整数或 safe integer，因此非负小数以及大于 `Number.MAX_SAFE_INTEGER`
+ *   但仍有限的值都可通过。
+ *
+ * 文件 API 把时间字段解释为 Unix epoch milliseconds，但该 guard 不验证值是否落在 JavaScript `Date`
+ * 可表示范围内，也不要求 `createdAt <= modifiedAt`、时间不晚于当前时刻，或两项同时存在。消费者若要排序、
+ * 格式化或比较时间，仍须按自己的业务范围继续校验。
+ *
+ * canonical 集合之外的可枚举自有字符串键会导致失败，包括值为 `undefined` 的额外键；非枚举属性、
+ * symbol 键和继承属性不在 `Object.keys()` 检查范围内，必需字段本身也不要求是自有或可枚举属性。
+ * 该函数不会复制、冻结或规范化输入，返回的仍是原始可变对象。
+ *
+ * 返回 `true` 只建立结构类型收窄，不证明该快照来自可信 Host、对应当前 `FileHandle` 或当前 request，也不证明
+ * 文件仍然存在、`size` 与磁盘内容一致、时间由文件系统提供、handle 属于当前 session/origin、`filesystem`
+ * 权限已启用或 Host 支持 `file.stat`。这些关联、权限与 I/O 错误必须由 Runtime 和 `FileHandle.stat()` 调用链处理。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramFileStat } from '@heybox/hb-sdk/protocol';
+ *
+ * const candidate: unknown = {
+ *   kind: 'file',
+ *   size: 4096,
+ *   modifiedAt: 1_795_027_200_000,
+ * };
+ *
+ * if (isMiniProgramFileStat(candidate)) {
+ *   console.log(`${candidate.size} bytes`);
+ *   if (candidate.modifiedAt !== undefined) {
+ *     console.log(candidate.modifiedAt);
+ *   }
+ * }
+ *
+ * isMiniProgramFileStat({ kind: 'file', size: 0 }); // true：时间字段可全部省略
+ * isMiniProgramFileStat({ kind: 'file', size: 1.5 }); // false：size 必须是 safe integer
+ * ```
+ *
+ * @see [MiniProgramFileStat](/reference/symbols/protocol/interfaces/MiniProgramFileStat) bridge 使用的元数据字段类型。
+ * @see [FileStatResult](/reference/symbols/protocol/types/FileStatResult) `file.stat` 的 wire 返回类型。
+ * @see [FileStat](/reference/symbols/root/interfaces/FileStat) SDK 向业务返回的元数据快照。
+ * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 提供 `stat()` 的当前 session 文件代理。
+ */
 function isMiniProgramFileStat(value) {
     return (isRecord$2(value) &&
         value.kind === 'file' &&
@@ -702,6 +1156,58 @@ function isMiniProgramFileStat(value) {
         (value.createdAt === undefined || isNonNegativeFiniteNumber(value.createdAt)) &&
         hasOnlyKeys(value, ['kind', 'size', 'modifiedAt', 'createdAt']));
 }
+/**
+ * 判断未知值是否为单个 `network.download` 进度 payload。
+ *
+ * @param value - 来自 operation progress 事件、Host adapter 或其他不可信边界的候选进度快照。
+ * @returns 字段组合满足 {@link DownloadProgressPayload} 的最低 wire 约束时返回 `true`，并将 TypeScript
+ * 类型收窄为下载进度 payload；否则返回 `false`。
+ *
+ * @remarks
+ * 对通常的对象字面量，仅允许 `loaded`、`total`、`lengthComputable` 三个 canonical key，并执行以下组合校验：
+ *
+ * - `loaded` 始终必需，必须是 `0` 到 `Number.MAX_SAFE_INTEGER` 范围内的整数。负数、小数、`NaN`、
+ *   `Infinity`、unsafe integer、bigint 和数字字符串都会被拒绝。
+ * - `lengthComputable` 必须是 boolean，不能使用 `0` / `1` 或其他 truthy/falsy 值代替。
+ * - `lengthComputable === false` 时，`total` 必须为 `undefined`；既可以省略该 key，也可以显式写成
+ *   `total: undefined`。此分支不对 `loaded` 应达到的最终值作推断。
+ * - `lengthComputable === true` 时，`total` 必须是非负 safe integer，且 `loaded <= total`。
+ *   `{ loaded: 0, total: 0, lengthComputable: true }` 是有效的空内容进度。
+ *
+ * canonical 集合之外的可枚举自有字符串键会导致失败；非枚举属性、symbol 键和继承属性不在
+ * `Object.keys()` 检查范围内，必需字段本身也不要求是自有或可枚举属性。该函数不会复制、冻结或
+ * 规范化输入。类型谓词只收窄到字段仍为可变、`total` 仍为可选的 {@link DownloadProgressPayload}，
+ * 不会在 TypeScript 中建立以 `lengthComputable` 为判别字段的精确联合。
+ *
+ * 单个 payload 通过不表示进度来自当前 request、使用当前 pending operation 的 ID，或由可信 Host 产生；
+ * 也不保证单位确为字节、事件按时间排序、`loaded` 相对前一事件单调、`total` 跨事件稳定、这是最终进度，
+ * 或对应字节已经原子提交到目标文件。`network.download` 的 Runtime 状态机必须另行绑定 request ID，校验
+ * 可信响应 framing、`maxBytes`、取消与终态，并过滤倒退或越界值。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramDownloadProgressPayload } from '@heybox/hb-sdk/protocol';
+ *
+ * function renderProgress(candidate: unknown) {
+ *   if (!isMiniProgramDownloadProgressPayload(candidate)) return;
+ *
+ *   if (candidate.lengthComputable && candidate.total !== undefined) {
+ *     console.log(`${candidate.loaded}/${candidate.total}`);
+ *   } else {
+ *     console.log(`${candidate.loaded} bytes`);
+ *   }
+ * }
+ *
+ * renderProgress({ loaded: 512, total: 1024, lengthComputable: true }); // valid
+ * renderProgress({ loaded: 512, lengthComputable: false }); // valid：总长度未知
+ * renderProgress({ loaded: 5, total: 4, lengthComputable: true }); // ignored：loaded > total
+ * ```
+ *
+ * @see [DownloadProgressPayload](/reference/symbols/protocol/interfaces/DownloadProgressPayload) bridge 使用的进度字段类型。
+ * @see [DownloadProgress](/reference/symbols/root/interfaces/DownloadProgress) `onProgress` 接收的公开 SDK 进度类型。
+ * @see [network.download](/reference/sdk/network/download) 产生并消费该进度的下载能力。
+ * @see [isMiniProgramBridgeMessage](/reference/symbols/protocol/functions/isMiniProgramBridgeMessage) operation progress envelope 的最低校验。
+ */
 function isMiniProgramDownloadProgressPayload(value) {
     if (!isRecord$2(value) ||
         !isNonNegativeSafeInteger(value.loaded) ||
@@ -835,7 +1341,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.2-alpha.1';
+    : '0.8.2-alpha.5';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);
@@ -1384,12 +1890,24 @@ function waitForHandshakeOrAbort(handshake, signal, createAbortError, getTermina
     });
 }
 
-/** 获取短期授权码。 */
+/**
+ * 获取短期授权码。
+ *
+ * @param requester - SDK 内部的能力请求器。
+ * @param options - 可选的资料 scope；不传时不附带请求载荷。
+ * @returns 与 {@link MiniProgramAuthModule.login} 相同的授权码结果。
+ * @throws {@link HbMiniProgramSDKError} 当 Host 拒绝请求、用户取消授权或 SDK 状态无效时抛出。
+ */
 function login(requester, options) {
     const payload = options?.scopes === undefined ? undefined : { scopes: options.scopes };
     return requester.request(AUTH_LOGIN_METHOD, payload);
 }
-/** 创建授权模块。 */
+/**
+ * 创建授权模块。
+ *
+ * @param requester - SDK 内部的能力请求器。
+ * @returns 绑定到该 requester 的授权模块。
+ */
 function createAuthModule(requester) {
     return {
         login: (options) => login(requester, options),
@@ -2039,9 +2557,35 @@ function createCompanionModule(requester) {
  * 复制当前小程序的通用分享链接。
  *
  * @param requester - 底层 bridge 请求能力。
- * @param options - 分享扩展数据；不传时复制默认首页链接。
- * @returns 已写入系统剪贴板的完整分享链接。
- * @throws {@link HbMiniProgramSDKError} 当参数、bridge、父容器或剪贴板能力调用失败时抛出。
+ * @param options - 可选配置；只接受本次链接需要携带的 `extra`。省略 `options` 或
+ * `options.extra` 时生成不带扩展数据的链接。
+ * @returns Host 完成剪贴板写入后 resolve 的完整分享链接；返回字符串与剪贴板内容一致。
+ * @throws {@link HbMiniProgramSDKError} 参数、`extra` 编码或小程序身份不合法时返回
+ * `INVALID_PARAMS`；未声明或未启用 `share` 权限时分别返回
+ * `PERMISSION_NOT_DECLARED` 或 `PERMISSION_DENIED`；当前 Host 未开放剪贴板能力时可返回
+ * `METHOD_FORBIDDEN` 或 `REQUEST_UNSUPPORTED`。握手、bridge 超时和其他 Host 写入失败会保留
+ * 对应错误码。
+ *
+ * @remarks 该方法生成当前小程序的固定通用落地页，不复制当前页面路径或 hash，也不继承
+ * 启动 URL 中已有的 `extra`。显式传入的 `extra` 会先编码，再作为 Base64URL 参数写入链接；
+ * 接收方使用 {@link MiniProgramShareModule.getExtra | share.getExtra} 读取还原值。
+ *
+ * 该调用需要声明 `share` 权限，但不额外要求 `clipboard` 权限或可信用户手势。它只写入
+ * 系统剪贴板，不会打开分享面板或自动显示成功提示。
+ *
+ * @example
+ * ```ts
+ * import hbSDK from '@heybox/hb-sdk'
+ *
+ * const copiedUrl = await hbSDK.share.copyLink({
+ *   extra: { page: 'ranking', season: 12 },
+ * })
+ *
+ * console.log('已复制分享链接', copiedUrl)
+ * ```
+ *
+ * @see {@link MiniProgramShareModule.getExtra | share.getExtra}
+ * @see {@link MiniProgramShareModule.showShareMenu | share.showShareMenu}
  */
 function copyLink(requester, options) {
     return requester.request(SHARE_COPY_LINK_METHOD, options);
@@ -3242,9 +3786,16 @@ function decodeBase64Url(value) {
  * 截图并唤起分享。
  *
  * @param requester - 底层 bridge 请求能力。
- * @param options - 截图区域、延迟与保存相册等配置。
- * @returns 由宿主客户端协议决定的结果。
- * @throws {@link HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ * @param options - 可选截图配置；省略时截取当前可见窗口。
+ * @returns Host 返回的不透明截图分享结果；不要依赖其具体结构。
+ * @throws {@link HbMiniProgramSDKError} 参数、权限、bridge、Runtime 或 Host 截图能力失败时抛出。
+ *
+ * @remarks
+ * 公开业务代码通常通过 {@link MiniProgramShareModule.screenshot | share.screenshot} 调用；
+ * 完整参数、平台和恢复语义见该方法。
+ *
+ * @see {@link MiniProgramShareModule.screenshot | share.screenshot}
+ * @see {@link MiniProgramScreenshotOptions}
  */
 function screenshot(requester, options) {
     return requester.request(SHARE_SCREENSHOT_METHOD, options);
@@ -3254,9 +3805,12 @@ function screenshot(requester, options) {
  * 展示以当前小程序通用分享页为落地页的基础分享面板。
  *
  * @param requester - 底层 bridge 请求能力。
- * @param options - 基础分享参数。
- * @returns 由宿主客户端协议决定的结果。
- * @throws {@link HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ * @param options - 标题、描述，以及可选缩略图、渠道、扩展数据和社区发帖预置。
+ * @returns Host 分享面板返回的 `unknown` 不透明值；不能依赖字段或真假值判断分享结果。
+ * @throws {@link HbMiniProgramSDKError} 参数、固定落地页身份、`extra` 或开发态 `post` 校验失败
+ * 时返回 `INVALID_PARAMS`；权限、Host 能力及生命周期错误见公开模块方法文档。
+ * @remarks 不支持自定义 `url`、宿主回调或直接发布；社区预置仍由用户在客户端修改确认。
+ * @see [share.showShareMenu](/reference/sdk/share/showShareMenu)
  */
 function showShareMenu(requester, options) {
     return requester.request(SHARE_SHOW_SHARE_MENU_METHOD, options);
@@ -3266,6 +3820,7 @@ function showShareMenu(requester, options) {
  * 创建分享模块。
  *
  * @param requester - 底层 bridge 请求能力。
+ * @param launchHref - 可选的小程序启动 URL；`getExtra()` 从这里同步解析分享扩展数据。
  * @returns 面向业务层的分享模块对象。
  */
 function createShareModule(requester, launchHref) {
@@ -3651,7 +4206,14 @@ function isDirectChildFileRef(directory, file) {
 function invalidDownloadResult(message) {
     throw createSDKError('INVALID_NETWORK_RESPONSE', message);
 }
-/** 发起不使用 bridge 固定总时长 timer 的流式下载。 */
+/**
+ * 发起不使用 bridge 固定总时长 timer 的流式下载。
+ *
+ * @param requester - 支持 request-scoped 取消与进度的 bridge 请求能力。
+ * @param options - 下载地址、受控写入目标、限制、取消信号与进度回调。
+ * @returns 原子提交完成后的 File 代理。
+ * @throws {@link HbMiniProgramSDKError} 参数、权限、目标、网络、取消或 Host 响应不符合公开合同时抛出。
+ */
 async function download(requester, options) {
     if (options?.signal?.aborted) {
         throw createSDKError('DOWNLOAD_CANCELLED', '下载已取消');
@@ -3848,18 +4410,46 @@ function createViewportModule(requester) {
 /**
  * 获取当前访问小程序用户的公开基础资料。
  *
- * @returns 当前用户的登录态与公开基础资料。
+ * @param requester - SDK 内部的 bridge 请求器；业务代码应通过 `hbSDK.user.getInfo()` 调用。
+ * @returns 以 `isHeyboxAppLoggedIn` 为判别字段的登录态、用户授权状态和已获准披露资料。
  *
- * 未开通网络权限且当前黑盒 APP 用户已登录时，该能力会静默建立或读取按小程序隔离的
- * `app_user_id`，并隐式授予 `identity` 与 `profile` 后返回昵称与头像，不展示授权 UI。未登录时返回
- * `{ isHeyboxAppLoggedIn: false, authorization: null, userInfo: null }`。
+ * @throws {@link HbMiniProgramSDKError} `userInfo` 未声明或不可用、握手失败、Host 不支持该能力、
+ * 当前小程序身份缺失、账号/隔离身份读取失败、返回结构不合法、Runtime 终止，或请求期间
+ * 账号与授权上下文变化时抛出。
  *
- * @throws {@link HbMiniProgramSDKError} 当 SDK 调用失败时抛出。
+ * @remarks
+ * 当前账号未登录属于正常返回分支，不抛错。账号已登录时，该能力不展示授权 UI，也不要求
+ * 可信用户手势；Runtime 会静默建立或读取当前小程序的隔离 `app_user_id`，并授予
+ * `identity` 与 `profile`。它只要求 Manifest 中声明 `userInfo`，不要求公开 `network`
+ * 权限，也不返回可供服务端换票的授权码。
+ *
+ * @example
+ * ```ts
+ * const result = await hbSDK.user.getInfo()
+ * if (!result.isHeyboxAppLoggedIn) {
+ *   showLoginHint()
+ * } else if (result.userInfo) {
+ *   renderUser(result.userInfo.app_user_id, result.userInfo.profile)
+ * }
+ * ```
+ *
+ * @see [auth.login](/reference/sdk/auth/login)
+ * @see [user.revokeAuthorization](/reference/sdk/user/revokeAuthorization)
  */
 function getInfo(requester) {
     return requester.request(USER_GET_INFO_METHOD);
 }
 
+/**
+ * 撤销当前用户授予本小程序的授权。
+ *
+ * @param requester - 底层 bridge 请求能力。
+ * @returns 撤销完成后 resolve `undefined`。
+ * @throws {@link HbMiniProgramSDKError} 缺少可信用户手势、当前用户未登录、Host 请求失败、
+ * 账号上下文变化或 SDK / Runtime 已终止时抛出；具体稳定错误码见公开模块方法文档。
+ * @remarks 该能力无需 Manifest 权限；撤销成功后由调用方清理自己的持久化数据和服务端会话。
+ * @see [user.revokeAuthorization](/reference/sdk/user/revokeAuthorization)
+ */
 function revokeAuthorization(requester) {
     return requester.request(USER_REVOKE_AUTHORIZATION_METHOD);
 }
@@ -3868,8 +4458,12 @@ function revokeAuthorization(requester) {
  * 获取当前用户 Steam 游戏库。
  *
  * @param requester - 底层 bridge 请求能力。
- * @param options - 查询与分页参数。
- * @returns 当前用户 Steam 游戏库；未登录或未绑定 Steam 时返回状态对象。
+ * @param options - 查询与分页参数；省略时采用默认 Steam 账号、分页和排序。
+ * @returns 登录态、Steam 绑定态以及绑定成功时的规范化分页数据。
+ * @throws {@link HbMiniProgramSDKError} 参数、权限、Host 能力、服务端响应、账号上下文或
+ * SDK 生命周期不满足要求时抛出；具体稳定错误码见公开模块方法文档。
+ * @remarks 该能力要求 `steamLibrary`，但不要求公开 `network` 权限或可信用户手势。
+ * @see [user.getSteamGameList](/reference/sdk/user/getSteamGameList)
  */
 function getSteamGameList(requester, options) {
     return requester.request(USER_GET_STEAM_GAME_LIST_METHOD, options);
@@ -3883,19 +4477,44 @@ function createUserModule(requester) {
     };
 }
 
-/** 展示 toast。 */
+/**
+ * 通过底层 bridge 展示 Toast。
+ *
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - Toast 文案与可选语义状态。
+ * @returns Host 接受并应用展示请求后 resolve。
+ * @throws {@link HbMiniProgramSDKError} 参数、bridge、Runtime 或 Host 调用失败时抛出。
+ */
 function showToast(requester, options) {
     return requester.request(UI_SHOW_TOAST_METHOD, options);
 }
-/** 展示全局 loading。 */
+/**
+ * 通过底层 bridge 展示或更新全局 Loading。
+ *
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - 可选展示配置；省略时使用不可手动关闭的 Loading。
+ * @returns Host 接受并应用展示请求后 resolve。
+ * @throws {@link HbMiniProgramSDKError} 参数、bridge、Runtime 或 Host 调用失败时抛出。
+ */
 function showLoading(requester, options) {
     return requester.request(UI_SHOW_LOADING_METHOD, options ?? {});
 }
-/** 隐藏全局 loading。 */
+/**
+ * 通过底层 bridge 请求隐藏全局 Loading。
+ *
+ * @param requester - 底层 bridge 请求能力。
+ * @returns Host 接受隐藏请求后 resolve。
+ * @throws {@link HbMiniProgramSDKError} bridge、Runtime 或 Host 调用失败时抛出。
+ */
 function hideLoading(requester) {
     return requester.request(UI_HIDE_LOADING_METHOD);
 }
-/** 创建 UI 模块。 */
+/**
+ * 创建绑定到指定 bridge requester 的 UI 模块。
+ *
+ * @param requester - 底层 bridge 请求能力。
+ * @returns 可供 Mini-program 调用的 UI 模块。
+ */
 function createUiModule(requester) {
     return {
         showToast: (options) => showToast(requester, options),
@@ -4005,15 +4624,41 @@ function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-/** 请求宿主关闭当前小程序容器。 */
+/**
+ * 请求宿主关闭当前小程序容器。
+ *
+ * @param requester - 底层 bridge 请求能力。
+ * @returns Host 接受关闭请求后 resolve `undefined`；当前页面上下文随后可能立即终止。
+ * @throws {@link HbMiniProgramSDKError} Host 能力缺失、关闭失败或 SDK / Runtime 已终止时抛出。
+ * @remarks 必须完成的持久化工作应在调用前结束；该能力无需 Manifest 权限或可信用户手势。
+ * @see [navigation.close](/reference/sdk/navigation/close)
+ */
 function close(requester) {
     return requester.request(NAVIGATION_CLOSE_METHOD);
 }
-/** 请求宿主重载当前小程序容器。 */
+/**
+ * 请求宿主重载当前小程序容器。
+ *
+ * @param requester - 底层 bridge 请求能力。
+ * @returns Host 接受 reload 请求后 resolve `undefined`；旧页面上下文随后会被替换。
+ * @throws {@link HbMiniProgramSDKError} Host 能力缺失、reload 失败或 SDK / Runtime 已终止时抛出。
+ * @remarks 跨页面状态应在调用前持久化；该能力无需 Manifest 权限或可信用户手势。
+ * @see [navigation.reload](/reference/sdk/navigation/reload)
+ */
 function reload(requester) {
     return requester.request(NAVIGATION_RELOAD_METHOD);
 }
-/** 请求宿主打开受 SDK 白名单约束的黑盒 App 页面。 */
+/**
+ * 请求宿主打开受 SDK 白名单约束的黑盒 App 页面。
+ *
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - 由 `target` 判别的目标页参数；发送前会校验并规范化。
+ * @returns Host 发起受控页面路由后 resolve `undefined`。
+ * @throws {@link HbMiniProgramSDKError} 参数非法、目标不受 Host 支持、路由失败或 SDK /
+ * Runtime 已终止时抛出。
+ * @remarks 该能力不接受任意 URL 或内部路由，也无需 Manifest 权限或可信用户手势。
+ * @see [navigation.openAppPage](/reference/sdk/navigation/openAppPage)
+ */
 function openAppPage(requester, options) {
     try {
         return requester.request(NAVIGATION_OPEN_APP_PAGE_METHOD, normalizeOpenAppPageOptions(options));
@@ -4245,6 +4890,66 @@ function getDefaultSDK() {
 /**
  * 获取默认 SDK 实例的当前握手状态。
  *
+ * @returns 当前冻结的
+ * [MiniProgramSDKHandshakeState](/reference/symbols/root/types/MiniProgramSDKHandshakeState)：
+ * `connecting` 表示初始握手尚未落定，`ready` 表示握手成功；`failed` 表示握手失败，并通过
+ * `error` 保留原始
+ * [HbMiniProgramSDKError](/reference/symbols/root/classes/HbMiniProgramSDKError)。状态不变期间重复调用
+ * 返回同一个对象引用，落定时只会替换一次。
+ *
+ * @remarks
+ * 该函数不接收参数并同步返回当前快照，不等待 Promise、不轮询、不发送 bridge 请求，也不会因为
+ * 握手失败而抛出 `failed.error`。读取状态无需在 `package.json#heybox.permissions` 中声明权限，
+ * 不要求可信用户手势。根包导入时已经自动启动握手；普通异步能力调用也会自行等待，不需要用本
+ * API 手动实现等待器。
+ *
+ * 状态 wrapper 已浅冻结。状态机只允许 `connecting -> ready` 或 `connecting -> failed` 一次迁移，
+ * 终态不会回退或互相转换；`failed.error` 是握手 Promise 使用的同一个原始错误实例，可根据稳定的
+ * `code` 分支处理。常见初始失败包括 `NOT_IN_IFRAME`、`MISSING_NONCE`、`READY_TIMEOUT`、
+ * `HANDSHAKE_FAILED`、`RUNTIME_UNAVAILABLE` 或握手完成前的 `SDK_DESTROYED`。
+ *
+ * 需要让界面跟随状态变化时，使用
+ * [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange)：它会在订阅期间同步回放
+ * 当前值，再通知至多一次终态迁移。不要轮询本函数。对于必须保留原始可信用户手势的按钮，可用
+ * 该持久状态提前控制 `disabled`，但不要在点击回调里等待握手。
+ *
+ * [on('ready')](/reference/sdk/lifecycle/on) 是握手成功瞬间的事件：不会向晚订阅者重放，Host 重复
+ * 派发时也可能再次触发事件 handler；持久状态则只迁移一次并始终可查询。`ready` 只表示初始握手
+ * 已成功，后续 `unload` 不会把状态改回 `failed`，因此不能把它当作 Runtime 持续存活检查。
+ *
+ * SDK 会在发布 `ready` 状态前缓存环境快照，所以 `status === 'ready'` 时可以立即调用
+ * [environment.getInfoSync()](/reference/sdk/environment/getInfoSync)。`failed` 时该同步环境 API 会抛出
+ * 同一个 `state.error`；不要求同步读取时，优先使用会自动等待的
+ * [environment.getInfo()](/reference/sdk/environment/getInfo)。
+ *
+ * @example
+ * ```ts
+ * import hbSDK from '@heybox/hb-sdk'
+ *
+ * const state = hbSDK.getHandshakeState()
+ *
+ * switch (state.status) {
+ *   case 'connecting':
+ *     submitButton.disabled = true
+ *     break
+ *   case 'ready': {
+ *     submitButton.disabled = false
+ *     const environment = hbSDK.environment.getInfoSync()
+ *     console.log(environment.runtime.mode)
+ *     break
+ *   }
+ *   case 'failed':
+ *     submitButton.disabled = true
+ *     console.error('SDK 握手失败', state.error.code)
+ *     break
+ * }
+ * ```
+ *
+ * @see [MiniProgramSDKHandshakeState](/reference/symbols/root/types/MiniProgramSDKHandshakeState) 三种状态及冻结语义。
+ * @see [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange) 同步回放当前状态并订阅终态迁移。
+ * @see [on('ready')](/reference/sdk/lifecycle/on) 不可重放的生命周期边沿事件。
+ * @see [environment.getInfoSync()](/reference/sdk/environment/getInfoSync) 在 `ready` 后同步读取环境快照。
+ *
  * @since 0.7.0-alpha.9
  * @hbPlatform android
  * @hbPlatform ios
@@ -4263,6 +4968,83 @@ function getHandshakeState() {
 /**
  * 订阅默认 SDK 实例的握手状态，并立即接收当前状态。
  *
+ * @param handler - 接收
+ * [MiniProgramSDKHandshakeState](/reference/symbols/root/types/MiniProgramSDKHandshakeState) 的处理函数。
+ * 注册期间会在本函数返回前同步调用一次：`connecting` 表示初始握手仍在进行，`ready` 表示成功，
+ * `failed.error` 是原始
+ * [HbMiniProgramSDKError](/reference/symbols/root/classes/HbMiniProgramSDKError)。
+ * @returns 从默认 SDK 状态 store 移除当前 handler 的 unsubscribe。调用一次或多次都返回 `void` 且
+ * 不会抛错；取消后不再接收未来迁移，但不会撤销已经同步回放的当前状态。
+ *
+ * @remarks
+ * 订阅是纯本地同步操作，不发送 bridge 请求、不等待握手，也无需在
+ * `package.json#heybox.permissions` 中声明权限或保留可信用户手势。根包导入时握手已经自动启动；
+ * 本 API 用于观察状态，不用于主动发起或重试握手。
+ *
+ * handler 会在加入订阅集合后、unsubscribe 返回前立即同步收到当前冻结状态：
+ *
+ * - 当前为 `connecting`：先立即收到 `connecting`，随后至多再收到一次 `ready` 或 `failed`；
+ * - 当前已是 `ready` 或 `failed`：立即收到该终态，之后不会再迁移；
+ * - 在终态通知过程中新增订阅：通过即时回放收到一次终态，不会因同一迁移重复调用。
+ *
+ * 状态只允许 `connecting -> ready` 或 `connecting -> failed`，终态不回退。`failed.error` 是握手失败
+ * 和同步环境读取使用的同一个原始错误实例，可按稳定的 `code` 分支处理。`ready` 只表示初始握手
+ * 已成功；后续 `unload` 不会把状态改回 `failed`，因此它不是 Runtime 持续存活探针。
+ *
+ * SDK 会逐个捕获 handler 的同步异常：初次即时回放或终态通知中抛错，都不会从本函数传播、改变
+ * 状态、阻断握手 Promise 或阻止其他订阅者收到通知。handler 返回值会被忽略，Promise 也不会被
+ * 等待；异步 handler 应在自身内部捕获 rejected Promise，避免未处理拒绝。
+ *
+ * 每个 handler 以 Set 语义保存；同一函数引用重复订阅只有一个未来通知注册，但每次调用本函数仍会
+ * 同步回放当前状态，任一 unsubscribe 都会移除该注册。应在页面、组件或业务模块销毁时调用
+ * unsubscribe。SDK 内部销毁会清空全部状态订阅；若销毁发生在握手落定前，会先发布携带
+ * `SDK_DESTROYED` 的 `failed`，再清空订阅。此后重复调用已经返回的 unsubscribe 仍是安全空操作。
+ * `unload` 发生在握手前时则以 `RUNTIME_UNAVAILABLE` 落为 `failed`；发生在 `ready` 后不会产生
+ * 第二次状态通知。
+ *
+ * 与 [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 相比，本 API 适合让 UI 自动跟随
+ * 唯一一次迁移，且即时回放意味着通常不需要先额外读取一次状态。
+ * [on('ready')](/reference/sdk/lifecycle/on) 则是不可重放、可能因 Host 重复事件再次触发的边沿通知，
+ * 不应用于驱动晚挂载按钮的可用状态。
+ *
+ * SDK 会在发布 `ready` 状态前缓存环境快照，因此可以在 `ready` handler 中立即调用
+ * [environment.getInfoSync()](/reference/sdk/environment/getInfoSync)。在 `failed` handler 中调用该
+ * API 会抛出同一个 `state.error`；一般异步读取可使用
+ * [environment.getInfo()](/reference/sdk/environment/getInfo) 自动等待。
+ *
+ * @example
+ * ```ts
+ * import hbSDK from '@heybox/hb-sdk'
+ *
+ * const stop = hbSDK.onHandshakeStateChange(state => {
+ *   switch (state.status) {
+ *     case 'connecting':
+ *       submitButton.disabled = true
+ *       statusText.textContent = '正在连接'
+ *       break
+ *     case 'ready':
+ *       submitButton.disabled = false
+ *       statusText.textContent = hbSDK.environment.getInfoSync().runtime.mode
+ *       break
+ *     case 'failed':
+ *       submitButton.disabled = true
+ *       statusText.textContent = `连接失败：${state.error.code}`
+ *       break
+ *   }
+ * })
+ *
+ * // 页面或组件真正销毁时执行；重复取消也安全。
+ * window.addEventListener('unload', () => {
+ *   stop()
+ *   stop()
+ * }, { once: true })
+ * ```
+ *
+ * @see [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 一次性同步读取当前持久状态。
+ * @see [on('ready')](/reference/sdk/lifecycle/on) 不可重放的握手成功边沿事件。
+ * @see [environment.getInfoSync()](/reference/sdk/environment/getInfoSync) 在 `ready` handler 中同步读取环境。
+ * @see [事件与生命周期](/guide/lifecycle) 握手与普通生命周期事件的使用建议。
+ *
  * @since 0.7.0-alpha.9
  * @hbPlatform android
  * @hbPlatform ios
@@ -4281,9 +5063,83 @@ function onHandshakeStateChange(handler) {
 /**
  * 注册默认 SDK 实例的事件监听。
  *
- * @param eventName - 要监听的事件名。
- * @param handler - 事件处理函数。
- * @returns 事件解绑函数。
+ * @param eventName - 要监听的
+ * [MiniProgramEventName](/reference/symbols/root/types/MiniProgramEventName)。泛型 `T` 通常由该字符串
+ * 字面量推断，并决定 handler 的 payload 类型。
+ * @param handler - 与 `eventName` 对应的
+ * [MiniProgramEventHandler](/reference/symbols/root/types/MiniProgramEventHandler)。payload 由
+ * [MiniProgramEventPayloadMap](/reference/symbols/root/interfaces/MiniProgramEventPayloadMap) 精确映射。
+ * @returns 只解绑当前 `eventName` / handler 组合的函数。调用一次或多次都返回 `void` 且不会抛错，
+ * 不影响同一事件上的其他 handler。
+ *
+ * @remarks
+ * 事件名决定 payload 字段：
+ *
+ * - `launch`：`{ timestamp, url? }`；`ready`：`{ timestamp }`；
+ * - `show` / `hide`：`{ timestamp, source? }`；`unload`：`{ timestamp }`；
+ * - `error`：
+ *   [MiniProgramBridgeError](/reference/symbols/protocol/interfaces/MiniProgramBridgeError)，包含 `code`、
+ *   `message` 与可选 `data`，不是 JavaScript `Error` 实例；
+ * - `heybox_app_login_change`：`{ isHeyboxAppLoggedIn }`；
+ * - `user_info_authorization_change`：
+ *   [UserInfoAuthorization](/reference/symbols/root/interfaces/UserInfoAuthorization)，包含 `identity` 与
+ *   `profile` 两项授权状态；
+ * - `companion.session.output`：`{ sessionId, controllerGeneration, stream, sequence, data }`；
+ * - `companion.session.exit`：`{ sessionId, exit }`；
+ * - `companion.session.ownershipLost`：`{ sessionId, controllerGeneration }`。
+ *
+ * `on()` 同步把 handler 加入默认 SDK 实例的本地 event bus，不等待握手、不发送 bridge 请求。
+ * 注册本身无需在 `package.json#heybox.permissions` 中声明权限，不要求可信用户手势，也不会因当前
+ * 握手处于 `connecting`、`ready` 或 `failed` 而抛出 SDK 错误。具体事件是否会产生，仍取决于 Host、
+ * Runtime 生命周期和相关业务能力。
+ *
+ * event bus 使用 Set 保存每个事件的 handler。同一事件与同一函数引用重复注册只有一个有效监听；
+ * 任一返回的 unsubscribe 或 [off()](/reference/sdk/lifecycle/off) 都会移除该唯一注册。不同函数引用
+ * 不会去重，同一函数注册到不同事件也彼此独立。应保存 unsubscribe，并在页面、组件或业务模块销毁
+ * 时调用；unsubscribe 可安全重复调用。
+ *
+ * handler 在事件派发时同步执行。SDK 不捕获普通事件 handler 的同步异常，也不等待其 Promise；某个
+ * handler 抛错可能阻断同次派发中的后续 handler，异步拒绝也可能成为未处理 Promise。需要隔离时在
+ * handler 内自行 `try/catch`，并显式处理异步任务的 rejected Promise。
+ *
+ * 所有生命周期与业务事件都不会重放：只派发给事件到达时已经注册的 handler，晚注册无法取回
+ * `launch`、`ready` 或其他历史事件。`ready` 只是握手成功瞬间的边沿通知，Host 重复派发时 handler
+ * 也可能再次执行；需要可查询、会向订阅者立即回放且只迁移一次的握手状态时，使用
+ * [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 和
+ * [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange)。
+ *
+ * 收到 `unload` 后当前 Runtime 上下文不可恢复，在途请求会失败，也不应再依赖后续 bridge 事件；
+ * SDK 内部销毁会移除底层 message listener。调用 unsubscribe 只清理该本地事件 handler，不取消
+ * API 请求、业务任务、Companion 进程或握手状态订阅。
+ *
+ * @example
+ * ```ts
+ * import hbSDK from '@heybox/hb-sdk'
+ *
+ * const stopShow = hbSDK.on('show', ({ timestamp, source }) => {
+ *   try {
+ *     refreshVisibleData({ timestamp, source })
+ *   } catch (error) {
+ *     reportHandlerError(error)
+ *   }
+ * })
+ *
+ * const stopError = hbSDK.on('error', ({ code, message }) => {
+ *   console.error(code, message)
+ * })
+ *
+ * // 页面或组件销毁时；重复调用也安全。
+ * stopShow()
+ * stopShow()
+ * stopError()
+ * ```
+ *
+ * @see [MiniProgramEventPayloadMap](/reference/symbols/root/interfaces/MiniProgramEventPayloadMap) 所有事件与 payload 字段。
+ * @see [off()](/reference/sdk/lifecycle/off) 使用事件名与 handler 引用精确移除监听。
+ * @see [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 同步读取持久握手状态。
+ * @see [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange) 订阅会立即回放的握手状态。
+ * @see [事件与生命周期](/guide/lifecycle) 生命周期时机与清理建议。
+ *
  * @since 0.2.0-alpha.0
  * @hbPlatform android
  * @hbPlatform ios
@@ -4302,9 +5158,57 @@ function on(eventName, handler) {
 /**
  * 移除默认 SDK 实例的事件监听。
  *
- * @param eventName - 要移除的事件名。
- * @param handler - 对应的事件处理函数。
- * @returns 无返回值。
+ * @param eventName - 注册 handler 时使用的同一个事件名。只检查该事件自己的监听集合，不影响
+ * 其他事件上的注册。
+ * @param handler - 传给 `on(eventName, handler)` 的同一个函数对象。签名或函数体相同的新函数不是
+ * 同一引用，不能移除原监听。
+ * @returns `void`。移除成功、目标从未注册或此前已经移除时都不返回状态。
+ *
+ * @remarks
+ * 该函数同步修改默认 SDK 实例的本地 event bus，不等待握手、不发送 bridge 请求，也不会调用
+ * handler。它无需在 `package.json#heybox.permissions` 中声明权限，不要求可信用户手势；握手处于
+ * `connecting`、`ready` 或 `failed`，以及已经收到 `unload` 时，取消操作本身都不会产生 SDK 错误。
+ *
+ * 匹配规则是 `eventName` 与 handler 函数引用同时相等。匹配后只移除这一项，同一事件上的其他
+ * handler、同一 handler 在其他事件上的注册均保留。event bus 对同一事件与同一函数引用使用集合
+ * 语义，重复 `on()` 只有一个有效注册，一次 `off()` 即会移除；重复调用 `off()` 是幂等的，未知事件
+ * 或未注册 handler 会被静默忽略。
+ *
+ * 大多数场景优先保存并调用 [on()](/reference/sdk/lifecycle/on) 返回的 unsubscribe：它已经闭包绑定
+ * 正确的事件名和 handler，同样可以重复调用。只有调用方需要在另一处按具名 handler 精确移除时，
+ * 才直接使用 `off()`。匿名函数必须先保存引用；重新创建一个内容相同的箭头函数无法取消旧监听。
+ *
+ * 生命周期与业务事件不会重放，只派发给事件到达时仍处于注册状态的 handler。`off()` 只阻止后续
+ * 事件，不能撤销已经执行的 handler，也不能取回注册前错过的 `launch`、`ready`、`show`、`hide`、
+ * `unload` 等事件。当前握手状态应通过
+ * [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 或
+ * [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange) 获取，不要通过重新注册
+ * `ready` 事件补状态。
+ *
+ * Runtime `unload` 或 SDK 内部销毁后不会再有可依赖的未来 bridge 生命周期事件，但调用 unsubscribe
+ * 或 `off()` 做本地清理仍可安全重复执行。取消监听不会取消已经开始的 API 请求、业务任务或
+ * `onHandshakeStateChange()` 订阅；后者必须调用其自己返回的取消函数。
+ *
+ * @example
+ * ```ts
+ * import hbSDK from '@heybox/hb-sdk'
+ *
+ * const pauseOnHide = () => pausePolling()
+ * const reportHide = () => reportVisibility('hidden')
+ *
+ * hbSDK.on('hide', pauseOnHide)
+ * const stopReporting = hbSDK.on('hide', reportHide)
+ *
+ * hbSDK.off('hide', pauseOnHide) // 只移除 pauseOnHide
+ * hbSDK.off('hide', pauseOnHide) // 已移除，仍然安全
+ * stopReporting()                // 推荐：使用 on() 返回的取消函数
+ * ```
+ *
+ * @see [on()](/reference/sdk/lifecycle/on) 注册事件并取得绑定好的取消函数。
+ * @see [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 同步读取持久握手状态。
+ * @see [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange) 订阅会立即回放的握手状态。
+ * @see [事件与生命周期](/guide/lifecycle) 生命周期事件列表与清理建议。
+ *
  * @since 0.2.0-alpha.0
  * @hbPlatform android
  * @hbPlatform ios