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

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

@@ -11,6 +11,57 @@ export interface MiniProgramUserModule {
     /**
      * 获取当前黑盒 APP 登录态、授权状态和已获准披露的资料。
      *
+     * @returns 以 `isHeyboxAppLoggedIn` 为判别字段的联合结果：
+     *
+     * - `false`：当前未登录，`authorization` 和 `userInfo` 固定为 `null`。
+     * - `true`：`authorization` 固定包含 `identity`、`profile` 两项状态；兼容 Host 的
+     *   `userInfo` 仍可能为 `null`，非空时包含隔离 `app_user_id` 与可空 `profile`。
+     *
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED` 表示
+     * `userInfo` Manifest 权限不可用；`INVALID_STATE` 表示缺少 canonical 小程序身份；
+     * `REQUEST_FAILED` / `REQUEST_UNSUPPORTED` / `INVALID_RESPONSE` 表示 Host 或资料读取失败；
+     * `HEYBOX_APP_LOGIN_REQUIRED` 表示初次登录态检查后，Host 会话在隔离身份读取期间失效；
+     * `AUTHORIZATION_CONTEXT_CHANGED` 表示请求期间发生账号切换或授权撤销；
+     * `RUNTIME_DESTROYED` 表示 Runtime 已终止。握手失败也会以该错误类型拒绝调用。
+     *
+     * @remarks
+     * 该读取不展示授权 UI，也不要求可信用户手势。Manifest 中必须声明 `userInfo`，但不需要
+     * 公开 `network` 权限；Manifest 权限与 `authorization.identity/profile` 表示的用户授权是
+     * 两层独立门禁。
+     *
+     * 当前账号未登录是正常返回分支，不是 `HEYBOX_APP_LOGIN_REQUIRED` 错误。已登录时 Runtime
+     * 会静默建立或读取本小程序隔离身份，并授予 `identity` 与 `profile`。`app_user_id` 只在
+     * 当前小程序与当前授权有效期内作为稳定、不透明的关联键；它不是黑盒用户 ID、授权码或
+     * 登录凭据。`profile.nickname` / `avatar` 只用于展示，可能为空字符串，不应用于鉴权。
+     *
+     * 该方法不返回 code、token 或 cookie，也不会创建开发者服务端会话。需要服务端身份时，
+     * 在可信用户操作中调用 [auth.login](/reference/sdk/auth/login) 获取一次性 code；需要停止
+     * 使用现有身份时，调用 [user.revokeAuthorization](/reference/sdk/user/revokeAuthorization)
+     * 并同步清理业务缓存与服务端会话。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const result = await hbSDK.user.getInfo()
+     * if (!result.isHeyboxAppLoggedIn) {
+     *   showHeyboxLoginHint()
+     * } else if (!result.userInfo) {
+     *   showUserInfoUnavailable()
+     * } else {
+     *   const { app_user_id, profile } = result.userInfo
+     *   bindLocalIdentity(app_user_id)
+     *   if (result.authorization.profile === 'granted' && profile) {
+     *     renderProfile(profile.nickname, profile.avatar)
+     *   }
+     * }
+     * ```
+     *
+     * @see [auth.login](/reference/sdk/auth/login)
+     * @see [user.revokeAuthorization](/reference/sdk/user/revokeAuthorization)
+     * @see [用户身份与登录](/guide/auth)
+     * @see [权限声明](/guide/permissions)
+     *
      * @since 0.2.0-alpha.0
      * @hbPlatform android
      * @hbPlatform ios
@@ -27,6 +78,55 @@ export interface MiniProgramUserModule {
     /**
      * 撤销当前用户授予本小程序的授权；必须由可信用户操作触发。
      *
+     * @returns Host 确认撤销后 resolve `undefined`；不会返回被撤销的身份、scope 或清理结果。
+     * @throws {@link HbMiniProgramSDKError} `USER_GESTURE_REQUIRED` 表示调用不在按钮点击、确认
+     * 等可信用户操作中；校验发生在网络 I/O 之前。
+     * @throws {@link HbMiniProgramSDKError} `HEYBOX_APP_LOGIN_REQUIRED` 表示当前 Host 没有已登录的
+     * 小黑盒账号；该方法不会主动拉起登录流程。
+     * @throws {@link HbMiniProgramSDKError} `INVALID_STATE` 表示缺少 canonical 小程序身份；
+     * `METHOD_FORBIDDEN` 表示当前 Host 缺少该能力依赖；通过底层协议传入任何 payload 时返回
+     * `INVALID_PARAMS`。
+     * @throws {@link HbMiniProgramSDKError} `REQUEST_UNSUPPORTED` / `REQUEST_FAILED` /
+     * `INVALID_RESPONSE` 表示 Host 请求能力、撤销请求或响应失败；`AUTHORIZATION_CONTEXT_CHANGED`
+     * 表示请求期间切换了账号或授权上下文已变化。
+     * @throws {@link HbMiniProgramSDKError} `RUNTIME_DESTROYED` / `SDK_DESTROYED` 表示 Runtime 或 SDK
+     * 已终止。SDK 握手失败或超过调用超时时间时，还会返回对应握手错误码或 `REQUEST_TIMEOUT`。
+     * @remarks
+     * 该方法没有参数。页面不能传入小程序 ID、黑盒用户 ID 或手势标记；Runtime 从受信 Host
+     * 启动上下文读取当前小程序和当前用户，并校验真实用户手势。
+     *
+     * `user.revokeAuthorization` 位于无需声明白名单，不要求 `userInfo`、`network` 或其他
+     * `package.json#heybox.permissions` 项，也不会修改 Manifest 声明或平台批准状态。它使用 Host
+     * 的受信请求撤销当前用户授予当前小程序的用户授权。
+     *
+     * 只有服务端确认成功且请求期间账号未变化时，Runtime 才清空缓存的隔离身份和授权 scope，
+     * 并通过 [on](/reference/sdk/lifecycle/on) 发布 `user_info_authorization_change`，payload 为
+     * `{ identity: 'denied', profile: 'denied' }`。失败或过期的撤销结果不会发布该成功事件。
+     *
+     * 成功后必须立即停止使用旧 `app_user_id` 和资料，并由业务自行清理 localStorage、SDK
+     * `storage` 中的业务值、cookie、数据库以及开发者服务端 session；SDK 不会代为删除这些
+     * 数据。随后调用 [auth.login](/reference/sdk/auth/login) 会重新进入授权流程；随后调用
+     * [user.getInfo](/reference/sdk/user/getInfo) 会按当前规则重新读取或建立隔离身份，不能假定
+     * 新旧 `app_user_id` 相同。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * async function revokeFromSettingsButton() {
+     *   if (!window.confirm('确定撤销当前小程序的用户授权吗？')) return
+     *
+     *   await hbSDK.user.revokeAuthorization()
+     *   clearPersistedUserProfile()
+     *   await deleteDeveloperSession()
+     * }
+     * ```
+     *
+     * @see [user.getInfo](/reference/sdk/user/getInfo)
+     * @see [auth.login](/reference/sdk/auth/login)
+     * @see [用户身份与登录](/guide/auth#撤销当前小程序授权)
+     * @see [权限声明](/guide/permissions#无需声明的-api)
+     *
      * @since 0.7.0-alpha.1
      * @hbPlatform android
      * @hbPlatform ios
@@ -43,6 +143,63 @@ export interface MiniProgramUserModule {
     /**
      * 获取当前用户的 Steam 游戏库。
      *
+     * @param options - Steam 账号、分页、排序和过滤条件；不传时使用默认账号、`limit: 20`、
+     * `offset: 0`、`sort: 'weeks'`、`includeHidden: false`。
+     * @returns 以 `isLogin`、`isBound` 为判别字段的联合结果：未登录或未绑定 Steam 时
+     * `data` 为 `null`；两者均为 `true` 时返回游戏列表、`hasMore` 和 `nextOffset`。
+     * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS` 表示存在未知字段，或参数类型、范围
+     * 不合法。
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED` 表示
+     * `steamLibrary` 未声明或未启用；`METHOD_FORBIDDEN` 表示当前 Host 缺少该能力依赖。
+     * @throws {@link HbMiniProgramSDKError} `INVALID_STATE` 表示缺少 canonical 小程序身份；
+     * `REQUEST_UNSUPPORTED` / `REQUEST_FAILED` / `INVALID_RESPONSE` 表示 Host 请求能力、Steam
+     * 请求或响应失败；`HEYBOX_APP_LOGIN_REQUIRED` 表示请求期间 Host 登录态失效。
+     * @throws {@link HbMiniProgramSDKError} `AUTHORIZATION_CONTEXT_CHANGED` 表示请求期间切换账号
+     * 或撤销授权；`RUNTIME_DESTROYED` / `SDK_DESTROYED` 表示 Runtime 或 SDK 已终止。SDK 握手失败
+     * 或超过调用超时时间时，还会返回对应的握手错误码或 `REQUEST_TIMEOUT`。
+     * @remarks
+     * 项目必须在 `package.json#heybox.permissions` 声明 `steamLibrary`。该能力通过 Host 的受信
+     * 请求读取当前账号数据，不要求公开 `network` 权限，也不展示授权 UI 或要求可信用户手势。
+     * 它不会调用 `auth.login()`，也不会返回授权码、token 或可供开发者服务端使用的 Steam
+     * scope；公开 OpenAPI 当前也没有 Steam 游戏库资源。
+     *
+     * `steamId` 与 `q` 会 trim；空 `q` 会被省略，非空 `q` 最多保留前 100 个 UTF-16 code
+     * unit。`limit` 必须为正整数并在大于 100 时收窄为 100。继续分页时把返回的
+     * `data.nextOffset` 原样传给下一次调用。
+     *
+     * 先检查 `isLogin` 和 `isBound`，再读取 `data`。需要单独读取小黑盒登录态和当前小程序
+     * 隔离身份时使用 [user.getInfo](/reference/sdk/user/getInfo)；需要为开发者服务端建立会话时，
+     * 在可信用户操作中使用 [auth.login](/reference/sdk/auth/login)。这两个 API 都要求
+     * `userInfo`，不能替代本方法的 `steamLibrary` 权限。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const result = await hbSDK.user.getSteamGameList({
+     *   limit: 20,
+     *   offset: 0,
+     *   sort: 'weeks',
+     *   q: '合作',
+     * })
+     *
+     * if (!result.isLogin) {
+     *   showHeyboxLoginHint()
+     * } else if (!result.isBound) {
+     *   showSteamBindingHint()
+     * } else {
+     *   renderGames(result.data.gameList)
+     *   if (result.data.hasMore) {
+     *     saveNextOffset(result.data.nextOffset)
+     *   }
+     * }
+     * ```
+     *
+     * @see [user.getInfo](/reference/sdk/user/getInfo)
+     * @see [auth.login](/reference/sdk/auth/login)
+     * @see [用户身份与登录](/guide/auth)
+     * @see [权限声明](/guide/permissions)
+     *
      * @since 0.5.0
      * @hbPlatform android
      * @hbPlatform ios

package/types/modules/user/revoke-authorization.d.ts

@@ -1,7 +1,31 @@
 import type { MiniProgramRequester } from '../../core/client';
 export { USER_REVOKE_AUTHORIZATION_METHOD } from '../../protocol/capabilities';
-/** `user.revokeAuthorization` 不接收入参。 */
+/**
+ * `user.revokeAuthorization` 不接收入参。
+ *
+ * @remarks
+ * 小程序 ID、当前小黑盒用户和可信手势状态均由 Host 上下文提供，页面不能通过 payload
+ * 指定或伪造。直接通过 bridge 发送非 `undefined` payload 会返回 `INVALID_PARAMS`。
+ *
+ * @see [user.revokeAuthorization](/reference/sdk/user/revokeAuthorization)
+ */
 export type RevokeAuthorizationPayload = void;
-/** 撤销成功后不返回用户身份或资料。 */
+/**
+ * 撤销成功后不返回用户身份或资料，Promise resolve 值为 `undefined`。
+ *
+ * @remarks
+ * resolve 表示 Host 已确认撤销，并已使当前 Runtime 缓存的用户授权和隔离身份失效；它不表示
+ * SDK 已清理小程序自己的存储、cookie、数据库或开发者服务端会话。
+ */
 export type RevokeAuthorizationResult = void;
+/**
+ * 撤销当前用户授予本小程序的授权。
+ *
+ * @param requester - 底层 bridge 请求能力。
+ * @returns 撤销完成后 resolve `undefined`。
+ * @throws {@link HbMiniProgramSDKError} 缺少可信用户手势、当前用户未登录、Host 请求失败、
+ * 账号上下文变化或 SDK / Runtime 已终止时抛出；具体稳定错误码见公开模块方法文档。
+ * @remarks 该能力无需 Manifest 权限；撤销成功后由调用方清理自己的持久化数据和服务端会话。
+ * @see [user.revokeAuthorization](/reference/sdk/user/revokeAuthorization)
+ */
 export declare function revokeAuthorization(requester: MiniProgramRequester): Promise<RevokeAuthorizationResult>;

package/types/modules/user/steam-game-list.d.ts

@@ -1,53 +1,130 @@
 import type { MiniProgramRequester } from '../../core/client';
-/** Steam 游戏库排序方式。 */
+/**
+ * Steam 游戏库的服务端排序维度。
+ *
+ * @remarks
+ * - `weeks`：按最近两周游玩时长排序，也是默认值。
+ * - `all`：按累计游玩时长排序。
+ * - `achieved`：按已解锁成就数排序。
+ */
 export type SteamGameListSort = 'weeks' | 'all' | 'achieved';
-/** Steam 游戏库查询与分页参数。 */
+/**
+ * Steam 游戏库查询与 offset 分页参数。
+ *
+ * @remarks
+ * Runtime 会拒绝未知字段和类型不匹配的值，不会把数字字符串或 `0` / `1` 自动转换为
+ * `number` / `boolean`。所有默认值和规范化均在 Host 发出 Steam 请求前完成。
+ */
 export interface GetSteamGameListOptions {
-    /** 指定当前用户绑定的 Steam ID；不传时使用默认主账号。 */
+    /**
+     * 要查询的 Steam ID；省略时使用当前小黑盒用户的默认绑定账号。
+     * 首尾空白会被移除，trim 后为空会以 `INVALID_PARAMS` 拒绝。
+     */
     steamId?: string;
-    /** 分页数量，默认 20，最大 100。 */
+    /** 单页数量，默认 `20`；必须是大于等于 `1` 的整数，大于 `100` 时按 `100` 查询。 */
     limit?: number;
-    /** 分页偏移量，默认 0。 */
+    /** 分页偏移量，默认 `0`；必须是大于等于 `0` 的整数，不接受数字字符串。 */
     offset?: number;
-    /** 排序方式，默认 `weeks`。 */
+    /** 排序维度，默认 `weeks`；只接受大小写完全一致的 `weeks`、`all` 或 `achieved`。 */
     sort?: SteamGameListSort;
-    /** 搜索关键词。 */
+    /**
+     * 游戏名称搜索词。Runtime 会先 trim，再保留前 `100` 个 UTF-16 code unit；trim 后为空时
+     * 不向服务端发送 `q`，等价于不按关键词过滤。
+     */
     q?: string;
-    /** 是否包含当前用户隐藏的游戏，默认 `false`。 */
+    /** 是否包含当前用户隐藏的游戏，默认 `false`；只接受 boolean，不接受 `0` / `1`。 */
     includeHidden?: boolean;
 }
-/** `user.getSteamGameList` 请求参数。 */
+/**
+ * `user.getSteamGameList` 请求参数；省略时使用默认 Steam 账号和全部默认查询值。
+ *
+ * @see [user.getSteamGameList](/reference/sdk/user/getSteamGameList)
+ */
 export type GetSteamGameListPayload = GetSteamGameListOptions | undefined;
-/** Steam 游戏库条目。 */
+/**
+ * Steam 游戏的可用价格信息。
+ *
+ * @remarks
+ * 整个 `price` 及其中每个字段都可能缺失；服务端返回 `null`、空字符串或不可用数值时，
+ * Runtime 会省略相应字段。协议不携带币种或最小货币单位，不能把数值字段自行解释为
+ * “分”或固定币种；直接展示价格时优先使用 `current` / `initial`。
+ */
 export interface SteamGamePrice {
+    /** 当前售价的非空展示文本；币种与格式由服务端决定。 */
     current?: string;
+    /** 原价的非空展示文本；币种与格式由服务端决定。 */
     initial?: string;
+    /** 服务端原始折扣数值；当前公开合同不承诺比例、百分比或取值范围。 */
     discount?: number;
+    /** 服务端最低价数值；协议不提供币种和缩放单位。 */
     lowestPrice?: number;
+    /** 截止时间的非空展示文本，例如剩余天数；不要把它当作可解析日期。 */
     deadlineDate?: string;
+    /** 服务端原始折扣截止时间数值；当前公开合同不承诺单位或时钟来源。 */
     deadlineTimestamp?: number;
 }
-/** Steam 游戏库条目。 */
+/**
+ * 经过 Runtime 规范化的 Steam 游戏库条目。
+ *
+ * @remarks
+ * 原始记录缺少有效 `appid`、`steamAppid`/`appid` 或非空 `name` 时，整条记录会从
+ * `gameList` 中移除。其余可选字段在服务端缺失、为空或类型无效时会被省略，而不是填充
+ * `null`。
+ */
 export interface SteamGameListItem {
+    /** 游戏在小黑盒游戏目录中的有限数值 ID。 */
     appid: number;
+    /** Steam App ID；服务端未提供有效值时回退为 `appid`。 */
     steamAppid: number;
+    /** trim 后的非空游戏名称。 */
     name: string;
+    /** 非空的游戏封面或主图 URL 字符串；Runtime 不保证 URL 协议。 */
     image?: string;
+    /** 非空的 Steam 图标 URL 字符串；优先读取服务端 `appicon`。 */
     icon?: string;
+    /** 服务端原始累计游玩时长数值；`0` 是有效值，当前公开合同不承诺单位。 */
     playtimeForever?: number;
+    /** 服务端原始最近游玩时长数值；`0` 是有效值，当前公开合同不承诺单位。 */
     playtime2Weeks?: number;
+    /** trim 后的非空游戏标签；没有有效标签时整个字段省略。 */
     tags?: string[];
+    /** 至少有一个可用字段时返回价格信息；免费游戏或价格不可用时省略。 */
     price?: SteamGamePrice;
 }
-/** Steam 游戏库分页数据。 */
+/**
+ * Steam 游戏库的 offset 分页数据。
+ *
+ * @remarks
+ * `nextOffset` 始终按“本次请求的有效 `offset` + `gameList.length`”计算。服务端返回有效
+ * `total` 时，`hasMore` 等于 `nextOffset < total`；没有 `total` 时，以本页有效条目数是否
+ * 达到规范化后的 `limit` 推断。继续加载应直接传回 `nextOffset`，不要自行加请求的原始
+ * `limit`。
+ */
 export interface SteamGameListData {
+    /** 当前页通过必填字段校验的游戏条目；没有结果时为空数组。 */
     gameList: SteamGameListItem[];
+    /** 服务端返回的游戏总数；缺失或不是有限数值时省略。 */
     total?: number;
+    /** 按 `total` 或当前页有效条目数推导的下一页标记。 */
     hasMore: boolean;
+    /** 下一页应使用的 offset；始终存在，即使 `hasMore` 为 `false`。 */
     nextOffset: number;
+    /** 服务端对“结果是否属于当前用户本人”的标记；缺失或不可识别时省略。 */
     isMe?: boolean;
 }
-/** `user.getSteamGameList` 返回当前用户的 Steam 绑定状态和游戏库。 */
+/**
+ * `user.getSteamGameList` 返回当前用户的 Steam 绑定状态和游戏库。
+ *
+ * @remarks
+ * 这是以 `isLogin` 和 `isBound` 为判别字段的联合类型：
+ *
+ * - `{ isLogin: false, isBound: false, data: null }`：当前小黑盒账号未登录；这是正常结果。
+ * - `{ isLogin: true, isBound: false, data: null }`：已登录，但当前账号没有 Steam 绑定信息。
+ * - `{ isLogin: true, isBound: true, data }`：已登录且已绑定，`data.gameList` 可以为空数组。
+ *
+ * 不存在 `isLogin: false, isBound: true` 分支。必须先缩窄两个判别字段再访问 `data`，不能
+ * 把前两个状态当作“绑定账号的空游戏库”。
+ */
 export type GetSteamGameListResult = {
     isLogin: false;
     isBound: false;
@@ -65,8 +142,12 @@ export type GetSteamGameListResult = {
  * 获取当前用户 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)
  */
 export declare function getSteamGameList(requester: MiniProgramRequester, options?: GetSteamGameListOptions): Promise<GetSteamGameListResult>;
 export { USER_GET_STEAM_GAME_LIST_METHOD } from '../../protocol/capabilities';

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

@@ -3,72 +3,117 @@ import type { MiniProgramRequester } from '../../core/client';
  * 小程序安全区域信息。
  *
  * @remarks
- * 所有字段单位均为像素，基于当前小程序可用窗口坐标系。
+ * 所有字段单位均为逻辑像素，坐标原点是当前小程序可用窗口的左上角。Runtime 会把
+ * 四条边界夹取到窗口范围内，并保证 `right >= left`、`bottom >= top`；`width` 恒等于
+ * `right - left`，`height` 恒等于 `bottom - top`。
+ *
+ * Host 未提供安全区域或某条边界无效时，Runtime 分别以 `left = 0`、
+ * `right = windowWidth`、`top = statusBarHeight`、`bottom = windowHeight` 降级，再把结果
+ * 夹取到当前窗口范围内。因此安全区域可能退化为零宽或零高矩形，但不会越过窗口边界。
+ *
+ * @see {@link MiniProgramWindowInfoResult}
  */
 export interface MiniProgramSafeArea {
-    /** 安全区域左上角横坐标。 */
+    /** 安全区域左边界横坐标；从窗口左边缘起算，范围为 `0` 到 `windowWidth`。 */
     left: number;
-    /** 安全区域右下角横坐标。 */
+    /** 安全区域右边界横坐标；从窗口左边缘起算，且不小于 `left`。 */
     right: number;
-    /** 安全区域左上角纵坐标。 */
+    /** 安全区域上边界纵坐标；从窗口上边缘起算，Host 未提供有效值时取 `statusBarHeight`。 */
     top: number;
-    /** 安全区域右下角纵坐标。 */
+    /** 安全区域下边界纵坐标；从窗口上边缘起算，且不小于 `top`。 */
     bottom: number;
-    /** 安全区域宽度，单位 px。 */
+    /** 安全区域宽度，恒等于 `right - left`，单位逻辑像素。 */
     width: number;
-    /** 安全区域高度，单位 px。 */
+    /** 安全区域高度，恒等于 `bottom - top`，单位逻辑像素。 */
     height: number;
 }
 /**
  * 小程序窗口信息。
  *
  * @remarks
- * 该结构统一描述屏幕尺寸、可用窗口尺寸、安全区域与顶部偏移等容器信息。
+ * 该结构统一描述调用时的屏幕尺寸、可用窗口尺寸、安全区域与顶部偏移等容器信息。
+ * 窗口可缩放的平台上，尺寸可能在后续用户拖拽后变化；需要最新值时重新调用
+ * `viewport.getWindowInfo()`。
+ *
+ * Runtime 会把无效 `pixelRatio` 降级为 `1`，把无效屏幕尺寸降级为对应窗口尺寸，
+ * 把无效窗口尺寸降级为 `0`。导航栏高度读取失败或返回无效值时，`statusBarHeight`
+ * 与 `screenTop` 均降级为 `0`；安全区域再基于这些归一化值计算。
+ *
+ * @see {@link MiniProgramViewportModule.getWindowInfo}
  */
 export interface MiniProgramWindowInfoResult {
-    /** 设备像素比。 */
+    /** 设备像素比；Host 返回非有限值或非正数时为 `1`。 */
     pixelRatio: number;
-    /** 屏幕宽度，单位 px。 */
+    /** 屏幕宽度，单位逻辑像素；Host 值无效时退回到 `windowWidth`。 */
     screenWidth: number;
-    /** 屏幕高度，单位 px。 */
+    /** 屏幕高度，单位逻辑像素；Host 值无效时退回到 `windowHeight`。 */
     screenHeight: number;
-    /** 可使用窗口宽度，单位 px。 */
+    /** 当前小程序可使用的窗口内容宽度，单位逻辑像素；Host 值无效时为 `0`。 */
     windowWidth: number;
-    /** 可使用窗口高度，单位 px。 */
+    /** 当前小程序可使用的窗口内容高度，单位逻辑像素；Host 值无效时为 `0`。 */
     windowHeight: number;
-    /** 状态栏高度；黑盒环境按顶部可用偏移兼容。 */
+    /** 状态栏或顶部导航占用高度，单位逻辑像素；读取失败或值无效时为 `0`。 */
     statusBarHeight: number;
-    /** 安全区域。 */
+    /** 当前窗口内经过边界夹取并补齐 `width`、`height` 的安全区域。 */
     safeArea: MiniProgramSafeArea;
-    /** 窗口上边缘的 y 值。 */
+    /** 顶部可用偏移兼容值，单位逻辑像素；当前恒等于 `statusBarHeight`。 */
     screenTop: number;
 }
 export { VIEWPORT_GET_WINDOW_INFO_METHOD } from '../../protocol/capabilities';
 export { VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD } from '../../protocol/capabilities';
-/** `viewport.getWindowInfo` 不需要入参。 */
+/** `viewport.getWindowInfo` 不接收 options 或 payload，调用时无需传入参数。 */
 export type GetWindowInfoPayload = void;
-/** `viewport.getWindowInfo` 返回当前小程序可用窗口信息。 */
+/** `viewport.getWindowInfo` 返回调用时经过 Runtime 归一化的窗口快照。 */
 export type GetWindowInfoResult = MiniProgramWindowInfoResult;
 /**
  * 导航栏关闭按钮与状态栏图标/文字的前景样式。
  *
  * @remarks
- * `light` 表示白色前景，适合深色背景；`dark` 表示黑色前景，适合浅色背景。
+ * `light` 请求 Host 使用白色或浅色前景，适合深色背景；`dark` 请求 Host 使用黑色
+ * 或深色前景，适合浅色背景。该类型没有 `auto`、`system` 或恢复默认值；需要跟随
+ * 页面主题时，应在主题变化后重新调用
+ * {@link MiniProgramViewportModule.setNavigationBarStyle}。
+ *
+ * 取值表达的是对比度语义，不是固定色号。具体颜色、透明度以及状态栏和关闭按钮的
+ * 渲染方式由当前 Host 与操作系统决定。
+ *
+ * @see {@link MiniProgramSetNavigationBarStyleOptions.foregroundStyle}
  */
 export type MiniProgramNavigationBarForegroundStyle = 'light' | 'dark';
 /**
  * 设置导航栏样式的配置。
  *
  * @remarks
+ * `options` 必须是对象，且 `foregroundStyle` 是必填字段。Runtime 只接受精确的
+ * `light` 或 `dark` 字符串；缺少字段、传入 `null`、数组或其他值都会以
+ * `INVALID_PARAMS` 拒绝。
+ *
  * 当前仅开放关闭按钮与状态栏图标/文字的前景明暗样式，不设置导航栏背景色。
+ *
+ * @see {@link MiniProgramNavigationBarForegroundStyle}
  */
 export interface MiniProgramSetNavigationBarStyleOptions {
-    /** 导航栏关闭按钮与状态栏图标/文字的前景样式。 */
+    /**
+     * 导航栏关闭按钮与状态栏图标/文字的前景样式。
+     *
+     * @remarks
+     * 该字段必填且仅接受 `light` 或 `dark`。`light` 适合深色背景，`dark` 适合浅色
+     * 背景；它不读取网页背景，也不会自动跟随 `prefers-color-scheme`。
+     */
     foregroundStyle: MiniProgramNavigationBarForegroundStyle;
 }
-/** `viewport.setNavigationBarStyle` 的入参。 */
+/**
+ * `viewport.setNavigationBarStyle` 的必填入参。
+ *
+ * @see {@link MiniProgramSetNavigationBarStyleOptions}
+ */
 export type SetNavigationBarStylePayload = MiniProgramSetNavigationBarStyleOptions;
-/** `viewport.setNavigationBarStyle` 无稳定返回值。 */
+/**
+ * `viewport.setNavigationBarStyle` 的结果；Host 完成设置后固定以 `undefined` resolve。
+ *
+ * @remarks
+ * Host 内部返回的其他值不会透传给 Mini-program，该结果也不包含最终渲染色值。
+ */
 export type SetNavigationBarStyleResult = void;
 export type { MiniProgramViewportMethod } from '../../protocol/capabilities';
 /** 外部小程序可调用的 Viewport 模块。 */
@@ -76,6 +121,44 @@ export interface MiniProgramViewportModule {
     /**
      * 获取当前小程序窗口信息。
      *
+     * @returns 调用时经过 Runtime 归一化的设备像素比、屏幕与窗口尺寸、安全区域及顶部偏移快照。
+     * @throws {@link HbMiniProgramSDKError} 当前 Host 未开放窗口测量能力时以 `METHOD_FORBIDDEN`
+     * 拒绝；握手失败、Runtime 已卸载、SDK 已销毁、请求超时或 Host 测量失败时抛出对应
+     * bridge / Runtime 错误。
+     *
+     * @remarks
+     * 该方法无入参，不触发用户授权，也无需在 `package.json#heybox.permissions` 中声明。
+     * 每次调用都会重新读取当前窗口并返回一次性快照；它不订阅尺寸变化。PC 可缩放窗口
+     * 可能在用户拖拽、Host 恢复窗口或系统缩放变化后得到新尺寸，需要最新值时应重新调用。
+     *
+     * `package.json#heybox.window` 的 `defaultWidth`、`defaultHeight`、`minWidth`、
+     * `minHeight` 与 `resizable` 只控制开窗初值和用户拖拽约束，不能替代本 API 的运行时
+     * 查询。该方法只读取几何信息；导航栏前景色由
+     * {@link MiniProgramViewportModule.setNavigationBarStyle} 单独设置。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const info = await hbSDK.viewport.getWindowInfo()
+     * const safeInsets = {
+     *   top: info.safeArea.top,
+     *   right: info.windowWidth - info.safeArea.right,
+     *   bottom: info.windowHeight - info.safeArea.bottom,
+     *   left: info.safeArea.left,
+     * }
+     *
+     * const root = document.documentElement
+     * for (const [edge, value] of Object.entries(safeInsets)) {
+     *   root.style.setProperty(`--safe-area-${edge}`, `${value}px`)
+     * }
+     * // 窗口尺寸变化后重新调用 getWindowInfo()，不要长期缓存这次结果。
+     * ```
+     *
+     * @see {@link MiniProgramWindowInfoResult}
+     * @see {@link MiniProgramViewportModule.setNavigationBarStyle}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/window-size/ | 窗口尺寸与可缩放性}
+     *
      * @since 0.2.0-alpha.0
      * @hbPlatform android
      * @hbPlatform ios
@@ -92,6 +175,59 @@ export interface MiniProgramViewportModule {
     /**
      * 设置导航栏关闭按钮与状态栏图标/文字的前景样式。
      *
+     * @param options - 必填的前景样式配置。`foregroundStyle` 只能是 `light` 或 `dark`。
+     * @returns Host 报告本次设置完成后以 `undefined` resolve；不会返回当前样式或实际渲染色值。
+     * @throws {@link HbMiniProgramSDKError} `options` 不是对象，或 `foregroundStyle` 缺失、
+     * 不是 `light`/`dark` 时以 `INVALID_PARAMS` 拒绝；当前 Host 未开放该能力时以
+     * `METHOD_FORBIDDEN` 拒绝，Host 无法处理当前请求时以 `REQUEST_UNSUPPORTED` 拒绝。
+     * 握手失败、SDK 或 Runtime 已销毁、bridge 请求超时以及 Host 设置失败时抛出对应
+     * SDK 错误。
+     *
+     * @remarks
+     * 该 API 无需在 `package.json#heybox.permissions` 中声明权限，也不要求可信用户手势
+     * 或平台批准；仍需当前 Host 开放 `viewport.setNavigationBarStyle` capability。
+     *
+     * 该方法只控制关闭按钮和状态栏图标/文字的前景明暗，不修改导航栏背景色，也不
+     * 改变网页自身的 `color-scheme`。它不提供读取接口、自动主题模式或恢复默认值；
+     * 后续调用可以覆盖先前样式，Host 重建容器后也不应依赖先前调用继续生效。
+     *
+     * 移动端 Host 将该语义应用到 App 顶部容器和系统状态栏，PC Host 将其应用到桌面
+     * 小程序窗口的导航控件；不同操作系统可以采用不同的实际颜色和渲染方式。Browser
+     * Dev Host 只更新本地设备预览中的 Host chrome，不能替代真机或桌面客户端验收。
+     *
+     * {@link MiniProgramViewportModule.getWindowInfo} 只读取窗口几何与安全区域，既不会
+     * 返回当前前景样式，也不是调用本方法的前置条件。`package.json#heybox.window` 只
+     * 声明开窗尺寸和可缩放性，与导航栏前景样式互不覆盖。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const colorScheme = window.matchMedia('(prefers-color-scheme: dark)')
+     *
+     * async function syncNavigationBarStyle() {
+     *   await hbSDK.viewport.setNavigationBarStyle({
+     *     // 深色页面使用浅色前景，浅色页面使用深色前景。
+     *     foregroundStyle: colorScheme.matches ? 'light' : 'dark',
+     *   })
+     * }
+     *
+     * await syncNavigationBarStyle()
+     * const handleColorSchemeChange = () => {
+     *   void syncNavigationBarStyle().catch(console.error)
+     * }
+     * colorScheme.addEventListener('change', handleColorSchemeChange)
+     * window.addEventListener('pagehide', () => {
+     *   colorScheme.removeEventListener('change', handleColorSchemeChange)
+     * }, { once: true })
+     * ```
+     *
+     * @see {@link MiniProgramNavigationBarForegroundStyle}
+     * @see {@link MiniProgramSetNavigationBarStyleOptions}
+     * @see {@link MiniProgramViewportModule.getWindowInfo}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/window-size/ | 窗口尺寸与可缩放性}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
      * @since 0.4.0
      * @hbPlatform android
      * @hbPlatform ios

package/types/protocol/types.d.ts

@@ -1,4 +1,22 @@
 import type { MiniProgramEventName, MiniProgramEventPayloadMap } from '@heybox/hb-sdk-protocol';
 export type { MiniProgramBridgeError, MiniProgramBridgeCancelMessage, MiniProgramBridgeMessage, MiniProgramBridgeMessageType, MiniProgramBridgeProgressMessage, MiniProgramEventName, MiniProgramEventPayloadMap, RuntimeLocationProbePayload, SDKCSPBlockedResourceType, SDKCSPViolationPayload, SDKHandshakePayload, SDKLocationReportPayload, SDKLocationReportTrigger, } from '@heybox/hb-sdk-protocol';
-/** 小程序事件监听函数。 */
+/**
+ * 小程序生命周期或业务事件监听函数。
+ *
+ * @typeParam T - 受
+ * [MiniProgramEventName](/reference/symbols/root/types/MiniProgramEventName) 约束的事件名；它决定
+ * `payload` 的精确类型。
+ * @param payload - 由
+ * [MiniProgramEventPayloadMap](/reference/symbols/root/interfaces/MiniProgramEventPayloadMap) 按 `T`
+ * 索引得到的事件载荷。
+ *
+ * @remarks
+ * handler 在 event bus 派发时同步调用，返回值会被忽略且 Promise 不会被等待。普通事件 handler
+ * 之间没有异常隔离：同步抛错会从当前派发传播，并可能阻止同一事件的后续 handler；异步 handler
+ * 的 rejected Promise 也不会被 SDK 捕获。监听器应在自身边界处理同步和异步错误。
+ *
+ * 生命周期事件不会重放，只派发给事件到达时已经注册的监听器。需要查询当前握手状态时，使用
+ * [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 或
+ * [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange)。
+ */
 export type MiniProgramEventHandler<T extends MiniProgramEventName = MiniProgramEventName> = (payload: MiniProgramEventPayloadMap[T]) => void;