@heybox/hb-sdk 0.8.1 → 0.8.2-alpha.2

package/types/modules/storage/index.d.ts

@@ -1,31 +1,115 @@
 import type { MiniProgramRequester } from '../../core/client';
 export { STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD } from '../../protocol/capabilities';
-/** `storage.getStorage` 入参。 */
+/**
+ * `storage.getStorage` 入参。
+ *
+ * @remarks
+ * Runtime 只读取 `key`，不会把额外字段用于选择其他小程序或 Storage 区域。
+ */
 export interface GetStoragePayload {
-    /** storage key。 */
+    /**
+     * Storage key。
+     *
+     * @remarks
+     * 必须是非空字符串，默认仅支持 1 至 128 位 ASCII 字母、数字、下划线和连字符，
+     * 即匹配 `/^[A-Za-z0-9_-]+$/`；Host 可以配置不同的长度上限。空串、空白、路径
+     * 分隔符、点号、中文或超过上限的 key 会以 `INVALID_PARAMS` 拒绝，且不会读取 Host Storage。
+     */
     key: string;
 }
 /**
  * `storage.getStorage` 返回值。
  *
- * @typeParam T - 反序列化后的业务数据类型。
+ * @typeParam T - 调用方声明的业务数据类型；只影响 TypeScript，不会触发运行时校验或转换。
+ *
+ * @remarks
+ * 数据由 Host 原始字符串解码得出。业务若依赖精确结构，应在使用前自行校验 `data`，
+ * 不要把泛型参数当作数据迁移或 schema 校验。
  */
 export interface GetStorageResult<T = unknown> {
-    /** key 对应的数据；不存在时为 undefined。 */
+    /**
+     * key 对应的数据。合法 JSON 会按 `JSON.parse` 语义还原，因此对象、数组、字符串、
+     * 数字、布尔值和 `null` 均原样返回；key 不存在或旧 Host 保存了空字符串时为
+     * `undefined`。升级前遗留的非 JSON 原始值不会导致解析错误，而是以原字符串返回。
+     */
     data: T | undefined;
 }
