@heybox/hb-sdk 0.9.0-alpha.4 → 0.9.0-alpha.6

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

@@ -124,6 +124,14 @@ export interface MiniProgramViewportModule {
     /**
      * 设置当前小程序的窗口方向和全屏状态。
      *
+     * @param options - 方向与全屏目标，至少提供一个字段；省略的字段保持当前目标值。
+     * @returns Host 完成原生方向与胶囊设置、布局稳定后返回 `{ supported: true }`；能力缺失或
+     * 请求不受支持时返回 `{ supported: false }`，调用方仍应按实际窗口与安全区布局。
+     * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS` 表示参数不合法；
+     * `ORIENTATION_TIMEOUT` 表示展示操作超时，`ORIENTATION_FAILED` 表示执行失败，
+     * `ORIENTATION_SUPERSEDED` 表示被后续不同目标替代，`REQUEST_CANCELLED` 表示操作已取消。
+     * SDK 或 Runtime 销毁、握手失败等其他错误保留对应 SDK 错误码。
+     *
      * @remarks
      * 新容器默认竖屏、非全屏。省略字段保持当前目标值，至少传一个字段；合并后横屏强制全屏，竖屏按 fullscreen 控制。
      * 全屏同时收起胶囊和宿主额外顶部栏，不保证原生内容铺满容器；页面应按实际 WebView 窗口和安全区适配。
@@ -133,12 +141,24 @@ export interface MiniProgramViewportModule {
      * 设置持续到下次调用或退出容器；SPA 路由应在进入时明确设置所需状态。
      * 后续设置先合并目标，再取消不同的旧设置；旧调用以 ORIENTATION_SUPERSEDED 失败。
      * 相同目标共用操作；方向和全屏一起确认，失败时一起恢复最后确认状态。
-     * Promise 在宿主布局稳定后完成，窗口尺寸与安全区变化通过 viewport_change 事件通知。
+     * 本方法等待 Host 展示操作完成，由 Runtime 的操作截止时间控制，不使用普通 bridge 请求的独立超时计时器。
+     * 操作超时或 SDK 销毁会向 Host 传递取消；不要依赖迟到的 Host 成功结果推进业务状态。
+     * 窗口尺寸与安全区变化通过 viewport_change 事件通知。
      * 方向或全屏状态确认变化时通过 display_change 通知，包括用户点击宿主退出全屏按钮。
      * display_change 不回放初始状态；重复设置、不支持、失败或取消不会发出展示状态变化通知。
      * 返回 supported: true 表示原生方向与胶囊设置已完成；不支持时返回 supported: false，保留原生状态。
      * 降级时宿主仍尽力收起 H5 顶部栏，不能据此假定屏幕已旋转或胶囊已隐藏；布局始终按实际窗口适配。
      * SDK 统一处理能力缺失错误；超时、取消、参数或其他执行错误仍抛出。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * // 同时恢复竖屏和非全屏，避免保留之前的全屏目标。
+     * const result = await hbSDK.viewport.setDisplay({ orientation: 'portrait', fullscreen: false })
+     * if (!result.supported) console.log('Host 不支持原生展示设置')
+     * ```
+     *
      * @since 0.8.1-alpha.4
      * @hbPlatform android
      * @hbPlatform ios

package/types/vite/index.d.ts

@@ -124,6 +124,7 @@ export declare const HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV = "HB_SDK_MIN
  * 不符合小程序 HTML 策略时，`transformIndexHtml` / 生产产物复检抛出。
  * @throws `Error` 生产构建无法读取或解析最近的 `package.json`，`version`、`heybox.platforms`、
  * `heybox.permissions`、`heybox.window`、`heybox.bindAppIds` 或 `heybox.companions` 声明非法时抛出。
+ * @throws `Error` 展示资料缺失、名称/图片路径非法、图片无法解码或不符合大小/尺寸约束，或类别非法时抛出。
  * @throws `Error` 生产 `build.outDir` 缺少根 `index.html`、递归发现额外 HTML，或 Companion 权限、
  * 目标平台、来源目录、归档结构、入口二进制不符合约束时抛出；更早的 Rollup/Vite 错误会原样优先重抛。
  *
@@ -134,6 +135,10 @@ export declare const HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV = "HB_SDK_MIN
  *
  * - `version`：发布版本；trim 后必须是完整 SemVer，可含 prerelease，不允许 build metadata 或模板值
  *   `0.0.0`；
+ * - `heybox.name`、`heybox.icon`、`heybox.coverImages`：SDK `0.8.2` 起须完整提供的展示资料。
+ *   图片源路径相对项目目录；icon 为 200×200，封面 1–5 张，每张不超过 10 MiB / 4000 万像素。
+ *   build 会复制图片到输出目录 `_hb/basic-info/`，并将 Manifest 路径改为生成路径，不改写源图片；
+ * - `heybox.category`：`tool`、`game` 或 `other`；构建时允许缺省，发布预检要求提供；
  * - `heybox.platforms`：项目实际承诺适配的非空、无重复平台 allowlist；输出按平台词表规范排序。
  *   声明仍停留在旧模板移动端默认（`android`、`ios`、`ohos`）时，`serve` 与 `build` 都只输出
  *   一条非阻断提示，不影响构建结果；