-/** `storage.setStorage` 入参。 */
+/**
+ * `storage.setStorage` 入参。
+ *
+ * @remarks
+ * Runtime 只消费 `key` 与 `data`。调用方不能通过额外字段选择其他小程序、账号、版本或
+ * Storage 区域；实际作用域由 Host 提供的 canonical 小程序身份决定。
+ */
 export interface SetStoragePayload {
-    /** storage key。 */
+    /**
+     * Storage key。
+     *
+     * @remarks
+     * 必须是非空字符串，默认仅支持 1 至 128 位 ASCII 字母、数字、下划线和连字符，
+     * 即匹配 `/^[A-Za-z0-9_-]+$/`；Host 可以配置不同的长度上限。空串、空白、路径
+     * 分隔符、点号、中文或超过上限的 key 会以 `INVALID_PARAMS` 拒绝，且不会覆盖已有值。
+     */
     key: string;
-    /** 需要写入的数据。 */
+    /**
+     * 要写入的结构化数据；必须先能通过 iframe structured clone，再能被 `JSON.stringify` 序列化。
+     *
+     * @remarks
+     * Runtime 对跨 bridge 后的值执行 `JSON.stringify`。对象属性中的 `undefined` 会被省略，
+     * 数组中的 `undefined` 会变成 `null`；顶层 `undefined` 会以 `INVALID_PARAMS` 拒绝。
+     * `NaN` 与正负 `Infinity` 会序列化为 `null`。`BigInt` 和循环引用会使序列化失败，并以
+     * `INVALID_PARAMS` 拒绝。
+     *
+     * 不要依赖自定义 `toJSON`：函数不能通过 structured clone，自定义原型也不会作为公开
+     * bridge 合同保留。`Date` 是例外，其内建 `toJSON` 会把值序列化为 ISO 时间字符串。
+     * 函数、Symbol 或其他不可 structured-clone 的成员可能在请求到达 Host 前触发
+     * `DataCloneError`。
+     *
+     * Host 若配置写入配额，会在完整 JSON 字符串生成后按 UTF-8 字节数校验；引号、转义、
+     * 属性名和 JSON 结构字符均计入配额，中文等字符可能占多个字节。超限时返回
+     * `STORAGE_QUOTA_EXCEEDED`，且不会调用 Host Storage。
+     */
     data: unknown;
 }
 export type { MiniProgramStorageMethod } from '../../protocol/capabilities';
 /** 外部小程序可调用的 storage 模块。 */
 export interface MiniProgramStorageModule {
     /**
-     * 获取小程序隔离 storage。
+     * 读取当前小程序隔离 Storage 中的值。
+     *
+     * @typeParam T - 调用方期望的反序列化数据类型；SDK 不会在运行时校验该类型。
+     * @param options - 读取参数；`options.key` 必须符合 {@link GetStoragePayload.key} 的字符和长度约束。
+     * @returns Host 读取完成后 resolve 的结果。合法 JSON 会被反序列化；key 不存在或历史空串返回 `{ data: undefined }`，合法 JSON `null` 返回 `{ data: null }`，历史非 JSON 原始值返回原字符串。
+     * @throws {@link HbMiniProgramSDKError} 参数非法时返回 `INVALID_PARAMS`；未声明或未启用
+     * `storage` 权限时分别返回 `PERMISSION_NOT_DECLARED` 或 `PERMISSION_DENIED`；canonical
+     * identity 尚未就绪时返回 `INVALID_STATE`；Host 不支持或禁用能力时可返回
+     * `METHOD_NOT_FOUND` 或 `METHOD_FORBIDDEN`。其他 bridge 与 Host 读取错误会保留对应错误码。
+     *
+     * @remarks
+     * Storage 作用域由平台确认的 canonical 小程序身份决定，并在首次使用时固定；不能通过
+     * `key` 读取其他小程序或调试工具的值。未绑定身份的本地调试实例只能使用 Runtime
+     * 显式分配的临时隔离 scope，不会根据请求中的小程序 ID 或页面 URL 推导 scope。
+     *
+     * 该 API 需要在 `package.json#heybox.permissions` 声明并启用 `storage`，不要求可信用户
+     * 手势。读取本身没有 `setStorage` 的 JSON 序列化与 UTF-8 写入字节配额；配额在写入时
+     * 校验，已有值仍按上述兼容规则读取。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * type Settings = { theme: 'light' | 'dark' }
+     *
+     * const { data } = await hbSDK.storage.getStorage<Settings>({
+     *   key: 'settings',
+     * })
+     *
+     * // 泛型不会校验持久化数据；关键数据应先做 schema/type guard 校验。
+     * const theme = data?.theme === 'dark' ? 'dark' : 'light'
+     * ```
+     *
+     * @see {@link MiniProgramStorageModule.setStorage | storage.setStorage}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
      *
      * @since 0.2.0-alpha.0
      * @hbPlatform android
@@ -41,7 +125,53 @@ export interface MiniProgramStorageModule {
      */
     getStorage<T = unknown>(options: GetStoragePayload): Promise<GetStorageResult<T>>;
     /**
-     * 写入小程序隔离 storage。
+     * 将 JSON 数据持久化到当前小程序隔离 Storage 的一个 key。
+     *
+     * @param options - 写入参数。`options.key` 必须符合 {@link SetStoragePayload.key} 的字符和
+     * 长度约束；`options.data` 必须符合 {@link SetStoragePayload.data} 的 clone、JSON 与配额约束。
+     * @returns Host 完成该 key 的整值替换后 resolve `undefined`；该 API 没有业务返回值。
+     * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS`：`options`、key 或 JSON 数据非法，
+     * 包括顶层 `undefined`、`BigInt`、循环引用或序列化过程抛错。
+     * @throws {@link HbMiniProgramSDKError} `STORAGE_QUOTA_EXCEEDED`：完整 JSON 字符串的 UTF-8
+     * 字节数超过当前 Host 配额。
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`：当前
+     * 版本未声明或未启用 `storage`；`INVALID_STATE`：canonical 小程序身份尚未就绪。
+     * @throws {@link HbMiniProgramSDKError} `METHOD_NOT_FOUND` / `METHOD_FORBIDDEN`：当前 Host
+     * 不支持或禁用了该能力。其他握手、bridge、超时与 Host 写入失败会保留对应错误码。
+     * @throws `DOMException` 数据含函数、Symbol、自定义 `toJSON` 方法等不可 structured-clone
+     * 内容时，浏览器可能在请求发送前抛出 `DataCloneError`。
+     *
+     * @remarks
+     * 该 API 需要在 `package.json#heybox.permissions` 声明并启用 `storage`，不需要平台批准、
+     * 用户授权或可信用户手势。
+     *
+     * Storage 作用域由平台确认的 canonical 小程序 ID 决定，并在当前 Runtime 首次使用时
+     * 固定；版本号、当前登录账号、页面 URL 和 key 都不能改变作用域。不同小程序不能互相
+     * 读取数据，同一小程序的版本升级仍使用相同作用域；本地匿名调试只使用 Runtime 显式
+     * 分配的临时 scope。该能力是 Host 本地持久化，不是账号级或跨设备云同步。
+     *
+     * Runtime 会先完成 JSON 序列化和 UTF-8 配额校验，再向 Host 提交一个完整字符串；这些
+     * 前置校验失败时不会覆盖旧值。Host 以单次操作整值替换同一个 key，不暴露局部写入、
+     * merge、append 或多 key 事务。Promise resolve 表示 Host 已完成本次持久化；随后可用
+     * {@link MiniProgramStorageModule.getStorage | storage.getStorage} 读取反序列化后的值。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * type Settings = { theme: 'light' | 'dark'; updatedAt: string }
+     *
+     * await hbSDK.storage.setStorage({
+     *   key: 'settings',
+     *   data: { theme: 'dark', updatedAt: new Date().toISOString() },
+     * })
+     *
+     * const { data } = await hbSDK.storage.getStorage<Settings>({ key: 'settings' })
+     * if (data) console.log(data.theme)
+     * ```
+     *
+     * @see {@link MiniProgramStorageModule.getStorage | storage.getStorage}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
      *
      * @since 0.2.0-alpha.0
      * @hbPlatform android

package/types/modules/ui/index.d.ts

@@ -1,32 +1,146 @@
 import type { MiniProgramRequester } from '../../core/client';
 export { UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD } from '../../protocol/capabilities';
-/** Toast 展示状态。 */
+/**
+ * Toast 的语义状态。
+ *
+ * @remarks
+ * `success` 与 `error` 用于请求 Host 展示对应的成功或错误反馈样式；不传状态时展示
+ * 普通文本 Toast。具体图标、颜色和停留时长由 Host 决定。
+ */
 export type MiniProgramToastStatus = 'success' | 'error';
-/** `ui.showToast` 入参。 */
+/**
+ * `ui.showToast` 的展示配置。
+ *
+ * @remarks
+ * 只支持 `message` 与可选的 `status`。Runtime 会拒绝未声明的额外字段，并在调用 Host 前
+ * 规范化文案与状态。
+ */
 export interface ShowToastPayload {
-    /** Toast 文案。 */
+    /**
+     * Toast 文案。
+     *
+     * @remarks
+     * Runtime 会先调用 `String#trim()` 移除首尾空白，内部空白保持不变；规范化后必须非空。
+     * 长度上限为 120 个 UTF-16 code unit，按 JavaScript `string.length` 计算，而不是按用户感知字符
+     * 或 Unicode code point 计数；例如多数 emoji 会占两个单位。
+     */
     message: string;
-    /** Toast 状态；不传时展示普通文本 toast。 */
+    /**
+     * 请求 Host 使用的语义状态。
+     *
+     * @defaultValue `undefined`，即普通文本 Toast。
+     *
+     * @remarks
+     * 仅支持 `success` 与 `error`；省略时不向 Host 传入状态，展示普通文本 Toast。具体图标、颜色、
+     * 声音或其他反馈由 Host 决定，不能作为业务成功或失败的判定依据。
+     */
     status?: MiniProgramToastStatus;
 }
-/** `ui.showToast` 无稳定返回值。 */
+/**
+ * `ui.showToast` 的空结果。
+ *
+ * @remarks
+ * `void` 只表示本次 Host show operation 已成功结束，不返回 Toast ID、可见状态、展示时长或
+ * 清理函数，也不会等待 Toast 自动消失或被下一条反馈替换。
+ */
 export type ShowToastResult = void;
-/** `ui.showLoading` 入参。 */
+/**
+ * `ui.showLoading` 的展示配置。
+ *
+ * @remarks
+ * 只支持可选的 `dismissible`；Runtime 会拒绝额外字段或非布尔值。Loading 的可见状态、
+ * 样式与交互由 Host 持有，SDK Runtime 不维护调用计数或展示栈，每次调用都会把规范化配置
+ * 转发给 Host。
+ */
 export interface ShowLoadingPayload {
-    /** 是否允许用户手动关闭 loading。 */
+    /**
+     * 是否允许用户通过 Host 提供的界面手动关闭 Loading。
+     *
+     * @defaultValue `false`
+     *
+     * @remarks
+     * 省略时 Runtime 固定向 Host 传入 `false`。设为 `true` 只允许 Host 提供关闭入口；具体关闭
+     * 手势和样式由 Host 决定，不表示 Host 必须展示某种按钮。手动关闭只影响 Host UI，不会取消
+     * 发起 Loading 的业务任务；SDK 不提供关闭事件、回调或可查询状态。
+     */
     dismissible?: boolean;
 }
-/** `ui.showLoading` 无稳定返回值。 */
+/**
+ * `ui.showLoading` 的空结果。
+ *
+ * @remarks
+ * `void` 只表示本次 Host show operation 已成功结束，不返回 Loading ID、可见状态、用户关闭状态
+ * 或清理函数，也不会等待 Loading 随后的隐藏或用户关闭。
+ */
 export type ShowLoadingResult = void;
-/** `ui.hideLoading` 不需要入参。 */
+/**
+ * `ui.hideLoading` 的空 payload。
+ *
+ * @remarks
+ * 公开方法不接收参数，也不接受 Loading ID、计数、`force` 或动画配置。SDK 发送请求时不携带
+ * payload；调用方不应传入 `{}` 或自行构造 bridge payload。
+ */
 export type HideLoadingPayload = void;
-/** `ui.hideLoading` 无稳定返回值。 */
+/**
+ * `ui.hideLoading` 的空结果。
+ *
+ * @remarks
+ * `void` 只表示本次 Host hide operation 已成功结束，不表示此前一定存在 Loading，也不返回
+ * “是否实际隐藏”、剩余展示计数或动画完成状态。
+ */
 export type HideLoadingResult = void;
 export type { MiniProgramUiMethod } from '../../protocol/capabilities';
-/** 外部小程序可调用的 UI 模块。 */
+/**
+ * 外部小程序可调用的 Host UI 反馈模块。
+ *
+ * @remarks
+ * 本模块无需在 `package.json#heybox.permissions` 中声明权限。展示样式、动画与持续
+ * 时间由 Host 决定，Mini-program 不应依赖这些视觉实现细节推进业务状态。
+ */
 export interface MiniProgramUiModule {
     /**
-     * 展示 toast。
+     * 展示短暂的 Toast 反馈。
+     *
+     * @param options - Toast 文案与可选语义状态。必须是只包含 `message`、`status` 的对象；`status`
+     * 省略时请求普通文本 Toast。
+     * @returns Runtime 调用的 Host `presentation.showToast` operation 成功结束并返回 bridge 响应后，
+     * Promise 以 `void` resolve。它不会等待 Toast 自动消失或被替换，也不返回可见状态。
+     * @throws [HbMiniProgramSDKError](/reference/symbols/root/classes/HbMiniProgramSDKError)
+     * options 不是对象、含额外字段，`message` 不是字符串、trim 后为空或超过 120 个 UTF-16 code unit，
+     * 或 `status` 不是 `success` / `error` 时，以 `INVALID_PARAMS` 拒绝。当前 Host 未开放
+     * `presentation.showToast` 时以 `METHOD_FORBIDDEN` 拒绝，旧 Runtime 不认识 `ui.showToast` 时可返回
+     * `METHOD_NOT_FOUND`，Host 不支持当前请求形状时可返回 `REQUEST_UNSUPPORTED`。bridge、Runtime
+     * 卸载、请求超时或 Host operation 失败时抛出对应 SDK 错误。
+     *
+     * @remarks
+     * 该 API 无需在 `package.json#heybox.permissions` 中声明权限，也不要求可信用户手势。Runtime 会
+     * 对 `message` 执行 `trim()`，再按 JavaScript `string.length` 校验最多 120 个 UTF-16 code unit；
+     * 规范化后的文本才会传给 Host。省略 `status` 时为普通 Toast，`success` / `error` 只请求对应
+     * 语义样式，不改变 Promise 或错误处理语义。
+     *
+     * 展示时长、动画、位置、图标、颜色、同时可见数量和无障碍呈现均由 Host 决定。连续调用不会在
+     * Runtime 排队或合并；新 Toast 是覆盖、排队还是与旧 Toast 共存，以及它与当前
+     * [ui.showLoading()](/reference/sdk/ui/showLoading) 如何交互，都不是公共契约。Promise resolve 只表示
+     * Host operation 完成，不能据此认为用户已经看到完整时长的提示。
+     *
+     * Toast 适合无需显式清理的短暂结果反馈；长任务使用 `showLoading()` 并在 `finally` 中调用
+     * `hideLoading()`。`status` 不会让 SDK 自动触发触觉反馈；需要震动时应单独调用
+     * [device.vibrate()](/reference/sdk/device/vibrate)，并独立处理平台不支持结果。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * await hbSDK.ui.showToast({
+     *   message: '  保存成功  ', // Host 最终收到“保存成功”
+     *   status: 'success',
+     * })
+     * ```
+     *
+     * @see [ui.showLoading()](/reference/sdk/ui/showLoading) 展示需要显式清理的全局 Loading。
+     * @see [device.vibrate()](/reference/sdk/device/vibrate) 请求独立的 Host 触觉反馈。
+     * @see [ShowToastPayload](/reference/symbols/root/interfaces/ShowToastPayload) 文案与状态配置类型。
+     * @see [ShowToastResult](/reference/symbols/root/types/ShowToastResult) 无业务数据的成功结果类型。
      *
      * @since 0.4.4
      * @hbPlatform android
@@ -42,7 +156,54 @@ export interface MiniProgramUiModule {
      */
     showToast(options: ShowToastPayload): Promise<void>;
     /**
-     * 展示全局 loading。
+     * 展示或更新全局 Loading。
+     *
+     * @param options - 可选展示配置。省略、JavaScript `null` 或传入 `{}` 时，SDK 将其规范化为
+     * 空配置，Runtime 再将 `dismissible` 规范化为 `false`；只接受布尔值且不支持额外字段。
+     * @returns Runtime 调用的 Host `presentation.showLoading` operation 成功结束并返回 bridge 响应后，
+     * Promise 以 `void` resolve。它不会等待 Loading 被隐藏或用户手动关闭，也不返回 Loading handle。
+     * @throws [HbMiniProgramSDKError](/reference/symbols/root/classes/HbMiniProgramSDKError)
+     * `dismissible` 不是布尔值、options 含额外字段或底层 payload 不符合对象契约时以
+     * `INVALID_PARAMS` 拒绝；当前 Host 未开放 `presentation.showLoading` 时以 `METHOD_FORBIDDEN` 拒绝，旧 Runtime 不认识
+     * `ui.showLoading` 时可返回 `METHOD_NOT_FOUND`，Host 不支持当前请求形状时以
+     * `REQUEST_UNSUPPORTED` 拒绝。bridge、Runtime 卸载、请求超时或 Host operation 失败时抛出
+     * 对应 SDK 错误。
+     *
+     * @remarks
+     * 该 API 无需在 `package.json#heybox.permissions` 中声明权限，也不要求可信用户手势。它只控制
+     * Host 的全局 Loading 反馈，不会阻塞或取消调用方的业务 Promise。
+     *
+     * `dismissible: false` 请求 Host 不提供用户手动关闭入口；`true` 允许 Host 提供入口。该字段只描述
+     * Host UI 是否可由用户关闭，不是业务取消能力：SDK 不会收到关闭事件，也不会因此 abort 网络请求
+     * 或其他任务。即使允许手动关闭，业务仍应在完成时调用
+     * [ui.hideLoading()](/reference/sdk/ui/hideLoading) 清理。
+     *
+     * SDK 与 Runtime 都不维护 Loading 是否可见、展示次数、引用计数或调用栈。每次调用都会独立发送并
+     * 转发到 Host；重复调用是更新还是重建、后一次配置如何覆盖前一次、Loading 与现有
+     * [ui.showToast()](/reference/sdk/ui/showToast) 如何交互，都由 Host 决定。一个流程的
+     * `hideLoading()` 可能隐藏另一个并发流程展示的 Loading，因此多个流程共享全局 Loading 时，应在
+     * 应用层协调所有权或自行维护计数。
+     *
+     * 单个流程拥有 Loading 时，先等待本方法成功，再把业务任务放进 `try`，并在 `finally` 中调用
+     * `hideLoading()`，确保成功与失败路径都尝试清理。若清理失败不能覆盖原始业务错误，应在应用层
+     * 单独捕获并记录清理错误。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * await hbSDK.ui.showLoading({ dismissible: true })
+     * try {
+     *   await saveChanges()
+     * } finally {
+     *   await hbSDK.ui.hideLoading()
+     * }
+     * ```
+     *
+     * @see [ui.hideLoading()](/reference/sdk/ui/hideLoading) 隐藏当前 Host 全局 Loading。
+     * @see [ui.showToast()](/reference/sdk/ui/showToast) 展示无需显式清理的短暂反馈。
+     * @see [ShowLoadingPayload](/reference/symbols/root/interfaces/ShowLoadingPayload) `dismissible` 配置类型。
+     * @see [ShowLoadingResult](/reference/symbols/root/types/ShowLoadingResult) 无业务数据的成功结果类型。
      *
      * @since 0.4.4
      * @hbPlatform android
@@ -58,7 +219,52 @@ export interface MiniProgramUiModule {
      */
     showLoading(options?: ShowLoadingPayload): Promise<void>;
     /**
-     * 隐藏全局 loading。
+     * 隐藏当前全局 Loading。
+     *
+     * @returns Runtime 调用的 Host `presentation.hideLoading` operation 成功结束并返回 bridge 响应后，
+     * Promise 以 `void` resolve。返回值不说明此前是否存在 Loading，也不承诺等待 Host 的退出动画完成。
+     * @throws [HbMiniProgramSDKError](/reference/symbols/root/classes/HbMiniProgramSDKError)
+     * 当前 Host 未开放 `presentation.hideLoading` 时以 `METHOD_FORBIDDEN` 拒绝；旧 Runtime 不认识
+     * `ui.hideLoading` 时可返回 `METHOD_NOT_FOUND`。bridge、Runtime 卸载、请求超时或 Host operation
+     * 失败时抛出对应 SDK 错误；Host 明确表示当前请求不受支持时可返回 `REQUEST_UNSUPPORTED`。
+     *
+     * @remarks
+     * 该方法不接收参数，无需在 `package.json#heybox.permissions` 中声明权限，也不要求可信用户手势。
+     * 它只请求隐藏 Host 当前持有的全局 Loading，不会关闭 Toast 或其他 UI 反馈。
+     *
+     * SDK 与 Runtime 都不维护 Loading 是否可见、展示次数、引用计数或调用栈。每次调用都会独立发送并
+     * 转发到 Host；连续调用不会在 Runtime 合并，也不需要按此前 `showLoading()` 的调用次数循环隐藏。
+     * 多个并发流程共用同一个全局 Loading 时，一个流程的 `hideLoading()` 可能隐藏另一个流程展示的
+     * Loading，调用方需要在业务层协调所有权或自行维护计数。
+     *
+     * 当前没有 Loading 时，行为由 Host 决定，公共契约不保证统一幂等：Browser Dev Host 会成功空操作，
+     * Mobile 与 PC Runtime 仍会把请求转发给实际 Host，由 Host 决定成功、空操作或报错。因此不要用
+     * `hideLoading()` 的 resolve/reject 探测 Loading 是否可见，也不要据此推进业务状态。
+     *
+     * 当当前异步流程拥有 Loading 时，应在 `finally` 中清理，使成功和失败路径都会尝试隐藏。
+     * [ui.showLoading()](/reference/sdk/ui/showLoading) 的 `dismissible: true` 不提供用户关闭回调；即使用户
+     * 可能已经手动关闭，流程结束时仍可按 Host 语义调用本方法。若清理失败不能覆盖原始业务错误，
+     * 应在应用层单独捕获并记录清理错误。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * let loadingShown = false
+     * try {
+     *   await hbSDK.ui.showLoading({ dismissible: false })
+     *   loadingShown = true
+     *   await saveChanges()
+     * } finally {
+     *   if (loadingShown) {
+     *     await hbSDK.ui.hideLoading()
+     *   }
+     * }
+     * ```
+     *
+     * @see [ui.showLoading()](/reference/sdk/ui/showLoading) 展示或更新同一个 Host 全局 Loading。
+     * @see [HideLoadingPayload](/reference/symbols/root/types/HideLoadingPayload) 无参数的 wire payload 类型。
+     * @see [HideLoadingResult](/reference/symbols/root/types/HideLoadingResult) 无业务数据的成功结果类型。
      *
      * @since 0.4.4
      * @hbPlatform android
@@ -74,11 +280,36 @@ export interface MiniProgramUiModule {
      */
     hideLoading(): Promise<void>;
 }
-/** 展示 toast。 */
+/**
+ * 通过底层 bridge 展示 Toast。
+ *
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - Toast 文案与可选语义状态。
+ * @returns Host 接受并应用展示请求后 resolve。
+ * @throws {@link HbMiniProgramSDKError} 参数、bridge、Runtime 或 Host 调用失败时抛出。
+ */
 export declare function showToast(requester: MiniProgramRequester, options: ShowToastPayload): Promise<void>;
-/** 展示全局 loading。 */
+/**
+ * 通过底层 bridge 展示或更新全局 Loading。
+ *
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - 可选展示配置；省略时使用不可手动关闭的 Loading。
+ * @returns Host 接受并应用展示请求后 resolve。
+ * @throws {@link HbMiniProgramSDKError} 参数、bridge、Runtime 或 Host 调用失败时抛出。
+ */
 export declare function showLoading(requester: MiniProgramRequester, options?: ShowLoadingPayload): Promise<void>;
-/** 隐藏全局 loading。 */
+/**
+ * 通过底层 bridge 请求隐藏全局 Loading。
+ *
+ * @param requester - 底层 bridge 请求能力。
+ * @returns Host 接受隐藏请求后 resolve。
+ * @throws {@link HbMiniProgramSDKError} bridge、Runtime 或 Host 调用失败时抛出。
+ */
 export declare function hideLoading(requester: MiniProgramRequester): Promise<void>;
-/** 创建 UI 模块。 */
+/**
+ * 创建绑定到指定 bridge requester 的 UI 模块。
+ *
+ * @param requester - 底层 bridge 请求能力。
+ * @returns 可供 Mini-program 调用的 UI 模块。
+ */
 export declare function createUiModule(requester: MiniProgramRequester): MiniProgramUiModule;

package/types/modules/user/get-info.d.ts

@@ -1,23 +1,44 @@
 import type { MiniProgramRequester } from '../../core/client';
 import type { MiniProgramUserInfoResult } from './types';
 export { USER_GET_INFO_METHOD } from '../../protocol/capabilities';
-/**
- * `user.getInfo` 不需要入参。
- */
+/** `user.getInfo` 不需要入参；调用时不要传小程序 ID 或用户 ID。 */
 export type GetUserInfoPayload = void;
 /**
  * `user.getInfo` 返回当前用户登录态与公开基础资料。
+ *
+ * @remarks
+ * 先用 `isHeyboxAppLoggedIn` 缩窄联合类型：未登录时 `authorization` 与 `userInfo` 均为
+ * `null`；已登录时 `authorization` 固定包含 `identity`、`profile`，但兼容 Host 的
+ * `userInfo` 仍可能为 `null`。这些状态表示用户授权，不是 Manifest 权限配置。
  */
 export type GetUserInfoResult = MiniProgramUserInfoResult;
 /**
  * 获取当前访问小程序用户的公开基础资料。
  *
- * @returns 当前用户的登录态与公开基础资料。
+ * @param requester - SDK 内部的 bridge 请求器；业务代码应通过 `hbSDK.user.getInfo()` 调用。
+ * @returns 以 `isHeyboxAppLoggedIn` 为判别字段的登录态、用户授权状态和已获准披露资料。
+ *
+ * @throws {@link HbMiniProgramSDKError} `userInfo` 未声明或不可用、握手失败、Host 不支持该能力、
+ * 当前小程序身份缺失、账号/隔离身份读取失败、返回结构不合法、Runtime 终止，或请求期间
+ * 账号与授权上下文变化时抛出。
+ *
+ * @remarks
+ * 当前账号未登录属于正常返回分支，不抛错。账号已登录时，该能力不展示授权 UI，也不要求
+ * 可信用户手势；Runtime 会静默建立或读取当前小程序的隔离 `app_user_id`，并授予
+ * `identity` 与 `profile`。它只要求 Manifest 中声明 `userInfo`，不要求公开 `network`
+ * 权限，也不返回可供服务端换票的授权码。
  *
- * 未开通网络权限且当前黑盒 APP 用户已登录时，该能力会静默建立或读取按小程序隔离的
- * `app_user_id`，并隐式授予 `identity` 与 `profile` 后返回昵称与头像，不展示授权 UI。未登录时返回
- * `{ isHeyboxAppLoggedIn: false, authorization: null, userInfo: null }`。
+ * @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)
+ * }
+ * ```
  *
- * @throws {@link HbMiniProgramSDKError} 当 SDK 调用失败时抛出。
+ * @see [auth.login](/reference/sdk/auth/login)
+ * @see [user.revokeAuthorization](/reference/sdk/user/revokeAuthorization)
  */
 export declare function getInfo(requester: MiniProgramRequester): Promise<GetUserInfoResult>;